diff --git a/.pan/continues/PAN-5499.xbrief.json b/.pan/continues/PAN-5499.xbrief.json new file mode 100644 index 00000000000..548348d3774 --- /dev/null +++ b/.pan/continues/PAN-5499.xbrief.json @@ -0,0 +1,234 @@ +{ + "version": "1", + "issueId": "PAN-5499", + "created": "2026-11-19T02:52:23.250Z", + "updated": "2026-11-19T03:26:20.066Z", + "gitState": {}, + "decisions": [], + "hazards": [], + "resumePoint": null, + "sessionHistory": [ + { + "reason": "feedback", + "note": "[2026-11-19T03:26Z] coderabbit → FINDINGS — seq 1", + "timestamp": "2026-11-19T03:26:20.065Z" + } + ], + "items": { + "intro-audit": { + "status": "completed", + "claimedBy": "agent-pan-5499", + "claimedAt": "2026-11-19T02:52:23.250Z", + "doneAt": "2026-11-19T02:53:21.755Z" + }, + "intro-audit.ac1": { + "status": "completed", + "doneAt": "2026-11-19T02:53:21.755Z" + }, + "intro-audit.ac2": { + "status": "completed", + "doneAt": "2026-11-19T02:53:21.755Z" + }, + "intro-audit.ac3": { + "status": "completed", + "doneAt": "2026-11-19T02:53:21.755Z" + }, + "intro-audit.ac4": { + "status": "completed", + "doneAt": "2026-11-19T02:53:21.755Z" + }, + "quickstart-audit": { + "status": "completed", + "claimedBy": "agent-pan-5499", + "claimedAt": "2026-11-19T02:53:25.911Z", + "doneAt": "2026-11-19T02:54:56.189Z" + }, + "quickstart-audit.ac1": { + "status": "completed", + "doneAt": "2026-11-19T02:54:56.189Z" + }, + "quickstart-audit.ac2": { + "status": "completed", + "doneAt": "2026-11-19T02:54:56.189Z" + }, + "quickstart-audit.ac3": { + "status": "completed", + "doneAt": "2026-11-19T02:54:56.189Z" + }, + "quickstart-audit.ac4": { + "status": "completed", + "doneAt": "2026-11-19T02:54:56.189Z" + }, + "quickstart-audit.ac5": { + "status": "completed", + "doneAt": "2026-11-19T02:54:56.189Z" + }, + "concepts-command-deck": { + "status": "completed", + "claimedBy": "agent-pan-5499", + "claimedAt": "2026-11-19T02:55:05.339Z", + "doneAt": "2026-11-19T02:56:04.875Z" + }, + "concepts-command-deck.ac1": { + "status": "completed", + "doneAt": "2026-11-19T02:56:04.875Z" + }, + "concepts-command-deck.ac2": { + "status": "completed", + "doneAt": "2026-11-19T02:56:04.875Z" + }, + "concepts-command-deck.ac3": { + "status": "completed", + "doneAt": "2026-11-19T02:56:04.875Z" + }, + "concepts-command-deck.ac4": { + "status": "completed", + "doneAt": "2026-11-19T02:56:04.875Z" + }, + "concepts-pipeline-and-rest": { + "status": "completed", + "claimedBy": "agent-pan-5499", + "claimedAt": "2026-11-19T02:56:11.513Z", + "doneAt": "2026-11-19T02:57:35.282Z" + }, + "concepts-pipeline-and-rest.ac1": { + "status": "completed", + "doneAt": "2026-11-19T02:57:35.282Z" + }, + "concepts-pipeline-and-rest.ac2": { + "status": "completed", + "doneAt": "2026-11-19T02:57:35.282Z" + }, + "concepts-pipeline-and-rest.ac3": { + "status": "completed", + "doneAt": "2026-11-19T02:57:35.282Z" + }, + "concepts-pipeline-and-rest.ac4": { + "status": "completed", + "doneAt": "2026-11-19T02:57:35.282Z" + }, + "concepts-pipeline-and-rest.ac5": { + "status": "completed", + "doneAt": "2026-11-19T02:57:35.282Z" + }, + "vision-autonomy-and-merge": { + "status": "completed", + "claimedBy": "agent-pan-5499", + "claimedAt": "2026-11-19T02:57:38.972Z", + "doneAt": "2026-11-19T02:59:33.525Z" + }, + "vision-autonomy-and-merge.ac1": { + "status": "completed", + "doneAt": "2026-11-19T02:59:33.525Z" + }, + "vision-autonomy-and-merge.ac2": { + "status": "completed", + "doneAt": "2026-11-19T02:59:33.525Z" + }, + "vision-autonomy-and-merge.ac3": { + "status": "completed", + "doneAt": "2026-11-19T02:59:33.525Z" + }, + "vision-autonomy-and-merge.ac4": { + "status": "completed", + "doneAt": "2026-11-19T02:59:33.525Z" + }, + "vision-criteria-and-appendix": { + "status": "completed", + "claimedBy": "agent-pan-5499", + "claimedAt": "2026-11-19T02:59:40.259Z", + "doneAt": "2026-11-19T03:02:29.469Z" + }, + "vision-criteria-and-appendix.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:02:29.469Z" + }, + "vision-criteria-and-appendix.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:02:29.469Z" + }, + "vision-criteria-and-appendix.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:02:29.469Z" + }, + "vision-criteria-and-appendix.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:02:29.469Z" + }, + "changelog-intro": { + "status": "completed", + "claimedBy": "agent-pan-5499", + "claimedAt": "2026-11-19T03:02:34.289Z", + "doneAt": "2026-11-19T03:03:22.867Z" + }, + "changelog-intro.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:03:22.867Z" + }, + "changelog-intro.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:03:22.867Z" + }, + "changelog-intro.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:03:22.867Z" + }, + "changelog-intro.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:03:22.867Z" + }, + "recapture-doc-shots": { + "status": "completed", + "claimedBy": "agent-pan-5499", + "claimedAt": "2026-11-19T03:03:27.022Z", + "doneAt": "2026-11-19T03:12:57.136Z" + }, + "recapture-doc-shots.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:12:57.136Z" + }, + "recapture-doc-shots.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:12:57.136Z" + }, + "recapture-doc-shots.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:12:57.136Z" + }, + "recapture-doc-shots.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:12:57.136Z" + }, + "validate-and-pr-body": { + "status": "completed", + "claimedBy": "agent-pan-5499", + "claimedAt": "2026-11-19T03:13:00.892Z", + "doneAt": "2026-11-19T03:15:57.535Z" + }, + "validate-and-pr-body.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:15:57.535Z" + }, + "validate-and-pr-body.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:15:57.535Z" + }, + "validate-and-pr-body.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:15:57.535Z" + }, + "validate-and-pr-body.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:15:57.535Z" + } + }, + "feedback": [ + { + "seq": 1, + "specialist": "coderabbit", + "outcome": "findings", + "timestamp": "2026-11-19T03:26:20Z", + "markdownBody": "# CodeRabbit findings for PAN-5499 (PR #5580)\n\nCodeRabbit posted 6 inline finding(s). CodeRabbit is advisory: nothing waits for these,\nbut each one gets an answer, either a fix or a reply with your reason.\n\n- Thread 4623953087 · .pan/drafts/PAN-5499.md:284 [Minor]: Describe the global setting as an inherited default.\n https://github.com/eltmon/overdeck/pull/5580#discussion_r4623953087\n- Thread 4623953089 · .pan/drafts/PAN-5499.md:313 [Minor]: Resolve the prohibited changelog edits before prescribing WI-5.\n https://github.com/eltmon/overdeck/pull/5580#discussion_r4623953089\n- Thread 4623953093 · changelog.mdx:2 [Minor]: Keep direct edits out of the changelog header.\n https://github.com/eltmon/overdeck/pull/5580#discussion_r4623953093\n- Thread 4623953097 · changelog.mdx:8 [Minor]: Include the installed package version in the sync startup gate.\n https://github.com/eltmon/overdeck/pull/5580#discussion_r4623953097\n- Thread 4623953100 · vision.mdx:104 [Minor]: Align the bot identity with the operating prompts.\n https://github.com/eltmon/overdeck/pull/5580#discussion_r4623953100\n- Thread 4623953104 · vision.mdx:132 [Major]: Describe the global setting as a fallback, not an unconditional hold.\n https://github.com/eltmon/overdeck/pull/5580#discussion_r4623953104\n\n## What to do\n\n1. Read each thread (open its link, or the code at the path and line).\n2. If you agree with a finding, fix it.\n3. If you reject a finding, reply on its thread with your reason:\n `gh api repos/eltmon/overdeck/pulls/5580/comments//replies -f body=\"\"`\n4. If you changed code: run the quality gates on what you touched, commit, push, then run `pan review request PAN-5499 -m \"CodeRabbit : \"`.\n If you only replied, you are done.\n5. If PR #5580 has already merged when you read this, stop: after the merge Overdeck files a follow-up issue\n for every thread with no reply, no later commit to its file, and no re-review request naming its thread id." + } + ] +} diff --git a/.pan/drafts/PAN-5499.md b/.pan/drafts/PAN-5499.md new file mode 100644 index 00000000000..1ae52b3a66b --- /dev/null +++ b/.pan/drafts/PAN-5499.md @@ -0,0 +1,398 @@ +# PAN-5499: accuracy audit of Getting Started, Vision and the Changelog intro + +**Issue:** https://github.com/eltmon/overdeck/issues/5499 (part of epic #5467, docs overhaul) +**Priority:** P1. Docs-only change, plus a recapture of three shared screenshots. No code change, no `changelog.d` entry. +**Base:** `main` at `919cc020249` (v0.89.1 plus later merges), 2026-11-18. Every PR the issue says to wait for has +merged into this base: #5472 (PR #5535), #5480 (PR #5545), #5470 (PR #5554) and #5468 (PR #5538). PAN-5505 (PR #5528) +also rewrote `introduction.mdx`. So each page is audited on top of those results. + +## Summary + +The issue asks for a line-by-line accuracy audit of five published pages: `introduction.mdx`, `quickstart.mdx`, +`concepts.mdx`, `vision.mdx` and the intro of `changelog.mdx`. The planning session already did the audit: it read every +claim on the five pages against current code, `pan --help` and the dashboard source, and re-checked each wrong +claim by grep. This PRD lists every wrong, stale or removed claim per page with the current text (a grep anchor), the +replacement text and the code evidence. The implementation agent applies the changes, removes en and em dashes, fixes +frontmatter, recaptures the three screenshots that still show the old "Panopticon v0.21.0" brand, checks links, runs the +Mintlify validators and writes a PR body with one note per page. It does not re-research; it re-checks a claim only when a +grep anchor no longer matches. + +## Glossary + +- **Audited pages**: `introduction.mdx`, `quickstart.mdx`, `concepts.mdx` (the `Getting Started` group in `docs.json`, + line 37 to 39), `vision.mdx` (the `Roadmap` group, `docs.json` line 208) and `changelog.mdx` (the `Changelog` tab, + `docs.json` line 220). All five are at the repo root. +- **Changelog intro**: the part of `changelog.mdx` above the first `` blocks below it are release + records written by `pan release stable` and are out of scope (Decision D1). +- **Claim**: any statement a reader could act on: a command or flag, a config key or default, a UI label or location, a + file path, a behavior, a limit, a list of supported harnesses, trackers or platforms, or a maturity label. +- **Primary source**: the code on the base (`git grep`), `pan --help`, `src/lib/config-yaml/defaults.ts`, the + dashboard source under `src/dashboard/frontend/src/`, and `changelog.mdx`. Other `.mdx` pages, `docs/*.md` and + `README.md` are never proof. +- **Grep anchor**: the quoted current text in each change table. Line numbers drift as edits land, so find the text with + `grep -n -F '' .mdx`, not by line number. +- **Dash rule**: no U+2013 (en dash) or U+2014 (em dash) in a touched page, in frontmatter and body. Check: + `! grep -nP '[\x{2013}\x{2014}]' .mdx` exits 0. Replace a dash with a comma, colon, period, parentheses, or the + word "to" for a range. The one exception is a verbatim UI string inside a changelog release record (Decision D1). +- **Frontmatter rule**: `title` is specific and searchable; `description` is 50 to 160 characters (the text between the + quotes); neither contains a dash. A retitled page keeps a short `sidebarTitle`. +- **Test role**: the pipeline role that runs tests and browser UAT on a PR. Today nothing starts it automatically after + review approves (open bug #5537). CI tests on the PR head still gate the merge. `features/issue-pipeline.mdx` line 80 + already states this. +- **Doc shot**: a docs screenshot pair `-light.png` and `-dark.png`, produced by + `node scripts/capture-doc-shot.mjs ` against a running dashboard and shown with the + `` snippet. +- **Follow-ups**: code bugs or out-of-scope doc problems the audit found. They go in a `## Follow-ups` list in the PR body. + This issue changes no code. +- **PR note**: one line per page saying what changed, or "verified, no change". Each page item puts it in its commit + message as `PR-note: .mdx: `; WI-7 collects the notes into the PR body. + +## Background and evidence + +**Before state** (dash lines from the dash-rule grep; description lengths without quotes): + +| Page | Lines | Dash lines | Title | Description chars | +| --- | --- | --- | --- | --- | +| introduction | 83 | 0 | What is Overdeck | 157 | +| quickstart | 118 | 0 | Install Overdeck and start your first agent | 137 | +| concepts | 146 | 0 | Overdeck concepts | 127 | +| vision | 236 | 24 | Flywheel Vision | 149 | +| changelog (intro) | 11 | 0 (1 in a release record, line 611) | Changelog | 61 | + +**Validators.** `npx -y mint@4.3.49 validate` and `npx -y mint@4.3.49 broken-links` pass on `main` +(`.overdeck/context/codebase/concerns.md`, entry "`npx mint validate` and `npx mint broken-links` pass on `main`"). That +entry lists what breaks them: a bare `` in prose outside backticks (MDX reads it as a JSX tag), an unquoted +frontmatter `description` containing `: `, an `import ... from "react"` line, and relative links to files `.mintignore` +excludes. `npm run lint:docs` (`scripts/lint-docs.js`) also fails on an Upcoming/Unreleased block in `changelog.mdx` +(`scripts/lint-docs.js:157-163`). + +**Code that reads these pages.** `src/lib/release/changelog-fold.ts` and `src/cli/commands/release.ts:554-610` fold +`changelog.d/` entries into `changelog.mdx` above the newest `` block; the fold depends on the `` blocks are dated release records produced by `pan release stable`; rewriting them would change history. The + em dash at `changelog.mdx:611` is inside the verbatim UI string "Held handoff — kickoff not sent", which the code still + renders (`src/dashboard/frontend/src/components/chat/HeldHandoffView.tsx:64`), so it stays. The PR note says so. +- **D2 (test role)**: on `introduction.mdx` and `concepts.mdx`, state only what is true whether or not #5537 lands: review + agents check the work, and the PR needs approval and green checks before it merges. Link `/features/issue-pipeline` for + the details. `features/specialists.mdx` still promises a test agent on every PR; that page belongs to #5502 and goes in + Follow-ups. +- **D3 (vision scope)**: correct current-state facts on `vision.mdx`: file references, the bot login, the pickup + predicate, setting names and storage, commands, gates and the merge and UAT model. Keep the operator's direction as is: + the v1.0 targets and thresholds, the definitions, the industry anchors, and open questions that are still open. Where a + criterion has no measurement today, say so in one sentence rather than deleting the target. +- **D4 (code bugs)**: when the code is wrong rather than the doc, the page states what the code does and the bug goes to + Follow-ups. Never describe intended behavior as current. +- **D5 (screenshots)**: recapture the hero, board and pipeline pairs in place with `scripts/capture-doc-shot.mjs` (WI-6). + Same file names, so every page that uses them gets the new image. **Implementation checkpoint:** if no dashboard is + reachable at `https://overdeck.localhost` (or `--base http://localhost:3011`), or Playwright cannot launch, keep the old + PNGs, still fix the alt text on the audited pages to describe current UI facts only where the old image already shows + them, and add a Follow-up "recapture hero, board and pipeline doc shots". Never edit image pixels by hand. +- **D6 (one PR)**: all items commit to `feature/pan-5499`; one PR. +- **D7 (titles)**: retitle only where a work item says so. Slugs and file names never change. +- **D8 (other pages' alt text)**: after WI-6, other pages that use the recaptured images may carry alt text that no longer + matches. They belong to #5501 (CLI) and #5502 (Features). WI-7 lists them in Follow-ups and posts one comment on each of + #5501 and #5502 naming the changed images. It edits none of those pages. + +## Repo rules that apply + +- Work only inside `workspaces/feature-pan-5499` on branch `feature/pan-5499`; never `git checkout` another branch; never + `git stash`. +- One commit per item with an `Item: ` trailer and its AC trailers, plus the `PR-note:` line. `pan task done` + checks the trailer on the pushed commit, so push before calling it. +- Docs-only: do not run the full `npm test`. The checks are the dash grep, `npm run lint:docs`, and (in WI-7) + `npx -y mint@4.3.49 validate` and `npx -y mint@4.3.49 broken-links`. +- Never run a destructive HTTP request, and run no `pan` command other than `--help` while verifying a claim. +- Browser work (WI-6) uses its own Playwright browser instance, as `capture-doc-shot.mjs` already does + (`chromium.launch`); never attach to another agent's browser. +- Issue and PR references in page prose are markdown links (`[#5537](https://github.com/eltmon/overdeck/issues/5537)`). + +## Common procedure for every page item + +0. **Code wins.** If a primary source contradicts a row (main moved), skip the row, say so in the PR note, and leave that + row's AC open with the evidence (`pan task block` with the reason). Never write a claim the code contradicts. +1. **Apply the change table.** For each row, find the anchor with `grep -n -F`, make the change. If an anchor no longer + matches, find the claim by meaning; if it is gone, skip the row and note it. +2. **Spot-check before deleting.** Before deleting a section, re-run the row's evidence grep once. +3. **Residual rule.** Read the whole page once. For a claim the table does not list that looks doubtful, verify it against + a primary source and fix the page to match the code. The rows marked "Verified, keep" need no re-check. +4. **Dashes.** Remove every en and em dash on the page (changelog: intro only) in the same commit. +5. **Frontmatter.** Apply the title change if any; confirm the description is 50 to 160 characters and dash-free; quote a + `description` that contains `: `. +6. **Links.** For each internal link, `ls .mdx` (and `grep -n "^#.*"` for an anchor), counting + `docs.json` redirects. +7. **MDX safety.** Keep any new `` placeholder inside backticks. +8. **Commit** with `Item: `, AC trailers and `PR-note: .mdx: `; push; `pan task done`. + +## Work items + +xBRIEF item map: WI-1 = `intro-audit`; WI-2 = `quickstart-audit`; WI-3 rows 1 to 6 = `concepts-command-deck`, rows 8 to 18 +plus page-wide checks = `concepts-pipeline-and-rest`; WI-4 rows 1 to 9 and 20 = `vision-autonomy-and-merge`, rows 10 to 19 +plus dashes and frontmatter = `vision-criteria-and-appendix`; WI-5 = `changelog-intro`; WI-6 = `recapture-doc-shots`; +WI-7 = `validate-and-pr-body`. + +Each page is one file; items on different files are independent and may run in parallel. WI-6 (screenshots) touches the +alt text of `introduction.mdx`, `quickstart.mdx` and `concepts.mdx`, so it runs after WI-1, WI-2 and WI-3 (shared +mutation). WI-7 runs last. + +### WI-1: `introduction.mdx` + +| # | Grep anchor (current text) | Change | Evidence | +| --- | --- | --- | --- | +| 1 | `It needs Node.js 22 or later` | Replace with `It needs Node.js 22.16 or later`. | `package.json:80-81` (`"node": ">=22.16.0"`); `src/lib/database/driver.ts:281` ("Overdeck requires Node 22.16+ or Node 24+ for the bundled SQLite driver"). Quickstart already says 22.16. | +| 2 | `Review agents and a test agent check the work, and the pull request waits for you to click Merge unless you turn on auto-merge.` | Replace with: `Review agents check the work. The pull request merges when it is approved and its checks are green: you click Merge, or auto-merge does it for you.` Keep the existing links and add `[the issue pipeline](/features/issue-pipeline)` first in the "See" list. | D2; #5537; `features/issue-pipeline.mdx:80`. | +| 3 | `Issues come from GitHub, Linear, GitLab, Rally or Jira.` | Replace with `Issues come from GitHub, Linear, Rally or Jira, and code can live on GitHub or GitLab.` | `src/lib/tracker/gitlab.ts:39` (GitLab tracker is a stub: `notImplemented('GitLab tracker is not yet implemented. Coming soon!')`); `configuration/issue-trackers.mdx:3,14`. | +| 4 | Verified, keep | Harness list (`HOME_AGENT_LABELS`, `src/dashboard/frontend/src/components/home/homeComposerIntents.ts:12-23`); Flywheel "early" (`features/flywheel.mdx:3`); skills on or off per project, issue or conversation (`pan skills set --help` has `--project`, `--issue`; `components/newConversation/ConversationSkillsField.tsx` sends `skillOverrides`); history dates (`git log`: first commit 2026-01-17, `@panctl/cli` 2026-04-27 in `9369c085799`, `@overdeck/core` 2026-06-20 in `032f9d3733d`); install script runs with no sudo into `~/.local` (`scripts/install.sh:8,17`). | | +| 5 | Image alt text | Handled by WI-6. | | + +Frontmatter: keep title `What is Overdeck`; the description (157 chars) stays. + +### WI-2: `quickstart.mdx` + +| # | Grep anchor (current text) | Change | Evidence | +| --- | --- | --- | --- | +| 1 | `4. **Pick an issue and start work.** Select an open issue on the kanban board, and Overdeck creates an isolated workspace for the agent.` | Replace with: `4. **Pick an issue and start work.** Open an issue from the **Board**. If it has no plan yet, choose **Plan…** first; once it is planned, start it from the **▶ Start** chip on its card or the start button in its issue view. Or run `pan start `, which plans the issue if needed and then starts work. Starting creates an isolated workspace and a work agent.` | Selecting an issue creates nothing. Start is offered only for planned issues: `src/dashboard/frontend/src/lib/issueActions.ts:535` (`canStartAgent = … state.hasPlan && state.hasTasks …`); the card chip comes from `components/issue-view/StartAgentCta.tsx:66` (`▶ Start · ${issueId}` when `surface === 'chip'`, used at `components/KanbanBoard/cards/KanbanCards.tsx:708`); the issue view label is `Start work agent` and Simple mode's is `Start work` (`components/simple/SimpleIssuePage.tsx:100`); the Plan action label is `Plan…` (`lib/issueActions.ts:615`); `pan start --help`. | +| 2 | `A conversation keeps its model once it starts. To use another model, [hand off to a new conversation](/features/conversations#why-hand-off).` | Replace with: `A conversation keeps its model once it starts, except a Pi conversation, which can switch model while it runs. To use another model, [hand off to a new conversation](/features/conversations#why-hand-off).` | `src/lib/overdeck/conversation-runtime.ts:435-445` (`livePiSwitch`; "Conversation model is locked once a conversation has started"). | +| 3 | `The board is the usual place to pick an issue. Each card carries a cost badge, a live agent status dot and workspace controls, so you can start or check in on an agent without leaving the column it lives in.` | Replace with: `The Board is the usual place to pick an issue. Each card carries a cost badge, its pipeline phase and a **▶ Start** or **▶ Resume** chip when the agent can start or resume, so you can start or check in on an agent without leaving the column it lives in.` | `IssueCard` in `components/KanbanBoard/cards/KanbanCards.tsx:550` onward: the cost badge button (`card-cost-…` test id, about line 680), the phase rail (`phaseRailState`, about line 588), `StartAgentCta … surface="chip"` (line 708), labelled `▶ Start` or `▶ Resume` (`StartAgentCta.tsx:61-66`). The card has no agent status dot or workspace controls. | +| 4 | `Under the hood: an Effect.js and TypeScript server, a React frontend over typed WebSocket RPC, SQLite for state, and Electron as the shell.` | Replace with: `Under the hood: an Effect.js and TypeScript server, a React frontend over typed WebSocket RPC, SQLite for local data such as conversations and settings, and Electron for the desktop app.` | The Cut (`changelog.mdx` v0.60.0): pipeline state is read live from git, the tracker, the PR and the terminal backend, so "SQLite for state" is wrong. `src/lib/database/driver.ts:277` (`node:sqlite`); `app_settings` table (`src/lib/overdeck/control-settings.ts:128-131` or `git grep -n "FROM app_settings"`). Electron is only the desktop app (`apps/desktop/package.json:8`); the browser dashboard has no shell. | +| 5 | `Overdeck started as a CLI and grew into **Command Deck**, a desktop-class development environment.` | Replace with: `Overdeck started as a CLI and grew into a dashboard, with **Command Deck** as its main view.` | Command Deck is one dashboard view (`features/mission-control.mdx` title; nav item in the hero image). Keep the rest of the paragraph. | +| 6 | Verified, keep | npx starts the dashboard on port 3011 (`pan up` default; CLAUDE.md "port 3011"); install-script bullets (`scripts/install.sh:15-17,48-58,69-125,131-134`); `overdeck up --detach`/`--no-open` (`pan up --help`); `overdeck install` installs Herdr, mkcert, ttyd and ast-grep (`src/cli/commands/install.ts`); Get set up card and "Finish setup so agents can start" (`components/home/GetSetUpCard.tsx`, `lib/simple/strings.ts:113`); Home opens in Simple mode on a fresh browser (`lib/simple/uiMode.ts:28-31`); Enter asks an agent, Ctrl+Enter runs a terminal (`components/home/homeComposerIntents.ts:33-36`); "Add a project" in the composer chip and the project switcher (`HomeComposerProjectChip.tsx:59`, `components/frame/ProjectSwitcher.tsx:237`); desktop downloads and `@overdeck/desktop` (`npm view @overdeck/desktop version` → 0.89.1). | | +| 7 | Image alt text | Handled by WI-6. | | + +Frontmatter: keep title and description (137 chars). The page already has `## Get help` with Discord and GitHub Issues. + +### WI-3: `concepts.mdx` + +All paths below are under `src/dashboard/frontend/src/` unless they start with `src/lib` or `src/dashboard/server`. +Every WRONG row was re-checked by grep on the base (labels: `Stage/PaneTabMenu.tsx:52-67`, `App/topbar/AgentsMenu.tsx:41-43`, +`CommandDeck/ConversationActionMenu.tsx:251`, `sessionFeed/SessionFeedSidebar.tsx:130-132`, `App/appChromeLabels.ts:44-46` +for Ctrl+K and ⌘K, `CostBreakdownModal.tsx:38-45`). + +| # | Grep anchor (current text) | Change | Evidence | +| --- | --- | --- | --- | +| 1 | `the project crumb, a project-scoped search, and status pills at a glance (Deacon health, running-agent count, stopped agents). No more persistent banners; attention items surface as compact pills.` | Replace with: `the project crumb, a search box that opens the command palette (Ctrl+K, or ⌘K on a Mac), an **N agents working** menu, **Needs you**, chips that appear only when something is wrong (Deacon frozen, stopped agents, low-cost mode, a stale build), and a system health menu.` | `App/AppChrome.tsx:195-225` renders `Breadcrumb`, `AgentsMenu`, `NeedsYouIndicator`, `DeaconFrozenChip`, `StoppedAgentsBanner variant="pill"`, `LowCostModePill`, `StaleBuildChip`, `SystemHealthPill`; `App/topbar/AgentsMenu.tsx:41-43` ("agents working"). No Deacon health pill. Banners still mount (`App/AppChrome.tsx:83-100`: `ShutdownBanner`, `RestartApprovalBanner`, `GitHubRateLimitBanner`, `SetupChecklistBanner`, `ClaudeCodeUpgradeBanner`, …), so "No more persistent banners" is wrong. | +| 2 | `right-click to pop out to a window or close others` | Replace with: `right-click a tab to split it right or down, close it, or close all tabs; drag a conversation's tab off the bar, or use **Pop out to window** in its ⋮ menu, to open it in its own window` | `components/Stage/PaneTabMenu.tsx:11-17` (`onOpenInSplit`, `onSplitDown`, `onCloseTab`, `onCloseAll`; labels "Split right", "Split down", "Close tab", "Close all tabs"); `components/Stage/PaneBar.tsx:49-52`; `components/CommandDeck/ConversationActionMenu.tsx:251` ("Pop out to window"). | +| 3 | `A project's **Home cockpit** (issue swimlanes, recent spend, a stuck count)` | Replace with: `A project's **Home** (facts for agents working, needs you, in review, landed this week and spend this week, then the pipeline lanes, the merge train and recent changes)` | `components/Stage/HomePane/HomeFacts.tsx:131-142` (`Agents working`, `Needs you`, `In review`, `Landed this week`, `Spend this week`); `components/CommandDeck/pipeline-helpers.ts:339-344` (lanes); `ProjectHome.tsx:214,218` (`MergeTrain`, `RecentChanges`). No stuck count. | +| 4 | Both tab lists: `(Conversation, Tasks, Plan, Changes, Activity, Discussion, Skills, Details)` (line 17) and `Conversation, Tasks, Plan, Changes, Activity, Discussion, Skills and Details.` (line 36) | Insert `Decisions (Deft projects only)` between Activity and Discussion in both. | `components/issue-detail/issueTabs.ts:15` (`{ id: 'decisions', label: 'Decisions' }`); `IssueDetail.tsx:191` (`if (!isDeft) hidden.add('decisions')`). | +| 5 | `with **Needs-you / Project / Global** scopes` | Replace with `with **Needs you / Project / Global** scopes (Project appears when a project is selected)`. Also replace `All lists what changed (created, ended, reported, merged) rather than every busy conversation` with `All lists activity events and the conversations that started or ended in the last day`. | `components/sessionFeed/SessionFeedSidebar.tsx:130-133`; `useMergedFeed.ts:8,30-33`. | +| 6 | `Everything is alive: no refresh buttons.` | Replace with `Views update live from domain events, so you rarely need to refresh.` | 29 frontend files import `RefreshCw` (`git grep -l RefreshCw -- src/dashboard/frontend/src | wc -l`). | +| 7 | `On most harnesses a conversation's model is fixed once it starts; Pi conversations can switch model in place.` | Verified, keep. | `src/lib/overdeck/conversation-runtime.ts:435-445`. | +| 8 | `- **Review and test agents**: check finished work on the pull request` | Replace with `- **Review agents**: review the pull request. The project's tests run as a check on the PR, on CI for most projects.` | D2; #5537; `src/lib/cloister/service-reactive.ts:66,376` (only `review.approved` starts the test role, and nothing emits it). | +| 9 | `Workspaces support both local execution and remote execution via Fly.io for cloud-hosted agent environments.` and `Workspaces can include Docker containers for full development environments. Supports both local execution and remote execution via Fly.io.` | Keep the first sentence and append `Start a remote one with \`pan start --remote\`.` In `### Docker Integration`, delete the repeated second sentence so the section reads only `Workspaces can include Docker containers for full development environments.` Keep both headings. | `pan start --help` (`--remote Use remote workspace (Fly.io)`). | +| 10 | `When a work agent finishes, a review agent and a test agent check the work on the pull request.` | Replace with `When a work agent finishes, the verification gate runs the project's checks on its pull request and a review agent reviews it.` Keep the next sentence (Merge or auto-merge) and the issue-pipeline link. | D2; `src/lib/cloister/ci-failure-feedback.ts:15`; `features/issue-pipeline.mdx` (verification gate). | +| 11 | Pipeline image `alt="Pipeline page: a metric strip (Active issues, Work running, Review queue, Ship, Spend) above phase-grouped issue rows for Ship, Review, and Verifying, with an activity feed on the right"` | Replace with `alt="Pipeline page: a metric strip (Active issues, Work running, Review running, Ship, Spend) above issue rows grouped by phase: Ship, Review, Work, Plan and Ready"`. WI-6 adjusts it if the new capture shows otherwise. | `components/Pipeline/PipelineView.tsx:416-420` (eyebrows); `lib/pipeline-state.ts:105` (`PIPELINE_BOARD_PHASES = ['ship', 'review', 'work', 'plan', 'ready']`); `components/primitives/PhaseHeader.tsx:10-15`. PipelineView imports no feed component (`PipelineView.tsx:19-25`). | +| 12 | `a metric strip across the top (Active issues, Work running, Review queue, Ship, Spend) sits over issue rows grouped by phase (Ship, Review, Verifying) with a live activity feed alongside.` | Replace with `a metric strip across the top (Active issues, Work running, Review running, Ship, Spend) sits over issue rows grouped by phase: Ship, Review, Work, Plan and Ready.` | Same as row 11. | +| 13 | `Turn it on with \`roles.review.mode: full\`.` | Replace with `Turn it on with \`roles.review.mode: full\`; the default, \`quick\`, runs one review agent.` | `src/lib/cloister/review-agent.ts:924` (`configMode === 'full' \|\| configMode === 'none' ? configMode : 'quick'`). | +| 14 | `Overdeck integrates with 5 issue trackers:` and the row `- **GitLab Issues**: Issue tracking and MR management` | Replace the lead with `Overdeck integrates with 4 issue trackers:`. Delete the GitLab row. After the list add: `GitLab issue tracking is not supported yet; GitLab works as a code host, and Overdeck opens and merges its merge requests. See [Issue trackers](/configuration/issue-trackers).` | `src/lib/tracker/gitlab.ts:39` (`notImplemented('GitLab tracker is not yet implemented. Coming soon!')`, 8 stub methods); `configuration/issue-trackers.mdx:14` already says this. | +| 15 | `The dashboard displays issues from all configured trackers in a unified kanban board` | Replace `a unified kanban board` with `one kanban board, the **Board**,`. Keep the rest. | Nav label `Board` (`components/frame/navGroups.ts:30`). | +| 16 | `- Dollar costs per stage (planning, work, review, test, merge)` and `- Daily cost summaries on the Board view` | Replace with `- Dollar costs per stage (planning, implementation, review, testing, merge, and interactive conversations)` and `- Daily cost trends on the **Costs** page, an experimental view (Settings → Experimental)`. | `components/CostBreakdownModal.tsx:38-45` (stage keys); `CostsPage.tsx:67,152` (`DailyTrend`); `lib/experimentalFeatures.ts:12` (`'costs'` in `EXPERIMENTAL_TAB_IDS`). | +| 17 | `- [Cloister](/features/cloister) - Understand the AI lifecycle manager` and the other four Next Steps lines (` - ` separators) | Replace the Cloister text with `How the agent watchdog keeps agents moving`, and use `: ` instead of ` - ` between link and text on all five lines. | Line 58 of the page calls Cloister "the agent watchdog"; consistency. | +| 18 | `` `pan start --plan skip` skips planning. `` | Replace with `` `pan start --plan skip` skips the planning agent and builds a minimal xBRIEF from the issue body. `` | `pan start --help` (`--plan ` interactive, auto, skip; `--auto` "[deprecated: use --plan skip] … synthesizing a minimal xBRIEF from the issue"). | +| 19 | Verified, keep | Project sidebar and left column (`components/frame/LeftColumn.tsx:3-6`); tab strip scroll and middle-click close (`Stage/PaneBar.tsx:84,193`); split by dragging to a pane edge (`Stage/PaneLayoutView.tsx:9`); issue view title row, pipeline strip with checks and pickup controls (`issue-view/IssuePipelineStrip.tsx:125`), Details contents (`issue-detail/IssueDrawerDetails.tsx:222-312`); `/activity` Feed tab (`App/routes.ts:18`, `ActivityPanel.tsx:49`); All / Chats / Activity tabs and the 24-hour window; gauntlet run card; "vs main" (`components/DiffPanel.tsx:566`); fork and hand off (`CommandDeck/ForkModal.tsx:209`); xBRIEF DAG (`xbrief/DagRenderer.tsx`); agent types; REST API; Cloister behaviors (`src/lib/cloister/deacon-lite.ts:616-630`); `.pan/` planning; branch and workspace paths; three workhorse slots (`src/lib/config-yaml/schema.ts:380`); more than 120 skills (126 `sync-sources/skills/*/SKILL.md`); `pan sync` targets (`src/lib/paths.ts:59`); four convoy reviewers (`src/lib/cloister/review-monitor.ts:22`); GitHub, Linear, Rally, Jira Cloud and Data Center (`src/lib/tracker/`); all linked pages exist. | | + +Frontmatter: retitle to `title: "Overdeck concepts: Command Deck, agents, workspaces and the pipeline"`; keep +`sidebarTitle: "Concepts"` and the description (127 chars). The page has no help section; add none. + +Concepts ACs: `grep -E "Review queue|Verifying|Deacon health|stuck count|5 issue trackers|GitLab Issues|Board view|a test agent" concepts.mdx` +prints nothing; `grep -F "Ship, Review, Work, Plan and Ready" concepts.mdx` matches the paragraph (and the alt text, unless the D5 +fallback removed the pipeline image); +`grep -F "Decisions (Deft projects only)" concepts.mdx` matches twice. + +### WI-4: `vision.mdx` + +Apply D3. Every row below was re-checked by grep on the base. + +| # | Grep anchor (current text) | Change | Evidence | +| --- | --- | --- | --- | +| 1 | `the per-run *what* lives in \`docs/flywheel-brief.md\`. When the role or` ... `fix the role or the brief.` (lines 7 to 9) | Replace the paragraph's second and third sentences with: `The loop's operating prompt is the [\`pan-flywheel\` skill](https://github.com/eltmon/overdeck/blob/main/sync-sources/skills/pan-flywheel/SKILL.md), and a bound order book under \`.pan/orders/\` sets the scope of a run. If the role or the skill drifts from this page, this page wins: fix the role or the skill.` | `docs/flywheel-brief.md` does not exist (`ls docs/flywheel-brief.md` fails; deleted in `7b953449633`). `sync-sources/skills/pan-flywheel/SKILL.md` exists. | +| 2 | `` `author.login` is `panopticon-agent[bot]` (the Overdeck GitHub App) `` | Replace the login with `overdeck-agent[bot]`. | `src/lib/github-app.ts:6` ("e.g. `overdeck-agent[bot]`"); issues the App files show author `app/overdeck-agent`. `roles/flywheel.md:100` and `sync-sources/skills/pan-flywheel/SKILL.md:98` still say `panopticon-agent[bot]`: Follow-up (code/prompt bug). | +| 3 | `It applies *always*,` / `regardless of any toggle, and has no relaxation flag.` | No change. Planning found the rule only in `roles/flywheel.md:99-104` and the skill, not in two dispatch files, but did not prove that repo-wide, so the page adds nothing about enforcement. | Keep. | +| 4 | `the Flywheel works only in-flight work plus emergency \`blocks-main\`` ... `**Releasing** them.` | Replace the OFF bullet's first two sentences with: `**OFF (dev-loop today):** the Flywheel works in-flight issues and the issues the operator releases, either with the \`released\` label or by adding them to the active order book.` Keep the sentence about planning ready backlog. | `src/lib/backlog/pickup.ts:122` (`const released = s.released \|\| autoPickupBacklog \|\| activeBookMember;`). No dispatch path picks up `blocks-main`; `blocksMain` is only classified (`pickup.ts:97`). | +| 5 | `` `needs-discussion`, `objection` (an AI relevance hold), and the relevance-vet. `` | Replace with: `` `needs-discussion` (the legacy spellings of `parked`) and `objection` (an AI relevance hold). `` | `git grep -i "relevance.vet" -- src` prints nothing. `pickup.ts:36-44` (`VETOED_LABEL`, `OBJECTION_LABEL`, `LEGACY_PARKED_LABELS = ['needs-design','needs-discussion']`). | +| 6 | `bounded by \`roles.flywheel.maxAgents\`.` | Replace with `` bounded by `roles.flywheel.maxAgents` (default 30). `` | `src/lib/config-yaml/roles.ts:61-65` (`maxAgents: 30`). | +| 7 | `ready && planned && (released \|\| auto_pickup_backlog) && !parked && !vetoed && !objection && !inPipeline && !epic` (indented code line) | Replace with `ready && planned && (released \|\| auto_pickup_backlog \|\| activeBookMember) && !parked && !vetoed && !objection && !inPipeline && !epic`. | `pickup.ts:122-123`. | +| 8 | `operator toggles (persisted in the \`app_settings\` SQLite` | Keep, and name the keys: `(persisted as \`flywheel.auto_pickup_backlog\` and \`flywheel.require_uat_before_merge\` in the \`app_settings\` SQLite table, user-machine level)`. | `src/lib/overdeck/control-settings.ts:124-131` (find with `git grep -n "flywheel.require_uat_before_merge" -- src/lib`). | +| 9 | Section `### UAT-required-before-merge` body from `"Human merges" and "human UATs" are independent constraints.` through `The model we want for v1.0 is "relax UAT for trusted work, but a human always owns the merge."` | Replace the body (keep the heading) with the text in **Vision replacement V1** below. | No "UAT passed" mark exists; a held issue is never auto-scheduled (`src/dashboard/server/services/auto-merge-scheduler.ts`); the merge gate blocks only on a failed UAT verdict, and only when the issue is held (`src/lib/cloister/pr-facts.ts:971`, `if (policy.uatRequired && facts.uatVerdict?.status === 'failed')`; `uatRequired` comes from `defaultUatRequired` in `src/lib/cloister/merge-gate.ts:99`, which applies the hold tiers). Three-tier hold resolution: `src/lib/cloister/auto-merge-policy.ts:4-8`. Fixed 5-minute cooldown: `src/lib/cloister/auto-merge-config.ts:1` (`AUTO_MERGE_COOLDOWN_MS = 300_000`). Kill switch `OVERDECK_DISABLE_AUTO_MERGE=1` (`git grep -n OVERDECK_DISABLE_AUTO_MERGE -- src/dashboard/server/main.ts`). | +| 10 | `Pipeline pass** — a single end-to-end completion: plan → work → review → test → merge.` | Replace with: `**Pipeline pass**: a single end-to-end completion: plan, work, review, tests, merge. Tests run as CI on the PR head; the automatic test-agent step after review does not run today ([#5537](https://github.com/eltmon/overdeck/issues/5537)).` Keep the following sentence. | D2; #5537. | +| 11 | Table rows 1 to 7 in `## v1.0 readiness criteria`: each metric name links `docs/FLYWHEEL.md` | Keep the targets and anchors (D3). Remove the links on criteria 3 to 7. After the table, add: `Overdeck measures criteria 1 and 2 today with \`pan flywheel stats\`: criterion 1 as substrate bugs (issues labeled \`substrate-improvement\`) filed per merged PR. Criteria 3 to 7 have no telemetry yet.` | `pan flywheel --help` lists `stats`; `src/lib/flywheel/substrate-stats.ts:7-8,30` (find with `git grep -n "substrate-improvement" -- src/lib`); `packages/contracts/src/flywheel-stats.ts:64-67` holds only `c1_bugRate` and `c2_p0Bugs`. | +| 12 | `## The path there` paragraphs: `tracked by the \`v1.0-required\` GitHub label, which is the` ... `Live critical path:` | Replace the first paragraph and the quote with: `The \`v1.0-required\` GitHub label marks work on the path to v1.0. It has no open issues right now: [\`v1.0-required\` issues](https://github.com/eltmon/overdeck/issues?q=is%3Aissue+label%3A%22v1.0-required%22).` | `gh issue list -R eltmon/overdeck --label v1.0-required --state open` prints nothing (2026-11-18). Implementation checkpoint: re-run it; if it now lists open issues, keep "marks work" and drop "It has no open issues right now". | +| 13 | `Substrate bugs` / `declare affected v1.0 criteria via the \`Flywheel-Affects-Criterion\` trailer; \`pan flywheel weights --json\`` ... `weight model.` | Delete the two sentences about the trailer and `pan flywheel weights`, and the `docs/FLYWHEEL.md` pointer for them. Replace with: `\`pan flywheel stats --json\` reports the substrate-bug rate and the P0 count.` Keep the first sentence of the paragraph and the last sentence ("The Flywheel and the backlog sequencer prioritize substrate-hardening epics first...") because `src/lib/backlog/sequencer-agent.ts:346` cites it. | `pan flywheel --help` has no `weights`; `git grep -n "Flywheel-Affects-Criterion" -- src roles sync-sources` prints nothing. | +| 14 | `- **Per-issue UAT override.** Once the global \`require_uat_before_merge\` flag exists` (bullet) | Delete the bullet. | The global flag exists (`control-settings.ts`); per-issue `auto-merge` and `hold-for-uat` labels (`src/dashboard/frontend/src/components/AutoMergeToggle.tsx:7-9`) and the project `auto_merge_default` cover it (`auto-merge-policy.ts:4-8`). | +| 15 | `- **Substrate-bug label.** A dedicated \`substrate-bug\` label for visibility` (bullet) | Delete the bullet. | Stats already count the `substrate-improvement` label (`substrate-stats.ts:30`); the trailer provenance it contrasts with no longer exists. | +| 16 | `- \`docs/flywheel-brief.md\`: the **per-run scope contract**` (appendix bullet) | Replace with: `- [\`sync-sources/skills/pan-flywheel/SKILL.md\`](https://github.com/eltmon/overdeck/blob/main/sync-sources/skills/pan-flywheel/SKILL.md): the tick loop, and \`.pan/orders/\`: the order books that scope a run.` | File missing; skill exists. | +| 17 | `- \`docs/FLYWHEEL-STATE.md\`: durable cumulative memory` (appendix bullet) | Replace with: `` - `.pan/flywheel/state.md`: the loop's memory across runs, and `.pan/flywheel/report.md`: the latest run report. `` | `docs/FLYWHEEL-STATE.md` is missing; `roles/flywheel.md:42`; `pan flywheel report --help` names `.pan/flywheel/report.md`. | +| 18 | `` [`packages/contracts/src/flywheel.ts`](...): the `` / `` `FlywheelStatus` schema the orchestrator emits each tick. `` | Replace with: `` [`packages/contracts/src/flywheel-derived.ts`](https://github.com/eltmon/overdeck/blob/main/packages/contracts/src/flywheel-derived.ts): the `FlywheelDerivedStatus` shape that `pan flywheel status` and the Flywheel page compute on read. `` | `packages/contracts/src/flywheel-derived.ts` (`FlywheelDerivedStatus`); `src/lib/flywheel/derive-status.ts:1-18` ("Nothing is stored"). | +| 19 | Lines 49 and 77: `plans,` / `implements, reviews, and tests it` and `review and test agents catch them` | Line 77: replace `review and test agents catch them` with `review agents and CI tests catch them`. Line 49 is the v1.0 goal; keep it. | D2. | +| 20 | Heading `### Auto-pickup from backlog (\`auto_pickup_backlog\`, default OFF) — the master autonomy switch` | Replace the em dash with a colon: `### Auto-pickup from backlog (\`auto_pickup_backlog\`, default OFF): the master autonomy switch`. No `.mdx` links this anchor. | Dash rule. | +| 21 | Verified, keep | `roles/flywheel.md` exists; `/features/flywheel` exists; `auto_pickup_backlog` defaults to off (`control-settings.ts:162`); `require_uat_before_merge` defaults to on (`control-settings.ts:261-263`); sequencer-priority order (`pickup.ts:135-140`); `vetoed`, `parked`, `objection` gates; the `pan-flywheel` skill is the tick loop; `docs/FLYWHEEL.md` exists; the Flywheel is not behind Settings → Experimental (`EXPERIMENTAL_TAB_IDS` in `src/dashboard/frontend/src/lib/experimentalFeatures.ts:4-14` has no `flywheel`). | | + +**Vision replacement V1** (body of `### UAT-required-before-merge`): + +```mdx +This setting decides whether Overdeck may merge a pull request on its own. When it is on (the default), every issue is +**held**: Overdeck never merges the PR itself, and a human tests it and clicks Merge. When it is off, issues default to +**auto**: once the PR is approved at its head commit, every check is green and GitHub says it is mergeable, Overdeck +waits five minutes, so you can cancel, and then merges it. On a held issue, a failed browser UAT verdict also blocks +the Merge button. + +The setting is the last of three tiers, and the first one that is set wins: + +1. The issue's `auto-merge` or `hold-for-uat` label (the auto-merge toggle on the issue sets it). +2. The project's `auto_merge_default` (`auto` or `hold`) in `projects.yaml`. +3. The global `require_uat_before_merge`. + +`OVERDECK_DISABLE_AUTO_MERGE=1` turns automatic merging off on a machine. See [Auto-merge](/configuration/auto-merge). + +The model we want for v1.0 is "relax UAT for trusted work, but a human always owns the merge." Auto mode already +merges without a click, so today that goal holds only for held issues. +``` + +Before writing V1, re-check these five facts with the evidence greps in row 9 (Common procedure step 0). If +`configuration/auto-merge.mdx` does not exist (`ls configuration/auto-merge.mdx`), drop that link. + +Then remove every remaining en and em dash on the page (24 lines on the base: 9, 30, 31, 41, 55, 63, 67, 68, 73, 76, 77, +78, 80, 82, 84, 86, 103, 108, 130, 131, 166, 179, 195, 217; some vanish with the rows above). Line 179's en dash in +`80–94%` becomes `80 to 94%`. Arrows (`→`, `↔`) are not dashes; leave the ones that survive. + +Frontmatter: retitle to `title: "Flywheel vision and v1.0 readiness criteria"` with `sidebarTitle: "Flywheel Vision"`. +The description (149 chars) stays. + +### WI-5: `changelog.mdx` intro + +| # | Grep anchor (current text) | Change | Evidence | +| --- | --- | --- | --- | +| 1 | `Install or upgrade with \`npm install -g @overdeck/core@latest\`, then run \`pan install\` so the terminal backend and synced skills match the new version.` | Replace with: `To upgrade, run the [install script](/quickstart#install-the-overdeck-command) again, or \`npm install -g @overdeck/core@latest\` if you installed with npm. The next \`pan up\` runs \`pan sync\` in the background, which updates your skills and Herdr.` | `pan install` only refreshes the skill cache in `~/.overdeck` (`src/cli/commands/install.ts:285-297`); distributing skills is `pan sync`, which `pan up` starts in the background (`src/cli/up-sidecars.ts:23-35,118-121`, `sync --if-changed`, log line "Context and Herdr sync running in background"). The quickstart upgrade path is "Run the script again at any time to upgrade" (`quickstart.mdx`). Anchor `#install-the-overdeck-command` = heading `## Install the overdeck command`. | +| 2 | Verified, keep | "This page starts at v0.60.0, the release that removed Overdeck's state layer" (`changelog.mdx` v0.60.0 block "The Cut"); "Older releases are listed on GitHub Releases" (`gh release list` includes v0.51.0 and earlier); the `{/* RELEASE STEP ... */}` comment (matches `src/lib/release/changelog-fold.ts` and `docs/RELEASING.md`); `rss: true`. | | + +Frontmatter: retitle to `title: "Overdeck changelog: release notes since v0.60.0"` and add `sidebarTitle: "Changelog"`. Keep +`description` (61 chars) and `rss: true`. Do not touch any line at or below the first `` + block, because the old image shows lanes the corrected text no longer names (PAN-5501 made the same call on its page). + Keep the hero and board images. Record the Follow-up. +4. Update alt text on the audited pages only, to describe what the new image shows: + - `introduction.mdx`, `quickstart.mdx`, `concepts.mdx`: the hero `alt=`. + - `quickstart.mdx`: the board `alt=`. + - `concepts.mdx`: the pipeline `alt=` (WI-3 sets its text from the code; adjust only if the image disagrees). +5. Commit the six PNGs and the alt-text edits together. + +### WI-7: validators, links and PR body + +Depends on every other item. Steps: + +1. Run the dash grep on the four full pages and on `sed -n '1,/^" quickstart.mdx` and `grep -F "Plan…" quickstart.mdx` match; `grep -F "SQLite for state" quickstart.mdx` and + `grep -F "Select an open issue on the kanban board" quickstart.mdx` print nothing; the Pi exception sentence is present. +- WI-3: see the concepts table ACs. +- WI-4: `! grep -nP '[\x{2013}\x{2014}]' vision.mdx` exits 0; `grep -E "flywheel-brief|FLYWHEEL-STATE|panopticon-agent|relevance-vet|Flywheel-Affects-Criterion|flywheel weights" vision.mdx` prints nothing; the predicate line contains `activeBookMember`. +- WI-5: the changelog intro names `pan sync` and no longer says `pan install` updates synced skills; the title is + `Overdeck changelog: release notes since v0.60.0`; `git diff origin/main -- changelog.mdx` touches no line at or below the first + `` release records, including the em dash in a quoted UI string at line 611. +- Changing vision targets, thresholds, definitions, industry anchors or still-open questions. +- Editing any page outside the five, including alt text on other pages that use the recaptured images. +- Fixing code or prompt bugs found by the audit (they are Follow-ups). +- Auditing `reference/template-conversations.mdx` (owned by #5504). +- Adding a help section to `concepts.mdx`, `vision.mdx` or `changelog.mdx`. + +## Planning Q&A + +None. The issue was planned with `pan plan --auto`; every choice that would have been a question is recorded in the +xBRIEF `autoDecisions[]` and in Decisions D1 to D8 above. diff --git a/.pan/specs/2026-11-19-PAN-5499-docs-accuracy-audit-getting-started-vision-and-changelog-intro-5-pages.xbrief.json b/.pan/specs/2026-11-19-PAN-5499-docs-accuracy-audit-getting-started-vision-and-changelog-intro-5-pages.xbrief.json new file mode 100644 index 00000000000..a32b3044110 --- /dev/null +++ b/.pan/specs/2026-11-19-PAN-5499-docs-accuracy-audit-getting-started-vision-and-changelog-intro-5-pages.xbrief.json @@ -0,0 +1,832 @@ +{ + "xBRIEFInfo": { + "version": "0.8", + "created": "2026-11-19T02:28:45Z", + "author": "overdeck/0.0.0", + "description": "Plan for PAN-5499: docs: accuracy audit, Getting Started, Vision and Changelog intro (5 pages)", + "updated": "2026-11-19T02:52:06.404Z" + }, + "plan": { + "id": "pan-5499", + "title": "docs: accuracy audit, Getting Started, Vision and Changelog intro (5 pages)", + "status": "running", + "uid": "85f751e9-e8e2-4e10-9b5d-c77f88737711", + "author": "agent:claude-opus-5-5", + "sequence": 5, + "created": "2026-11-19T02:28:45Z", + "updated": "2026-11-19T02:52:06.404Z", + "references": [ + { + "uri": "https://github.com/eltmon/overdeck/issues/5499", + "label": "PAN-5499", + "type": "issue" + }, + { + "uri": "https://github.com/eltmon/overdeck/issues/5467", + "label": "PAN-5467 (epic)", + "type": "issue" + } + ], + "tags": [ + "docs", + "accuracy-audit", + "mintlify", + "screenshots" + ], + "metadata": { + "sizeJustification": "Docs-only audit of five root-level Mintlify pages plus three shared screenshot pairs. The finalize lint counts each root .mdx page and the images directory as separate subsystems, but they form one nav-group audit that shares one validation pass and one PR body, as the epic (#5467) scopes one audit issue per nav group.", + "canonicalFilename": "2026-11-19-PAN-5499-docs-accuracy-audit-getting-started-vision-and-changelog-intro-5-pages.xbrief.json", + "promotionIntent": "automatic" + }, + "narratives": { + "Problem": "The five first pages a new user reads (introduction, quickstart, concepts, the Flywheel vision and the changelog intro) still make claims the product no longer matches: a test agent on every PR, GitLab issue tracking, wrong Pipeline lanes and metric, a Home stuck count, Deacon health pills, deleted vision files and commands, a wrong merge and UAT model, an old bot login, and screenshots that still show the Panopticon v0.21.0 brand.", + "Proposal": "Apply the per-page change tables in .pan/drafts/PAN-5499.md, each row carrying a grep anchor, replacement text and code evidence; remove en and em dashes; fix frontmatter; recapture the three stale screenshot pairs with scripts/capture-doc-shot.mjs; run the Mintlify validators; write a PR body with one note per page and a Follow-ups list for the code and prompt bugs found.", + "NonGoals": "- Rewriting changelog release records, including the em dash inside the quoted UI string at changelog.mdx line 611\n- Changing vision v1.0 targets, thresholds, definitions, industry anchors or still-open questions\n- Editing any page outside the five audited pages, including alt text on other pages that use the recaptured images\n- Fixing code or prompt bugs the audit found (roles/flywheel.md bot login and UAT text, roles/review.md test dispatch, scripts/install.sh Node check, #5537); they go to Follow-ups\n- Auditing reference/template-conversations.mdx (owned by #5504)\n- Adding help sections to concepts.mdx, vision.mdx or changelog.mdx\n- Any docs.json, CLAUDE.md, rule, role or changelog.d change\n- Editing image pixels by hand" + }, + "autoDecisions": [ + { + "summary": "Audit only the changelog intro (frontmatter, two paragraphs, RELEASE STEP comment), not the release records.", + "rationale": "The issue title says 'Changelog intro'; release records are dated history written by pan release stable, and rewriting them would change history." + }, + { + "summary": "On introduction and concepts, drop the 'test agent checks every PR' claim and state only what holds whether or not #5537 lands, linking /features/issue-pipeline.", + "rationale": "#5537 is open and its fix direction is undecided; features/issue-pipeline.mdx already documents current behavior, so the overview pages should not repeat a caveat that may soon change." + }, + { + "summary": "On vision.mdx, correct current-state facts only and keep the operator's targets, thresholds and definitions.", + "rationale": "The vision page is operator direction; an accuracy audit fixes what the page says the product does today, not what the operator wants v1.0 to be." + }, + { + "summary": "Recapture the hero, board and pipeline screenshot pairs in place, with a keep-old-images fallback when no dashboard is reachable.", + "rationale": "All three are from 2026-06-04 and show the Panopticon v0.21.0 brand on the landing page and quickstart; scripts/capture-doc-shot.mjs exists, and same-name files fix every page that uses them." + }, + { + "summary": "Retitle concepts, vision and changelog with specific searchable titles and keep short sidebarTitles.", + "rationale": "The issue's frontmatter rule asks for specific searchable titles; 'Changelog' and 'Flywheel Vision' are generic, and sidebarTitle keeps the nav labels short." + }, + { + "summary": "Treat GitLab as a code host only on introduction and concepts.", + "rationale": "src/lib/tracker/gitlab.ts returns notImplemented for every method, and configuration/issue-trackers.mdx already says GitLab issue tracking is not supported." + } + ], + "items": [ + { + "id": "intro-audit", + "title": "introduction.mdx: fix Node version, test-agent, tracker and pipeline claims", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T02:28:45Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5499", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "introduction.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "! grep -nP '[\\x{2013}\\x{2014}]' introduction.mdx", + "! grep -q 'a test agent' introduction.mdx", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash check prints nothing and exits 0", + "the test-agent check exits 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-7", + "NFR-3" + ], + "parallelSafeReason": "Edits only introduction.mdx; no other page item touches it." + }, + "narrative": { + "Action": "Apply WI-1 rows 1 to 3 of .pan/drafts/PAN-5499.md to introduction.mdx (leave the hero alt text to recapture-doc-shots). Follow the PRD's Common procedure (.pan/drafts/PAN-5499.md): find each row by grep anchor, apply the change, code wins over the PRD (skip and note a row a primary source contradicts), residual rule, dash rule, frontmatter rule, link check, MDX safety. Never change code. Commit with 'Item: intro-audit', the AC trailers and a 'PR-note: introduction.mdx: ' line; push; then pan task done." + }, + "items": [ + { + "id": "intro-audit.ac1", + "title": "introduction.mdx contains 'It needs Node.js 22.16 or later' and no longer contains 'Node.js 22 or later.'", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "intro-audit.ac2", + "title": "The issue pipeline paragraph renders 'Review agents check the work' and `grep -c 'a test agent' introduction.mdx` prints 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "intro-audit.ac3", + "title": "The issue pipeline paragraph renders 'Issues come from GitHub, Linear, Rally or Jira' and links /features/issue-pipeline", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "intro-audit.ac4", + "title": "`grep -nP '[\\x{2013}\\x{2014}]' introduction.mdx` prints nothing and the '## Get help' section still links https://discord.gg/ZpHE2ZTv5P and GitHub Issues", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "quickstart-audit", + "title": "quickstart.mdx: fix start-work step, model lock, board card and architecture claims", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T02:28:45Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5499", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "quickstart.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "! grep -nP '[\\x{2013}\\x{2014}]' quickstart.mdx", + "! grep -qE 'SQLite for state|Select an open issue on the kanban board' quickstart.mdx", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash check prints nothing and exits 0", + "the stale-claim check exits 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-7", + "NFR-3" + ], + "parallelSafeReason": "Edits only quickstart.mdx; no other page item touches it." + }, + "narrative": { + "Action": "Apply WI-2 rows 1 to 5 of .pan/drafts/PAN-5499.md to quickstart.mdx (leave hero and board alt text to recapture-doc-shots). Follow the PRD's Common procedure (.pan/drafts/PAN-5499.md): find each row by grep anchor, apply the change, code wins over the PRD (skip and note a row a primary source contradicts), residual rule, dash rule, frontmatter rule, link check, MDX safety. Never change code. Commit with 'Item: quickstart-audit', the AC trailers and a 'PR-note: quickstart.mdx: ' line; push; then pan task done." + }, + "items": [ + { + "id": "quickstart-audit.ac1", + "title": "Step 4 of 'What happens next' renders 'choose **Plan…** first', the '**▶ Start** chip' and 'run `pan start `', and the page no longer contains 'Select an open issue on the kanban board'", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "quickstart-audit.ac2", + "title": "Step 5 renders the exception 'except a Pi conversation, which can switch model while it runs'", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "quickstart-audit.ac3", + "title": "The board paragraph renders 'a **▶ Start** or **▶ Resume** chip' and no longer contains 'workspace controls'", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "quickstart-audit.ac4", + "title": "'Architecture at a glance' renders 'SQLite for local data such as conversations and settings' and `grep -c 'SQLite for state' quickstart.mdx` prints 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "quickstart-audit.ac5", + "title": "`grep -nP '[\\x{2013}\\x{2014}]' quickstart.mdx` prints nothing and the '## Get help' section still links the Discord and GitHub Issues", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "concepts-command-deck", + "title": "concepts.mdx: fix the Command Deck section (app bar, tab menu, Home, tabs, feed)", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T02:28:45Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5499", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "concepts.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "! grep -qE 'Deacon health|No more persistent banners|stuck count' concepts.mdx", + "test \"$(grep -c 'Decisions (Deft projects only)' concepts.mdx)\" = 2", + "npm run lint:docs" + ], + "expected_outputs": [ + "the stale-claim check exits 0", + "the Decisions count test exits 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "traces": [ + "FR-1", + "FR-2", + "NFR-2", + "NFR-3" + ], + "parallelSafeReason": "Edits only the Command Deck section of concepts.mdx; the second concepts item is serialized after it by a blocks edge." + }, + "narrative": { + "Action": "Apply WI-3 rows 1 to 6 of .pan/drafts/PAN-5499.md to concepts.mdx: the '## Command Deck' section through '### What You Can Do From Command Deck'. Leave image alt text alone. Follow the PRD's Common procedure (.pan/drafts/PAN-5499.md): find each row by grep anchor, apply the change, code wins over the PRD (skip and note a row a primary source contradicts), residual rule, dash rule, frontmatter rule, link check, MDX safety. Never change code. Commit with 'Item: concepts-command-deck', the AC trailers and a 'PR-note: concepts.mdx: ' line; push; then pan task done." + }, + "items": [ + { + "id": "concepts-command-deck.ac1", + "title": "The app bar bullet renders 'an **N agents working** menu' and `grep -cE 'Deacon health|No more persistent banners' concepts.mdx` prints 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "concepts-command-deck.ac2", + "title": "The tab strip bullet renders 'split it right or down' and 'Pop out to window', and no longer contains 'right-click to pop out'", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "concepts-command-deck.ac3", + "title": "The pane body bullet renders 'landed this week and spend this week' and `grep -c 'stuck count' concepts.mdx` prints 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "concepts-command-deck.ac4", + "title": "`grep -c 'Decisions (Deft projects only)' concepts.mdx` prints 2 and the feed bullet renders '**Needs you / Project / Global**'", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "concepts-pipeline-and-rest", + "title": "concepts.mdx: fix test agent, pipeline lanes, trackers, costs and Next Steps", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T02:28:45Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5499", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "concepts.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "! grep -nP '[\\x{2013}\\x{2014}]' concepts.mdx", + "! grep -qE 'Review queue|Verifying|5 issue trackers|GitLab Issues|Board view|a test agent' concepts.mdx", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash check prints nothing and exits 0", + "the stale-claim grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "NFR-3" + ], + "parallelSafeReason": "Same file as concepts-command-deck, so a blocks edge serializes them; no other item edits concepts.mdx text before recapture-doc-shots." + }, + "narrative": { + "Action": "Apply WI-3 rows 8 to 18 of .pan/drafts/PAN-5499.md to concepts.mdx (from '## Agents' to the end, including the pipeline image alt text in row 11), then the page-wide dash, frontmatter (retitle to 'Overdeck concepts: Command Deck, agents, workspaces and the pipeline', keep sidebarTitle 'Concepts') and link checks. Follow the PRD's Common procedure (.pan/drafts/PAN-5499.md): find each row by grep anchor, apply the change, code wins over the PRD (skip and note a row a primary source contradicts), residual rule, dash rule, frontmatter rule, link check, MDX safety. Never change code. Commit with 'Item: concepts-pipeline-and-rest', the AC trailers and a 'PR-note: concepts.mdx: ' line; push; then pan task done." + }, + "items": [ + { + "id": "concepts-pipeline-and-rest.ac1", + "title": "`grep -cE 'a test agent|Review and test agents' concepts.mdx` prints 0 and the Specialists section renders 'the verification gate runs the project's checks'", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "concepts-pipeline-and-rest.ac2", + "title": "The Pipeline paragraph renders 'issue rows grouped by phase: Ship, Review, Work, Plan and Ready' and `grep -cE 'Review queue|Verifying|activity feed alongside' concepts.mdx` prints 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "concepts-pipeline-and-rest.ac3", + "title": "The tracker section renders 'Overdeck integrates with 4 issue trackers' with no GitLab Issues row, plus the sentence that GitLab works as a code host linking /configuration/issue-trackers", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "concepts-pipeline-and-rest.ac4", + "title": "The Cost Tracking list renders 'Daily cost trends on the **Costs** page, an experimental view' and no longer contains 'Board view'", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "concepts-pipeline-and-rest.ac5", + "title": "The frontmatter title is 'Overdeck concepts: Command Deck, agents, workspaces and the pipeline' and `grep -nP '[\\x{2013}\\x{2014}]' concepts.mdx` prints nothing", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "vision-autonomy-and-merge", + "title": "vision.mdx: fix file references, author gate, pickup gates and the merge and UAT model", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T02:28:45Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5499", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "vision.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "! grep -qE 'panopticon-agent|relevance-vet|marks UAT passed|blocks-main' vision.mdx", + "npm run lint:docs" + ], + "expected_outputs": [ + "the stale-claim check exits 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "traces": [ + "FR-1", + "FR-2", + "NFR-2", + "NFR-3" + ], + "parallelSafeReason": "Edits only the first half of vision.mdx; the second vision item is serialized after it by a blocks edge." + }, + "narrative": { + "Action": "Apply WI-4 rows 1 to 9 and row 20 of .pan/drafts/PAN-5499.md to vision.mdx: the intro paragraph, the author gate login, the auto-pickup bullets, gates and predicate, the setting keys, and replace the body of '### UAT-required-before-merge' with 'Vision replacement V1' after re-checking its five facts. Keep targets, thresholds and definitions (Decision D3). Follow the PRD's Common procedure (.pan/drafts/PAN-5499.md): find each row by grep anchor, apply the change, code wins over the PRD (skip and note a row a primary source contradicts), residual rule, dash rule, frontmatter rule, link check, MDX safety. Never change code. Commit with 'Item: vision-autonomy-and-merge', the AC trailers and a 'PR-note: vision.mdx: ' line; push; then pan task done." + }, + "items": [ + { + "id": "vision-autonomy-and-merge.ac1", + "title": "The intro paragraph links the pan-flywheel SKILL.md and `.pan/orders/`, `grep -cE 'panopticon-agent|relevance-vet' vision.mdx` prints 0, and the author gate names `overdeck-agent[bot]`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "vision-autonomy-and-merge.ac2", + "title": "The predicate line contains `ready && planned && (released || auto_pickup_backlog || activeBookMember) && !parked && !vetoed && !objection && !inPipeline && !epic`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "vision-autonomy-and-merge.ac3", + "title": "The UAT section renders the three-tier list (issue label, project `auto_merge_default`, global `require_uat_before_merge`), the five-minute wait and a link to /configuration/auto-merge, and no longer contains 'marks UAT passed' or '`overdeck/review` + `overdeck/test`'", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "vision-autonomy-and-merge.ac4", + "title": "The OFF bullet renders 'released label or by adding them to the active order book' and no longer contains 'blocks-main'", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "vision-criteria-and-appendix", + "title": "vision.mdx: fix pipeline pass, criteria measurement, path, open questions and appendix", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T02:28:45Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5499", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "vision.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "! grep -nP '[\\x{2013}\\x{2014}]' vision.mdx", + "! grep -qE 'Flywheel-Affects-Criterion|flywheel weights|FLYWHEEL-STATE|flywheel-brief' vision.mdx", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash check prints nothing and exits 0", + "the removed-feature check exits 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "NFR-3" + ], + "parallelSafeReason": "Same file as vision-autonomy-and-merge, serialized by a blocks edge." + }, + "narrative": { + "Action": "Apply WI-4 rows 10 to 19 of .pan/drafts/PAN-5499.md to vision.mdx, then remove every remaining en and em dash on the page ('80–94%' becomes '80 to 94%'), retitle to 'Flywheel vision and v1.0 readiness criteria' with sidebarTitle 'Flywheel Vision', and check links. Run the row 12 implementation checkpoint (gh issue list --label v1.0-required --state open). Follow the PRD's Common procedure (.pan/drafts/PAN-5499.md): find each row by grep anchor, apply the change, code wins over the PRD (skip and note a row a primary source contradicts), residual rule, dash rule, frontmatter rule, link check, MDX safety. Never change code. Commit with 'Item: vision-criteria-and-appendix', the AC trailers and a 'PR-note: vision.mdx: ' line; push; then pan task done." + }, + "items": [ + { + "id": "vision-criteria-and-appendix.ac1", + "title": "`grep -cE 'Flywheel-Affects-Criterion|flywheel weights|FLYWHEEL-STATE|flywheel-brief|bypass-uat' vision.mdx` prints 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "vision-criteria-and-appendix.ac2", + "title": "After the readiness table the page renders 'Overdeck measures criteria 1 and 2 today with `pan flywheel stats`' and the seven targets are unchanged", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "vision-criteria-and-appendix.ac3", + "title": "The appendix contains `.pan/flywheel/state.md`, the pan-flywheel SKILL.md link and `packages/contracts/src/flywheel-derived.ts`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "vision-criteria-and-appendix.ac4", + "title": "`grep -nP '[\\x{2013}\\x{2014}]' vision.mdx` prints nothing and the frontmatter title is 'Flywheel vision and v1.0 readiness criteria' with sidebarTitle 'Flywheel Vision'", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "changelog-intro", + "title": "changelog.mdx intro: fix the upgrade sentence and retitle the page", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T02:28:45Z", + "metadata": { + "difficulty": "trivial", + "kind": "docs", + "issueLabel": "pan-5499", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "changelog.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "! sed -n '1,/^' line; push; then pan task done." + }, + "items": [ + { + "id": "changelog-intro.ac1", + "title": "The intro renders 'The next `pan up` runs `pan sync` in the background' and no longer says `pan install` makes synced skills match", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "changelog-intro.ac2", + "title": "The frontmatter contains title 'Overdeck changelog: release notes since v0.60.0' and sidebarTitle 'Changelog', and preserves 'rss: true'", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "changelog-intro.ac3", + "title": "`git diff origin/main -- changelog.mdx` shows changes only above the first `'; push; pan task done." + }, + "items": [ + { + "id": "recapture-doc-shots.ac1", + "title": "Either the six PNG files are re-committed and each one, when read, shows the 'Overdeck' brand and not 'Panopticon v0.21.0', or (D5 fallback) they are unchanged and the commit message carries 'Follow-up: recapture hero, board and pipeline doc shots'", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "recapture-doc-shots.ac2", + "title": "Either the new pipeline capture shows the phase groups the concepts.mdx pipeline alt text names, or (D5 fallback) concepts.mdx no longer contains a pipeline-light.png image", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "recapture-doc-shots.ac3", + "title": "Either the hero alt text on introduction.mdx, quickstart.mdx and concepts.mdx and the board alt text on quickstart.mdx contains a description of what the new image shows, or (D5 fallback) each page preserves its old alt text", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "recapture-doc-shots.ac4", + "title": "No committed PNG shows a secret, token, email address or private message text (each new PNG was read in both themes before commit)", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "validate-and-pr-body", + "title": "Run the Mintlify validators and write the PR body with page notes and Follow-ups", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T02:28:45Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5499", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "introduction.mdx", + "quickstart.mdx", + "concepts.mdx", + "vision.mdx", + "changelog.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "npx -y mint@4.3.49 validate", + "npx -y mint@4.3.49 broken-links", + "npm run lint:docs" + ], + "expected_outputs": [ + "validate reports success and exits 0", + "broken-links reports no broken links and exits 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "traces": [ + "FR-5", + "FR-7", + "FR-8", + "NFR-1" + ], + "parallelSafeReason": "Runs last; blocked by every other item." + }, + "narrative": { + "Action": "Apply WI-7 of .pan/drafts/PAN-5499.md: run the dash greps, npm run lint:docs, npx -y mint@4.3.49 validate and npx -y mint@4.3.49 broken-links; fix anything the five pages caused; write the PR body ticking the five pages with their PR-note lines, pasting the three validator outputs and listing every Follow-up in WI-7 step 3; post one comment each on #5501 and #5502 naming the recaptured images and their pages that use them (Decision D8). Commit any fix with 'Item: validate-and-pr-body'." + }, + "items": [ + { + "id": "validate-and-pr-body.ac1", + "title": "`npx -y mint@4.3.49 validate` and `npx -y mint@4.3.49 broken-links` each exits 0 on the branch, and the PR body contains their output", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "validate-and-pr-body.ac2", + "title": "The PR body contains a ticked entry with a one-line note for each of introduction, quickstart, concepts, vision and changelog", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "validate-and-pr-body.ac3", + "title": "The PR body's Follow-ups list contains the roles/flywheel.md bot login, the install.sh Node check, features/specialists.mdx and roles/review.md test-agent text, and the other pages that use the recaptured images", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "validate-and-pr-body.ac4", + "title": "Issues #5501 and #5502 each shows one new comment that contains the recaptured image file names", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + } + ], + "edges": [ + { + "from": "concepts-command-deck", + "to": "concepts-pipeline-and-rest", + "type": "blocks" + }, + { + "from": "vision-autonomy-and-merge", + "to": "vision-criteria-and-appendix", + "type": "blocks" + }, + { + "from": "intro-audit", + "to": "recapture-doc-shots", + "type": "blocks" + }, + { + "from": "quickstart-audit", + "to": "recapture-doc-shots", + "type": "blocks" + }, + { + "from": "concepts-pipeline-and-rest", + "to": "recapture-doc-shots", + "type": "blocks" + }, + { + "from": "intro-audit", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "quickstart-audit", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "concepts-command-deck", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "concepts-pipeline-and-rest", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "vision-autonomy-and-merge", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "vision-criteria-and-appendix", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "changelog-intro", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "recapture-doc-shots", + "to": "validate-and-pr-body", + "type": "blocks" + } + ] + }, + "status": "active" +} \ No newline at end of file diff --git a/changelog.mdx b/changelog.mdx index 10174ec0165..bc7f9cc79ce 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -1,10 +1,11 @@ --- -title: "Changelog" +title: "Overdeck changelog: release notes since v0.60.0" +sidebarTitle: "Changelog" description: "What changed in each Overdeck release, starting with v0.60.0." rss: true --- -Overdeck ships to npm as [`@overdeck/core`](https://www.npmjs.com/package/@overdeck/core). Install or upgrade with `npm install -g @overdeck/core@latest`, then run `pan install` so the terminal backend and synced skills match the new version. +Overdeck ships to npm as [`@overdeck/core`](https://www.npmjs.com/package/@overdeck/core). To upgrade, run the [install script](/quickstart#install-the-overdeck-command) again, or `npm install -g @overdeck/core@latest` if you installed with npm. The next `pan up` runs `pan sync` in the background, which updates your skills and Herdr. This page starts at v0.60.0, the release that removed Overdeck's state layer. Older releases are listed on [GitHub Releases](https://github.com/eltmon/overdeck/releases). diff --git a/concepts.mdx b/concepts.mdx index 32ffb505c35..9f6a17de8c8 100644 --- a/concepts.mdx +++ b/concepts.mdx @@ -1,5 +1,5 @@ --- -title: "Overdeck concepts" +title: "Overdeck concepts: Command Deck, agents, workspaces and the pipeline" sidebarTitle: "Concepts" description: "The core ideas behind Overdeck: Command Deck, agents, workspaces, the issue pipeline, model routing, skills and issue trackers." --- @@ -12,20 +12,20 @@ Learn the fundamental concepts that power Overdeck. The live development surface where you and your agents work together. A full-height **project sidebar** on the left owns project selection; everything to its right is scoped to the project you pick and updates in real time: -- **App bar**: the project crumb, a project-scoped search, and status pills at a glance (Deacon health, running-agent count, stopped agents). No more persistent banners; attention items surface as compact pills. -- **Tab strip**: every issue, agent, and conversation you open becomes a tab. Scroll on overflow, middle-click to close, right-click to pop out to a window or close others, and **split the view** (drag a tab to a pane's edge) to watch two panes side by side. -- **Pane body**: the working area. A project's **Home cockpit** (issue swimlanes, recent spend, a stuck count), an **issue view** (a title row with the issue's state, cost and next actions; a pipeline strip; a needs-you banner when you must act; and tabs led by the agent's conversation (Conversation, Tasks, Plan, Changes, Activity, Discussion, Skills, Details). It is the same view the issue drawer shows), or an agent's live conversation and terminal. -- **Activity feed**: the **Feed** tab on `/activity`, with **Needs-you / Project / Global** scopes, so anything waiting on your input is one page away; the top bar's **Needs you** menu lists the same items. Inside Project and Global, the **All / Chats / Activity** tabs: All lists what changed (created, ended, reported, merged) rather than every busy conversation, Chats lists the conversations active in the last day, and a gauntlet run appears as one card. +- **App bar**: the project crumb, a search box that opens the command palette (Ctrl+K, or ⌘K on a Mac), an **N agents working** menu, **Needs you**, chips that appear only when something is wrong (Deacon frozen, stopped agents, low-cost mode, a stale build), and a system health menu. +- **Tab strip**: every issue, agent, and conversation you open becomes a tab. Scroll on overflow, middle-click to close, right-click a tab to split it right or down, close it, or close all tabs; drag a conversation's tab off the bar, or use **Pop out to window** in its ⋮ menu, to open it in its own window, and **split the view** (drag a tab to a pane's edge) to watch two panes side by side. +- **Pane body**: the working area. A project's **Home** (facts for agents working, needs you, in review, landed this week and spend this week, then the pipeline lanes, the merge train and recent changes), an **issue view** (a title row with the issue's state, cost and next actions; a pipeline strip; a needs-you banner when you must act; and tabs led by the agent's conversation (Conversation, Tasks, Plan, Changes, Activity, Decisions (Deft projects only), Discussion, Skills, Details). It is the same view the issue drawer shows), or an agent's live conversation and terminal. +- **Activity feed**: the **Feed** tab on `/activity`, with **Needs you / Project / Global** scopes (Project appears when a project is selected), so anything waiting on your input is one page away; the top bar's **Needs you** menu lists the same items. Inside Project and Global, the **All / Chats / Activity** tabs: All lists activity events and the conversations that started or ended in the last day, Chats lists the conversations active in the last day, and a gauntlet run appears as one card. Command Deck is where you *manage the conversation*, not just watch a workflow run. The center pane streams the agent's turn-by-turn reasoning and tool calls as they happen, the left column keeps the project's conversations, issues and workspaces one click away on every page, and the top bar's Needs you menu and the Activity feed on `/activity` collect anything that needs your attention. -Everything is alive: no refresh buttons. Domain events trigger small, informative UI motion: cost increments animate, tool names fade in and out, status dots pulse. +Views update live from domain events, so you rarely need to refresh. Domain events trigger small, informative UI motion: cost increments animate, tool names fade in and out, status dots pulse. -The **issue view** above is the same view the issue drawer shows. It has a title row with the issue's state, cost and next actions; a pipeline strip with the checks and pickup controls; a needs-you banner when you must act; and tabs led by the agent's conversation: Conversation, Tasks, Plan, Changes, Activity, Discussion, Skills and Details. Details holds the status, the pipeline with per-agent cost, the ship progress, the workspace, and (in the Command Deck tab) the launcher and agent dock. +The **issue view** above is the same view the issue drawer shows. It has a title row with the issue's state, cost and next actions; a pipeline strip with the checks and pickup controls; a needs-you banner when you must act; and tabs led by the agent's conversation: Conversation, Tasks, Plan, Changes, Activity, Decisions (Deft projects only), Discussion, Skills and Details. Details holds the status, the pipeline with per-agent cost, the ship progress, the workspace, and (in the Command Deck tab) the launcher and agent dock. ### What You Can Do From Command Deck @@ -49,7 +49,7 @@ Agents are AI coding assistants that work on the tasks you assign. You direct th Agent types: - **Implementation (work) agents**: work on features, bugs, and refactoring in isolated worktrees - **Planning agents**: write a PRD and an xBRIEF plan before work starts -- **Review and test agents**: check finished work on the pull request +- **Review agents**: review the pull request. The project's tests run as a check on the PR, on CI for most projects. You can manage agents via Command Deck, the CLI, or the REST API. @@ -59,7 +59,7 @@ Cloister is the agent watchdog. It checks each running agent's health, pokes or ## Planning -`pan start ` plans the issue before work starts: a planning agent writes a PRD and an xBRIEF plan, and they are committed under `.pan/` in your repo. `pan start --plan skip` skips planning. See [Planning](/features/planning). +`pan start ` plans the issue before work starts: a planning agent writes a PRD and an xBRIEF plan, and they are committed under `.pan/` in your repo. `pan start --plan skip` skips the planning agent and builds a minimal xBRIEF from the issue body. See [Planning](/features/planning). ## Workspaces @@ -73,7 +73,7 @@ Cloister is the agent watchdog. It checks each running agent's health, pokes or This allows multiple agents to work on different features simultaneously without conflicts. -Workspaces support both local execution and remote execution via Fly.io for cloud-hosted agent environments. +Workspaces support both local execution and remote execution via Fly.io for cloud-hosted agent environments. Start a remote one with `pan start --remote`. ### Main Project Branch Convention @@ -81,20 +81,20 @@ The main project directory should **always** stay on the `main` branch. All feat ### Docker Integration -Workspaces can include Docker containers for full development environments. Supports both local execution and remote execution via Fly.io. +Workspaces can include Docker containers for full development environments. ## Specialists -When a work agent finishes, a review agent and a test agent check the work on the pull request. When the PR is approved and its checks are green, you click **Merge**, or let [auto-merge](/configuration/auto-merge) ship it. See [Specialists](/features/specialists). +When a work agent finishes, the verification gate runs the project's checks on its pull request and a review agent reviews it. When the PR is approved and its checks are green, you click **Merge**, or let [auto-merge](/configuration/auto-merge) ship it. See [Specialists](/features/specialists). See [Issue pipeline](/features/issue-pipeline) for every stage from start to close-out. -The **Pipeline** page is the at-a-glance view of this lifecycle: a metric strip across the top (Active issues, Work running, Review queue, Ship, Spend) sits over issue rows grouped by phase (Ship, Review, Verifying) with a live activity feed alongside. It shows where every issue sits as specialists hand it forward. +The **Pipeline** page is the at-a-glance view of this lifecycle: a metric strip across the top (Active issues, Work running, Review running, Ship, Spend) sits over issue rows grouped by phase: Ship, Review, Work, Plan and Ready. It shows where every issue sits as specialists hand it forward. ## Model routing @@ -114,19 +114,20 @@ See [Skills](/features/skills). ## Convoys -A convoy is the full review mode: four reviewers (security, correctness, performance and requirements) check one pull request in parallel, and a review parent writes the verdict. Turn it on with `roles.review.mode: full`. See [Convoys](/features/convoys). +A convoy is the full review mode: four reviewers (security, correctness, performance and requirements) check one pull request in parallel, and a review parent writes the verdict. Turn it on with `roles.review.mode: full`; the default, `quick`, runs one review agent. See [Convoys](/features/convoys). ## Issue Tracker Integration -Overdeck integrates with 5 issue trackers: +Overdeck integrates with 4 issue trackers: - **GitHub Issues**: Full integration with PRs and status updates - **Linear**: Full integration with cycles, labels, and status updates -- **GitLab Issues**: Issue tracking and MR management - **Rally (CA Agile Central)**: Enterprise issue tracking - **Jira (Cloud and Data Center)**: Atlassian issue tracking -The dashboard displays issues from all configured trackers in a unified kanban board with cost badges, agent status indicators, and workspace controls. +GitLab issue tracking is not supported yet; GitLab works as a code host, and Overdeck opens and merges its merge requests. See [Issue trackers](/configuration/issue-trackers). + +The dashboard displays issues from all configured trackers in one kanban board, the **Board**, with cost badges, agent status indicators, and workspace controls. ## Cost Tracking @@ -134,13 +135,13 @@ Per-issue, per-stage token costs with dashboard analytics. Every agent session i - Model and provider attribution - Token counts (input/output) -- Dollar costs per stage (planning, work, review, test, merge) -- Daily cost summaries on the Board view +- Dollar costs per stage (planning, implementation, review, testing, merge, and interactive conversations) +- Daily cost trends on the **Costs** page, an experimental view (Settings → Experimental) ## Next Steps -- [Issue pipeline](/features/issue-pipeline) - Follow an issue from start to merge -- [CLI Commands](/cli/overview) - Learn about available commands -- [Command Deck](/features/mission-control) - Deep dive into the dashboard -- [Cloister](/features/cloister) - Understand the AI lifecycle manager -- [Specialists](/features/specialists) - Learn about the automated quality pipeline +- [Issue pipeline](/features/issue-pipeline): Follow an issue from start to merge +- [CLI Commands](/cli/overview): Learn about available commands +- [Command Deck](/features/mission-control): Deep dive into the dashboard +- [Cloister](/features/cloister): How the agent watchdog keeps agents moving +- [Specialists](/features/specialists): Learn about the automated quality pipeline diff --git a/images/dashboard/board-dark.png b/images/dashboard/board-dark.png index 840c09d8239..33b2dcc56ee 100644 Binary files a/images/dashboard/board-dark.png and b/images/dashboard/board-dark.png differ diff --git a/images/dashboard/board-light.png b/images/dashboard/board-light.png index bb161272d16..a449bd5438d 100644 Binary files a/images/dashboard/board-light.png and b/images/dashboard/board-light.png differ diff --git a/images/dashboard/command-deck-hero-dark.png b/images/dashboard/command-deck-hero-dark.png index 687dd2c0121..00e8aaa6f9e 100644 Binary files a/images/dashboard/command-deck-hero-dark.png and b/images/dashboard/command-deck-hero-dark.png differ diff --git a/images/dashboard/command-deck-hero-light.png b/images/dashboard/command-deck-hero-light.png index ed35e208c1c..b838abb53f3 100644 Binary files a/images/dashboard/command-deck-hero-light.png and b/images/dashboard/command-deck-hero-light.png differ diff --git a/images/dashboard/pipeline-dark.png b/images/dashboard/pipeline-dark.png index 80c50f5c9c9..a4cb2a4be6d 100644 Binary files a/images/dashboard/pipeline-dark.png and b/images/dashboard/pipeline-dark.png differ diff --git a/images/dashboard/pipeline-light.png b/images/dashboard/pipeline-light.png index 616de5e3c9f..43b140b260c 100644 Binary files a/images/dashboard/pipeline-light.png and b/images/dashboard/pipeline-light.png differ diff --git a/introduction.mdx b/introduction.mdx index 123cd4fd8cb..c1c4535e27a 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -17,7 +17,7 @@ With Overdeck you can: ## Get started @@ -28,7 +28,7 @@ Try Overdeck without installing anything. This starts Overdeck and opens the das npx @overdeck/core ``` -To install the `overdeck` and `pan` commands, run the install script. It needs Node.js 22 or later, installs with npm into `~/.local`, and does not use sudo: +To install the `overdeck` and `pan` commands, run the install script. It needs Node.js 22.16 or later, installs with npm into `~/.local`, and does not use sudo: ```bash curl -fsSL https://overdeck.ai/install | sh @@ -44,7 +44,7 @@ Start a conversation with an agent in any project and steer it while it works. E ### The issue pipeline -`pan start ` plans the issue, makes an isolated workspace for it, and starts a work agent. Review agents and a test agent check the work, and the pull request waits for you to click Merge unless you turn on auto-merge. Issues come from GitHub, Linear, GitLab, Rally or Jira. See [Planning](/features/planning), [the review convoy](/features/convoys), [merge batches](/features/merge-batches), [auto-merge](/configuration/auto-merge) and [issue trackers](/configuration/issue-trackers). +`pan start ` plans the issue, makes an isolated workspace for it, and starts a work agent. Review agents check the work. The pull request merges when it is approved and its checks are green: you click Merge, or auto-merge does it for you. Issues come from GitHub, Linear, Rally or Jira, and code can live on GitHub or GitLab. See [the issue pipeline](/features/issue-pipeline), [Planning](/features/planning), [the review convoy](/features/convoys), [merge batches](/features/merge-batches), [auto-merge](/configuration/auto-merge) and [issue trackers](/configuration/issue-trackers). ### Order books and the Flywheel (early) diff --git a/quickstart.mdx b/quickstart.mdx index d739f0e74fa..943d2fcdd81 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -9,7 +9,7 @@ import { ThemedImage } from "/snippets/themed-image.mdx"; ## Try Overdeck without installing @@ -62,16 +62,16 @@ The **Get set up** card on Home lists what is still missing and shows the comman 1. **The dashboard opens on Home, in Simple mode.** No project is required to start. 2. **Type what you want.** Press Enter to ask an agent, or Ctrl+Enter to run it in a terminal. You still need no project. 3. **Add a project** from the composer's project chip, or from **Add a project** in the left column's project switcher, when you want an agent working in a repo. -4. **Pick an issue and start work.** Select an open issue on the kanban board, and Overdeck creates an isolated workspace for the agent. -5. **Stay in control.** Watch diffs land as the agent works, send messages to steer it, and fork the conversation to explore alternatives. A conversation keeps its model once it starts. To use another model, [hand off to a new conversation](/features/conversations#why-hand-off). +4. **Pick an issue and start work.** Open an issue from the **Board**. If it has no plan yet, choose **Plan…** first; once it is planned, start it from the **▶ Start** chip on its card or the start button in its issue view. Or run `pan start `, which plans the issue if needed and then starts work. Starting creates an isolated workspace and a work agent. +5. **Stay in control.** Watch diffs land as the agent works, send messages to steer it, and fork the conversation to explore alternatives. A conversation keeps its model once it starts, except a Pi conversation, which can switch model while it runs. To use another model, [hand off to a new conversation](/features/conversations#why-hand-off). -The board is the usual place to pick an issue. Each card carries a cost badge, a live agent status dot and workspace controls, so you can start or check in on an agent without leaving the column it lives in. +The Board is the usual place to pick an issue. Each card carries a cost badge, its pipeline phase and a **▶ Start** or **▶ Resume** chip when the agent can start or resume, so you can start or check in on an agent without leaving the column it lives in. Work at whatever level of involvement you want. Pair-program hands-on with a single agent in the conversation view above, or let the specialist pipeline take issues from plan to merged PR while you focus elsewhere. Command Deck is built to manage both the agents and the workflow they move through. @@ -110,7 +110,7 @@ See [Desktop app](/features/desktop-app) for setup on each system, the tray, not ## Architecture at a glance -Overdeck started as a CLI and grew into **Command Deck**, a desktop-class development environment. The CLI, the GUI and any script that can make an HTTP request all drive the same REST surface, so you can start an agent from a kanban card, a terminal or a webhook without switching tools. Under the hood: an Effect.js and TypeScript server, a React frontend over typed WebSocket RPC, SQLite for state, and Electron as the shell. Launch with `npx @overdeck/core` or the `overdeck` command (`pan` is its short alias); use `@overdeck/desktop` for the packaged desktop app. +Overdeck started as a CLI and grew into a dashboard, with **Command Deck** as its main view. The CLI, the GUI and any script that can make an HTTP request all drive the same REST surface, so you can start an agent from a kanban card, a terminal or a webhook without switching tools. Under the hood: an Effect.js and TypeScript server, a React frontend over typed WebSocket RPC, SQLite for local data such as conversations and settings, and Electron for the desktop app. Launch with `npx @overdeck/core` or the `overdeck` command (`pan` is its short alias); use `@overdeck/desktop` for the packaged desktop app. ## Get help diff --git a/vision.mdx b/vision.mdx index 8f395b11152..655a097ac22 100644 --- a/vision.mdx +++ b/vision.mdx @@ -1,12 +1,13 @@ --- -title: Flywheel Vision +title: "Flywheel vision and v1.0 readiness criteria" +sidebarTitle: "Flywheel Vision" description: "The roadmap for the Overdeck Flywheel: a dev loop that builds Overdeck today, and the readiness criteria for a user-facing delivery pipeline at v1.0." --- **A living north-star document.** It explains *why* the Flywheel exists and what it is -becoming. The operational *how* lives in [`roles/flywheel.md`](https://github.com/eltmon/overdeck/blob/main/roles/flywheel.md); the -per-run *what* lives in `docs/flywheel-brief.md`. When the role or -the brief ever drifts from this doc, the vision wins — fix the role or the brief. +becoming. The operational *how* lives in [`roles/flywheel.md`](https://github.com/eltmon/overdeck/blob/main/roles/flywheel.md). +The loop's operating prompt is the [`pan-flywheel` skill](https://github.com/eltmon/overdeck/blob/main/sync-sources/skills/pan-flywheel/SKILL.md), and a bound order book under `.pan/orders/` sets the scope of a run. +If the role or the skill drifts from this page, this page wins: fix the role or the skill. To run the Flywheel today, see [Flywheel](/features/flywheel). @@ -27,8 +28,8 @@ This document names the mental model, the vocabulary, and the measurable criteri ### Today: the Flywheel as substrate dev-loop The Flywheel takes whatever work is moving through Overdeck and watches it flow. When a stage -misbehaves — a review specialist fails to block obvious issues, a test agent loops, a merge -gate confuses itself, a planning artifact lands at the wrong path — the failure is a defect in +misbehaves (a review specialist fails to block obvious issues, a test agent loops, a merge +gate confuses itself, a planning artifact lands at the wrong path), the failure is a defect in Overdeck, not in the work. We call those **substrate bugs**. The work issue is almost a vehicle. The real product of a revolution is: @@ -38,7 +39,7 @@ The work issue is almost a vehicle. The real product of a revolution is: 3. Zero or more substrate-bug fixes merged (often before the original work merges). Every substrate bug is a step toward v1.0. The Flywheel exists to expose them faster than we'd -find them with manual usage — and to fix them at the root, so each revolution leaves the +find them with manual usage, and to fix them at the root, so each revolution leaves the substrate permanently better. **A workaround is a failed tick.** ### v1.0: the Flywheel as user-facing pipeline @@ -52,7 +53,7 @@ human approves. At v1.0, **the only required human input is UAT (optional, per-issue) and merge approval.** Users who trust the system more flip per-issue toggles to skip UAT for low-risk classes of work; users who trust it less keep UAT required for everything. The substrate doesn't change -either way — only the human checkpoints do. +either way: only the human checkpoints do. ### What changes between today and v1.0 @@ -60,84 +61,89 @@ either way — only the human checkpoints do. |---|---|---| | Who files issues | Mostly us, often Overdeck agents | Mostly users | | Who picks up from backlog | Operator releases each item (`auto_pickup_backlog` OFF) | The pipeline, by sequencer priority (`auto_pickup_backlog` ON) | -| Substrate-bug discovery rate | High — expected, that's the point | Low — bounded by error budget | +| Substrate-bug discovery rate | High: expected, that's the point | Low: bounded by error budget | | Required human input | UAT + merge + frequent intervention | UAT (optional) + merge | | Flywheel posture | Surface and fix our own defects | Deliver user work | -The Flywheel doesn't disappear at v1.0. It changes role — from "exposes our own defects" to -"drives the user's pipeline" — the same orchestration loop with different defaults and a much +The Flywheel doesn't disappear at v1.0. It changes role, from "exposes our own defects" to +"drives the user's pipeline": the same orchestration loop with different defaults and a much smaller intervention rate. ## Definitions -- **Substrate bug** — a defect in Overdeck itself: a broken route, a misbehaving role prompt, a +- **Substrate bug**: a defect in Overdeck itself: a broken route, a misbehaving role prompt, a wrong gate condition, a flaky lifecycle transition, a UI that lies about state. Substrate bugs are filed against `eltmon/overdeck` and fixed through the normal Overdeck pipeline. -- **Work-code bug** — a defect in the application code an issue agent is producing. Work-code - bugs are normal pipeline operation, not a v1.0 signal — review and test agents catch them. -- **Pipeline run** — one issue's journey from `start` to `merged` (or to `parked`/`cancelled`). +- **Work-code bug**: a defect in the application code an issue agent is producing. Work-code + bugs are normal pipeline operation, not a v1.0 signal: review agents and CI tests catch them. +- **Pipeline run**: one issue's journey from `start` to `merged` (or to `parked`/`cancelled`). The Flywheel may have many issues in flight; each is its own run for measurement. -- **Pipeline pass** — a single end-to-end completion: plan → work → review → test → merge. A - run may take multiple passes if review or test rejects work and the agent re-submits. -- **Operator intervention** — any human action on a run beyond clicking merge: filing a +- **Pipeline pass**: a single end-to-end completion: plan, work, review, tests, merge. Tests run + as CI on the PR head; the automatic test-agent step after review does not run today + ([#5537](https://github.com/eltmon/overdeck/issues/5537)). A run may take multiple passes if + review or test rejects work and the agent re-submits. +- **Operator intervention**: any human action on a run beyond clicking merge: filing a substrate bug, telling an agent something, pausing/resuming, restarting a review cycle, - editing a workspace file, manual merge resolution. UAT is *not* an intervention — it's the + editing a workspace file, manual merge resolution. UAT is *not* an intervention: it's the expected human checkpoint. -- **Substrate-bug discovery rate** — substrate bugs filed per pipeline run, over a rolling +- **Substrate-bug discovery rate**: substrate bugs filed per pipeline run, over a rolling window. The headline v1.0 metric. ## The autonomy model Three properties govern how much the Flywheel does on its own. The first is a permanent -security invariant; the other two are operator toggles (persisted in the `app_settings` SQLite -table, user-machine level) that move the human checkpoints without changing the substrate. +security invariant; the other two are operator toggles (persisted as `flywheel.auto_pickup_backlog` +and `flywheel.require_uat_before_merge` in the `app_settings` SQLite table, user-machine level) +that move the human checkpoints without changing the substrate. ### Author + assignee invariant (security-critical, always on) The Flywheel includes an issue in inventory and suggestions **only if at least one of**: - `author.login` is `eltmon` (project owner), **OR** -- `author.login` is `panopticon-agent[bot]` (the Overdeck GitHub App), **OR** +- `author.login` is `overdeck-agent[bot]` (the Overdeck GitHub App), **OR** - `assignees[].login` contains `eltmon` (operator has personally assigned the issue). -Any other state — third-party author and `eltmon` not among assignees — is out of scope. When +Any other state (third-party author and `eltmon` not among assignees) is out of scope. When auto-pickup is ON, this filter is the only safeguard between an attacker filing a malicious issue and the Flywheel autonomously running an agent against it. It applies *always*, regardless of any toggle, and has no relaxation flag. -### Auto-pickup from backlog (`auto_pickup_backlog`, default OFF) — the master autonomy switch +### Auto-pickup from backlog (`auto_pickup_backlog`, default OFF): the master autonomy switch -- **OFF (dev-loop today):** the Flywheel works only in-flight work plus emergency `blocks-main` - unblockers. Routine backlog stays off the start list; the operator feeds specific items in by - **Releasing** them. The Flywheel still *plans* ready backlog aggressively, so a deep - *awaiting-release* queue is always there for the operator. +- **OFF (dev-loop today):** the Flywheel works in-flight issues and the issues the operator + releases, either with the `released` label or by adding them to the active order book. The + Flywheel still *plans* ready backlog aggressively, so a deep *awaiting-release* queue is + always there for the operator. - **ON (v1.0 posture):** the toggle is a **blanket release**. The Flywheel auto-starts `ready - && planned` backlog in **sequencer-priority order**, bounded by `roles.flywheel.maxAgents`. - The gates that still apply are `vetoed` (absolute stop), `parked`/`needs-design`/ - `needs-discussion`, `objection` (an AI relevance hold), and the relevance-vet. + && planned` backlog in **sequencer-priority order**, bounded by `roles.flywheel.maxAgents` + (default 30). The gates that still apply are `vetoed` (absolute stop), `parked`/`needs-design`/ + `needs-discussion` (the legacy spellings of `parked`) and `objection` (an AI relevance hold). A single predicate is the source of truth: `isAutoPickable` in [`src/lib/backlog/pickup.ts`](https://github.com/eltmon/overdeck/blob/main/src/lib/backlog/pickup.ts), shared by the dashboard forecast and the Flywheel so they can never disagree: - ready && planned && (released || auto_pickup_backlog) && !parked && !vetoed && !objection && !inPipeline && !epic + ready && planned && (released || auto_pickup_backlog || activeBookMember) && !parked && !vetoed && !objection && !inPipeline && !epic ### UAT-required-before-merge (`require_uat_before_merge`, default ON) -"Human merges" and "human UATs" are independent constraints. When `true` (today's default), -merge cannot proceed until a human marks UAT passed. When `false`, the merge gate only requires -the configured CI checks (`overdeck/review` + `overdeck/test`); the human still clicks merge. -The "auto-merge" side — automatically clicking MERGE after a cooldown when every gate is green -— composes orthogonally: +This setting decides whether Overdeck may merge a pull request on its own, unless an issue or project override applies. +When it is on (the default), every issue defaults to **held**: Overdeck never merges the PR itself, and a human tests it +and clicks Merge. When it is off, issues default to **auto**: once the PR is approved at its head commit, every check is +green and GitHub says it is mergeable, Overdeck waits five minutes, so you can cancel, and then merges it. On a held +issue, a failed browser UAT verdict also blocks the Merge button. -| `require_uat_before_merge` | auto-merge enabled | Behavior | -|---|---|---| -| `true` (default) | `false` (default) | Human UATs, human clicks merge | -| `true` | `true` | Human UATs, system auto-merges after cooldown | -| `false` | `false` | Human merges without requiring UAT | -| `false` | `true` | Unattended merge after cooldown; only for trusted classes of work | +The setting is the last of three tiers, and the first one that is set wins: + +1. The issue's `auto-merge` or `hold-for-uat` label (the auto-merge toggle on the issue sets it). +2. The project's `auto_merge_default` (`auto` or `hold`) in `projects.yaml`. +3. The global `require_uat_before_merge`. + +`OVERDECK_DISABLE_AUTO_MERGE=1` turns automatic merging off on a machine. See [Auto-merge](/configuration/auto-merge). -The model we want for v1.0 is "relax UAT for trusted work, but a human always owns the merge." +The model we want for v1.0 is "relax UAT for trusted work, but a human always owns the merge." Auto mode already +merges without a click, so today that goal holds only for held issues. ## v1.0 readiness criteria @@ -150,11 +156,15 @@ days**: |---|---|---|---| | 1 | [Substrate-bug discovery rate (per pipeline run)](https://github.com/eltmon/overdeck/blob/main/docs/FLYWHEEL.md) | **< 2%** (≤ 1 per 50 runs) | Best-in-class defect escape rate (<2%, Capers Jones) | | 2 | [Critical/P0 substrate bugs](https://github.com/eltmon/overdeck/blob/main/docs/FLYWHEEL.md) | **0** in rolling 30-day window | DRE convention: zero critical escapes | -| 3 | [Pipeline pass success rate (substrate-attributable failures only)](https://github.com/eltmon/overdeck/blob/main/docs/FLYWHEEL.md) | **≥ 99%** | Google/Shopify CI SLO framing | -| 4 | [MTTR for a filed substrate bug (filed → fix merged)](https://github.com/eltmon/overdeck/blob/main/docs/FLYWHEEL.md) | **< 24h median, < 1 week p95** | DORA Elite (<1hr) scaled for internal tooling | -| 5 | [Operator intervention rate per pipeline run](https://github.com/eltmon/overdeck/blob/main/docs/FLYWHEEL.md) | **< 5%** | Inverted from frontier agent autonomy on SWE-bench Verified | -| 6 | [Time-in-pipeline consistency, per complexity bucket](https://github.com/eltmon/overdeck/blob/main/docs/FLYWHEEL.md) | **p95 within 2× median** | Shopify CI p95 < 2.5× target | -| 7 | [Flake rate on substrate-attributable failures](https://github.com/eltmon/overdeck/blob/main/docs/FLYWHEEL.md) | **< 5%** | Tighter than Google's 16% / Microsoft's 13% | +| 3 | Pipeline pass success rate (substrate-attributable failures only) | **≥ 99%** | Google/Shopify CI SLO framing | +| 4 | MTTR for a filed substrate bug (filed → fix merged) | **< 24h median, < 1 week p95** | DORA Elite (<1hr) scaled for internal tooling | +| 5 | Operator intervention rate per pipeline run | **< 5%** | Inverted from frontier agent autonomy on SWE-bench Verified | +| 6 | Time-in-pipeline consistency, per complexity bucket | **p95 within 2× median** | Shopify CI p95 < 2.5× target | +| 7 | Flake rate on substrate-attributable failures | **< 5%** | Tighter than Google's 16% / Microsoft's 13% | + +Overdeck measures criteria 1 and 2 today with `pan flywheel stats`: criterion 1 as substrate bugs +(issues labeled `substrate-improvement`) filed per merged PR. Criteria 3 to 7 have no telemetry +yet. Why "all of the above" and not a weighted score: a single metric can be gamed (fewer runs → fewer bugs) or hidden (intervene constantly → success rate looks fine). The combination forces @@ -163,7 +173,7 @@ afterward we re-affirm v1.0 or name the bottleneck criterion. **What "v1.0" does not mean:** not "no bugs ever" (criterion 1 leaves an error budget); not "no human in the loop" (humans still UAT and approve merges); not "all features done" (v1.0 is -about substrate reliability — feature work continues after). +about substrate reliability; feature work continues after). ## How we measure @@ -176,7 +186,7 @@ per pipeline run" has no direct published benchmark: 2. **Pass success rate ↔ CI/CD SLO.** Google SRE and Shopify treat CI/CD as a 99%-availability service with a 1% error budget; we scope the 99% to substrate-attributable failures. 3. **Intervention rate ↔ agent-autonomy benchmarks.** Top SWE-bench Verified systems sit at - 80–94%; our <5% intervention target is *stricter than the agent layer* because the substrate + 80 to 94%; our <5% intervention target is *stricter than the agent layer* because the substrate is supposed to be the reliable part. Sources: [DORA 2024](https://dora.dev/research/2024/dora-report/) · @@ -191,31 +201,20 @@ This is why the criteria are **draft** and revisited after ~1 month of data. ## The path there -The work that gets us to v1.0 is tracked by the `v1.0-required` GitHub label, which is the -canonical, always-current list — this doc deliberately does not inline it, because a snapshot -here goes stale while the label stays true: - -> **Live critical path:** [open `v1.0-required` issues](https://github.com/eltmon/overdeck/issues?q=is%3Aissue+is%3Aopen+label%3A%22v1.0-required%22) +The `v1.0-required` GitHub label marks work on the path to v1.0. It has no open issues right now: +[`v1.0-required` issues](https://github.com/eltmon/overdeck/issues?q=is%3Aissue+label%3A%22v1.0-required%22). The minimum bar underneath every criterion is **substrate-bug provenance + telemetry** (so the seven criteria can be measured at all) and **metric-aware prioritization** (so the bottleneck -criterion bubbles to the top of the sequencer rather than P-level and age alone). Substrate bugs -declare affected v1.0 criteria via the `Flywheel-Affects-Criterion` trailer; `pan flywheel weights --json` -computes a per-bug weight from live telemetry, and the Flywheel orders substrate-hardening -suggestions by that weight within the tier. See `docs/FLYWHEEL.md` for the trailer format and the -weight model. The Flywheel and the backlog sequencer prioritize substrate-hardening epics first: -a stable substrate is the prerequisite for everything else on the path. +criterion bubbles to the top of the sequencer rather than P-level and age alone). `pan flywheel +stats --json` reports the substrate-bug rate and the P0 count. The Flywheel and the backlog +sequencer prioritize substrate-hardening epics first: a stable substrate is the prerequisite for +everything else on the path. ## Open questions Decisions we haven't made and don't need to make today, but should revisit before v1.0: -- **Per-issue UAT override.** Once the global `require_uat_before_merge` flag exists, do we add - a per-issue override (a `bypass-uat` label or an xBRIEF field)? Defer until after the global - toggle has run for a while. -- **Substrate-bug label.** A dedicated `substrate-bug` label for visibility, separate from the - commit-trailer provenance? Probably yes for visibility — but it never replaces provenance - (labels can be edited; trailers can't). - **What counts as a pipeline run for measurement?** Does a parked/cancelled issue count? We may scope the denominator to runs that reach at least the work stage. - **When to retire this doc.** At v1.0 it transitions from "north star" to "history of how we got @@ -226,11 +225,11 @@ Decisions we haven't made and don't need to make today, but should revisit befor - [`roles/flywheel.md`](https://github.com/eltmon/overdeck/blob/main/roles/flywheel.md): the **durable doctrine**, root-cause rules and the load-bearing rails (author/assignee gate, pickup gate, veto, saturation cap). The tick loop itself is the `pan-flywheel` skill. -- `docs/flywheel-brief.md`: the **per-run scope contract**, scope - and this run's config. The *what-this-run*. +- [`sync-sources/skills/pan-flywheel/SKILL.md`](https://github.com/eltmon/overdeck/blob/main/sync-sources/skills/pan-flywheel/SKILL.md): the + tick loop, and `.pan/orders/`: the order books that scope a run. - [`docs/FLYWHEEL.md`](https://github.com/eltmon/overdeck/blob/main/docs/FLYWHEEL.md): technical reference for the contract, lifecycle, and dashboard surfaces. -- `docs/FLYWHEEL-STATE.md`: durable cumulative memory authored by the - orchestrator across runs. -- [`packages/contracts/src/flywheel.ts`](https://github.com/eltmon/overdeck/blob/main/packages/contracts/src/flywheel.ts): the - `FlywheelStatus` schema the orchestrator emits each tick. +- `.pan/flywheel/state.md`: the loop's memory across runs, and `.pan/flywheel/report.md`: the + latest run report. +- [`packages/contracts/src/flywheel-derived.ts`](https://github.com/eltmon/overdeck/blob/main/packages/contracts/src/flywheel-derived.ts): the + `FlywheelDerivedStatus` shape that `pan flywheel status` and the Flywheel page compute on read.