diff --git a/CLAUDE.md b/CLAUDE.md index 05f30bf..a42f4d3 100644 --- a/CLAUDE.md +++ b/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 diff --git a/README.md b/README.md index e928a7e..7f26fed 100644 --- a/README.md +++ b/README.md @@ -182,10 +182,10 @@ Back it up separately — it is required to restore from any snapshot. └─ POST /channels/google-chat/{username} — Google Chat Add-on (per-user) ↓ 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) + • Claude CLI — primary, all user-facing responses + • Gemini CLI — fallback + • 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. diff --git a/documentation/ARCH__CHANNELS.md b/documentation/ARCH__CHANNELS.md index 9d9588c..962ddd3 100644 --- a/documentation/ARCH__CHANNELS.md +++ b/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": "" }, + "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) --- diff --git a/documentation/ARCH__SYSTEM.md b/documentation/ARCH__SYSTEM.md index 25d6a80..6946023 100644 --- a/documentation/ARCH__SYSTEM.md +++ b/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 | diff --git a/documentation/MASTER.md b/documentation/MASTER.md index 9ce6d0a..c09bed8 100644 --- a/documentation/MASTER.md +++ b/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 | diff --git a/documentation/ROADMAP.md b/documentation/ROADMAP.md index 7bb1786..aed4672 100644 --- a/documentation/ROADMAP.md +++ b/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