constellai 0.3.0

package/docs/en/SKILLS.md

@@ -0,0 +1,349 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/SKILLS.md) · [✦ Constella](../../README.md)
+
+# Skills ✦ — the constellation's playbooks 🌌
+
+![](../assets/divider-orbit.svg)
+
+A research-backed library of `SKILL.md` playbooks that ships with Constella and is seeded into every workspace. Skills are the procedural starlight each agent steers by — the right ones auto-link to the right agents based on the project **stack** and the agent's **role**, and the team can grow new ones from what it has learned.
+
+---
+
+## 1. When to use 🛰️
+
+- You want to know **what an agent already knows** before it builds (engineering practice, the chosen framework, the security posture).
+- You're tuning **which skills reach which agent** — enable/disable per agent, or pin signature skills so they survive the prompt budget.
+- You changed the **Project Stack** and want each agent re-linked to the skills its new stack actually needs.
+- Vannevar (Knowledge) has **distilled new skills** from the team's learnings and you need to review and approve them.
+- You're authoring a **custom skill** for this workspace, or generating one from a prompt.
+
+See [AGENTS.md](./AGENTS.md) for the roster, [KB_RAG.md](./KB_RAG.md) for how knowledge is indexed, and [PROJECT_STACKS.md](./PROJECT_STACKS.md) for where the stack picks come from.
+
+---
+
+## 2. How it works 🌠
+
+There are **two layers** of skills, and it's important not to conflate them:
+
+| Layer | Where it lives | Source of truth | Indexed into DB? |
+|---|---|---|---|
+| **Native library** | `skills/` at the **package root** (ships inside the npm package, outside the org workspace jail) | the `SKILL.md` files | No — it is a read-only catalogue the seeder reads from |
+| **Workspace skills** | `.claude/skills/<name>.md` inside each org's workspace | the `.md` file on disk (write-through) | Yes — `src/server/sync.ts` mirrors the file into the `skill` table |
+
+The native library is the **catalogue**; the workspace skills are the **executable copies** an agent actually carries. At onboarding the whole library is seeded into the workspace, then each agent is auto-linked to the subset its stack + role need.
+
+### Where the library is found
+
+`skillsLibraryRoot()` (in `src/server/skills-library.ts`) probes, in order:
+
+1. `process.env.CONSTELLA_PKG_ROOT/skills` (set by the CLI launcher in an installed/compiled run)
+2. `launchDir()/skills` (the repo root in a dev tree)
+3. `process.cwd()/skills`
+
+The first directory that actually exists wins. If none exist, the loader degrades to an **empty index** — every helper becomes a safe no-op rather than crashing.
+
+### Leaf-folder keying (and the stale `INDEX.json`) 🕳️
+
+`loadLibraryIndex()` fs-walks `skills/` (depth ≤ 8) for every file literally named `SKILL.md`. Each skill is keyed by its **leaf folder name** — `skills/stacks/frontend/react/SKILL.md` → `react` — **not** by the frontmatter `name` (some skills carry a namespaced frontmatter name like `testing/testing-strategy-pyramid` that wouldn't match the stable ids used by the stack map and the universal list). The folder name is the stable id.
+
+The hand-maintained `skills/INDEX.json` **is known to lag behind the files and is ignored at runtime** — the loader walks the real files instead. First occurrence wins on duplicate leaf names (e.g. `redis` exists under both `stacks/database` and `stacks/queue`).
+
+Frontmatter parsed per skill (minimal single-line YAML reader): `name`, `description`, `domain`, `category`, and the multi-line list `official_sources`. The `official_sources` URLs become the **web-research allowlist hosts** (`stackDocHosts()`).
+
+---
+
+## 3. Main flow: Stack → Skills → Research → RAG → Execution 🚀
+
+```mermaid
+flowchart LR
+  STACK["Project Stack<br/>workspace.stack {lang, framework, db, …}"]
+  MAP["STACK_VALUE_TO_SKILL<br/>(catalog value → leaf id)"]
+  ROLE["Role profile<br/>role-skill-profile.ts"]
+  LIB["Native library skills/<br/>240 SKILL.md (leaf-keyed)"]
+  WS[".claude/skills/&lt;name&gt;.md<br/>seeded into workspace"]
+  LINK["agent_skill links<br/>auto vs hand-toggled"]
+  RES["Web research<br/>official_sources hosts"]
+  RAG["RAG / KB<br/>memory nebula"]
+  EXEC["Execution<br/>agent run"]
+
+  STACK --> MAP --> LIB
+  ROLE --> LIB
+  LIB --> WS --> LINK
+  LIB --> RES --> RAG
+  LINK --> EXEC
+  RAG --> EXEC
+```
+
+1. **Project Stack** (`workspace.stack`, a `Record<string,string>`) lists the chosen language, runtime, framework, database, ORM, styling, testing, etc.
+2. Each stack value maps through `STACK_VALUE_TO_SKILL` to a library leaf id (`Vue → vue`, `Django → django`, `Tailwind CSS → tailwind`). Missing or `None` → skipped.
+3. The whole library is **seeded** as `.claude/skills/<name>.md` files; only the stack + role subset is **auto-linked** per agent.
+4. The matched skills' `official_sources` define which official-docs hosts the **web research** step may fetch.
+5. Researched docs and patterns flow into **RAG / the KB** (the memory nebula — see [KB_RAG.md](./KB_RAG.md), [MEMORY_RAG.md](./MEMORY_RAG.md)).
+6. At **execution**, the agent's pinned core skills + the long tail + RAG hits are assembled into its prompt.
+
+---
+
+## 4. Key concepts 🪐
+
+### Universal vs stack vs role skills
+
+| Kind | Defined by | Reaches |
+|---|---|---|
+| **Universal** | `UNIVERSAL_SKILL_NAMES` (a fixed list in `skills-library.ts`) | Every agent, regardless of stack — clean-code, git-workflow, owasp-top-10, testing-strategy-pyramid, ui-ux-principles, accessibility-wcag, the process rituals, `research-official-docs`, `readme-generation`, … |
+| **Stack** | `STACK_VALUE_TO_SKILL[stackValue]`, gated by the role's `stackPrefixes` | The agents whose role owns that stack folder (a Vue project's Frontend gets `vue`, not `react`+`svelte`) |
+| **Role** | `roleProfile(role).allPrefixes` | Every skill under the role's folders (Frontend → all of `design/`; Backend → `engineering/backend/`; Security → `engineering/security/`) |
+
+The auto-link set for an agent is computed by `skillNamesForRole(stack, role)`:
+- start with the universals that exist on disk;
+- add every skill whose `relPath` starts with one of the role's `allPrefixes`;
+- add stack-gated skills whose `relPath` starts with a `stackPrefixes` entry **and** were actually selected by the stack.
+
+This replaced the old "link all ~180 to everyone" so the **right skills reach the right agent**.
+
+### Core (pinned) skills
+
+`coreSkillNamesForRole(stack, role)` returns the role's signature skills (`roleProfile().core`) plus the chosen stack picks under the role's stack folders. The context assembler (`agentSkills()` in `src/server/context-manager.ts`) ranks the agent's enabled skills — `core = 0`, stack = `1`, rest = `2` — pins up to **10 core** into a high-priority prompt section (never trimmed under budget) and caps the long tail at **30**.
+
+### Native vs provisional
+
+The `skill` table (`src/db/schema.ts`):
+
+| Column | Meaning |
+|---|---|
+| `native` | `true` = seeded from the library (only non-native can be deleted) |
+| `provisional` | `true` = AI-drafted / Vannevar-proposed, **not linked** to any agent until approved |
+| `indexed` | `pending` \| `indexed` — sync/index state |
+| `proposedRole` | for a Vannevar proposal: the team role it targets (approval links it there) |
+
+### `agentSkill.auto` — auto vs hand-toggled
+
+The `agent_skill` join carries one boolean, `auto`:
+
+- `auto = true` → **system-managed**: created by the stack/role auto-link and **reconciled** on boot / stack change. The reconciler may add or remove it.
+- `auto = false` → **operator hand-toggled** in the UI. The reconciler **never touches it** — neither prunes nor re-adds.
+
+This is what lets you pin a non-default skill onto an agent (e.g. give the Backend agent `react`) and trust it won't be wiped when the stack reconciles.
+
+### Reconciliation
+
+`reconcileStackRoleSkills(wsId)` (in `src/server/seed-library-skills.ts`) runs at boot and on stack change. For each agent it computes the desired set from `skillNamesForRole`, then:
+- **prunes** `auto` links to **library** skills that fall outside the role's profile (manual links and the procedural skills are left alone);
+- **adds** the role's missing skills with `auto = true`.
+
+It is idempotent and uses **no LLM**.
+
+---
+
+## 5. Seeding & file shapes
+
+At onboarding (`completeOnboarding` in `src/server/onboarding.ts`):
+
+1. Six **procedural** skills are seeded first and win on name conflict: `open-pr`, `run-suite`, `secret-scan`, `telegram-notify` (provisional), `moscow-prioritise`, `gguf-validate` (provisional). Non-provisional ones are enabled for every agent.
+2. The **whole native library** is seeded with `seedLibrarySkills({ names: allLibrarySkillNames(), linkNames: [] })` — every library skill becomes a `skill` row + a `.claude/skills/<name>.md` file, but **none** is linked here.
+3. `reconcileStackRoleSkills(wsId)` then links each agent to its stack + role subset.
+
+`seedLibrarySkills()` writes each `.md` in the exact shape `indexSkillFile` derives, so the watcher's later re-index is a no-op:
+
+```markdown
+# Skill — react
+
+**Trigger:** When working with react in this project.
+
+<description from frontmatter>
+
+## Procedure
+<SKILL.md body with frontmatter stripped>
+```
+
+Each agent's enablement is mirrored to `.claude/agents/<handle>/skills.md` by `rebuildAgentSkillsMd()` — a generated index listing each enabled skill and its file, plus the agent's ritual. The sync engine reads backtick-wrapped names from this file to drive enablement (disk = truth).
+
+---
+
+## 6. Vannevar's skill proposals (P3 — learning → skills) 🌌
+
+`proposeSkillsFromLearnings(orgId)` (in `src/server/kb.ts`), triggered from the Skills page via `suggestSkillsFromLearnings()`:
+
+1. Finds the Vannevar agent (handle `vannevar`, or a role matching `/knowledge/i`); aborts if over its daily USD cap.
+2. Reads up to **50** active KB entries of **reusable** types (`doc`, `research`, `ui-pattern`, `stack`, `integration`, `fix`, `decision`, `architecture`, `business-rule`), keeps those with confidence ≥ 60, and requires **at least 4** strong entries.
+3. Prompts the agent (local RAG model preferred, else the agent's CLI) to propose **0–3** genuinely reusable skills as a JSON array, deduped against existing skill names.
+4. Each accepted proposal lands as a **provisional** skill (`native = false`, `provisional = true`) with a `proposedRole`, written to `.claude/skills/<name>.md`, **not linked** to any agent.
+5. Operators are notified to review and approve in `/skills`.
+
+`approveProvisional(id)` flips `provisional → false`, sets `indexed = indexed`, and links it to the agents of its `proposedRole` (or to **all** agents if no role) with `auto = false` — so it is actually used, not approved-but-orphan.
+
+Other authoring paths:
+- `createSkill()` — operator-authored skill, written to disk and enabled for one agent (`auto = false`).
+- `generateSkill(prompt)` — drafts a **provisional** skill from a prompt (no agent enabled until approved).
+- `saveSkillInstructions()` — edits a skill's Procedure (rewrites the `.md`).
+- `toggleAgentSkill()` / `setAllAgentSkills()` — per-agent enablement (always `auto = false`).
+- `deleteSkill()` — only **non-native** skills; removes the `.md` (deindex drops the row).
+
+---
+
+## 7. Tables 🛰️
+
+### `skill`
+| Column | Type | Notes |
+|---|---|---|
+| `id` | text PK | |
+| `workspaceId` | text | FK → workspace |
+| `name` | text | leaf id / kebab-case |
+| `summary` | text | one-line description |
+| `instructions` | text | the Procedure body |
+| `trigger` | text | when to use it |
+| `native` | bool | library-seeded (undeletable) |
+| `provisional` | bool | AI-drafted, pending approval |
+| `indexed` | `pending`\|`indexed` | sync state |
+| `proposedRole` | text? | Vannevar proposal target role |
+
+### `agent_skill` (join, PK `agentId+skillId`)
+| Column | Type | Notes |
+|---|---|---|
+| `agentId` | text | FK → agent |
+| `skillId` | text | FK → skill |
+| `auto` | bool | `true` = system-managed (reconciled); `false` = hand-toggled (never touched) |
+
+### Library taxonomy (native `skills/`)
+| Group | Approx. count | What's inside |
+|---|---|---|
+| `process/` | 15 | Discovery, framing, architecture-first, requirements→specs, specs→issues, MoSCoW/RICE, security-by-design, testing-before-done, ADRs, review |
+| `engineering/` | 32 | `security/` `architecture/` `performance/` `testing/` `frontend/` `backend/` `practices/` |
+| `design/` | 9 | UI/UX, design systems, CSS, motion, color & typography, responsive layout |
+| `languages/` | 15 | Per-language techniques (TypeScript … Dart) |
+| `stacks/` | ~98 | One per catalog option across runtime/frontend/meta/backend/database/orm/styling/container/infra/queue/auth |
+| `references/` | 10 | Distilled external UI/AI references |
+| `meta/` | 3 | How to author agent skills |
+
+> Counts are approximate and live in `skills/README.md`; the loader walks **240** `SKILL.md` files at the time of writing (the catalogue grows). Only leaf-named, on-disk skills are usable.
+
+---
+
+## 8. Helper reference
+
+| Function (`src/server/skills-library.ts`) | Returns |
+|---|---|
+| `loadLibraryIndex()` | cached `Map<name, LibrarySkill>` from the fs-walk |
+| `librarySkillByName(name)` / `readLibrarySkillMd(name)` | one entry / its raw `SKILL.md` |
+| `stripFrontmatter(md)` | the body with the leading `---` block removed |
+| `librarySkillNamesForStack(stack)` | universals + stack-matched ids, on disk |
+| `allLibrarySkillNames()` | every leaf name (seeded so the whole library shows) |
+| `skillNamesForRole(stack, role)` | the auto-link set for an agent |
+| `coreSkillNamesForRole(stack, role)` | the pinned signature set |
+| `stackDocHosts(stack)` | official-docs hostnames for the web-research allowlist |
+
+---
+
+## 9. Step-by-step
+
+### Re-link agents after a stack change
+1. Change the Project Stack (see [PROJECT_STACKS.md](./PROJECT_STACKS.md)).
+2. `reconcileStackRoleSkills(wsId)` runs (boot / stack change) — auto links update, hand-toggles untouched.
+3. Verify in Agent Studio → Skills.
+
+### Approve a Vannevar-proposed skill
+1. Open `/skills` after the "proposed N new skills" notification.
+2. Review the provisional skill's Procedure.
+3. Approve → `approveProvisional` links it to its `proposedRole` (or all) with `auto = false`.
+
+### Add a custom skill to one agent
+1. Author it (`createSkill`) or generate a draft (`generateSkill`).
+2. If generated, approve it first (it's provisional).
+3. Toggle it on for the agent (`toggleAgentSkill`) — it is `auto = false`, so reconcile leaves it alone.
+
+---
+
+## 10. Examples
+
+Inspect the library from chat (`src/server/commands.ts`):
+
+```text
+/skills
+→ 📚 Skills library — 240 skill(s). Sample: clean-code, git-workflow, … . Enable/disable per agent in Agent Studio → Skills.
+```
+
+A seeded workspace skill file (`.claude/skills/tailwind.md`):
+
+```markdown
+# Skill — tailwind
+
+**Trigger:** When working with tailwind in this project.
+
+Utility-first CSS framework; consult for design tokens, responsive variants, and component styling.
+
+## Procedure
+…SKILL.md body…
+```
+
+A frontmatter header in the native library (`skills/stacks/frontend/react/SKILL.md`):
+
+```yaml
+---
+name: react
+description: Component-based JavaScript library for building web and native UIs; …
+domain: stack
+category: frontend
+tags: [react, components, hooks, jsx, ui, spa]
+official_sources:
+  - https://react.dev/
+  - https://github.com/facebook/react
+verified: 2026-06-16
+---
+```
+
+---
+
+## 11. Possible states 🌠
+
+| Object | States |
+|---|---|
+| `skill.indexed` | `pending` → `indexed` |
+| `skill.native` | `true` (library) / `false` (custom or proposed) |
+| `skill.provisional` | `true` (awaiting approval) / `false` (active) |
+| `agent_skill.auto` | `true` (managed) / `false` (manual) |
+| Library index | populated / empty (dir missing → no-op) |
+
+---
+
+## 12. Related integrations 🪐
+
+- **Web research** — matched skills' `official_sources` → `stackDocHosts()` → the WebSearch/WebFetch allowlist (see [AI_ARCHITECTURE.md](./AI_ARCHITECTURE.md), [MODELS.md](./MODELS.md)).
+- **RAG / KB** — `.claude/skills/*.md` are re-indexed by the sync engine and embedded into RAG (see [KB_RAG.md](./KB_RAG.md), [MEMORY_RAG.md](./MEMORY_RAG.md)).
+- **Vannevar / KB agent** — proposes skills from learnings (see [KB_AGENT.md](./KB_AGENT.md)).
+- **Onboarding** — seeds + reconciles the library (see [ONBOARDING.md](./ONBOARDING.md)).
+- **Plugins** — skills are knowledge, not capabilities; plugins are integrations (see [PLUGINS.md](./PLUGINS.md)).
+
+---
+
+## 13. Security 🕳️
+
+- The native library lives **outside** the org workspace jail (at the package root) and is **read-only** — agents never write to it.
+- Workspace skill files live under `.claude/skills/` **inside** the FS jail (`safe()` path checks; see [SECURITY.md](./SECURITY.md)).
+- Skill mutations are workspace-scoped with IDOR guards (`agentInWorkspace`, `skillInWorkspace`) so one org cannot flip skills on another org's agents.
+- Vannevar proposals are budget-gated (daily USD cap) and land **provisional** — nothing reaches an agent's prompt until an operator approves.
+- Only **non-native** skills can be deleted; the library catalogue cannot be mutated through the app.
+
+---
+
+## 14. Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `/skills` reports 0 skills | library dir not found at runtime | ensure `CONSTELLA_PKG_ROOT/skills` (installed) or repo-root `skills/` (dev) exists |
+| A stack skill didn't auto-link | catalog value missing from `STACK_VALUE_TO_SKILL`, or no `SKILL.md` for that leaf id | the map filters to on-disk skills — add the `SKILL.md` or the mapping |
+| A pinned skill keeps disappearing | it was an `auto` (managed) link outside the role profile | hand-toggle it (`auto = false`) so reconcile leaves it alone |
+| Edited a `.claude/skills/*.md` and the UI didn't update | watcher debounce / sync not run | the sync engine re-indexes on file change; disk is truth |
+| Vannevar proposed nothing | < 4 strong reusable KB entries, or over daily cap | accumulate more validated learnings; check the agent's cost cap |
+| Frontmatter `name` ≠ folder | by design — leaf folder name is the id, not frontmatter | rename the **folder** to change the id |
+
+---
+
+## 15. Related links
+
+- [AGENTS.md](./AGENTS.md) — the roster and roles that drive role profiles
+- [PROJECT_STACKS.md](./PROJECT_STACKS.md) — where `workspace.stack` comes from
+- [KB_AGENT.md](./KB_AGENT.md) — Vannevar and learning → skills
+- [KB_RAG.md](./KB_RAG.md) · [MEMORY_RAG.md](./MEMORY_RAG.md) — the memory nebula
+- [AI_ARCHITECTURE.md](./AI_ARCHITECTURE.md) — prompt assembly, web research
+- [ONBOARDING.md](./ONBOARDING.md) — seeding the library
+- [PLUGINS.md](./PLUGINS.md) — integrations (distinct from skills)
+- [CHAT_COMMANDS.md](./CHAT_COMMANDS.md) — `/skills` and friends
+- [SECURITY.md](./SECURITY.md) — the FS jail

package/docs/en/START_MODE.md

@@ -0,0 +1,285 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/START_MODE.md) · [✦ Constella](../../README.md)
+
+# Start — running Constella locally ✦
+
+> The default ignition for a single-pilot ship on your own machine: `constella --start` boots Constella on `127.0.0.1`, and the agent constellation runs with full local permissions. Authentication is always on — first run shows a signup screen, later runs show login.
+
+`constella --start` is the **local install** of Constella: the server binds the loopback interface and is reachable only from the machine it runs on. It is the right launch flag for a single operator on their own laptop / workstation — zero network exposure, full agent autonomy. It is **not** an auth mode: just like every other launch flag, it requires you to sign in (email + password).
+
+---
+
+## 🛰️ When to use
+
+| Use `--start` when… | Prefer another install method when… |
+| --- | --- |
+| You run Constella **on your own laptop / workstation** | You expose it on a network → [VPS](./VPS_MODE.md) |
+| You want a **loopback-only** control plane | You need remote access over a private tailnet → [VPS](./VPS_MODE.md) |
+| You want agents that can **install deps + run tests** (full shell) | You boot from a USB drive across machines → [PORTABLE](./PORTABLE_MODE.md) |
+| You're developing, demoing, or running a personal agent-company | — |
+
+`--start` is **local-only by design**. It binds the loopback interface, so the surface is never on the network. Authentication is the same as in every other launch flag — there is no auto-login and no passwordless shortcut.
+
+---
+
+## 🌌 How it works
+
+`start` is one of the launch flags resolved by `bin/constella.mjs`. A launch flag is **required** — a bare `constella` no longer starts. The launcher selects the flag, then exports it as `CONSTELLA_RUN_MODE`, which the server reads back through `getRunMode()`:
+
+```ts
+// src/lib/run-mode.ts
+export type RunMode = "start" | "vps" | "portable";
+
+export function getRunMode(): RunMode {
+  const m = process.env.CONSTELLA_RUN_MODE as RunMode | undefined;
+  return m && m in RUN_MODES ? m : "start";
+}
+```
+
+Two behaviours flow from `--start`:
+
+1. **Loopback bind.** The web server binds `127.0.0.1`, so nothing is reachable off-box. Only `vps` / `portable` bind `0.0.0.0`.
+2. **Full-access agents.** The CLI adapter runs agents with `--permission-mode bypassPermissions` (install deps, run tests, full shell) because `start` means you're on your own machine.
+
+Authentication is **identical to every launch flag**: the first time the database has no user, you get a real **signup** screen (name + email + password) that creates the single operator account; afterwards you get a **login** screen. There is no auto-login, no `/api/dev-login`, no predictable default credential.
+
+The chosen flag is also **persisted on the organization** at onboarding time (`organization.runMode`), so the org record remembers how it was first launched.
+
+---
+
+## 🚀 Main flow
+
+```mermaid
+flowchart TD
+  A["constella --start"] --> B["bin/constella.mjs"]
+  B --> C["CONSTELLA_RUN_MODE=start, host 127.0.0.1, port 3000"]
+  C --> D["Persist secrets to HOME/.env chmod 600: BETTER_AUTH_SECRET, VAULT_KEY, WORKER_SECRET"]
+  D --> E["drizzle-kit migrate, fresh DB gets its tables"]
+  E --> F["next start + worker, supervised"]
+  F --> G["Browser hits any app page"]
+  G --> H{"requireWorkspace: session cookie?"}
+  H -- "yes" --> Z["Render the app"]
+  H -- "no" --> I{"any user in the DB?"}
+  I -- "no" --> S["redirect /signup, name + email + password"]
+  I -- "yes" --> L["redirect /login, email + password"]
+  S --> N["operator account created, session set"]
+  L --> N
+  N --> Z
+```
+
+### Authentication flow (signup-then-login) 🌠
+
+```mermaid
+sequenceDiagram
+  participant U as Browser
+  participant W as requireWorkspace
+  participant A as better-auth
+
+  U->>W: GET app page
+  W->>W: getSession
+  Note over W: no session cookie
+  alt no user exists yet
+    W-->>U: redirect /signup
+    U->>A: name + email + password
+    A-->>U: operator created, session cookie set
+  else operator exists
+    W-->>U: redirect /login
+    U->>A: email + password
+    A-->>U: session cookie set, or wrong password
+  end
+  U->>W: GET app page, now authenticated
+  W-->>U: scoped workspace returned
+```
+
+---
+
+## 🪐 Key concepts
+
+### The single operator
+
+There is **one** operator account, shared across every launch flag — it is never duplicated. The first run with an empty database shows a **signup** screen (name + email + password) that creates it; every later run shows **login**. A wrong password returns "incorrect email or password". There is **no** predictable default credential, **no** `ensureLocalOperator`, and **no** `/api/dev-login` auto sign-in.
+
+The operator is resolved the same way under `start`, `vps` and `portable`: it is the single `user` row. Switching between launch flags keeps the **same** account.
+
+### Full-access agents (`bypassPermissions`)
+
+`src/server/adapters/cli.ts` decides how much shell power agents get:
+
+```ts
+const RUN_MODE = process.env.CONSTELLA_RUN_MODE ?? "start";
+const AGENT_FULL_ACCESS = process.env.CONSTELLA_AGENT_FULL_ACCESS != null
+  ? process.env.CONSTELLA_AGENT_FULL_ACCESS !== "0"
+  : RUN_MODE === "start";
+
+function claudePermArgs(): string[] {
+  return AGENT_FULL_ACCESS
+    ? ["--permission-mode", "bypassPermissions"]   // start → full: install + test
+    : ["--permission-mode", "acceptEdits"];        // network installs → jailed: edits only
+}
+```
+
+So under `--start` the `claude` / `codex` CLIs run with `bypassPermissions` — they can install dependencies and run tests in the workspace — because you're on your own machine. The network installs (`vps` / `portable`) default to `acceptEdits` (edits-only, jailed). Override either way with `CONSTELLA_AGENT_FULL_ACCESS=1|0`. Agents still always run **vanilla** (a temp settings overlay sets `disableAllHooks: true`) so the operator's personal `~/.claude` hooks/plugins never bleed into agent runs. This full-access default is a **run-context** detail of being local — it is independent of authentication, which is always required. See [AGENTS](./AGENTS.md) and [AI_ARCHITECTURE](./AI_ARCHITECTURE.md).
+
+### The auth secret
+
+`next start` runs under `NODE_ENV=production`, where better-auth **throws on its default secret**. So Constella always needs a real `BETTER_AUTH_SECRET` — the launcher generates and persists one to `<HOME>/.env` (`chmod 600`) on every launch flag, `start` included. Session cookies stay non-`Secure` under `--start` because the local transport is plain `http`.
+
+---
+
+## Tables 📊
+
+### `--start` vs the other launch flags
+
+| Property | **start** | vps | portable |
+| --- | --- | --- | --- |
+| Authentication | email + password | email + password | email + password |
+| First run (no user) | signup screen | signup screen | signup screen |
+| Later runs | login screen | login screen | login screen |
+| Bind host | `127.0.0.1` | `0.0.0.0` | `0.0.0.0` |
+| Operator | the single shared account | the single shared account | the single shared account |
+| Agent permission | `bypassPermissions` | `acceptEdits` | `acceptEdits` |
+| `BETTER_AUTH_SECRET` | persisted (always required) | persisted (always required) | persisted (always required) |
+| Secure cookies | no (local http) | yes | if behind https |
+| Typical use | own machine / dev | server over Tailscale | USB across machines |
+
+### Launch commands → local install
+
+| Command | Result |
+| --- | --- |
+| `constella --start` | Local install (loopback bind) |
+| `constella --bind local` | Local install (legacy `--bind` back-compat) |
+| `CONSTELLA_RUN_MODE=start` | Forces local behaviour for the server process |
+
+> A bare `constella` (no flag) **no longer starts** — a launch flag is required.
+
+### Env vars that shape a local install
+
+| Variable | Default under `--start` | Effect |
+| --- | --- | --- |
+| `CONSTELLA_RUN_MODE` | `start` | The run flag the server reads |
+| `CONSTELLA_HOME` | `~/.constella` | Runtime root (DB, secrets, orgs) |
+| `--host` / host | `127.0.0.1` | Loopback bind |
+| `--port` / `PORT` | `3000` | Web port |
+| `CONSTELLA_AGENT_FULL_ACCESS` | `1` (implied by start) | `0` re-jails agents to edits-only |
+| `CONSTELLA_WEB_RESEARCH` | on | `0` disables agent WebSearch/WebFetch |
+| `BETTER_AUTH_SECRET` | generated → `<HOME>/.env` | Session signing key (always required) |
+
+### Key files
+
+| File | Role |
+| --- | --- |
+| `src/lib/run-mode.ts` | `RunMode` type, `RUN_MODES`, `getRunMode()`, `requiresLogin()` |
+| `bin/constella.mjs` | Launcher: picks flag, sets host/port, persists secrets, boots web + worker |
+| `src/lib/workspace.ts` | `requireWorkspace()` — redirects to `/signup` or `/login` |
+| `src/lib/auth.ts` | better-auth config; `assertAuthSecret()` boot gate |
+| `src/server/adapters/cli.ts` | `claudePermArgs()` → `bypassPermissions` under `--start` |
+| `src/lib/run-context.ts` | `detectRunContext()` for the Update path |
+
+---
+
+## Step-by-step 🧭
+
+### Start a fresh ship locally
+
+1. **Launch** with `--start`:
+   ```bash
+   npm install -g constellai
+   constella --start
+   # or, once: npx constellai --start
+   ```
+2. The launcher prints the runtime root and `Mode : start · 127.0.0.1:3000`, persists secrets to `<HOME>/.env`, applies migrations, and boots `next start` + the worker.
+3. **Open** `http://127.0.0.1:3000`.
+4. `requireWorkspace()` finds no session. If the database has no user yet, you land on the **signup** screen; create the single operator with name + email + password.
+5. On later runs the same path lands on the **login** screen — sign in with that email + password.
+6. If no org exists yet, you continue into [ONBOARDING](./ONBOARDING.md); otherwise you're in the app.
+
+### Re-jail agents (extra caution)
+
+```bash
+CONSTELLA_AGENT_FULL_ACCESS=0 constella --start
+```
+Agents now run `acceptEdits` (edits-only, no arbitrary shell), while you keep the loopback-local convenience.
+
+---
+
+## Examples 🌟
+
+**Default local launch:**
+```bash
+$ constella --start
+Constella runtime root : /home/you/.constella
+Mode                   : start  ·  127.0.0.1:3000
+• Secrets ready (stored in /home/you/.constella/.env, never printed).
+• Starting: next start -H 127.0.0.1 -p 3000  (…)  +  worker
+```
+
+**Custom port, still local:**
+```bash
+$ constella --start --port 4000
+# → http://127.0.0.1:4000, signup on first run then login, full-access agents
+```
+
+**Pin a different runtime root:**
+```bash
+$ CONSTELLA_HOME=/data/constella constella --start
+# DB at /data/constella/constella.db; secrets at /data/constella/.env
+```
+
+---
+
+## Possible states 🛰️
+
+| Situation | Behaviour |
+| --- | --- |
+| No session cookie, no user in DB | Redirect `/signup` → create the operator → app |
+| No session cookie, operator exists | Redirect `/login` |
+| Sign-in succeeds | Cookie set, land on `/` (or `/onboarding` if no org) |
+| Wrong password | "incorrect email or password" |
+| `CONSTELLA_FORCE_ONBOARDING=1` | After session, redirect `/onboarding` (one-shot, cleared by `completeOnboarding`) |
+| Org missing / workspace missing | Redirect `/onboarding` |
+| Agent run, `--start` | `claude --permission-mode bypassPermissions` (full shell) |
+| Agent run, `CONSTELLA_AGENT_FULL_ACCESS=0` | `claude --permission-mode acceptEdits` (jailed) |
+
+---
+
+## Related integrations 🪐
+
+- **Onboarding** persists the active flag onto `organization.runMode` (`src/server/onboarding.ts`). See [ONBOARDING](./ONBOARDING.md).
+- **Worker** (`bin/worker.mjs`) connects back over `127.0.0.1` regardless of bind host; under `--start` that's also the web bind. See [ARCHITECTURE](./ARCHITECTURE.md).
+- **Vault** still needs `CONSTELLA_VAULT_KEY` even locally (provider keys are encrypted). See [SECURITY](./SECURITY.md).
+- **Update** path is context-aware via `detectRunContext()`. See [UPDATE](./UPDATE.md).
+
+---
+
+## Security 🕳️
+
+A local install trades network hardening for local convenience — safe precisely because it is local:
+
+- **Loopback only.** Host binds `127.0.0.1`; nothing is reachable off-box.
+- **Authentication always on.** A real signup-then-login gate guards every session — there is no auto-login and no predictable credential. The single operator is whoever completes the first-run signup.
+- **Real auth secret persisted.** A real `BETTER_AUTH_SECRET` is generated to `<HOME>/.env` (`chmod 600`) so sessions aren't forgeable; cookies are non-`Secure` only because the local transport is plain `http`.
+- **Full-access agents are local-only.** `bypassPermissions` lets agents run shell, but the workspace is still an FS jail (`safe()` lexical + symlink checks), and the guard/lock hooks still apply. Set `CONSTELLA_AGENT_FULL_ACCESS=0` to re-jail.
+- **Do not port-forward a local install.** If you need remote access, use [VPS](./VPS_MODE.md) (Tailscale + Docker) — never expose the loopback install to a network.
+
+---
+
+## Troubleshooting 🧰
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Signup screen never appears | A user already exists in the DB | Expected — you get `/login` once the operator exists; sign in instead |
+| "incorrect email or password" | Wrong password for the operator | Re-enter the operator's password set at signup |
+| Agents can't install deps / run tests | `CONSTELLA_AGENT_FULL_ACCESS=0` set | Unset the override, or relaunch with `--start` |
+| Reachable from another machine | You overrode `--host` to `0.0.0.0` | Drop `--host`; `--start` binds `127.0.0.1` |
+| better-auth secret error at boot | Forced an install without a secret | The launcher persists `BETTER_AUTH_SECRET` — let it run, or set it |
+| A bare `constella` does nothing | A launch flag is now required | Relaunch with `--start` (or `--vps` / `--portable`) |
+
+---
+
+## Related links 🌌
+
+- [INSTALLATION](./INSTALLATION.md) · [ONBOARDING](./ONBOARDING.md) · [CONFIGURATION](./CONFIGURATION.md)
+- [VPS](./VPS_MODE.md) · [PORTABLE](./PORTABLE_MODE.md)
+- [ARCHITECTURE](./ARCHITECTURE.md) · [AI_ARCHITECTURE](./AI_ARCHITECTURE.md) · [AGENTS](./AGENTS.md)
+- [SECURITY](./SECURITY.md) · [UPDATE](./UPDATE.md) · [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [FAQ](./FAQ.md)
+</content>
+</invoke>