Docs split Phase 1: docs.roboco.tech becomes canonical — redirect stubs, user tree removed, MkDocs retired (#299)

* docs: replace MkDocs deploy with static redirect stubs docs.roboco.tech (roboco-website) is now the canonical user-facing docs site (spec: docs/internal/specs/2026-07-03-docs-site-split.md). Every URL this repo's Pages site published needs to keep resolving, so scripts/gen_docs_redirects.py generates one meta-refresh + rel=canonical stub per page — derived from mkdocs.yml's nav while it still lists every page — into the committed docs-redirects/ directory. All 58 stub targets verify against the website repo's nav.ts (0 unmapped); the only rename is how-to/* -> tour/* per the spec's slug map. Rewrite .github/workflows/docs.yml to deploy docs-redirects/ directly instead of running `mkdocs build`. The user-facing docs/ tree and mkdocs.yml itself are untouched here — deleting them is the next step, gated on these stubs resolving correctly. * docs: delete the MkDocs user-facing tree, docs.roboco.tech is canonical Per docs/internal/specs/2026-07-03-docs-site-split.md decision (1): Material->MDX is not verbatim-portable, so repo A's user-facing docs are deleted rather than kept as a permanently-drifting mirror. Deletes index/get-started/company/how-to/panel/models/operations/optional/deploy/ api/troubleshooting plus images/videos/assets. KEEPS docs/rag/ (indexed agent corpus), docs/map/, docs/internal/, and the team buckets (backend/frontend/ux_ui) — none of these were ever in mkdocs.yml's nav. mkdocs.yml's entire nav mapped 1:1 onto the deleted tree, so pruning it "accordingly" leaves nothing — remove it outright, along with the now-dead `docs` optional-dependency group (mkdocs/mkdocs-material/mkdocstrings/ pymarkdownlnt — mkdocstrings was already unused, not wired into any mkdocs plugin), the matching deptry DEP002 ignore entries, .pymarkdown.json, and the serve-docs/build-docs/lint-docs/fix-docs Makefile targets (all scoped only to the deleted paths). Add regen-docs-redirects as the one remaining docs Makefile target. Repointed everything that linked into the deleted tree or the old Pages URL: README's hero video/gif and walkthrough links now hit the docs.roboco.tech-hosted copies (already duplicated there per the spec's ground truth), usage.md / deployment.md's jump-links, pyproject's Documentation URL, and CLAUDE.md's Blueprint Reference paragraph. * chore: sync uv.lock after removing the docs optional-dependency group Follow-up to the mkdocs.yml / docs extra removal — mkdocs, mkdocs-material, mkdocstrings, pymarkdownlnt, and their transitive-only dependencies drop out of the lockfile now that nothing in pyproject.toml declares them. --------- Co-authored-by: Renn F <rennf93@users.noreply.github.com>
2026-08-03 07:23:24 +02:00 · 2026-07-03 02:04:59 +02:00
parent 876e19b389
commit 5936c2bdea
158 changed files with 917 additions and 4473 deletions
@@ -1,7 +1,16 @@
-# Builds the MkDocs site and deploys it with GitHub's official Pages Actions
-# flow (build once -> upload artifact -> deploy). This avoids the gh-pages
-# branch entirely, so there is no force-push race and the custom domain set in
-# Settings persists across deploys.
+# Docs-site split Phase 1 (docs/internal/specs/2026-07-03-docs-site-split.md):
+# docs.roboco.tech (the roboco-website repo) is now the canonical user-facing
+# docs site, so this workflow no longer builds MkDocs. It deploys the
+# already-generated, already-committed `docs-redirects/` directory — one
+# meta-refresh + rel=canonical stub per URL this repo's Pages site used to
+# publish, pointing at the docs.roboco.tech equivalent — with GitHub's
+# official Pages Actions flow (upload artifact -> deploy). No force-push
+# race, and the custom domain set in Settings persists across deploys.
+#
+# `docs-redirects/` was generated once by scripts/gen_docs_redirects.py while
+# mkdocs.yml still listed every published page; that script is not re-run
+# here. Regenerating it (e.g. to add a redirect) means re-running the script
+# against a restored copy of the old nav and committing the new output.
 #
 # One-time setup: Settings -> Pages -> Source = "GitHub Actions".
 name: docs
@@ -10,8 +19,7 @@ on:
  push:
    branches: [master]
    paths:
-      - "docs/**"
-      - "mkdocs.yml"
+      - "docs-redirects/**"
      - ".github/workflows/docs.yml"
  workflow_dispatch:

@@ -30,16 +38,10 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
-      - name: Install uv
-        uses: astral-sh/setup-uv@v7
-      - name: Build the site (strict)
-        run: |
-          uv sync --extra docs
-          uv run mkdocs build --strict
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v5
        with:
-          path: site
+          path: docs-redirects

  deploy:
    needs: build
@@ -1,16 +0,0 @@
-{
-  "extensions": {
-    "front-matter": { "enabled": true }
-  },
-  "plugins": {
-    "md013": { "enabled": false },
-    "md033": { "enabled": false },
-    "md007": { "enabled": false },
-    "md030": { "enabled": false },
-    "md032": { "enabled": false },
-    "md041": { "enabled": false },
-    "md046": { "enabled": false },
-    "md025": { "enabled": false },
-    "md036": { "enabled": false }
-  }
-}
@@ -571,4 +571,4 @@ ROBOCO_OLLAMA_BASE_URL=http://roboco-ollama:11434          # Native API

 ## Blueprint Reference

-The organizational structure, communication matrix, role descriptions, and access-control model are documented inline above and in the user-facing documentation site (MkDocs Material; source under `docs/`, built by `mkdocs.yml`, deployed by `.github/workflows/docs.yml` via GitHub Pages Actions and served at rennf93.github.io/roboco). `docs/rag/` remains the agent-facing RAG corpus (excluded from the published site); the old root `usage.md` / `deployment.md` are now redirect stubs into the site.
+The organizational structure, communication matrix, role descriptions, and access-control model are documented inline above and in the user-facing documentation site at **[docs.roboco.tech](https://docs.roboco.tech)** (the `roboco-website` repo — Next.js MDX, the canonical docs site as of the 2026-07-03 docs-site split: `docs/internal/specs/2026-07-03-docs-site-split.md`). This repo's old MkDocs-built user tree is gone; `.github/workflows/docs.yml` now only deploys the committed `docs-redirects/` stubs (meta-refresh + canonical) so every URL the old Pages site published keeps resolving, to docs.roboco.tech. `docs/rag/` remains the agent-facing RAG corpus (never published); `docs/map/` is the agent-facing exhaustive codebase map; `docs/internal/` holds specs and working notes; the old root `usage.md` / `deployment.md` now link straight to docs.roboco.tech.
@@ -428,29 +428,13 @@ high-load-stress-test:
 	@docker compose down --rmi all --remove-orphans -v
 	@docker system prune -f

-# Serve docs
-.PHONY: serve-docs
-serve-docs:
-	@uv run --extra docs mkdocs serve
-	@find . | grep -E "(__pycache__|\.pyc|\.pyo|\.pytest_cache|\.ruff_cache|\.mypy_cache)" | xargs rm -rf
-
-# Build the documentation site (strict — fails on broken links / nav)
-.PHONY: build-docs
-build-docs:
-	@uv run --extra docs mkdocs build --strict
-	@find . | grep -E "(__pycache__|\.pyc|\.pyo|\.pytest_cache|\.ruff_cache|\.mypy_cache)" | xargs rm -rf
-
-# Lint documentation
-.PHONY: lint-docs
-lint-docs:
-	@uv run --extra docs pymarkdownlnt --config .pymarkdown.json scan -r docs/index.md docs/get-started docs/company docs/how-to docs/panel docs/models docs/operations docs/optional docs/deploy docs/api docs/troubleshooting
-	@find . | grep -E "(__pycache__|\.pyc|\.pyo|\.pytest_cache|\.ruff_cache|\.mypy_cache)" | xargs rm -rf
-
-# Fix documentation
-.PHONY: fix-docs
-fix-docs:
-	@uv run --extra docs pymarkdownlnt --config .pymarkdown.json fix -r docs/index.md docs/get-started docs/company docs/how-to docs/panel docs/models docs/operations docs/optional docs/deploy docs/api docs/troubleshooting
-	@find . | grep -E "(__pycache__|\.pyc|\.pyo|\.pytest_cache|\.ruff_cache|\.mypy_cache)" | xargs rm -rf
+# Regenerate the GitHub Pages redirect stubs (docs-redirects/) that replaced
+# the old MkDocs-built site — docs.roboco.tech is canonical now. Only needed
+# if a legacy URL is missing a stub; requires a restored copy of the old
+# nav-bearing mkdocs.yml (see git history) since the live one is gone.
+.PHONY: regen-docs-redirects
+regen-docs-redirects:
+	@uv run python scripts/gen_docs_redirects.py

 # Prune
 .PHONY: prune
@@ -514,16 +498,12 @@ help:
 	@echo "  make test-all                 - Run tests (all Python versions)"
 	@echo "  make stress-test              - Run stress test"
 	@echo ""
-	@echo "Documentation:"
-	@echo "  make serve-docs               - Serve documentation"
-	@echo "  make lint-docs                - Lint markdown files"
-	@echo ""
 	@echo "Cleanup:"
 	@echo "  make stop                     - Stop all containers"
 	@echo "  make clean                    - Clean cache files"
 	@echo "  make prune                    - Prune docker resources"
 	@echo ""
-	@echo "Full docs: https://rennf93.github.io/roboco/  (preview locally: make serve-docs)"
+	@echo "Full docs: https://docs.roboco.tech"

 # Python versions list
 .PHONY: show-python-versions
@@ -22,9 +22,9 @@ AI Agents Company - A virtual organization of 25 AI agents + 1 human CEO, design
 </table>

 <p align="center">
-  <img src="docs/videos/panel-teaser.gif" alt="Twelve-second looping preview of the RoboCo control panel — the org tree, a task in progress, and an approval queue." width="80%">
+  <img src="https://docs.roboco.tech/docs/videos/panel-teaser.gif" alt="Twelve-second looping preview of the RoboCo control panel — the org tree, a task in progress, and an approval queue." width="80%">
  <br>
-  <sub><a href="docs/videos/panel-full-walkthrough.mp4">Watch the full 2:33 walkthrough (.mp4) →</a></sub>
+  <sub><a href="https://docs.roboco.tech/docs/videos/panel-full-walkthrough.mp4">Watch the full 2:33 walkthrough (.mp4) →</a></sub>
 </p>

 > [!WARNING]
@@ -73,9 +73,9 @@ One full loop, put simply:

 **— Full circle —**

-**[See the full walkthrough, with screenshots →](docs/how-to/README.md)**
+**[See the full walkthrough, with screenshots →](https://docs.roboco.tech/docs/tour)**

-**[Or watch the full panel walkthrough (video) →](docs/videos/panel-full-walkthrough.mp4)**
+**[Or watch the full panel walkthrough (video) →](https://docs.roboco.tech/docs/videos/panel-full-walkthrough.mp4)**

 ## Project Structure

@@ -100,8 +100,8 @@ roboco/
 ├── agents/
 │   └── prompts/                 # Agent system prompts (roles, teams, identities)
 ├── docs/
-│   ├── how-to/                 # Visual walkthrough — 5-chapter guide (start at README.md)
-│   └── rag/                     # Agent knowledge base (indexed into RAG)
+│   ├── rag/                     # Agent knowledge base (indexed into RAG)
+│   └── map/                     # Exhaustive codebase map (agent-facing)
 ├── alembic/                     # Database migrations
 ├── CLAUDE.md                    # Claude Code guidance
 ├── docker-compose.yml           # Full stack, built from source
@@ -1,13 +1,11 @@
 # RoboCo Deployment Guide

-> **This guide has moved.** Deploying RoboCo is now documented in the full docs site at **[rennf93.github.io/roboco](https://rennf93.github.io/roboco/)** (source under [`docs/`](docs/)).
+> **This guide has moved.** Deploying RoboCo is now documented in the full docs site at **[docs.roboco.tech](https://docs.roboco.tech)**.

 Jump straight to:

- **[Install & first run](docs/get-started/installation.md)** — the quickest path: clone, set two secrets, `docker compose up`.
- **[Deployment](docs/deploy/deployment.md)** — the production guide: compose files, the single-origin nginx, host-path mounts, data persistence, secure mode, and startup ordering.
- **[Environment reference](docs/deploy/env-reference.md)** — every `ROBOCO_*` setting with its default and purpose.
- **[Data & migrations](docs/deploy/data-and-migrations.md)** — the schema, pgvector, and how the stack self-migrates.
- **[Troubleshooting](docs/troubleshooting/common-issues.md)** — the common deploy snags and their fixes.
-
-Preview the site locally with `make serve-docs`.
+- **[Install & first run](https://docs.roboco.tech/docs/get-started/installation)** — the quickest path: clone, set two secrets, `docker compose up`.
+- **[Deployment](https://docs.roboco.tech/docs/deploy/deployment)** — the production guide: compose files, the single-origin nginx, host-path mounts, data persistence, secure mode, and startup ordering.
+- **[Environment reference](https://docs.roboco.tech/docs/deploy/env-reference)** — every `ROBOCO_*` setting with its default and purpose.
+- **[Data & migrations](https://docs.roboco.tech/docs/deploy/data-and-migrations)** — the schema, pgvector, and how the stack self-migrates.
+- **[Troubleshooting](https://docs.roboco.tech/docs/troubleshooting/common-issues)** — the common deploy snags and their fixes.
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Authentication</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/api/auth">
+<link rel="canonical" href="https://docs.roboco.tech/docs/api/auth">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/api/auth">https://docs.roboco.tech/docs/api/auth</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>API Reference</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/api">
+<link rel="canonical" href="https://docs.roboco.tech/docs/api">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/api">https://docs.roboco.tech/docs/api</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>REST API</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/api/rest-api">
+<link rel="canonical" href="https://docs.roboco.tech/docs/api/rest-api">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/api/rest-api">https://docs.roboco.tech/docs/api/rest-api</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>WebSocket streams</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/api/websockets">
+<link rel="canonical" href="https://docs.roboco.tech/docs/api/websockets">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/api/websockets">https://docs.roboco.tech/docs/api/websockets</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>How agents are sandboxed</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/company/agent-gateway">
+<link rel="canonical" href="https://docs.roboco.tech/docs/company/agent-gateway">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/company/agent-gateway">https://docs.roboco.tech/docs/company/agent-gateway</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>The Company</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/company">
+<link rel="canonical" href="https://docs.roboco.tech/docs/company">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/company">https://docs.roboco.tech/docs/company</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>MegaTask — batched, sequenced work</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/company/megatask">
+<link rel="canonical" href="https://docs.roboco.tech/docs/company/megatask">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/company/megatask">https://docs.roboco.tech/docs/company/megatask</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>The merge model</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/company/merge-model">
+<link rel="canonical" href="https://docs.roboco.tech/docs/company/merge-model">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/company/merge-model">https://docs.roboco.tech/docs/company/merge-model</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Org & roles</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/company/org-and-roles">
+<link rel="canonical" href="https://docs.roboco.tech/docs/company/org-and-roles">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/company/org-and-roles">https://docs.roboco.tech/docs/company/org-and-roles</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>The task lifecycle</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/company/task-lifecycle">
+<link rel="canonical" href="https://docs.roboco.tech/docs/company/task-lifecycle">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/company/task-lifecycle">https://docs.roboco.tech/docs/company/task-lifecycle</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Bootstrap & seeds</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/deploy/bootstrap-and-seeds">
+<link rel="canonical" href="https://docs.roboco.tech/docs/deploy/bootstrap-and-seeds">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/deploy/bootstrap-and-seeds">https://docs.roboco.tech/docs/deploy/bootstrap-and-seeds</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Data & migrations</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/deploy/data-and-migrations">
+<link rel="canonical" href="https://docs.roboco.tech/docs/deploy/data-and-migrations">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/deploy/data-and-migrations">https://docs.roboco.tech/docs/deploy/data-and-migrations</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Deployment</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/deploy/deployment">
+<link rel="canonical" href="https://docs.roboco.tech/docs/deploy/deployment">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/deploy/deployment">https://docs.roboco.tech/docs/deploy/deployment</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Environment reference</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/deploy/env-reference">
+<link rel="canonical" href="https://docs.roboco.tech/docs/deploy/env-reference">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/deploy/env-reference">https://docs.roboco.tech/docs/deploy/env-reference</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Configure & Deploy</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/deploy">
+<link rel="canonical" href="https://docs.roboco.tech/docs/deploy">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/deploy">https://docs.roboco.tech/docs/deploy</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Register your first project</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/get-started/first-project">
+<link rel="canonical" href="https://docs.roboco.tech/docs/get-started/first-project">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/get-started/first-project">https://docs.roboco.tech/docs/get-started/first-project</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Your first task</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/get-started/first-task">
+<link rel="canonical" href="https://docs.roboco.tech/docs/get-started/first-task">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/get-started/first-task">https://docs.roboco.tech/docs/get-started/first-task</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Get Started</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/get-started">
+<link rel="canonical" href="https://docs.roboco.tech/docs/get-started">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/get-started">https://docs.roboco.tech/docs/get-started</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Install & first run</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/get-started/installation">
+<link rel="canonical" href="https://docs.roboco.tech/docs/get-started/installation">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/get-started/installation">https://docs.roboco.tech/docs/get-started/installation</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>The shape of the company</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/tour/01-the-company">
+<link rel="canonical" href="https://docs.roboco.tech/docs/tour/01-the-company">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/tour/01-the-company">https://docs.roboco.tech/docs/tour/01-the-company</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>It starts with you</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/tour/02-it-starts-with-you">
+<link rel="canonical" href="https://docs.roboco.tech/docs/tour/02-it-starts-with-you">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/tour/02-it-starts-with-you">https://docs.roboco.tech/docs/tour/02-it-starts-with-you</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>The cells build it</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/tour/03-the-cells-build-it">
+<link rel="canonical" href="https://docs.roboco.tech/docs/tour/03-the-cells-build-it">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/tour/03-the-cells-build-it">https://docs.roboco.tech/docs/tour/03-the-cells-build-it</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>The last call — and the loop</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/tour/04-the-last-call-and-the-loop">
+<link rel="canonical" href="https://docs.roboco.tech/docs/tour/04-the-last-call-and-the-loop">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/tour/04-the-last-call-and-the-loop">https://docs.roboco.tech/docs/tour/04-the-last-call-and-the-loop</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>The business workflow</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/tour/05-the-business-workflow">
+<link rel="canonical" href="https://docs.roboco.tech/docs/tour/05-the-business-workflow">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/tour/05-the-business-workflow">https://docs.roboco.tech/docs/tour/05-the-business-workflow</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>The Tour</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/tour">
+<link rel="canonical" href="https://docs.roboco.tech/docs/tour">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/tour">https://docs.roboco.tech/docs/tour</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Home</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs">
+<link rel="canonical" href="https://docs.roboco.tech/docs">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs">https://docs.roboco.tech/docs</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Running on Grok</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/models/grok">
+<link rel="canonical" href="https://docs.roboco.tech/docs/models/grok">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/models/grok">https://docs.roboco.tech/docs/models/grok</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Choosing & Running Models</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/models">
+<link rel="canonical" href="https://docs.roboco.tech/docs/models">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/models">https://docs.roboco.tech/docs/models</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Provider routing</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/models/provider-routing">
+<link rel="canonical" href="https://docs.roboco.tech/docs/models/provider-routing">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/models/provider-routing">https://docs.roboco.tech/docs/models/provider-routing</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Resilience</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/models/resilience">
+<link rel="canonical" href="https://docs.roboco.tech/docs/models/resilience">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/models/resilience">https://docs.roboco.tech/docs/models/resilience</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Cost & usage</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/operations/cost-and-usage">
+<link rel="canonical" href="https://docs.roboco.tech/docs/operations/cost-and-usage">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/operations/cost-and-usage">https://docs.roboco.tech/docs/operations/cost-and-usage</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Health & metrics</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/operations/health-and-metrics">
+<link rel="canonical" href="https://docs.roboco.tech/docs/operations/health-and-metrics">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/operations/health-and-metrics">https://docs.roboco.tech/docs/operations/health-and-metrics</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Cost & Observability</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/operations">
+<link rel="canonical" href="https://docs.roboco.tech/docs/operations">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/operations">https://docs.roboco.tech/docs/operations</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Autonomous maintenance</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/optional/autonomous-maintenance">
+<link rel="canonical" href="https://docs.roboco.tech/docs/optional/autonomous-maintenance">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/optional/autonomous-maintenance">https://docs.roboco.tech/docs/optional/autonomous-maintenance</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Architectural Conventions</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/optional/conventions">
+<link rel="canonical" href="https://docs.roboco.tech/docs/optional/conventions">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/optional/conventions">https://docs.roboco.tech/docs/optional/conventions</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>HTTP security (fastapi-guard)</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/optional/http-security">
+<link rel="canonical" href="https://docs.roboco.tech/docs/optional/http-security">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/optional/http-security">https://docs.roboco.tech/docs/optional/http-security</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Optional Subsystems</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/optional">
+<link rel="canonical" href="https://docs.roboco.tech/docs/optional">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/optional">https://docs.roboco.tech/docs/optional</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Pitch provisioning</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/optional/pitch-provisioning">
+<link rel="canonical" href="https://docs.roboco.tech/docs/optional/pitch-provisioning">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/optional/pitch-provisioning">https://docs.roboco.tech/docs/optional/pitch-provisioning</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>External / internal PR review</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/optional/pr-review">
+<link rel="canonical" href="https://docs.roboco.tech/docs/optional/pr-review">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/optional/pr-review">https://docs.roboco.tech/docs/optional/pr-review</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Self-healing CI</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/optional/self-heal">
+<link rel="canonical" href="https://docs.roboco.tech/docs/optional/self-heal">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/optional/self-heal">https://docs.roboco.tech/docs/optional/self-heal</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Strategy engine</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/optional/strategy-engine">
+<link rel="canonical" href="https://docs.roboco.tech/docs/optional/strategy-engine">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/optional/strategy-engine">https://docs.roboco.tech/docs/optional/strategy-engine</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Toolchain matching</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/optional/toolchain-matching">
+<link rel="canonical" href="https://docs.roboco.tech/docs/optional/toolchain-matching">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/optional/toolchain-matching">https://docs.roboco.tech/docs/optional/toolchain-matching</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Web research</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/optional/web-research">
+<link rel="canonical" href="https://docs.roboco.tech/docs/optional/web-research">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/optional/web-research">https://docs.roboco.tech/docs/optional/web-research</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Agents & Work Sessions</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/panel/agents-and-work-sessions">
+<link rel="canonical" href="https://docs.roboco.tech/docs/panel/agents-and-work-sessions">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/panel/agents-and-work-sessions">https://docs.roboco.tech/docs/panel/agents-and-work-sessions</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Auditor</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/panel/auditor">
+<link rel="canonical" href="https://docs.roboco.tech/docs/panel/auditor">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/panel/auditor">https://docs.roboco.tech/docs/panel/auditor</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Business</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/panel/business">
+<link rel="canonical" href="https://docs.roboco.tech/docs/panel/business">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/panel/business">https://docs.roboco.tech/docs/panel/business</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Command Center</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/panel/command-center">
+<link rel="canonical" href="https://docs.roboco.tech/docs/panel/command-center">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/panel/command-center">https://docs.roboco.tech/docs/panel/command-center</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Communications & Journals</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/panel/communications-and-journals">
+<link rel="canonical" href="https://docs.roboco.tech/docs/panel/communications-and-journals">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/panel/communications-and-journals">https://docs.roboco.tech/docs/panel/communications-and-journals</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Git</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/panel/git">
+<link rel="canonical" href="https://docs.roboco.tech/docs/panel/git">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/panel/git">https://docs.roboco.tech/docs/panel/git</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Operating the Panel</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/panel">
+<link rel="canonical" href="https://docs.roboco.tech/docs/panel">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/panel">https://docs.roboco.tech/docs/panel</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Knowledge Base</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/panel/knowledge-base">
+<link rel="canonical" href="https://docs.roboco.tech/docs/panel/knowledge-base">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/panel/knowledge-base">https://docs.roboco.tech/docs/panel/knowledge-base</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Metrics</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/panel/metrics">
+<link rel="canonical" href="https://docs.roboco.tech/docs/panel/metrics">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/panel/metrics">https://docs.roboco.tech/docs/panel/metrics</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Projects & Products</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/panel/projects-and-products">
+<link rel="canonical" href="https://docs.roboco.tech/docs/panel/projects-and-products">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/panel/projects-and-products">https://docs.roboco.tech/docs/panel/projects-and-products</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Settings</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/panel/settings">
+<link rel="canonical" href="https://docs.roboco.tech/docs/panel/settings">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/panel/settings">https://docs.roboco.tech/docs/panel/settings</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Tasks & Kanban</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/panel/tasks-and-kanban">
+<link rel="canonical" href="https://docs.roboco.tech/docs/panel/tasks-and-kanban">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/panel/tasks-and-kanban">https://docs.roboco.tech/docs/panel/tasks-and-kanban</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Common issues</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/troubleshooting/common-issues">
+<link rel="canonical" href="https://docs.roboco.tech/docs/troubleshooting/common-issues">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/troubleshooting/common-issues">https://docs.roboco.tech/docs/troubleshooting/common-issues</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Troubleshooting & Security</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/troubleshooting">
+<link rel="canonical" href="https://docs.roboco.tech/docs/troubleshooting">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/troubleshooting">https://docs.roboco.tech/docs/troubleshooting</a>.</p>
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Security</title>
+<meta http-equiv="refresh" content="0; url=https://docs.roboco.tech/docs/troubleshooting/security">
+<link rel="canonical" href="https://docs.roboco.tech/docs/troubleshooting/security">
+</head>
+<body>
+<p>This page has moved to <a href="https://docs.roboco.tech/docs/troubleshooting/security">https://docs.roboco.tech/docs/troubleshooting/security</a>.</p>
+</body>
+</html>
@@ -1,63 +0,0 @@
-# Authentication
-
-RoboCo's API identifies a caller by a small set of headers — `X-Agent-ID`, `X-Agent-Role`, and optionally `X-Agent-Team`. How much it *trusts* those headers depends on one flag. Out of the box the API runs in header-trust mode, which is fine on a private LAN and dangerous anywhere else. This page covers both modes and the WebSocket caveat.
-
-## The identity headers
-
-Every REST request carries:
-
-| Header | Required | Meaning |
-|--------|----------|---------|
-| `X-Agent-ID` | Yes | The agent's UUID or slug (e.g. `be-dev-1`). |
-| `X-Agent-Role` | Yes | The role the caller is acting as (e.g. `developer`, `cell_pm`, `ceo`). |
-| `X-Agent-Team` | No | The team (`backend`, `frontend`, `uxui`), when relevant. |
-| `X-Agent-Token` | Only in secure mode | The HMAC token that proves the headers above weren't forged. |
-
-These are resolved in `roboco/api/deps.py` (`get_agent_context`), and the role gates the action — so a request claiming `X-Agent-Role: ceo` can do CEO-only things like approving and merging.
-
-## Header-trust mode (default)
-
-By default `ROBOCO_AGENT_AUTH_REQUIRED` is unset/false. In this mode the API **accepts the role headers without verifying any token**. There is no proof of identity: whoever sets `X-Agent-Role: ceo` *is* the CEO for that request.
-
-!!! danger "Anyone who can reach the API can claim any role — including CEO"
-    In header-trust mode there is no authentication. Any client that can open a connection to the orchestrator port can act as any agent, approve and merge work as the CEO, cancel tasks, or override task state. The app logs a loud startup warning to this effect. This is acceptable **only** on a trusted private network where nothing untrusted can reach the orchestrator — which is the default single-host LAN deployment behind nginx on `localhost:3000`. Do not expose the orchestrator to anything you don't control without first turning on secure mode.
-
-## Secure mode (HMAC tokens)
-
-Set `ROBOCO_AGENT_AUTH_REQUIRED=true` to require a signed token on every REST request. In this mode:
-
- `X-Agent-Token` becomes mandatory; a request without it is rejected with **401**.
- The token is an HMAC signed with `ROBOCO_AGENT_AUTH_SECRET` and **bound to the agent's id, role, and team**. The server recomputes the signature over the presented `X-Agent-ID` / `X-Agent-Role` / `X-Agent-Team` and compares it constant-time. If a caller swaps the role header to escalate to `ceo`, the signature no longer matches and the request is rejected with **401 — signature mismatch**.
- The orchestrator issues each agent its token at spawn time, so delivery agents are authenticated by construction.
- A presented token is **always** verified, even when auth isn't required — so you can roll out tokens before flipping the switch without breaking anything.
-
-| Flag | Default | Purpose |
-|------|---------|---------|
-| `ROBOCO_AGENT_AUTH_REQUIRED` | `false` | When `true`, REST requires a valid HMAC `X-Agent-Token`. |
-| `ROBOCO_AGENT_AUTH_SECRET` | (unset) | Shared secret the orchestrator uses to sign and the API uses to verify the per-agent token. |
-
-!!! tip "How the panel authenticates as the CEO"
-    The control panel acts as the CEO agent. In secure mode, nginx injects the panel's CEO `X-Agent-Token` so your browser session is authenticated without you handling the secret — you just use the panel as normal.
-
-## The WebSocket + live-chat streams
-
-Secure mode extends beyond REST. When `ROBOCO_AGENT_AUTH_REQUIRED=true`:
-
- The **per-resource WebSocket streams** (`/ws/channels|agents|sessions|notifications/{id}`) require the **CEO panel token** — the same signed `X-Agent-Token` nginx injects for the panel. An agent on the Docker network can no longer subscribe to another agent's notifications with no auth. They still validate `agent_id`/`viewer_id` against the DB and channel access on top.
- The **`/api/v1/do/*` content routes** require a valid per-agent HMAC token bound to `X-Agent-ID` (the do router serves every role, so the gate is token-only, not role-specific).
- The **live-chat bridges** (`/prompter/live/*`, `/secretary/live/*`) — the prompter/secretary intake chats — require the CEO panel token on their start/stream/status/messages/stop endpoints. They were the last panel-facing API surface that ran unauthenticated.
- **`/ws/system`** stays operator-only and read-only by design (it carries system telemetry and accepts nothing from the client); it is not token-gated.
-
-A presented-but-forged token is rejected even in dev (header-trust) mode, so you can roll out tokens before flipping the switch without breaking anything. The container→relay internal callback is left ungated by design (internal Docker network, opaque session id).
-
-## What to do
-
- **Single-host LAN, nothing untrusted on the network** → header-trust is fine; that's the default.
- **Anything reachable beyond a trusted LAN** → set `ROBOCO_AGENT_AUTH_REQUIRED=true` and a strong `ROBOCO_AGENT_AUTH_SECRET`, and keep the orchestrator port off the public internet regardless.
-
-For the full hardening checklist — network exposure, the GitHub PAT handling, and the prompt/bash guards — see [Security](../troubleshooting/security.md).
-
-## Next
-
- [REST API](./rest-api.md) — the route surface these headers authorize.
- [WebSockets](./websockets.md) — the live streams and their separate auth model.
@@ -1,25 +0,0 @@
-# API Reference
-
-RoboCo is API-first: the control panel is just a client of the same REST and WebSocket surface you can drive yourself. This section is for integrators and the curious; the live, always-current schema is at **`/docs`** (Swagger UI) and **`/redoc`** on the orchestrator.
-
-<div class="grid cards" markdown>
-
-   **[REST API](rest-api.md)**
-
-    ---
-
-    The `/api` domain routes, the agent gateway verbs, the error envelope, and where to find the live OpenAPI.
-
-   **[WebSocket streams](websockets.md)**
-
-    ---
-
-    The `/ws` live streams the panel consumes — per-resource feeds and the operator system stream.
-
-   **[Authentication](auth.md)**
-
-    ---
-
-    Header-trust mode versus secure token mode, and how the panel stays authenticated.
-
-</div>
@@ -1,119 +0,0 @@
-# REST API
-
-RoboCo's backend is a single FastAPI application (`roboco/api/app.py`, one `create_app()` factory). It mounts every domain router under the `/api` prefix, the agent-gateway intent verbs under `/api/v1`, and the live WebSocket streams under `/ws`. Everything is fronted by nginx on `localhost:3000`, so the panel and any integrator use relative URLs (`/api/...`, `/ws/...`) against one origin with no CORS to configure.
-
-!!! tip "The live OpenAPI docs are the source of truth"
-    The fastest way to see the full, current REST surface — every path, request body, and response schema — is the interactive docs the app serves itself:
-
-    - **Swagger UI** → [`http://localhost:3000/docs`](http://localhost:3000/docs)
-    - **ReDoc** → [`http://localhost:3000/redoc`](http://localhost:3000/redoc)
-
-    This page is a map of *where things live*; `/docs` is the authoritative reference for *exactly how to call them*.
-
-## The two prefixes
-
-There are two distinct API surfaces, and the prefix tells you which one you're on:
-
-| Prefix | Audience | What it is |
-|--------|----------|------------|
-| `/api/*` | You / the panel / integrators | The domain REST surface — tasks, agents, projects, git, usage, settings, and the rest. This is what the control panel calls. |
-| `/api/v1/flow/{role}/{verb}` and `/api/v1/do` | AI agents only | The [agent gateway](../company/agent-gateway.md). Agents never call the domain routes above — they POST intent verbs here through their MCP servers, and the server-side Choreographer enforces state, locks, and evidence. |
-
-Health and readiness probes sit at the root, not under `/api`: `GET /health` and `GET /ready`.
-
-## Domain route groups (`/api/*`)
-
-Every router is mounted under `/api`. The groups an operator or integrator hits:
-
-| Route group | Prefix | Purpose |
-|-------------|--------|---------|
-| Tasks | `/api/tasks` | The largest router: full task CRUD and lifecycle transitions (claim, submit, pass/fail, complete, escalate). The CEO god-mode override (`PATCH /api/tasks/{id}` with `X-Agent-Role: ceo`) lives here. |
-| Kanban | `/api/kanban` | Board view of tasks grouped by state. |
-| Agents | `/api/agents` | Agent roster, roles, teams, current state. |
-| Work sessions | `/api/work-sessions` | Git session records — branch, commits, files, PR. |
-| Projects | `/api/projects` | Repository config, CI/quality commands, git-token management. |
-| Products | `/api/products` | Product entities + CEO approve-and-start / cell-routing. |
-| Sessions | `/api/sessions` | Communication sessions and their messages. |
-| Channels | `/api/channels` | Team channels. |
-| Groups | `/api/groups` | Agent/channel grouping. |
-| Messages | `/api/messages` | Extracted messages from agent streams. |
-| Notifications | `/api/notifications` | Formal ack-required notifications. |
-| Stream | `/api/stream` | Agent output stream access. |
-| Journals | `/api/journals` | Agent journals and entries. |
-| Optimal | `/api/optimal` | RAG queries (in-house pgvector engine). |
-| Git | `/api/git` | Git operations surfaced for the panel. |
-| Providers | `/api/providers` | Model-provider routing config. |
-| Orchestrator | `/api/orchestrator` | Agent-runtime control (spawn/stop, dispatcher state). |
-| Dashboard | `/api/dashboard` | Aggregated dashboard data. |
-| Usage | `/api/usage` | Token/cost analytics (`GET /api/usage/summary?period=24h\|7d\|30d`). |
-| System | `/api/system` | Rate-limit introspection (`GET /api/system/rate-limits`). |
-| Settings | `/api/settings` | App settings, including feature-flag persistence. |
-| Company goals | `/api/company-goals` | The company charter. |
-| Cockpit | `/api/cockpit` | CEO read-only business summary. |
-| Research | `/api/research` | Web-research subsystem (flag-gated). |
-| Pitches | `/api/pitches` | Pitch provisioning (flag-gated). |
-| Secretary | `/api/secretary` | Secretary chief-of-staff + its live-chat bridge. |
-| Prompter | `/api/prompter` | Intake interviewer live chat (SSE relay). |
-| Docs | `/api/docs` | Project documentation file management. |
-| A2A | `/api/a2a` | Agent-to-agent messaging plumbing. |
-
-!!! info "Health vs readiness"
-    `GET /health` is a liveness probe — it returns 200 once the app is up. `GET /ready` is a readiness probe — it checks PostgreSQL and Redis and returns a `degraded` payload if either is down. Wire your uptime monitor to `/ready` if you want it to react to a backing-store outage, `/health` if you only care that the process is alive. See [Health & metrics](../operations/health-and-metrics.md).
-
-## The agent gateway (`/api/v1`)
-
-Agents do not touch the domain routes. They go through the gateway, which exposes one POST endpoint per (role, verb) pair plus a shared content-tools endpoint:
-
-| Endpoint | Role |
-|----------|------|
-| `POST /api/v1/flow/developer/{verb}` | Developer |
-| `POST /api/v1/flow/qa/{verb}` | QA |
-| `POST /api/v1/flow/documenter/{verb}` | Documenter |
-| `POST /api/v1/flow/cell_pm/{verb}` | Cell PM |
-| `POST /api/v1/flow/main_pm/{verb}` | Main PM |
-| `POST /api/v1/flow/board/{verb}` | Board (Product Owner, Head of Marketing, Auditor) |
-| `POST /api/v1/flow/auditor/{verb}` | Auditor |
-| `POST /api/v1/flow/pr_reviewer/{verb}` | PR reviewer |
-| `POST /api/v1/do` | Content tools (`commit`, `note`, `say`, `dm`, `evidence`) for every role |
-
-The `roboco-flow` MCP server in each agent container is a thin shim: it reads the agent's spawn manifest, registers only the verbs that role may call, and POSTs each one here. The verb set per role and the structural sandboxing are documented in [How agents are sandboxed](../company/agent-gateway.md) — you generally won't call these endpoints yourself.
-
-## The error envelope
-
-Every gateway verb returns the same standardized **envelope** (`roboco/services/gateway/envelope.py`), so agents recover from a rejection instead of looping:
-
- **Success** carries `status`, `task_id`, `next` (the verb to call next), an optional `evidence` block, a `context_briefing`, and introspection fields (`current_state`, `valid_next_verbs`).
- **Error** carries an `error` flavor, a human `message`, a concrete `remediate` hint, and — for input gaps — a `missing` list and a `field_hints` answer-key.
-
-The error flavors:
-
-| `error` | Meaning |
-|---------|---------|
-| `tracing_gap` | A required tracing artifact (e.g. a commit, PR, or note) is missing. |
-| `incomplete_input` | A required input field was not supplied; `missing` + `field_hints` tell the agent exactly which. |
-| `invalid_state` | The verb isn't valid from the task's current state. |
-| `not_authorized` | The role isn't allowed to perform this action. |
-| `not_found` | The task or resource doesn't exist. |
-| `circuit_open` | The agent has hammered one failing verb too many times; the breaker points it at a graceful exit. |
-
-The domain routes (`/api/*`) use FastAPI's standard error model, with the exception-handler stack in `roboco/api/middleware.py` mapping domain and service errors to clean responses. Notably:
-
- A provider rate-limit error becomes **HTTP 429 with a `Retry-After` header**.
- A validation failure is a **422**, with a special remediation hint when an agent sends an 8-character short task id instead of a full UUID.
- Every response echoes back an `X-Correlation-ID` (and the request's `X-Response-Time-Ms`), so one id threads through the panel, the API, and the logs.
-
-## Quick checks
-
-```bash
-curl -s localhost:3000/health
-curl -s localhost:3000/ready
-curl -s localhost:3000/api/system/rate-limits
-curl -s 'localhost:3000/api/usage/summary?period=7d'
-open http://localhost:3000/docs
-```
-
-## Next
-
- [WebSockets](./websockets.md) — the live `/ws` streams the panel consumes.
- [Authentication](./auth.md) — header-trust vs. secure mode, and who can claim which role.
- [How agents are sandboxed](../company/agent-gateway.md) — the gateway, verbs, and envelope in depth.
@@ -1,66 +0,0 @@
-# WebSockets
-
-RoboCo pushes live updates over WebSocket endpoints under `/ws`, served by the orchestrator (`roboco/api/websocket.py`) and routed through nginx alongside the REST API. A single in-process `ConnectionManager` holds per-resource connection sets and broadcasts events to them. The panel consumes all of these through its `useWebSocket("/<endpoint>", …)` hook — you rarely connect to them directly, but they're the same streams an integrator can subscribe to.
-
-## The endpoints
-
-There are four per-resource streams plus one operator-wide stream:
-
-| Endpoint | Stream | Auth |
-|----------|--------|------|
-| `/ws/channels/{channel_id}` | Live messages in a team channel | `agent_id` query param, validated against the DB + channel access; **CEO panel token required in secure mode** |
-| `/ws/agents/{agent_id}` | An agent's output and lifecycle events | `viewer_id`/`agent_id` query param, validated against the DB; **CEO panel token required in secure mode** |
-| `/ws/sessions/{session_id}` | Messages in a communication session | `agent_id` query param, validated; **CEO panel token required in secure mode** |
-| `/ws/notifications/{agent_id}` | An agent's notifications | `agent_id` query param, validated; **CEO panel token required in secure mode** |
-| `/ws/system` | Operator/system-wide stream — no per-agent keying | **Unauthenticated, read-only** (operator-only by design; not token-gated) |
-
-All sockets support a `ping`/`pong` keepalive: send `{"type": "ping"}` and you'll get a `pong` back.
-
-!!! info "Secure mode now covers the per-agent streams"
-    When `ROBOCO_AGENT_AUTH_REQUIRED=true`, the four per-resource sockets require the **CEO panel token** (the signed `X-Agent-Token` nginx injects for the panel) on top of their `agent_id`/`viewer_id` DB validation — an agent on the Docker network can no longer subscribe to another agent's stream unauthenticated. `/ws/system` is intentionally left operator-only and read-only. A forged token is rejected even in dev mode. See [Authentication](./auth.md).
-
-## How events reach the sockets
-
-Server-side events are published to an in-process `StreamEventBus`. The bridge in `roboco/api/websocket_bridge.py` subscribes to it and registers a `_handle_*` forwarder per event type, mapping each `EventType` to the right socket broadcast.
-
-```mermaid
-flowchart LR
-    S[Service / orchestrator] -->|publish EventType| B[StreamEventBus]
-    B --> WB[websocket_bridge _handle_*]
-    WB --> R[/ws/channels, /ws/agents, /ws/sessions, /ws/notifications/]
-    WB --> SYS[/ws/system/]
-    R --> P[Panel useWebSocket hook]
-    SYS --> P
-```
-
-To add a new live event you define an `EventType`, publish it to the bus, add a `_handle_*` forwarder in `websocket_bridge`, and consume it on the panel via the same hook — you never stand up a parallel endpoint.
-
-## Event types
-
-| Event | Arrives on | What it carries |
-|-------|-----------|-----------------|
-| `RATE_LIMIT_HIT` | `/ws/system` | A provider just hit a rate limit / overload and was parked. Drives the panel's amber rate-limit banner. |
-| `RATE_LIMIT_LIFTED` | `/ws/system` | A parked provider recovered; queued work resumes. Clears the banner. |
-| `USAGE_SNAPSHOT` | `/ws/system` | A fresh token-usage/cost snapshot. Drives the live "Token Usage & Cost" dashboard. |
-| `NOTIFICATION_SENT` / `NOTIFICATION_ACKED` | `/ws/notifications/{agent_id}` | A notification was sent to or acknowledged by an agent. |
-| `MESSAGE_SENT` | `/ws/sessions/{session_id}` **and** `/ws/channels/{channel_id}` | A chat message was persisted. Forwarded as a `message.new` frame (carrying `message_id`, `agent_id`, `content`, `message_type`, `timestamp`) so the session transcript and channel view update live instead of waiting on a manual refresh. |
-| `SESSION_CREATED` / `SESSION_CLOSED` / `SESSION_TIMEOUT` | `/ws/sessions/{session_id}` | Communication-session lifecycle. |
-| `AGENT_SPAWNED` / `AGENT_STOPPED` / `AGENT_WAITING` / `AGENT_RESUMED` / `AGENT_ERROR` | `/ws/agents/{agent_id}` | Agent runtime lifecycle transitions. |
-
-Each forwarded message is a JSON object with a `type` field merged with the event's data. The `type` is the event-type name above, except the message forwarder, which sets `type: "message.new"` (the frame the panel's channel/session stream filters on).
-
-## REST fallbacks
-
-The two operator dashboards that ride `/ws/system` fall back to HTTP polling when the socket is down, so the panel keeps working without the stream:
-
-| Live event | HTTP fallback |
-|------------|---------------|
-| `RATE_LIMIT_HIT` / `RATE_LIMIT_LIFTED` | `GET /api/system/rate-limits` |
-| `USAGE_SNAPSHOT` | `GET /api/usage/summary?period=24h\|7d\|30d` |
-
-See [Cost & usage](../operations/cost-and-usage.md) and [Health & metrics](../operations/health-and-metrics.md) for what the panel does with these.
-
-## Next
-
- [REST API](./rest-api.md) — the `/api/*` route map and the error envelope.
- [Authentication](./auth.md) — the WebSocket-auth caveat in full.
@@ -1,52 +0,0 @@
-# How agents are sandboxed
-
-The most important thing to understand about trusting RoboCo with your repository: **agents never touch your API, your database, or a shell directly.** Every action an agent can take goes through a narrow, server-side gateway that only exposes the handful of verbs that agent's *role* is allowed to use. Capability is decided by role at spawn time — not by the model's good behavior.
-
-## Agents speak in verbs, not API calls
-
-Each agent container talks to RoboCo through two thin MCP servers, both backed by a single server-side component (the **Choreographer**) that composes the real services behind the scenes:
-
-| Server | What it exposes |
-|--------|-----------------|
-| `roboco-flow` | **Intent verbs** — the lifecycle actions: `give_me_work`, `i_will_work_on`, `open_pr`, `i_am_done`, `claim_review`, `pass_review`, `complete`, `submit_up`, `submit_root`, `pr_pass`, … |
-| `roboco-do` | **Content tools** — `commit`, `note`, `say`, `dm`, `evidence`. |
-
-Two more read-only servers give agents a read-only view of git (`status`, `log`, `diff`) and access to the knowledge base. That's the entire surface. There is no "run arbitrary SQL," no "call any endpoint," no general shell.
-
-## A role can only call its own verbs
-
-At spawn, every agent is handed a **manifest** listing exactly the verbs its role may call — and nothing else. The manifest is built from a server-side role configuration and mounted read-only into the container. The result is that the lifecycle's role rules aren't just policy, they're *unreachable code* for the wrong role:
-
- A **developer** can `give_me_work`, open a PR, mark itself done, and `sync_branch` (rebase its branch onto its base through the gate) — but there is no merge verb in its manifest.
- **QA** can claim a review and pass or fail it — but it has no `commit`. QA and Documenters also get `i_am_blocked` as their escape hatch when they're stuck.
- A **PR reviewer** can pass or fail an assembled PR and post its review on the PR — but it never gets agent chat verbs.
- The **Auditor** is restricted to leaving a private note and reading evidence; it cannot `say` or `dm`. It observes; it does not participate.
-
-So when [the lifecycle](task-lifecycle.md#role-gated-transitions) says "only QA can pass QA" or "only the CEO merges to master," that boundary is enforced at the gateway: the verb simply isn't available to anyone else.
-
-## Every action returns a structured envelope
-
-Agents don't guess at state. Every verb returns a standardized **envelope**:
-
- On success: `{ status, task_id, next, evidence?, context_briefing }` — where `next` tells the agent what to call next.
- On error: `{ error, message, remediate, missing }` — where `remediate` tells the agent exactly how to fix it and retry.
-
-That `next` / `remediate` contract is why agents move through the lifecycle reliably instead of flailing: the gateway leads them, step by step, and rejects anything out of order with an explanation rather than a crash.
-
-## The other guardrails
-
-A few more protections run by construction, the same way on every backend (Claude or Grok):
-
- **Claim-locking** serializes work, so two agents can't grab the same task or race a merge.
- **Content posts require an active claim.** `commit`, `note`, `say`, `dm`, and `evidence` on a specific task are refused unless the agent holds that task's active claim — an agent can't write to a task it hasn't locked.
- **Human-only roles are never spawned.** The CEO, the Intake (prompter), and the Secretary are human-driven, so `spawn_agent` structurally refuses them — a notification addressed to the CEO can never launch a CEO container that acts as the human. Intake and Secretary run through their own dedicated, guarded chat paths instead.
- **Notifications can't target human-only roles.** `notify` rejects the CEO/prompter/secretary as recipients — there is no agent acknowledgement path for them, so a notification to them is a no-op rather than a stuck ack.
- **The token never enters the container.** Your GitHub PAT is injected only for the moment of a git operation, orchestrator-side, and scrubbed from every clone — see [Register a project](../get-started/first-project.md#what-happens-under-the-hood).
- **A prompt-injection guard** screens task prompts, and a bash guard blocks credential-exfiltration and identity-forgery patterns.
- **Rate limits and overloads park, they don't crash-loop.** If a provider returns a 429 or a persistent overload, RoboCo *queues* that agent's work and probes for recovery instead of burning tokens retrying. You'll see an amber banner; the work resumes automatically when the provider does.
-
-The practical upshot for you as operator: the workforce is structurally constrained to do its job and only its job. You're not relying on twenty-five models all choosing to behave — you're relying on the fact that the misbehaving action isn't on the menu.
-
-## Next
-
-→ Watch it all in motion in [the Tour](../how-to/README.md), or head back to [the lifecycle](task-lifecycle.md).
@@ -1,35 +0,0 @@
-# The Company
-
-What keeps twenty-five agents from dissolving into noise is that RoboCo is relentlessly opinionated about *how* work happens. Everything is a task, no task moves without acceptance criteria, and every task walks the same strict, role-gated lifecycle — built, QA'd, documented, reviewed, approved. The structure is the point. It's what turns a roster of models into a company that actually ships.
-
-This section explains the machinery:
-
-<div class="grid cards" markdown>
-
-   **[Org & roles](org-and-roles.md)**
-
-    ---
-
-    The twenty-five agents, the three cells, the Board, and the chain of command you sit on top of.
-
-   **[The task lifecycle](task-lifecycle.md)**
-
-    ---
-
-    The fifteen states every task moves through, who owns each step, and how rejected work loops back.
-
-   **[The merge model](merge-model.md)**
-
-    ---
-
-    How work flows up a cell → root → master pull-request chain — and why only you ever touch `master`.
-
-   **[How agents are sandboxed](agent-gateway.md)**
-
-    ---
-
-    Agents never touch your API or your shell. They act only through a narrow set of role-scoped verbs.
-
-</div>
-
-If you'd rather see these ideas in motion than read about them, [the Tour](../how-to/README.md) follows one real feature through the whole company.
@@ -1,50 +0,0 @@
-# MegaTask
-
-Most of the time you describe one piece of work and RoboCo builds it. Sometimes you have **several** things you want done at once — and they aren't always in the same repository. A **MegaTask** lets you describe the whole set in a single intake chat and hand it off as one batch that the company sequences and builds for you.
-
-The motivating example: you want to ship a change to a SaaS app, the open-source core engine it depends on, and a framework adapter — three repositories that don't share a codebase. That's one MegaTask.
-
-## Starting a MegaTask
-
-The intake modal has three scopes:
-
- **Single cell** — one task in one project.
- **Board-led** — a feature spanning the cells of one product.
- **MegaTask** — several tasks across the projects you pick.
-
-Choose **MegaTask** and check every repository the work spans (pick at least two). The intake agent clones and reads all of them, interviews you exactly as usual, and then — instead of proposing one draft — proposes the **whole batch at once**: one task per piece of work, each already assigned to the project it belongs to.
-
-## How the batch is sequenced
-
-For each task it proposes, the agent declares a small **collision surface**: which files or directories it will touch, whether it adds a database migration, and whether it edits a widely-shared component. RoboCo turns those surfaces into conflict-free **waves** with a deterministic analyzer — no guesswork:
-
- Tasks that touch the same files are **serialized** (the more important one first).
- Tasks that add a migration run in a **serial chain**, never two at once.
- A task that edits a shared surface runs **after** the tasks it overlaps.
- Everything else runs **in parallel**.
-
-The waves are just ordinary task dependencies, so the same dependency-gate that already paces the rest of the company runs them: a wave starts only once the previous wave's tasks have reached a terminal state — normally each one's pull request is merged (a cancelled task releases the next wave too).
-
-The same collision-aware sequencing follows the work **down the chain**, not just at the top level. When a cell PM delegates a root-subtask into developer tasks, the dev-task collision surfaces flow through the same DAG — file-overlap serializes, migration-adders chain, shared-surface edits wait their turn — and cell tasks themselves wave-chain off their sibling root-subtasks. So a batch that spans a shared codebase stays ordered all the way to the leaves, not only at the umbrella. The task hierarchy is capped at four layers (umbrella → root → cell → dev) to fit this MegaTask shape.
-
-## What gets created
-
-When you confirm, RoboCo creates one **umbrella** task that groups the batch, and one **root-subtask** per piece of work:
-
-```mermaid
-graph TD
-    U["MegaTask umbrella<br/>(no repo, no PR)"] --> A["Task A — project 1<br/>own branch + PR"]
-    U --> B["Task B — project 2<br/>own branch + PR"]
-    U --> C["Task C — project 3<br/>own branch + PR"]
-```
-
-The **umbrella** is the batch's single review-and-approve unit. It does no git of its own — it spans repositories that have no common `master`, so there is no mega-PR. Each **root-subtask** is a normal piece of work in its own repository, with its own branch and its own pull request, coordinated by the Main PM down to the cells exactly like any other task. The umbrella finishes only when every task in it is done.
-
-## The two start buttons
-
-Like a single task, a MegaTask offers two start paths:
-
- **Board review & Start** — the Product Owner and Head of Marketing review the **whole batch** first (they see every task and can adjust scope). The work is held until you approve the umbrella, then released wave by wave.
- **Approve & Start** — the batch goes straight to the Main PM and the first wave dispatches immediately.
-
-Either way you review and approve the batch **once**, not task by task. After it launches, the umbrella and its tasks appear in your task views like any other work — you watch the waves progress, and each task lands as its own pull request for you to merge.
@@ -1,76 +0,0 @@
-# The merge model
-
-A feature in RoboCo isn't one commit on one branch — it's a small tree of work that converges, as real pull requests, up a fixed chain to your repository's default branch. The rule at the top is simple and absolute: **only you ever merge to `master`.**
-
-## Branches, commits, and PRs are traceable
-
-Every branch, commit, and pull request carries the task ID it belongs to, so your git history reads back to the work that produced it.
-
- **Branches** follow `{type}/{team}/{task-hierarchy}`, where the hierarchy uses `--` between levels (a `/` would collide with git's ref storage). Types are `feature`, `bug`, `chore`, `docs`, `hotfix`.
-
-    ```text
-    feature/backend/ABC12345                    # a root task
-    feature/backend/ABC12345--DEF67890           # a subtask
-    feature/backend/ABC12345--DEF67890--GHI11111 # a sub-subtask (max depth)
-    ```
-
- **Commits** are auto-prefixed with the short task ID: `[ABC12345] Add the auth endpoint`.
- **Pull requests** are titled the same way: `[ABC12345] <title>`.
-
-A branch is created automatically the moment an agent claims a task, and a **work session** tracks its branch, base, commits, files changed, and pull request from claim to merge.
-
-## Per-task worktrees
-
-An agent's clone is a single shared checkout, but a coordinator PM legitimately holds several in-progress roots at once. So instead of one checkout that each fresh claim `git reset --hard`s onto a new branch — destroying uncommitted work on the still-active first root — **each claimed task gets its own working tree** under the clone at `{clone}/.worktrees/{task-short}/`. The clone keeps the real `.git` object store and the shared `.venv`; each worktree symlinks that `.venv` so tools resolve without a per-task re-sync. The clone's `HEAD` is never moved by a claim, so a second task (or a PM's parallel roots) never overwrites a first task's uncommitted changes.
-
-Branch-by-name operations (`push`, `pull`, `merge`) run from the clone root as before; only the checkout/HEAD-moving operations (`create_branch`, `commit`, `rebase`) target the task's worktree. Exactly one active work session exists per task at a time, so a re-claim supersedes any stale prior session and re-points the worktree at the new claim. When a task reaches a terminal state (completed or cancelled), its worktree is removed best-effort; a task that bounces back through `needs_revision` keeps its worktree to keep working.
-
-## Work converges up a chain
-
-Each developer works in their **own clone** and opens a pull request from their branch. Those flow upward:
-
-```mermaid
-graph BT
-    D1["dev branch"] --> C["cell branch"]
-    D2["dev branch"] --> C
-    C --> R["root / integration branch"]
-    C2["other cell branch"] --> R
-    R --> M["master"]
-    M:::ceo
-    classDef ceo fill:#1f6feb,color:#fff,stroke:#1f6feb;
-```
-
-1. **Developers → cell.** A cell's developers merge their work into the cell's branch.
-2. **Cell → root.** The **cell PM** runs `submit_up` to open the cell → root pull request. The Main PM keeps one integration (root) branch per repository.
-3. **Root → master.** The **Main PM** runs `submit_root` to open the final root → master pull request.
-
-Each of those assembled pull requests passes through the [in-path PR-review gate](task-lifecycle.md#the-in-path-pr-review-gate) before its PM merges it.
-
-## Submit gates that keep the chain clean
-
-Two gate-level checks stop a stale branch from sneaking through:
-
- **Behind-base gate on `i_am_done`.** If a sibling's PR merged into the parent branch while the developer worked, the dev's branch is now behind its base and the assembled PR won't merge cleanly. The gate refuses `i_am_done` in that state and steers the developer to `sync_branch` — the gate-level rebase verb that rebases the branch onto its base (raw shell git is denied to agents, so the rebase goes through the gate, traced and evidenced). Conflicts abort with no force-push and point the dev at resolve-by-hand. The gate fails open on a flaky fetch so a transient git error can't strand a task at the submit gate.
- **Unchanged-PR gate on `submit_root`.** When a Main-PM root PR is `pr_fail`'d and re-submitted byte-identical, the loop would repeat forever. The gate refuses the re-submit when the assembled root PR's head SHA is unchanged since the last `pr_fail` (no new cell work → identical diff); a different SHA means the branch advanced and the submit proceeds. Every ambiguous case fails open.
-
-PR operations are also **scoped per project** — `open_pr`, `pr_target`, `close_pull_request`, and `merge_pr` all require the project and resolve the PR number within it, so two tasks in different repos that happen to share a PR number can never collide and merge the wrong repository's PR.
-
-## Only the CEO merges to master
-
-The final pull request — root → master — is the one place the company stops and hands the decision back to you. It lands in your **CEO Approval Queue** and waits.
-
- The agent-facing merge path **hard-refuses to target the default branch.** A PM can merge a cell PR up to the root, but the merge to `master` is reserved for the CEO action, taken from `awaiting_ceo_approval`.
- **Force-push is CEO-only** too.
-
-From the queue you **Approve & Merge** (it ships to `master`), **Request Changes** (it loops back for another pass), or **Cancel**. This is the second of the only two moments the company needs you — the first being the green light that started the work.
-
-!!! info "Why a squash and one integration branch"
-    Cell pull requests are squash-merged, so each cell's work lands as a single verified commit on the integration branch, co-authored by the agent that wrote it. The final pull request then carries one clean commit per cell — three streams of work folded into one reviewable history.
-
-## Pull requests you didn't open
-
-Not every pull request comes from inside the company. When an external contributor or a fork opens one against your repository, the read-only **PR Reviewer** reads the diff against your standards and posts a single change-request on the PR — it never chats, merges, or decides. The PR then surfaces in the **PR Review Queue** on the Command Center, where you **Supersede** it (the company cuts its own branch from the contributor's commits, hardens it, opens its own PR, and links back to the original once that merges) or **Dismiss** it. Either way the call is yours, and the org never pushes to anyone else's fork. *(This inbound-review flow is feature-flagged; see the optional-subsystems reference.)*
-
-## Next
-
-→ **[How agents are sandboxed](agent-gateway.md)** — why a developer agent literally cannot perform the merge.
@@ -1,92 +0,0 @@
-# Org & roles
-
-RoboCo is **25 AI agents and one human — you, the CEO**. They're organized as a real company: a Board sets direction, a Main PM coordinates three delivery cells, and an Auditor watches everything. A few agents sit at your side on demand. You're on top of all of it.
-
-```mermaid
-graph TD
-    CEO["👤 CEO — you (human)"]
-
-    subgraph Support["At your side (on demand)"]
-        INTAKE["Intake<br/>drafts tasks with you"]
-        SEC["Secretary<br/>gated chief-of-staff"]
-        PRR["PR Reviewer<br/>inbound + root→master gate"]
-    end
-
-    subgraph Board["Board"]
-        PO["Product Owner"]
-        HOM["Head of Marketing"]
-        AUD["Auditor (silent)"]
-    end
-
-    MPM["Main PM<br/>coordinates the cells"]
-
-    subgraph Cells["Delivery cells (6 agents each)"]
-        BE["Backend cell"]
-        FE["Frontend cell"]
-        UX["UX/UI cell"]
-    end
-
-    CEO --- Support
-    CEO --> Board
-    Board --> MPM
-    MPM --> BE & FE & UX
-```
-
-## The cells
-
-The three delivery cells — **Backend, Frontend, UX/UI** — are where code gets written. Each cell is a small, complete team of **six agents**:
-
-| Role | Count | What they do |
-|------|-------|--------------|
-| **Cell PM** | 1 | Runs the cell like an engineering manager: delegates, clears blockers, triages, and folds the cell's work up to the Main PM. |
-| **Developers** | 2 | Build the code in their own clones and open pull requests. |
-| **QA** | 1 | Reads the real diff and decides whether work ships or comes back. Doesn't rubber-stamp. |
-| **Documenter** | 1 | Writes down what was built, so the next agent — and you — don't start cold. |
-| **PR Reviewer** | 1 | Reviews the cell's assembled pull request at the in-path gate before the PM merges it up. |
-
-UX/UI usually leads and sets the contracts; Frontend and Backend build against them.
-
-## The Board and the Main PM
-
-| Role | Reports to | What they do |
-|------|-----------|--------------|
-| **Product Owner** | CEO | Turns your ask into requirements and acceptance criteria. |
-| **Head of Marketing** | CEO | Reviews work from the positioning / naming / user angle. |
-| **Auditor** | CEO | Silent observer with read access to *everything*; reports quality concerns to you and never interferes. |
-| **Main PM** | Board | Coordinates all three cells: fans a task out into per-cell subtasks, integrates the results, and opens the final pull request. |
-
-## At your side, on demand
-
-Three agents work directly with you rather than in the delivery flow. They run only while you're interacting with them or have given an explicit instruction:
-
-| Role | What they do |
-|------|--------------|
-| **Intake** | The conversational **Task Assistant** on the Prompter page. Reads your codebase and drafts a well-formed task with you. Chats only with you. |
-| **Secretary** | Your conversational chief-of-staff. Reads the whole company's state to advise you and executes your directives — but every high-impact action is **gated** for your explicit confirmation. It spends nothing and approves nothing on its own. |
-| **PR Reviewer** | The read-only main reviewer. Handles inbound external/fork pull requests and acts as the in-path gate on the final root → master pull request. It posts a review on the PR; it never chats, merges, or decides. |
-
-## The full roster
-
-25 agents, by their panel IDs:
-
- **Backend:** `be-pm`, `be-dev-1`, `be-dev-2`, `be-qa`, `be-doc`, `be-pr-reviewer`
- **Frontend:** `fe-pm`, `fe-dev-1`, `fe-dev-2`, `fe-qa`, `fe-doc`, `fe-pr-reviewer`
- **UX/UI:** `ux-pm`, `ux-dev-1`, `ux-dev-2`, `ux-qa`, `ux-doc`, `ux-pr-reviewer`
- **Coordination:** `main-pm`
- **Board:** `product-owner`, `head-marketing`, `auditor`
- **At your side:** `intake-1`, `secretary-1`, `pr-reviewer-1`
-
-## How agents talk
-
-Communication is constant and logged. Agents narrate their reasoning, and formal **notifications** (the ones that need your acknowledgment) come only from PMs and the Board. Channels are seeded automatically:
-
- **Cell channels** — `#backend-cell`, `#frontend-cell`, `#uxui-cell`
- **Cross-cell** — `#dev-all`, `#qa-all`, `#pm-all`, `#doc-all`
- **Management** — `#main-pm-board`, `#board-private`
- **Company-wide** — `#announcements` (read-only except Board / Main PM), `#all-hands`
-
-The **Auditor has silent read access to every channel.** You watch all of it from the **Communications** page.
-
-## Next
-
-→ **[The task lifecycle](task-lifecycle.md)** — the path every piece of work walks.
@@ -1,92 +0,0 @@
-# The task lifecycle
-
-Everything in RoboCo is a task, and every task walks the same path. Each step is gated by role — only QA can pass QA, only the CEO can merge to `master` — so work can't skip a stage or land unreviewed. This is the backbone that makes the company trustworthy.
-
-```mermaid
-stateDiagram-v2
-    direction LR
-    [*] --> backlog
-    backlog --> pending: PM activates
-    pending --> claimed: agent claims
-    claimed --> in_progress: start work
-    in_progress --> verifying: self-verify
-    verifying --> awaiting_qa: submit (PR is open)
-    awaiting_qa --> awaiting_documentation: QA passes
-    awaiting_qa --> needs_revision: QA fails
-    needs_revision --> in_progress: rework
-    awaiting_documentation --> awaiting_pm_review: docs done
-    awaiting_pm_review --> completed: PM merges
-    awaiting_pm_review --> awaiting_ceo_approval: escalate
-    awaiting_ceo_approval --> completed: CEO approves & merges
-    awaiting_ceo_approval --> needs_revision: CEO requests changes
-    completed --> [*]
-
-    in_progress --> blocked: external dependency
-    in_progress --> paused: temporarily stopped
-    blocked --> in_progress: unblocked
-    paused --> in_progress: resumed
-```
-
-## The states
-
-| State | What it means | Who owns the next move |
-|-------|---------------|------------------------|
-| `backlog` | PM setup phase — dependencies or session setup still needed. | PM |
-| `pending` | Ready for work; the orchestrator can spawn an agent for it. | the matching role |
-| `claimed` | An agent has locked the task. | the assignee |
-| `in_progress` | Active development. | the assignee |
-| `blocked` | An external dependency is blocking progress. | whoever clears it |
-| `paused` | Temporarily stopped; can resume. | the assignee |
-| `verifying` | The developer is self-verifying before handing off. | the developer |
-| `awaiting_qa` | Submitted for QA — **a pull request is already open** so QA reviews the real diff. | QA |
-| `needs_revision` | QA, a PR reviewer, or the CEO asked for changes. | the developer |
-| `awaiting_documentation` | The Documenter writes up what was built (the PR is already open). | Documenter / Developer |
-| `awaiting_pr_review` | The in-path PR-review gate: a reviewer checks an assembled pull request before the PM merges it. | PR reviewer |
-| `awaiting_pm_review` | Docs are done; the PM reviews and merges. | PM |
-| `awaiting_ceo_approval` | A major task escalated to you for the final call. | **you** |
-| `completed` | Terminal — work done and merged. | — |
-| `cancelled` | Terminal — work cancelled. | — |
-
-!!! note "The PR comes *before* QA"
-    A pull request is opened *before* QA review, not after. That lets QA read the actual PR diff on GitHub, and means the whole downstream approval chain — PM, then you — is signing off on a pull request that already exists.
-
-## When work is rejected
-
-Rejection isn't a dead end — it's a loop. When **QA fails** a task, or a **PR reviewer rejects** an assembled pull request, the task drops back to `needs_revision`, the developer reworks it, and it re-enters the flow. The same is true when *you* request changes from the CEO Approval Queue. Nothing is lost; the task carries its history, branch, and pull request with it the whole way around.
-
-A failed developer task is routed back to **the developer who worked it** (resolved from the work session), not the pool — so the revision lands with whoever has the context, rather than being re-claimed cold by a cell PM. Only a task no developer ever touched falls back to the pool.
-
-## The in-path PR-review gate
-
-Most leaf developer tasks are reviewed by QA and never need a separate PR review. But when work is **assembled and pushed up the chain as a pull request**, it stops for a dedicated review before any PM merges it:
-
-```mermaid
-stateDiagram-v2
-    direction LR
-    in_progress --> awaiting_pr_review: submit_up / submit_root
-    awaiting_pr_review --> awaiting_pm_review: pr_pass
-    awaiting_pr_review --> needs_revision: pr_fail
-```
-
- A **cell PM** runs `submit_up` to open the cell → root pull request.
- The **Main PM** runs `submit_root` to open the root → master pull request.
- Both land in `awaiting_pr_review`, where a PR reviewer either **`pr_pass`es** it on to the PM merge or **`pr_fail`s** it back to `needs_revision`.
-
-This gives the merge step a real reviewer with the power to reject — the one thing a PM otherwise lacks. **Leaf dev tasks and branchless coordination roots skip the gate.**
-
-## Role-gated transitions
-
-Transitions aren't suggestions; they're enforced. A handful of the rules:
-
- **Activating** a task (`backlog → pending`) is PM-only.
- **Passing or failing QA** is QA-only, and a pass requires real review notes.
- **`pr_pass` / `pr_fail`** are PR-reviewer-only.
- **Merging** (`awaiting_pm_review → completed`) is PM-only; **escalating to the CEO** and the final **approve / request-changes / cancel** are CEO-only.
- **Cancelling** is PM-only.
- **A Main-PM coordination root can never be `task_type=code`.** The Main PM coordinates; it doesn't write code itself, so the combination is rejected at creation — a structural guard, not a hint.
-
-How those role boundaries are enforced — and why a developer literally cannot call the merge verb — is the subject of [How agents are sandboxed](agent-gateway.md).
-
-## Next
-
-→ **[The merge model](merge-model.md)** — how a task's branch travels up to `master`.
@@ -1,56 +0,0 @@
-# Bootstrap & seeds
-
-A fresh RoboCo database isn't an empty shell — it comes pre-populated with the whole org chart: every agent, every communication channel, and the welcome messages that establish the channels. This page covers what `make db-init` seeds, and the console entry points that run the bootstrap.
-
-## `make db-init` — seed a fresh instance
-
-The one command you need to bring a clean database to life:
-
-```bash
-make db-init
-```
-
-This runs `python -m roboco.cli --db-only`, which enables the schema (the [migration chain](./data-and-migrations.md)) and then seeds the company in a single transaction.
-
-!!! tip "It's idempotent — safe to re-run"
-    Every seed operation skips what already exists (agents and channels by slug; welcome messages are skipped if the channel already has any). Running `make db-init` against an already-seeded database is a harmless no-op, so you can re-run it any time without fear of duplicates.
-
-## What gets seeded
-
-| Seeded data | Detail |
-|-------------|--------|
-| **26 agent rows** | The 25 AI agents **plus the human CEO** ("Renzo"), each with a stable static UUID. A `system` sentinel row is also appended (it's the FK target for system-authored messages and lives outside the team enum). |
-| **11 channels** | The 3 cell channels (`#backend-cell`, `#frontend-cell`, `#uxui-cell`), the 4 cross-role channels (`#dev-all`, `#qa-all`, `#pm-all`, `#doc-all`), and the management/special channels (`#main-pm-board`, `#board-private`, `#announcements`, `#all-hands`). |
-| **Channel memberships** | Who can read and write each channel, plus the **Auditor's silent-observer access** to every channel. |
-| **Welcome messages** | An opening message seeded into `#announcements`, `#all-hands`, and the three cell channels (each first spins up the backing group and session). |
-
-The roster and the seeded UUIDs are derived from the foundation catalog (`roboco/foundation/identity.py` for agents, `roboco/foundation/policy/communications.py` for channels), so the seed data and the runtime role/permission rules can never drift apart. For the full org chart and who sits in which channel, see [Org & roles](../company/org-and-roles.md).
-
-## The console entry points
-
-`make db-init` is a thin wrapper over the CLI. The supported way to invoke RoboCo directly is the module form:
-
-```bash
-python -m roboco.cli --db-only          # seed the DB and exit (what make db-init runs)
-python -m roboco.cli                     # seed + start the full orchestrator stack
-python -m roboco.cli --skip-db           # start the stack against an already-seeded DB
-python -m roboco.cli --spawn be-dev-1 fe-dev-1   # also spawn the named agents on boot
-```
-
-`python -m roboco.cli` is what the orchestrator container runs and what `make db-init` / `make` targets call. Full system start does more than seed: it brings up the Redis event bus, constructs the orchestrator, starts the API under uvicorn, polls `/health` until the FastAPI lifespan finishes indexing (up to ~2 minutes), then begins dispatching.
-
-!!! note "`python -m roboco.cli` is the working invocation"
-    `pyproject.toml` declares two console scripts, `roboco` and `roboco-bootstrap`. Use `python -m roboco.cli` (or `make db-init`) — that's the invocation the Makefile and the container use and the one that's verified to work. `roboco-bootstrap` maps to the same bootstrap routine; the bare `roboco` console script is not the supported path.
-
-## Required configuration before first boot
-
-Bootstrap itself needs almost nothing, but the orchestrator will refuse to start without two secrets:
-
- **`ROBOCO_ENCRYPTION_KEY`** — the Fernet key that encrypts project GitHub tokens. Its config default is an empty string, but startup is mandatory: no key, no boot.
- **`ROBOCO_AGENT_AUTH_SECRET`** — the HMAC secret that signs agent tokens. Unset, every token is treated as unsigned.
-
-Everything else has a sensible default. See the [environment reference](./env-reference.md) for the full list, and [Deployment](./deployment.md) for the compose host-path mounts.
-
-## Next
-
-→ [Data & migrations](./data-and-migrations.md) — the entities you just seeded, and how the schema stays current. → [Org & roles](../company/org-and-roles.md) — the workforce these seeds create.
@@ -1,74 +0,0 @@
-# Data & migrations
-
-RoboCo keeps all of its state in PostgreSQL. There is no separate document store, no schema you have to hand-build, and — in normal operation — no migration command you have to remember. This page gives you the operator's-eye view: the handful of entities worth understanding, the one hard database requirement (pgvector), and how the schema keeps itself up to date.
-
-## The entities you'll actually see
-
-The full data model spans about thirty Pydantic models in `roboco/models/` with matching SQLAlchemy tables in `roboco/db/tables.py`. You don't need most of them. These are the ones that show up across the panel and explain how work flows:
-
-| Entity | What it is |
-|--------|------------|
-| **Task** | The atomic unit of work. Carries its acceptance criteria, status (the 15-state [lifecycle](../company/task-lifecycle.md)), priority, branch name, PR number/URL, ownership (`created_by` / `assigned_to` / `team`), and its place in the tree (`parent_task_id`, `dependency_ids`, `blocker_ids`). A task points at **exactly one** of a `project_id` or a `product_id` — a single-repo task uses the project, a Board/fan-out coordination task uses the product. A validator enforces "one or the other, never both." |
-| **Project** | A git repository configuration: `git_url`, default branch, protected branches, the Fernet-encrypted GitHub PAT (`git_token_encrypted` — the API only ever returns `has_git_token`, never the token), the per-project CI/gate commands, and the assigned cell. See [Register your first project](../get-started/first-project.md). |
-| **WorkSession** | The link between an agent, a task, and a branch. One is created each time an agent claims a task. It tracks the base/target branches, the commits made, the files modified, the PR and merge outcome, and (when toolchain matching is on) the resolved Python version and toolchain status. |
-| **Agent** | One row per member of the workforce — role, team, status — plus the human CEO. See [Org & roles](../company/org-and-roles.md). |
-| **Session / Channel / Message** | The communication substrate. A `Channel` is a room; a `Session` is a live conversation inside it; a `Message` is one extracted line of an agent's stream. |
-| **Notification** | A formal signal that requires acknowledgment (sent by PMs and the Board), distinct from the constant message stream. |
-| **Journal** | Each agent's personal log of reflections and learnings, with `JournalEntry` rows underneath. |
-
-Two newer entities round out the company-in-a-box features: **Product** (with `ProductProject`, the per-cell repo-routing map for fan-out work) and **Pitch** (a Board proposal that the CEO approves and that can auto-provision a repo). You'll meet these on the [Business](../panel/business.md) page.
-
-## pgvector is required
-
-RoboCo's in-house RAG engine stores embeddings in PostgreSQL using the **pgvector** extension. The orchestrator enables it for you at startup (`CREATE EXTENSION IF NOT EXISTS vector`), so the bundled `postgres` image — which ships pgvector — works out of the box.
-
-!!! warning "If pgvector isn't installed"
-    On a bring-your-own PostgreSQL where the `vector` extension isn't available, the orchestrator logs a warning and **RAG features silently disable** — agents lose the knowledge base and mentor lookups, but the rest of the system runs. If you point RoboCo at an external Postgres, make sure pgvector is installed there.
-
-Operationally, **PostgreSQL and Redis are the only two stateful services to back up.** Everything the company knows lives in Postgres; Redis holds the event bus and short-lived coordination state.
-
-!!! danger "The encryption key is not in the database"
-    Each project's GitHub PAT is stored encrypted with `ROBOCO_ENCRYPTION_KEY`. A database backup **without that key is useless for the tokens** — you'll be able to restore every project except its credentials. Keep the key safe and separate. See the [environment reference](./env-reference.md).
-
-## The stack migrates itself on startup
-
-You almost never run a migration command by hand. When the orchestrator boots, `init_db()` enables pgvector and then `run_migrations()` runs `alembic upgrade head` in a worker thread:
-
-```mermaid
-flowchart LR
-    A[Orchestrator starts] --> B[init_db: enable pgvector]
-    B --> C[run_migrations: alembic upgrade head]
-    C --> D[create_all gap-fill on existing DB]
-    D --> E[dispose pool to refresh enum cache]
-    E --> F[API ready]
-```
-
-The practical consequence: **a normal `docker compose up` / restart already applies any new migrations.** A fresh database is built entirely by the migration chain from base; an existing one runs only the pending steps (a pre-Alembic database is auto-stamped at the initial revision first, so it isn't re-built).
-
-!!! tip "The manual command is belt-and-suspenders"
-    The documented manual step — after pulling a change that adds a migration —
-
-    ```bash
-    docker compose exec orchestrator alembic upgrade head
-    ```
-
-    is a safety net, not a routine requirement, since the orchestrator runs the same command on boot. In host-dev mode (no container) the equivalent is `uv run alembic upgrade head`, or `make migrate`.
-
-## A fresh DB is built by migrations, not `create_all` { #fresh-db-gotcha }
-
-This is the one gotcha that bites operators who try to reset state by hand. Several migrations embed **seed data** — most importantly the LLM provider rows (Anthropic, Ollama, self-hosted, Grok). The schema must be built by **running the migration chain**, never by a bare SQLAlchemy `create_all`.
-
-!!! warning "Don't reset a database with `create_all`"
-    A `create_all`-only database has empty `provider_configs`, so the Settings → Providers endpoints return **404**. The fix is always the same: let the migrations run (restart the orchestrator, or run `alembic upgrade head`). The orchestrator's own startup uses `create_all` only as a *gap-fill* on an already-migrated database, never as the builder.
-
-## Contributor notes
-
-If you write or review custom migrations:
-
- **Revision-id length is capped at 32 characters.** PostgreSQL stores `alembic_version.version_num` as `VARCHAR(32)`. A longer id breaks a live `upgrade` even though the test suite (which renders offline / uses `create_all`) never catches it. The chain currently has **54 revisions** (55 files — revision `026` is split into two consecutive steps); the head is `054_a2a_message_skill`, and the longest id in the tree is `015_drop_task_execution_outputs` at 31 characters, deliberately just under the limit.
- **The chain is linear.** Every revision has a single `down_revision`; there are no branches or merges to reconcile.
- **Models, tables, and migrations must stay in sync.** A Pydantic model in `roboco/models/`, its ORM table in `roboco/db/tables.py`, and the migration that creates the column are three layers that move together.
-
-## Next
-
-→ [Bootstrap & seeds](./bootstrap-and-seeds.md) — what `make db-init` puts into a fresh database. → [Environment reference](./env-reference.md) — every `ROBOCO_DATABASE_*` knob and the encryption key.
@@ -1,178 +0,0 @@
-# Production deploy
-
-This is the operator reference for running RoboCo on a NAS or server. If you just want it up on your laptop, the [install quickstart](../get-started/installation.md) is faster — this page assumes you've done that once and now want the durable, server-side setup: the compose files, the host mounts agents need, where data lives, how to back it up, and how to harden it.
-
-!!! warning "Trusted network only"
-    RoboCo is built for a private LAN or homelab. Do not expose it directly to the public internet. nginx is the single entry point, but the orchestrator's WebSocket streams and (in header-trust mode) its API assume a trusted network. Put it behind your own VPN if you need remote access.
-
-## The three compose files
-
-There are **three tracked compose files**, and they are not interchangeable:
-
-| File | What it does | Needs a build toolchain? |
-|------|--------------|--------------------------|
-| `docker-compose.yml` | Builds every image from the Dockerfiles in `docker/`. | Yes |
-| `docker-compose.yaml` | **Byte-identical** to `docker-compose.yml`. | Yes |
-| `docker-compose.registry.yml` | Pulls and runs the **pre-built published images**. | No |
-
-`docker-compose.yml` and `docker-compose.yaml` are the same file under two names — Docker Compose picks up either, and the NAS deployment runs the `.yaml`. If you fork RoboCo and change a service, keep all three in sync.
-
-### Which one to run
-
-For a server you don't intend to hack on, run the **registry** file — it pulls finished images and needs no source tree or compiler on the host:
-
-```bash
-docker compose -f docker-compose.registry.yml pull
-docker compose -f docker-compose.registry.yml up -d
-```
-
-Two variables choose what you pull (defaults shown):
-
-```bash
-ROBOCO_REGISTRY=ghcr.io/rennf93   # or docker.io/renzof93
-ROBOCO_VERSION=latest             # or a pinned release, e.g. 0.15.0
-```
-
-The orchestrator then spawns the **matching** pre-built agent images on demand (it reads `ROBOCO_AGENT_IMAGE_REGISTRY` / `ROBOCO_AGENT_IMAGE_TAG`, which the registry compose wires to the same registry and version). Pin `ROBOCO_VERSION` to a release tag in production so an upstream `latest` push can't silently change your fleet.
-
-Build from source only when you're modifying RoboCo:
-
-```bash
-docker compose up -d   # builds on first run
-```
-
-!!! note "Agent images are build/pull-only services"
-    The `agent-*-image` services in every compose file are one-shot stubs — they exist so `docker compose build`/`pull` materializes each per-role agent image up front. They never run as long-lived containers. The orchestrator spawns the actual agent containers itself, on demand, over the mounted Docker socket, and tears them down when their work is done.
-
-## The single origin
-
-nginx (`docker/nginx.conf`, rendered from an envsubst template) is the only externally-exposed service. It listens on `localhost:3000` and routes by path:
-
-```mermaid
-flowchart LR
-    B[Browser :3000] --> N[nginx]
-    N -->|/| P[panel:3000]
-    N -->|/api/, /ws/, /health, /ready| O[orchestrator:8000]
-```
-
-| Path | Upstream |
-|------|----------|
-| `/api/`, `/ws/`, `/health`, `/ready` | `roboco-orchestrator:8000` |
-| everything else | `roboco-panel:3000` |
-
-The browser only ever sees one origin (`:3000`), so there's no CORS to configure — the panel uses relative `/api` and `/ws` URLs and lets nginx dispatch. The panel container is never published directly; you reach it only through nginx. `/ws/` also gets a long (86400s) read timeout so live sockets stay open.
-
-The backing services *do* publish host ports for direct inspection — Postgres on **15432**, Redis on **16379**, Ollama on **11435**, and the orchestrator on **8000**. You don't route browser traffic at these; they're there for `psql`, `redis-cli`, and the like.
-
-## Required host-path mounts
-
-The orchestrator is Docker-in-Docker: it mounts `/var/run/docker.sock` and spawns agent containers itself. Because those agent bind-mounts resolve on the **host** daemon (not inside the orchestrator container), several paths must be given as **absolute host paths** — the orchestrator passes them straight through to `docker run -v` for each agent.
-
-| Variable | What it points at | Compose default |
-|----------|-------------------|-----------------|
-| `ROBOCO_HOST_PROJECT_DIR` | The RoboCo project directory on the host. | `/volume1/roboco` |
-| `ROBOCO_HOST_CLAUDE_DIR` / `CLAUDE_AUTH_DIR` | The host `~/.claude` Claude Code auth dir, mounted into the orchestrator and each agent. | `/home/renzof/.claude` / `${HOME}/.claude` |
-| `ROBOCO_HOST_DATA_DIR` | The host data dir handed to agents for shared volumes (workspaces, logs, grok-usage). | `/volume1/roboco/data` |
-| `ROBOCO_DATA_DIR` | Host root for all persistent volumes mounted into the *backing* services and orchestrator (see below). | `./data` |
-| `ROBOCO_HOST_GROK_DIR` | Host `~/.grok` SuperGrok auth — only needed if you run any agent on Grok. | `/home/renzof/.grok` |
-
-!!! danger "These must be real, absolute host paths"
-    A relative path or a path that only exists *inside* the orchestrator container will make agent spawns fail, because the host Docker daemon resolves the bind. On a NAS the project and data dirs usually live on the RAID volume (e.g. `/volume1/roboco` and `/volume1/roboco/data`).
-
-The host `~/.grok` is mounted **read-write** into the orchestrator (it rewrites the short-lived token in place to keep agents from hanging on an expired login) and **read-only** into each Grok agent. Run `grok login` on the host once before enabling Grok. Provider routing and the Grok runtime are covered in the models section.
-
-## Data persistence and backup
-
-Everything durable lives under `ROBOCO_DATA_DIR` (default `./data`). On a server, point this at a RAID volume:
-
-```bash
-ROBOCO_DATA_DIR=/volume1/roboco/data
-```
-
-| Subdirectory | Holds |
-|--------------|-------|
-| `postgres/` | The entire database — tasks, projects, work sessions, journals, encrypted git tokens, the pgvector store. |
-| `redis/` | Append-only cache, sessions, rate-limit + event-bus state. |
-| `ollama/` | The local model cache (embedding model + local LLM) — large, but re-pullable. |
-| `workspaces/` | Each agent's git clone of each project. |
-| `logs/` | Per-agent run logs. |
-| `mcp-configs/`, `prompts-generated/`, `agent-settings/`, `briefings/`, `manifests/` | Per-agent spawn artifacts the orchestrator writes. |
-| `grok-usage/` | Per-agent Grok cost/usage capture. |
-
-For backup, the load-bearing directory is `postgres/` (everything that isn't re-derivable). `ollama/` and `workspaces/` are reconstructible — Ollama re-pulls models, agents re-clone repos — so they're optional in a backup. Take Postgres backups with `pg_dump` against the published port rather than copying the live data directory:
-
-```bash
-pg_dump -h localhost -p 15432 -U roboco roboco > roboco-backup.sql
-```
-
-!!! danger "Back up `ROBOCO_ENCRYPTION_KEY` with the database"
-    Every per-project GitHub token in the database is Fernet-encrypted with `ROBOCO_ENCRYPTION_KEY`. **A database backup is useless without the key.** If you lose or change the key, every stored token becomes undecryptable and must be re-entered project by project. Store the key with your secrets, keep it stable across restarts, and never commit `.env`.
-
-## Secure mode
-
-On a trusted LAN RoboCo runs in **header-trust mode** by default (`ROBOCO_AGENT_AUTH_REQUIRED=false`): callers are identified by role headers, no token required. That's the intended homelab setup.
-
-To harden it so one agent can't spoof another's role, turn on fail-closed auth:
-
-```bash
-ROBOCO_AGENT_AUTH_REQUIRED=true
-ROBOCO_AGENT_AUTH_SECRET=<your HMAC secret>     # already required for docker compose
-ROBOCO_PANEL_AGENT_TOKEN=<from make panel-token>
-```
-
-With auth required, every API call must carry a valid `X-Agent-Token`. The panel runs in your browser and can't hold the signing secret, so nginx injects the CEO's token for it: generate the token with `make panel-token` (it signs one using your `ROBOCO_AGENT_AUTH_SECRET`), put it in `ROBOCO_PANEL_AGENT_TOKEN`, and nginx adds it as `X-Agent-Token` on `/api` and `/ws`. The panel keeps working; the secret never reaches the browser.
-
-`ROBOCO_ENCRYPTION_KEY` and `ROBOCO_AGENT_AUTH_SECRET` are both **required** for any docker compose run — the orchestrator service block guards them with compose `:?` so the stack refuses to start if either is unset. See [Security](../troubleshooting/security.md) for the full sandboxing model and [the env reference](./env-reference.md) for every knob.
-
-## Startup sequence
-
-`depends_on` conditions enforce a strict boot order; the effective sequence is:
-
-```mermaid
-flowchart LR
-    PG[postgres] --> OL[ollama]
-    RD[redis] --> OL
-    OL --> OI[ollama-init]
-    OI --> OR[orchestrator]
-    AB[agent-base-image] --> OR
-    OR --> PN[panel]
-    PN --> NG[nginx]
-    OR --> NG
-```
-
- **postgres / redis / ollama** must each pass their healthcheck (`pg_isready`, `redis-cli ping`, `ollama list`) before anything downstream starts.
- **ollama-init** is a one-shot that best-effort pulls the embedding model and the local LLM, then gates success on the models being **present** — a degraded model registry can't take down a fully-cached deployment.
- **orchestrator** waits for postgres + redis + ollama healthy, ollama-init completed, and agent-base-image built. On startup it **runs the database migrations itself** (idempotently, to head) and indexes its knowledge base — you do not run `alembic upgrade head` by hand for the compose path.
- **panel** waits for the orchestrator; **nginx** waits for both.
-
-First boot is the slow one: the model pulls (the LLM is a couple of minutes) plus knowledge-base indexing. Watch it come up:
-
-```bash
-docker compose logs -f orchestrator
-curl http://localhost:8000/health
-docker ps --filter name=roboco
-```
-
-When the orchestrator reports serving, open `http://localhost:3000`. A boot that hangs is almost always waiting on `ollama-init` (model pull) or a healthcheck — check `docker compose ps` to see which service is still `starting`. Migration and data details are in [Data & migrations](./data-and-migrations.md); recurring boot symptoms are in [Common issues](../troubleshooting/common-issues.md).
-
-## Operator-relevant Makefile targets
-
-The `Makefile` drives the **host** developer workflow (uv-based, for hacking on RoboCo itself) — it is separate from the Docker stack and needs `uv` on the host. The handful that matter operationally:
-
-| Target | Does |
-|--------|------|
-| `make panel-token` | Prints a signed CEO token for `ROBOCO_PANEL_AGENT_TOKEN` (secure mode). |
-| `make infra` | Brings up only postgres + redis (`make infra-down` stops them) — for host-side dev against the backing services. |
-| `make migrate` | Runs `alembic upgrade head` on the host (the compose stack self-migrates; this is the host-dev path). |
-| `make run` | Runs the API + orchestrator on the host (no `--reload`); `make api` is the reload dev server, `make dev` runs both. |
-| `make quality` | The full merge gate: ruff format-check + lint, mypy, pytest with 80% coverage floor, complexity, security, dependency, and migration checks. |
-| `make serve-docs` | Serves this documentation locally with `mkdocs serve`. |
-| `make status` / `make logs` | Orchestrator status / recent logs against a running instance. |
-
-Run `make help` for the full list.
-
-## Next
-
- **[Environment reference](./env-reference.md)** — every `ROBOCO_*` setting, with defaults and on/off state.
- **[Data & migrations](./data-and-migrations.md)** — the self-migrating schema and what to back up.
- **[Security](../troubleshooting/security.md)** — the full agent sandboxing and auth model.
@@ -1,314 +0,0 @@
-# Environment reference
-
-This is the canonical list of every `ROBOCO_*` setting. They are all read by a single Pydantic-Settings class (`roboco/config.py`), loaded from the process environment and `.env`, prefixed with `ROBOCO_`, and case-insensitive. Most have a working default; the few that don't, and the ones the orchestrator refuses to start without, are flagged below.
-
-!!! tip "You rarely set most of these"
-    For a working deploy you set the two required secrets, the host paths, and maybe a feature flag or two. The long tables here exist so that when you *do* need to tune a timeout or a window, you can find it. The defaults shown are RoboCo's config defaults; a few compose-only defaults differ and are called out.
-
-A feature flag set in `.env` takes effect on the next backend restart. The env-gated subsystems can also be toggled from the panel's **Settings → Feature Flags** card, which persists to the settings store and overrides the env default; an unset toggle falls back to the env/config default. See the [Optional capabilities](../optional/index.md) section for what each subsystem does.
-
-## Required secrets
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_ENCRYPTION_KEY` | *(empty — required)* | Fernet key encrypting every per-project git token at rest. The orchestrator **refuses to start** without it (compose `:?` guard). Generate with `python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'`. Keep it stable — losing it makes stored tokens undecryptable. |
-| `ROBOCO_AGENT_AUTH_SECRET` | *(empty — required for compose)* | HMAC secret signing the per-agent `X-Agent-Token`. Generate with `python -c 'import secrets; print(secrets.token_hex(32))'`. |
-
-## Security & auth
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_AGENT_AUTH_REQUIRED` | `false` | Fail-closed secure mode. When `true`, every API call must carry a valid token. Requires `ROBOCO_PANEL_AGENT_TOKEN` to keep the panel working. On a trusted LAN, leave `false` (header-trust mode). |
-| `ROBOCO_PANEL_AGENT_TOKEN` | *(empty)* | The CEO token nginx injects as `X-Agent-Token` on `/api` and `/ws` in secure mode, so the panel works without the browser holding the signing secret. Generate with `make panel-token`. |
-
-## Application & API server
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_APP_VERSION` | `0.15.0` | Reported app version. |
-| `ROBOCO_DEBUG` | `false` | Debug mode. |
-| `ROBOCO_ENVIRONMENT` | `development` | One of `development` / `staging` / `production`. Selects the JSON log renderer (prod) vs console renderer. The compose stack sets `production`. |
-| `ROBOCO_HOST` | `127.0.0.1` | Bind address. Use `0.0.0.0` in containers. |
-| `ROBOCO_PORT` | `8000` | API port. |
-| `ROBOCO_API_URL` | *(unset)* | Override base URL for containerized agents (e.g. `http://roboco-orchestrator:8000`); otherwise built from host/port. |
-| `ROBOCO_CORS_ORIGINS` | `["http://localhost:3000","http://localhost:5173"]` | Allowed CORS origins. The single-origin nginx setup means you rarely change this. |
-| `ROBOCO_CORS_ALLOW_CREDENTIALS` | `true` | Whether CORS allows credentials. |
-| `ROBOCO_PUBLIC_BASE_URL` | `http://127.0.0.1:8000` | Reachable base URL embedded in commit-trailer links — set to your LAN IP or domain so the links resolve. |
-
-## Database
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_DATABASE_HOST` | `localhost` | Postgres host (`roboco-postgres` in compose). |
-| `ROBOCO_DATABASE_PORT` | `5432` | Postgres port. |
-| `ROBOCO_DATABASE_USER` | `roboco` | Postgres user. |
-| `ROBOCO_DATABASE_PASSWORD` | `roboco` | Postgres password — change it for any real deployment. |
-| `ROBOCO_DATABASE_NAME` | `roboco` | Database name. |
-| `ROBOCO_DATABASE_ECHO` | `false` | Log every SQL statement. |
-| `ROBOCO_DATABASE_POOL_SIZE` | `10` | Connection pool size. |
-| `ROBOCO_DATABASE_MAX_OVERFLOW` | `20` | Extra connections beyond the pool. |
-| `ROBOCO_DATABASE_POOL_TIMEOUT` | `10` | Seconds to wait for a pooled connection. |
-| `ROBOCO_DATABASE_POOL_RECYCLE` | `1800` | Recycle a connection after this many seconds. |
-
-## Redis
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_REDIS_HOST` | `localhost` | Redis host (`roboco-redis` in compose). |
-| `ROBOCO_REDIS_PORT` | `6379` | Redis port. |
-| `ROBOCO_REDIS_DB` | `0` | Redis logical DB. |
-| `ROBOCO_REDIS_PASSWORD` | *(unset)* | Optional Redis password. |
-
-## RAG, embeddings & Ollama
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_RAG_PERSIST_DIR` | `.roboco` | Local RAG persistence dir. |
-| `ROBOCO_RAG_CHUNK_STRATEGY` | `fixed` | One of `fixed` / `semantic` / `hierarchical` / `contextual`. `fixed` recommended; `semantic` loads an extra model. |
-| `ROBOCO_RAG_CHUNK_SIZE` | `512` | Base chunk size. |
-| `ROBOCO_RAG_CHUNK_SIZE_DOCS` | `1536` | Chunk size for docs. |
-| `ROBOCO_RAG_CHUNK_SIZE_JOURNALS` | `1024` | Chunk size for journals/reflections. |
-| `ROBOCO_RAG_CHUNK_OVERLAP` | `128` | Chunk overlap. |
-| `ROBOCO_RAG_AUTO_UPDATE_ENABLED` | `true` | Whether the RAG index auto-refreshes. |
-| `ROBOCO_RAG_AUTO_UPDATE_INTERVAL` | `300` | Seconds between auto-updates. |
-| `ROBOCO_ANTHROPIC_API_KEY` | *(unset)* | Optional Anthropic key. Agents use the mounted Claude Code auth, not a metered key. |
-| `ROBOCO_DEFAULT_EMBEDDING_MODEL` | `qwen3-embedding:0.6b` | Embedding model (1024-dim). |
-| `ROBOCO_EMBEDDING_DIMENSIONS` | `1024` | Embedding dimensions — must match the model. |
-| `ROBOCO_LOCAL_LLM_MODEL` | `glm-5.2:cloud` | Local LLM for RAG answer synthesis. |
-| `ROBOCO_LOCAL_LLM_BASE_URL` | `http://roboco-ollama:11434/v1` | Ollama OpenAI-compatible endpoint. |
-| `ROBOCO_OLLAMA_BASE_URL` | `http://roboco-ollama:11434` | Ollama native endpoint (embeddings, model management). |
-
-## Workspaces & git timeouts
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_WORKSPACES_ROOT` | `/data/workspaces` | Root for all agent git clones. |
-| `ROBOCO_WORKSPACE_AUTO_CLONE` | `true` | Auto-clone a repo on first workspace access. |
-| `ROBOCO_WORKSPACE_CLONE_TIMEOUT` | `300` | Seconds for a `git clone`. |
-| `ROBOCO_WORKSPACE_REFRESH_FETCH_TIMEOUT_SECONDS` | `60` | Timeout for the best-effort `git fetch` on re-entry into a healthy clone. |
-| `ROBOCO_WORKSPACE_INSTALL_DEV_DEPS` | `true` | After cloning, install the project's dev dependencies into the workspace so `make quality` runs without re-downloading tooling. |
-| `ROBOCO_WORKSPACE_DEP_INSTALL_TIMEOUT_SECONDS` | `600` | Timeout for that post-clone dependency install. |
-| `ROBOCO_GIT_COMMAND_TIMEOUT_SECONDS` | `30` | Timeout for a single local git subprocess (status, log, checkout). |
-| `ROBOCO_GIT_COMMIT_TIMEOUT_SECONDS` | `180` | Timeout for staging + committing a changeset. |
-| `ROBOCO_GIT_NETWORK_TIMEOUT_SECONDS` | `120` | Timeout for git ops that talk to origin (fetch / pull / push). |
-| `ROBOCO_PROTECTED_GIT_URLS` | *(empty)* | Repo URL substrings a project may not point at — blocks agent commits/merges from reaching a protected repo. |
-| `ROBOCO_SESSION_IDLE_TIMEOUT_SECONDS` | `3600` | Idle seconds before a messaging session is swept closed. |
-
-## Agent images (spawn source)
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_AGENT_IMAGE_REGISTRY` | *(empty)* | Registry namespace for pre-built agent images (e.g. `ghcr.io/rennf93`). Empty = build locally. The registry compose wires this to `ROBOCO_REGISTRY`. |
-| `ROBOCO_AGENT_IMAGE_TAG` | *(empty)* | Tag for pre-built agent images (e.g. `0.9.0`). Empty = implicit `:latest`. The registry compose wires this to `ROBOCO_VERSION`. |
-
-!!! note "Deploy-time variables (compose, not config.py)"
-    A few variables are consumed by the compose files and host-mount wiring rather than by `config.py`: `ROBOCO_REGISTRY`, `ROBOCO_VERSION`, `ROBOCO_DATA_DIR`, `ROBOCO_HOST_PROJECT_DIR`, `ROBOCO_HOST_CLAUDE_DIR` / `CLAUDE_AUTH_DIR`, `ROBOCO_HOST_DATA_DIR`, and `ROBOCO_HOST_GROK_DIR`. They are documented in the [production deploy reference](./deployment.md#required-host-path-mounts).
-
-## Transcript retention
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_TRANSCRIPT_RETENTION_DAYS` | `14` | Days to keep agent Claude Code transcripts. A stored panel setting overrides this default. |
-| `ROBOCO_TRANSCRIPT_PRUNE_ENABLED` | `true` | Whether the background sweep prunes old transcripts. |
-| `ROBOCO_TRANSCRIPT_PRUNE_INTERVAL_SECONDS` | `3600` | Minimum seconds between prune passes. |
-
-## Spawn pacing, SLAs & reaper windows
-
-The orchestrator's dispatcher uses these to pace spawns, detect loops, and reclaim stuck work. Defaults are tuned for real LLM latency — raise the reaper windows (not lower) if long agent tasks are being reaped mid-work.
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_AGENT_TOOL_CALL_WARN` | `50` | Soft warning threshold for per-session tool calls. |
-| `ROBOCO_AGENT_TOOL_CALL_HALT` | `150` | Hard cap on per-session tool calls; the orchestrator stops the container. |
-| `ROBOCO_AGENT_LOOP_THRESHOLD` | `3` | Identical tool+args repeats in the window that flag a loop. |
-| `ROBOCO_AGENT_LOOP_WINDOW` | `10` | How many recent tool calls to inspect for loop detection. |
-| `ROBOCO_AGENT_STOP_ATTEMPT_ALLOWANCE` | `1` | Stop-without-terminal attempts before auto-substitute. |
-| `ROBOCO_AGENT_SLA_DEVELOPER_IN_PROGRESS` | `7200` | SLA (s) for a developer in `in_progress`. |
-| `ROBOCO_AGENT_SLA_DEVELOPER_VERIFYING` | `1800` | SLA (s) for a developer in `verifying`. |
-| `ROBOCO_AGENT_SLA_QA_CLAIMED` | `1800` | SLA (s) for QA on a claimed review. |
-| `ROBOCO_AGENT_SLA_DOCUMENTER_CLAIMED` | `3600` | SLA (s) for a documenter on a claimed task. |
-| `ROBOCO_AGENT_SLA_CELL_PM_CLAIMED` | `14400` | SLA (s) for a cell PM on a claimed task. |
-| `ROBOCO_CLAIM_STALE_SECONDS` | `180` | Claim-heartbeat staleness used by the spawn trigger filter. |
-| `ROBOCO_STALE_CLAIM_REAP_SECONDS` | `600` | Reaper-only stale-claim threshold before releasing a claim back to pending. |
-| `ROBOCO_PM_CLOSURE_RECENTLY_PAUSED_SECONDS` | `45` | Debounce before respawning a PM to close a recently paused parent. |
-| `ROBOCO_NOTIFICATION_SPAWN_COOLDOWN_SECONDS` | `600` | Cross-tick damper for notification-triggered spawns (escalation/approval/audit/a2a): one spawn per (agent, notification) per window. The notification stays pending, so the next window retries if still unacknowledged; `0` restores the legacy every-tick respawn. |
-| `ROBOCO_GROK_IDLE_KILL_SECONDS` | `900` | Idle-container kill threshold for Grok agents (they emit no SDK heartbeat). |
-| `ROBOCO_GROK_MAX_COST_USD` | `0.0` | Per-agent Grok cost ceiling (USD) before kill; `0` disables. |
-| `ROBOCO_INTERACTIVE_IDLE_REAP_SECONDS` | `1800` | Idle-reap threshold for live intake/secretary chats; `0` disables. |
-| `ROBOCO_CLAIMED_NO_AGENT_GRACE_SECONDS` | `120` | Grace window before respawning/releasing a claimed task with no running agent. |
-| `ROBOCO_PM_DECISION_WINDOW_SECONDS` | `300` | Recency window for a PM `journal:decision` to satisfy gating verbs. |
-| `ROBOCO_SPAWN_COOLDOWN_SECONDS` | `60` | Per-task spawn-rate cooldown. |
-| `ROBOCO_ROLE_SPAWN_RATE_PER_MINUTE` | `6` | Per-role spawn-rate limit per minute. |
-
-## Gateway: manifests & tracing-gate minimums
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_MANIFEST_HOST_DIR` | `/app/manifests` | Orchestrator dir where per-agent tool manifests are written; must be a host-bind-mounted path so the daemon can mount each manifest into its agent. |
-| `ROBOCO_QA_NOTES_MIN_CHARS` | `80` | Minimum characters for QA notes. |
-| `ROBOCO_DOCS_NOTES_MIN_CHARS` | `20` | Minimum characters for docs notes. |
-| `ROBOCO_DEV_NOTES_MIN_CHARS` | `40` | Minimum characters for a developer's `dev_notes`. |
-| `ROBOCO_PR_REVIEWER_NOTES_MIN_CHARS` | `40` | Minimum characters for a PR reviewer's notes. |
-| `ROBOCO_QUICK_CONTEXT_MIN_CHARS` | `30` | Minimum characters for a PM's `quick_context` resumption section. |
-| `ROBOCO_COMMIT_SUBJECT_MIN_CHARS` | `20` | Minimum characters for a commit subject. |
-| `ROBOCO_COMMIT_BANNED_WORDS` | `wip,tmp,asdf,oops,fix,update,change,stuff,things` | Banned single-word commit subjects. |
-
-## Grok runtime
-
-Only relevant if you run any agent on Grok. See the [models section](../models/grok.md) for the full runtime.
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_HOST_GROK_DIR` | `/home/renzof/.grok` (compose) | Host `~/.grok` SuperGrok auth dir; mounted read-write into the orchestrator (token auto-refresh) and read-only into Grok agents. The same value is both the source and target path. |
-| `ROBOCO_GROK_AGENT_IMAGE` | `roboco-agent-grok:latest` | Image the orchestrator spawns for Grok agents. |
-| `ROBOCO_GROK_CLI_MODEL` | `grok-build` | Grok CLI model id. |
-| `ROBOCO_GROK_REASONING_EFFORT` | *(empty)* | `low`/`medium`/`high`/`xhigh`/`max` for all Grok agents; empty keeps the model default. |
-| `ROBOCO_GROK_MAX_TURNS` | `200` | Hard ceiling on agentic turns per Grok run (loop guard). |
-| `ROBOCO_GROK_IDLE_KILL_SECONDS` | `900` | (see reaper table) Idle-kill window for a wedged Grok container. |
-| `ROBOCO_GROK_MAX_COST_USD` | `0.0` | (see reaper table) Per-agent Grok cost ceiling. |
-
-## Optional subsystem flags (default-off unless noted)
-
-These gate the env-toggled capabilities. Each is inert when off. See [Optional capabilities](../optional/index.md).
-
-### Web research — default **on**
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_RESEARCH_ENABLED` | `true` | Master switch for web research. When `false`, the search MCP is not mounted into any agent. |
-| `ROBOCO_RESEARCH_PROVIDER` | `tavily` | `tavily` / `brave` / `exa` / `null`. |
-| `ROBOCO_RESEARCH_API_KEY` | *(unset)* | Provider key — **server-side only**, never reaches an agent. Unset = empty-result null provider. |
-| `ROBOCO_RESEARCH_MAX_RESULTS` | `5` | Cap on results per search (1–20). |
-| `ROBOCO_RESEARCH_FETCH_MAX_CHARS` | `20000` | Cap on extracted characters per fetch. |
-| `ROBOCO_RESEARCH_TIMEOUT_SECONDS` | `15.0` | Per-request outbound timeout. |
-| `ROBOCO_RESEARCH_DAILY_QUOTA_PER_AGENT` | `50` | Search+fetch calls per agent per UTC day. |
-
-### GitHub repo provisioning — default **on** (inert without token/org)
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_PROVISIONING_ENABLED` | `true` | Master switch for pitch auto-provisioning. Inert with no token/org regardless. |
-| `ROBOCO_PROVISIONING_TOKEN` | *(empty)* | GitHub PAT (repo + org admin) used to create repos — server-side only. |
-| `ROBOCO_PROVISIONING_ORG` | *(empty)* | GitHub org where new repos are created. |
-| `ROBOCO_GITHUB_API_BASE_URL` | `https://api.github.com` | Override for GitHub Enterprise. |
-| `ROBOCO_PROVISIONING_TIMEOUT_SECONDS` | `30.0` | Per-request provisioning timeout. |
-| `ROBOCO_PROVISIONING_REPO_PRIVATE` | `true` | Whether provisioned repos are private. |
-
-### Architectural conventions — **off** (config) / **on** (compose)
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_CONVENTIONS_ENABLED` | `false` (config) / `true` (compose) | Master switch for the per-project conventions standard (scaffold, ambient injection, baseline constraints, gate enforcement). The compose orchestrator block defaults this **on** (left off in `docker-compose.registry.yml`); fully inert when off. |
-
-### Toolchain matching — default **off**
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_TOOLCHAIN_MATCH_ENABLED` | `false` (config) / `true` (compose) | Provision the agent workspace with the target project's Python and block delivery gates when the suite can't run. The compose orchestrator block defaults this **on**. |
-
-### Provider overload break — default **on**
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_OVERLOAD_BREAK_ENABLED` | `true` | Park a provider on a persistent overload (HTTP 529/500/503) the way a 429 is parked, instead of crash-retrying. |
-| `ROBOCO_GATEWAY_HEALTH_ENABLED` | `true` | Probe a stale-heartbeat-but-live agent's gateway and kill + respawn it when the gateway is broken (a corrupted `/app` venv firing no verb), instead of the reaper protecting it forever. Off => spare live containers on verb-heartbeat liveness alone. |
-| `ROBOCO_GATEWAY_HEALTH_GRACE_SECONDS` | `180` | How long an agent gateway may probe as broken before recovery — tolerates a transient probe miss. |
-| `ROBOCO_IMAGE_PRUNE_ENABLED` | `true` | Background sweep prunes dangling (`<none>`) Docker images left by agent-image rebuilds, throttled ~6h. Only dangling images are removed — a tagged image or one backing a running container is never touched. Not a feature flag; disable to manage image cleanup yourself. |
-
-### Strategy engine — default **off**
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_STRATEGY_ENGINE_ENABLED` | `false` | Master switch for the autonomous strategy engine (notify-only). When off the loop never runs. |
-| `ROBOCO_STRATEGY_ENGINE_INTERVAL_SECONDS` | `1800` | Seconds between assessment passes. |
-| `ROBOCO_STRATEGY_STRANDED_BLOCKED_MINUTES` | `120` | A task blocked longer than this is surfaced as stranded. |
-
-### External / internal PR review — default **off**
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_EXTERNAL_PR_ENABLED` | `false` (config) / `true` (compose) | Master switch for inbound external/fork PR review. The compose orchestrator block defaults this on. |
-| `ROBOCO_EXTERNAL_PR_POLL_INTERVAL_SECONDS` | `300` | Seconds between inbound external-PR discovery passes. |
-| `ROBOCO_EXTERNAL_PR_AUTHOR_ALLOWLIST` | *(empty)* | GitHub usernames auto-trusted. Empty = every external PR needs human confirmation. |
-| `ROBOCO_EXTERNAL_PR_REQUIRE_HUMAN_CONFIRM` | `true` | Require explicit human confirmation before any agent fetches/checks-out/executes external code. |
-| `ROBOCO_INTERNAL_PR_ENABLED` | `false` | Also review org-repo (non-fork) PRs not tied to an active task. |
-
-### Self-healing CI loop — default **off**
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_SELF_HEAL_ENABLED` | `false` | Master switch for the self-heal loop (detect + notify the CEO). When off the loop never runs. |
-| `ROBOCO_SELF_HEAL_PROJECT_SLUG` | *(empty)* / `roboco-api` (compose) | The registered project that *is* RoboCo itself — the only repo the loop watches/originates into. |
-| `ROBOCO_SELF_HEAL_CI_WORKFLOW` | `ci.yml` | GitHub Actions workflow file to scope the CI signal to. |
-| `ROBOCO_SELF_HEAL_ORIGINATE_ENABLED` | `false` | Second opt-in: on a regression, also open a fix task and dispatch it to the Main PM automatically (no manual start). The loop never merges or deploys — the fix ships through the normal gates (QA, PR review, your merge). |
-| `ROBOCO_SELF_HEAL_INTERVAL_SECONDS` | `1800` | Seconds between telemetry passes. |
-| `ROBOCO_SELF_HEAL_MAX_OPEN_TASKS` | `3` | Rolling cap on concurrently-open self-heal tasks. |
-| `ROBOCO_SELF_HEAL_MAX_PER_CYCLE` | `1` | Max self-heal tasks originated in one cycle. |
-
-### Multi-repo CI-watch — default **off**
-
-The global switch arms the engine; each project opts in via `ci_watch_enabled` (+ optional `ci_watch_workflow`) in the edit-project dialog.
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_CI_WATCH_ENABLED` | `false` | Master switch for watching opted-in projects' CI. When off the engine never runs and no CI telemetry is fetched. |
-| `ROBOCO_CI_WATCH_DEFAULT_WORKFLOW` | `ci.yml` | Workflow file to scope the CI signal to when a project sets no `ci_watch_workflow` of its own. |
-| `ROBOCO_CI_WATCH_INTERVAL_SECONDS` | `1800` | Seconds between CI-watch passes. |
-| `ROBOCO_CI_WATCH_MAX_OPEN_TASKS` | `3` | Rolling cap on concurrently-open CI-watch fix tasks per repo. |
-| `ROBOCO_CI_WATCH_MAX_PER_CYCLE` | `1` | Max CI-watch fix tasks opened in one cycle. |
-
-### Dependency-update bot — default **off**
-
-The global switch arms the engine; each project opts in via `dep_update_command` (+ optional `dep_update_paths`) in the edit-project dialog. Detection is read-only — the command runs in a throwaway clone and only the lockfiles are diffed; the real repo is never mutated.
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_DEP_UPDATE_ENABLED` | `false` | Master switch for the dependency-update bot. When off nothing runs and no throwaway clone is made. |
-| `ROBOCO_DEP_UPDATE_INTERVAL_SECONDS` | `604800` | Seconds between dependency-update passes (default weekly). |
-| `ROBOCO_DEP_UPDATE_MAX_OPEN_TASKS` | `3` | Rolling cap on concurrently-open update-dependencies tasks per repo. |
-| `ROBOCO_DEP_UPDATE_MAX_PER_CYCLE` | `1` | Max update-dependencies tasks opened in one cycle. |
-
-### Gated release manager (default-off)
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_RELEASE_MANAGER_ENABLED` | `false` | Master switch for the gated release manager. When off the loop never runs and no release is proposed. Even on it only PROPOSES — the CEO approves before any publish. |
-| `ROBOCO_RELEASE_MIN_COMMITS` | `8` | Minimum unreleased commits since the last tag before a release is proposed (a feat/security change also qualifies). |
-| `ROBOCO_RELEASE_MANAGER_INTERVAL_SECONDS` | `3600` | Seconds between release-readiness assessment passes. |
-| `ROBOCO_RELEASE_CI_WORKFLOW` | `ci.yml` | GitHub Actions workflow file the release fail-closed CI gate scopes to. Decoupled from `ROBOCO_SELF_HEAL_CI_WORKFLOW` — the release gate always resolves a named workflow and never uses all-workflows mode. |
-
-### Organizational memory loop (default-off)
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_ORG_MEMORY_ENABLED` | `false` | Master switch for the org-memory loop. When off: legacy completion capture, no auto-inject, no playbook curation verbs. |
-| `ROBOCO_ORG_MEMORY_TOP_K` | `3` | Max institutional-memory items injected into a briefing on claim. |
-| `ROBOCO_ORG_MEMORY_MIN_SCORE` | `0.6` | Cosine-similarity floor for injected memory; below it, nothing is injected. |
-
-### Spawn preflight — **off** (config) / **on** (compose)
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_SPAWN_PREFLIGHT_ENABLED` | `false` (config) / `true` (compose) | Refuse to spawn a non-human delivery role that isn't in `GATEWAY_ENABLED_ROLES` — such a role gets no gateway manifest and could never claim its work, so the dispatcher would respawn it on the same task forever. On refusal the spawn is rejected (`AgentReadinessError`) and the overseer is alerted once. Inert in practice (every delivery role is gateway-enabled); a misconfiguration guardrail. Armed on the NAS composes, off in `docker-compose.registry.yml`. |
-
-### HTTP security (fastapi-guard)
-
-Default **off**. When off, `create_app` never mounts the middleware and the request path is byte-for-byte unchanged. See [HTTP security hardening](../optional/http-security.md) for the full picture. The NAS compose arms it in passive/log-only mode; enforcement (`ROBOCO_GUARD_PASSIVE_MODE=false`) is a deliberate later step after calibrating against real traffic.
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROBOCO_GUARD_ENABLED` | `false` | Master switch. On ⇒ `create_app` mounts `SecurityMiddleware` and the per-route guard decorators become active. |
-| `ROBOCO_GUARD_PASSIVE_MODE` | `false` | Detect-and-log without blocking — the calibration switch. Arm this first on live traffic to surface false positives, then set `false` to enforce. |
-| `ROBOCO_GUARD_FAIL_SECURE` | `true` | Fail **closed** when a security check itself errors (block the request). The personal/NAS compose overrides to `false` so a guard-internal bug never 500s your deploy. |
-| `ROBOCO_ENVIRONMENT` | `development` | Drives `enforce_https` — TLS is enforced only when set to `production`. |
-| `ROBOCO_GUARD_EMERGENCY` | `false` | Emergency lockdown: block every non-whitelisted IP. A flip-on-without-redeploy kill switch for an active attack. |
-| `ROBOCO_GUARD_EMERGENCY_WHITELIST` | *(empty)* | Comma-separated IPs / CIDRs always allowed during lockdown, in addition to loopback. |
-| `ROBOCO_GUARD_TELEMETRY_ENABLED` | `false` | Report security events/metrics to a guard-core platform via guard-agent. No data leaves the box while off. |
-| `ROBOCO_GUARD_AGENT_API_KEY` | *(empty)* | guard-core API key — telemetry only. |
-| `ROBOCO_GUARD_PROJECT_ID` | *(empty)* | guard-core project id — telemetry only. |
-
-## Next
-
- **[Production deploy](./deployment.md)** — compose files, host mounts, secure mode, startup.
- **[Optional capabilities](../optional/index.md)** — what each flag above turns on.
- **[Settings panel](../panel/settings.md)** — toggling flags from the UI instead of `.env`.
@@ -1,31 +0,0 @@
-# Configure & Deploy
-
-The reference layer beneath [Get Started](../get-started/index.md): the full configuration surface, the production deployment story, and how RoboCo's data and schema are managed.
-
-<div class="grid cards" markdown>
-
-   **[Deployment](deployment.md)**
-
-    ---
-
-    The compose files, the single-origin nginx, the host-path mounts, data persistence and backup, secure mode, and the startup sequence.
-
-   **[Environment reference](env-reference.md)**
-
-    ---
-
-    Every `ROBOCO_*` setting, by category, with its default and purpose — the canonical configuration reference.
-
-   **[Data & migrations](data-and-migrations.md)**
-
-    ---
-
-    The core data model, the pgvector requirement, and how the stack migrates itself on every boot.
-
-   **[Bootstrap & seeds](bootstrap-and-seeds.md)**
-
-    ---
-
-    What `make db-init` seeds — the agents, channels, and memberships a fresh company starts with.
-
-</div>
@@ -1,57 +0,0 @@
-# Register your first project
-
-A **project** is a git repository RoboCo is allowed to work on, plus the configuration that tells the company how to build and check it. Until you register one, the agents have nowhere to put their work. You register projects in the panel under **Projects → New**.
-
-## What a project needs
-
-| Field | What it is |
-|-------|-----------|
-| **Name** | Human-readable label for the repo. |
-| **Slug** | URL-safe short name. It becomes the top of the workspace path (`{slug}/{team}/{agent}/`) and shows up in branch names. |
-| **Git URL** | The clone URL. HTTPS is the common case and **requires a token** (below). |
-| **GitHub token (PAT)** | A Personal Access Token, stored encrypted. Required for private or HTTPS repos — see [The GitHub token](#the-github-token). |
-| **Assigned cell** | Which delivery cell owns this repo: Backend, Frontend, or UX/UI. |
-| **Default branch** | The branch PRs ultimately target. **Read [the default-branch gotcha](#the-default-branch-gotcha) before you save.** |
-| **Gate commands** *(optional)* | Per-project test / lint / format / typecheck / build commands, and a fast pre-submit `quality_command`. See [Gate commands](#gate-commands). |
-
-## The GitHub token
-
-Agents clone your repository and open pull requests on it, so they need a **GitHub Personal Access Token** with permission to do that.
-
- **Scopes:** the token needs repository **contents** access (to clone and push branches) and **pull request** access (to open and merge PRs). A classic `repo`-scoped token works; a fine-grained token needs *Contents: Read and write* and *Pull requests: Read and write* on the target repo.
- **It's encrypted and write-only.** The token is encrypted at rest the moment you save it (with your `ROBOCO_ENCRYPTION_KEY`) and the API **never returns it** — the panel only shows whether a token is set, not its value.
- **Rotating or clearing it:** in **Edit Project**, entering a new token replaces it, an empty field clears it, and leaving it untouched keeps the current one.
-
-!!! danger "HTTPS without a token fails"
-    If you give an HTTPS Git URL and no token, the clone fails — agents can't reach the repo. Set the token when you create the project.
-
-!!! warning "The encryption key is load-bearing"
-    Every stored project token is encrypted with `ROBOCO_ENCRYPTION_KEY`. If you ever change that key, all stored tokens become undecryptable and you'll have to re-enter every one. Pick it once at install and keep it backed up.
-
-## The default-branch gotcha { #the-default-branch-gotcha }
-
-The **Create Project** dialog defaults the branch to `main`, but several places in the backend assume `master`. **Set this field explicitly to match your repository's real default branch** (`main` or `master`) rather than trusting the pre-filled value. Getting it wrong is the most common first-run snag — branches get cut from, and PRs target, the wrong base.
-
-## Gate commands { #gate-commands }
-
-A developer agent runs a quality gate against its own work *before* it submits for QA. By default that's a sensible lint + typecheck pair, but you'll get far better results by pointing RoboCo at your repository's *real* checks:
-
- **`quality_command`** — the fast pre-submit gate, run at the moment an agent says it's done (for example `make gate`). If you set this, it replaces the default lint/typecheck pair. Keep it fast; it runs on every submission.
- **`test_command`, `lint_command`, `format_command`, `typecheck_command`, `build_command`** — the individual commands for the cell's QA and CI steps.
-
-Setting these so they mirror what *you* would run locally is the single biggest lever on output quality: the company gates itself exactly the way you would.
-
-## Sandboxing agents away from a repo
-
-If you want to make sure agents can never point a project at a particular repository — RoboCo's own source, say, during a test run — set `ROBOCO_PROTECTED_GIT_URLS` to a comma-separated list of URL substrings. Creating or updating a project whose Git URL matches one is rejected.
-
-## What happens under the hood
-
-You don't have to manage any of this, but it's worth knowing what registering a project sets in motion:
-
- The first time an agent is assigned work on the project, RoboCo clones the repo into that agent's own workspace under `ROBOCO_WORKSPACES_ROOT` (default `/data/workspaces`). **Every agent gets its own clone**, so they work in parallel without stepping on each other. That directory is the disk to provision and back up.
- Right after cloning, RoboCo **scrubs the token out of the clone's git config** and verifies no token byte survived anywhere under `.git/` — destroying the workspace if one did. Your PAT never lives inside an agent container.
-
-## Next
-
-→ **[Your first task](first-task.md)** — hand the company something to build.
@@ -1,46 +0,0 @@
-# Your first task
-
-With a project registered, you can hand the company work. The way in is the **Task Assistant** — the Intake agent — on the **Prompter** page. You give it a rough idea; it reads your *actual* codebase, asks a few sharp questions, and hands back a properly-formed task with an objective, a per-cell breakdown, and the acceptance criteria that define "done."
-
-## Draft a task with the assistant
-
-1. Open the **Prompter** page (the **Task Assistant**).
-2. Point it at the **project** you just registered (or a **product**, if you've mapped several repos together), and describe what you want — a feature, a fix, anything.
-3. It spins up an agent that **clones the scope and reads the real code** before it says a word, then comes back with a grounded proposal: what to build, where it should live, and the acceptance criteria — citing your actual files and pages.
-4. Refine it over a turn or two until the spec is right.
-
-When the proposal is ready, you choose on a single card:
-
- **Keep chatting** — keep refining the draft.
- **Board review & Start** — send it to the Product Owner and Head of Marketing to sharpen the requirements before any code is written.
- **Approve & Start** — hand it straight to the Main PM.
-
-!!! tip "You don't have to use the assistant"
-    The assistant is the easiest path, but a task is just a record. You can also create one directly through the API (`POST /api/tasks`) if you're scripting RoboCo — every task needs a title, a description, at least one acceptance criterion, a team, and a target project. The API reference covers the full schema.
-
-## What happens after you approve
-
-The moment you approve, the company takes over:
-
-1. The **Main PM** breaks the task into per-cell subtasks and sets the cells running.
-2. Each **cell PM** delegates to its developers, clears blockers, and triages.
-3. **Developers** build it in their own clones and open pull requests; **QA** reads the real diff and passes or fails it; **Documenters** write down what was built.
-4. A **PR reviewer** checks each assembled pull request before a PM merges it up the chain.
-5. The **Main PM** opens the final pull request into `master` and notifies you it's done.
-
-You can watch all of this live — on the **Kanban** board, the **Tasks** table, the **Communications** stream, and the **Command Center**. Nothing happens in the dark.
-
-## The two moments you're needed
-
-A whole feature only needs you at **two points**:
-
- **The green light at the start** — *Approve & Start* (or send it back).
- **The last call at the end** — the finished pull request lands in your **CEO Approval Queue**, where you **Approve & Merge**, **Request Changes**, or **Cancel**. Only you ever merge to `master`.
-
-Everything between those two moments is the company doing its job.
-
-## See it for real
-
-The best way to understand the whole journey is to watch one happen. **[The Tour](../how-to/README.md)** follows RoboCo building one of its *own* features — the Prompter you just used — from this same starting point all the way to a merged pull request, with screenshots at every step.
-
-To understand the machinery behind it — the roles, the gated lifecycle, the merge chain — read **[The Company](../company/index.md)**.
@@ -1,27 +0,0 @@
-# Get Started
-
-Three steps take you from a cloned repository to a company working on your code:
-
-1. **[Install & first run](installation.md)** — bring up the whole stack with Docker, set two secrets, and open the Command Center.
-2. **[Register your first project](first-project.md)** — point RoboCo at a git repository it's allowed to work on.
-3. **[Your first task](first-task.md)** — hand the company something to build and watch it go end to end.
-
-You don't need Python, Node, or a database on your machine — everything runs in Docker. The one thing you provide is a way for the agents to reach a model: by default that's the **Claude Code** session already on your host, so there's no API key to wire up.
-
-!!! tip "Prefer to watch first?"
-    The [26-minute intro](https://www.youtube.com/watch?v=t1QNqJgBmkM) and the [full panel walkthrough](../how-to/README.md) are the fastest way to get the shape of the thing before you install it.
-
-## What you'll need
-
-| You need | Why |
-|----------|-----|
-| **Docker** + **Docker Compose** | The entire stack (PostgreSQL, Redis, Ollama, the orchestrator, the panel, nginx) runs as containers. |
-| **A Claude Code auth directory** (`~/.claude`) | Mounted into the orchestrator so agents can reach the model. Run `claude` once on the host to create it. *(Or run the workforce on [Grok](installation.md#optional-run-on-grok-instead) instead.)* |
-| **A GitHub Personal Access Token** | One per project you register, so agents can clone it and open pull requests. You add this in the panel later, not now. |
-| **~10 GB of disk** and a few GB of RAM | The image set and the per-agent git clones. RoboCo is light at runtime — see the [resource notes](installation.md#resources). |
-
-## The shape of the system
-
-Everything is served behind a single address — **`http://localhost:3000`** — by an nginx reverse proxy. The browser only ever sees one origin; nginx routes `/api` and `/ws` to the orchestrator (FastAPI) and everything else to the Next.js control panel. That panel is your one window into the company.
-
-When you're set up and looking at the **Command Center**, head into [The Company](../company/index.md) to understand the org and the lifecycle, or take [the Tour](../how-to/README.md) to watch a real feature get built.
@@ -1,160 +0,0 @@
-# Install & first run
-
-This page takes you from nothing to the **Command Center** open in your browser. The whole stack runs in Docker, so the only things you install on the host are Docker itself and (for the default Claude backend) the Claude Code CLI.
-
-## 1. Authenticate the model backend
-
-By default every agent runs on Anthropic Claude, using the **Claude Code** session on your host rather than a metered API key. Authenticate once:
-
-```bash
-npm install -g @anthropic-ai/claude-code
-claude   # opens a browser to log in; creates ~/.claude
-```
-
-That `~/.claude` directory is mounted read-only into the orchestrator, which hands it to each agent container. If you'd rather run the workforce on Grok, skip this and see [Optional: run on Grok](#optional-run-on-grok-instead) below.
-
-## 2. Get the code
-
-```bash
-git clone https://github.com/rennf93/roboco.git
-cd roboco
-cp .env.example .env
-```
-
-## 3. Set the two required secrets
-
-Open `.env` and set these two — the orchestrator refuses to start without the first, and Docker deployments need the second:
-
-```bash
-# Encrypts every per-project GitHub token at rest (Fernet). REQUIRED.
-ROBOCO_ENCRYPTION_KEY=
-
-# Signs the per-agent auth tokens (HMAC). REQUIRED for docker compose.
-ROBOCO_AGENT_AUTH_SECRET=
-```
-
-Generate each one:
-
-```bash
-# ROBOCO_ENCRYPTION_KEY
-python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'
-
-# ROBOCO_AGENT_AUTH_SECRET
-python -c 'import secrets; print(secrets.token_hex(32))'
-```
-
-!!! danger "Keep `ROBOCO_ENCRYPTION_KEY` safe and stable"
-    This key encrypts the GitHub tokens you'll store per project. If you lose it or change it later, **every stored token becomes undecryptable** and must be re-entered. Back it up with your other secrets, and never commit `.env`.
-
-Everything else in `.env.example` has a working default for a local Docker run. On a NAS or remote server you'll also set the host-path variables (`ROBOCO_HOST_PROJECT_DIR`, `ROBOCO_HOST_CLAUDE_DIR`, `ROBOCO_DATA_DIR`) — those are covered in the deployment reference.
-
-## 4. Bring up the stack
-
-You have two ways to get the images. Both start from the clone above.
-
-=== "Pre-built images (quickest)"
-
-    Every release publishes all RoboCo images to both the GitHub Container Registry and Docker Hub, so you can run the full stack without building anything:
-
-    ```bash
-    docker compose -f docker-compose.registry.yml pull
-    docker compose -f docker-compose.registry.yml up -d
-    ```
-
-    Pick the registry and version with two variables (defaults shown):
-
-    ```bash
-    ROBOCO_REGISTRY=ghcr.io/rennf93   # or docker.io/renzof93
-    ROBOCO_VERSION=latest             # or a pinned release, e.g. 0.9.0
-    ```
-
-    The orchestrator pulls and spawns the matching pre-built agent images on demand — no build toolchain on your host.
-
-=== "Build from source"
-
-    The same stack, built locally from the Dockerfiles instead of pulled:
-
-    ```bash
-    docker compose up -d   # builds images on first run, then starts everything
-    ```
-
-The first start does real work: it pulls the local models into Ollama (the embedding model is quick; the local LLM is a couple of minutes), then the orchestrator waits for them, **runs the database migrations itself**, and indexes its knowledge base. You don't run migrations by hand — the stack brings its own schema up to date on every boot.
-
-## 5. Watch it come up
-
-```bash
-docker compose logs -f orchestrator
-```
-
-Wait until the orchestrator reports it's serving, then open:
-
-```text
-http://localhost:3000
-```
-
-That's the **Command Center** — per-cell health, the CEO approval queue, live metrics, and recent activity. The company is up; it's just idle because you haven't given it a repository or a task yet.
-
-!!! note "One address for everything"
-    nginx is the only externally-exposed service. It serves the panel and proxies `/api` and `/ws` to the orchestrator, so the browser sees a single origin at `:3000`. You generally won't hit the orchestrator's own port directly.
-
-## Next
-
-→ **[Register your first project](first-project.md)** — point RoboCo at a repository it's allowed to work on.
-
---
-
-## Optional: run on Grok instead
-
-RoboCo can run the entire workforce on **xAI Grok** using xAI's official `grok` CLI on a **SuperGrok subscription** — no metered API key, so a run can't stall mid-task on exhausted credits.
-
-```bash
-grok login                     # once, on the host — creates ~/.grok/auth.json
-```
-
-Then in `.env`:
-
-```bash
-ROBOCO_HOST_GROK_DIR=/home/youruser/.grok   # the real host ~/.grok to mount in
-# ROBOCO_GROK_AGENT_IMAGE=roboco-agent-grok:latest
-# ROBOCO_GROK_CLI_MODEL=grok-build
-# ROBOCO_GROK_REASONING_EFFORT=        # low|medium|high|xhigh|max (empty = model default)
-```
-
-The orchestrator keeps the short-lived Grok token refreshed for you, so agents don't hang on an expired login. Which agents run on which backend is set on the **Settings → AI Providers** page — that, and the per-role model assignments, are covered in the models section.
-
-## Optional: secure mode
-
-On a trusted LAN, RoboCo runs in **header-trust mode** by default: requests identify the caller by role headers, with no token required. That's fine on a private network and is the intended setup.
-
-If you need to harden it so an agent can't spoof another's role, set `ROBOCO_AGENT_AUTH_REQUIRED=true`, keep your `ROBOCO_AGENT_AUTH_SECRET`, and generate the panel's CEO token with `make panel-token` into `ROBOCO_PANEL_AGENT_TOKEN`. nginx injects that token so the panel keeps working without the browser holding the signing secret. The full security model is in the Configure & Deploy reference.
-
-!!! warning
-    Don't expose RoboCo to the public internet as-is. It's built to run on a trusted private network (homelab / LAN).
-
-## Resources { #resources }
-
-RoboCo is light at runtime. Agent containers are spawned on demand and torn down when their work is done, so you rarely have more than a handful live at once.
-
-| At idle (full stack, no task running) | RAM |
-|---------------------------------------|-----|
-| Ollama (models loaded) | ~2.2 GB |
-| Orchestrator | ~150 MB |
-| Postgres / Panel / Redis / nginx | ~120 MB combined |
-
-The whole standing stack idles around **~2.5 GB**, almost all of it Ollama. Under load — five agents working concurrently — the stack peaked around **~6.6 GB**; even at full-fleet peak you stay well under ~10 GB. **Storage is the larger footprint:** the agent images all build from a shared base layer, so on disk they cost far less than their nominal sizes summed. `docker system prune` reclaims old image versions, stopped containers, and build cache.
-
-```bash
-docker stats        # live RAM / CPU per running container
-docker system df    # image / container / build-cache disk usage
-```
-
-## Running on the host (for hacking on RoboCo itself)
-
-If you want to develop RoboCo's own code rather than just run it, you can run only the backing services in Docker and the app on your host. RoboCo's code needs **Python 3.13+** (`uv` fetches it if needed):
-
-```bash
-uv sync
-docker compose up -d postgres redis ollama   # backing services only
-uv run alembic upgrade head                    # migrate the database
-uv run python -m roboco.cli                    # API + orchestrator
-```
@@ -1,28 +0,0 @@
-# The shape of the company
-
-What keeps twenty-two agents from dissolving into noise is that RoboCo is relentlessly opinionated about *how* work happens: everything is a task, no task moves without acceptance criteria, and every task walks the same strict lifecycle — built, QA'd, documented, PM-reviewed, approved — each step gated by role. The structure is the point. It is what turns a roster of models into a company that actually ships.
-
-Work in RoboCo is always a **task**, and tasks nest into a tree that mirrors the org itself:
-
-```text
-CEO (you, the human)
- ├── Intake (on-demand interviewer — drafts a task with you)
- ├── Secretary (your chief-of-staff — acts only on your command)
- └── Board ── Product Owner · Head of Marketing · Auditor (silent) · PR Reviewer (inbound external PRs)
-      └── Main PM (coordinates the cells)
-           ├── UX/UI cell    ── PM · 2 Devs · QA · Documenter
-           ├── Frontend cell ── PM · 2 Devs · QA · Documenter
-           └── Backend cell  ── PM · 2 Devs · QA · Documenter
-```
-
-The walkthrough that follows traces the delivery path — Intake, the Board, the Main PM, the cells. The Secretary and the research and strategy engines sit one layer up, steering the company as a whole; they get their own chapter at the end.
-
-In practice, one feature becomes a small tree of work — a parent task at the top, a branch for each cell underneath, every node carrying its own status, git branch, and pull request:
-
-![The task tree for a feature: a Main PM parent task fanned out to UX/UI, Frontend, and Backend cell tasks, each with a live status and a GitHub branch.](../images/run.png)
-
-*A feature in motion. The parent task fans out to the UX/UI, Frontend, and Backend cells, and each child moves through its own lifecycle — in progress, awaiting review, completed — on its own branch.*
-
---
-
-Next: **[It starts with you →](02-it-starts-with-you.md)**
@@ -1,61 +0,0 @@
-# It starts with you
-
-## 1 · It starts with you
-
-You describe what you want — a feature, a fix, an entire product. The way in is the **Task Assistant** — which is the **Prompter** itself, the very feature whose build the rest of this guide follows. (You're about to use the tool RoboCo built for itself; further on, you'll watch the company build it.) Instead of filling a form from memory, you give it a rough idea and it reads your *actual* codebase, asks a few sharp questions, and hands back a properly-formed task — an objective, a per-cell breakdown, and the acceptance criteria that define what "finished" really means.
-
-![The Task Assistant's scope form: pick the project or product to work in, then describe what you want to build.](../images/start_prompter.png)
-
-*Where it starts — point the assistant at a project (one repo) or a product (several), drop in a rough idea, and it spins up an agent that reads that code before it says a word.*
-
-There is a third scope, **MegaTask**, for when you want several tasks at once across projects that don't share a codebase — the assistant proposes the whole batch and the company sequences it into conflict-free waves. See [MegaTask](../company/megatask.md).
-
-![The Task Assistant chat opening: the idea is in, and the agent is cloning the repo and reading the code before it answers.](../images/prompter_run_1.png)
-
-*No canned questions. The agent clones the scope and reads the real surface first, so everything it asks and proposes is grounded in what your code actually does.*
-
-<!-- Optional: re-capture prompter_run_2 after the markdown-rendering fix ships (its headers will render cleanly instead of as raw ###). -->
-![The agent's grounded analysis: a read of the existing surface, what's missing, where the feature should live, and a proposed shape — citing real files and pages.](../images/prompter_run_2.png)
-
-*It comes back having done the homework — naming the real pages, services, and files, laying out what to build and where, and refining with you over a couple of turns until the spec is right.*
-
-<!-- prompter_draft_card.png is the captured smoke shot; optionally re-capture after the draft-card cell-badge dedupe ships, for cleaner "Board-led across Backend Frontend" badges. -->
-![The draft proposal card: the finished task — objective, per-cell work, and acceptance criteria — with three choices: Keep chatting, Board review & Start, or Approve & Start.](../images/prompter_draft_card.png)
-
-*The proposal, ready to launch. Keep chatting to refine it, send it to the **Board** for review, or approve it straight to the Main PM — your call, on one card.*
-
-![The Task Assistant's confirmation: the task has been created and handed to the company.](../images/prompter_task_accepted.png)
-
-![The created task, live: its objective, the per-cell breakdown, status, and assignment — exactly as the company will work it.](../images/prompter_task_created.png)
-
-*From a rough sentence to a real, scoped task in a single chat — acceptance criteria and all, already moving through the company.*
-
-From here, every task follows the path you chose for it. To show that journey end to end, the rest of this guide follows the **Prompter's own** trip through the company — from this same starting point to a merged pull request. Send a task to the **Board** and their job is to pin it down: the Product Owner and Head of Marketing turn the draft into a settled spec, sharpening the requirements and the acceptance criteria before anyone writes a line of code. The Auditor watches the whole time but never interferes.
-
-![A Board review session: the Product Owner writing out requirements and acceptance criteria for a task.](../images/chat_session.png)
-
-*The Product Owner working a task over — pinning down the requirements and the must-haves before anyone writes a line of code.*
-
-![A Board review session for the Prompter feature, with the Product Owner and Head of Marketing each recording their take — positioning, naming, the model-selector UX — against the task.](../images/po_hom_review.png)
-
-*Two seats at the table. The Product Owner and the Head of Marketing review the same task from their own angles and put their reasoning on the record — this is the Board building the actual spec for the Prompter, the feature this whole walkthrough follows.*
-
-## 2 · Nothing moves without your green light
-
-The Board hands the reviewed task back to you as a **notification** and waits. You make one call: send it forward, or send it back. Approve it, and the **Main PM** picks it up, splits it across the cells, and sets them running.
-
-![The board-review notification waiting on the CEO's decision to start the work or send it back.](../images/notifications.png)
-
-*The Board's verdict lands in your notifications and pauses there. A single approval is what turns the whole company on.*
-
-![The board-review-complete notification for the Prompter task: the Product Owner and Head of Marketing have both reviewed it, and it is now ready for the CEO's Approve & Start decision or rejection.](../images/ceo_review_notif.png)
-
-*The notification itself, spelled out: the Board has finished, the task is recorded, and nothing happens until you say so — Approve & Start hands it to the Main PM; reject it and it goes back. This is the first of the only two moments the company needs you.*
-
-![The CEO's pending-approval queue with a task card showing the green "Approve & Start" button.](../images/approve_task.png)
-
-![The task detail panel opened from the approval queue, with the Approve & Start action alongside the task brief.](../images/approve_task_detail.png)
-
---
-
-Previous: **[← The shape of the company](01-the-company.md)** · Next: **[The cells build it →](03-the-cells-build-it.md)**
@@ -1,37 +0,0 @@
-# The cells build it
-
-## 3 · The cells take over
-
-Underneath the Main PM are three cells — **UX/UI, Frontend, Backend** — each a small team with its own PM. Those PMs run their cells like engineering managers: parcelling out the work, clearing blockers, and stepping in when something stalls. UX/UI usually leads and sets the contracts; Frontend and Backend build against them.
-
-![The Dev Kanban: cards moving from Backlog through Ready, Assigned, In Progress, and Blocked.](../images/kanban.png)
-
-*A cell at work, seen as a board — tasks flow from backlog to done, and the role tabs let you watch it from the developer's, QA's, or PM's seat.*
-
-## 4 · The work gets done — and checked
-
-This is where it's actually built. Developers write the code and open pull requests from their own branches. QA doesn't rubber-stamp — it reads the real diff and decides whether the work ships or comes back for another pass. Documenters write down what was built so the next agent (and you) aren't starting cold. None of it happens in the dark: agents narrate their reasoning as they go, and each keeps a running journal of what it learned and why it chose what it chose.
-
-![A task's notes after a QA review: the developer's notes, a QA section marked Failed, and a silent Auditor column — all on the same task.](../images/qa_fail.png)
-
-*QA earning its seat. On this Prompter task it read the work, marked it **failed**, and sent it back — the developer's notes and the QA verdict sit side by side on the record, with the Auditor watching the whole exchange. Real review, not a rubber stamp; the gate only opens when the work is right.*
-
-![Agent Journals: per-agent reflections, decision logs, and learnings.](../images/journaling.png)
-
-*Every agent keeps a journal — reflections, decisions, and lessons. Between that and the Documenters, there's a paper trail for everything the company does.*
-
-## 5 · The work converges
-
-Once a cell's piece is green and documented, its PM folds those branches up into the Main PM's integration branch. Three independent streams of work come back together into one. Each task brings its branch, pull request, commits, and docs along with it:
-
-![A completed task showing its branch, pull request, commits, and documentation.](../images/task_details.png)
-
-*One finished unit — branch, pull request, commits, and docs all attached. This is the thing that travels up the merge chain.*
-
-![The integrated pull request's commit list: one verified commit per cell — the UX/UI design specs and the backend chat endpoint — each co-authored by the agent that wrote it.](../images/opened_final_pr_commits.png)
-
-*Three streams becoming one history. Each cell's work lands as its own **verified** commit, co-authored by the agent that wrote it — the UX/UI design, the backend endpoint, the frontend page — folded together into the single pull request that comes back to you.*
-
---
-
-Previous: **[← It starts with you](02-it-starts-with-you.md)** · Next: **[The last call — and the loop →](04-the-last-call-and-the-loop.md)**
@@ -1,45 +0,0 @@
-# The last call — and the loop
-
-## 6 · The last call is yours
-
-The cells' work is folded up, the Main PM opens the **final pull request** into `master`, and the company goes quiet. The decision comes back to exactly where it started — with you. You're the only one who ever touches `master`, and anything waiting on you sits in the **CEO Approval Queue** until you act.
-
-![The final CEO approval notification: the integrated Prompter PR is ready, all three cells delivered and QA-passed, awaiting the CEO's review and merge.](../images/ceo_approval_notif.png)
-
-*The hand-off back to you. The integrated PR is open, every cell has delivered, QA is green — and it waits. Nothing reaches `master` without your word.*
-
-![The integrated pull request open on GitHub, in the repository's Pull Requests list.](../images/opened_final_pr.png)
-
-*And it is a real pull request, on the real repository — not a simulation. The company's work shows up exactly where any engineer would look for it.*
-
-![The pull request's description: the objective, what the task builds, the per-cell breakdown, and the notes the company wrote for it.](../images/opened_final_pr_body.png)
-
-*Open it and the whole brief is there — the objective, what was built, the board-led split across the three cells, and the company's own notes — written by RoboCo, for you to read before you decide.*
-
-![The pull request's Files changed tab: the actual diff — migrations, API, and panel components — the company is asking to merge.](../images/opened_final_pr_changes.png)
-
-*The real diff, laid out for you to inspect — the migrations, the endpoints, the panel components. This is the substance you are signing off on.*
-
-![The CEO's actions on the awaiting-approval task: Approve & Merge, Request Changes, or Cancel.](../images/approve_button_merge_rework.png)
-
-*Your two words. **Approve & Merge** and it ships to `master`; **Request Changes** and it goes around for another lap. The last call has the same shape as the first — one decision, yours alone.*
-
-## The other queue: PRs you didn't open
-
-Not every pull request comes from inside the company. When someone opens a PR against your repo — an external contributor, a fork — the read-only **PR Reviewer** picks it up, reads the diff against your standards, and posts a single change-request directly on the PR (it never chats, never merges, never decides). The PR then surfaces in the **PR Review Queue** on the Command Center — your second decision surface. There you **Supersede** it: the company cuts its own branch from the contributor's commits, hardens the work to your standards, opens its own PR, and — once that replacement merges — closes and links the original. Or you **Dismiss** it. Either way the call is yours, and the org never pushes to anyone else's fork.
-
---
-
-## And round it goes
-
-You handed the company a task; it scoped it, built it, failed and re-ran its own QA, documented it, and brought it back as a single pull request for your sign-off. That's one complete pass.
-
-![The full task table for the Prompter feature: a parent task awaiting CEO approval over its completed UX/UI, Frontend, and Backend child tasks.](../images/all_tasks_final_state.png)
-
-*The whole tree in its final state — the parent waiting on your approval, every cell's task done beneath it. One feature, start to finish, with you at only the two ends.*
-
-And the feature in these screenshots is the proof. The **Prompter** wasn't built for a demo — it's a real page RoboCo's agents shipped to RoboCo's own control panel. A company building its own product, in front of you, is the whole point of RoboCo. What makes that hold together isn't a clever model or a lucky run; it's the **organization** — the roles, the gated lifecycle, the reviews and the sign-offs that keep twenty-two agents moving as a company instead of a crowd. Run as many of these passes as you like, across as many projects as you like.
-
---
-
-Previous: **[← The cells build it](03-the-cells-build-it.md)** · Next: **[The business workflow →](05-the-business-workflow.md)**
@@ -1,55 +0,0 @@
-# The business workflow
-
-The first four chapters follow one task through the company. But a company isn't only its task queue — it has a direction, a budget, and a reason every task exists. That layer lives in the **Business** tab, and it is how you steer the whole organization rather than one job at a time.
-
-## The charter
-
-The charter is the company's standing context: its **north star**, its **objectives**, the **constraints** it must respect, and the **operating policy** it works under. You write it once in the Business tab and revise it whenever the direction shifts. It isn't decoration — the charter is threaded into every agent's briefing, into the pitches the Board produces, and into what the Secretary is allowed to act on. Set it well and every agent inherits the same sense of what the company is for; leave it empty and they only know the task in front of them.
-
-<!-- Screenshot to capture: the Business tab charter editor with the north-star / objectives / constraints / operating-policy fields filled in. -->
-
-## The Cockpit
-
-Where the charter says what the company *should* be doing, the Cockpit shows what it *is* doing — the company reflected back against its own charter. It surfaces spend against budget and the signals worth your attention: drift from the stated objectives, agents sitting idle, work that has been blocked too long. It is the one screen that answers "is the company on course?" without your having to read every task.
-
-<!-- Screenshot to capture: the Cockpit with spend-vs-budget and the signals panel. -->
-
-## The Company Scorecard
-
-On the Business tab's Goals view sits the Company Scorecard — live performance against the charter in one card. Where the Cockpit surfaces signals to act on, the Scorecard is the one-glance answer to "how is the company actually doing?": what's been delivered, spend against budget, the median lead time from task to merge, and progress on the objectives you set. It is the company's vital signs, read off the same work the rest of the panel tracks.
-
-## The Secretary
-
-The Secretary is your conversational chief-of-staff. You chat with it the way you'd brief a human one — ask it where things stand, or dictate a change to the charter. What it never does is act on its own: every directive it derives from your instruction is **gated**, landing in a queue for your explicit confirmation before anything happens. It reads the whole company's state to advise you, but it spends nothing, builds nothing, and approves nothing until you say the word. It is leverage with a safety catch — your intent, executed, but only after you confirm it.
-
-<!-- Screenshot to capture: a Secretary chat dictating a charter tweak, and the resulting gated directive awaiting confirmation in the queue. -->
-
-## Web research and the strategy engine
-
-Two capabilities run above the day-to-day. Both are **off by default** and master-switched from **Settings → Feature Flags** in the panel — the switch persists and takes effect on the next backend restart. The environment variables below are the same toggles at the source, and still carry the parts the panel deliberately doesn't surface (the research provider and its API key, which never leave the server). Their effect shows up inside agent runs once enabled.
-
-### Web research
-
-Flip **Web research** on in Settings → Feature Flags (or set `ROBOCO_RESEARCH_ENABLED=true`), choose a provider with `ROBOCO_RESEARCH_PROVIDER` (`tavily`, `brave`, or `exa`), and supply `ROBOCO_RESEARCH_API_KEY`. With that in place, the Board and PM agents gain `web_search` and `web_fetch` through the `roboco-search` MCP server — so a Product Owner scoping a feature can ground it in the live web, not just your codebase. The API key stays server-side; the agents never see it and never make the external call themselves. Leave it off and the tools simply aren't there — a no-op.
-
-### The strategy engine
-
-Flip **the strategy engine** on in Settings → Feature Flags (or set `ROBOCO_STRATEGY_ENGINE_ENABLED=true`) and a background loop begins watching the company against its charter. When it spots drift from the objectives, agents gone idle, or work blocked for too long, it tells you. It is **notify-only by design**: it never spends, never builds, never approves — it raises the flag and leaves the decision where every decision belongs, with you. Off, it is fully dormant.
-
-### The self-healing CI loop
-
-The same shape, pointed inward: flip **self-healing** on in Settings → Feature Flags (or set `ROBOCO_SELF_HEAL_ENABLED=true`) and RoboCo begins watching its **own** repository's CI. When a run regresses it tells you. Turn on the second switch (`ROBOCO_SELF_HEAL_ORIGINATE_ENABLED=true`) and it goes one step further — it opens a fix task for the regression and hands it straight to the Main PM, who coordinates the repair. It never merges or deploys that work itself: the fix still flows through the normal gates — dev, QA, PR review, and **your** merge — so the company can repair its own build autonomously while the decision to ship stays yours. Both switches are off by default, and it watches only the one repo you name as RoboCo itself.
-
-## Feel the whole thing
-
-The cleanest way to understand this layer is to walk it once, end to end:
-
-1. Open the **Business** tab and set the charter — north star, a couple of objectives, your constraints, the operating policy.
-2. Open the **Cockpit** and watch the company reflected against it — spend against budget, and the signals as they appear.
-3. Chat the **Secretary** and dictate one change to the charter. Watch the gated directive land in the queue, and confirm it — that round trip, from your sentence to a confirmed action, is the whole shape of how you steer RoboCo from above.
-
---
-
-Previous: **[← The last call — and the loop](04-the-last-call-and-the-loop.md)** · Back to **[the index](README.md)**
-
-*RoboCo is early-stage, work-in-progress software (v0) — expect rough edges. The [Get Started guide](../get-started/index.md) covers setup, configuration, and the security model.*
@@ -1,31 +0,0 @@
-# How RoboCo works
-
-![Twelve-second looping preview of the RoboCo control panel — the org tree, a task in progress, and an approval queue.](../videos/panel-teaser.gif)
-
-RoboCo is a virtual software company — 25 AI agents and one human: you. Not a swarm of bots, not a framework to wire together — an **organization**, with roles, a chain of command, formal reviews, and sign-offs. You don't micromanage it; you run it like a CEO. Drop work in at the top and the company carries it all the way through planning, building, review, and documentation, then brings it back to your desk for the final word. You act at the two ends; the organization fills in everything between.
-
-And the proof is this guide. The screenshots throughout aren't a mock-up: they follow RoboCo building one of its *own* features — the **Prompter**, the task-authoring page now living in this very control panel. RoboCo's agents scoped it, built it across three cells, failed and re-ran its QA, documented it, and opened the real pull request you'll see at the end. RoboCo builds RoboCo — that is the whole proof of concept.
-
-> The panel is your one window into the company. Every task, agent, message, journal, and pull request is live in front of you.
-
-**Prefer video?** A [full screen-recording of the panel](../videos/panel-full-walkthrough.mp4) walks through every page and detail end-to-end — useful as a first tour before diving into the screenshots.
-
-![The RoboCo Command Center: per-cell health, the CEO approval queue, live metrics, auditor alerts, and recent activity.](../images/overview_dashboard.png)
-
-*The **Command Center** — a glance tells you how each cell is doing, what's waiting on your approval, how fast work is moving, and what just happened.*
-
---
-
-## Read it in order
-
-This guide follows one task — the Prompter's own build — from a rough idea to a merged pull request, then steps back to the strategic layer you steer the whole company with.
-
-1. **[The shape of the company](01-the-company.md)** — the org, and how every piece of work is a task that nests into a tree.
-2. **[It starts with you](02-it-starts-with-you.md)** — drafting a task with the assistant, the Board review, and your first green light.
-3. **[The cells build it](03-the-cells-build-it.md)** — the three cells, the Dev Kanban, real QA, journals, and the integration branch.
-4. **[The last call — and the loop](04-the-last-call-and-the-loop.md)** — the final pull request, the CEO Approval Queue, the merge, and round it goes.
-5. **[The business workflow](05-the-business-workflow.md)** — the charter, the Cockpit, the Secretary, and the research and strategy engines that run above the day-to-day.
-
---
-
-*RoboCo is early-stage, work-in-progress software (v0) — expect rough edges. The [Get Started guide](../get-started/index.md) covers setup, configuration, and the security model.*
--- a/Show More
+++ b/Show More