docs: refresh published reference docs against current code

- CLAUDE.md + README.md: RAG engine is hybrid retrieval, not HyDE (retired)
- usage.md: org chart + agent-IDs table now show all 22 agents (adds
  secretary-1 + pr-reviewer-1); task-lifecycle diagram adds awaiting_pm_review
  and the awaiting_ceo_approval escalation
- deployment.md: architecture diagram + data-persistence table include ollama,
  panel, nginx, workspaces, and logs
- docs/initiatives + docs/self READMEs: access lists match middleware_docs.py
- CLAUDE.md blueprint pointer no longer references the gitignored docs/internal tree

CLAUDE.md

@@ -74,11 +74,11 @@ pnpm test
 | API Framework | FastAPI |
 | Database | PostgreSQL + asyncpg |
 | Vector Store | PostgreSQL + pgvector (in-house engine) |
-| RAG Engine | in-house (asyncpg + pgvector, HyDE) |
+| RAG Engine | in-house (asyncpg + pgvector, hybrid retrieval) |
 | Cache/Queue | Redis |
 | Container Runtime | Docker + Docker Compose |
 | Cloud LLM | Claude API (claude-opus-4-6) |
-| Local LLM | Ollama (glm-5:cloud for HyDE/RAG) |
+| Local LLM | Ollama (glm-5:cloud for RAG/hybrid retrieval) |
 | Embeddings | qwen3-embedding:0.6b (1024 dim) |
 | Frontend | Next.js 16 + TypeScript + Tailwind + Radix UI (in `panel/`) |
 | Edge / Proxy | nginx (single entry point on port 3000) |
@@ -503,9 +503,4 @@ ROBOCO_OLLAMA_BASE_URL=http://roboco-ollama:11434          # Native API
 
 ## Blueprint Reference
 
-The complete system design is documented in `HOMELAB_TEAM_V0.md`, which contains:
+The organizational structure, communication matrix, role descriptions, and access-control model are documented inline above and in the published `docs/` tree (per-area `README.md` files, `usage.md`, `deployment.md`).
-- Organizational structure and role descriptions
-- Communication matrix and notification permissions
-- API endpoint specifications
-- Security and access control model
-- Configuration templates

README.md

@@ -257,7 +257,7 @@ uv run mypy roboco/
 | Database | PostgreSQL + SQLAlchemy (async) |
 | Vector Store | PostgreSQL + pgvector (in-house engine) |
 | Cache/Queue | Redis |
-| RAG Engine | in-house (asyncpg + pgvector, HyDE) |
+| RAG Engine | in-house (asyncpg + pgvector, hybrid retrieval) |
 | Embeddings | qwen3-embedding:0.6b (Ollama) |
 | Local LLM | Ollama (glm-5:cloud) |
 | Cloud LLM | Claude API (Anthropic) |

deployment.md

@@ -59,21 +59,27 @@ Your NAS/Server
 │   │
 │   ├── roboco-postgres (pgvector)
 │   ├── roboco-redis
-│   └── roboco-orchestrator
+│   ├── roboco-ollama (+ ollama-init: pulls the embedding + local LLM models)
-│       │
+│   ├── roboco-orchestrator
-│       ├── Runs FastAPI on port 8000
+│   │   │
-│       ├── Builds (from source) or pulls (registry) the agent images
+│   │   ├── Runs FastAPI on port 8000
-│       └── Spawns agent containers:
+│   │   ├── Builds (from source) or pulls (registry) the agent images
-│           ├── roboco-agent-main-pm
+│   │   └── Spawns agent containers:
-│           ├── roboco-agent-be-dev-1
+│   │       ├── roboco-agent-main-pm
-│           ├── roboco-agent-be-qa
+│   │       ├── roboco-agent-be-dev-1
-│           └── ... (each mounts ~/.claude for auth)
+│   │       ├── roboco-agent-be-qa
+│   │       └── ... (each mounts ~/.claude for auth)
+│   ├── roboco-panel (Next.js control panel, internal)
+│   └── roboco-nginx (single entry point on :3000 → panel + /api,/ws → orchestrator)
 │
 ├── ~/.claude/              ← Your Claude Code auth (from host)
 │
 └── ./data/                 ← Persistent data
     ├── postgres/
     ├── redis/
+    ├── ollama/             ← model cache (multi-GB)
+    ├── workspaces/         ← per-agent git clones
+    ├── logs/
     └── mcp-configs/
 ```
 
@@ -143,6 +149,9 @@ All data is persisted to the host:
 |----------------|-----------|
 | postgres data | `./data/postgres/` |
 | redis data | `./data/redis/` |
+| Ollama models | `./data/ollama/` |
+| Agent workspaces | `./data/workspaces/` |
+| Agent + orchestrator logs | `./data/logs/` |
 | MCP configs | `./data/mcp-configs/` |
 
 For NAS RAID protection, set `ROBOCO_DATA_DIR` to your RAID volume:

docs/initiatives/README.md

@@ -16,8 +16,8 @@ initiatives/
 
 ## Access
 
-- **READ**: Assigned teams
+- **READ**: Main PM, Cell PMs, Product Owner
-- **WRITE**: Assigned documenters
+- **WRITE**: Main PM
 
 ## Creating an Initiative
 

docs/self/README.md

@@ -10,7 +10,7 @@ Meta-documentation about the RoboCo system itself.
 
 ## Access
 
-- **READ**: Board + PM roles
+- **READ**: Main PM, Cell PMs, Product Owner, Auditor
 - **WRITE**: Main PM, Auditor
 
 ## Purpose

usage.md

@@ -9,9 +9,11 @@ Operating the AI company after deployment.
 ```
 CEO (You)
 ├── Intake (on-demand interviewer: chats only with you to draft a task)
+├── Secretary (your chief-of-staff: runs gated directives under your command)
 └── Board
     ├── Product Owner
     ├── Head of Marketing
+    ├── PR Reviewer (read-only: gates inbound external/fork PRs)
     └── Auditor
         └── Main PM
             ├── Backend Cell (PM, 2 Devs, QA, Documenter)
@@ -40,6 +42,8 @@ CEO (You)
 | `head-marketing` | Head of Marketing | Board |
 | `auditor` | Auditor | Board |
 | `intake-1` | Intake (interviewer) | Board |
+| `secretary-1` | Secretary (chief-of-staff) | Board |
+| `pr-reviewer-1` | PR Reviewer (read-only) | Board |
 
 ## Spawning Agents
 
@@ -122,9 +126,9 @@ Enum values: `task_type` ∈ {`code`, `documentation`, `research`, `planning`, `
 ## Task Lifecycle
 
 ```
-pending → claimed → in_progress → verifying → awaiting_qa → awaiting_documentation → completed
+pending → claimed → in_progress → verifying → awaiting_qa → awaiting_documentation → awaiting_pm_review → completed
-                         ↓
+                         ↓                                                                    ↓
-                    blocked/paused
+                    blocked/paused                                                  awaiting_ceo_approval (major tasks)
 ```
 
 Agents automatically: