docs: update README for current state

- .env location: cortex/.env + cortex/.env.example (not project root)
- Webhook endpoints: per-user /webhook/nextcloud/{username} and /channels/google-chat/{username}
- Personas table: added brian/wintermute and scott/developer
- Docs table: added GOOGLE_CHAT_BOT.md, cortex/static/HELP.md
- Channels section: per-user webhook note + links to setup docs
- User management: added google-add command and channels.json note
- Removed stale Inara/Tina-only framing

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Scott Idem
2026-03-29 21:42:11 -04:00
parent 2d3a380d6b
commit cec6d3e23a

View File

@@ -6,7 +6,7 @@
> *"You can't stop the signal."*
Cortex is a self-hosted multi-agent AI platform. It supports multiple users, each with their own named AI persona. Inara (Scott's persona) and Tina (Holly's persona) are the initial instances.
Cortex is a self-hosted multi-agent AI platform. It supports multiple users, each with their own named AI persona.
---
@@ -16,9 +16,7 @@ Cortex is a self-hosted multi-agent AI platform. It supports multiple users, eac
|---|---|
| `cortex/` | FastAPI service — dispatcher, routing, LLM backends, session management |
| `home/` | User and persona data (`home/{username}/persona/{name}/`) |
| `home/scott/persona/inara/` | Inara identity, memory, and context files |
| `home/holly/persona/tina/` | Tina identity, memory, and context files |
| `docs/` | Integration reference docs (NC Talk bot, etc.) |
| `docs/` | Integration reference docs (NC Talk bot, Google Chat bot) |
| `documentation/` | Architecture decisions, project plans, agent task lists |
---
@@ -69,7 +67,7 @@ http://localhost:8000 (or cortex.dgrzone.com on WireGuard)
The service starts automatically at boot via `loginctl enable-linger`.
Service file: `~/.config/systemd/user/cortex.service`
Config lives in `cortex/config.py` and a `.env` file at the project root (not tracked — see `.env.default`).
Config lives in `cortex/config.py` and `cortex/.env` (not tracked — see `cortex/.env.example`).
---
@@ -79,10 +77,10 @@ Config lives in `cortex/config.py` and a `.env` file at the project root (not tr
|---|---|
| `documentation/TODO__Agents.md` | Active task list — read first |
| `documentation/ARCH__Intelligence_Layer.md` | Intelligence layer architecture (orchestrator, dev agents, knowledge) |
| `docs/NEXTCLOUD_TALK_BOT.md` | NC Talk bot setup |
| `home/scott/persona/inara/IDENTITY.md` | Inara persona and identity |
| `home/scott/persona/inara/HELP.md` | In-app help content (rendered in UI) |
| `home/scott/persona/inara/PROTOCOLS.md` | Inara behavioral protocols |
| `docs/NEXTCLOUD_TALK_BOT.md` | NC Talk bot setup and troubleshooting |
| `docs/GOOGLE_CHAT_BOT.md` | Google Chat Add-on setup and troubleshooting |
| `cortex/static/HELP.md` | Shared in-app help content (rendered in UI for all users) |
| `home/scott/persona/inara/PROTOCOLS.md` | Inara behavioral protocols (template for all personas) |
| `~/agents_sync/projects/CORTEX.md` | High-level project vision and phases |
---
@@ -93,10 +91,10 @@ Config lives in `cortex/config.py` and a `.env` file at the project root (not tr
[User / Cron / Webhook]
Cortex Dispatcher (FastAPI, cortex/)
├─ POST /chat — direct to LLM (streaming SSE)
├─ POST /orchestrate — Gemini tool loop → Claude response
├─ POST /webhook/nextcloud — Nextcloud Talk bot
└─ POST /webhook/google — Google Chat Add-on
├─ POST /chat — direct to LLM (streaming SSE)
├─ POST /orchestrate — Gemini tool loop → Claude response
├─ POST /webhook/nextcloud/{username} — Nextcloud Talk bot (per-user)
└─ POST /channels/google-chat/{username} — Google Chat Add-on (per-user)
LLM Backend(s)
• Claude CLI — primary reasoning, coding, long-context
@@ -111,7 +109,7 @@ See `documentation/ARCH__Intelligence_Layer.md` for the orchestrator/responder a
---
## Inara / Tina
## Personas
Each persona has its own identity, memory, and session history.
They are not tied to a specific LLM model — the name is fixed, the backend varies.
@@ -120,17 +118,23 @@ Context is loaded at request time from `home/{user}/persona/{name}/` via `cortex
| User | Persona | Description |
|---|---|---|
| scott | inara | Scott's primary AI assistant |
| scott | developer | Scott's dev-focused persona |
| holly | tina | Holly's primary AI assistant |
| brian | wintermute | Brian's primary AI assistant |
---
## Channels
| Channel | Status | Notes |
Webhook endpoints are per-user — each user configures their own secrets in `home/{username}/channels.json`.
| Channel | Status | Endpoint |
|---|---|---|
| Web UI | Live | `https://cortex.dgrzone.com` — session auth (login form + JWT cookie) |
| Nextcloud Talk | Live | HMAC-signed webhook, async reply |
| Google Chat | Live | Workspace Add-on, JWT auth |
| Nextcloud Talk | Live | `POST /webhook/nextcloud/{username}` HMAC-signed, async reply |
| Google Chat | Live | `POST /channels/google-chat/{username}` Workspace Add-on, JWT auth |
See `docs/NEXTCLOUD_TALK_BOT.md` and `docs/GOOGLE_CHAT_BOT.md` for setup instructions.
---
@@ -142,7 +146,10 @@ cd cortex
# Create a user directory and send an invite email
.venv/bin/python manage_passwords.py invite <username> <email>
# List users with password and email status
# Register a Google account for sign-in (run after user completes onboarding)
.venv/bin/python manage_passwords.py google-add <username> <email>
# List users with password, Google, and email status
.venv/bin/python manage_passwords.py list
# Set/check a password directly
@@ -152,6 +159,8 @@ cd cortex
New users receive a link to `/setup/{token}` where they set their own password and create their first persona. Invite tokens expire in 72 hours and are one-time-use.
To enable a channel for a user, create `home/{username}/channels.json` — see the relevant doc in `docs/`.
---
## Testing