docs: comprehensive doc audit — sync all docs to current state

- MASTER.md: tool count 40→47, add proactive notifications + spawn_agent rows, date bump
- ROADMAP.md: mark local orchestrator/web push/proactive notifs/spawn_agent/web_read/session_read as done, date bump
- ARCH__CHANNELS.md: rewrite notification channel config section — all 4 channels, all triggers, on-demand endpoints
- ARCH__SYSTEM.md: update tools/ module list to include files, agents
- README.md: update LLM backends in architecture diagram, add browser push to channels table
- CLAUDE.md: add doc update checklist to Documentation Philosophy section

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -185,6 +185,19 @@ Cortex is a no-black-box system. Docs must match reality — at all times.
 - **CLAUDE.md + ARCH__*.md are the developer contract:** Update them as the architecture evolves.
 - **Stale docs are bugs.** If you notice drift, fix it before moving on.
 
+### Doc update checklist (run after any significant change)
+
+| Doc | Update when |
+|---|---|
+| `CLAUDE.md` | New tool, channel, router, major design change, tool count |
+| `cortex/static/HELP.md` | Any user-visible feature — tools, settings, UI, API endpoints |
+| `documentation/TODO__Agents.md` | Mark completed items; add new planned work |
+| `documentation/MASTER.md` | New capability goes live; tool count changes |
+| `documentation/ROADMAP.md` | Phase items completed or added |
+| `documentation/ARCH__CHANNELS.md` | New channel, notification trigger, or scheduler job |
+| `documentation/ARCH__SYSTEM.md` | New module, router, or tools/ file |
+| `README.md` | Architecture diagram, channels table, or setup steps change |
+
 ---
 
 ## Adding a New Tool

README.md

@@ -184,8 +184,8 @@ Back it up separately — it is required to restore from any snapshot.
   LLM Backends
   • Claude CLI      — primary, all user-facing responses
   • Gemini CLI      — fallback
-  • Gemini API   — orchestrator tool loop only (not general chat)
-  • Local        — Open WebUI/Ollama on scott_gaming (private/offline)
+  • Gemini API      — orchestrator tool loop (two-brain: Gemini plans, Claude responds)
+  • Local OpenAI    — Open WebUI/Ollama on scott_gaming; also runs local orchestrator loop
         ↓
   Persona context loaded from home/{user}/persona/{name}/
 ```
@@ -213,11 +213,12 @@ Context is loaded at request time from `home/{user}/persona/{name}/` via `cortex
 
 Webhook endpoints are per-user — each user configures their own secrets in `home/{username}/channels.json`.
 
-| Channel | Status | Endpoint |
+| Channel | Status | Endpoint / Notes |
 |---|---|---|
 | Web UI | Live | `https://cortex.dgrzone.com` — session auth (login form + JWT cookie) |
 | Nextcloud Talk | Live | `POST /webhook/nextcloud/{username}` — HMAC-signed, async reply |
 | Google Chat | Live | `POST /channels/google-chat/{username}` — Workspace Add-on, JWT auth |
+| Browser Push | Live | VAPID push notifications — subscribe via ☰ menu; proactive reminders + distill alerts |
 
 See `docs/NEXTCLOUD_TALK_BOT.md` and `docs/GOOGLE_CHAT_BOT.md` for setup instructions.
 

documentation/ARCH__CHANNELS.md

@@ -129,16 +129,24 @@ User-defined scheduled jobs stored in `home/{user}/persona/{name}/CRONS.json`. R
 
 ## Notification Channel Config
 
-`notification_channel` in `channels.json` sets the default outbound channel for all proactive messages (distill alerts, cron message/brief jobs):
+`notification_channel` in `channels.json` sets the default outbound channel for all proactive messages (distill alerts, cron jobs, reminder checks):
 
 ```json
 {
-  "notification_channel": "nextcloud",
-  ...
+  "notification_channel": "web_push",
+  "notification_email": "user@example.com",
+  "nextcloud": { "notification_room": "<token>" },
+  "google_chat": { "outbound_webhook": "https://..." }
 }
 ```
 
-If absent, defaults to `nextcloud` if configured. Currently only NC Talk is supported for outbound; Google Chat outbound is a future item.
+Supported channels: `web_push` (browser push via VAPID), `email`, `nextcloud` (NC Talk), `google_chat`. Configured via **Settings → Notifications** (`/settings/notifications`).
+
+**Proactive notification triggers:**
+- **Daily 09:00** — `_run_reminder_check()` in `scheduler.py`: reads due/overdue reminders per persona, fires `notify()` with a formatted summary
+- **Memory distillation** — `_run_mid()` / `_run_long()` call `notify()` on completion
+- **Cron jobs** — `message` / `brief` job types call `notify()` directly
+- **On-demand** — `POST /api/push/test` (test notification) and `POST /api/push/reminders/check` (immediate reminder check)
 
 ---
 

documentation/ARCH__SYSTEM.md

