constella 0.1.0

package/docs/en/ARCHITECTURE.md

@@ -0,0 +1,334 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/ARCHITECTURE.md) · [✦ Constella](../../README.md)
+
+# 🌌 Architecture — the central ship
+
+Constella is a local-first control plane: a single Node process supervises a **web server** and a **24/7 worker**, both orbiting one runtime root on disk where every organization keeps an isolated workspace. The directory is the source of truth; SQLite is the index that lets the UI and search agree.
+
+> ✦ This document maps the *structural* layer: process topology, runtime root + org isolation, the filesystem jail, the SQLite/Drizzle store, the sync engine + file-watcher, and the cron tick that drives autonomous work. For the *cognitive* layer (how agents think, RAG, KB) see [AI_ARCHITECTURE](./AI_ARCHITECTURE.md).
+
+---
+
+## 🛰️ When to use this doc
+
+- You need to understand **how Constella boots** and which process does what.
+- You are debugging **why a file edit did not appear** in the UI (sync engine).
+- You are reasoning about **multi-tenant isolation** (one runtime root, many orgs).
+- You are hardening or auditing the **worker ↔ web** trust boundary.
+- You want the **table-level map** of the database (`src/db/schema.ts`).
+
+---
+
+## 🚀 How it works (high level)
+
+A single launcher — `bin/constella.mjs` — resolves the run mode, prepares the runtime root and secrets, applies the database migrations, then **supervises two long-lived children**:
+
+| Child | Entry | Role |
+| --- | --- | --- |
+| **web** | `next start -H <host> -p <port>` (from `PKG_ROOT`) | The Next.js 16 app: UI, server actions, all `/api` routes, agent orchestration. |
+| **worker** | `bin/worker.mjs` | Headless 24/7 driver: cron tick, the chokidar file-watcher, the Telegram long-poll. Talks to the web over loopback HTTP. |
+
+The worker never touches the database directly. It only makes authenticated HTTP calls back into the web server (`x-worker-secret`), so all writes funnel through one process and one set of server actions. This keeps the trust boundary small and the DB single-writer.
+
+```mermaid
+flowchart TB
+  subgraph Launcher["bin/constella.mjs (supervisor)"]
+    SUP["supervise(): restart on crash<br/>max 5 / 60s"]
+  end
+
+  SUP -->|spawn| WEB["web<br/>next start @ host:port<br/>cwd = PKG_ROOT"]
+  SUP -->|spawn| WK["worker<br/>bin/worker.mjs"]
+
+  WK -->|"POST /api/cron/tick<br/>(x-worker-secret)"| WEB
+  WK -->|"POST /api/sync/file<br/>(x-worker-secret)"| WEB
+  WK -->|"POST /api/telegram/poll"| WEB
+  WK -->|"chokidar watch"| DISK[("Runtime root<br/>~/.constella")]
+
+  WEB -->|drizzle / better-sqlite3| DB[("constella.db<br/>WAL")]
+  WEB -->|"fs-workspace safe()"| DISK
+  WEB -->|spawn claude / codex| CLI["agent CLIs<br/>cwd = org workspace (FS jail)"]
+  CLI -->|edit files| DISK
+
+  classDef store fill:#1a1a2e,stroke:#e0a44e,color:#fff
+  class DB,DISK store
+```
+
+---
+
+## 🌠 Main flow — boot to steady state
+
+The launcher's boot sequence (`bin/constella.mjs`), in order:
+
+1. **Resolve run mode** — explicit flag (`--start|--auth|--vps|--portable`) wins, then legacy `--bind`, default `start`. See [START_MODE](./START_MODE.md), [AUTH_MODE](./AUTH_MODE.md), [VPS_MODE](./VPS_MODE.md), [PORTABLE_MODE](./PORTABLE_MODE.md).
+2. **Resolve the runtime root** — `CONSTELLA_HOME` / `--path` wins; otherwise `~/.constella`. Portable mode with no path enumerates removable USB drives and prompts. `mkdir -p <HOME>/organizations`.
+3. **Pin paths** — `DATABASE_URL=file:<HOME>/constella.db`, `CONSTELLA_PKG_ROOT=<install dir>`. `PKG_ROOT` is where the prebuilt `.next`, `drizzle/` migrations and configs live (not the launch dir).
+4. **Persist secrets** — read/generate `BETTER_AUTH_SECRET`, `CONSTELLA_VAULT_KEY`, `CONSTELLA_WORKER_SECRET` and write them to `<HOME>/.env` with mode `0o600`. Generated once; reused across restarts so sessions + the encrypted vault survive.
+5. **Portable disk check** — refuse `< 32 GB` free (fatal); `≥ 32 GB` is fine.
+6. **Apply migrations** — `drizzle-kit migrate --config drizzle.config.mjs` from `PKG_ROOT`. Idempotent. A *fresh* DB that fails to migrate aborts the boot (no tables → every request 500s).
+7. **Build-on-first-run (fallback only)** — the published package ships a prebuilt `.next`, so this is skipped. From a source tree without a build it runs `next build`; it refuses to silently fall back to `next dev` in a public run unless `CONSTELLA_DEV=1`.
+8. **Supervise web + worker** — spawn the web server, then ~1.5 s later the worker (so Next has a head start). Each child is wrapped in `supervise()`; on an unexpected exit it auto-restarts (bounded: `MAX_RESTARTS = 5` within `WINDOW_MS = 60_000`), else the supervisor gives up and exits.
+
+Once steady, the **worker** waits for the server to answer (`waitForServer`, up to ~90 s), then:
+
+- Fires the **cron tick** immediately and every `INTERVAL` (`CONSTELLA_WORKER_INTERVAL_MS`, default `60_000` ms).
+- Starts the **chokidar watcher** over `<HOME>/organizations`.
+- Runs the **Telegram long-poll** loop (`getUpdates` waits ~25 s server-side; gap ~1 s between polls).
+
+---
+
+## 🪐 Key concepts
+
+### Runtime root + per-org isolation
+
+```
+~/.constella/                         ← runtime root (CONSTELLA_HOME or --path)
+├─ .env                               ← persisted secrets (mode 0600)
+├─ constella.db                       ← SQLite (WAL) — the index
+├─ cache/                             ← models.dev cache, etc.
+├─ backups/                           ← .env + db backups on update
+└─ organizations/
+   └─ <orgId>/
+      └─ workspace/                   ← the org's isolated, sandboxed tree
+         ├─ .claude/                  ← agents/, skills/, BRIEF.md (config INSIDE the workspace)
+         ├─ DOCS/  PO/  Reports/
+         ├─ specs/ issues/ mock/
+         ├─ uploads/                  ← operator attachments, Telegram media
+         └─ <the product the agents build>
+```
+
+The workspace directory is keyed by the **stable `organization.id`** (never the renameable slug). A one-time boot migration renames a legacy `constella/` dir to `workspace/` so existing orgs keep their data (falling back to a copy on a cross-device move, never deleting the legacy dir).
+
+### The filesystem jail — `safe()`
+
+Every workspace read/write goes through `safe(root, rel)` in `src/lib/fs-workspace.ts`. It is the single chokepoint that keeps a prompt-injected agent (or a buggy path) inside its own org:
+
+1. **Lexical check** — `normalize(join(root, rel))` must equal `root` or start with `root + sep`. Because `join` re-roots absolute, drive-letter and UNC paths under `root`, this blocks `../`, absolute escapes and Windows drive tricks.
+2. **Symlink check** — it resolves the real path of the nearest existing ancestor (`realAncestor`) and re-verifies it is still under the real `root`. This defeats a symlink *planted inside* the workspace that would otherwise tunnel out to another org or the wider filesystem.
+
+`orgRoot()` additionally validates the org id (`/^[A-Za-z0-9_-]{6,64}$/`) before it ever touches a path, so a malformed id can't traverse. Heavy build/dependency dirs (`node_modules`, `.git`, `.next`, `dist`, `.testdev`, …) are skipped by `listFiles()` via `HEAVY_DIRS`.
+
+### Directory is truth, DB is the index
+
+The filesystem is canonical; the database **mirrors** it. Indexers in `src/server/sync.ts` are idempotent upserts and **disk always wins on conflict**. The same file written by an agent and later re-indexed by the watcher updates *one* row (keyed by H1 title or relative path), never duplicates.
+
+### SQLite + Drizzle
+
+`src/db/index.ts` opens `better-sqlite3` against the resolved `DATABASE_URL`, sets `journal_mode = WAL` and `foreign_keys = ON`, and wraps it with `drizzle-orm`. It also exports the raw `sqlite` handle for **migration-free boot DDL** (`CREATE TABLE IF NOT EXISTS` + guarded `ALTER ADD COLUMN`) — used to add tables/columns to existing DBs *without* `drizzle-kit push`, which would drift this project's migration history. See [SECURITY](./SECURITY.md) and [TROUBLESHOOTING](./TROUBLESHOOTING.md) for the `db:push` caveat.
+
+### Worker ↔ web trust boundary
+
+The worker holds the privileged `CONSTELLA_WORKER_SECRET` and attaches it as `x-worker-secret` to every call. Two protections matter:
+
+- **Fail closed on the server**: `/api/cron/tick` and `/api/sync/file` return `401` unless the header equals the configured secret. An unset secret does **not** leave them open — they reject everyone.
+- **SSRF / exfil guard on the worker**: the worker refuses to send the secret to a non-loopback host. The launcher always sets `CONSTELLA_BASE_URL=http://127.0.0.1:<port>` (loopback even when the web binds `0.0.0.0` for vps/portable). A genuine remote worker must opt in with `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1`, and over plain `http://` it warns that the secret travels in cleartext.
+
+---
+
+## 🗃️ Tables
+
+### Process / runtime environment
+
+| Env var | Set by | Meaning |
+| --- | --- | --- |
+| `CONSTELLA_HOME` | launcher (`--path` / default `~/.constella`) | Runtime root. Relative values are anchored to the launch dir (`INIT_CWD`). |
+| `DATABASE_URL` | launcher | `file:<HOME>/constella.db` (absolute, so app + `drizzle-kit migrate` open the same DB). |
+| `CONSTELLA_PKG_ROOT` | launcher | Installed package root (prebuilt `.next`, `drizzle/`, bundled `skills/`). |
+| `CONSTELLA_RUN_MODE` | launcher | `start \| auth \| vps \| portable`. |
+| `CONSTELLA_PUBLIC` | launcher (`=1`) | A CLI launch is the public runtime → the UI mode-picker is hidden. |
+| `CONSTELLA_VERSION` | launcher | Installed version, for the in-app Update check. |
+| `BETTER_AUTH_SECRET` | `<HOME>/.env` | Session signing key (real, never the public default). |
+| `CONSTELLA_VAULT_KEY` | `<HOME>/.env` | AES-256-GCM key for the `vault` table. |
+| `CONSTELLA_WORKER_SECRET` | `<HOME>/.env` | Shared secret for worker → web auth (`x-worker-secret`). |
+| `CONSTELLA_BASE_URL` | launcher → worker | `http://127.0.0.1:<port>` — loopback target for worker calls. |
+| `CONSTELLA_WORKER_INTERVAL_MS` | optional | Cron tick interval (default `60_000`). |
+| `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL` | optional (`=1`) | Allow the worker to call a non-loopback host. |
+| `CONSTELLA_WEB_HEAP_MB` | optional | `--max-old-space-size` for the web child. |
+| `CONSTELLA_DEV` | optional (`=1`) | Permit a `next dev` fallback from a source tree without a build. |
+
+### Core tenancy + structural tables (`src/db/schema.ts`)
+
+| Table | Key columns | Purpose |
+| --- | --- | --- |
+| `organization` | `id`, `ownerId`, `runMode` (`start\|auth\|vps\|portable`), `archived` | Tenant. `runMode` is the persisted mode. |
+| `member` | `orgId`, `userId`, `role` (`owner\|admin\|member`) | Org membership + roles. |
+| `workspace` | `id`, `orgId`, `slug` (unique), `stack` (JSON), `runMode`, `bootstrap`, `settings` (JSON) | One workspace per org; `settings` holds Telegram/GitHub/source/agents config. |
+| `agent` | `handle`, `role`, `adapter`, `model`, `status`, `health`, `reportsTo`, `dailyCapUsd` | The 10-agent constellation. |
+| `skill` / `agentSkill` | `name`, `native`, `indexed`; join `auto` | Markdown procedures + per-agent enablement. |
+| `goal` / `spec` / `issue` / `task` / `plan` | lifecycle `status`/`col`, `approved`, `auto247` | The work pipeline ([GOALS_SPECS_ISSUES](./GOALS_SPECS_ISSUES.md)). |
+| `message` / `chatSession` / `event` / `decision` | `channel`, `runId`, `seq` | Team Room, DM sessions, live run events, decision log. |
+| `ragChunk` / `kbEntry` / `syncedBlock` / `docIndex` | embeddings + KB layer | Memory nebula ([KB_RAG](./KB_RAG.md), [MEMORY_RAG](./MEMORY_RAG.md)). |
+| `file` | `path`, `gitStatus` (`""\|M\|A\|U\|D`) | Editor mirror + git porcelain status. |
+| `vault` | `ref`, `ciphertext`, `iv` | AES-GCM secrets keyed by provider. |
+| `fileLock` | `workspaceId+path` (PK), `taskId`, `heartbeatAt` | Per-file lock so parallel agents never edit the same file ([SECURITY](./SECURITY.md)). |
+
+> The schema defines ~60 tables. The list above covers the ones load-bearing for *architecture*; the work, KB and model tables are documented in their own pages.
+
+### Sync engine — indexed prefixes
+
+`bin/worker.mjs` only forwards files matching the `INDEXED` regex; `src/server/sync.ts` then routes each path to a per-type indexer:
+
+| Path pattern | Indexer | DB target |
+| --- | --- | --- |
+| `.claude/skills/<name>.md` | `indexSkillFile` | `skill` |
+| `.claude/agents/<handle>/(Agent\|skills).md` | `indexAgentFile` | `agent` (+ `agentSkill`) |
+| `Reports/**.md` | `indexReportFile` | `report` |
+| `DOCS/**.md` | `indexDocFile` (kind `docs`) | `docIndex` |
+| `PO/**.md` | `indexDocFile` (kind `po`) | `docIndex` |
+
+Any change to a RAG file also schedules a debounced incremental re-embed via `scheduleRagReindex`; a delete drops its chunks via `deindexRagFile`.
+
+---
+
+## 🌌 Mermaid — the sync engine (disk → DB)
+
+```mermaid
+sequenceDiagram
+    participant FS as Workspace files
+    participant W as worker (chokidar)
+    participant API as POST /api/sync/file
+    participant SYNC as src/server/sync.ts
+    participant DB as SQLite
+
+    FS->>W: add / change / unlink
+    Note over W: parse() → {orgId, rel}<br/>INDEXED regex gate<br/>debounce 400ms per key
+    W->>API: POST {orgId, rel, event}<br/>x-worker-secret
+    API->>API: 401 unless secret matches
+    alt event = unlink
+        API->>SYNC: deindexFile(orgId, rel)
+        SYNC->>DB: delete row + drop RAG chunks
+    else add / change
+        API->>SYNC: indexFile(orgId, rel)
+        SYNC->>SYNC: scheduleRagReindex(orgId, rel)
+        SYNC->>DB: upsert (disk wins) + revalidatePath
+    end
+```
+
+---
+
+## 🛰️ Mermaid — the prompt flow (tick → agent → disk → index)
+
+This is the full loop that turns an autonomous tick into real work on disk, then back into the UI.
+
+```mermaid
+flowchart LR
+  T["worker tick<br/>every 60s"] -->|"POST /api/cron/tick"| API["/api/cron/tick<br/>(401 unless x-worker-secret)"]
+  API --> RUN["tickAll({ execute:true, auto:true })"]
+  RUN -->|"per active workspace"| TW["tickWorkspace()"]
+  TW --> SPAWN["spawn claude / codex<br/>--output-format json<br/>cwd = org workspace"]
+  SPAWN -->|"FS jail safe()"| EDIT["agent edits files"]
+  EDIT --> DISK[("workspace/ on disk")]
+  DISK -->|"chokidar"| WATCH["worker watcher"]
+  WATCH -->|"POST /api/sync/file"| SYNC["indexFile()"]
+  SYNC --> DB[("SQLite index")]
+  DB -->|"revalidatePath"| UI["Next.js UI updates"]
+  EDIT -.->|"event rows (runId, seq)"| DB
+
+  classDef store fill:#1a1a2e,stroke:#e0a44e,color:#fff
+  class DISK,DB store
+```
+
+The agent run itself (model, permission mode, web research, timeouts) is detailed in [AGENTS](./AGENTS.md) and [AI_ARCHITECTURE](./AI_ARCHITECTURE.md). Architecturally, the key point is the **closed loop**: tick → spawn (jailed CLI) → disk → watcher → sync → DB → UI.
+
+---
+
+## 🚀 Step-by-step — trace a single edit end-to-end
+
+1. The cron tick (or a DM) advances a workspace; the runner spawns a CLI agent with `cwd` = the org workspace (the FS jail).
+2. The agent writes a file (e.g. `Reports/sprint-3.md`). All writes from server code go through `writeWorkspaceFile` → `safe()`; the CLI itself is confined by `cwd` + the guard/lock hooks.
+3. chokidar (`awaitWriteFinish`, 300 ms stability) fires `add`/`change`.
+4. `parse(abs)` derives `{orgId, rel}` from `<orgId>/workspace/<rel>` and tests the `INDEXED` regex. Non-indexed files are ignored.
+5. A 400 ms per-key debounce coalesces rapid saves, then `POST /api/sync/file` with `x-worker-secret`.
+6. The route authenticates and calls `indexFile(orgId, rel)` → `indexReportFile` → upsert into `report`, plus `scheduleRagReindex`.
+7. `revalidatePath("/reports")` (and `/code`) refresh the UI on next navigation.
+
+---
+
+## 🌠 Examples
+
+**Boot from npm (start mode):**
+```bash
+npx constella                 # default = start mode, 127.0.0.1:3000
+# Constella runtime root : C:\Users\you\.constella
+# Mode                   : start  ·  127.0.0.1:3000
+# • Starting: next start -H 127.0.0.1 -p 3000  +  worker
+# watching C:\Users\you\.constella\organizations
+```
+
+**Point the runtime root at a project folder (dev):**
+```bash
+CONSTELLA_HOME=./.constella npx constella --auth --port 4000
+```
+
+**Run web + worker together in development (no global install):**
+```bash
+pnpm dev:all       # scripts/dev-all.mjs → next dev + worker (Telegram poll works in dev)
+pnpm start         # scripts/start-all.mjs → next start + worker (prod build)
+```
+
+**Inspect the index directly:**
+```bash
+sqlite3 ~/.constella/constella.db ".tables"
+sqlite3 ~/.constella/constella.db "SELECT handle,status,health FROM agent;"
+```
+
+---
+
+## 🕳️ Possible states
+
+| Surface | States |
+| --- | --- |
+| Supervised child | running · auto-restarting (`n/5 within 60s`) · gave up (supervisor exits) |
+| `organization.runMode` | `start` · `auth` · `vps` · `portable` |
+| `workspace.runMode` | `off` · `start` · `auth` · `vps` · `portable` (`off` is excluded from `tickAll`) |
+| `workspace.bootstrap` | `pending` · `template-only` · `enriching` · `done` |
+| `agent.status` | `idle` · `working` · `review` · `blocked` |
+| `agent.health` | `alive` · `stale` · `down` |
+| `file.gitStatus` | `""` · `M` · `A` · `U` · `D` |
+| Worker base URL guard | loopback (allowed) · non-loopback + `ALLOW_REMOTE` · refused (exit 1) |
+
+---
+
+## 🛰️ Related integrations
+
+- **Worker endpoints**: `/api/cron/tick`, `/api/sync/file`, `/api/telegram/poll` — all behind `x-worker-secret`.
+- **Telegram** long-poll runs inside the worker → [TELEGRAM](./TELEGRAM.md).
+- **GitHub** git status flows into `file.gitStatus` → [GITHUB](./GITHUB.md).
+- **RAG/KB** re-embedding is triggered by the sync engine → [KB_RAG](./KB_RAG.md), [MEMORY_RAG](./MEMORY_RAG.md).
+- **Public API / MCP** are separate inbound surfaces (not worker-secret) → [PUBLIC_API](./PUBLIC_API.md), [MCP](./MCP.md).
+
+---
+
+## 🕳️ Security
+
+- **FS jail** `safe()` — lexical + symlink checks; the workspace root is never deletable through it. Org id is validated before any path is built.
+- **Worker secret fails closed** — `/api/cron/tick` and `/api/sync/file` reject every request when no secret is configured (an unset secret is *not* an open door).
+- **SSRF guard** — the worker only sends its secret to loopback unless explicitly overridden; cleartext remote use is warned.
+- **Vault** — secrets live only in the `vault` table (AES-256-GCM via `CONSTELLA_VAULT_KEY`), never on provider rows; `.env` is written `0o600`.
+- **Single writer** — the worker has no DB handle; all writes go through the web process, so there is one authority for consistency.
+- Full detail in [SECURITY](./SECURITY.md).
+
+---
+
+## 🌌 Troubleshooting
+
+| Symptom | Likely cause | Where to look |
+| --- | --- | --- |
+| File edited but UI stale | watcher not running, or path not in `INDEXED` | worker logs (`watching …`); `bin/worker.mjs` `INDEXED` regex |
+| `401 unauthorized` on tick/sync | `CONSTELLA_WORKER_SECRET` mismatch between web + worker | `<HOME>/.env`; both children inherit it from the launcher |
+| Worker exits at start | `CONSTELLA_BASE_URL` is non-loopback without override | set loopback or `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` |
+| Two separate databases appear | standalone server chdir without `INIT_CWD` | use `pnpm start` / the CLI (they set `INIT_CWD`); see `src/lib/runtime-root.ts` warning |
+| Fresh DB has no tables | `drizzle-kit migrate` failed on first boot | reinstall the package; check `drizzle/` ships; boot aborts on a fresh-DB migrate failure by design |
+| Crash-loop "giving up" | a child crashed 5× in 60s | check the OOM hint; raise `CONSTELLA_WEB_HEAP_MB` if it's a JS-heap OOM |
+
+More in [TROUBLESHOOTING](./TROUBLESHOOTING.md) and [FAQ](./FAQ.md).
+
+---
+
+## ✦ Related links
+
+- [AI_ARCHITECTURE](./AI_ARCHITECTURE.md) — the cognitive layer (agents, RAG, context).
+- [AGENTS](./AGENTS.md) — the 10-agent constellation and how runs are spawned.
+- [CONFIGURATION](./CONFIGURATION.md) — env vars and settings in depth.
+- [INSTALLATION](./INSTALLATION.md) · [START_MODE](./START_MODE.md) · [AUTH_MODE](./AUTH_MODE.md) · [VPS_MODE](./VPS_MODE.md) · [PORTABLE_MODE](./PORTABLE_MODE.md)
+- [KB_RAG](./KB_RAG.md) · [MEMORY_RAG](./MEMORY_RAG.md) · [SYNCED_BLOCKS](./SYNCED_BLOCKS.md)
+- [SECURITY](./SECURITY.md) · [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [FAQ](./FAQ.md)
+- [TELEGRAM](./TELEGRAM.md) · [GITHUB](./GITHUB.md) · [PUBLIC_API](./PUBLIC_API.md) · [MCP](./MCP.md)

package/docs/en/AUTH_MODE.md

@@ -0,0 +1,247 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/AUTH_MODE.md) · [✦ Constella](../../README.md)
+
+# Auth Mode 🛰️
+
+![](../assets/divider-orbit.svg)
+
+> Real email + password gating in front of the central ship — for when more than one human shares the same machine, but you still want a private, loopback-only control plane.
+
+Auth mode is the run mode where every session must pass a credential gate. Unlike `start` mode (which auto-creates and auto-signs-in a local operator), `auth` mode shows the real login screen, signs sessions with a mandatory `BETTER_AUTH_SECRET`, and supports TOTP 2FA and WebAuthn passkeys. It still binds to `127.0.0.1`, so the surface is the same local-only orbit as `start` — only the front door is locked.
+
+---
+
+## ✦ When to use
+
+Use `auth` mode when:
+
+- A **shared workstation** hosts Constella and you do not want anyone with physical access to land straight in the app.
+- You want a **real account** (email + password, optional 2FA / passkey) instead of the auto-provisioned `operator@constella.dev` account.
+- You want session signing with a **persisted secret**, but you still want to keep the listener on loopback (no network exposure).
+
+Reach for a different mode when:
+
+| You want… | Use |
+|---|---|
+| Zero-friction local, single user, no login | [START_MODE](./START_MODE.md) |
+| Remote access over a private tailnet, in Docker | [VPS_MODE](./VPS_MODE.md) |
+| The whole runtime carried on a USB drive | [PORTABLE_MODE](./PORTABLE_MODE.md) |
+
+---
+
+## 🌌 How it works
+
+`auth` is one of four `RunMode` values defined in `src/lib/run-mode.ts`:
+
+```ts
+export type RunMode = "start" | "auth" | "vps" | "portable";
+
+export const RUN_MODES: Record<RunMode, { label: string; requiresLogin: boolean; note: string }> = {
+  start:    { label: "Start",    requiresLogin: false, note: "Local auto-created account · always signed in." },
+  auth:     { label: "Auth",     requiresLogin: true,  note: "Email + password required each session." },
+  vps:      { label: "VPS",      requiresLogin: true,  note: "Access over your Tailscale tailnet; runs in Docker." },
+  portable: { label: "Portable", requiresLogin: true,  note: "USB drive mounted as root across machines." },
+};
+```
+
+The mode is selected by the launch flag in `bin/constella.mjs` and exported into the environment as `CONSTELLA_RUN_MODE`. The server reads it back with `getRunMode()`; `requiresLogin()` returns `true` for `auth`.
+
+Three pillars define the mode:
+
+1. **`requiresLogin: true`** — `requireWorkspace()` (in `src/lib/workspace.ts`) sends an unauthenticated request to `/login`, not to `/api/dev-login`. There is no auto sign-in.
+2. **Mandatory `BETTER_AUTH_SECRET`** — every network-capable mode (`auth`, `vps`, `portable`) must boot with a real signing secret or it refuses to serve (see [Security](#-security)).
+3. **`127.0.0.1` bind** — `auth` keeps the same loopback host as `start`; only `vps` and `portable` bind `0.0.0.0`.
+
+### The login surface (`better-auth`)
+
+`src/lib/auth.ts` configures `better-auth` with:
+
+- **Email + password** always enabled (`emailAndPassword: { enabled: true, autoSignIn: true, requireEmailVerification: false }`).
+- **TOTP 2FA** via the `twoFactor()` plugin (Profile → Security).
+- **WebAuthn passkeys** via custom `/api/passkey/*` routes built on `@simplewebauthn` (the login form offers a passkey button).
+- **Social providers** (GitHub / Google) only when their env credentials are present — used for account linking, not as the primary auth path.
+- **30-day sessions** (`expiresIn: 60 * 60 * 24 * 30`).
+- **Secure cookies** whenever the base URL is `https://` (`useSecureCookies: BASE_URL.startsWith("https://")`). In plain `auth` over local http, cookies stay relaxed; behind an https reverse proxy they become `Secure`.
+
+---
+
+## 🚀 Main flow
+
+```mermaid
+flowchart TD
+  A["constella --auth"] --> B["bin/constella.mjs<br/>CONSTELLA_RUN_MODE=auth<br/>host = 127.0.0.1"]
+  B --> C["ensureSecret() persists<br/>BETTER_AUTH_SECRET to ~/.constella/.env"]
+  C --> D["boot.ts → assertAuthSecret()"]
+  D -->|secret present| E["server serves"]
+  D -->|secret missing| X["process.exit(1)"]
+  E --> F["browser hits any (app) page"]
+  F --> G["requireWorkspace()"]
+  G -->|no session| H["redirect /login"]
+  H --> I["LoginForm: email + password"]
+  I -->|2FA enabled| J["TOTP code → verifyTotp"]
+  I -->|passkey| K["/api/passkey/authenticate"]
+  J --> L["session cookie set · redirect /"]
+  K --> L
+  I -->|password ok, no 2FA| L
+  G -->|session ok| M["scoped workspace returned"]
+```
+
+---
+
+## 🪐 Key concepts
+
+| Concept | Where | Meaning |
+|---|---|---|
+| `RunMode` | `src/lib/run-mode.ts` | `"auth"` is one of four modes; drives login + bind behaviour. |
+| `requiresLogin()` | `src/lib/run-mode.ts` | Returns `true` for `auth` — the app demands a credential. |
+| `assertAuthSecret()` | `src/lib/auth.ts` | Hard boot gate: refuses to run a network mode without `BETTER_AUTH_SECRET`. |
+| `requireWorkspace()` | `src/lib/workspace.ts` | Per-page guard; redirects unauthenticated `auth`-mode requests to `/login`. |
+| `LoginForm` | `src/app/(auth)/login/login-form.tsx` | Email/password + 2FA + passkey UI. |
+| `auth` (better-auth) | `src/lib/auth.ts` | The configured auth server (email/pw, 2FA, social, sessions). |
+| `createSessionCookie()` | `src/server/passkey-login.ts` | Mints a real better-auth session after a passkey assertion. |
+| `member.role` | `src/db/schema.ts` | `owner` \| `admin` \| `member` — org membership roles. |
+
+### `auth` vs `start` — the contrast
+
+`start` and `auth` share the same loopback host and the same dual-process runtime; they differ entirely at the **front door**.
+
+| Dimension | `start` | `auth` |
+|---|---|---|
+| `requiresLogin` | `false` | `true` |
+| Login screen | skipped | shown (`/login`) |
+| Account | auto-provisioned `operator@constella.dev` / `operator123` | a real account you create/sign into |
+| Auto sign-in | yes — `/api/dev-login` | no |
+| `BETTER_AUTH_SECRET` | persisted but not strictly required by `assertAuthSecret()` | **mandatory** (boot refuses without it) |
+| Bind host | `127.0.0.1` | `127.0.0.1` |
+| 2FA / passkeys | available but pointless (auto-login) | the point of the mode |
+| Shared machine safe? | no (anyone with the box is in) | yes (credential gate) |
+| `ensureLocalOperator()` | called | throws — "start-mode only" |
+
+The predictable `operator/operator123` credential is provisioned **only** in `start` mode. `ensureLocalOperator()` (in `src/server/dev-auth.ts`) explicitly throws if `getRunMode() !== "start"`, so a network mode can never carry a default remote login.
+
+---
+
+## 🌠 Step-by-step
+
+### 1. Launch in auth mode
+
+```bash
+npx constella --auth
+```
+
+`bin/constella.mjs` sets `CONSTELLA_RUN_MODE=auth`, picks `host = 127.0.0.1` (only `vps`/`portable` use `0.0.0.0`), and `port` defaults to `3000` (override with `--port`).
+
+### 2. Secrets are persisted
+
+On every launch, `bin/constella.mjs` ensures three secrets exist under the runtime root and writes them (mode `0o600`) to `~/.constella/.env`:
+
+| Secret | Purpose |
+|---|---|
+| `BETTER_AUTH_SECRET` | Signs session cookies (mandatory in `auth`). |
+| `CONSTELLA_VAULT_KEY` | AES-256-GCM key for the provider-secret vault. |
+| `CONSTELLA_WORKER_SECRET` | Shared secret the worker presents to the web (`x-worker-secret`). |
+
+`ensureSecret()` reuses an existing persisted value, prefers an env override, and otherwise generates one once. Persisting (not regenerating) means your login sessions and the encrypted vault survive a restart.
+
+### 3. Boot gate fires
+
+At first request, `reconcileOnBoot()` (in `src/server/boot.ts`) calls `assertAuthSecret()` **before anything else**. In `auth` without a real secret, the process logs `[boot] FATAL:` and calls `process.exit(1)` — the server never serves a forgeable cookie.
+
+### 4. Sign in
+
+The browser hits any `(app)` page → `requireWorkspace()` finds no session → redirects to `/login`. The `LoginForm`:
+
+- Pre-fills `operator@constella.dev` but accepts any email.
+- Calls `signIn.email({ email, password })`. If the email is unknown it falls back to `signUp.email(...)` (create-on-first-login).
+- The submit button is disabled until the password is at least 8 characters.
+
+### 5. Optional second factor
+
+- **TOTP 2FA:** if enabled, `signIn.email` returns `twoFactorRedirect`; the form switches to a 6-digit code field and calls `authClient.twoFactor.verifyTotp({ code })`.
+- **Passkey:** the "passkey" button posts to `/api/passkey/authenticate/options`, runs `startAuthentication(...)` in the browser, then posts the assertion to `/api/passkey/authenticate/verify`. On success the server mints a real session cookie via `createSessionCookie()`.
+
+### 6. Manage second factors (Profile → Security)
+
+- **Enable 2FA:** `authClient.twoFactor.enable({ password })` → scan the TOTP URI → `verifyTotp({ code })`. Disable with `authClient.twoFactor.disable({ password })`.
+- **Passkeys:** registered via the `/api/passkey/register/*` routes; managed (rename / remove) by `removePasskey` / rename actions in `src/server/actions/profile-actions.ts`.
+
+---
+
+## 🕳️ Examples
+
+```bash
+# Standard auth-mode launch on the default port
+npx constella --auth
+
+# Auth mode on a custom port
+npx constella --auth --port 4000
+
+# Auth mode with the runtime root somewhere else
+npx constella --auth --path /srv/constella-home
+
+# Force the first-run onboarding wizard, still under the auth gate
+npx constella --auth --onboarding
+```
+
+> The run-mode **picker** on the login screen appears only in developer mode (`isDevMode()` in `src/lib/build-mode.ts`). A public CLI launch sets `CONSTELLA_PUBLIC=1`, so the mode is fixed by the launch flag and the picker is hidden.
+
+---
+
+## ✦ Possible states
+
+| State | Cause | Symptom |
+|---|---|---|
+| **Login required** | `auth` mode, no session | Browser redirected to `/login`. |
+| **Password rejected** | Wrong password for an existing account | `login.failed` message; no fallthrough to signup (email exists). |
+| **New account created** | Unknown email + valid password | `signUp.email` succeeds, redirect to `/`. |
+| **2FA challenge** | Account has TOTP enabled | Code field shown; needs a 6-digit TOTP. |
+| **Passkey login** | User clicks the passkey button | Browser WebAuthn prompt; session minted server-side. |
+| **Boot refused** | Network mode, missing `BETTER_AUTH_SECRET` | `[boot] FATAL` + `process.exit(1)`; server never starts. |
+| **Auto-login attempted** | `ensureLocalOperator` reached in `auth` | Throws `"ensureLocalOperator is start-mode only"` (defense-in-depth). |
+
+---
+
+## 🛰️ Related integrations
+
+- **Org isolation** — after sign-in, `requireWorkspace()` resolves the active org through a `member` join so a session can never point at another tenant's org (`getActiveOrg` in `src/lib/workspace.ts`). Roles are `owner` / `admin` / `member`.
+- **Vault** — provider secrets are encrypted with `CONSTELLA_VAULT_KEY`, persisted alongside `BETTER_AUTH_SECRET` in `~/.constella/.env`. See [SECURITY](./SECURITY.md).
+- **Worker** — the 24/7 worker authenticates to the web with `x-worker-secret` (`CONSTELLA_WORKER_SECRET`) over loopback, independent of the human login. See [ARCHITECTURE](./ARCHITECTURE.md).
+- **Public API / PAT** — programmatic access uses `Bearer cn_<token>` PATs, a separate path from the browser session. See [PUBLIC_API](./PUBLIC_API.md).
+
+---
+
+## 🕳️ Security
+
+- **Mandatory signing secret.** `auth` (like `vps`/`portable`) **must** boot with a real `BETTER_AUTH_SECRET`. Without one, sessions would be signed with better-auth's public default key (forgeable cookies), because better-auth only throws on the default under `NODE_ENV=production`. `assertAuthSecret()` closes that gap by exiting the process. `start` is exempt because it is local-only with auto-login.
+- **Loopback bind.** `auth` binds `127.0.0.1`; the listener is not reachable from the network. If you place an https reverse proxy in front, set `BETTER_AUTH_URL` to the public `https://` origin so session cookies are marked `Secure`.
+- **No default remote credential.** The `operator/operator123` account is start-mode-only and never provisioned in `auth`.
+- **Real 2FA / passkeys.** TOTP secrets live in the `two_factor` table; WebAuthn credentials in the `passkey` table (COSE public key, counter, transports). Passkey challenges are stored in short-lived (`maxAge: 300`) httpOnly cookies between the options and verify round-trips (`src/lib/passkey.ts`).
+- **30-day sessions.** Sessions expire after 30 days; the `account` deletion path cascades to sessions, accounts, passkeys and tokens.
+- **Cross-tenant safety.** `activeOrgId` is treated as attacker-controllable and always re-validated through a membership join.
+
+---
+
+## 🌌 Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Server exits immediately with `[boot] FATAL: BETTER_AUTH_SECRET is required` | Network mode booted without a secret | Let the CLI persist one (default), or set `BETTER_AUTH_SECRET` in the environment / `~/.constella/.env`. |
+| Login screen never appears (auto-signed-in) | You actually launched `start`, not `auth` | Check the boot line `Mode : auth · 127.0.0.1:3000`; relaunch with `--auth`. |
+| "ensureLocalOperator is start-mode only" in logs | Auto-login code path reached under `auth` | Expected guard — there is no auto-login in `auth`; sign in manually. |
+| Passkey button fails | `BETTER_AUTH_URL` host mismatch (RP id) | Set `BETTER_AUTH_URL` to the exact origin you browse from; `rpID()` is its hostname. |
+| Cookies not `Secure` behind https | `BASE_URL` still `http://localhost:3000` | Set `BETTER_AUTH_URL` to the `https://` origin so `useSecureCookies` flips on. |
+| Forgot the operator password (start→auth migration) | Default credential only exists in `start` | In `auth`, create/sign into a real account; do not rely on `operator123`. |
+| Can't reach the app from another machine | `auth` binds loopback by design | Use [VPS_MODE](./VPS_MODE.md) for remote access. |
+
+---
+
+## ✦ Related links
+
+- [START_MODE](./START_MODE.md) — the auto-login local mode `auth` contrasts with.
+- [VPS_MODE](./VPS_MODE.md) — network-exposed mode over a tailnet, in Docker.
+- [PORTABLE_MODE](./PORTABLE_MODE.md) — the USB-drive run mode.
+- [CONFIGURATION](./CONFIGURATION.md) — env vars, secrets, and the runtime root.
+- [INSTALLATION](./INSTALLATION.md) — installing and first launch.
+- [SECURITY](./SECURITY.md) — vault, scrubbing, FS jail, session model.
+- [ARCHITECTURE](./ARCHITECTURE.md) — dual-process web + worker, boot reconcile.
+- [PUBLIC_API](./PUBLIC_API.md) — PAT-based programmatic access.
+- [TROUBLESHOOTING](./TROUBLESHOOTING.md) — broader failure catalogue.