From 8de1f1b8bd86d286a6955a123320705c3adc6470 Mon Sep 17 00:00:00 2001
From: Leonard <leonard@hermes.local>
Date: Sat, 20 Jun 2026 16:38:10 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20comprehensive=20root=20README=20?=
 =?UTF-8?q?=E2=80=94=20structure,=20conventions,=20living/cron=20workflows?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 112 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 110 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index af9e953..1713f0c 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,111 @@
-# personal-agent-os
+# 🧠 Personal Agent OS
 
-Personal Knowledge + Projects OS — git-backed external brain for Hermes. Projects, knowledge base, automation patterns, and agent config.
\ No newline at end of file
+A git-backed external brain for Hermes — projects, knowledge, automation patterns, and agent config, all in one compounding repository.
+
+## Why This Exists
+
+Scattered notes don't compound. This repo is:
+
+- **A project hub** — every active project has a home with goals, decisions, and next actions
+- **A knowledge base** — high-signal finds from X, tools, research, and experiments preserved with structured metadata
+- **A context layer** — Hermes reads from it, writes to it, and gets smarter over time
+
+## How It Works
+
+```
+You / Telegram                      Hermes                        Gitea
+       │                              │                              │
+       │─  "Find me everything on     │                              │
+       │   wakeAgent gates" ─────────→│── search_files ─────────────→│
+       │                              │←─ gate designs + notes ─────│
+       │←─ 3 patterns found ─────────│                              │
+       │                              │                              │
+       │─ daily brief fires ─────────→│── fetches data ─────────────→│
+       │                              │── saves to kb/daily-briefs/ ─→│
+       │←─ formatted brief ──────────│                              │
+```
+
+## Directory Layout
+
+```
+personal-agent-os/
+├── _meta/                        # Root-level meta
+│   └── decision-log.md           # Key decisions, rationale, dates
+│
+├── projects/                     # Active projects
+│   ├── hermes-persistent-os/     # The OS project itself
+│   ├── compliance-tracker/       # (create when ready)
+│   ├── local-business-automation/ # (create when ready)
+│   └── ...
+│
+├── knowledge-base/               # Cross-cutting knowledge
+│   ├── automation-blueprints/    # Reusable pattern docs
+│   │   └── hermes/               # Hermes-specific patterns (migrated from hermes-automation/)
+│   ├── ai-agent-patterns/        # General agent design patterns
+│   ├── hermes-integrations/      # Platform-specific setup notes
+│   ├── x-threads/                # Curated X threads and discussions
+│   ├── tool-evaluations/         # 6-part evaluations of tools
+│   ├── local-entrepreneurship/   # Local business patterns (Phoenix, etc.)
+│   └── daily-briefs/             # (auto-populated by cron)
+│
+├── archive/                      # Completed/closed projects
+│
+├── templates/                    # Consistent formats
+│   ├── project-readme-template.md
+│   ├── kb-entry-template.md
+│   └── experiment-log-template.md
+│
+└── agent-config/                 # Hermes runtime reference material
+    └── .gitkeep
+```
+
+## Conventions
+
+### Creating a New Project
+1. Copy `templates/project-readme-template.md` into `projects/<name>/README.md`
+2. Fill in Overview, Status, Goals, Architecture
+3. Create `tasks.md` with Now / Next / Backlog sections
+
+### Adding a Knowledge Entry
+1. Copy `templates/kb-entry-template.md` into the relevant `knowledge-base/` subfolder
+2. Fill the YAML frontmatter (title, date, source, tags, related_projects, status)
+3. Write Summary, Key Insights, Mechanics, Actionable Ideas, Open Questions
+
+### Naming
+- Lowercase with hyphens for directories and files
+- Dates in `YYYY-MM-DD` format
+- Tags as comma-separated, lowercase
+
+## How This Stays Alive (Living/Cron Workflows)
+
+This repo is designed to be written to by Hermes cron jobs.
+
+| Cron Job | What It Writes | Frequency | Status |
+|----------|---------------|-----------|--------|
+| daily-brief | Delivers to Telegram. Will also save to `knowledge-base/daily-briefs/` | Daily at 15:00 UTC | ✅ Live |
+| weekly tag index | Scans all KB entries, rebuilds `_meta/tag-index.md` | Weekly (Sun) | 🔲 Planned |
+| opportunity scan | Saves entries to `knowledge-base/x-threads/` | Daily | ⏸️ Paused |
+| email triage | Summary to Telegram + entry to `knowledge-base/hermes-integrations/` | Every 15m | 🔲 Planned |
+
+### Writing Rules for Cron Jobs
+- Always use the `kb-entry-template.md` format when saving to `knowledge-base/`
+- Tag entries with the originating cron job name + relevant project
+- Use `write_file` to append or create; never overwrite another entry
+- Silent delivery on no-change ticks (masterclass pattern)
+
+## Agent Hooks
+
+Hermes reads from this repo for context:
+
+- `projects/<name>/README.md` — project status and goals
+- `projects/<name>/tasks.md` — next actions
+- `knowledge-base/**/*.md` — structured knowledge retrieval via search_files
+- `_meta/decision-log.md` — why things were done a certain way
+- `agent-config/` — reference configs and setup snippets
+
+## Getting Started
+
+1. Browse `projects/hermes-persistent-os/` for the current automation roadmap
+2. Read `knowledge-base/automation-blueprints/hermes/` for running patterns
+3. Use `templates/` when adding new content
+4. Check `_meta/decision-log.md` for architectural reasoning
\ No newline at end of file