@@ -72,7 +72,7 @@ Details: [`ARCH__BACKENDS.md`](ARCH__BACKENDS.md) | [`ARCH__PERSONA.md`](ARCH__P
 | `email_utils.py` | SMTP invite emails |
 | `persona_template.py` | Bootstrap a new persona directory from templates |
 | `routers/` | One file per endpoint group — `chat`, `orchestrator`, `auth`, `files`, `ui`, `settings`, `local_llm`, `distill`, `audit`, `usage`, `push`, `help`, `onboarding`, `auth_google`, `nextcloud_talk`, `google_chat` |
-| `tools/` | Orchestrator tool implementations — `web`, `tasks`, `scratch`, `reminders`, `cron`, `system`, `notify`, `ae_journals`, `ae_tasks`, `agent_notes` |
+| `tools/` | Orchestrator tool implementations — `web` (search/fetch/web_read), `files` (file_read/write/session_read/search), `tasks`, `scratch`, `reminders`, `cron`, `system`, `notify`, `ae_journals`, `ae_tasks`, `agent_notes`, `agents` (spawn_agent) |
 | `static/` | Web UI — `index.html`, `app.js`, `style.css`, `login.html`, `setup.html`, `HELP.md`, `local_llm.html`, `settings.html` |
 | `tests/` | pytest suite |
 

documentation/MASTER.md

@@ -1,7 +1,7 @@
 # Cortex / Inara — Master Index
 
 > Start here. This document is a map, not a manual.
-> Last updated: 2026-05-06
+> Last updated: 2026-05-09
 >
 > **Documentation philosophy:** Cortex is a no-black-box system. Docs must match reality.
 > Update docs before implementing significant changes. Verify they still match after.
@@ -26,7 +26,7 @@ Cortex is a self-hosted personal AI platform. It routes messages from any input
 | Claude backend | ✅ Live | Primary — via Claude Code CLI |
 | Gemini backend | ✅ Live | Fallback — via Gemini CLI |
 | Local backend | ✅ Live | Open WebUI/Ollama on scott_gaming; per-user multi-model config |
-| Gemini orchestrator | ✅ Live | Tool loop → Claude response, ⚡ toggle in UI (40 tools) |
+| Gemini orchestrator | ✅ Live | Tool loop → Claude response, ⚡ toggle in UI (47 tools) |
 | Local orchestrator | ✅ Live | OpenAI-compatible ReAct loop; used when orchestrator role → local model |
 | Model registry V2 | ✅ Live | Providers (Anthropic/Google/Local), multi-account Gemini, role assignments |
 | Memory distillation | ✅ Live | Short (daily) / Mid (weekly) / Long (monthly) |
@@ -36,6 +36,8 @@ Cortex is a self-hosted personal AI platform. It routes messages from any input
 | Tool audit log | ✅ Live | Every orchestrator tool call logged to `home/{user}/tool_audit/` |
 | Token usage tracking | ✅ Live | Per-user daily buckets in `home/{user}/usage.json`; visible in Settings |
 | Web push notifications | ✅ Live | VAPID push; `web_push` orchestrator tool; subscribe via ☰ menu |
+| Proactive notifications | ✅ Live | Daily reminder check (09:00); distill/cron completion alerts; dedicated `/settings/notifications` page |
+| Sub-agent spawning | ✅ Live | `spawn_agent` tool — synchronous sub-agents via any configured model |
 | Agent private notes | ✅ Live | `AGENT_NOTES.md` — orchestrator-only notepad; 3 rolling backups; user-visible as read-only |
 | Distill safety | ✅ Live | Per-persona asyncio lock, per-endpoint cooldowns, Rebuild option |
 | Guided onboarding | ✅ Live | Setup Step 3 for OpenRouter; existing-user banner; settings quick-link |

documentation/ROADMAP.md

@@ -1,7 +1,7 @@
 # Cortex — Roadmap
 
 > Phases and priorities. For active tasks see `TODO__Agents.md`.
-> Last updated: 2026-04-29
+> Last updated: 2026-05-09
 
 ---
 
@@ -39,7 +39,12 @@
 - ✅ Session search (full-text across past session logs)
 - ✅ Distill notifications (NC Talk after mid/long runs)
 - ✅ Local backend for distillation (DISTILL_BACKEND_MID/LONG in .env)
-- [ ] **Local orchestrator** — ReAct tool loop using local model (High priority — see `TODO__Agents.md`)
+- ✅ Local orchestrator — OpenAI-compatible ReAct loop; fires when orchestrator role → local model
+- ✅ Web push notifications — VAPID; `web_push` tool; PWA-installable; subscribe via ☰ menu
+- ✅ Proactive notifications — daily reminder check (09:00); `notify()` routes to any configured channel; dedicated settings page
+- ✅ Sub-agent spawning — `spawn_agent` tool; per-host concurrency limit; Gemini API + local OpenAI backends
+- ✅ Web content extraction — `web_read` via trafilatura; strips ads/nav/boilerplate; 128K cap
+- ✅ Session log reader — `session_read(date)` tool; complements `session_search`
 - [ ] Knowledge import — markdown → AE Journals (import script)
 - [ ] Dev agent pipeline — specialist agents + supervisor + approval gate
 - [ ] Gitea webhook integration + Actions CI