diff --git a/.pan/continues/PAN-5502.xbrief.json b/.pan/continues/PAN-5502.xbrief.json new file mode 100644 index 00000000000..c866f40e373 --- /dev/null +++ b/.pan/continues/PAN-5502.xbrief.json @@ -0,0 +1,492 @@ +{ + "version": "1", + "issueId": "PAN-5502", + "created": "2026-11-19T05:29:14.806Z", + "updated": "2026-11-19T06:10:01.437Z", + "gitState": {}, + "decisions": [], + "hazards": [], + "resumePoint": null, + "sessionHistory": [ + { + "reason": "feedback", + "note": "[2026-11-19T06:10Z] coderabbit → FINDINGS — seq 1", + "timestamp": "2026-11-19T06:10:01.437Z" + } + ], + "items": { + "conv-surface": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:29:14.806Z", + "doneAt": "2026-11-19T05:30:50.813Z" + }, + "conv-surface.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:30:50.813Z" + }, + "conv-surface.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:30:50.813Z" + }, + "conv-surface.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:30:50.813Z" + }, + "conv-surface.ac4": { + "status": "completed", + "doneAt": "2026-11-19T05:30:50.813Z" + }, + "conv-surface.ac5": { + "status": "completed", + "doneAt": "2026-11-19T05:30:50.813Z" + }, + "conv-handoff": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:31:00.322Z", + "doneAt": "2026-11-19T05:32:25.556Z" + }, + "conv-handoff.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:32:25.556Z" + }, + "conv-handoff.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:32:25.556Z" + }, + "conv-handoff.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:32:25.556Z" + }, + "conv-handoff.ac4": { + "status": "completed", + "doneAt": "2026-11-19T05:32:25.556Z" + }, + "conv-handoff.ac5": { + "status": "completed", + "doneAt": "2026-11-19T05:32:25.556Z" + }, + "conv-machines-to-end": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:34:26.728Z", + "doneAt": "2026-11-19T05:35:53.250Z" + }, + "conv-machines-to-end.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:35:53.250Z" + }, + "conv-machines-to-end.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:35:53.250Z" + }, + "conv-machines-to-end.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:35:53.250Z" + }, + "conv-machines-to-end.ac4": { + "status": "completed", + "doneAt": "2026-11-19T05:35:53.250Z" + }, + "audit-skill-packs": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:36:02.190Z", + "doneAt": "2026-11-19T05:37:21.056Z" + }, + "audit-skill-packs.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:37:21.056Z" + }, + "audit-skill-packs.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:37:21.056Z" + }, + "audit-skill-packs.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:37:21.056Z" + }, + "audit-skill-packs.ac4": { + "status": "completed", + "doneAt": "2026-11-19T05:37:21.056Z" + }, + "audit-skills": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:37:26.348Z", + "doneAt": "2026-11-19T05:38:28.565Z" + }, + "audit-skills.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:38:28.565Z" + }, + "audit-skills.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:38:28.565Z" + }, + "audit-skills.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:38:28.565Z" + }, + "audit-skills.ac4": { + "status": "completed", + "doneAt": "2026-11-19T05:38:28.565Z" + }, + "audit-skills.ac5": { + "status": "completed", + "doneAt": "2026-11-19T05:38:28.565Z" + }, + "audit-safe-shutdown": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:38:34.560Z", + "doneAt": "2026-11-19T05:39:10.007Z" + }, + "audit-safe-shutdown.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:39:10.007Z" + }, + "audit-safe-shutdown.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:39:10.007Z" + }, + "audit-safe-shutdown.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:39:10.007Z" + }, + "audit-swarm": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:39:15.938Z", + "doneAt": "2026-11-19T05:39:50.442Z" + }, + "audit-swarm.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:39:50.442Z" + }, + "audit-swarm.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:39:50.442Z" + }, + "audit-swarm.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:39:50.442Z" + }, + "workspaces-layout-to-lifecycle": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:39:59.155Z", + "doneAt": "2026-11-19T05:40:57.191Z" + }, + "workspaces-layout-to-lifecycle.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:40:57.191Z" + }, + "workspaces-layout-to-lifecycle.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:40:57.191Z" + }, + "workspaces-layout-to-lifecycle.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:40:57.191Z" + }, + "workspaces-layout-to-lifecycle.ac4": { + "status": "completed", + "doneAt": "2026-11-19T05:40:57.191Z" + }, + "workspaces-layout-to-lifecycle.ac5": { + "status": "completed", + "doneAt": "2026-11-19T05:40:57.191Z" + }, + "workspaces-safeguards-to-end": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:41:10.667Z", + "doneAt": "2026-11-19T05:41:55.377Z" + }, + "workspaces-safeguards-to-end.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:41:55.377Z" + }, + "workspaces-safeguards-to-end.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:41:55.377Z" + }, + "workspaces-safeguards-to-end.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:41:55.377Z" + }, + "workspaces-safeguards-to-end.ac4": { + "status": "completed", + "doneAt": "2026-11-19T05:41:55.377Z" + }, + "audit-specialists": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:42:00.829Z", + "doneAt": "2026-11-19T05:42:43.596Z" + }, + "audit-specialists.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:42:43.596Z" + }, + "audit-specialists.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:42:43.596Z" + }, + "audit-specialists.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:42:43.596Z" + }, + "audit-convoys": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:42:51.843Z", + "doneAt": "2026-11-19T05:43:36.873Z" + }, + "audit-convoys.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:43:36.873Z" + }, + "audit-convoys.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:43:36.873Z" + }, + "audit-convoys.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:43:36.873Z" + }, + "audit-convoys.ac4": { + "status": "completed", + "doneAt": "2026-11-19T05:43:36.873Z" + }, + "audit-cloister": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:43:42.455Z", + "doneAt": "2026-11-19T05:44:09.161Z" + }, + "audit-cloister.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:44:09.161Z" + }, + "audit-cloister.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:44:09.161Z" + }, + "audit-merge-batches": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:44:14.691Z", + "doneAt": "2026-11-19T05:45:11.814Z" + }, + "audit-merge-batches.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:45:11.814Z" + }, + "audit-merge-batches.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:45:11.814Z" + }, + "audit-merge-batches.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:45:11.814Z" + }, + "audit-merge-batches.ac4": { + "status": "completed", + "doneAt": "2026-11-19T05:45:11.814Z" + }, + "audit-mission-control": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:45:17.660Z", + "doneAt": "2026-11-19T05:47:06.151Z" + }, + "audit-mission-control.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:47:06.151Z" + }, + "audit-mission-control.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:47:06.151Z" + }, + "audit-mission-control.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:47:06.151Z" + }, + "audit-mission-control.ac4": { + "status": "completed", + "doneAt": "2026-11-19T05:47:06.151Z" + }, + "audit-keyboard-shortcuts": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:47:11.837Z", + "doneAt": "2026-11-19T05:47:52.668Z" + }, + "audit-keyboard-shortcuts.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:47:52.668Z" + }, + "audit-keyboard-shortcuts.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:47:52.668Z" + }, + "audit-keyboard-shortcuts.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:47:52.668Z" + }, + "audit-file-explorer": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:48:01.111Z", + "doneAt": "2026-11-19T05:48:31.955Z" + }, + "audit-file-explorer.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:48:31.955Z" + }, + "audit-file-explorer.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:48:31.955Z" + }, + "audit-open-in-overdeck": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:48:37.635Z", + "doneAt": "2026-11-19T05:49:07.017Z" + }, + "audit-open-in-overdeck.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:49:07.017Z" + }, + "audit-open-in-overdeck.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:49:07.017Z" + }, + "audit-issue-pipeline": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:49:12.788Z", + "doneAt": "2026-11-19T05:49:44.752Z" + }, + "audit-issue-pipeline.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:49:44.752Z" + }, + "audit-issue-pipeline.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:49:44.752Z" + }, + "audit-planning": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:49:49.929Z", + "doneAt": "2026-11-19T05:50:27.594Z" + }, + "audit-planning.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:50:27.594Z" + }, + "audit-planning.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:50:27.594Z" + }, + "audit-planning.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:50:27.594Z" + }, + "audit-flywheel": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:50:33.210Z", + "doneAt": "2026-11-19T05:51:15.313Z" + }, + "audit-flywheel.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:51:15.313Z" + }, + "audit-flywheel.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:51:15.313Z" + }, + "audit-flywheel.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:51:15.313Z" + }, + "audit-dashboard-views": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:51:21.150Z", + "doneAt": "2026-11-19T05:51:57.755Z" + }, + "audit-dashboard-views.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:51:57.755Z" + }, + "audit-dashboard-views.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:51:57.755Z" + }, + "audit-costs": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:52:03.318Z", + "doneAt": "2026-11-19T05:52:37.539Z" + }, + "audit-costs.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:52:37.539Z" + }, + "audit-costs.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:52:37.539Z" + }, + "audit-desktop-app": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:52:42.945Z", + "doneAt": "2026-11-19T05:53:23.897Z" + }, + "audit-desktop-app.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:53:23.897Z" + }, + "audit-desktop-app.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:53:23.897Z" + }, + "validate-and-pr-body": { + "status": "completed", + "claimedBy": "agent-pan-5502", + "claimedAt": "2026-11-19T05:53:31.125Z", + "doneAt": "2026-11-19T05:55:29.979Z" + }, + "validate-and-pr-body.ac1": { + "status": "completed", + "doneAt": "2026-11-19T05:55:29.979Z" + }, + "validate-and-pr-body.ac2": { + "status": "completed", + "doneAt": "2026-11-19T05:55:29.979Z" + }, + "validate-and-pr-body.ac3": { + "status": "completed", + "doneAt": "2026-11-19T05:55:29.979Z" + }, + "validate-and-pr-body.ac4": { + "status": "completed", + "doneAt": "2026-11-19T05:55:29.979Z" + } + }, + "feedback": [ + { + "seq": 1, + "specialist": "coderabbit", + "outcome": "findings", + "timestamp": "2026-11-19T06:10:01Z", + "markdownBody": "# CodeRabbit findings for PAN-5502 (PR #5583)\n\nCodeRabbit posted 9 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 4624988983 · features/costs.mdx:40 [Minor]: Clarify costs for unlisted models with reported costs.\n https://github.com/eltmon/overdeck/pull/5583#discussion_r4624988983\n- Thread 4624988987 · features/costs.mdx:47 [Minor]: Document the working-directory rule for the Claude Code fallback, not the branch.\n https://github.com/eltmon/overdeck/pull/5583#discussion_r4624988987\n- Thread 4624988997 · features/desktop-app.mdx:68 [Minor]: Remove the browser claim for the installed-command path.\n https://github.com/eltmon/overdeck/pull/5583#discussion_r4624988997\n- Thread 4624989002 · features/merge-batches.mdx:85 [Minor]: Qualify the accumulate step for the batch window.\n https://github.com/eltmon/overdeck/pull/5583#discussion_r4624989002\n- Thread 4624989007 · features/skill-packs.mdx:773 [Minor]: Correct the Atlassian header scope: it is not limited to Cloud base URLs.\n https://github.com/eltmon/overdeck/pull/5583#discussion_r4624989007\n- Thread 4624989017 · features/skills.mdx:225 [Minor]: Document the `okf` vendored-skill overwrite exception.\n https://github.com/eltmon/overdeck/pull/5583#discussion_r4624989017\n- Thread 4624989040 · features/skills.mdx:227 [Major]: Document that `pan sync` overwrites any same-path file in `~/.claude/skills`, not only bundled skills.\n https://github.com/eltmon/overdeck/pull/5583#discussion_r4624989040\n- Thread 4624989047 · features/workspaces.mdx:140 [Minor]: Correct the Docker project-name fallback for `pan workspace create --docker`.\n https://github.com/eltmon/overdeck/pull/5583#discussion_r4624989047\n- Thread 4624989059 · features/workspaces.mdx:375 [Minor]: Separate cancellation from the transition to work.\n https://github.com/eltmon/overdeck/pull/5583#discussion_r4624989059\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/5583/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-5502 -m \"CodeRabbit : \"`.\n If you only replied, you are done.\n5. If PR #5583 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-5502.md b/.pan/drafts/PAN-5502.md new file mode 100644 index 00000000000..9389e17a91d --- /dev/null +++ b/.pan/drafts/PAN-5502.md @@ -0,0 +1,2316 @@ +# PAN-5502: accuracy audit of the Features docs group + +**Issue:** https://github.com/eltmon/overdeck/issues/5502 (part of epic #5467, docs overhaul) +**Priority:** P1. Docs-only change. No code changes, no `changelog.d` entry. +**Base:** `main` at `2007e9a4d3c` (v0.89.1 plus later merges), 2026-11-19. Every prerequisite PR named in the issue has +merged, and its commit is in the history of the page it edited: PAN-5474 (`c70b40b4a6b`) and PAN-5472 (`94f8a78502d`) +on `mission-control.mdx`; PAN-5472 on `specialists.mdx`; PAN-5471 (`c5235aaecfb`) and PAN-5472 on `cloister.mdx`; +PAN-5479 (`919cc020249`) on `workspaces.mdx`; PAN-5482 (`0558b4ab739`) on `swarm.mdx`. No open PR touches +`features/*.mdx` (checked with `gh pr list --state open --json files`). So this audit works on top of all of them. + +## Summary + +The issue asks for a line-by-line accuracy audit of every published page in the **Features** navigation group. The +planning session already did the audit. Ten research passes read all 20 pages (5,679 lines) against the code on the +base. The planner then checked every change-table row mechanically: each grep anchor matches its page exactly once, +and each evidence quote cited with a full repo path greps in its file. Quotes cited by a bare file name, or with +escaped quotes, were not machine-checked; the planner spot-checked them for the rows below and for every section +deletion. Absence claims ("no match") were re-run for the deleted skills and the mission-control sections. The planner +also re-checked these high-stakes claims by hand: + +- the model lock in conversations (`ComposerToolbar.tsx:20`, `ComposerFooter.tsx:186`, `conversation-runtime.ts:435-445`); +- every `pan handoff` option (`src/cli/index.ts:378-397`); +- the test-role dispatch gap (#5537 open; `review-pipeline.ts:644` is the only request-time dispatch; nothing emits `review.approved`); +- the server merge path (`merge-ops.ts:878`, `merge-strike.ts:630-636`); +- the `pan workspace destroy --force` no-op (`workspace-list.ts:505-523`); +- the mission-control section deletions (BadgeBar, the `ActivityView` hosts and `TranscriptUpload` have no mounted importer); +- the stale handoff-dialog screenshot (it shows a **Harness** dropdown that `ModelPicker.tsx:446-449` no longer renders). + +This PRD lists every wrong, stale or removed claim per page, each with the exact current text, the replacement text and +the code evidence. The implementation agent does seven things. It applies those changes. It removes the en and em dashes. +It fixes frontmatter. It deletes the screenshots that show removed UI. It checks links. It runs the Mintlify validators. +It writes a PR body with one note per page. It does not need to re-research. It re-checks a claim only when a grep anchor +no longer matches. + +## Glossary + +- **Features group**: the `"group": "Features"` block in `docs.json` (line 104). On the base it lists 20 pages, each + `features/.mdx`: `issue-pipeline`, `planning`, `flywheel`, `conversations`, `file-explorer`, `mission-control`, + `dashboard-views`, `costs`, `convoys`, `specialists`, `merge-batches`, `swarm`, `skills`, `skill-packs`, `workspaces`, + `cloister`, `safe-shutdown`, `open-in-overdeck`, `desktop-app`, `keyboard-shortcuts`. +- **Listed pages**: the 14 pages named in the issue body. **Added pages**: the six pages the epic's child issues added to + the group after the issue was filed (`issue-pipeline` by PAN-5468, `planning` by PAN-5469, `flywheel` by PAN-5470, + `dashboard-views` by PAN-5474, `costs` by PAN-5475, `desktop-app` by PAN-5473). +- **Claim**: any statement on a page a reader could act on. That includes a command or flag, a config key or default, a + UI label or location, a file path, a behavior, a limit, a keyboard binding, and a list of supported harnesses or + platforms. +- **Primary source**: the code on the base (`git grep`), the commander definitions under `src/cli/`, + `src/lib/config-yaml/defaults.ts`, the dashboard source under `src/dashboard/frontend/src/` and + `src/dashboard/server/`, and `changelog.mdx`. Other `.mdx` pages, `docs/*.md`, `README.md` and skills are never proof. + One exception: for the Flywheel loop's own behavior, `sync-sources/skills/pan-flywheel/SKILL.md` is the program + `pan flywheel start` runs, so it counts. Where it disagrees with code, code wins. +- **Grep anchor**: the quoted current text in each change table. Line numbers drift as earlier edits land, so find the + text with `grep -n -F '' features/.mdx`, not by line number. In the appendices an anchor is the text + inside the outer backticks of the "Grep anchor" cell. Where a cell holds `\|`, the page has a plain `|`. Where a + replacement holds `` \` ``, type a plain backtick; the backslash only escapes it inside the table cell. Line numbers + in an appendix are base line numbers; each section item states its range by heading. +- **Dash rule**: no U+2013 (en dash) or U+2014 (em dash) anywhere in a touched page, frontmatter and body. Check: + `grep -nP '[\x{2013}\x{2014}]' features/.mdx` prints nothing. Replace a dash with a comma, colon, period, + parentheses, or the word "to" for a range. Arrows (`→`) and box-drawing characters (`─`, `│`, `├`) are not dashes. +- **Frontmatter rule**: `title` is specific and searchable. `description` is 50 to 160 characters, counting the text + between the quotes. Neither contains a dash. When this PRD retitles a page, also add `sidebarTitle: ""`, + unless the page already has a `sidebarTitle`, so the navigation label stays short. `configuration/docs-rag.mdx` uses + this pattern already. +- **Experimental**: a dashboard view hidden unless Settings → Experimental → **Experimental features** is on. The gated + tab ids are in `EXPERIMENTAL_TAB_IDS` (`src/dashboard/frontend/src/lib/experimentalFeatures.ts:4`): `agents`, + `autopreso`, `resources`, `sessions`, `metrics`, `costs`, `health`, `god-view`. Navigating to one with the switch off + lands on Home (`src/dashboard/frontend/src/App.tsx:410` "const nextTab = denyExperimental && isExperimentalTab(tab) ? + 'home' : tab;"). +- **Stale screenshot**: a page image that shows UI the code no longer renders. This issue does not recapture images. + Where only the alt text is wrong, the alt text is rewritten. Where the image shows removed UI, the `` + block is deleted and a recapture goes to Follow-ups (Decision D5). +- **Follow-ups**: code bugs or out-of-scope doc problems found during the audit. They go in a `## Follow-ups` list in the + PR body. This issue changes no code. +- **PR note**: a one-line summary of what changed on a page, or "verified, no change". Each page item puts its note in its + commit message as a line `PR-note: features/.mdx: `. WI-Z1 collects them into the PR body. + +## Background and evidence + +- **Scope grew from 14 to 20 pages.** The issue lists 14 pages. Since it was filed, the epic's child issues added six + pages to the group (see Glossary, "Added pages"). No other audit issue covers them: the bodies of #5499, #5500, #5501, + #5503 and #5504 name no `features/` page (`gh issue view --json body | grep -o 'features/[a-z-]*\.mdx'` prints + nothing for each). The issue's scope sentence is "every published page in the Features nav group". PAN-5503 (#5577) + made the same call for its group. Decision D1 includes them. They were written this week, so their tables are short. +- **Issue comments, tested against code.** Every claim in the four issue comments was tested, not assumed: + - specialists (comment 1): all three claims hold. See WI-G1. + - swarm (comment 2): PAN-5482 rewrote the page and has merged. The audit found six small fixes. See WI-E3. + - workspaces (comment 3): all five suspicions hold except one. The git hook and `OVERDECK_AUTO_REVERT_CHECKOUT` still + exist. See WI-F1 and WI-F2. + - screenshots (comment 4): the four recaptured images were opened. Their alt text is wrong on all four pages that use + them. See WI-A1, WI-F1, WI-G2 and WI-H1. +- **Before-state per page** (dash lines counted with the dash-rule grep; description lengths without quotes): + +| Page | Lines | Dash lines | Title | Description chars | +| --- | --- | --- | --- | --- | +| mission-control | 263 | 0 | Command Deck | 133 | +| conversations | 1346 | 66 | Conversations & Handoff | 151 | +| specialists | 55 | 0 | Review and test agents: checking an agent's work | 149 | +| cloister | 87 | 0 | Cloister lifecycle manager | 145 | +| safe-shutdown | 85 | 0 | Safe shutdown | 52 | +| skills | 338 | 6 | Skills System | 141 | +| skill-packs | 829 | 19 | Skill Packs | 98 | +| workspaces | 553 | 0 | Workspaces: issue worktrees, scratch work and the main checkout | 139 | +| file-explorer | 123 | 0 | File explorer | 71 | +| open-in-overdeck | 107 | 0 | Open in Overdeck | 105 | +| keyboard-shortcuts | 96 | 0 | Keyboard shortcuts | 127 | +| convoys | 329 | 0 | Review convoy | 67 | +| swarm | 49 | 0 | Swarm: parallel workers on one issue with the foreman | 125 | +| merge-batches | 204 | 12 | UAT Batch Trains | 75 | +| issue-pipeline | 169 | 0 | Issue pipeline: from issue to merged PR | 144 | +| planning | 274 | 0 | Planning: PRDs, xBRIEF plans and the plan critic | 145 | +| flywheel | 189 | 0 | Flywheel: an autonomous loop that works your backlog | 149 | +| dashboard-views | 240 | 0 | Dashboard views: Home, Board, Pipeline and the Experimental switch | 124 | +| costs | 164 | 0 | Costs and spend: how Overdeck tracks what agents cost | 146 | +| desktop-app | 179 | 0 | Desktop app for macOS, Windows and Linux | 126 | + +- **Validators.** `npx -y mint@4.3.49 validate` and `npx -y mint@4.3.49 broken-links --check-anchors` are the + checks PAN-5500 (#5581) ran. Its PR body (run on its own base, just before this one) records 3 broken links in 2 + files; WI-Z1 re-runs the check on this branch. + Two are in this group, `features/skills.mdx` → `/cli/core-commands#pan-skill-creator` and + `/cli/core-commands#pan-subagent-creator`; WI-E1 fixes both. The third, `guides/docker-setup.mdx` → + `/reference/troubleshooting#slow-vitereact-frontend-with-multiple-workspaces`, is outside the group and belongs to + #5504. `mint validate` passes with `duplicate-h1` warnings that exist across the repo (`safe-shutdown.mdx` has one); + they are not new and are not fixed here (NFR-2). +- **What breaks the validators** (`.overdeck/context/codebase/concerns.md`, "`npx mint validate` and + `npx mint broken-links` pass on `main`"): a bare `` in prose outside backticks (MDX reads it as a JSX tag), an + unquoted frontmatter `description` containing `: `, an `import ... from "react"` line in a snippet, and relative links + to files that `.mintignore` excludes. `npm run lint:docs` (`scripts/lint-docs.js`) catches only `$` in prose and `<` + before a digit. +- **Help sections.** These pages already link both the Discord and GitHub Issues: `conversations`, `swarm`, + `issue-pipeline`, `planning`, `flywheel`, `dashboard-views`, `costs` and `desktop-app`. Three pages have a + troubleshooting section without the links: `skill-packs`, `convoys` and `workspaces`. Their items add them (D3). + +## Requirements + +- **FR-1**: Every wrong, stale or removed claim listed in the work items and appendices is replaced with the listed text + or deleted as listed. Wording may be adjusted for flow; the fact may not. +- **FR-2**: For any claim on a page that this PRD does not list, the executor applies the residual rule (Common procedure + step 3). It verifies the claim against a primary source only if the claim looks doubtful. If the code disagrees, it + fixes the page to match the code. It never changes code. +- **FR-3**: Every page in the group satisfies the dash rule. +- **FR-4**: Every page in the group satisfies the frontmatter rule. The titles and descriptions named in the work items + change; each retitled page gets a `sidebarTitle` holding the old title (unless it already has one). +- **FR-5**: Every internal link on every page resolves to an existing page, and to an existing heading for an anchor, + counting `docs.json` redirects. `npx -y mint@4.3.49 broken-links --check-anchors` reports no broken link in a + `features/` page. +- **FR-6**: `skill-packs`, `convoys` and `workspaces` link the Overdeck Discord (https://discord.gg/ZpHE2ZTv5P) and + GitHub Issues (https://github.com/eltmon/overdeck/issues) in or right after their troubleshooting section. The eight + pages that already have both links keep them. +- **FR-7**: Every place a page sends the reader to an experimental view, or describes one, says it is experimental and + names the switch (Settings → Experimental → **Experimental features**). The rows that do this: conversations none; + workspaces row 34 (Resources); convoys row 6 (God View); mission-control M3 (Agents page); keyboard-shortcuts K1 + (`G` then `A`) and K3 (God View); dashboard-views row 1 (Analytics opens Metrics). +- **FR-8**: Screenshot alt text matches what the image shows (hero, board and pipeline images). The `` + blocks that show removed UI are deleted: `continue-modal`, `continue-modal-advanced` and `skills`; mission-control + `activity` goes with its section. +- **FR-9**: The PR body ticks all 20 pages with a one-line note each. It pastes the clean output of the dash loop, + `npm run lint:docs`, `npx -y mint@4.3.49 validate` and `npx -y mint@4.3.49 broken-links --check-anchors`. It lists + the Follow-ups. +- **NFR-1**: No file outside the 20 `features/*.mdx` pages changes, except the PR body. No code, test, rule, image, + `docs.json`, `CLAUDE.md` or `changelog.d` change. Image files are not deleted even when a page stops using them. +- **NFR-2**: No heading text changes, except where a work item says so explicitly. Those items are: `workspaces` + `### Specialist Agent Safeguards` → `### Agent safeguards`, and `### Planning Artifacts` → `### Planning artifacts` + (same slug); `mission-control` deletes `## Activity View` (with `### Section Isolation Mode`), `## Badge Bar`, + `## Status Reviews` and `### Model Selection`, and replaces `## Planning Artifacts` (with `### Uploading Artifacts` + and `### Syncing Discussions`) with `## Issue documents`; `skills` replaces + `### Code Review Subagents` with `### Code review`. Each of these was checked for inbound links (none exist). The + repo-wide `duplicate-h1` style is left alone. +- **NFR-3**: Prose follows the repo writing rules: plain, active, short sentences; no em or en dashes; no hype. + +## Decisions + +- **D1 (scope)**: audit the 20 pages in the Features group on the base, not only the 14 in the issue body. The six added + pages get the same procedure; their tables are short. Rationale under Background. +- **D2 (prerequisite PRs)**: all five prerequisite PRs have merged (Base line). Audit the pages as they are on the base. + The swarm comment ("treat that page as covered by PAN-5482") is satisfied: PAN-5482 landed, and this audit checks its + result, with six small rows. +- **D3 (help links)**: add the Discord and GitHub Issues sentence only where a page talks about getting help (FR-6). Do + not add a help section to every page. The sentence, as the last paragraph of each troubleshooting section, or under a + new `## Get help` heading where the row says so: "Still stuck? Ask on the + [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a [GitHub Issue](https://github.com/eltmon/overdeck/issues)." +- **D4 (code bugs)**: when the code is wrong rather than the doc, the page states what the code does today and the bug + goes to Follow-ups. Examples: the test role is never dispatched after approval (#5537), and + `pan workspace destroy --force` does nothing. Never describe intended behavior as current. +- **D5 (stale screenshots)**: this issue adds and replaces no image. Wrong alt text is rewritten. An image that shows UI + the code no longer renders is removed from the page by deleting its whole `` block, and a recapture + goes to Follow-ups. The deleted blocks are listed in FR-8. The image files stay in `images/` (NFR-1). If deleting the + last `` on a page leaves the `import { ThemedImage } ...` line unused, keep the import; Mintlify ignores + it. +- **D6 (removed features)**: delete the section about a removed feature. Do not keep it with a "removed" note, unless + the work item says to keep a pointer. +- **D7 (one PR)**: the epic asks for one PR per audit issue. All items commit to `feature/pan-5502`; one PR. +- **D8 (titles)**: a page is retitled only where its work item says so. That applies to generic one- or two-word + titles: `Skills System`, `Skill Packs`, `Safe shutdown`, `File explorer`, `Keyboard shortcuts`, `Review convoy` and + `UAT Batch Trains`. `Command Deck` and `Open in Overdeck` are product names and stay. Slugs and file names never change. +- **D9 (model lock wording)**: in the dashboard, a conversation's model is fixed once it starts, for every harness + (`ComposerFooter.tsx:186` "const canEditModelBeforeStart = !agentId && !conversation.sessionAlive && + !conversation.claudeSessionId;"). The server still accepts a live model change for a running Pi conversation + (`conversation-runtime.ts:441` "const livePiSwitch = isPiControlChannelHarness(currentHarness) && conv.status !== + 'ended';"), but no dashboard control sends one. The conversations page describes the dashboard. The server-only path + is a Follow-up. +- **D10 (unverifiable figures)**: figures that code in this repo cannot confirm stay as written, unless a row changes + them. Examples: skill counts that depend on a pack fork's contents, and macOS notarization status. The research passes + list them under "Follow-ups" or "Unsure". The same holds for the macOS `⌘W` and `⌘T` bindings in a Chrome tab, which + need a real Mac to test (keyboard-shortcuts Follow-up). + +## Repo rules that apply + +- Work only inside `workspaces/feature-pan-5502` on branch `feature/pan-5502`. Never `git checkout` another branch. + Never `git stash`. +- One commit per item, with an `Item: ` trailer, the AC trailers, and 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-Z1) + `npx -y mint@4.3.49 validate` and `npx -y mint@4.3.49 broken-links --check-anchors`. +- While you verify a claim, never send a destructive HTTP request and never run a `pan` command other than + `pan --help`. +- Issue and PR references in prose stay markdown links (`[#5537](https://github.com/eltmon/overdeck/issues/5537)`). +- Keep every `` inside backticks (MDX safety). The appendices write placeholders as ``; type them as + literal `<` and `>` characters in the page, inside backticks. + +## Common procedure for every page item + +0. **Code wins.** If a primary source contradicts a row in this PRD (the research was wrong, or main moved), skip the + row and record it in the PR note. Leave that row's acceptance criterion unticked and put the evidence in the commit + message (`pan task block` with the reason). Never write a claim the code contradicts to satisfy a row. +1. **Apply the change table.** For each row, find the grep anchor with `grep -n -F`, make the change, and keep the + evidence in mind for the replacement wording. If an anchor no longer matches because another edit moved or reworded + it, find the claim by meaning. If the claim is gone, skip the row and say so in the PR note. "Replacement blocks" + in an appendix hold the exact text for rows that say "see block". +2. **Spot-check before deleting.** Before deleting a whole section, re-run the row's evidence grep once. If the evidence + no longer holds on the current branch (main moved), keep the section and note it as a Follow-up. +3. **Residual rule.** Read the whole page (or the item's line range) once. For a claim the table does not list that + looks doubtful, verify it against a primary source. If the code disagrees, change the page to match the code. Do not + chase claims that look right; the research passes verified the claims in each appendix's "Verified, keep" list. +4. **Dashes.** Remove every en and em dash in the item's range (dash rule). Do it in the same commit. +5. **Frontmatter.** Apply the item's title and description changes, if any. Confirm the description is 50 to 160 + characters and dash-free. Quote a `description` that contains `: ` (every new value below is already quoted). +6. **Links.** For each internal link, `ls .mdx`, and for an anchor `grep -n "^#.*"`, counting + `docs.json` redirects. Fix any that fail. +7. **MDX safety.** Keep any new `` placeholder inside backticks. Run `npm run lint:docs`. +8. **Commit** with `Item: `, its AC trailers and `PR-note: features/.mdx: `. Push. Run `pan task done`. + +## Work items + +Each page item applies the change table in the appendix it names. Items that edit the same file are chained: +WI-A1 → WI-A2 → WI-A3 (conversations) and WI-F1 → WI-F2 (workspaces). All other page items are independent and may run +in parallel. WI-Z1 runs last. + +### WI-A1: `features/conversations.mdx`, lines 1 to 555 (frontmatter through Scheduled runs) + +Range by heading (line numbers drift once an item lands): from the frontmatter to the line before `## Why hand off?`. + +Apply **Appendix A** (11 rows). The headline rows: +- Row 1 rewrites the hero alt text. The recaptured image shows the project home tab, not a conversation. +- Rows 2 and 3 replace "hot-swap the model" with the model lock (D9). +- Row 11 adds the **Machine** field of the New conversation dialog. +Frontmatter: keep (title "Conversations & Handoff", 151 chars). Remove dashes in lines 1 to 555 only. WI-A3 does the +page-wide check. + +### WI-A2: `features/conversations.mdx`, lines 556 to 959 (Why hand off? through Pull requests on conversations) + +Range by heading: from `## Why hand off?` to the line before `## Conversations from your other machines`. + +Apply **Appendix B** (28 rows plus blocks B5, B6, B13, B19, B24). The headline rows: +- Rows 6 to 14 bring the `pan handoff` docs in line with `src/cli/index.ts:378-397`: `--harness` and + `--author-harness` are ignored; `--title`, `--issue`, `--role` and `--allow-primary` are added; the `--cwd` rules and + examples are fixed. +- Rows 17 to 20 mark which fallback reasons apply only to source-authored handoffs, and add `handoff-request-failed`. +- Row 24 replaces the invented "4 of 6 uncommitted lines" note. +- Row 27 fixes the only relative `.mdx` link. + +Two planner rows, from FR-8 and D5: + +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| P1 | ` light="/images/handoff/continue-modal-light.png"` | DELETE the whole ``, plus one blank line next to it. | The image shows a **Harness** dropdown and the old "Claude Opus 4.8" model (planner opened `images/handoff/continue-modal-light.png`). `src/dashboard/frontend/src/components/shared/ModelPicker/ModelPicker.tsx:448` "the prop type for call-site compatibility but are ignored — no harness selector is" | +| P2 | ` light="/images/handoff/continue-modal-advanced-light.png"` | DELETE the whole `` stores `swarm.policy.mode=always` when the mode is Off. +- Row 6: the select option is "Inherit global". +- Row 2: nothing checks who passes `--steal`. +- Row 1: item worktrees belong to `pan spawn` workers only. +- Row 5 adds the swarm defaults. +Frontmatter: keep. The page already has a help section with both links. + +### WI-F1: `features/workspaces.mdx`, lines 1 to 340 (intro through Cleaning up after close-out) + +Range by heading: from the frontmatter to the line before `## Main Project Branch Convention`. + +Apply **Appendix F rows 1 to 20**, plus blocks 6, 7 and 20. These rows fix five things: +- the directory and branch names: `workspaces/feature-` on `feature/`; +- the `.planning/`, STATE.md and beads claims, which become `.pan/` and `.overdeck/`; +- Docker Compose naming: no `-p`; the compose file's `name:` decides it; +- the planning dialog's Docker checkbox, which defaults to off; +- `pan workspace destroy`: it discards uncommitted changes, and `--force` changes nothing (D4). + +Also apply the board screenshot alt text from Appendix F's "Screenshot alt text" as a row: + +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| P4 | `alt="Kanban board: issue columns with cost badges, agent status dots, and workspace controls, one card per issue/workspace"` | `alt="Board view: Backlog, Plan, Work, Review and Done columns of issue cards showing task progress, agent activity and actions such as Start work, under cycle and project filters and a Needs you strip"` | Planner-verified research: both `images/dashboard/board-*.png` show no per-card cost badges and no workspace controls (Appendix F, "Screenshot alt text") | + +The heading `### Planning Artifacts` becomes `### Planning artifacts` (block 7; same slug). + +### WI-F2: `features/workspaces.mdx`, lines 341 to the end, plus page-wide checks + +Range by heading: from `## Main Project Branch Convention` to the end of the page. + +Apply **Appendix F rows 21 to 35**, plus blocks 22 and 23. These rows fix: +- the role wording: there is no merge-agent; review and test agents remain; +- the planning safeguard: there is no "Planning agent is still running" message; the real refusals are listed; +- `### Specialist Agent Safeguards`, replaced by `### Agent safeguards` (block 23; no inbound links); +- the branch convention and Best Practices; +- the Fly section. + +Row 34 labels the Resources page experimental (FR-7). Row 35 adds the help sentence (FR-6). Then run the page-wide +checks. Frontmatter: keep. + +### WI-G1: `features/specialists.mdx` + +Apply **Appendix G, part `features/specialists.mdx`** (4 rows). They rewrite the description, the intro, the Test step and +the Merge step. The new text matches today's code: +- no test agent starts after approval (#5537, D4); the CI test job gates CI-mode projects; `pan review request` on an + approved PR with red checks starts a test agent; +- you click Merge only for issues held for UAT; +- the server merges a clean PR directly and rebases otherwise. +The new description in row 1 is 145 chars. Keep the title (it is specific). + +### WI-G2: `features/convoys.mdx` + +Apply **Appendix G, part `features/convoys.mdx`** (7 rows). The rows: +- Rows 1 and 2: "Roles panel" becomes Settings → Model Routing → Role Models. +- Row 3: the real synthesis report format, from `roles/review.md`, drops "Convoy Notes". +- Rows 4 and 5: the Pipeline page prose and alt text. It has no activity feed; its phases are Ship, Review, Work, + Plan and Ready. +- Row 6: label God View experimental (FR-7). +- Row 7: add `## Get help` before `## Related Guides` (FR-6). +Frontmatter: retitle to `title: "Review convoy: four parallel reviewers and a synthesis parent"` with +`sidebarTitle: "Review convoy"`. Change the description to `"How Overdeck's review convoy works: four parallel reviewers +for security, correctness, performance and requirements, and the synthesis parent."` (142 chars). + +### WI-G3: `features/cloister.mdx` + +Apply **Appendix G, part `features/cloister.mdx`** (2 rows). They narrow "Cloister does not choose models": a legacy +model-escalation trigger still exists. They also name Settings → Tiered Execution. Frontmatter: keep. + +### WI-G4: `features/merge-batches.mdx` + +Apply **Appendix G, part `features/merge-batches.mdx`** (10 rows). The headline rows: +- Row 3: with the switch off, held features wait, and GitLab and polyrepo projects never auto-merge. +- Row 7: a batch of one inside the batch window. The quoted "1 feature ready" line is removed; it is never rendered. +- Row 6: the button is **Open UAT**. +- Row 10: the UAT host format. +- Row 4: the Awaiting Merge page. +Row 1 replaces the description (132 chars). Frontmatter: retitle to +`title: "Merge train: batch CI and UAT batches for ready pull requests"` with `sidebarTitle: "UAT Batch Trains"`. +Remove all 12 dash lines. + +### WI-H1: `features/mission-control.mdx` + +Apply **Appendix H, part `features/mission-control.mdx`** (14 rows, plus blocks M2-TEXT and M9-TEXT). The headline rows: +- Rows M4, M7, M8 and M13 delete four sections that describe UI nothing renders: `## Activity View` (with + `### Section Isolation Mode` and its image), `## Badge Bar`, `## Status Reviews` and `### Model Selection`. The planner + re-ran the importer greps. +- Row M9 replaces `## Planning Artifacts` with `## Issue documents`. +- Row M2 rewrites `## Project Tree`. +- Rows M10 and M11 fix the Pipeline prose and alt text. +- Row M12: projects live in `projects.yaml`. +- Row M3 labels the Agents page experimental (FR-7). +Frontmatter: keep. + +### WI-H2: `features/keyboard-shortcuts.mdx` + +Apply **Appendix H, part `features/keyboard-shortcuts.mdx`** (3 rows, plus block K3-INSERT). The rows: +- K1: `G` then `A` leads to the experimental Agents page. +- K2: `Ctrl+W` in a Chrome tab closes the browser tab. +- K3: adds a `## Keys on single pages` section with the context keys the `?` sheet omits. +Leave the macOS `⌘W` and `⌘T` lines unchanged (D10). Frontmatter: retitle to +`title: "Dashboard keyboard shortcuts"` with `sidebarTitle: "Keyboard shortcuts"`. Keep the description (127 chars). + +### WI-H3: `features/file-explorer.mdx` + +Apply **Appendix H, part `features/file-explorer.mdx`** (2 rows): the tree keys (`F2`, `Delete`), and the 100 MB +upload limit with no-overwrite. Frontmatter: retitle to `title: "File explorer and code editor"` with +`sidebarTitle: "File explorer"`. Change the description to `"Browse, edit and ship changes to any project's files from +the dashboard, with edit workspaces, search, trash and pull requests."` (127 chars). + +### WI-H4: `features/open-in-overdeck.mdx` + +Apply **Appendix H, part `features/open-in-overdeck.mdx`** (2 rows): the root-folder message, and how Windows finds +`pan`. Frontmatter: keep. + +### WI-I1: `features/issue-pipeline.mdx` + +Apply **Appendix I, part `features/issue-pipeline.mdx`** (3 rows): +- `verification.tests` lives in `projects.yaml`. +- The test role drives the workspace's own app. +- Require UAT is a switch on the Flywheel page. +Frontmatter: keep. + +### WI-I2: `features/planning.mdx` + +Apply **Appendix I, part `features/planning.mdx`** (6 rows): +- The probe pass runs at `High` and above. +- A canonical spec has a root `status`. +- `narrative.Action` is required. +- The example is not finalize-ready. +- Nothing sets `completed` automatically. +- Only `pan scope cancel` sets `cancelled`. +Frontmatter: keep. + +### WI-I3: `features/flywheel.mdx` + +Apply **Appendix I, part `features/flywheel.mdx`** (10 rows). The headline rows: +- Row 3: a failed UAT blocks merge only while the issue is held. +- Row 10: the sequencer ranks only `PAN-` issues. +- Row 4: the per-project merge-train opt-out. +- Row 2: `.pan/parked.md`. +- Rows 7 and 8: the UI labels. +Frontmatter: keep. + +### WI-J1: `features/dashboard-views.mdx` + +Apply **Appendix J, part `features/dashboard-views.mdx`** (4 rows). The rows: +- Row 1: Analytics opens the experimental Metrics view (FR-7). +- Row 2: the Anywhere row's condition. +- Row 3: `pan context detach`. +- Row 4: Simple Home's empty sections. +Frontmatter: keep. + +### WI-J2: `features/costs.mdx` + +Apply **Appendix J, part `features/costs.mdx`** (5 rows): +- Grok reports its own cost, like Pi. +- Grok records `0` for an unpriced model. +- The branch pattern needs a hyphen. +- The week and month windows start at UTC day boundaries. +Frontmatter: keep. + +### WI-J3: `features/desktop-app.mdx` + +Apply **Appendix J, part `features/desktop-app.mdx`** (4 rows): +- `pan up` checks more Linux paths. +- The embedded server's port shifts after crashes. +- There are four reminder toasts. +- A canary version contains `-canary`. +Frontmatter: keep. + +### WI-Z1: validate the group and write the PR body + +Runs after every page item. + +1. Dash loop over the 20 pages prints nothing: + `for f in features/{issue-pipeline,planning,flywheel,conversations,file-explorer,mission-control,dashboard-views,costs,convoys,specialists,merge-batches,swarm,skills,skill-packs,workspaces,cloister,safe-shutdown,open-in-overdeck,desktop-app,keyboard-shortcuts}.mdx; do grep -HnP '[\x{2013}\x{2014}]' "$f"; done` +2. Frontmatter check: for each page, the `description` value is 50 to 160 characters and dash-free, and every retitled + page has a `sidebarTitle`. +3. `npm run lint:docs` exits 0. +4. Run `npx -y mint@4.3.49 validate` and `npx -y mint@4.3.49 broken-links --check-anchors` from the repo root. `mint` + is not a repo dependency, so `npx` downloads it. Both must report no error in a `features/` page. If one fails on a + page in this group, fix the page in this item's commit. If it fails on a page outside the group (for example the + known `guides/docker-setup.mdx` anchor), do not fix it: list it under Follow-ups and confirm the same failure exists + on `origin/main`. If `npx` cannot download the CLI (no network), record the exact error instead of a clean result. +5. Write the PR body draft into this item's commit message, above the trailer block (git trailers must stay the last + paragraph). An `--allow-empty` commit is fine when no page needed a fix. The draft has these sections: + - `## Summary`. + - `## Pages`: 20 ticked lines `- [x] features/.mdx: `, collected by + `git log origin/main..HEAD --format=%B | grep '^PR-note:'`. conversations and workspaces have one note per item; + join them on one line. + - `## Validation`: the output of steps 1, 3 and 4. + - `## Follow-ups`: the list below, plus anything found during the work. + + The PR does not exist yet. `pan done` opens it after every item is done (`src/cli/commands/done.ts`, + `openOrUpdatePullRequests`), with a body holding only the acceptance-criteria checklist. +6. **Post-step after `pan done`** (not an item): append the draft to the PR body. Run + `gh pr view --json body -q .body > /body.md`, add the draft from the validation commit message, then + run `gh pr edit --body-file /body.md`. The review role checks the PR body for the 20 page lines. + +### Documentation work item + +This issue is documentation. Every page item edits a Mintlify page under `features/`, and WI-Z1 records the result. No +other documentation changes: no `docs/*.md`, no `CLAUDE.md`, no rules. Inconsistencies found there are Follow-ups. + +## Follow-ups found during planning (list in the PR body, do not fix) + +- Test role never dispatched after review approval: nothing emits `review.approved` (#5537, open). The prompt text still + promises it in two places: `src/lib/cloister/review-agent.ts:171` and `roles/review.md:240`. When #5537 lands, the + specialists Test step needs revising. +- `pan workspace destroy --force` does nothing. Removal always passes `git worktree remove --force` and never checks for + uncommitted changes (`src/lib/worktree.ts:109`, `src/lib/workspace-manager/worktree-ops.ts:181`). `options.force` only + prints a tip (`src/cli/commands/workspace-list.ts:519-520`). +- `workspace-create.ts:146` builds container hints from `basename(projectConfig.path)-feature-`, which disagrees + with the declared-name logic in `src/lib/workspace/stack-health.ts`. +- The dashboard locks a conversation's model once it starts, but the server still accepts a live Pi model switch + (`src/lib/overdeck/conversation-runtime.ts:441`). The composer's model picker can never change the model of a + not-yet-started conversation either (`ComposerFooter.tsx:183,186`). +- External handoff authoring always runs under Claude Code, even for a GPT authoring model + (`src/lib/conversations/summary-fork.ts:197`). The dialog and server disagree on which sources can do Exact copy and + source authoring (`ForkModal.tsx:150,180` vs `conversation-forks.ts:773`, `transcript-adapter.ts:522`). +- Recapture the screenshots this PR removes or flags: `images/handoff/continue-modal-*.png`, + `continue-modal-advanced-*.png` and `continue-help-*.png` (the help panel leaves out Fresh start); + `images/dashboard/skills-*.png`; `images/dashboard/board-*.png` (light and dark show different states). The + conversations hero should show a conversation, not the project home tab. `images/dashboard/activity-*.png` is + orphaned after the mission-control deletion. +- Dead frontend code: `BadgeBar`, `TranscriptUpload`, the CommandDeck `ActivityView`, `AgentOutputPanel`, and + `TerminalPanel` apart from `popoutTerminal`, have no mounted importer. Neither do `IssueCockpitBody` and `IssueDigTabs`. + The routes `/api/command-deck/planning/:id/{status-review,upload,sync-discussions}` have no UI caller. +- `SINGLE_FEATURE_READY_LINE` (`src/dashboard/frontend/src/components/merge-train/mergeTrainCopy.ts:24`) is defined but + never rendered. +- Cloister's legacy escalation triggers (`src/lib/cloister/triggers.ts`) compare the agent's model with the bare names + `'haiku'` and `'sonnet'`. They are close to dead code. +- `sync-sources/skills/pan-code-review/SKILL.md:162,209` dispatches `code-review-correctness` and + `code-review-synthesis` subagents, which no longer ship. +- Keyboard shortcuts: + - Several context keys bypass the shortcut registry, so the `?` sheet never shows them. + - Board `Ctrl+Z` fires inside text fields too (`KanbanBoard.tsx:336`). + - The `⌘⇧O` label shows on Linux, and the voice tooltip says `Ctrl+Shift+M` on macOS. + - The palette's **View Agents** lands on Home with experimental features off. + - macOS `⌘W` and `⌘T` in a Chrome tab need a real-Mac check. +- The Experimental features switch description (`ExperimentalSection.tsx:78`) still names Activity and Skills, which are + not gated. The Pipeline `No PR` filter keeps issues with an open, not-ready PR. +- Nothing sets a spec's status to `completed` on merge. The Cancel action skips the spec transition because the + workspace is already gone (`src/lib/overdeck/issue-transitions.ts:182`). The comment at `merge-agent.ts:233` is stale. +- `src/lib/cloister/verification-runner.ts:702` tells agents to run `pan task close`, which does not exist. +- The backlog sequencer ranks only `PAN-` issues (`src/lib/backlog/sequencer-agent.ts:232`; PAN-1999 is meant to + generalize it). `RolesPanel.tsx:92` falls back to `maxAgents: 8`, while the config default is 30. +- The Overdeck desktop menu's **Open Workspace** submenu shows only a disabled "Loading..." row; `buildWorkspaceSubmenu` + is never called (`apps/desktop/src/menu.ts:68,188`). +- `pan conv embed` checks neither `conversations.embeddings` nor the Background AI `sessionEmbeddings` switch. +- `pan swarm ` may judge eligibility without the continue-file item statuses (unverified; `deacon-swarm.ts:308` + applies them). +- `guides/docker-setup.mdx` has a broken anchor `/reference/troubleshooting#slow-vitereact-frontend-with-multiple-workspaces` + (outside this group; #5504). + +## Acceptance criteria (map 1:1 to work items) + +Every page item meets four criteria: +- its change-table rows are applied, spot-checked by grepping removed anchors and added phrases; +- the dash grep over its range prints nothing; +- the frontmatter passes; +- its commit carries a `PR-note:` line. + +The xBRIEF has the specific checks for each item. WI-Z1: lint and both Mintlify commands pass for `features/` pages, and +the PR body has 20 ticked page lines. + +## Non-goals + +- No code, test, rule, `docs.json`, `CLAUDE.md`, `README.md` or `changelog.d` change. Code bugs become Follow-ups. +- No page outside the Features group. +- No new pages, no navigation changes, no file renames or slug changes. +- No heading renames or deletions except those listed in NFR-2. +- No screenshots added, replaced or recaptured, and no image files deleted. Only alt text changes and the `` + removals in FR-8. +- No help section added to pages that have no troubleshooting section. + +## Planning Q&A + +Planning ran in `--auto` mode, so no questions went to the operator. These defaults were chosen instead and are recorded in +the xBRIEF's `autoDecisions`: + +- **Scope**: 20 nav pages instead of the 14 listed (D1). +- **Prerequisite PRs**: all merged; audit on top of them (D2). +- **Help links**: only on pages with troubleshooting sections (D3). +- **Stale screenshots**: rewrite wrong alt text, remove images of removed UI, recapture as a Follow-up (D5). +- **Retitles**: generic titles get specific ones with a `sidebarTitle` that keeps the short nav label (D8). +- **Plan size**: one item per page, three section items for conversations, two for workspaces, and one validation item. + The plan sets `sizeJustification` because the finalize lint counts each page as its own subsystem, while the work is + one docs directory. + +## How to read the appendices + +Each appendix is a research pass's output, as the planner verified it. The planner kept the passes' row numbers. +- **Change table**: the rows to apply. +- **Verified, keep**: claims already checked, which need no re-research. +- **Follow-ups / Unsure**: notes for the PR body; they are not rows. +- **Replacement blocks**: exact multi-line text for rows that point to them. + +A "Before:" line in a section appendix gives +whole-page or range figures; the before-state table above is authoritative. + +## Appendix A: conversations.mdx lines 1 to 555 (WI-A1) + +Research pass output, base `2007e9a4d3c`, rows verified by the planner (anchor unique, evidence greps). + +### features/conversations.mdx (lines 1-555) + +Before: 1346 lines (whole page), 24 dash lines in lines 1-555 (66 in the whole page), title "Conversations & Handoff", description 151 chars. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| 1 | `alt="Command Deck with a live conversation: the project's conversations and issues, and the agent's turn-by-turn tool calls"` | `alt="Command Deck on a project's home tab: the conversation list in the left column, and the project's agents, Needs you queue and pipeline in the main pane"` | Both `images/dashboard/command-deck-hero-light.png` and `-dark.png` (viewed) show the **Project home** tab: tiles "Agents working / Needs you / In review / Landed this week / Spend this week", a "Needs you" list, a "Pipeline · 3 issues" table, the Auto-merge card. No transcript or tool calls. | +| 2 | `\| **Model picker** \|` (row: `... Hot-swap the model for the next message — Sonnet → Opus → Kimi/GPT/Gemini — without losing the conversation \|`) | Replace the row with: `\| **Model picker** \| Shows the conversation's model. In the dashboard, the model is fixed once a conversation starts; click the button to see why, and hand off to a new conversation to use another model \|` | `src/dashboard/frontend/src/components/chat/ComposerToolbar.tsx:20` "The model is fixed once a conversation starts. To use another model, hand off to a new conversation (⋯ → Hand off)."; `ComposerToolbar.tsx:98` "lockedReason={canEditModelBeforeStart ? undefined : agentId ? AGENT_MODEL_LOCKED : CONVERSATION_MODEL_LOCKED}" | +| 3 | `The model picker spans the harness (Claude Code, Pi, Codex) and every routed` | Replace lines 191-193 (this line through `click:`) with: `The model and harness picker spans the harness (Claude Code, Pi, Codex) and every routed provider, each with live per-million pricing. It picks the model for a new conversation (on the Home composer and in the **New conversation** caret menu); once a conversation starts, the dashboard keeps its model fixed:` | `ComposerToolbar.tsx:20` "The model is fixed once a conversation starts."; `src/dashboard/frontend/src/components/home/HomeComposer.tsx:17` "import { ModelPicker, MODEL_EFFORT_SUPPORT, type Harness } from '../chat/ModelPicker';"; `src/dashboard/frontend/src/components/frame/NewConversationButton.tsx:6` "the model, harness and effort pickers, the Retrospective button and" | +| 4 | `\| **Reasoning effort** \|` (row: `... Tune how hard the model thinks per message (e.g. *Extra High*) \|`) | Replace the row with: ``\| **Reasoning effort** \| The `Thinking: ` button changes how hard the model thinks while the session runs (e.g. *Extra High*); see [Changing effort while a conversation runs](#changing-effort-while-a-conversation-runs) \|`` | `src/dashboard/frontend/src/components/chat/EffortPicker.tsx:93` "`Thinking: ${SHORT_LABELS[chip ? chip.level : selected.id].toLowerCase()}`"; `src/lib/agents/effort-live.ts:6` "`/effort ` through the terminal backend and reports success only" | +| 5 | `\| **Conversation / Terminal toggle** \|` | Replace the row with: `\| **Conversation / Terminal toggle** \| Switch between the rendered conversation and the raw terminal of the same session (the native CLI for OpenCode and Codex). Shown only while the session is live \|` | `src/dashboard/frontend/src/components/chat/header/ConversationHeader.tsx:209` "View toggle — only when session is live" | +| 6 | `- **⋯** opens the conversation menu. A right-click on the header opens it too.` | Keep the line and add a new bullet after it: `- A Pi conversation that is working also shows **Stop**, which stops the current turn.` | `ConversationHeader.tsx:151` "const showPiAbort = isWorking && (conversation.harness === 'ohmypi' \|\| conversation.harness === 'pi');"; same file "title=\"Stop current turn\"" | +| 7 | `committed**, and the cost. A count of zero is left out. In a Command Deck tab` | `committed**, and the cost. The commit and file counts show only in a Command Deck tab, and a count of zero is left out. In a Command Deck tab` | `src/dashboard/frontend/src/components/chat/header/ConversationStatusLine.tsx:51` "if (totals && openDock) {"; `src/dashboard/frontend/src/components/chat/header/headerChanges.tsx:3` "Change data appears only inside a Stage: outside one there is no dock to" | +| 8 | `4. **Hand off to new conversation**, **Create summary fork**, **Export` | `4. **Hand off to new conversation**, **Create summary fork** (not for Pi), **Add skills…** (Claude Code and Codex), **Export` | `src/dashboard/frontend/src/components/chat/header/ConversationHeaderMenu.tsx:280` "conversation.claudeSessionId && conversation.harness !== 'pi'"; same file :293 "Add skills…"; `packages/contracts/src/harness-capabilities.ts:130` "conversationSkillApply: \"hot-reload\"," and :197 "conversationSkillApply: \"restart\"," (every other harness is `null`) | +| 9 | `` and `K` step through the turn's files, and **Back** shows the This`` | `` and `K` step through the turn's files, and the back arrow (**Back to the list**) shows the This`` | `src/dashboard/frontend/src/components/dock/changes/DockDiffView.tsx:180` "title=\"Back to the list\" aria-label=\"Back to the list\"" (icon-only ArrowLeft button) | +| 10 | `there, so **Show in files** and the row's beside and reveal actions are not` | Replace this line and the next line (`shown.`) with: `there, so **Show in files** is not shown, and the row's beside and reveal actions are greyed out.` | `src/dashboard/frontend/src/components/chat/messagesTimeline/TurnChangesCard.tsx:63` "{stage && (" (gates only Show in files); `src/dashboard/frontend/src/components/dock/changes/ChangeFileRow.tsx:61` "" | +| 11 | `- **Model** and **Harness.**` | Replace with two bullets: `- **Machine.** This machine (the default), **Auto**, a linked machine, or **Fly (new VM)**, which needs a project. On another machine, that machine picks the working directory from its copy of the project.` then `- **Model** and **Harness.**` | `src/dashboard/frontend/src/components/newConversation/MachineField.tsx:68` ""; same file :70 "'Fly (new VM) needs a project'"; same file "its copy of ${projectName}"; `src/dashboard/frontend/src/components/newConversation/NewConversationDialog.tsx:220` "" | + +#### Verified, keep +- **⋯ menu copy and open items.** Copy conversation id; Copy session id (only when it differs from the name); Copy link; Open in new window; Full diff in a new window (hidden for linked and vault). + - `ConversationHeaderMenu.tsx:227` "sessionId && sessionId !== conversation.name" + - `src/dashboard/frontend/src/components/chat/diffWindow.ts:19` "conversation.origin !== 'linked' && conversation.origin !== 'vault'" +- **⋯ menu groups 1-6 and their order.** Delivery method is under Advanced and shows for Claude Code only. + - `ConversationHeaderMenu.tsx:328` "conversation.harness === 'claude-code' && (<>" +- **A right-click on the header opens the menu.** + - `ConversationHeader.tsx:289` "Right-click the header → open the ⋯ menu." +- **Side-panel shortcuts.** Ctrl/⌘ Shift G toggles Changes; Ctrl/⌘ Shift E toggles Files. + - `src/dashboard/frontend/src/components/explorer/search/useExplorerShortcuts.ts:35` "label: 'Show or hide Changes'" + - same file :34 "label: 'Show or hide Files'" +- **Ctrl/⌘ Shift O opens the folder in your favorite editor.** + - `src/dashboard/frontend/src/lib/keybindings.ts:8` "export const EDITOR_OPEN_FAVORITE_KEY = 'mod+shift+o';" +- **Status line.** Order and labels match, the home directory shortens to `~`, and a detached checkout reads "detached". + - `ConversationStatusLine.tsx:43` "state · machine · folder · branch (+PR) · commits pushed · commits" + - `src/dashboard/frontend/src/components/chat/ConversationBranchMeta.tsx:28` "detached ? 'detached' : conversation.branch" +- **With no upstream, a commit counts as pushed when any remote branch has it.** + - `src/lib/overdeck/conversation-change-commits.ts:104` "['rev-list', 'HEAD', '--not', '--remotes']" +- **The Subagents rail starts collapsed and the browser remembers your choice.** + - `src/dashboard/frontend/src/components/chat/SubagentRail.tsx:66` "localStorage.getItem(AGENTS_RAIL_COLLAPSED_KEY) !== 'false'" +- **Turn card.** The first 8 rows show; "Show all N files"; the amber "N not committed" tag; Review; Show in files; hover labels; J/K step through files. + - `TurnChangesCard.tsx:16` "const VISIBLE_ROWS = 8;" + - `ChangeFileRow.tsx:64` "label=\"Reveal in files\"" + - `DockDiffView.tsx:80` "label: 'Next changed file'" + - `src/dashboard/frontend/src/components/explorer/ExplorerPane.tsx:158` "Only what this conversation changed" +- **File-path chip menu.** Open diff, Open beside, Reveal in files. + - `src/dashboard/frontend/src/components/chat/MarkdownFileLink.tsx:352` "label: 'Open diff'" +- **Send menu.** Reads `Send: `, with four modes; it shows for Claude Code and Pi. + - `src/dashboard/frontend/src/components/chat/SendModeMenu.tsx:93` "Send: {selected.label}" + - `src/dashboard/frontend/src/components/chat/ComposerFooter.tsx:182` "steerKind === 'send-now-keys' || (steerKind === 'control-channel' && !agentId)" +- **Cancel messages.** + - `src/dashboard/frontend/src/components/chat/messagesTimeline/messageRows.tsx:168` "Already delivered, can't cancel" +- **Live effort change.** Refused mid-turn; the source labels are `set`, `default` and `terminal`. + - `src/lib/agents/effort-live.ts:156` "The session is mid-turn. Change effort when it is idle." + - `src/dashboard/frontend/src/components/chat/effortChip.ts:20` "explicit: 'set'," +- **New conversation dialog fields.** Effort `Default:` hint, No context, Skip CLAUDE.md, Linked issue, First message. + - `NewConversationDialog.tsx:278` "Not supported by this model" +- **Split button.** `N` shortcut outside text fields; "New conversation with options…" is also in the command palette. + - `NewConversationButton.tsx:55` "keys: { mac: 'N', other: 'N' }, scope: 'not-editing'" + - `src/dashboard/frontend/src/components/CommandPalette.tsx:475` +- **`pan skills add --pack ` with `--restart`, and the `add_skills` MCP tool.** + - `src/cli/commands/skills.ts:743` "skills.command('add ')" + - `src/lib/mcp/tools-write.ts:220` "name: 'add_skills'," +- **Home composer.** "Talk it through first:" is Simple mode only; with no project it starts in `~/Projects`, otherwise your home directory. + - `src/dashboard/frontend/src/components/home/homeComposerIntents.ts:43` "if (mode === 'simple') {" + - `src/lib/default-cwd.ts:17` "const candidate = join(homedir(), 'Projects');" +- **No-project UI.** "Start without a project", "Not in a project · Move to project…", and the row menu's Move. + - `src/dashboard/frontend/src/components/CommandDeck/DeckEmptyState.tsx:22` + - `UnscopedConversationChip.tsx:66` + - `ConversationActionMenu.tsx:191` +- **Native CLI panes and messages.** + - `src/dashboard/frontend/src/components/chat/ConversationTerminalView.tsx:195-198` + - `src/lib/codex/app-server-manager.ts:33` "MINIMUM_NATIVE_ENDPOINT_CODEX_VERSION = '0.153.4'" + - `src/lib/config-yaml/schema.ts:687` "transport?: 'app-server' | 'tui';" +- **Attachments.** Extension list, the `@` reference, 5 MB per file, 50,000 characters per message. + - `src/lib/overdeck/conversation-message.ts:100` "export const ALLOWED_ATTACHMENT_EXTENSIONS = [" + - `ComposerFooter.tsx:505` "`@${attachment.serverPath}`" + - `conversation-message.ts:61` "export const MAX_UPLOAD_BYTES = 5 * 1024 * 1024;" + - `conversation-message.ts:62` "const MAX_MESSAGE_LENGTH = 50_000;" +- **Vision gating.** Images are dropped with a toast; Sonnet 5.5 has vision. + - `ComposerFooter.tsx:211` "Switch to a vision-capable model to send images." + - `src/dashboard/frontend/src/components/Settings/modelCatalog.ts:60` "'claude-sonnet-5-5'" +- **The image lightbox closes on Escape.** + - `src/dashboard/frontend/src/components/chat/ImageLightbox.tsx:39` +- **Citations.** Block format; slash commands leave citations pending; pending citations live in localStorage; the markdown-file toast. + - `src/dashboard/frontend/src/lib/citationFormat.ts:16` "Notes on your previous reply:" + - `ComposerFooter.tsx:500` "slash text (commands) never carries citations" + - `src/dashboard/frontend/src/lib/composerCitations.ts:93` + - `src/dashboard/frontend/src/components/Stage/panes/EditorPane.tsx:263` "Citation added" +- **Bookmarks.** Stored by the server; a message missing from the transcript shows a note. + - `src/dashboard/frontend/src/components/chat/bookmarks/BookmarksDrawer.tsx:99` + - `src/dashboard/server/routes/conversation-bookmarks.ts` +- **`pan conv schedule` verbs and every flag on the page.** + - `src/cli/commands/conversations/index.ts:182` "schedule.command('add ')" + - `.alias('conv')` at :37 +- **`self` aliases.** + - `src/cli/commands/conversations/schedule.ts:53` "new Set(['self', '.', 'current', 'me'])" +- **Schedule rules.** 5-field cron only; runs at least 15 minutes apart. + - `src/lib/overdeck/conversation-schedule-recurrence.ts:32` + - same file :46 "Schedules must be at least 15 minutes apart" +- **Schedule sweep.** Runs every 60 s; the delivered prompt starts with the header. + - `src/dashboard/server/services/conversation-schedule-service.ts:114` "`[Scheduled run · schedule ${schedule.id} · ${schedule.cron} · ${schedule.timeZone}]" +- **Schedule limits.** Agent conversations and vault copies are refused; at most 20 per conversation. + - `src/lib/overdeck/conversation-schedules.ts:197` + - same file :16 "MAX_SCHEDULES_PER_CONVERSATION = 20" +- **Schedule MCP tools.** + - `src/lib/mcp/tools-schedule.ts:52` "name: 'schedule_recurring'," +- **Schedule… dialog and the next-run badge.** + - `src/dashboard/frontend/src/components/chat/ConversationScheduleDialog.tsx:69` "label: 'Custom cron'" + - `ConversationRow.tsx:388` + +#### Labels needed (experimental / early / testing) +- None. Nothing in lines 1-555 describes an `EXPERIMENTAL_TAB_IDS` view or another flagged feature. + +#### Links +- All 7 internal links resolve: + - `/configuration/harnesses#steering-a-running-turn` + - `/features/skill-packs#for-one-conversation` + - `/features/skills` + - `/features/file-explorer` + - `/configuration/mcp` + - `#reviewing-changes-in-the-diff-window`, used twice (heading at line 1021) +- The anchor that row 4 adds, `#changing-effort-while-a-conversation-runs`, matches the heading at line 178. +- The GitHub link to `docs/CONTEXT-LAYERS.md#bare-conversations-no-overdeck-context` matches that file's line 137. + +#### Frontmatter +- title: keep +- description: keep (151 chars, no dashes) + +#### Help section +- No troubleshooting or getting-help section in lines 1-555. + +#### Screenshot alt text +- Lines 15-19: the current alt text does not match. Both PNGs (2880x1800) show the Project home tab, not a conversation. + - **Left column:** the project switcher; Project home, Flywheel, Order books and More; the New conversation split button reading "Fable 5 · High"; the CONVERSATIONS list. + - **Main pane:** the project header with CI and deploy status; the action buttons; the stat tiles; Needs you; the Pipeline table; the Auto-merge card. + - Light and dark differ only in live counts. +- Proposed alt text: see row 1. + +#### Follow-ups (never fixed by this issue) +- **The hero image doesn't show what the page is about.** This page needs a capture of a conversation (transcript, composer, header). The current image fits a Command Deck or project-home page better. +- **The model picker may be dead code.** `ComposerFooter.tsx:186` sets `canEditModelBeforeStart` only when the session is not alive, but `:183` sets `isDisabled = !conversation.sessionAlive || sending`. So the picker in a conversation that hasn't started can never change the model. +- **The turn card's beside and reveal buttons may be meant to be hidden.** Outside a Stage, `ChangeFileRow` still renders them, greyed out. If hiding was intended, that's a code fix. Row 10 documents today's behavior. + +## Appendix B: conversations.mdx lines 556 to 959 (WI-A2) + +Research pass output, base `2007e9a4d3c`, rows verified by the planner (anchor unique, evidence greps). + +### features/conversations.mdx (lines 556-959) + +Before: 1346 lines (whole page), 66 dash lines on the whole page, 29 of them inside lines 556-959; title "Conversations & Handoff", description 155 chars (frontmatter is audited by another agent; not re-checked here). + +Notes for the executor: +- Anchors are cell or sentence text, never whole table rows. Where a row says "see block Bn", the exact replacement text is in the fenced block of that name below the table. +- One row per physical line. No heading is renamed or deleted, so inbound anchors stay valid (`#why-hand-off`, `#handing-off-from-the-cli`, `#linking-a-pull-request-by-hand`). +- Replacement text uses no en/em dashes. Angle-bracket placeholders inside table cells are in backticks (MDX). + +#### Change table +| # | Grep anchor (EXACT current text, copy-paste, must match the page exactly once; keep it short, one line, no line breaks) | Change (exact replacement text, or "DELETE section `## Heading` (lines x-y)", or "DELETE sentence") | Evidence (`path/file.ts:LINE` + a short exact quote that greps in that file; for an absence, the grep command run and "no match") | +|---|---|---|---| +| 1 | `Open the **Continue** dialog from a conversation's action menu, or type` | `Open the dialog (titled **Continue in a new conversation**) from a conversation's menu: **Hand off to new conversation** opens it on Agent handoff, **Create summary fork** on Fresh summary. Or type` | `src/dashboard/frontend/src/components/CommandDeck/ConversationActionMenu.tsx:280` "Hand off to new conversation"; `:288` "Create summary fork"; `src/dashboard/frontend/src/components/CommandDeck/ForkModal.tsx:248` "title=\"Continue in a new conversation\"" (same items in `ConversationRow.tsx:873,881` and `chat/header/ConversationHeaderMenu.tsx:277,285`; no menu item is named "Continue") | +| 2 | `Copies the raw conversation history verbatim — no summary generated.` | `Copies the raw conversation history from the last compaction point, with no summary. Only a Claude Code conversation can be copied, and the copy launches under Claude Code.` | `src/lib/overdeck/conversation-forks.ts:775` "only Claude Code can be the source of a plain fork"; `src/dashboard/frontend/src/components/CommandDeck/ForkModal.tsx:602` "last compaction point and resumes under Claude Code" | +| 3 | `Pick the authoring model and harness here.` | `Pick the authoring model here; the dialog has no harness picker.` | `src/dashboard/frontend/src/components/shared/ModelPicker/ModelPicker.tsx:448` "no harness selector is" | +| 4 | `**Source session**` | Replace with `**Source agent**`, and append to the end of that row's Behavior cell: ` Offered only for a Claude Code source, and Continue stays disabled until the source conversation is running.` | `ForkModal.tsx:565` "Source agent (uses source's model"; `:180` "const sourceSupportsSourceAuthoring = (conversation.harness ?? 'claude-code') === 'claude-code';"; `:267` "'Source-authored handoff requires a running source conversation'" | +| 5 | `If a source-authored handoff stalls or produces an invalid document, Overdeck` | Replace this line and the next line (`falls back to a summary fork automatically.`) with block B5 | `src/lib/overdeck/conversation-forks.ts:459` "forkFallbackReason = handoffFailureReason(error);" (external-author branch; `:477` for source); `:458` "if (error instanceof HandoffAuthorModelNotConfiguredError) throw error;" | +| 6 | `The dialog is the visual front-end for `pan handoff`. The CLI does exactly what` | Replace this line and the next line (`the dialog does, and the two are interchangeable.`) with block B6 | `src/cli/index.ts:367` ".command('fork [conv]')"; `src/cli/index.ts:374` ".option('--plain', 'Skip summary generation and copy raw conversation history')"; `src/cli/commands/handoff.ts:209` "forkMode: 'handoff'," | +| 7 | `pan handoff source-conv --harness pi` | DELETE this line (inside the bash code block) | `src/cli/index.ts:382` "'Ignored: harness is provider-default-only (PAN-1984)'" | +| 8 | `pan handoff source-conv --cwd /path/to/project` | `pan handoff source-conv --cwd ~/Projects/myapp/workspaces/feature-myapp-42` | `src/lib/overdeck/conversation-forks.ts:795` "; use a worktree" (a project's primary checkout is refused without `--allow-primary`) | +| 9 | `pan handoff source-conv --cwd ../isolated-worktree --project mind-your-now` | `pan handoff source-conv --cwd ~/worktrees/isolated --project mind-your-now` | `src/lib/overdeck/cwd-containment.ts:15` "if (!cwd.startsWith('/')) return false;"; `:17` "if (segments.includes('..')) return false;"; CLI sends it unresolved: `src/cli/commands/fork-client.ts:138` "if (opts.cwd) body['cwd'] = opts.cwd;" | +| 10 | `Harness for the new conversation: `claude-code` or `pi`.` | `Accepted and ignored with a printed notice: the new conversation's harness follows its model's provider.` | `src/cli/index.ts:382` "'Ignored: harness is provider-default-only (PAN-1984)'"; `src/cli/commands/handoff.ts:41` "is provider-default-only (PAN-1984); ignoring" | +| 11 | `Harness for the external authoring session: `claude-code` or `pi` (external only).` | `Accepted and ignored with a printed notice; there is no authoring harness choice.` | `src/cli/index.ts:391` "'Ignored: author harness is provider-default-only (PAN-1984)'" | +| 12 | `Working directory for the new conversation. |` | `An absolute path to an existing directory under your home directory and, except with `--fresh`, inside a git working tree. A project's primary checkout is refused: use a worktree, or pass `--allow-primary`. |` | `src/lib/overdeck/cwd-containment.ts:23` "return resolved.startsWith(`${home}/`) \|\| resolved === home;"; `src/lib/overdeck/conversation-forks.ts:814` "Handoff cwd is not inside a git repository"; `:795` "; use a worktree" | +| 13 | `even when `--cwd` points outside that project's directory. |` | Keep the line; insert the four rows of block B13 directly after it | `src/cli/index.ts:384` "Operator only: allow --cwd to be a project"; `:386` "'Issue ID to associate with the new conversation; without --cwd the new conversation starts in the issue workspace when it exists'"; `:387` "With --issue, review makes the handoff the issue"; `:388` "defaults to \"Handoff: \" (first ~70 chars)" | +| 14 | `The focus becomes its first message. Project, cwd, model and effort still default from the source. |` | `The focus becomes its first message. Project, cwd, model and effort still default from the source. Cannot be combined with `--author source` or `--author-model`; with `--hold` it needs focus text. |` | `src/cli/commands/handoff.ts:163` "'--fresh authors no handoff document; drop --author/--author-model'"; `:167` "'fresh with hold needs focus text: there is nothing to hold'" | +| 15 | `A longer focus is rejected with` | Replace this line and the next line (`` `focus must be 10000 characters or fewer` and no ``) with: `` `pan handoff` refuses a longer focus before anything is created; the dashboard API refuses it with `focus must be 10000 characters or fewer`. No `` (the following line `conversation is created. Keep it short...` stays and completes the sentence) | `src/cli/commands/handoff.ts:136` "No conversation was created."; `src/lib/overdeck/conversation-forks.ts:93` "error: 'focus must be 10000 characters or fewer'" | +| 16 | `live-agent handoff can't complete` | `handoff can't be authored` | `src/lib/overdeck/conversation-forks.ts:459` "forkFallbackReason = handoffFailureReason(error);" (external authoring falls back too) | +| 17 | `The source conversation is already ended. |` | `The source conversation is already ended (source-authored handoffs only). |` | `src/lib/conversations/summary-fork.ts:349` "if (sourceConv.status === 'ended') return 'source-ended';"; only called in the source branch: `src/lib/overdeck/conversation-forks.ts:465` "const preconditionFallback = await handoffPreconditionFallbackReason(parentConv);" | +| 18 | `The source didn't write both the document and its `.done` sentinel in time. |` | `A source-authored handoff: the source didn't write both the document and its `.done` sentinel within 5 minutes. |` | `src/lib/conversations/summary-fork.ts:43` "const DEFAULT_HANDOFF_TIMEOUT_MS = 300_000;"; `:131` "throw new HandoffStallError(paths.docPath, paths.sentinelPath, timeoutMs);" (only in waitForHandoffDoc, used by the source path at `:317`) | +| 19 | `The document didn't satisfy the handoff contract. |` | `The document didn't satisfy the handoff contract, or the external authoring session never wrote it. |` then insert block B19 as a new table row on the next line | `src/lib/conversations/summary-fork.ts:276` "throw new HandoffValidationError(paths.docPath, 'authoring session did not call its Write tool to create the handoff doc');"; `:369` "return 'handoff-request-failed';" | +| 20 | `The source can't write to the host handoff directory from inside a workspace container. |` | `The source can't write to the host handoff directory from inside a workspace container (source-authored handoffs only). |` | `src/lib/conversations/summary-fork.ts:363` "return health.healthy ? 'source-workspace-devcontainer' : null;" (same source-only call site as row 17) | +| 21 | `A successful handoff prints the new conversation id, tmux session, model,` | `A successful handoff prints the new conversation id, terminal session, model, effort,` | `src/cli/commands/handoff.ts:248` "Effort: ${newConv.effort \|\| 'default'}"; `:246` "Session: ${newConv.tmuxSession}" | +| 22 | `harness, dashboard link, and the handoff document path. Fallbacks print the same` | `harness, project (when set), issue, handoff document path and dashboard link. Fallbacks print the same` | `src/cli/commands/handoff.ts:250` "if (newConv.projectKey) console.log(chalk.gray(` Project: ${newConv.projectKey}`));"; `:251` "Issue: ${newConv.issueId ?? 'none'}" | +| 23 | `Overdeck can list the commits and uncommitted edits each conversation made.` | `The work dock's **Changes** tab lists the commits and uncommitted edits each conversation made.` | `src/dashboard/frontend/src/components/dock/WorkDock.tsx:227` "label: 'Changes',"; `:267` "else if (tab === 'changes') body = " | +| 24 | `counts, for example "4 of 6 uncommitted lines in this file are from this` | Replace the whole paragraph (lines 792-796, `Uncommitted edits are best effort.` through `Edits made only through shell commands are not shown.`) with block B24 | `git grep -n "uncommitted lines in this file" -- src` : no match. Real notes: `src/dashboard/frontend/src/components/dock/changes/ConversationChangesList.tsx:41` "other uncommitted lines come from"; `:37` "Line attribution needs edit records, which only Claude Code writes." | +| 25 | `than its 100 most recent PRs, in another repository, or on a conversation` | `than the 100 most recent open and 100 most recent closed PRs it lists, in another repository, or on a conversation` | `src/lib/overdeck/pr-listing.ts:175` "const OPEN_READ_FULL_LIMIT = 100;"; `:235` "'pr', 'list', '--state', 'closed', '--limit', '100'" | +| 26 | `They exit 2 when no conversation matches, and 1 on any` | `They exit 2 when no conversation matches or the match is ambiguous, and 1 on any` | `src/cli/commands/conversations/pull-requests.ts:71` "Ambiguous match for" (then `return exitCli(2);` at `:74`) | +| 27 | `[`configuration/mcp.mdx`](../configuration/mcp.mdx)` | `[MCP server: Pull requests](/configuration/mcp#pull-requests).` | `configuration/mcp.mdx:185` "### Pull requests" (only `](../` link in any .mdx: `git grep -c "](\.\./" -- '*.mdx'` lists only this page) | +| 28 | `("Pull requests").` | DELETE this line (row 27's link now names the section and ends the sentence) | same as row 27 | + +Block B5: +If authoring fails (the document never arrives or fails validation, or the +authoring request errors), Overdeck falls back to a summary fork automatically, +whoever authors it. A missing authoring model is the exception: that handoff fails. + +Block B6: +`pan handoff` is the CLI form of the dialog's **Agent handoff**, including Fresh +start and Hold. Fresh summary is `pan fork `, and Exact copy is +`pan fork --plain`. + +Block B13 (four new table rows after the `--project` row): +| `--allow-primary` | Operator only: allow `--cwd` to be a project's primary checkout. Refused for agent sessions. | +| `--issue ` | Issue ID to associate with the new conversation. Without `--cwd`, the new conversation starts in the issue's workspace when one exists. | +| `--role ` | Pane role for the new conversation: `conversation` (default), `work`, `review`, `test` or `plan`. With `--issue`, `review` makes the handoff the issue's Review row. | +| `--title ` | Title for the new conversation. Defaults to `Handoff: <focus>` (the first ~70 characters of the focus), or `Handoff: <source title>` without focus. | + +Block B19 (new table row after the `handoff-validation` row): +| `handoff-request-failed` | Any other authoring failure, for example the external authoring session erroring or timing out. | + +Block B24 (replaces lines 792-796): +Uncommitted edits are best effort. Claude Code conversations get per-line +attribution: when other sessions also changed a file, its row says how many of +its uncommitted lines came from elsewhere and names the conversations that wrote +them when those conversations were opened recently. Conversations on other +harnesses list the file only, with a note that line attribution needs edit +records, which only Claude Code writes. Edits made only through shell commands +are not shown. + +#### Verified, keep +- Intents Fresh summary (recommended), Agent handoff, Exact copy — `ForkModal.tsx:239` "label: 'Fresh summary'"; `:335` "· recommended" +- `/handoff [focus]` (also `/pan-handoff`, `/pan handoff`) opens the dialog in handoff mode — `src/dashboard/frontend/src/components/chat/ComposerFooter.tsx:443` "const handoffMatch = messageText.match(" +- Project picker defaults to Same as source — `ForkModal.tsx:371` "Same as source ({sourceProjectLabel})" +- Fast summary toggle; heuristic of user messages/files/tools — `ForkModal.tsx:501` "Fast summary (no LLM, heuristic only)"; `src/lib/conversations/summary-fork.ts:438` "const toolsUsed = new Set<string>();" +- Launch model defaults to parent's — `ForkModal.tsx:160` "useState(conversation.model || defaultModel)" +- External session is the default author — `ForkModal.tsx:173` "useState<HandoffAuthor>('external')" +- Fresh start checkbox beside Hold; Focus relabels "First message (optional)"; Authored-by hidden; no parent link — `ForkModal.tsx:467`, `:410`, `:541`; `conversation-forks.ts:881` "...(fresh ? {} : { parentName: conv.name })," +- Help panel "Continue Options" — `ForkModal.tsx:83` "title=\"Continue Options\"" +- `pan handoff [conv] [focus...]`, self refs — `src/cli/index.ts:378`; `handoff.ts:30` "const SELF_REFS = new Set(['self', '.', 'current', 'me']);" +- Bare first word read as conv ref, CLI suggests `self` — `handoff.ts:112` "If that was focus text for the current conversation, pass `self` before it:" +- `pan conv current` alias `whoami` — `src/cli/commands/conversations/index.ts:208-209` +- `--model`, `--effort` (clamped), `--project`, `--author` (default external), `--author-model`, `--skill`/`--pack`/`--group`, `--hold`, `--fresh` — `src/cli/index.ts:379-397`; `src/lib/overdeck/conversation-effort.ts:36` "are clamped to the model and" +- No built-in author model; missing config fails — `summary-fork.ts:196` "if (!effectiveModel) throw new HandoffAuthorModelNotConfiguredError();"; `src/lib/config-yaml/defaults.ts:94` "PAN-3860: deliberately no default here" +- `--skill`/`--pack` apply only on Claude Code and Codex — `src/lib/skill-overrides/launch.ts:186` "harness: 'claude-code' | 'codex'," +- `--group` skips not-added/not-cached packs — `handoff.ts:68` "not added (pan skills pack add --group ${group})" +- Focus cap 10,000 — `handoff.ts:134` "const FOCUS_MAX_CHARS = 10_000;" +- `pan handoff start <conv>` (id or name), once; 409 "No held kickoff..." exits 1 — `handoff.ts:88` "if (convRef === 'start') {"; `src/cli/commands/handoff-shared.ts:5`; `src/dashboard/server/routes/conversation-kickoff.ts:55` +- Composer waiting notice; Send starts — `src/dashboard/frontend/src/components/chat/heldKickoff.tsx:167` "Waiting to start. The handoff kickoff is in the composer" +- Ended held page, Start, no Resume — `src/dashboard/frontend/src/components/chat/HeldHandoffView.tsx:64`, `:6` "There is no Resume" +- Held conversations under Waiting, Needs you scope, Feed tab, Open — `src/dashboard/frontend/src/components/DecisionsPanel.tsx:206`, `:74`; `sessionFeed/SessionFeedSidebar.tsx:130`; `ActivityPanel.tsx:49` "feed: 'Feed'" +- `--fresh` reads no transcript, inherits no issue — `handoff.ts:124` "if (!options.fresh) {"; `conversation-forks.ts:818` +- Yellow fallback notice — `handoff.ts:239` "Handoff fell back to summary fork:" +- `Overdeck-Conversation` trailer via conversation git shim; older commits from `git commit` output — `src/lib/launcher-git-guard.ts:650`; `src/lib/overdeck/conversation-change-commits.ts:142` +- Shell-only edits never shown; others named from cached parses — `src/lib/overdeck/conversation-change-uncommitted.ts:8`, `:343` +- Project spend includes conversations; "today" = server local midnight — `src/dashboard/server/routes/costs.ts:88`, `:70`; `src/lib/costs/request-digest.ts:77` +- PR badge tones, `×`, tooltip, click, `+N` — `src/dashboard/frontend/src/components/primitives/PullRequestBadge.tsx:20-23`, `:105`, `:106` +- Sweep +30 s / 60 s; branch rules; open/closed/merged refresh; 3-strike 15-min backoff — `src/dashboard/server/services/pull-request-sync-service.ts:77,78,80,82,197`; `src/lib/overdeck/conversation-branch.ts:37`, `:40` +- Link pull request…, Pull requests…, Unlink #n in row/header/tab menus — `src/dashboard/frontend/src/components/CommandDeck/PullRequestMenuItems.tsx:63,67,74` +- Ref forms incl. GitLab MR URL — `packages/contracts/src/pull-request-ref.ts:58`; `src/cli/commands/conversations/index.ts:152` +- Dialog source labels incl. `branch-detected`, `unlinked`, shown — `src/dashboard/frontend/src/components/chat/LinkPullRequestDialog.tsx:39`, `:167` +- Transcript Link to conversation / Unlink from conversation — `src/dashboard/frontend/src/components/chat/TranscriptPullRequestLink.tsx:111`, `:98` +- `link-pr`/`unlink-pr`/`prs`, `--source`, `OVERDECK_AGENT_ID`, offline fallback — `src/cli/commands/conversations/index.ts:151-163`; `pull-requests.ts:90`, `:60` +- MCP `link_pull_request`, `watch_pull_request` — `src/lib/mcp/tools-pr.ts:15`, `:45` +- Allowed repositories list — `src/lib/overdeck/conversation-pull-request-commands.ts:96-102` +- Hand link beats branch — `packages/contracts/src/pull-request-links.ts:105` +- Unlink is sticky; relink restores — `src/lib/overdeck/conversation-pull-requests.ts:133` "ON CONFLICT(conversation_id, host, repository, number) DO NOTHING" +- Pipeline `created` links; never restores a dismissed link — `conversation-pull-requests.ts:227`; callers `src/cli/commands/done.ts:247`, `src/lib/review-artifacts.ts:140` +- Code card linked conversations with reasons — `src/dashboard/frontend/src/components/Stage/cockpit/LinkedConversations.tsx:8-11` +- Issue links: drawer only in main layout; modified clicks new tab — `src/dashboard/frontend/src/components/chat/TranscriptIssueLink.tsx:49` +- Conversation reference forms, tooltip — `src/dashboard/frontend/src/lib/conversationReferences.ts:33-35`; `ConversationReferenceLink.tsx:30` +- Pop-out routes — `src/dashboard/frontend/src/App/StandaloneRoutes.tsx:25`, `:145` +- Auto-settle setting, menu choices, CLI verbs, default on, agent skipped — `Settings/sections/AutoSettleOnMergeRow.tsx:59`; `settingsPageConstants.ts:80`; `CommandDeck/TriageMenuItems.tsx:9-11`; `conversations/index.ts:165,169`; `pull-request-sync-service.ts:230` +- GitLab MR status not shipped — `pull-request-sync-service.ts:42` "GitHub only; GitLab projects and MR links are skipped." + +Not verified (no row): "a PR that closed without merging is not shown" on issue/workspace rows; conversation-link rules for inline code, fenced code, archived and current conversation; the Pull requests dialog's refresh/relink actions. + +#### Labels needed (experimental / early / testing) +- None. The Feed tab on /activity is always shown: `src/dashboard/frontend/src/components/ActivityPanel.tsx:322` "const streams = experimentalFeaturesEnabled ? ACTIVITY_STREAMS : (['feed'] as const);" + +#### Links +- broken: `../configuration/mcp.mdx` → `/configuration/mcp#pull-requests` (rows 27-28). +- ok: `/features/skill-packs#pack-groups` (`features/skill-packs.mdx:120` "### Pack groups"); all six `/images/handoff/*.png` exist. + +#### Frontmatter +- Covered by another agent. + +#### Help section +- no (not in lines 556-959). + +#### Follow-ups (code bugs or out-of-scope doc problems; never fixed by this issue) +- External handoff authoring always runs under Claude Code: the dialog (`ForkModal.tsx:293` passes `undefined`) and the CLI never send a harness, so `src/lib/conversations/summary-fork.ts:197` "const effectiveHarness: RuntimeName = harness ?? 'claude-code';" applies even for a GPT authoring model. The CLI's "harness=provider-default" output (`handoff.ts:181`) is misleading. +- The dialog and the server disagree on what each source can do. The dialog shows Exact copy for every source except acp/opencode/grok/prime-agent (`ForkModal.tsx:150`), but the server allows only Claude Code sources (`conversation-forks.ts:773`). The dialog allows source authoring only for Claude Code (`ForkModal.tsx:180`), but the codex adapter supports it (`src/lib/conversations/transcript-adapter.ts:522` "supportsSourceAuthoredHandoff: true,"). +- Screenshot alt text at lines 588 and 630 mentions harness pickers that no longer exist (`ModelPicker.tsx:448`). The `images/handoff/continue-modal-*.png` screenshots probably show the old UI and should be retaken. The help-panel alt text (line 651) leaves out Fresh start (`ForkModal.tsx:40`). +- `pan conv prs` reads the local database directly (`pull-requests.ts:165`), not through the dashboard. Harmless. +- The "project spend on its Home page" sentence (lines 798-799) does not belong under "What a conversation changed". + +## Appendix C: conversations.mdx lines 960 to end (WI-A3) + +Research pass output, base `2007e9a4d3c`, rows verified by the planner (anchor unique, evidence greps). + +### features/conversations.mdx (lines 960-1346) + +Before: 1346 lines in the page (this range: 387 lines), 13 dash lines in this range (66 in the whole page), title/description: covered by the agent auditing lines 1-959. + +#### Change table +| # | Grep anchor (EXACT current text, copy-paste, must match the page exactly once; keep it short, one line, no line breaks) | Change (exact replacement text, or "DELETE section `## Heading` (lines x-y)", or "DELETE sentence") | Evidence (`path/file.ts:LINE` + a short exact quote that greps in that file; for an absence, the grep command run and "no match") | +|---|---|---|---| +| 1 | `Arrives in the next release (v0.65.0), and needs Session Vault set up on this machine` | `Needs Session Vault set up on this machine` (the next line, `([Session Vault](/configuration/session-vault)).`, stays as it is) | Shipped in v0.65.0 on 2026-10-04; the current version is 0.89.1. `changelog.mdx:678` "<Update label=\"v0.65.0\" description=\"2026-10-04\">"; `changelog.mdx:685` "**Conversations from your other machines:**"; `package.json:3` "\"version\": \"0.89.1\"" | +| 2 | ``runs appear in the list live, with an "on `<machine>`" chip, and open at`` | ``runs appear in the list live, with a chip naming the machine (tooltip "Runs on `<machine>`"), and open at`` | The list-row chip shows only the machine label, without "on". `src/dashboard/frontend/src/components/CommandDeck/LinkedConversationRow.tsx:51` "title={offline ? `Runs on ${label}, which is offline` : `Runs on ${label}`}" and `:54` "{chipMachineLabel(label)}". The "on <machine>" text is the header chip (`src/dashboard/frontend/src/components/chat/ConversationMachineBanner.tsx:127` "on {chipMachineLabel(label)}"), which the page's "the title bar shows which machine owns each one" already covers. | +| 3 | `evening, tomorrow morning, next week) or **Custom…** for any future date and` | `evening, tomorrow morning, next week) or the date and time field under them, then **Snooze**, for any future date and` | There is no "Custom…" item: the snooze submenu has a date and time field and a Snooze button. `src/dashboard/frontend/src/components/CommandDeck/TriageMenuItems.tsx:115` "aria-label=\"Custom snooze time\""; `git grep -n "Custom…" -- src/dashboard/frontend/src/components/CommandDeck` matches only `__tests__/TriageMenuItems.test.tsx` (no match in non-test source) | +| 4 | ``Stop is the `X` on the row, "Stop agent" in the row menu or the tab menu, or`` | ``Stop is the `X` on the row, "Stop agent" in the tab menu, or`` | The row's overflow menu has no Stop item. Its items are Rename, Regenerate title, Move, the hand-off items, Continue on another device, Copy link and Archive. The "Stop agent" menu item exists only in the tab menu: `src/dashboard/frontend/src/components/CommandDeck/ConversationActionMenu.tsx:330` "Stop agent", mounted at `src/dashboard/frontend/src/components/Stage/index.tsx:831` "<ConversationActionMenu". In `ConversationRow.tsx`, "Stop agent" is only the row X button: `:513` "title=\"Stop agent\"" | +| 5 | `"Stop the agent" in the conversation header menu; Archive is in those same menus. After you stop` | `"Stop the agent" in the conversation header menu; Archive is in the row menu, the tab menu, and the header menu ("Archive conversation"). After you stop` | Follows from row 4. `ConversationRow.tsx:921` "{archivePending ? 'Archiving…' : 'Archive'}"; `ConversationActionMenu.tsx:343` "{mutations.isArchivePending(conversation.name) ? 'Archiving…' : 'Archive'}"; `src/dashboard/frontend/src/components/chat/header/ConversationHeaderMenu.tsx:372` "{archivePending ? 'Archiving…' : 'Archive conversation'}" and `:380` "Stop the agent" | +| 6 | `Relative links in the preview show as plain text for now, until they resolve` | Replace this line and the next line (`to files.`) with: `Relative links in the preview show as plain text in the diff window, which has no pane to open a file in; a link to a file that does not exist shows as not found.` | "for now, until they resolve" is stale. PAN-5337 made preview links resolve, but a link opens a file only where a Command Deck pane exists. `changelog.mdx:167` "**Links in Markdown previews work:**"; `src/dashboard/frontend/src/components/chat/MarkdownDocLink.tsx:96` "if (!deck \|\| (isDir && !deck.openDock)) return <span>{children}</span>;" and "Link target not found: ${target}"; `src/dashboard/frontend/src/components/diff/DiffMarkdownPreview.tsx:59` "<MarkdownTab body={query.data.text} docLocation={{ rootId, path }} />" | +| 7 | ``The command palette (`⌘J` / `Ctrl+J`, see [Command palette](/features/keyboard-shortcuts#command-palette))`` | ``The command palette (`⌘K` / `Ctrl+K`, or `⌘J` / `Ctrl+J` to open it on conversations; see [Command palette](/features/keyboard-shortcuts#command-palette))`` | `src/dashboard/frontend/src/App/hooks/useAppShortcuts.ts:43` "keys: { mac: 'Meta+K', other: 'Ctrl+K' }," and `:55` "keys: { mac: 'Meta+J', other: 'Ctrl+J' }," with "label: 'Find a conversation'," | +| 8 | ``run. In `~/.overdeck/config.yaml` under `conversations:`, the matching keys are `embeddings` `` | ``run. The automatic embed also needs **Settings → Background AI → Session embeddings** on (off by default) and low-cost mode off. In `~/.overdeck/config.yaml` under `conversations:`, the matching keys are `embeddings` `` | `src/lib/conversations/enrichment/index.ts:241` "if (tier >= 2 && config.embeddings && config.embeddingAutoOnDeep" and `:242` "&& isBackgroundFeatureEnabled('sessionEmbeddings')) {"; `src/lib/background-ai/features.ts:42` "if (backgroundAi.cheapMode) return false;"; `src/lib/background-ai/registry.ts:40` "sessionEmbeddings defaults OFF"; `src/dashboard/frontend/src/components/Settings/types.ts:155` "label: 'Session embeddings'"; `src/dashboard/frontend/src/components/Settings/sections/BackgroundAiSection.tsx:175` "Background AI" | +| 9 | `back. See [Terminal backends]` | Insert a new paragraph after the paragraph that ends on this anchor's line (`...for the details.`): ``After `pan shutdown`, the same Needs you row offers the sessions the shutdown stopped (`Resume the <N> sessions shutdown stopped`), and Resume all resumes those conversations, then the work agents.`` | Missing fact (PAN-5342). `src/dashboard/frontend/src/lib/useDecisions.ts:385` "? `Resume the ${count} ${count === 1 ? 'session' : 'sessions'} shutdown stopped`"; `src/dashboard/server/services/backend-restart-recovery.ts:46` "operator stops after the offer. Resume all then resumes conversations with"; `changelog.mdx:102` "**Safe shutdown:**" | + +#### Verified, keep +- Vault copy chip "from `<machine>`" with tooltip "Read-only copy from `<machine>`" — `src/dashboard/frontend/src/components/CommandDeck/ConversationRow.tsx:370` "title={`Read-only copy from ${ownerLabel}`}" +- Claude Code and Codex vault copies — `changelog.mdx:685` "Claude Code and Codex conversations saved to the vault by another machine" +- Pipeline agent title — `src/dashboard/server/services/vault-agent-subjects.ts:37` "`${issue} ${state.role} agent (${state.id})`" +- Read-only composer, `pan vault resume <id>`, **Continue here** — `src/dashboard/frontend/src/components/chat/ComposerFooter.tsx:875` "{`Read-only copy from ${label}.`}", `:883` "Continue here" +- Continue dialog strings — `src/dashboard/frontend/src/components/chat/VaultContinueDialog.tsx`: + - title and "Saved on" line: `:171`, `:178` + - drift buttons Continue / Continue with a note / Cancel + - "No registered project matches" `:123` and "Clone and register" `:126` + - "Already continued on" `:95` + - no-native-resume shows the command + - dirty checkout: "goes into a new workspace" +- `/conv/@<env>/<name>` — `src/dashboard/frontend/src/App/routes.ts:201` +- **Pull here** — `ConversationMachineBanner.tsx:133` +- `pan conv pull` / `reclaim`: + - steps: `src/cli/commands/conversations/pull.ts:22` "const STEPS = ['release', 'transfer', 'adopt', 'finish'] as const;" + - `:91` "Pulled: /conv/${status.conversation.id}" + - failure line `:88` + - `--stop-turn` and `--force` in `src/cli/commands/conversations/index.ts:133,139` + - codes `still-running-there` / `target-offline`: `src/dashboard/server/services/conversation-release-service.ts:321,328` +- Released copy "Continued on `<machine>`" — `ConversationMachineBanner.tsx` "Continued on <span className={styles.machineBannerLabel}>{label}</span>" +- Diff window: + - **Full diff in a new window**: `ConversationHeaderMenu.tsx:245` + - All turns / vs main / Compare…: `src/dashboard/frontend/src/components/DiffPanel.tsx:549,566,585` + - Compare base/head, A..B / A...B, Enter: `src/dashboard/frontend/src/components/DiffCompareBar.tsx:97,103,110,84` + - ignore whitespace: `DiffPanel.tsx:645` + - Diff/Preview switch: `src/dashboard/frontend/src/components/diff/DiffFileBar.tsx:33` + - "Showing the current file": `src/dashboard/frontend/src/components/diff/markdownPreviewSource.ts:7` + - Open file only with a deck: `DiffPanel.tsx:377` "deck?.openBeside && explorerRootId && rootPath" +- Sections and settling: + - four sections: `ConversationList.tsx:303-308` + - only Snoozed/Settled collapse: `:311` + - pending input means Needs you: `src/dashboard/frontend/src/components/CommandDeck/conversation-triage.ts:41` + - settle checkbox on top-level rows: `ConversationRow.tsx:521` +- Snoozing: + - presets and "back <when>": `conversation-triage.ts:84,87,89,93,123` + - Unsnooze: `TriageMenuItems.tsx:134` + - Undo toast: `useConversationMutations.ts:430` + - Cmd/Ctrl+Z: `ConversationList.tsx:629` + - bulk bar: `ConversationList.tsx:802-811` + - Ctrl/Cmd-click opens beside: `ConversationList.tsx:657` +- Idle auto-settle: + - default 3, `0` = off: `src/lib/overdeck/control-settings.ts:215` "Default 3; 0 turns it off." + - 15 minutes, primary only, Deacon freeze: `src/dashboard/server/services/conversation-idle-settle-service.ts:18` "IDLE_SETTLE_INTERVAL_MS = 900_000", plus `isPeerDashboardProcess` and `isDeaconGloballyPaused` + - CLI: `index.ts:169` + - Settings label: `AutoSettleIdleRow.tsx:81` + - scheduled delivery clears settle/snooze: `src/dashboard/server/services/conversation-schedule-service.ts:58` +- Stopping and archiving: "Stopping…"/"Archiving…" at `ConversationRow.tsx:262`; toast `Archived "<title>"` at `useConversationMutations.ts:251` +- Resume: + - `pan conv resume`, output and exit codes: `src/cli/commands/conversations/resume.ts:10,57` + - MCP `resume_conversation`: `src/lib/mcp/tools-write.ts:202` + - `operate` scope: `src/dashboard/server/route-scopes.ts:221` +- Backend-restart recovery: + - row label: `useDecisions.ts:386` + - Resume all / Dismiss: `BackendRestartCard.tsx:87,90` + - skip rules, pressure wait, flywheel, in-memory, Herdr only ("tmux hosts never fire the edges"): `backend-restart-recovery.ts` header +- Palette: + - tiers: `palette-conversation-hits.ts:71` + - `archived` chip: `:150` + - Newest first (default on, remembered): `CommandPalette.tsx:376,1065` + - timeout and unavailable messages: `:955`, `:964` + - `On <machine>` group: `palette-fleet-hits.tsx:43` +- Search settings: + - conversationSearch defaults: `src/lib/config-yaml/defaults.ts:150-153` + - model prices: `src/dashboard/frontend/src/components/Settings/embeddingModels.ts:10-12` + - "Estimate & reindex all conversations": `ConversationSearchSection.tsx:177` + - card lives in the Conversations section: `SettingsPage.tsx:596-602` + - banners: `ConversationSearchBanner.tsx:50,52,53,97,108` +- `pan conv`: + - scan/search/embed/enrich flags: `index.ts:41-47,58-80,226-252` + - enrich threshold: `defaults.ts:110` "costConfirmThreshold: 1.00," + - `conversations.embeddings` false and related keys: `defaults.ts:102-105` + - embedding Settings rows: `ConversationSearchSection.tsx:228,253,304,334` + - `VOYAGE_API_KEY`: `src/lib/conversations/embeddings/providers.ts:115` + - `~/.overdeck.env` loaded first: `src/cli/index.ts:12` +- "See also" commands exist: + - `pan conv current` / `whoami`: `index.ts:208-209` + - fork, handoff, unarchive-conversation, resume, open: `src/cli/index.ts:367,378,400,405,268` + - tell: `tell-register.ts:11` + - share: `sharing/index.ts:16` +- Subagents: + - "Working for …": `messagesTimeline/dividers.tsx:35` + - composer only for live Codex conversations with a capable child, drafts kept per child, delivery-confirmation message: `SubagentComposer.tsx:14,24,73` + +#### Labels needed (experimental / early / testing) +- None. Nothing in this range is gated by `EXPERIMENTAL_TAB_IDS`. The stale "next release (v0.65.0)" label is removed by row 1. + +#### Links +- All 17 internal links resolve: + - `/configuration/session-vault` + - `/configuration/session-vault#continue-on-another-machine` (heading at line 190) + - `/configuration/linked-machines` + - `#the-turn-card` + - `#stopping-or-archiving-a-conversation` + - `/features/mission-control#all-projects-and-side-by-side-conversations` (heading at line 33) + - `#pull-requests-on-conversations` + - `#scheduled-runs` + - `/configuration/mcp` + - `/features/keyboard-shortcuts#command-palette` (3 links; heading at line 39) + - `#search-from-the-command-line` + - `/cli/conversation-commands` + - `/features/mission-control` + - `/features/cloister` + - `/configuration/harnesses` +- The external link to `docs/TERMINAL-BACKENDS.md#after-a-session-server-restart-pan-5091` resolves (`docs/TERMINAL-BACKENDS.md:159`). +- No headings change, so there are no inbound anchors to update. + +#### Frontmatter +- Outside this range. + +#### Help section +- Yes: "When search is not working" (lines 1259-1280) already has both the Discord and GitHub Issues links. + +#### Follow-ups (code bugs or out-of-scope doc problems; never fixed by this issue) +- The diff window's Markdown preview renders relative links as plain text, because the popout has no Stage deck (`MarkdownDocLink.tsx:96`). If links are meant to work there too, that is a code gap. +- `pan conv embed` checks neither `conversations.embeddings` nor the Background AI `sessionEmbeddings` toggle; only the automatic embed after enrich checks them. The two overlapping switches (Settings → Conversations "Semantic embeddings" and Settings → Background AI "Session embeddings") are easy to confuse. + +## Appendix D: skill-packs.mdx (WI-D1) + +Research pass output, base `2007e9a4d3c`, rows verified by the planner (anchor unique, evidence greps). + +### features/skill-packs.mdx + +Before: 829 lines, 19 dash lines, title "Skill Packs", description 98 chars. + +Pack catalog check: `KNOWN_PACKS` (`src/lib/skill-packs/adapters.ts:115`) holds exactly 10 ids: mattpocock, deft, sageox, +gstack, pstack, atlassian, remotion, hyperframes, openmontage, video-use. The catalog table, the known-pack list (page line +167) and the `## Packs` sections cover all 10. No pack in code is missing from the page, and the page names no pack code +lacks. `KNOWN_PACK_GROUPS` (`src/lib/skill-packs/groups.ts:17`) holds only `video` with the four video packs. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| 1 | `The dashboard can turn packs on and off but not add them; it shows the `pan skills pack add` command instead.` | `The dashboard turns packs on and off. On the Skills page it can also add the known packs listed under **Available packs** (see [Adding packs from the dashboard](#adding-packs-from-the-dashboard)); for any other pack it shows the `pan skills pack add` command.` | `src/dashboard/frontend/src/components/skills/SkillPacksSection.tsx:301` "{level === 'global' && <AvailablePacksSection search={search} onAdd={setAddRequest} />}"; `src/dashboard/frontend/src/components/skills/AddPacksDialog.tsx:156` "Trust and add {plural(ready.length)}"; `src/lib/skill-packs/known.ts:3` "which the dashboard may add with one click" | +| 2 | `Overdeck's default source for the `mattpocock` pack is the operator-controlled fork `eltmon/skills`, pinned to the `v1.2.3` commit.` | `Overdeck's default url for the `mattpocock` pack is the operator-controlled fork `eltmon/skills`. The pack has no default ref, so `pan skills pack add mattpocock` needs `--ref` (these docs use `--ref v1.2.3`, commit `6acc160`).` | `src/lib/skill-packs/adapters.ts:116-121` mattpocock entry has a url and no `ref:`; `src/lib/skill-packs/known.ts:66` "return KNOWN_PACKS[id]?.ref ?"; `src/lib/skill-packs/known.ts:155` "has no default ref; pass --ref <tag-or-branch>" | +| 3 | `` `pstack` and `sageox` default to commit refs `` | `` `pstack`, `sageox`, `atlassian` and the four video packs default to commit refs `` | `src/lib/skill-packs/sources.ts:410` "if (COMMIT_PATTERN.test(entry.ref)"; 40-hex refs at `src/lib/skill-packs/adapters.ts:183` "ref: '3e20ac75161bc34468845df714701cc9bf6075f4'," (also 192, 201, 212) and `src/lib/skill-packs/atlassian.ts:7` "export const ATLASSIAN_PACK_COMMIT" | +| 4 | `` `acp` and `opencode` get no server: the ACP host drops non-`stdio` entries. `ohmypi`, `kimi-code`, `muse` and `prime-agent` provision no MCP at all. `` | `` `acp`, `opencode` and `grok` get no server: the ACP host drops non-`stdio` entries. `pi`, `ohmypi`, `kimi-code`, `muse` and `prime-agent` provision no MCP at all. `` | `packages/contracts/src/harness-behavior.ts:254` "export const GROK_BEHAVIOR: HarnessBehavior = {" (spreads ACP_BEHAVIOR, `:201` "launchCommandKind: \"acp-host\","); `:155` "export const PI_BEHAVIOR: HarnessBehavior = {" (spreads OHMYPI_BEHAVIOR); `src/lib/mcp/agent-injection.ts:149` "const OVERDECK_MCP_JSON_LAUNCH_KINDS: ReadonlySet<string> = new Set(['claude-code', 'acp-host']);"; `src/lib/acp/mcp-config.ts:23` "entry.type !== \"stdio\"" | +| 5 | `(for example `video · 4 packs not added`)` | `` (for example `video` with `group · 4 packs not added`) `` | `src/dashboard/frontend/src/components/skills/AvailablePacksSection.tsx:76` "group · {missingLabel(group)}" (page line 189's new-conversation example is correct: `src/dashboard/frontend/src/components/newConversation/ConversationSkillsField.tsx:270` "· {missingLabel(group)}") | +| 6 | `Never: they upgrade the install in place` | `` Never: `connect-chrome` is a symlink alias (symlinked skills are never mounted); the others upgrade the install in place `` | `src/lib/skill-packs/gstack.ts:78` "'connect-chrome': { class: 'excluded'" with reason "Symlink alias; symlinked skills are never mounted." | +| 7 | `Changes apply at the next launch; a running agent keeps the skills it launched with.` | `Changes apply at the next launch; a running agent keeps the skills it launched with, but a running conversation can load new ones with `pan skills add` (see [Adding skills to a running conversation](#adding-skills-to-a-running-conversation)).` | `src/cli/commands/skills.ts:743` "skills.command('add <conversation>')" | +| 8 | `Overdeck sends them to the server as `Authorization: Basic base64(email:token)`.` | `Overdeck sends them to the server as `Authorization: Basic base64(email:token)`, but only for a Jira Cloud site (`*.atlassian.net`); with a Data Center base URL no header is sent.` | `src/lib/skill-packs/atlassian.ts:31` "if (keys?.jiraBaseUrl && !isCloudJiraSite(keys.jiraBaseUrl)) return null;"; `src/lib/tracker/jira-config.ts:38` "return new URL(site).hostname.toLowerCase().endsWith('.atlassian.net');" | +| 9 | `npm and pnpm projects run Deft's installer, `npx --yes @deftai/directive install --yes`.` | `npm and pnpm projects run Deft's installer: `directive install --yes` when `directive` is on `PATH`, else `npx --yes @deftai/directive install --yes`.` | `src/lib/deft/install.ts:134` "? ['directive', ['install', '--yes', '--root', worktree]]"; `:135` ": ['npx', ['--yes', '@deftai/directive', 'install', '--yes', '--root', worktree]];" | +| 10 | `## Terminology: skill packs and skill bundles` | `Still stuck? Ask in [Discord](https://discord.gg/ZpHE2ZTv5P) or open a [GitHub issue](https://github.com/eltmon/overdeck/issues).` + blank line + `## Terminology: skill packs and skill bundles` | Brief rule 9: page has `## Troubleshooting` (line 810); `grep -c 'discord.gg' features/skill-packs.mdx` prints 0 | + +#### Verified, keep +- KNOWN_PACKS urls (all `eltmon/` forks except atlassian upstream) and adapters — `src/lib/skill-packs/adapters.ts:115-219`, `atlassian.ts:5` +- Default refs sageox 0e6c7e2, pstack ae5650f, atlassian 3be5562, remotion 3e20ac7, hyperframes 34f98e6, openmontage 2e003e6, video-use 43cfc56; none for mattpocock, deft, gstack — `adapters.ts:129,154,183,192,201,212`, `atlassian.ts:7` +- pstack `pluginRoot: 'harness/pstack/claude-code',` (`adapters.ts:156`), mountExtras, 7 opt-in names; 58 skills / 6 executables, so 51/7 (counted in the cached `~/.overdeck/packs/pstack/ae5650f…/harness/pstack/claude-code`) +- mattpocock 25 skills / 1 opt-in, MIT (cached `~/.overdeck/packs/mattpocock/6acc160…/.claude-plugin/plugin.json`) +- sageox `skillsRoot: 'extensions/skills',` (`adapters.ts:127`) and 9 opt-in names; atlassian `skillsExclude: ['skills/v1'],` (`:174`), 4 opt-in names, MCP URL and disclosure (`atlassian.ts:9-18`) +- hyperframes `archivePaths: ['skills', 'plugin.json'],` (`:194`); openmontage `skillsRoot: '.agents/skills',` (`:203`); "holds 92 skills. The pack mounts the 38" (`openmontage.ts:4`); 54 excluded (55 names, `gsap` has no SKILL.md) +- video-use root skill (`adapters.ts:214`), host notice and `uv run --no-project --with-requirements` (`video-use.ts:14-19`) +- gstack map 22 default / 14 opt-in / 9 browser / 9 browser-opt-in / 9 excluded, names exact, reviewed at 1b778f78 — `gstack.ts:28,39-109` +- Deft map (7 mounted, all conflicting equivalents) at 48e8cbf — `deft.ts:29,33-83` +- Dashboard-addable rule — `known.ts:59` "if (!known?.url || !known.ref) return 'needs-ref';", `:60`; `pack list` footer — `known.ts:120` +- CLI verbs and flags all match: skills list/set/add, pack add/update/browser/list/remove/sync/gc (gc default 7), pack sageox status/upload/link/commit, deft status/enable/disable/use/back/save/show, handoff --skill/--pack/--group — `skills.ts:733-786`, `skills-sageox.ts:63-67`, `skills-deft.ts:151-161`, `skills-deft-pipeline.ts:149-158`, `src/cli/index.ts:392-394` +- "<id>: already added" (`skills.ts:419`); "use either --pack or --group, not both" (`:128`); pack id pattern (`sources.ts:41`); core-skill reservation (`:586`); adapter detection (`:477`); "Trust this commit? [y/N]" (`skills.ts:346`); "Not written: re-run with --yes" (`:356`) +- Resolution precedence — `resolve.ts:90`; global pack off stored as no key — `store.ts:578` +- Six outcomes — `conversation-skill-apply.ts:32`; launch-wired packs — `conversation-skill-hot-apply.ts:60`; self-restart refusal — `skills-add.ts:25`; `add_skills` MCP tool — `tools-write.ts:220` +- SageOx strings, hook event lists (`launch.ts:32`, `codex-hooks.ts:22`), doctor messages "built ox at" / "ox not built for pack" (`doctor-sageox.ts:54,47`), link states (`binding.ts:28`) +- Launch warnings "not cached" / "browser runtime not built" (`skill-overrides/launch.ts:122,131`); bun and go missing errors (`browser.ts:54`, `ox-build.ts:27`) +- Settings → Tracker Keys and JIRA_EMAIL/JIRA_API_TOKEN fallback — `settingsPageConstants.ts:85`, `config-yaml/load.ts:257-258` + +#### Labels needed (experimental / early / testing) +- None. Skills is not in `EXPERIMENTAL_TAB_IDS` (`src/dashboard/frontend/src/lib/experimentalFeatures.ts:4`). + +#### Links +- all 25 internal links resolve (16 in-page anchors; `cli/skills-commands.mdx:328,366`; `configuration/mcp.mdx:645`; the other pages exist). The GitHub links to docs/SAGEOX-FORK.md and docs/SKILL-PACKS.md point at existing files. + +#### Frontmatter +- title: keep +- description: keep (98 chars) + +#### Help section +- yes, `## Troubleshooting` at line 810, with no help links; row 10 adds them. + +#### Follow-ups +- Not checked (fork contents, not in this repo): remotion 13, hyperframes 9 skills and 6 scripts, sageox 17 defaults, atlassian's 3 default skill names, gstack "five binaries", ~1 GB / ~115 MiB / go1.27.3 sizes. +- Only partly checked: Deft dashboard surfaces (page lines 624-631). Components exist for Sign off, Deft gates, Deft review cycle, spec/install drift (`components/deft/`); the Decisions tab placement, Resolve, the board `Deft` chip, and whether the agents lane sits behind an experimental tab were not checked. Atlassian doctor probe wording (line 780) was checked only for "no Jira email and API token". The Codex `overdeck-packs` marketplace and `--plugin-dir` (line 806) appear only in comments I read. +- Line 573 "Both variables" follows a three-row table; left alone. +- Line 451 shows `<project>` where the code prints the project path (`skills-pack-browser.ts:60`); cosmetic. + +## Appendix E: skills.mdx, swarm.mdx, safe-shutdown.mdx (WI-E1, WI-E3, WI-E2) + +Research pass output, base `2007e9a4d3c`, rows verified by the planner (anchor unique, evidence greps). + +### features/skills.mdx + +Before: 338 lines, 6 dash lines, title "Skills System", description 141 chars. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| 1 | The dashboard's **Skills** page lists every skill side by side per harness | Replace the whole paragraph (line 10) with: The dashboard's **Skills** page (left column, More, System, Skills) lists every skill with its description and a global on/off switch, grouped as Core (locked on), Overdeck (`~/.overdeck/skills`) and Personal (`~/.claude/skills`, `~/.agents/skills`). Filter by name or description, or narrow the list with **All**, **Off**, **Core** and **Overridden below**. Skill packs are listed below the skills. | `src/dashboard/frontend/src/components/skills/SkillOverridesPanel.tsx:80` "global: [['all', 'All'], ['off', 'Off'], ['core', 'Core'], ['below', 'Overridden below']]," ; `:35` "{ key: 'overdeck', title: 'Overdeck', hint: '~/.overdeck/skills' }," ; `:36` "{ key: 'personal', title: 'Personal', hint: '~/.claude/skills, ~/.agents/skills' }," ; `:294` 'placeholder="Filter skills by name or description"' ; `src/dashboard/frontend/src/components/frame/navGroups.ts:58` "{ id: 'skills' as Tab, label: 'Skills', icon: Cpu }," . SkillRow (~459-498) renders name, description, override note and switch only: no path, no harness columns, no sync indicator. | +| 2 | - **Universal** - Work across all AI coding tools (Claude Code, Codex, Cursor, Gemini CLI, Google Antigravity) | - **Multi-harness** - `pan sync` installs them for Claude Code (`~/.claude/skills`) and for Codex and Pi (`~/.agents/skills`) | `src/lib/paths.ts:57` "Codex, Pi, and Oh My Pi discover the Agent Skills standard directory." ; `src/lib/paths.ts:63` "skills: join(CLAUDE_DIR, 'skills')," ; `src/lib/multi-tool-sync.ts:4` "Deprecated compatibility surface for the retired `tools.also_sync` option." ; `git grep -n -i "antigravity\|\.gemini/skills" -- src/lib src/cli` (non-fixture): no match | +| 3 | - **Shareable** - Distribute via `pan sync` to sync to all connected AI tools | - **Shareable** - `pan sync` copies them to every harness skill directory it manages | `src/lib/harness-skill-sync.ts:36` "Copy complete skill bundles into the standard directory shared by Codex, Pi, and Oh My Pi." ; `src/cli/commands/sync.ts:357` "executeSync({ force: options.force, diff: options.diff })" | +| 4 | Overdeck ships with 70+ built-in skills organized by category: | Overdeck ships more than 120 built-in skills. A selection, by category: | `ls -d sync-sources/skills/*/ \| grep -v _template \| wc -l` printed 126, each with a SKILL.md | +| 5 | Comprehensive code review checklist | DELETE the table row `code-review` (line 40) | `ls sync-sources/skills/code-review sync-sources/dev-skills/code-review`: No such file or directory | +| 6 | Spawn agent for an issue | Replace the row (line 65) with: `` \| `pan-start` \| Spawn a work agent for an issue \| `` | `ls sync-sources/skills/pan-issue`: No such file ; `sync-sources/skills/pan-start/SKILL.md:3` "spawn a work agent for an issue in its own terminal-backend pane and workspace" | +| 7 | Approve agent work and merge | DELETE the table row `pan-approve` (line 69) | `ls sync-sources/skills/pan-approve`: No such file or directory | +| 8 | Check system health | Replace the row (line 70) with: `` \| `pan-doctor` \| Check system health, dependencies and configuration \| `` | `ls sync-sources/skills/pan-health`: No such file ; `sync-sources/skills/pan-doctor/SKILL.md:3` "check Overdeck system health, dependencies, and configuration" | +| 9 | Initial setup wizard | DELETE the table row `pan-setup` (line 73) | `ls sync-sources/skills/pan-setup`: No such file or directory | +| 10 | Issue tracker operations | Replace the row (line 76) with: `` \| `pan-admin-tracker` \| Tracker-specific operations (Linear states, cleanup) \| `` | `ls sync-sources/skills/pan-tracker`: No such file ; `sync-sources/skills/pan-admin-tracker/SKILL.md:3` "tracker-specific operations (Linear states, cleanup)" | +| 11 | Recover crashed agents | DELETE the table row `pan-rescue` (line 78) | `ls sync-sources/skills/pan-rescue`: No such file or directory | +| 12 | Configuration management | Replace the row (line 82) with: `` \| `pan-admin-config` \| View and edit project configuration \| `` | `ls sync-sources/skills/pan-config`: No such file ; `sync-sources/skills/pan-admin-config/SKILL.md:3` "view and edit Overdeck project configuration" | +| 13 | Git-backed issue tracking with dependencies | DELETE the table row `beads` (line 97) | `ls sync-sources/skills/beads`: No such file or directory | +| 14 | Opus-driven planning with PRD, STATE.md, and beads | DELETE the table row `opus-plan` (line 102) | `ls sync-sources/skills/opus-plan`: No such file or directory | +| 15 | Skills are invoked via slash commands in any AI coding tool: | Skills are invoked as slash commands, for example in Claude Code: | `src/lib/multi-tool-sync.ts:4` "Deprecated compatibility surface for the retired `tools.also_sync` option." (no Cursor/Windsurf target) | +| 16 | # In Claude Code, Cursor, Windsurf, etc: | # In Claude Code: | same as row 15 | +| 17 | cat > ~/.overdeck/skills/my-custom-skill/skill.md <<'EOF' | cat > ~/.overdeck/skills/my-custom-skill/SKILL.md <<'EOF' | `src/lib/skill-overrides/catalog.ts:62` "readFile(join(root, dirent.name, 'SKILL.md'), 'utf8')" | +| 18 | # My Custom Skill | Insert these four lines immediately before `# My Custom Skill`, inside the heredoc: `---` / `name: my-custom-skill` / `description: One line saying what the skill does and when to use it` / `---` | `src/lib/skill-overrides/catalog.ts:44` "First line of the SKILL.md frontmatter `description`" ; `src/lib/skill-packs/adapters.ts:244` "const rawDescription = record['description'];" ; `sync-sources/skills/_template/pan-verb-skill.md` opens with `name:`/`description:` frontmatter | +| 19 | # Skill Title | Insert these four lines immediately before `# Skill Title` in the anatomy block: `---` / `name: skill-name` / `description: One line saying what the skill does and when to use it` / `---` | same as row 18 | +| 20 | See the [Claude skill creator](/cli/core-commands) or use `/pan-skill-creator` for guided creation. | Use `/pan-skill-creator` or `/claude-skill-creator` for guided creation. | `grep -n "skill-creator" cli/core-commands.mdx`: no match ; `sync-sources/skills/claude-skill-creator/SKILL.md` and `sync-sources/skills/pan-skill-creator/SKILL.md` exist | +| 21 | - Updates existing skills if versions differ | - Overwrites installed skill files you have not edited; a file you edited since Overdeck installed it is skipped and reported as user-modified (`pan sync --force` overwrites it) | `src/lib/sync.ts:458` "// File exists, hash matches manifest — safe to overwrite (user didn't modify)" ; `src/lib/sync.ts:484` "result.conflicts.push(file.relativePath);" ; `src/cli/commands/sync.ts:402` "Use --force to overwrite, --diff to see changes." | +| 22 | - Preserves user-owned and user-modified files, reporting modified stale files instead of deleting them | - Preserves files Overdeck did not install, except that in `~/.claude/skills` a file at the same path as a bundled skill file is overwritten and reported as adopted; when a bundled skill is removed, an installed copy you edited is reported instead of deleted | `src/lib/sync.ts:419` "install; it is overwritten, recorded in the manifest, and reported as" ; `src/lib/sync.ts:503` "result.adopted.push(file.relativePath);" ; `~/.agents/skills` skips such files: `src/lib/harness-skill-sync.ts:81` "result.skipped.push(file.relativePath);" | +| 23 | Conversation values are set only when the conversation is created | Replace from the start of line 241 through "(see [Conversations](/features/conversations))." with: Conversation values are set when the conversation is created, in the **New conversation with options…** dialog (see [Conversations](/features/conversations)), and later with [`pan skills add`](/cli/skills-commands#pan-skills-add), the `add_skills` MCP tool or **Add skills…** in the conversation menu; a running Claude Code conversation loads added packs in place. Keep the rest of the paragraph. | `src/lib/overdeck/conversation-skill-apply.ts:200` "const write = () => deps.setConversationSkillOverrides(head.name, merged);" ; `src/cli/commands/skills.ts:743` "skills.command('add <conversation>')" ; `src/lib/mcp/tools-write.ts:220` "name: 'add_skills'," ; `src/dashboard/frontend/src/components/CommandDeck/ConversationActionMenu.tsx:296` "Add skills…" ; `changelog.mdx:37` "Claude Code loads them in place with `/reload-plugins`" | +| 24 | Overdeck includes specialized subagent templates for common development tasks. | Replace line 297 with: Overdeck ships five pipeline agent definitions, `pan-work-agent`, `pan-review-agent`, `pan-test-agent`, `pan-uat-agent` and `pan-merge-agent`, which `pan sync` installs into `~/.claude/agents/` and Cloister uses when it launches the matching specialist. It ships no general-purpose subagent templates. | `src/lib/sync.ts:283` "const REQUIRED_PIPELINE_AGENTS = [" ; `src/lib/sync.ts:257` "used by `claude --agent pan-<type>-agent` when Cloister" ; `ls sync-sources/agents` lists only the five pan-*-agent.md files | +| 25 | ### Code Review Subagents | DELETE section `### Code Review Subagents` (lines 299-313) and put in its place: `### Code review` / (blank line) / Overdeck ships no code-review subagents. A full review runs as the [review convoy](/features/convoys): four reviewers (correctness, security, performance and requirements) whose prompts live in `roles/review-*.md` and are inlined when the review starts, plus a review parent that combines their findings. | `src/lib/__tests__/code-review-agent-definitions.test.ts:55` "it('does not keep legacy .claude/agents/code-review-* subagent files'" ; `:67` "it('does not ship a separate code-review-synthesis sub-agent" ; `:10` "const REVIEW_SUB_ROLES = ['security', 'correctness', 'performance', 'requirements'] as const;" ; `features/convoys.mdx:2` 'title: "Review convoy"'. Inbound links to `skills#code-review-subagents`: none (`git grep` no match) | +| 26 | - [Creating Skills](/cli/core-commands#pan-skill-creator) - Detailed skill creation guide | - [Creating custom skills](#creating-custom-skills) - Write your own SKILL.md | `grep -n "^#" cli/core-commands.mdx`: no pan-skill-creator heading ; in-page `## Creating Custom Skills` (line 122) | +| 27 | - [Convoys](/features/convoys) - Parallel subagent execution | - [Review convoy](/features/convoys) - Four parallel reviewers and one synthesis parent | `features/convoys.mdx:2` 'title: "Review convoy"' | +| 28 | - [Subagents](/cli/core-commands#pan-subagent-creator) - Custom subagent templates | DELETE the line | `grep -n "subagent" cli/core-commands.mdx`: no match | + +#### Verified, keep +- `pan sync` installs into `~/.claude/skills` and `~/.agents/skills` (line 219): `src/lib/paths.ts:59` "export const AGENT_SKILLS_DIR = join(homedir(), '.agents', 'skills');" ; `src/cli/commands/sync.ts:359` "executeAgentSkills({ force: options.force, diff: options.diff })" +- `pan sync` first refreshes `~/.overdeck/skills` from `sync-sources/skills/`, then copies from it (lines 201, 227): `src/cli/commands/sync.ts:345` "refreshCache()" ; `src/lib/sync.ts:228` "const dst = join(SKILLS_DIR, skillDir.name);" +- A hand-made skill in `~/.overdeck/skills` survives the refresh: `src/lib/sync.ts:331` "setManifestEntry(manifest, relativePath, entry.hash, 'user');" ; `src/lib/manifest.ts:152` "if (entry.source !== 'overdeck') continue;" +- Removed bundled skills are pruned (line 229): `src/lib/sync.ts:514` "pruneStaleManifestEntries(targetBase, manifest, sourceSet, {" +- Empty bundled dirs are not recreated (line 231): `src/lib/sync.ts:187` "mkdirSync(dest, { recursive: true });" runs only when a file is copied +- `--dry-run` (line 223): `src/cli/index.ts:153` "'--dry-run', 'Show what would be synced'" +- Project skills: listed last and the first name found wins (line 205): `src/lib/skill-overrides/catalog.ts:88` "if (!byName.has(entry.name)) byName.set(entry.name, entry);" +- Project skills are copied once at workspace creation, never over an existing target (lines 207, 212): `src/lib/workspace-manager/create.ts:541` "mergePanSkillsIntoWorkspace(projectConfig.path, workspacePath)" ; `src/lib/skills-merge.ts:258` "if (existsSync(targetSkillDir)) {". The CLI fallback and `pan workspace update` call only `mergeSkillsIntoWorkspace` (`src/cli/commands/workspace-create.ts:322`, `src/cli/commands/workspace-maintenance.ts:148`). Both verbs exist (`src/cli/commands/workspace.ts:21`, `:178`). +- Precedence (line 237): `src/lib/skill-overrides/resolve.ts:5` "conversation > issue > project > global > default (on)" +- The 11 core skills (lines 245-247): `src/lib/skill-overrides/resolve.ts:15` "'pan', 'pan-done', 'pan-flywheel', 'pan-foreman', 'pan-plan', 'pan-start'," +- Storage table (lines 253-256): `src/lib/skill-overrides/store.ts:4` and `:6` ; `src/lib/skill-overrides/issue-file.ts:63` ; `src/cli/commands/skills.ts:180` "push pending: ${result.reason ?? 'unknown'}" ; `src/lib/overdeck/conversations.ts:343` "skill_overrides: string | null;" +- CLI list/set flags (lines 264-269): `src/cli/commands/skills.ts:734-738` +- Dashboard controls (lines 276-278): `SkillControls.tsx:104` "`${word} · pinned here`" ; `SkillOverridesPanel.tsx:344` "Reset all" ; issue filters "Changed here", "Off" (`:82`) +- Claude `--settings` skillOverrides and Codex `[[skills.config]]` (lines 284-285): `src/lib/skill-overrides/launch.ts:238`, `:269` +- Overrides apply only to local claude-code and codex launches, not Fly; a failure prints a warning (line 287): `src/lib/skill-overrides/launcher-lines.ts:105` "Local launches of the harness apply overrides; remote (Fly) launches do not." and "[launcher] WARNING: skill overrides not applied" +- `pan handoff --skill/--pack` (line 287): `src/cli/index.ts:393-394` +- Planning subsection (line 317): `roles/plan.md` exists ; `docs/ROLES.md:169` "## Why no ambient subagents" + +#### Labels needed (experimental / early / testing) +- None. The Skills tab is not in `EXPERIMENTAL_TAB_IDS`. + +#### Links +- broken: `/cli/core-commands` (line 192) → removed by row 20 +- broken: `/cli/core-commands#pan-skill-creator` (line 336) → `#creating-custom-skills` (row 26) +- broken: `/cli/core-commands#pan-subagent-creator` (line 338) → delete (row 28) +- These resolve: `#project-skills`, `/features/skill-packs`, `/guides/skill-pack-authoring`, `/features/conversations`, `/configuration/skills`, `/features/convoys`. The new link in row 23 also resolves (`cli/skills-commands.mdx:83` "## pan skills add"). + +#### Frontmatter +- title: change to "Skills: bundled workflows, pan sync and on/off overrides" (sidebarTitle "Skills System") +- description: change to "How Overdeck skills work: reusable SKILL.md workflows that pan sync installs for Claude Code, Codex and Pi, and how to turn each one on or off." (143 chars). The current "for every supported harness" is wrong. + +#### Help section +- no + +#### Follow-ups +- The screenshot `/images/dashboard/skills-light.png` / `skills-dark.png` and its alt text show the old per-harness columns page. Retake it and rewrite the alt. +- `sync-sources/skills/pan-code-review/SKILL.md:162` dispatches `subagent_type: 'code-review-correctness'` (and `code-review-synthesis` at :209), which are no longer shipped. The skill is broken; fix or retire it. Its table row (line 84) is kept because the skill exists. +- The comment at `src/lib/skill-overrides/resolve.ts:33` "set at creation only" has been stale since PAN-5465. +- The comment at `src/lib/workspaces/item-worktree.ts:6` contradicts `src/cli/commands/spawn.ts:154`: every non-`--shared` spawn gets an item worktree. + +### features/swarm.mdx + +Before: 49 lines, 0 dash lines, title "Swarm: parallel workers on one issue with the foreman", description 125 chars. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| 1 | Ordinarily, a worker runs in its own item worktree | A `pan spawn` worker runs in its own item worktree | `src/cli/commands/spawn.ts:154` "const cwd = options.shared" (otherwise `createItemWorktree`). Only `pan spawn` and the `pan worker run` library call `createItemWorktree`; no code puts in-harness subagents in `.swarm/<item>/`. | +| 2 | `--steal` overrides this, for the foreman or an operator only. | `--steal` overrides this. It is meant for the foreman or an operator; nothing checks who passes it. | `src/cli/commands/task.ts:277` "(foreman/operator override)" is help text only. `grep -n "steal" src/cli/commands/task.ts` shows lines 122, 133, 150, 156 and 277, with no caller check. Compare `src/cli/commands/spawn.ts:104` "if (options.shared && env.OVERDECK_ITEM_ID) {" | +| 3 | at least two items are slot-eligible, each one has a `files_scope`, and | at least two items are slot-eligible (readiness `ready`, a non-empty `files_scope` whose `files_scope_confidence` is not `low`, and at least one `verify_commands` and one `expected_outputs` entry), and | `src/lib/xbrief/swarm-readiness.ts:115` "return item.metadata?.readiness === 'ready'" ; `:117` "(item.metadata.verify_commands?.length ?? 0) > 0" ; `src/cli/commands/swarm.ts:932` "swarm dispatch requires at least 2" | +| 4 | it prints that the foreman owns dispatch. | it prints that the foreman owns dispatch. It refuses a plan that is not eligible and lists the reasons. When the effective swarm mode is Off, it first stores `swarm.policy.mode=always` for that issue, so the foreman stays managed. | `src/cli/commands/swarm.ts:183` "is not swarm eligible:" ; `:203` "Persisted swarm.policy.mode=always for ${issue}" | +| 5 | "Advance waves automatically". | "Advance waves automatically" (defaults: Off, 3 slots with a range of 1 to 12, advance on). | `src/lib/config-yaml/defaults.ts:42` "swarm: { mode: 'off', maxSlots: 3, autoAdvance: true }," ; `src/dashboard/frontend/src/components/Settings/sections/SwarmSettingsSection.tsx:11` "min={1} max={12}" | +| 6 | A project's own "Automatic swarming" select (Inherit, Off, Auto, Always) | A project's own "Automatic swarming" select (Inherit global, Off, Auto, Always) | `src/dashboard/frontend/src/components/CommandDeck/ProjectSettingsDisclosure.tsx:524` '<option value="">Inherit global</option>' | + +#### Verified, keep +- Item worktree path, branch and reuse: `src/lib/workspaces/item-worktree.ts:23` "const path = join(workspacePath, '.swarm', itemId);" ; `:24` "if (existsSync(path)) return path;" ; `:30` "const itemBranch = `${featureBranch}-${itemId}`;" +- `--shared`: `src/cli/commands/spawn.ts:208` "Run the worker in the issue workspace instead of an item worktree (foreman/operator only; serial use)" +- Claim refusals, including the `low` confidence rule: `src/lib/xbrief/claim-check.ts:117` "targetItem.metadata?.files_scope_confidence === 'low' ||" ; `:96` "if (holderLiveness !== 'dead') {" +- Who can message a worker: `src/lib/terminal-backends/prompt-guard.ts:172` "only that issue's work pane, the worker's parent, or an operator conversation may." +- Eligibility needs a dispatchable slot-eligible item: `swarm-readiness.ts` "some(item => item.slotEligible && dispatchableIds.has(item.id))" +- Slot branch and worktree: `src/lib/agents/spawn-prep.ts:181` "branch: options.slotBranch ?? `feature/${issueLower}-slot-${slotIndex}`," +- `pan swarm <id>` does not dispatch: `src/cli/commands/swarm.ts:209` "The foreman owns dispatch; this command does not dispatch slot work." +- Subcommands: `src/cli/commands/swarm.ts:808-881` +- Settings → Swarming labels: `SwarmSettingsSection.tsx:7`, `:10-12` ; `settingsPageConstants.ts:71` +- Prompt-only claims, kept as written and not verifiable against code: the foreman's linear-chain and wave dispatch rule (lines 7, 13), subagent vs `pan spawn` pane (line 17), and the commit, hand-back and integration flow (line 25). Their source is `roles/work.md` and the pan-foreman skill. `roles/work.md:56` agrees on the `Item: <id>.acN` lines. + +#### Labels needed +- None. Row 5 adds that the slot swarm defaults to Off. + +#### Links +- all 2 internal links resolve (`cli/pipeline-commands.mdx:313` "## pan swarm", `:340` "## pan spawn") + +#### Frontmatter +- title: keep +- description: keep (125 chars) + +#### Help section +- yes, "## Get help" (lines 47-49), with both links present + +#### Follow-ups +- Possible bug, not verified: `swarmCommand` (`loadSwarmPlan` in `src/cli/commands/swarm.ts`) analyzes the main-side spec without continue-file item statuses. The Deacon applies them (`src/lib/cloister/deacon-swarm.ts:308` "applyItemStatuses(spec.document, itemStatuses)"). If so, `pan swarm <id>` may still treat a finished blocker as unfinished. + +### features/safe-shutdown.mdx + +Before: 85 lines, 0 dash lines, title "Safe shutdown", description 52 chars. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| 1 | A plain reboot gives every session 5 seconds to exit and then kills it, wherever it is. | A plain reboot stops every session wherever it is: systemd sends each process SIGTERM, then SIGKILL once its stop timeout passes. | `git grep -n "TimeoutStopSec" -- 'src/**'`: no match. Overdeck sets no stop timeout; the 5 s was one host's `user@.service.d` setting. The Herdr unit has no timeout: `src/lib/herdr-setup/service.ts:87` "'OOMPolicy=continue'," | +| 2 | `pan down` stops the dashboard and its services but leaves every agent running. | `pan down` stops the dashboard, its services and any review sessions, but leaves work agents and conversations running. | `src/cli/commands/down.ts:2` "`pan down`: stop smee, the supervisor, the dashboard, review sessions," ; `:88` "const { killed, failed } = await killAllReviewSessions();" | +| 3 | pan shutdown --cancel # cancel a running drain | Keep the line and add after it: `pan shutdown --no-wait # start the drain and return without following it` | `src/cli/commands/dashboard-lifecycle-commands.ts:114` ".option('--no-wait', 'Start the drain and exit without following it')" | +| 4 | `pan shutdown` needs the dashboard. If the dashboard is not running, start it with `pan up` first. | `pan shutdown` needs the dashboard. If the dashboard is not running, start it with `pan up` first. It also refuses to start while a `pan reload` or `pan restart` is in progress. | `src/dashboard/server/routes/shutdown.ts:118` "A pan reload or pan restart is in progress (pid ${result.pid}). Wait for it to finish, then shut down." | + +#### Verified, keep +- Flags and deadline (default 120, range 10 to 3600): `dashboard-lifecycle-commands.ts:108-112` ; `src/dashboard/server/routes/shutdown.ts:42` "const SHUTDOWN_DEFAULT_DEADLINE_SECONDS = 120;" ; `src/cli/commands/shutdown.ts:54` "const MIN_DEADLINE_SECONDS = 10;" +- Shutdown record and its refusal text: `src/lib/shutdown/drain-record.ts:42` "return join(getOverdeckHome(), 'shutdown.json');" ; `:76` "'Overdeck is shutting down (pan shutdown). New work is refused." +- Admissions closed while the record exists: + - launches: `terminal-backends/launch.ts` assertNotShuttingDown + - conversation create, resume and message: `src/lib/shutdown/refusal.ts` + - Deacon: `control-settings.ts:150` + - auto-merge: `auto-merge-executor.ts:187` + - merge train: `merge-train.ts:35` + - backlog sequencer: `backlog-auto-trigger.ts:22` + - `pan reload`: `src/cli/commands/reload.ts:161` +- Pre-tool hook deny: `sync-sources/hooks/pre-tool-hook:22` "Overdeck is shutting down (pan shutdown). Do not start any tool." It is installed to `~/.overdeck/bin` (`src/lib/paths.ts:33`). +- Turn-boundary rule: `src/lib/agents/liveness.ts:102` +- Server writers and the force semantics: `services/shutdown/writers.ts` header. The verify step warns but never blocks: `verify.ts` header "It reports and never blocks". +- Final stage and reboot: `src/cli/commands/shutdown.ts:159` "await deps.execFile('systemctl', ['reboot'], { timeout: 30_000 });" +- Called from inside a session, `pan shutdown` returns at once: `src/cli/commands/shutdown.ts:245` +- Banner: `ShutdownBanner.tsx:67`, `:165`, `:174`, `:200`, `:233` +- Entry points: + - Agents menu: `AgentsMenu.tsx:210`, `:221` + - Health popover, System controls: `AppChrome.tsx:221` + - Command palette: `CommandPalette.tsx:523` + - Confirmation dialog with "Reboot when done": `ShutdownDialog.tsx:172` +- Resume offer: `useDecisions.ts:385` ; `services/shutdown/end.ts:35` "s.kind === 'agent' || s.wasWorking" +- A dashboard restart mid-drain ends as a cancel: `services/shutdown/boot.ts` +- Reboot guard: `reboot-guard.ts:65` "`--why=Overdeck has ${n} agents running. Use Shut down Overdeck first.`," ; `:24` "Linux only; a no-op elsewhere." + +#### Labels needed +- None. + +#### Links +- all 1 internal link resolves (`/guides/operating`) + +#### Frontmatter +- title: change to "Safe shutdown: drain agents with pan shutdown before a reboot" (sidebarTitle "Safe shutdown") +- description: keep (52 chars) + +#### Help section +- no + +#### Follow-ups +- The body repeats the title as an H1 (`# Safe shutdown`, line 6). This is stylistic and not changed here. + +## Appendix F: workspaces.mdx (WI-F1, WI-F2) + +Research pass output, base `2007e9a4d3c`, rows verified by the planner (anchor unique, evidence greps). + +### features/workspaces.mdx + +Before: 553 lines, 0 dash lines, title "Workspaces: issue worktrees, scratch work and the main checkout", description 139 chars. + +Every anchor below printed 1 with `grep -c -F`. Every evidence quote was checked with `grep -n -F`. Multi-line replacements are in "Replacement blocks" after the table. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| 1 | `- Has its own feature branch (e.g., `feature/min-123-add-login`)` | `- Has its own feature branch, named `feature/<issue>` (e.g., `feature/min-123`)` | `src/cli/commands/workspace-create.ts:48` "const branchName = `feature/${normalizedId}`;" | +| 2 | `- Is located at `{project}/workspaces/{issue-id}/`` | `- Is located at `{project}/workspaces/feature-<issue>/` (lowercase, e.g. `workspaces/feature-min-123/`)` | `src/cli/commands/workspace-create.ts:49` "const folderName = `feature-${normalizedId}`;" | +| 3 | `│ ├── .git # Symlink to ../.git` | `│ ├── .git # File pointing at the shared ../../.git` | `sync-sources/hooks/git-hooks/post-checkout:27` "worktrees have .git as a file, not directory" | +| 4 | `│ ├── .planning/ # Planning artifacts (ephemeral)` | `│ ├── .overdeck/ # Workspace runtime state (plan copy, continue file, pipeline journal)` | `src/lib/pan-dir/types.ts:11` "export const WORKSPACE_RUNTIME_DIRNAME = '.overdeck'"; `src/cli/commands/release.ts:441` "PAN-967 retired the `.planning/` directory" | +| 5 | ` ├── .planning/` | ` ├── .overdeck/` | same as row 4 | +| 6 | `├── .planning/ # Planning artifacts (ephemeral)` | Replace lines 97-102 (this line through `│ └── output-*.jsonl # Backup of previous rounds`) with Block 6 | `src/lib/pan-dir/continue.ts:19` "const panDir = join(workspacePath, WORKSPACE_RUNTIME_DIRNAME)"; `src/lib/cloister/pipeline-journal.ts:60` "const JOURNAL_RELATIVE_PATH = join('.overdeck', 'pipeline.jsonl');" | +| 7 | `### Planning Artifacts` | Replace section (lines 109-125, through `3. **Beads tasks** - Sub-tasks ARE persisted (beads uses label-based isolation)`) with Block 7. No inbound links (`git grep -n "workspaces#planning-artifacts"`: no match) | `src/lib/pan-dir/paths.ts:4` "Planning artifacts live in `.pan/` inside the repo they describe."; `src/lib/pan-dir/specs.ts:146` "PAN-3917: the spec is a tracked file in the plan home."; `src/lib/xbrief/continue-state.ts:184` "Structured replacement for STATE.md."; `src/cli/commands/task.ts:271` "Read and update xBRIEF item state for one issue"; beads: `git grep -n "execFile.*'bd'" -- src` no match | +| 8 | `3. Runs `docker compose -p "{project}-feature-{issue}" up -d --build`` | `3. Runs `docker compose -f <compose file> up -d --build` without `-p`, so the compose file names the stack` | `src/cli/commands/workspace-create.ts:357` "Don't pass -p: the compose file's `name:` field is the authority"; `src/lib/workspace-manager/create.ts:679` "docker compose -f \"${composePath}\" up -d --build" | +| 9 | `2. Looks for docker-compose files in workspace` | `2. Looks for a compose file in the workspace root or `.devcontainer/`, and regenerates `.devcontainer/` from the project template when none exists` | `src/cli/commands/workspace-create.ts:341` "it from the project template before looking for a compose file." | +| 10 | `Each workspace gets a unique Docker Compose project name:` | `Each workspace's Docker Compose project name is the one its compose file declares in its top-level `name:` field, or `COMPOSE_PROJECT_NAME` in the workspace's `dev` script. With neither, Overdeck uses `overdeck-feature-<issue>`.` | `src/lib/workspace/stack-health.ts:6` "A workspace's compose project is whatever it DECLARES"; `:153` "const fallback = `overdeck-${featureFolder}`;" | +| 11 | `- Format: `{project-name}-feature-{issue-id}`` | DELETE line | same as row 10 | +| 12 | `- Example: `mind-your-now-feature-min-123`` | `- Example: a compose file with `name: myn-feature-min-123`` | `src/lib/workspace/stack-health.ts:12` "workspace's real `myn-feature-*` one" | +| 13 | `- Container names: `{project}-{service}-1`` | `- Container names: `{compose-project}-{service}-1`` | `src/cli/commands/workspace-create.ts:148` "const containerName = `${composeProject}-${service.name}-1`;" | +| 14 | `- **Default:** Enabled (containers start automatically)` | `- **Default:** Off (planning agents don't need Docker)` | `src/dashboard/frontend/src/components/PlanDialog.tsx:83` "return stored !== null ? stored === 'true' : false;" | +| 15 | `2. Checks out feature branch `feature/min-123-*`` | `2. Creates and checks out the branch `feature/min-123`` | `workspace-create.ts:48` (row 1) | +| 16 | `- **Planning agents** - Explore codebase, create STATE.md and beads tasks` | `- **Planning agents** - Explore the codebase and write the PRD draft and the xBRIEF plan` | `src/lib/pan-dir/drafts.ts:101` "PAN-3917: the draft is a tracked file in the plan home"; `specs.ts:146` | +| 17 | `- **Specialists** - Review code, run tests, merge changes` | `- **Review and test agents** - Review the code and run the tests` | `src/lib/agents/role.ts:6` "export type Role = 'plan' | 'work' | 'review' | 'test'"; `roles/review.md:237` "Review never merges." | +| 18 | `# Destroy workspace (safe - checks for uncommitted changes)` | `# Destroy workspace (uncommitted changes are discarded, so commit and push first)` | `src/lib/worktree.ts:109` "gitRun(['worktree', 'remove', worktreePath, '--force'], repoPath)"; `src/lib/workspace-manager/worktree-ops.ts:181` "await execFileAsync('git', ['worktree', 'remove', targetPath, '--force'], { cwd: repoPath })" | +| 19 | `# Force destroy (even with uncommitted changes)` | DELETE this line, the next line (`pan workspace destroy MIN-123 --force`) and the blank line before it (lines 198-200) | `src/cli/commands/workspace-list.ts:519` "if (!options.force) {" is the only read of `options.force` in `destroyCommand` (`grep -n "force" src/cli/commands/workspace-list.ts`: lines 326, 369, 519, 520 only) | +| 20 | `1. Stops and removes Docker containers (if any)` | Replace lines 204-208 (through `5. Unregisters from Overdeck`) with Block 20 | `src/lib/workspace-manager/remove.ts:48` "const dockerResult = await stopWorkspaceDocker(workspacePath, featureName);"; `workspace-list.ts:337` "await execFileAsync('git', ['branch', '-D', branch], { cwd: repoPath });"; `:367` "await deleteWorkspace(row.id);"; `src/cli/commands/workspace.ts:72` "Destroy workspace (all shapes by default: base, strike, and slot worktrees)" | +| 21 | `- **Specialists** (review-agent, test-agent) need a stable reference point` | `- **Review and test agents** need a stable reference point` | `role.ts:6` | +| 22 | `The dashboard prevents starting a work agent` | Replace lines 383-388 (this line through `3. **Or kill manually** - `pan kill planning-<issue>``) with Block 22; keep the heading | `git grep -n -i "planning agent is still running" -- src`: no match; `src/lib/overdeck/planning-sessions.ts:294` "Cannot start planning: work agent already running for"; `src/dashboard/server/routes/agents/spawn-issue.ts:387` "Work agents require a finalized plan."; `src/dashboard/frontend/src/lib/issueActions.ts:617` "label: 'Accept plan'"; `PlanDialog.tsx:736` "'Abort Planning'"; `src/cli/index.ts:344` ".command('kill <id>')" | +| 23 | `### Specialist Agent Safeguards` | Replace lines 390-400 (heading through `- **Git hooks** - Auto-revert if checkout detected in tmux sessions`) with Block 23. No inbound links (`git grep -n "specialist-agent-safeguards"`: no match) | `src/lib/agents/spawn.ts:141` "const workspace = options.workspace ?? defaultRunWorkspace(issueId);"; `src/lib/cloister/prompts/work.md:56` "NEVER run `git checkout <other-branch>` inside your workspace"; `grep -rn -i "workspace create" src/lib/cloister/prompts roles sync-sources/agents`: no match; `post-checkout:73` "if [ \"$OVERDECK_AGENT\" = \"1\" ] || [ -n \"$OVERDECK_AGENT_ID\" ]; then" | +| 24 | `- Follow convention: `feature/{issue-id}-{description}`` | `- Branches are named `feature/<issue>`, lowercase` | `workspace-create.ts:47` "const normalizedId = issueId.toLowerCase()"; `:48` | +| 25 | `- Example: `feature/min-123-add-login`` | `- Example: `feature/min-123`` | same as row 24 | +| 26 | `- `.planning/` is ephemeral - don't rely on it for cross-machine work` | `- The PRD draft and xBRIEF plan live under `.pan/` and are committed on the feature branch, so they move with the branch` | `specs.ts:146` | +| 27 | `- STATE.md and beads persist the important context` | `- Item progress is kept in the continue file and updated with `pan task`` | `continue-state.ts:184`; `task.ts:271` | +| 28 | `- Feature PRD goes to `docs/prds/active/` for permanent storage` | `- The PRD is `.pan/drafts/<issue>.md`` | `src/lib/pan-dir/drafts.ts:29` "Canonical draft filename is lowercase (`drafts/pan-123.md`)."; `git grep -n "prds/active" -- src` returns only a legacy archive comment (`archive-planning.ts:8`) and a reset-time copy (`workflows.ts:489`); nothing writes `<issue>-plan.md` | +| 29 | `- **On-demand provisioning**: machines spin up per workspace and shut down after merge.` | `- **On-demand provisioning**: machines spin up per workspace and are destroyed when the agent finishes and its branch is handed to review.` | `src/lib/remote/remote-completion.ts:20` "6. destroys the fly machine, marks the remote agent state stopped, and" | +| 30 | `Remote workspaces are created through the dashboard planning dialog or CLI:` | `Remote workspaces are created from the planning dialog (**Workspace Location**: **Remote (Fly.io)**) or the CLI:` | `PlanDialog.tsx:777` "Workspace Location"; `:805` "Remote (Fly.io)" | +| 31 | `Agents connect to the remote environment via the same tmux-based interface used for local workspaces.` | `The agent runs in a tmux session on the machine.` | `src/lib/remote/remote-agents.ts:5` "Agents run in tmux sessions for persistence and monitoring." (local agents default to Herdr) | +| 32 | `docker compose -p mind-your-now-feature-min-123 down` | `docker compose -p myn-feature-min-123 down # the name: from the workspace's compose file` | row 10 | +| 33 | `# Destroy completed workspaces` | `# Show merged branches still on disk, with sizes, then destroy them`, and insert the new line `pan workspace list --stale` directly after it | `src/cli/commands/workspace.ts:67` "Show reclaim candidates: merged branches still on disk, with sizes" | +| 34 | `The dashboard's Resources page breaks down system memory` | `The dashboard's Resources page (experimental: turn on **Settings → Experimental → Experimental features**) breaks down system memory` | `src/dashboard/frontend/src/lib/experimentalFeatures.ts:7` "'resources',"; `src/dashboard/frontend/src/components/Settings/sections/ExperimentalSection.tsx:76` "Experimental features" | +| 35 | `- [Planning](/features/planning) - Planning an issue before work starts` | Use as a locator only: insert above `## Related Guides` (after the Troubleshooting Resources image): `Still stuck? Ask in [Discord](https://discord.gg/ZpHE2ZTv5P) or open an issue on [GitHub](https://github.com/eltmon/overdeck/issues).` | brief rule 9 | + +#### Replacement blocks + +Block 6 (replaces lines 97-102): +├── .overdeck/ # Workspace runtime state +│ ├── spec.vbrief.json # Working copy of the xBRIEF plan +│ ├── continue.json # Item progress +│ ├── sessions.jsonl # Agent sessions in this workspace +│ └── pipeline.jsonl # Pipeline journal +├── .pan/ # Committed planning artifacts (drafts/, specs/, continues/) + +Block 7 (replaces lines 109-125): +#### Planning artifacts + +Planning writes its artifacts under `.pan/` in the project repo and commits them on the feature branch, so they travel with the branch. A polyrepo project can name one sub-repo as the plan home with `pan_records.repo` in `projects.yaml`. + +- `.pan/drafts/<issue>.md`: the PRD draft +- `.pan/specs/`: the xBRIEF plan +- `.pan/continues/`: the continue files that record item progress + +The workspace's `.overdeck/` directory holds runtime state: a working copy of the plan (`spec.vbrief.json`), `continue.json`, `sessions.jsonl`, `context.md`, `feedback/` and the pipeline journal `pipeline.jsonl`. Work items are xBRIEF items; agents claim and complete them with `pan task`. +(Evidence: `src/lib/pan-dir/paths.ts:8` "`pan_records.repo` in `projects.yaml` (MYN uses `infra`)"; `continue.ts:22-26` specPath/continuePath/sessionsPath/feedbackDir/contextPath.) + +Block 20 (replaces lines 204-208): +1. Stops the workspace's Docker stack (projects with a `workspace` block in `projects.yaml`) +2. Removes every worktree for the issue (base, strike and slot; limit with `--shape`) with `git worktree remove --force`, so uncommitted changes are lost +3. Deletes the local feature branch +4. Removes the workspace's record; `--purge-memory` also deletes its memory +(Docker stop runs only in the `workspace-list.ts:413` "if (projectConfig?.workspace) {" branch.) + +Block 22 (replaces lines 383-388; keep the `### Planning vs Work Agent Safeguard` heading): +Planning refuses to start while a work agent (`agent-<issue>`) is running for the issue ("Cannot start planning: work agent already running"). A work agent refuses to start until the issue has a finalized xBRIEF plan with items. + +To move from planning to work: +1. **Accept the plan** - the **Accept plan** action finalizes it (`pan plan finalize`) +2. **Or abort** - **Abort Planning** in the planning dialog returns the issue to Todo and keeps the workspace +3. **Or stop the planning agent** - `pan kill planning-<issue>` +(Evidence: `PlanDialog.tsx:709` "Return issue to Todo (keeps workspace)"; `issueActions.ts:617` "panVerb: 'plan finalize'"; `spawn-issue.ts:423` "Plan exists but contains no items.") + +Block 23 (replaces lines 390-400): +#### Agent safeguards + +Planning, work, review and test agents start with the issue workspace as their working directory, never the main project directory. The work prompt tells the agent never to check out another branch in its workspace. The post-checkout hook auto-reverts a checkout in the main project directory when it runs inside an Overdeck agent (`OVERDECK_AGENT=1` or `OVERDECK_AGENT_ID` set), a planning session, or a tmux session named `agent-*`, `planning-*` or `specialist-*`. +(Evidence: `post-checkout:78` "if [ \"$OVERDECK_PLANNING\" = \"1\" ]"; `:86` "agent-*|planning-*|specialist-*)"; `src/dashboard/server/routes/misc/planning.ts:391` "OVERDECK_AGENT_ID: sessionName,".) + +#### Verified, keep +- `pan workspace create <issueId>` with `--docker`, `--remote`, `--local`, `--dry-run` — `src/cli/commands/workspace.ts:21,27,28` +- `pan workspace destroy --purge-memory` (line 268) — `workspace.ts:76` +- `pan workspace new` flags `--isolated`, `--parent-branch`, `--target-path`, `--origin`, `--dry-run`, `--project` — `workspace.ts:80-87` +- `main/get/activate/archive/relocate`; archive refuses main; relocate refuses issue workspaces and needs `--force` for main — `workspace.ts:108` "refuses kind=main", `:113` "refuses kind=issue; kind=main requires --force" +- `list --kind`, `--archived` only with `--kind` — `workspace.ts:66` +- Issue workspace record registered — `src/lib/workspace-manager/create.ts:175` "kind: 'issue',"; boot backfill `src/lib/workspaces/rebuild.ts:68` +- "Start Docker containers" checkbox exists and is remembered in localStorage — `PlanDialog.tsx:839`, `:837` +- Hook installed on `pan project add` and `pan sync`; warns humans; `OVERDECK_AUTO_REVERT_CHECKOUT=1` opt-in — `src/lib/project-registration.ts:85`, `src/cli/commands/sync.ts:660`, `post-checkout:100` +- `pan admin remote init/setup/status/resources` — `src/cli/commands/admin/index.ts:86` "registerRemoteCommands(admin);" +- `pan start --remote` — `src/cli/commands/start-register.ts:19` +- `REMOTE_DONE` reaped about every minute — `remote-completion.ts:6`, `src/lib/cloister/deacon-lite.ts:645` "DEACON_LITE_INTERVAL_MS = 60_000" +- VMs stop after 300 s without heartbeat — `src/lib/remote/fly-machine-loops.ts:11` +- No SSH keys on VMs; HTTPS with `gh auth token` — `src/lib/remote-workspace.ts:200`, `src/lib/remote/fly-provider.ts:547` +- Close-out defaults (`remove_workspace` on, `delete_feature_branch` off, `auto` keys inert) — `src/lib/cloister/config.ts:537-539` +- UI labels: Clean up now (`CloseOutSection.tsx:123`), Resume Deacon (`DeaconPauseToggle.tsx:104`), Close Out (`CloseOutIssueButton.tsx:80`), "Untitled workspace" (`SmartWorkspaceField.tsx:118`), "Open <ID> and start work" and "Start from branch" (`SmartWorkspaceField.tsx:37-38`), Start workspace (`NewWorkspacePage.tsx:470`), Shared directory / Isolated worktree (`NewWorkspacePage.tsx:305`), "New workspace in <project>…" (`ProjectSwitcher.tsx:247`), "New workspace…" (`CommandPalette.tsx:465`), Favorite/Unfavorite (`WorkspaceView.tsx:275`), Relocate (`WorkspaceView.tsx:244`), Main checkout (`HomeActions.tsx:226`), "Add a project first." (`src/lib/workspaces/create.ts:207`) + +#### Labels needed (experimental / early / testing) +- Resources page (line 541) is experimental. Row 34. +- The Board is not experimental. The Fly section already says remote must be enabled (line 498). + +#### Links +- All 6 internal links resolve, including `/configuration/memory#workspace-observation-memory` (`configuration/memory.mdx:265`). +- Inbound anchors (`#remote-workspaces-on-fly`, `#scratch-and-main-workspaces-from-the-cli`, `#cleaning-up-after-close-out`) are unchanged. +- The headings renamed by rows 7 and 23 have no inbound or in-page links. `#workspace-lifecycle` (in-page link at line 272) is unchanged. + +#### Frontmatter +- title: keep +- description: keep (139 chars) + +#### Help section +- yes: `## Troubleshooting` (lines 504-547). It has no Discord or GitHub links; row 35 adds them. + +#### Screenshot alt text +- Current: "Kanban board: issue columns with cost badges, agent status dots, and workspace controls, one card per issue/workspace". +- Both PNGs show the Board: Backlog/Plan/Work/Review/Done columns under Cycle and Projects filters and a Needs you strip. Cards show the id, title, labels, TASKS progress, agent activity dots with model and time, and actions (Resume/Start, WORK RUNNING, Message agent, Finish work and start review). There are no per-card cost badges and no workspace controls. Backlog groups issues by project. +- The pair does not match. Dark has a Cost today/Agents/Stuck strip and 9 Needs you cards. Light has no cost strip, Needs you 0, and Ready to start 18 with Plan Ready cards. +- Proposed alt: `Board view: Backlog, Plan, Work, Review and Done columns of issue cards showing task progress, agent activity and actions such as Start work, under cycle and project filters and a Needs you strip` + +#### Follow-ups +- Bug: `pan workspace destroy --force` does nothing. Removal always passes `--force` (`src/lib/worktree.ts:109`, `worktree-ops.ts:181`) and never checks for uncommitted changes. `options.force` only prints a tip (`workspace-list.ts:519-520`, `workspace-remote.ts:219`). +- Bug: `workspace-create.ts:146` builds container hints from `basename(projectConfig.path)-feature-<id>`. That disagrees with the declared-name logic in `stack-health.ts:151`. +- Orphaned prompt: `src/lib/cloister/prompts/merge.md` runs `git checkout {{TARGET_BRANCH}}` in the project path, but nothing in the code supplies `TARGET_BRANCH` (`git grep -ln "TARGET_BRANCH" -- src` returns only merge.md). +- Recapture `board-light.png` and `board-dark.png` as a matched pair. +- `cli/workspace-commands.mdx:176` repeats the hook text. Out of scope here. +- Use Cases (lines 419-430) create issue workspaces for issue ids that don't exist (`MIN-123-alternative`, `MIN-999-hotfix`). `pan workspace new --isolated` is the scratch path. Stylistic, so not changed. +- Unverified: line 490 "dependencies pre-installed"; line 215 More menu vs the `ActionDock.tsx:68` **Main checkout** button. + +## Appendix G: specialists.mdx, convoys.mdx, cloister.mdx, merge-batches.mdx (WI-G1 to WI-G4) + +Research pass output, base `2007e9a4d3c`, rows verified by the planner (anchor unique, evidence greps). + +### features/specialists.mdx + +Before: 55 lines, 0 dash lines, title "Review and test agents: checking an agent's work", description 149 chars. + +#### Change table +| # | Grep anchor (EXACT current text, copy-paste, must match the page exactly once; keep it short, one line, no line breaks) | Change (exact replacement text, or "DELETE section `## Heading` (lines x-y)", or "DELETE sentence") | Evidence (`path/file.ts:LINE` + a short exact quote that greps in that file; for an absence, the grep command run and "no match") | +|---|---|---|---| +| 1 | `description: "After pan done, a review agent and a test agent` | Replace the whole description line with: `description: "After pan done, a review agent checks the pull request and its checks must pass. Then you click Merge, or auto-merge or the merge train lands it."` (145 chars) | No producer of `review.approved`: every `notifyPipeline(` call site (`git grep -n "notifyPipeline(" -- src`) passes `pipeline.entry`, `task_queued`, `reviewer_*` or `coordinator_*`, except `src/dashboard/server/routes/workspaces/internal-pipeline-notify.ts:100` "notifyPipeline({ type, issueId });", which only re-emits a POSTed type, and no caller POSTs `review.approved`. `git grep -n "transitionTo(" -- src` shows no transition to `testing`. Merge paths: `src/lib/cloister/merge-route.ts:75` " if (!input.trainOn) return 'per-pr';" | +| 2 | `Two more agents check it before it can merge: a **review agent** and a **test agent**. The docs call them specialists.` | `A **review agent** checks it before it can merge, and a **test agent** can run its tests and browser UAT. The docs call them specialists.` | As row 1; existing test-agent start: `src/dashboard/server/routes/workspaces/review-pipeline.ts:644` "PR approved but checks" | +| 3 | `3. **Test.** A test agent runs the project` | Replace the whole item 3 (line 15, from this anchor to `There is no separate UAT agent.`) with: `3. **Test.** Nothing starts a test agent automatically after the review approves ([#5537](https://github.com/eltmon/overdeck/issues/5537)). In a project that runs its tests on CI (\`verification.tests: ci\`, or a GitHub Actions workflow that runs a test job on pull requests), the CI test job must pass on the PR head before the PR can merge. Running \`pan review request\` on a PR that is approved at its head but whose checks are not green starts a test agent: it runs the project's test commands and, when the acceptance criteria describe UI behavior, drives a browser with Playwright and records a separate UAT verdict. There is no separate UAT agent.` | `src/lib/cloister/service-reactive.ts:377` " return { issueId, state: 'testing' };" is reachable only from `review.approved` (row 1); `src/lib/cloister/pr-facts.ts:966` "no CI test job reported on PR HEAD"; `src/lib/cloister/verification-tests-mode.ts:297` " * \`verification.tests\` key, else \`ci\` when a GitHub Actions workflow runs a"; `src/dashboard/server/routes/workspaces/review-pipeline.ts:644` "PR approved but checks" | +| 4 | `4. **Merge.** When the PR is approved` | Replace the whole item 4 (line 16, from this anchor to `No agent merges code.`) with: `4. **Merge.** When the PR is approved at its head commit, its checks are green and GitHub says it can merge, the issue is ready. Whether you click depends on whether the issue is held for UAT: its \`hold-for-uat\` or \`auto-merge\` label, else the project's \`auto_merge_default\`, else the global **Require UAT** switch on the Flywheel page header, which is on by default. A held issue waits for you to click **Merge** on the issue or on the Awaiting Merge page. In a GitHub single-repo project, an issue that is not held merges on its own five minutes after it is ready, or with the next batch while the [merge train](/features/merge-batches) is on; GitLab and polyrepo projects never merge on their own. To merge, the server merges a clean, up-to-date PR as it is; otherwise it rebases the branch onto \`main\` itself, and when that rebase fails during a merge you started, it asks the work agent to rebase and push. Overdeck then squash-merges the PR. No agent merges it.` | `src/lib/overdeck/control-settings.ts:263` "return val !== 'false'; // defaults to true if unset"; `src/lib/cloister/auto-merge-policy.ts:8` " * 3. global \`flywheel.require_uat_before_merge\`"; `src/dashboard/frontend/src/pages/FlywheelPage.tsx:182` 'label="Require UAT"'; `src/lib/cloister/auto-merge-config.ts:1` "export const AUTO_MERGE_COOLDOWN_MS = 300_000;"; `src/dashboard/server/services/auto-merge-scheduler.ts:40` " * GitLab projects are skipped with a log line: their MRs are not listed here."; `src/dashboard/server/services/merge-path-owner.ts:108` " if (config?.workspace?.type === 'polyrepo') return false;"; `src/dashboard/server/routes/workspaces/merge-ops.ts:878` "PR is CLEAN — merging directly without rebase"; `src/dashboard/server/routes/workspaces/merge-strike.ts:630` "escalating to the work agent for"; `merge-strike.ts:635` "an automatic merge is rebased by the server only"; `src/lib/forge.ts:407` "const method = input.method \|\| 'squash';" | + +#### Verified, keep +- Default review mode is `quick`; `roles.review.mode: full` runs the convoy — `src/lib/config-yaml/roles.ts:45` "mode: 'quick',"; `src/lib/cloister/review-agent.ts:924` "return configMode === 'full' \|\| configMode === 'none' ? configMode : 'quick';" +- Re-review cap 25, HTTP 429, count kept in memory, so it resets on restart — `src/dashboard/server/routes/workspaces/review-pipeline.ts:76` "const MAX_AUTO_REQUEUE = 25;"; same file "{ status: 429 }", "A human must click the Review button to continue." +- **Request review** in the issue menu — `src/dashboard/frontend/src/lib/issueActions.ts:621` "label: 'Request review'" +- `pan review request <id> -m` — `src/cli/commands/review-subcommands.ts:12` "-m, --message <text>" +- Awaiting Merge page — `src/dashboard/frontend/src/components/frame/navGroups.ts:32` "label: 'Awaiting Merge'" +- Line 28, "When a check fails": undelivered feedback raises Needs-you — `src/lib/cloister/feedback-target.ts:359` "Failed to announce needs-you"; CI test failure feedback — `src/lib/cloister/ci-failure-feedback.ts:666` "was not delivered". With row 3, "a failed test" still holds for a failed CI test job. +- Lines 36-38, agents stay warm and re-review reuses the reviewer — `src/lib/cloister/review-agent.ts:382` "warm-reusing for the new review cycle" +- `pan admin specialists list` — `src/cli/commands/specialists/index.ts:17` ".command('list')" +- `pan show` prints the journal — `src/cli/commands/show.ts:285` "readPipelineJournal(workspacePath)" +- Settings → Model Routing — `src/dashboard/frontend/src/components/Settings/settingsPageConstants.ts:64` "label: 'Model Routing'" +- Line 18 (auto-merge, merge batches) stays correct after row 4. + +#### Labels needed (experimental / early / testing) +- None. + +#### Links +- All 7 internal links resolve. + +#### Frontmatter +- title: keep +- description: change (row 1), 145 chars. + +#### Help section +- no + +#### Follow-ups (code bugs or out-of-scope doc problems; never fixed by this issue) +- #5537 is confirmed on base. Places that still promise the dispatch: the synthesis prompt line `src/lib/cloister/review-agent.ts:171` "'Reactive Cloister dispatches the test role after review passes." (a second copy is in the same file), `roles/review.md:240`, and the comment at `merge-ops.ts:1600-1602`. When #5537 lands, row 3 needs revising. + +--- + +### features/convoys.mdx + +Before: 329 lines, 0 dash lines, title "Review convoy", description 67 chars. + +#### Change table +| # | Grep anchor (EXACT current text, copy-paste, must match the page exactly once; keep it short, one line, no line breaks) | Change (exact replacement text, or "DELETE section `## Heading` (lines x-y)", or "DELETE sentence") | Evidence (`path/file.ts:LINE` + a short exact quote that greps in that file; for an absence, the grep command run and "no match") | +|---|---|---|---| +| 1 | `dashboard's Roles panel or in` | `Role Models panel of Settings → Model Routing, or in` | `src/dashboard/frontend/src/components/Settings/RolesPanel.tsx:457` "Role Models"; `src/dashboard/frontend/src/components/Settings/SettingsPage.tsx:520` "<RolesPanel />" (inside the Model Routing section) | +| 2 | `dashboard's Roles settings panel, or with` | `**Review mode** field of Settings → Model Routing → Role Models, or with` | `RolesPanel.tsx:759` "Review mode</span>" | +| 3 | `# Verdict: APPROVED \| CHANGES_REQUESTED \| FAILED` | Replace the fenced block (lines 148-158) with a ```` ```markdown ```` block holding these lines: `# Review <issueId>` / `## Verdict: APPROVED / CHANGES REQUESTED` / `## Context` / `## Blocking Findings` / `## Non-blocking Findings` / `## Coverage` / `## Verification` / `## Scope Note`. Then add after the block: `A synthesis report also names each lane's signal and report, including any lane that failed or timed out.` The template in `roles/review.md` reads `# Review — <issueId>`; the em dash is dropped here only because of the no-dash rule. | `roles/review.md:181` "## Blocking Findings" (report contract, lines 168-195, includes "## Non-blocking Findings", "## Coverage", "## Verification", "## Scope Note"); `roles/review.md:199` "Include the current convoy signal/output status"; the synthesis prompt defers to it at `src/lib/cloister/review-agent.ts:129` "follow roles/review.md exactly to"; `grep -rn "Convoy Notes" src roles` returns no match | +| 4 | `and its agents by phase (Ship, Review, Verifying), with a metric strip across` | Replace the sentence from "The Pipeline page groups every issue" to `activity feed on the right.` (lines 228-231) with: `The Pipeline page groups every issue and its agents by phase (Ship, Review, Work, Plan, Ready), with a metric strip across the top (Active issues, Work running, Review running, Ship, Spend). Its List, Board and Analytics buttons switch views.` | `src/dashboard/frontend/src/lib/pipeline-state.ts:105` "export const PIPELINE_BOARD_PHASES = ['ship', 'review', 'work', 'plan', 'ready']"; `src/dashboard/frontend/src/components/Pipeline/PipelineView.tsx:418` "eyebrow: 'Review running'"; `PipelineView.tsx:471` "(['List', 'Board', 'Analytics'] as const)"; `grep -n -i "activity\|feed" src/dashboard/frontend/src/components/Pipeline/PipelineView.tsx` returns no match | +| 5 | `alt="Pipeline page: a metric strip` | Replace the whole alt line (236) with: ` alt="Pipeline page: a metric strip showing Active issues, Work running, Review running, Ship, and Spend over issue rows grouped by phase (Ship, Review, Work), with phase and project filter chips above them."` | Screenshot (see "Screenshot alt text"); `PipelineView.tsx:418` | +| 6 | `When reviews run across several projects at once, the God View gives an` | Insert before it: `The God View is experimental: turn on Settings → Experimental → **Experimental features** to see it. ` | `src/dashboard/frontend/src/lib/experimentalFeatures.ts:14` " 'god-view'," | +| 7 | `## Related Guides` | Insert before it: `## Get help` + blank line + `Ask on [Discord](https://discord.gg/ZpHE2ZTv5P) or open an issue on [GitHub Issues](https://github.com/eltmon/overdeck/issues).` + blank line | Brief rule 9: the page has `## Troubleshooting` (line 287) and no help links | + +#### Verified, keep +- Four lanes and the parent `agent-<issue>-review` — `src/lib/cloister/review-agent.ts:99` "the four convoy reviewers (security, correctness, performance, requirements)"; `src/lib/cloister/review-convoy.ts:160` +- Lane role files exist: `roles/review-{security,correctness,performance,requirements}.md` +- File names: `synthesis.md`, and `review.md` for quick mode — `review-agent.ts:83-84` +- `roles.review.sub.<lane>.model` defaults — `src/lib/config-yaml/roles.ts:47` "security: { model: 'workhorse:expensive' }," +- Modes quick (default) / full / none — `roles.ts:45`; `src/lib/config-yaml/schema.ts:392` +- Verdict marker comment fallback — `src/lib/cloister/pr-facts.ts:194` "<!-- overdeck-verdict: ${verdict}" +- `pan review request -m`, `abort`, `restart --role/--model` — `src/cli/commands/review-subcommands.ts:12,22,27,29,30` +- Journal entry types — `src/lib/cloister/pipeline-journal.ts:35` +- Stall re-dispatch after 15 min, at most once an hour per issue — `src/lib/cloister/deacon-lite.ts:290-291` +- `GET /api/agents/:id/output` — `src/dashboard/server/routes/agents/conversation.ts:119` +- `pan status --json` has `alive` — `src/cli/commands/status.ts:120`; `pan show --json` has `pr` — `src/cli/commands/show.ts:294` "pr: issueState.pr," +- "Review never started" shows as a needs-you item — `src/dashboard/frontend/src/components/CommandDeck/ProjectTree/featureStateBadge.ts:59`; `src/lib/flywheel/board.ts:416` +- The Pipeline page itself is not experimental. + +#### Labels needed +- God View (lines 262-271), row 6. + +#### Links +- All 7 internal links resolve, including `#review-modes` and `/configuration/terminal-backend#reaching-an-agent-from-a-shell`. + +#### Frontmatter +- title: keep; description: keep (67 chars) + +#### Help section +- no (the Troubleshooting section has no links); row 7 adds them. + +#### Screenshot alt text +- I opened `images/dashboard/pipeline-light.png` and `pipeline-dark.png`; both show the same view. +- Metric strip: ACTIVE ISSUES / WORK RUNNING / REVIEW RUNNING / SHIP / SPEND. +- Buttons: List / Board / Analytics, plus Start agent. +- Chips: All, Ship, Review, Work, Plan, Ready, then project chips and Blocked / No PR. +- Visible sections: Ship (5), Review (0), Work (3). +- There is no activity feed, and the metric is "Review running", not "Review queue". +- The current alt text and the prose (lines 228-231) are both wrong; rows 4 and 5 fix them. + +#### Follow-ups +- `roles/retrospective.md:28` says only "older runs" have `synthesis.md`, but the convoy still writes it. That prompt is inconsistent; out of scope. + +--- + +### features/cloister.mdx + +Before: 87 lines, 0 dash lines, title "Cloister lifecycle manager", description 145 chars. + +#### Change table +| # | Grep anchor (EXACT current text, copy-paste, must match the page exactly once; keep it short, one line, no line breaks) | Change (exact replacement text, or "DELETE section `## Heading` (lines x-y)", or "DELETE sentence") | Evidence (`path/file.ts:LINE` + a short exact quote that greps in that file; for an absence, the grep command run and "no match") | +|---|---|---|---| +| 1 | `Cloister does not choose models and does not decide merges.` | `Cloister does not choose the model an agent starts with and does not decide merges.` | Cloister still has a model-handoff path: `src/lib/cloister/service-health.ts:172` "void host.checkHandoffTriggers(agentHealths);"; `src/lib/cloister/triggers.ts:94` "if (currentModel === 'haiku' && minutesSinceActivity"; `src/lib/cloister/config.ts:506` "haiku_to_sonnet_minutes: 10," | +| 2 | `Cloister does not pick models. Roles, workhorse slots and tiered execution do that, configured in Settings → Model Routing; see` | `Cloister does not pick the model an agent starts with. Roles and workhorse slots (Settings → Model Routing) and tiered execution (Settings → Tiered Execution) do that; see` | `src/dashboard/frontend/src/components/Settings/settingsPageConstants.ts:64` "label: 'Model Routing'"; `:70` "label: 'Tiered Execution'"; plus row 1 evidence | + +#### Verified, keep +- `pan admin cloister status/start/stop/emergency-stop` — `src/cli/commands/cloister/index.ts:17,24,30,36`; registered under admin at `src/cli/commands/admin/index.ts:80` +- `[startup] auto_start` in `~/.overdeck/cloister.toml`, default true — `src/lib/cloister/config.ts:29`, `:389` "auto_start: true," +- Start/Stop Cloister in the System Health menu and the command palette — `src/dashboard/frontend/src/App/AppChrome.tsx:222` "<CloisterStatusBar" (inside `SystemHealthPill`); `src/dashboard/frontend/src/components/CommandPalette.tsx:490` +- Stale/warning/stuck at 5/15/30 min, poke on warning and stuck, `kill_on_stuck` false, 30-min poke cooldown — `config.ts:394` "stale: 5,", `:403` "poke_cooldown_ms: 30 * 60 * 1000"; `service-health.ts:164` +- Crashed work-agent resume rules — `src/lib/cloister/crashed-work-resume.ts:19` "It was confirmed dead on two consecutive ticks", `:40` "a failed attempt raises one Needs-you" +- Patrol: nudge after 20 min idle with unpushed commits, once an hour; API-error agents; closed-issue reaper; review recovery; Fly reap — `src/lib/cloister/deacon-lite.ts:55`, `:57`, `:621-637` +- Logs go to `~/.overdeck/logs/deacon.log` — `src/lib/persistent-logger.ts:40` +- Agents and Health pages are experimental and already labeled — `experimentalFeatures.ts` +- Not on the page and not needed: the patrol also re-sends refused planning hand-offs and files missed advisory follow-ups (`deacon-lite.ts:632-637`). + +#### Labels needed +- None missing. + +#### Links +- All 4 resolve. + +#### Frontmatter +- keep both (description 145 chars) + +#### Help section +- no + +#### Follow-ups +- Old escalation triggers (`src/lib/cloister/triggers.ts` stuck_escalation and test_failure, enabled by default in `config.ts`) compare the agent's model with the bare names `'haiku'`/`'sonnet'`. They swap models only when the recorded model is exactly that name, so they are close to dead code: either remove them or fix them. I did not confirm how agent state stores model IDs. + +--- + +### features/merge-batches.mdx + +Before: 204 lines, 12 dash lines, title "UAT Batch Trains", description 75 chars. + +#### Change table +| # | Grep anchor (EXACT current text, copy-paste, must match the page exactly once; keep it short, one line, no line breaks) | Change (exact replacement text, or "DELETE section `## Heading` (lines x-y)", or "DELETE sentence") | Evidence (`path/file.ts:LINE` + a short exact quote that greps in that file; for an absence, the grep command run and "no match") | +|---|---|---|---| +| 1 | `description: Always one tested batch` | Replace the whole line with: `description: "How the merge train batches ready PRs: batch CI, UAT batches you test and merge, the Auto and Hold policy, and the merge train card."` (132 chars) | Window batches merge with no click: `src/dashboard/server/services/batch-auto-promote.ts:4` " * With the merge train on, a batch in an auto GitHub monorepo project merges"; one unheld feature gets no batch: `src/lib/cloister/uat-reconciler.ts:480` | +| 2 | ``(`merge_train_enabled`) is on. With it on, normal-priority PRs in a project that`` | ``(`merge_train_enabled`, off by default) is on. With it on, normal-priority PRs in a GitHub single-repo project that`` | `src/lib/overdeck/control-settings.ts:278` " return getSetting(FLYWHEEL_MERGE_TRAIN_ENABLED_KEY) === 'true';"; `src/dashboard/server/services/merge-train-batching.ts:10` " * train is on (the reconciler checked), the project is GitHub and monorepo," | +| 3 | `With the switch off, every ready PR merges on its own` | Replace the sentence from this anchor to `and nothing batches.` (lines 23-24) with: `With the switch off, nothing batches: every ready PR that is not held for UAT merges on its own five minutes after it is ready, and a held one waits for you to merge it from the issue page. GitLab and polyrepo projects never merge automatically: their batches wait for you to merge them, and with the switch off you merge each PR yourself.` | `src/lib/cloister/merge-route.ts:74` " if (input.heldForUat) return 'batch';"; `src/dashboard/frontend/src/components/merge-train/train/trainCopy.ts:45` "const OFF_HOLD = 'No batches assemble, so features held for UAT wait until the train is on again."; `src/dashboard/server/services/auto-merge-scheduler.ts:40` " * GitLab projects are skipped with a log line: their MRs are not listed here."; `src/dashboard/server/services/merge-path-owner.ts:27` "(the scheduler never schedules either) => batch;"; `merge-path-owner.ts:108` | +| 4 | `projects, with filter chips) and on each project's Home (that project only).` | `projects, with filter chips), on the Awaiting Merge page (all projects, under a global **Merge train** switch), and on each project's Home (that project only).` | `src/dashboard/frontend/src/components/merge-train/train/MergeTrain.tsx:4` "(Flywheel rail, Awaiting Merge)"; `src/dashboard/frontend/src/components/AwaitingMergePage.tsx:90` "<MergeTrainSection />"; `src/dashboard/frontend/src/components/merge-train/MergeTrainSection.tsx:32` 'aria-label="Merge train"' | +| 5 | `off, a banner says no batches assemble and each ready PR merges on its own` | `off, a banner says no batches assemble. In a Holds for UAT project held features then wait until the train is on again; in an Auto-merge project each ready PR merges on its own` (the next line's "after the cooldown." finishes the sentence) | `trainCopy.ts:45` (OFF_HOLD) | +| 6 | `Click **Open UAT frontend**` | `Click **Open UAT** (**Start & open** when its stack is not running)` | `trainCopy.ts:322` "export const OPEN_UAT_LABEL = 'Open UAT';", `:323` "export const START_UAT_LABEL = 'Start & open';"; `grep -rn "Open UAT frontend" src/dashboard/frontend/src` returns no match | +| 7 | `Unless the ready feature is held for UAT, a batch assembles only when **two or` | Replace the paragraph (lines 94-101, from this anchor to `because that batch is the stack you test on.`) with: `Outside the batch window, a batch assembles only when **two or more** features are ready, unless the one ready feature is held for UAT. With exactly one unheld feature ready, it merges on its own (Merge button or \`gh pr merge\`): a one-member batch is the PR branch itself and its CI run a duplicate. A feature held for UAT (its issue's \`hold-for-uat\` label, else the project's \`auto_merge_default: hold\`, else the global **Require UAT** switch on the Flywheel page header, which is on by default) keeps a batch when it is the only one ready, because that batch is the stack you test on. The batch window applies in a GitHub single-repo project that does not hold for UAT: there a batch, even of one PR, assembles once its oldest PR has waited \`batch_wait_minutes\`.` | `src/lib/cloister/uat-reconciler.ts:480` "if (!windowed && toAssemble.length < MIN_BATCH_FEATURES"; `src/lib/cloister/batch-window.ts:58` "if (input.features.length > 0 && waited >= input.waitMs)"; `merge-train-batching.ts:10`; `src/dashboard/frontend/src/pages/FlywheelPage.tsx:183` "checked={config?.require_uat_before_merge ?? true}". The quoted "1 feature ready …" line is never rendered: `git grep -n SINGLE_FEATURE_READY_LINE -- src/dashboard/frontend/src` finds only the definition `src/dashboard/frontend/src/components/merge-train/mergeTrainCopy.ts:24` and tests | +| 8 | `2. With the merge train off, every other feature merges on its own, five` | `2. With the merge train off, every other feature merges on its own (GitHub single-repo projects only), five` | `merge-path-owner.ts:108`; `auto-merge-scheduler.ts:40` | +| 9 | `gets batch trains too, on the same terms as a single-repo` | Replace the first two sentences of that paragraph (lines 139-141, "A polyrepo project … is the only gate.", which contain an em-dash pair) with: `A polyrepo project, one where a single issue's work lands across several member repositories, gets batch trains too. There is no separate setting: the merge-train flag is the only gate. Polyrepo batches never merge on their own: there is no batch window, no automatic batch merge and no per-PR auto-merge, so each batch waits for you to test and merge it.` | `merge-train-batching.ts:185` " if (!config \|\| config.workspace?.type === 'polyrepo') return false;"; `merge-path-owner.ts:27` | +| 10 | `` `uat-<codename>.overdeck.localhost` `` | `` `uat-<label>-<codename>-<mmdd>.overdeck.localhost` `` | `src/lib/cloister/uat-stack.ts:7` " * \`uat-<label>-<codename>-<mmdd>.overdeck.localhost\` with zero new infra." | + +#### Verified, keep +- Flywheel header has **Merge train** and **Require UAT** switches — `FlywheelPage.tsx:182` and following. `merge_train_enabled` is the API payload key; the stored setting is `merge_train.enabled` (`control-settings.ts:126-127`). +- `batch_size` 3 (1 to 20) and `batch_wait_minutes` 30 (1 to 1440) in Settings → Merge Train — `control-settings.ts:284-285`; `settingsPageConstants.ts:74` +- High-priority labels — `merge-route.ts:23`; route-rule order — `merge-route.ts:73-79` +- Batch CI: workflow `CI` on `uat/**`, 10-minute wait, retried after a day — `batch-auto-promote.ts:75,87`; `merge-route.ts:45` +- 5-minute cooldown — `auto-merge-config.ts:1` +- Card labels, pills, nine-step tracker, policy toggle, recent merges — all in `trainCopy.ts`; Retry — `TrainCarRow.tsx:99` +- Older batches capped at 3; terminal batches older than a day dropped — `batchSections.ts:31`; `src/dashboard/server/services/uat-board-chain.ts:17` +- 60 s reconciler — `uat-train.ts:86`; branch name — `src/lib/cloister/uat-candidate-name.ts:44`; timeboxed assembly agent — `src/lib/cloister/uat-conflict-agent.ts:5` +- Touchpoint checklist item — `BatchCard.tsx:415` +- Batch and assembly button labels — `trainCopy.ts` +- Stop after 3 failed assemblies; failures older than 6 h ignored — `uat-reconciler.ts:67,76` +- Merge buttons only while the train is on — `ProjectTrainCard.tsx:102` +- Max two UAT stacks — `uat-stack.ts:32` +- Stack-gate refusal message — `src/dashboard/server/services/promote-stack-gate.ts:84` +- Agents cannot set the labels — `src/lib/launcher-git-guard.ts` +- Not verified in depth: the polyrepo all-or-nothing merge and resume bullets (lines 155-165). + +#### Labels needed +- None; the merge train is opt-in and the page already says so. + +#### Links +- Both internal links resolve (`/features/flywheel`, and `/integrations/ci#merge-train-batches-need-a-ci-workflow` matches the heading at `integrations/ci.mdx:38`). + +#### Frontmatter +- title: keep; description: change (row 1), 132 chars. + +#### Help section +- no + +#### Follow-ups +- Dead copy: `SINGLE_FEATURE_READY_LINE` (`mergeTrainCopy.ts:24`) is defined but nothing renders it. +- The intro (lines 8-12) overclaims "a batch of every ready feature … at all times" and "a single click". Rows 1-3 and 7 carry the facts; the intro is worth rewriting during the dash pass. + +## Appendix H: keyboard-shortcuts.mdx, mission-control.mdx, file-explorer.mdx, open-in-overdeck.mdx (WI-H1 to WI-H4) + +Research pass output, base `2007e9a4d3c`, rows verified by the planner (anchor unique, evidence greps). + +### features/keyboard-shortcuts.mdx + +Before: 96 lines, 0 dash lines, title "Keyboard shortcuts", description 127 chars. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| K1 | `Go to Agents` | `Go to Agents (experimental; opens Home while Experimental features is off)` | `src/dashboard/frontend/src/App/hooks/useAppShortcuts.ts:23` "{ id: 'app.lens-agents', key: 'G A', tab: 'agents', label: 'Go to Agents' }"; `src/dashboard/frontend/src/lib/experimentalFeatures.ts:5` "'agents',"; `src/dashboard/frontend/src/App.tsx:410` "const nextTab = denyExperimental && isExperimentalTab(tab) ? 'home' : tab;" | +| K2 | `` `Ctrl+K`, `Ctrl+J` and `Ctrl+W` go to the shell, as they would in any terminal. `` | `` `Ctrl+K` and `Ctrl+J` go to the shell, as they would in any terminal. In a Chrome tab, `Ctrl+W` never reaches the terminal: Chrome keeps it and closes the browser tab. `` | `src/dashboard/frontend/src/components/Stage/useStageShortcuts.ts:65` "Chrome never delivers Ctrl+1..9 or Ctrl+W to the page"; `src/dashboard/frontend/src/components/XTerminal.tsx:296` "Handle keyboard shortcuts before xterm converts them into PTY input." (only Ctrl+C with a selection and Ctrl+V are intercepted) | +| K3 | `For every view these shortcuts reach, see [Dashboard views](/features/dashboard-views).` | Keep the line; insert block K3-INSERT (below) after it | `src/dashboard/frontend/src/components/KanbanBoard.tsx:617` and `src/dashboard/frontend/src/components/Pipeline/PipelineView.tsx:353` "if (e.key !== 'j' && e.key !== 'k' && e.key !== 'Enter') return;"; `KanbanBoard.tsx:336` "if ((e.metaKey ‖ e.ctrlKey) && e.key === 'z') {" (‖ = two pipes); `src/dashboard/frontend/src/components/CommandDeck/ConversationList.tsx:631` "if (mutations.undoLastTriage()) e.preventDefault();"; `src/dashboard/frontend/src/lib/keybindings.ts:8` "export const EDITOR_OPEN_FAVORITE_KEY = 'mod+shift+o';"; `src/dashboard/frontend/src/components/chat/ComposerFooter.tsx:702` (Meta on mac, Ctrl elsewhere; key 'm' with Shift); `src/dashboard/frontend/src/components/GodView/confluence/GodViewConfluence.tsx:101` "if (event.key === 'h' ‖ event.key === '?') {" | + +K3-INSERT: +``` +## Keys on single pages + +These keys work only where named, and the `?` sheet does not list them. + +| Action | macOS | Linux and Windows | Where | +| --- | --- | --- | --- | +| Next or previous issue, then open it | `J` / `K`, then `↵` | `J` / `K`, then `↵` | Board and Pipeline, when you are not typing | +| Undo the last status move | `⌘Z` | `Ctrl+Z` | Board | +| Undo the last settle or snooze | `⌘Z` | `Ctrl+Z` | the Conversations list, when it has focus | +| Open the folder in your preferred editor | `⌘⇧O` | `Ctrl+Shift+O` | a conversation, or an issue's open-in picker | +| Voice input | `⌘⇧M` | `Ctrl+Shift+M` | the conversation composer | +| God View help, fullscreen | `H` or `?`, `F` | `H` or `?`, `F` | God View (experimental) | +``` + +#### Verified, keep +- Palette, conversations, `/`, `?` and the `G` chords match `src/dashboard/frontend/src/App/hooks/useAppShortcuts.ts:43` "keys: { mac: 'Meta+K', other: 'Ctrl+K' },", `:55` "keys: { mac: 'Meta+J', other: 'Ctrl+J' },", and LENSES at `:21-24`. +- Stage keys match `src/dashboard/frontend/src/components/Stage/useStageShortcuts.ts:13` "keys: { mac: `Meta+${n}`, other: `Ctrl+Alt+${n}` },", `:29` "keys: { mac: 'Meta+W', other: 'Ctrl+Alt+W' }," and `:44` "keys: { mac: 'Meta+T', other: null },". +- `[` and `N` match `src/dashboard/frontend/src/components/frame/LeftColumn.tsx:100` "keys: { mac: '[', other: '[' }, scope: 'not-editing'" and `src/dashboard/frontend/src/components/frame/NewConversationButton.tsx:55` "keys: { mac: 'N', other: 'N' }". +- The four Files keys are global and register only while the WorkDock is mounted, which happens only in Stage: `src/dashboard/frontend/src/components/explorer/search/useExplorerShortcuts.ts:34-37`, `src/dashboard/frontend/src/components/dock/WorkDock.tsx:153` "useExplorerShortcuts(shortcuts)", `src/dashboard/frontend/src/components/Stage/index.tsx:828` "<WorkDock deckKey={deckKey}". +- `J`/`K` in a diff match `src/dashboard/frontend/src/components/dock/changes/DockDiffView.tsx:80` "id: 'dock.diff-next', keys: { mac: 'J', other: 'J' }". +- Emergency stop is global: `src/dashboard/frontend/src/components/EmergencyStopOverlay.tsx:72` "keys: { mac: 'Meta+Shift+.', other: 'Ctrl+Shift+.' },". +- The 1.5 s chord window matches `src/dashboard/frontend/src/lib/shortcuts/registry.ts:46` "export const CHORD_TIMEOUT_MS = 1500". "Not typing" means focus is outside input, textarea, select, xterm and Monaco (`registry.ts:118`). +- The `?` sheet: `src/dashboard/frontend/src/lib/shortcuts/ShortcutsSheet.tsx:23` "<Modal title=\"Keyboard shortcuts\"". The God View exception is `useAppShortcuts.ts:78` "when: () => activeTabRef.current !== 'god-view',". +- `/` opens issue search: `src/dashboard/frontend/src/components/search/SearchModal.tsx:136` "'Search all issues…'". +- The conversation find bar matches `src/dashboard/frontend/src/components/chat/messagesTimeline/MessagesTimeline.tsx:530` (Ctrl or Meta, no Shift, `f`). +- Palette details match `src/dashboard/frontend/src/components/CommandPalette.tsx`: + - `:405` "if (trimmed.length < 2) {" + - `:955` "Search timed out after 10 s. Try again." + - `:465` "label: 'New workspace…'," + - `:483` "label: 'Open Flywheel'" + - `:547` "label: 'Open Settings'," + - `:565` "label: 'Go to Kanban Board'," + - `:583` "label: 'View Agents'," + - `:1065` "Newest first" + - `:289` "await navigator.clipboard.writeText(text);" + - `:868` scope fallback to All +- **N tabs** and Escape: `src/dashboard/frontend/src/components/Stage/PaneBar.tsx:289` "{panes.length} tabs", `:128` "Escape closes the menu and returns focus to its trigger". + +#### Labels needed (experimental / early / testing) +- `G` then `A` (handled by K1). God View in K3 is labeled. + +#### Links +- All 3 internal links resolve: `/features/dashboard-views`, and `/features/conversations#find-a-conversation` twice (heading at conversations.mdx:1200). + +#### Frontmatter +- title: change to "Dashboard keyboard shortcuts" (sidebarTitle "Keyboard shortcuts"). +- description: keep (127 chars). + +#### Help section +- no + +#### Chrome reserved keys +- No Linux/Windows binding uses a bare Ctrl+N/T/W or Ctrl/Alt+digit. Only the terminal sentence is wrong (K2). +- Unsure: on macOS Chrome, `⌘W` (close Stage tab) and `⌘T` (terminal drawer) probably never reach the page, though they work in the desktop app. Line 94 ("On macOS, `⌘1` to `⌘9` and `⌘W` reach the page") and the `⌘T` row need a real-Mac check before anyone edits them. + +#### Follow-ups +- `registry.ts:3-4` says no other listeners exist, but the K3 keys and the file-tree keys (`src/dashboard/frontend/src/components/explorer/actions/useTreeActionKeys.ts`) bypass the registry, so the `?` sheet never shows them. +- Board undo (`KanbanBoard.tsx:336`) listens on window with no editable-focus check, so Ctrl+Z inside a text field on the Board also undoes a status move. +- The `⌘⇧O` label is mac-only (`keybindings.ts:9`) and also shows on Linux. The voice tooltip says "Ctrl+Shift+M" even on macOS (`src/dashboard/frontend/src/components/chat/ComposerToolbar.tsx:150`). +- The palette offers **View Agents** with experimental features off, and it lands on Home. + +--- + +### features/mission-control.mdx + +Before: 263 lines, 0 dash lines, title "Command Deck", description 133 chars. + +**Route and gating:** tab id `command-deck`, route `/command-deck` (`src/dashboard/frontend/src/App/routes.ts:10` "'command-deck': '/command-deck',"). It is not in `EXPERIMENTAL_TAB_IDS`. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| M1 | `- **Main panel (right)**: Feature activity view, planning artifacts, and status reviews` | `- **Main panel (right)**: the Stage, with the project's Home pane, conversations, issues and code files in tabs` | `src/dashboard/frontend/src/lib/panesStore.ts:23` "export type PaneType =" (home, issue, agent, files, code…) | +| M2 | `## Project Tree` | Replace section `## Project Tree` (lines 62-73) with block M2-TEXT | `src/dashboard/frontend/src/components/CommandDeck/ProjectTree/featureRowMeta.ts:27` "const parts = [needsYou ? 'Needs you' : STAGE_WORDS[phase]];", `:32` "parts.push(`${taskTotals.closed} of ${taskTotals.total} items`);", `:10` "export const STAGE_WORDS"; absence: `git grep -n "review-status.json" -- src` returned no match. The old labels (Has Context…) are only server-side in `src/dashboard/server/services/resource-discovery.ts:228` and are not rendered in the row. | +| M3 | `Click it for the Agents page.` | `Click it for the Agents page, which is experimental: with Experimental features off, the click lands on Home.` | `src/dashboard/frontend/src/components/Stage/ProjectHome.tsx:188` "onAgents={() => navigate('/agents', 'agents')}"; `src/dashboard/frontend/src/App.tsx:410` "const nextTab = denyExperimental && isExperimentalTab(tab) ? 'home' : tab;" | +| M4 | `## Activity View` | DELETE section `## Activity View` (lines 114-132, includes `### Section Isolation Mode` and the activity image) | `src/dashboard/frontend/src/components/AgentOutputPanel.tsx:15` and `src/dashboard/frontend/src/components/TerminalPanel.tsx:8` "import { ActivityView } from './CommandDeck/ActivityView';". Neither host is rendered: `git grep -n -E "AgentOutputPanel\|<TerminalPanel" -- src/dashboard/frontend/src ':!*.test.*' ':!**/__tests__/**'` finds only the files themselves. | +| M5 | `request, a rate-limit dialog, or simply a finished turn. **Decisions** is the one` | `request, a rate-limit dialog, or simply a finished turn. **Decisions**, the **Needs you** scope of the Activity page (`/activity`), is the one` | `src/dashboard/frontend/src/components/ActivityFeedTab.tsx:4` "(Needs you carries the DecisionsPanel cards)" | +| M6 | `The list separates **Blocking work** from **Waiting**.` | `The list puts **System** items (Overdeck's own machine needs attention) first, then separates **Blocking work** from **Waiting**.` | `src/dashboard/frontend/src/components/DecisionsPanel.tsx:204` "<Group title=\"System\" hint=\"Overdeck's machine needs attention\"" | +| M7 | `## Badge Bar` | DELETE section `## Badge Bar` (lines 185-198) | `BadgeBar` has no importer: `git grep -n "BadgeBar" -- src/dashboard/frontend/src ':!*.test.*' ':!**/__tests__/**'` matches only its own file. `src/dashboard/frontend/src/lib/__tests__/issueActions.no-actions-lost.test.ts:50` "the artifact badges (Inference, Discussions, Transcripts," | +| M8 | `## Status Reviews` | DELETE section `## Status Reviews` (lines 200-210) | Its only UI caller is the unmounted BadgeBar: `git grep -n "status-review" -- src/dashboard/frontend/src` matches only `components/CommandDeck/FeatureMetadata/BadgeBar.tsx`. `git grep -n -i "workflow agents" -- src` returned no match. | +| M9 | `## Planning Artifacts` | Replace section `## Planning Artifacts` (lines 212-232, includes `### Uploading Artifacts` and `### Syncing Discussions`) with block M9-TEXT | Upload and sync callers are only BadgeBar and TranscriptUpload, both unmounted. The server reads `.pan`, not `.planning`: `src/dashboard/server/routes/command-deck.ts:632` "const planningDir = join(workspacePath, PAN_DIRNAME);", `src/lib/pan-dir/types.ts:10` "export const PAN_DIRNAME = '.pan'". Replacement tabs: `src/dashboard/frontend/src/components/issue-detail/issueTabs.ts:16` "{ id: 'discussion', label: 'Discussion' },", `:57` "plan: [{ value: 'plan', label: 'Map' }, { value: 'prd', label: 'PRD' }],"; mounted by `src/dashboard/frontend/src/components/drawer/IssueDrawer.tsx:143` "<IssueDetail" | +| M10 | `A metric strip (Active issues, Work running, Review queue, Ship, and Spend) sits above phase-grouped rows (Ship, Review, Verifying), with a live activity feed on the right.` | `A metric strip (Active issues, Work running, Review running, Ship and Spend) sits above phase and project filters and the issue rows, grouped by phase: Ship, Review, Work, Plan and Ready.` | `src/dashboard/frontend/src/components/Pipeline/PipelineView.tsx:418` "eyebrow: 'Review running'"; `src/dashboard/frontend/src/lib/pipeline-state.ts:105` "export const PIPELINE_BOARD_PHASES = ['ship', 'review', 'work', 'plan', 'ready']"; no feed component in PipelineView (also confirmed in both PNGs) | +| M11 | `alt="Pipeline page: a metric strip over phase-grouped issue rows with a live activity feed"` | `alt="Pipeline page: five metric tiles over phase and project filters, with issue rows grouped under Ship, Review and Work"` | Both PNGs (see Screenshot alt text) | +| M12 | `` Projects are configured in `~/.overdeck/config.yaml`. Any project with active workspaces appears in the project switcher. `` | `` Projects are registered in `~/.overdeck/projects.yaml`. Add one with **Add a project** in the project switcher or `pan project add <path>`; every registered project appears in the switcher. See [Projects](/configuration/projects). `` | `src/lib/projects.ts:80` "export const PROJECTS_CONFIG_FILE = join(OVERDECK_HOME, 'projects.yaml');"; `src/dashboard/frontend/src/components/frame/ProjectSwitcher.tsx:6` "Its menu lists every registered project"; `src/cli/commands/project.ts:673` ".command('add <path>')" | +| M13 | `### Model Selection` | DELETE subsection `### Model Selection` (lines 254-256); the status-review UI is gone (M8), and M12 carries the `/configuration/projects` link | same as M8 | +| M14 | `the deck reads "Pick conversations on the left. Ctrl+Click opens one beside another."` | `the deck reads "Pick conversations on the left. Ctrl+Click opens one beside another." (Cmd+Click on macOS)` | `src/dashboard/frontend/src/components/Stage/index.tsx:803` "{`Pick conversations on the left. ${currentPlatform() === 'mac' ? 'Cmd' : 'Ctrl'}+Click opens one beside another.`}" | + +M2-TEXT: +``` +## Project Tree + +The Issues section lists the selected project's issues in the pipeline. A collapsed row shows the issue ID, its title and its spend, then a meta line: the stage word (`Not started`, `Planning`, `Building`, `Ready`, `In review` or `Ready to merge`, or `Needs you` when it waits on you), the model of the newest active agent, and task progress such as `3 of 7 items`. Expand the row for its badges, pull request and sessions. +``` + +M9-TEXT: +``` +## Issue documents + +An issue's plan and PRD, tasks, tracker discussion, changes and activity are tabs of the issue drawer and the full issue view. See [Issue drawer and full issue view](/features/dashboard-views#issue-drawer-and-full-issue-view). +``` + +#### Verified, keep +- Left column sizes: `src/dashboard/frontend/src/components/frame/LeftColumn.tsx:33-36` (264, 240, 640, 48). The narrow-window drawer and its button: `src/dashboard/frontend/src/App/AppChrome.tsx:187` "aria-label=\"Open navigation\"" with `min-[900px]:hidden`. +- Project switcher: more-than-8 filter at `ProjectSwitcher.tsx:32` "export const PROJECT_FILTER_THRESHOLD = 8;"; status words at `:74`; "Choose a project" at `:100`; "Add a project" at `:237`; "New workspace in" at `:247`. +- Navigation and More groups: `src/dashboard/frontend/src/components/frame/LeftNav.tsx:89,98,104,109,119`, `src/dashboard/frontend/src/components/frame/navGroups.ts:27,38,44,55`. +- Issues filter: `src/dashboard/frontend/src/components/frame/IssuesFilterMenu.tsx:13` "{ all: 'All', alive: 'Alive', failed: 'Failed' }", `:68` Planned. +- Footer: `src/dashboard/frontend/src/components/frame/LeftColumnFooter.tsx:2-5`. Workspaces section hidden when empty: `src/dashboard/frontend/src/components/frame/WorkspacesSection.tsx:120`. +- All projects deck labels (spot-checked by grep, not audited in depth): + - "Open beside" and "Open in its project": `src/dashboard/frontend/src/components/CommandDeck/ConversationRow.tsx:797,803` + - Layout names: `src/dashboard/frontend/src/components/Stage/LayoutPresetBar.tsx:18-20` + - "Make this the only pane": `src/dashboard/frontend/src/components/Stage/PaneLayoutView.tsx:124` + - "N conversations side by side": `src/dashboard/frontend/src/App/topbar/Breadcrumb.tsx:41` +- Project home release and CI words: `src/dashboard/frontend/src/components/Stage/HomePane/HomeMetaLine.tsx:34-40,97-102`. +- Action row: `src/dashboard/frontend/src/components/Stage/HomePane/HomeActions.tsx:39-40,61-62`. +- Facts: `src/dashboard/frontend/src/components/Stage/HomePane/HomeFacts.tsx:8` "const COMMIT_CAP = 500", `:131-144`. +- Pipeline lanes and tags: `src/dashboard/frontend/src/components/CommandDeck/pipeline-helpers.ts:54` "const STALLED_INACTIVITY_MS = 14 * 24 * 60 * 60 * 1000;", `:341-343`, tags at `:394-411`. "Open the board": `src/dashboard/frontend/src/components/CommandDeck/ProjectOverview.tsx:89`. +- Recent changes, ten commits: `src/dashboard/frontend/src/components/Stage/HomePane/RecentChanges.tsx:9,11,69`. Refresh every minute: `src/dashboard/frontend/src/components/Stage/HomePane/useHomeData.ts:35` "refetchInterval: 60_000,". +- Needs you button: `src/dashboard/frontend/src/components/flywheel/NeedsYouIndicator.tsx:113`. Board strip, six cards: `src/dashboard/frontend/src/components/KanbanBoard/NeedsYouStrip.tsx:226,232`. +- Activity feed: Feed, Activity Log, Detailed, TTS at `src/dashboard/frontend/src/components/ActivityPanel.tsx:49`; Chats at `src/dashboard/frontend/src/components/sessionFeed/SessionFeedSidebar.tsx:64`. +- Costs is already labeled experimental on line 99. + +#### Labels needed (experimental / early / testing) +- The Agents page link (M3). The Costs link is already labeled. + +#### Links +- All 7 internal links resolve: conversations#new-conversation-with-options (heading at :213), costs, configuration/projects, specialists, cloister, workspaces, dashboard-views. +- M9 adds `/features/dashboard-views#issue-drawer-and-full-issue-view`; that heading exists at dashboard-views.mdx:137. +- No repo file links to the deleted or renamed anchors (`git grep "mission-control#(project-tree|activity-view|section-isolation-mode|badge-bar|status-reviews|planning-artifacts|uploading-artifacts|syncing-discussions|model-selection|adding-projects|configuration|pipeline-view)"` returned no match). Inbound links to `#project-home` and `#all-projects-and-side-by-side-conversations` stay valid. + +#### Frontmatter +- title: keep ("Command Deck" is a product name, not generic). +- description: keep (133 chars). + +#### Help section +- no + +#### Screenshot alt text +- pipeline-light.png and pipeline-dark.png (same content) show: + - five tiles: ACTIVE ISSUES, WORK RUNNING, REVIEW RUNNING, SHIP, SPEND + - a phase filter (All, Ship, Review, Work, Plan, Ready), project chips, and Blocked and No PR toggles + - rows grouped under Ship (5), Review (0) and Work (3) + - List, Board and Analytics, plus Start agent +- There is no activity feed. The current alt text is wrong; use M11. + +#### Follow-ups +- Dead code: BadgeBar, TranscriptUpload, the CommandDeck `ActivityView`, `AgentOutputPanel`, `TerminalPanel` (except `popoutTerminal`), `IssueCockpitBody` and `IssueDigTabs` have no mounted importer. The server routes `/api/command-deck/planning/:id/{status-review,upload,sync-discussions}` have no UI caller. +- `/images/dashboard/activity-{light,dark}.png` become orphaned after M4. + +--- + +### features/file-explorer.mdx + +Before: 123 lines, 0 dash lines, title "File explorer", description 71 chars. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| F1 | `` `Ctrl/Cmd+Z` undoes the last file action and `Ctrl/Cmd+Shift+Z` redoes it. `` | `` With the tree focused, `F2` renames the selected row, `Delete` (or `⌘⌫` on macOS) deletes the selection, `Ctrl/Cmd+Z` undoes the last file action and `Ctrl/Cmd+Shift+Z` redoes it. `` | `src/dashboard/frontend/src/components/explorer/actions/useTreeActionKeys.ts:5` "F2 renames the single selected row; Delete, or Meta+Backspace, deletes the" | +| F2 | `Drop files from your computer onto a folder to upload them.` | `Drop files from your computer onto a folder to upload them. Each file can be up to 100 MB, and an upload never replaces a file of the same name.` | `src/dashboard/server/services/explorer/upload.ts:15` "export const EXPLORER_UPLOAD_MAX_BYTES = 100 * 1024 * 1024;", `:6` "so an upload never replaces an existing file" | + +#### Verified, keep +- Roots (main checkout read-only, issue and edit workspaces writable): `src/dashboard/server/services/explorer/roots.ts:4-7`. +- Edit workspace branch and folder: + - `src/dashboard/server/services/explorer/edit-workspace.ts:7` "(`scratch/edit-<MMDD-HHMM>[-n]`) cut from `origin/<default branch>`" + - `src/lib/workspaces/create.ts:388` "const worktreePath = join(workspacesDir, `scratch-${name}`);" + - New edit workspace: `src/dashboard/frontend/src/components/explorer/ExplorerPane.tsx:262` +- Trash: `src/dashboard/server/services/explorer/trash.ts:40` "export const TRASH_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;" in `~/.overdeck/trash` (`:54`). Pruning happens at the next delete, so "stays 7 days" is a minimum, not exact. +- Folder download as `.tar.gz`: `src/dashboard/server/services/explorer/folder-archive.ts:2`. +- Dock tabs Files, Changes, Search and Live: `src/dashboard/frontend/src/components/dock/WorkDock.tsx:224-236`. + - "Open project files": `:261` + - "Follow tab" and "Follow the active tab": `:320-324` + - Stage + menu items: `src/dashboard/frontend/src/components/Stage/index.tsx:493-506` +- View options menu items: `ExplorerPane.tsx:156-182`. "Find in folder": `src/dashboard/frontend/src/components/explorer/menu/ExplorerContextMenu.tsx:169`. +- Search toggles: `src/dashboard/frontend/src/components/explorer/search/ContentSearch.tsx:155-156` ("Match case", "Use regular expression"). "changed here" tag: `src/dashboard/frontend/src/components/explorer/search/QuickOpen.tsx:189`. +- Autosave 1 s: `src/dashboard/frontend/src/components/explorer/code/autosave.ts:11` "export const AUTOSAVE_DELAY_MS = 1000;". Alt+Z: `src/dashboard/frontend/src/components/explorer/code/MonacoCodeEditor.tsx:78`. +- External-change banner (Compare, Reload from disk, Keep my edits, Overwrite): `src/dashboard/frontend/src/components/explorer/code/ExternalChangeBanner.tsx`. +- Create PR dialog strings: `src/dashboard/frontend/src/components/explorer/edit/CreatePrDialog.tsx:43,48,53,197,209,241`. +- Editor bar: `src/dashboard/frontend/src/components/explorer/edit/EditorBar.tsx:199,251,361,366,371,405`. +- PR status refresh every 15 s: `src/dashboard/frontend/src/components/explorer/edit/edit-workspace-http.ts:68` "export const PR_STATUS_REFETCH_MS = 15_000". +- Merge anyway: `src/dashboard/frontend/src/components/explorer/edit/MergeAnywayDialog.tsx:19,24`. Also close PR, checked by default: `src/dashboard/frontend/src/components/explorer/edit/DiscardDialog.tsx:25`. +- Stale tab: `src/dashboard/frontend/src/components/explorer/code/StaleCodeTab.tsx:25,60`. +- Preview messages: `src/dashboard/frontend/src/components/diff/markdownPreviewSource.ts:7-9`. Link-not-found tooltip: `src/dashboard/frontend/src/components/chat/MarkdownDocLink.tsx:42`. +- Changes chips: `src/dashboard/frontend/src/components/dock/changes/ConversationChangesList.tsx:24-26,41`. + +#### Labels needed +- none + +#### Links +- All 4 internal links resolve: `/features/open-in-overdeck`, `/features/keyboard-shortcuts`, and `#markdown-preview` twice (heading at line 70). + +#### Frontmatter +- title: change to "File explorer and code editor" (sidebarTitle "File explorer"). +- description: keep (71 chars). + +#### Help section +- no + +#### Follow-ups +- Tree undo and redo are disabled on the main checkout root (`useTreeActionKeys.ts:50` "if (!isProjectRoot) handled(event.shiftKey ? redo : undo)"). That does not matter in practice, because a file action there switches to an edit workspace. + +--- + +### features/open-in-overdeck.mdx + +Before: 107 lines, 0 dash lines, title "Open in Overdeck", description 105 chars. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| O1 | ``or `Opened the <issue> workspace in <project>` for an issue workspace.`` | ``or `Opened the <issue> workspace in <project>` for an issue workspace, or `Opened root folder in <project>` for a root folder. The path it names is relative to the project or workspace folder.`` | `packages/contracts/src/ui-commands.ts:29` "if (relPath) return `Opened ${relPath} in ${deckKey}`", `:31` "return `Opened root folder in ${deckKey}`" | +| O2 | ``(the shim `pan sync` writes in `~/.overdeck/cli-bin`, or the first `pan` on PATH)`` | ``(on Linux and macOS the shim `pan sync` writes in `~/.overdeck/cli-bin`, or the first `pan` on PATH; on Windows the first `pan.cmd` or `pan.exe` on PATH)`` | `src/lib/integrations/file-manager.ts:255` "is executable, else the first `pan` on PATH. Windows: the first `pan.cmd`" | + +#### Verified, keep +- `pan open <target>` and its four options: `src/cli/index.ts:268` ".command('open <target>')", `-e, --editor [editor]`, `--line`, `--column`, `--new-tab`. +- Target parsing (path, `:line[:column]`, issue id) and the rule that a real file ending in `:12` wins: `src/cli/commands/open-target.ts:2-7`. `--line` beats the suffix: `src/cli/commands/open.ts:241`. The issue workspace is `workspaces/feature-<id>` (`open.ts:204`). +- Editor ids include `file-manager`: `packages/contracts/src/editor.ts:25`. With no name, the first editor on PATH is used, skipping file-manager (`open.ts:46-53`). +- Error messages: `open.ts:168` "Overdeck isn't running. Start it with: pan up", `:176`, `:178`. The suggestion `pan project add ${dir}` is at `src/dashboard/server/routes/ui-open.ts:97`. +- Dashboard address: `src/lib/config.ts:443-447` (OVERDECK_DASHBOARD_URL, default 3011). +- The `/open` link: `open.ts:149-151`. "Add it as a project?" and "Add project": `src/dashboard/frontend/src/components/open/OpenPathHost.tsx:95,110`. +- Leader tab: stale after a day (`src/dashboard/frontend/src/lib/uiCommands/leaderTab.ts:9` "const STALE_MS = 24 * 60 * 60 * 1000"); followers wait 750 ms (`src/dashboard/frontend/src/lib/uiCommands/useUiCommands.ts:18`). +- `pan integrate file-manager` with `--remove` and `--dry-run`: `src/cli/commands/integrate.ts:147-150`. "Nothing to remove": `:110`. The no-pan error says to run `pan sync` (`:58`). +- Install flags: `src/cli/commands/install.ts:72-73`. The step runs after Ollama (`:491` then `:501`). Prompt text and default No: `src/cli/commands/install-file-manager.ts:28,31`. A failure is only a warning: `:59`. +- Linux paths: `src/lib/integrations/file-manager.ts:78-80`; update-desktop-database: `:104`; icon at `~/.overdeck/integrations/overdeck.svg`: `:282`, Linux only (`:71`). +- macOS: the `Open in Overdeck.workflow` path is `file-manager.ts:85`; the Services refresh (`pbs -update`) is `:68,111`. The Quick Action uses zsh (`src/lib/integrations/templates/macos.ts:123`). +- Windows `HKCU\Software\Classes` keys: `file-manager.ts:60-65`. The record file `file-manager.json`: `:203`. +- Doctor check: `src/cli/commands/doctor-file-manager.ts:53` "File-manager integration is stale: ${missing}", called from `src/cli/commands/doctor.ts:757`. +- Desktop `--open`: `apps/desktop/src/main.ts:112-127`. It is ignored when the window shows a remote dashboard (`:124`). + +#### Labels needed +- none (the page already says macOS and Windows are covered by unit tests only) + +#### Links +- The only internal link (`/features/desktop-app`) resolves. + +#### Frontmatter +- title: keep. +- description: keep (105 chars). + +#### Help section +- no + +#### Follow-ups +- The Linux Open With entry declares only `inode/directory`, `text/plain` and `application/octet-stream` (`src/lib/integrations/templates/linux.ts:31`). Some file types may therefore not list **Open With → Overdeck**. Worth testing; no row proposed. + +## Appendix I: issue-pipeline.mdx, planning.mdx, flywheel.mdx (WI-I1 to WI-I3) + +Research pass output, base `2007e9a4d3c`, rows verified by the planner (anchor unique, evidence greps). + +### features/issue-pipeline.mdx + +Before: 169 lines, 0 dash lines, title "Issue pipeline: from issue to merged PR", description 144 chars. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| 1 | The `verification.tests` setting picks | The per-project `verification.tests` setting in `projects.yaml` picks | `src/lib/cloister/verification-tests-mode.ts:10` "`projects.yaml` decides per project:" | +| 2 | drives the workspace's built dashboard with Playwright | drives the workspace's own running app with Playwright | `roles/test.md:72` "start or connect to the running app using the project instructions and drive the browser with Playwright MCP tools"; `roles/test.md:64` "Test only the feature workspace's own containers and endpoint" | +| 3 | otherwise the global `require_uat_before_merge` setting, which defaults to true | otherwise the global Require UAT switch on the [Flywheel](/features/flywheel) page (app setting `flywheel.require_uat_before_merge`), which defaults to on | `src/lib/overdeck/control-settings.ts:125` "const FLYWHEEL_REQUIRE_UAT_BEFORE_MERGE_KEY = 'flywheel.require_uat_before_merge';"; `:263` "return val !== 'false'; // defaults to true if unset"; `src/dashboard/frontend/src/pages/FlywheelPage.tsx:182` `label="Require UAT"` | + +#### Verified, keep +- `pan start` flags `--plan`, `--plan-model`, deprecated `--auto`, `--fresh`, `--force`: `src/cli/commands/start-register.ts:21-25` +- Plan-mode order is the `--plan` flag, then `--auto`, then `planning.default_mode`, then `auto`; an invalid value names the three choices: `src/cli/commands/planning-mode.ts` +- An unplanned `pan start` posts `autoStart: true`: `src/cli/commands/start.ts:700` +- `Start work` needs a plan, tasks and no live agent: `src/dashboard/frontend/src/lib/issueActions.ts:535` +- `pan done` preflight checks and its flags: `src/lib/work/done-preflight.ts:91-93`, `src/cli/index.ts:429-431` +- Default gates when no `quality_gates` is set: `src/lib/cloister/validation.ts:276` +- Up to 3 attempts per head, and the same check failing twice escalates: `src/lib/cloister/verification-cycles.ts:30` and `:32` +- Test-skip gate `.skip`/`.only`/`xit`, waived with `pan review waive-test-removal`: `src/lib/cloister/test-skip-gate.ts:7`, `src/cli/commands/review-subcommands.ts:16` +- Review modes, with `quick` as default: `src/lib/cloister/review-agent.ts:924`, `src/lib/config-yaml/roles.ts:45` +- 25 automatic re-requests: `src/dashboard/server/routes/workspaces/review-pipeline.ts:76` +- Convergence needs 3 rounds and shows `Review loop not converging`: `src/lib/cloister/review-convergence.ts:19`, `src/lib/cloister/review-verdict-feedback.ts:226` +- The test role starts only from two places: `review-pipeline.ts:644` "dispatching test role" and `src/lib/agents/issue-pause.ts:254`. `git grep "'review.approved'" src` finds consumers but no emitter. +- A failed UAT blocks merge only while held for UAT: `src/lib/cloister/merge-gate.ts:156-158`, `src/lib/cloister/pr-facts.ts:971` +- `[INHERITED FROM MAIN` tag: `src/lib/cloister/ci-failure-feedback.ts:599` +- CodeRabbit follow-up title: `src/lib/cloister/advisory-followup.ts:48` +- Conflict-resolver throttle (30 min) and conflict-repair grace (45 min): `src/lib/cloister/conflict-gate.ts:14`, `src/lib/cloister/conflict-repair.ts:42` +- `pan sync-main` does not push; plan-path conflicts resolve to main, other conflicts abort: `src/lib/cloister/merge-agent.ts:59-61` and `:860` +- `Needs you · N`: `src/dashboard/frontend/src/components/flywheel/NeedsYouIndicator.tsx:113` +- `pan ask` options, and the dialog header "Decision": `src/cli/index.ts:331-336`, `src/lib/cloister/operator-decision.ts:184` +- Merge gate rules: `merge-gate.ts:136-188` +- Squash merge: `src/lib/forge.ts:555` +- 5-minute cooldown: `src/lib/cloister/auto-merge-config.ts:1` +- Pipeline Override, Force Approve, Force Merge: `src/dashboard/frontend/src/components/AwaitingMergePage.tsx:606`, `:683`, `:694` +- Strike branch and workspace names, one review per head, changes-requested stops it: `src/cli/commands/strike.ts:124` and `:131`, `src/dashboard/server/services/strike-review.ts:9` +- Nine DoD rows, row 9 not overridable: `src/lib/lifecycle/dod.ts:16-79`, `src/cli/commands/close.ts:114-118` +- `Close Out` button: `src/dashboard/frontend/src/components/CloseOutIssueButton.tsx:56` +- `close_out.auto` is inert: `src/lib/cloister/config.ts:539` +- The reaper deletes the workspace and the local and remote branch once merged: `src/lib/cloister/reap-issue-residue.ts:138` +- `pan show` flags, the nine states, and the journal in `--json`: `src/cli/index.ts:258-263`, `src/lib/overdeck/derived-issue-state.ts:179-214`, `src/cli/commands/show.ts:300` +- `pan reopen` adds the `in-progress` label: `src/cli/commands/reopen.ts:187` + +#### Labels needed +- None. + +#### Links +- All 10 internal links resolve, plus the in-page `#merge`. + +#### Frontmatter +- title: keep. description: keep (144 chars). + +#### Help section +- Yes, lines 167-169, with both links. + +#### Follow-ups +- Issue #5537 (open): the page already describes today's behavior. +- `src/lib/cloister/verification-runner.ts:702` tells the agent to run `pan task close`, but `pan task` has no `close` verb (`src/cli/commands/task.ts:272-289`). It should say `pan task done`. +- Strike review is GitHub-only: `strike-review.ts` header, "GitLab projects are skipped". + +--- + +### features/planning.mdx + +Before: 274 lines, 0 dash lines, title "Planning: PRDs, xBRIEF plans and the plan critic", description 145 chars. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| 1 | `Xhigh` and `Max` add the probe pass. | `High` and above add the probe pass, so the default effort runs it. | `src/lib/planning/spawn-planning-session.ts:259` "const deepEffort = effort !== undefined && compareEffort(effort, 'high') >= 0;"; `:307` "const probeSection = probe" | +| 2 | A spec has exactly two top level keys, `xBRIEFInfo` and `plan`. | The planner writes exactly two top level keys, `xBRIEFInfo` and `plan`; the canonical spec in `.pan/specs/` also carries a root `status` field, the lifecycle status described under [Where the plan lives](#where-the-plan-lives). | `src/lib/cloister/prompts/planning.md:238` "It MUST have exactly two top-level keys: `xBRIEFInfo` and `plan`."; `src/lib/pan-dir/specs.ts:90` "missing valid root status"; promoted spec `.pan/specs/2026-11-19-PAN-5501-…xbrief.json` has keys xBRIEFInfo, plan, status | +| 3 | an optional `narrative.Action` | a `narrative.Action` (finalize's quality lint requires at least 8 words) | `src/lib/xbrief/quality-lint.ts:179` "narrative.Action must contain at least 8 words" | +| 4 | A small example, two items and one dependency between them: | A small example of the shape, two items and one dependency between them. It is not a finalize-ready plan: the quality lint (exit code `3`) also requires, per item, `metadata.files_scope`, `files_scope_confidence`, `readiness` and `requiresInspection`, a `narrative.Action` of at least 8 words, and 2 to 5 acceptance criteria (or `metadata.acJustification`) whose titles name observable behavior: | `quality-lint.ts:115` "metadata.files_scope is required and must name at least one concrete file or narrow glob"; `:127` "metadata.files_scope_confidence is required and must be high, medium, or low"; `:131` "metadata.readiness is required and must be ready, sequential, or needs_refinement"; `:183` "metadata.requiresInspection is required"; `:163` "expected 2-5 or metadata.acJustification"; `:173` "does not name observable behavior" | +| 5 | The PR merges | Nothing automatic: close-out leaves the field alone and the merged PR is the evidence; `pan scope complete` sets it by hand | `src/lib/lifecycle/workflows.ts:577` "is derived from the merged PR; close-out does not write it"; `src/cli/commands/scope.ts:457` "transitionIssueXBrief(target.planHome, issueId, 'completed', 'completed')". 386 of the last 400 specs on main read `active`, none read `completed`. This is the trigger cell of the `active to completed` row. | +| 6 | The issue is closed | Only `pan scope cancel` (the dashboard's `Cancel issue` action deletes the workspace first, so it skips the spec) | `src/cli/commands/scope.ts:465` "transitionIssueXBrief(target.planHome, issueId, 'cancelled', 'cancelled')"; `src/lib/overdeck/issue-transitions.ts:182` "return 'xBRIEF cancel transition skipped: no workspace';"; `src/dashboard/frontend/src/components/IssueActionMenu/useIssueActions.ts:126` "return { wipeWorkspace: true };". This is the trigger cell of the `active to cancelled` row. | + +#### Verified, keep +- Plan dialog entry points: `issueActions.ts:615`, `KanbanCards.tsx:155`, `StartIssueDialog.tsx` (an unplanned issue opens the PlanDialog) +- Availability (`canPlan`): `issueActions.ts:522` +- Dialog controls, labels and defaults: `src/dashboard/frontend/src/components/PlanDialog.tsx:83`, `:88-89`, `:106`, `:115`, `:749-884` +- No harness picker is rendered: `src/dashboard/frontend/src/components/shared/ModelPicker/ModelPicker.tsx:448`. The harness comes from `roles.plan.harness`, else `claude-code`: `PlanDialog.tsx:206`. The server honors the explicit pick: `src/lib/harness-resolve.ts` +- Default effort `high`: `packages/contracts/src/effort.ts:12` +- `Done` appears once the plan is `proposed`: `src/dashboard/server/routes/misc/planning.ts:115`. `Accept plan`: `issueActions.ts:617` +- Stop, Abort and Done behaviors: `PlanDialog.tsx:378`, `:525`, `:645-652`, `:997-1014` +- `pan plan` flags: `src/cli/index.ts:303-310` +- Auto-mode `autoDecisions`: `spawn-planning-session.ts:296-303` +- `planning` and `planned` labels: `src/lib/overdeck/planning-sessions.ts:340`, `src/lib/overdeck/planning-promotion.ts:749` +- PRD minimum of 20 lines: `src/lib/pan-dir/drafts.ts:184` +- xBRIEF metadata enums and edge types: `src/lib/xbrief/types.ts:23-38` +- The AC gate runs in verification: `src/lib/cloister/verification-runner.ts:637` +- Finalize flags: `src/cli/index.ts:313-327` +- Exit codes: `src/cli/commands/plan-finalize.ts:224`, `:308`, `:339`, `:522` +- 90 s promotion timeout: `plan-finalize.ts:563` +- Critic labels, model setting, 9-minute wait and headings: `src/lib/planning/plan-critique.ts:9` and `:41-46`, `src/lib/planning/plan-critic-model.ts:17` and `:51-58`, `src/lib/planning/plan-critic-dispatch.ts:29` +- `pan task` verbs: `task.ts:272-289` +- Blocker wake every 120 s: `src/lib/cloister/blocker-wake.ts:37` +- Plan-integrity allowed fields: `src/lib/cloister/plan-integrity-gate.ts` +- `--skip-freshness`: `start-register.ts:28` +- `pan scope` help text is stale: `scope.ts:504` +- `planning.default_mode`: `src/lib/config-yaml/schema.ts:107` + +#### Labels needed +- None found. Whether `Remote (Fly.io)` needs one is listed as unsure above. + +#### Links +- All 7 internal links resolve, plus `#finalize-the-plan`. Row 2's new `#where-the-plan-lives` resolves to `### Where the plan lives`. + +#### Frontmatter +- title: keep. description: keep (145 chars). + +#### Help section +- Yes, lines 272-274, with both links. + +#### Follow-ups +- The `PlanEffortPicker.tsx` hints mention the probe pass only for `xhigh` and `max`, though `high` runs it. +- `scope.ts:504-528` help text is stale. +- Nothing sets `completed` on a spec, and the comment at `merge-agent.ts:233` ("Close-out flips the spec to completed/cancelled") is stale. +- The Cancel action never marks the spec `cancelled` because the workspace is gone by the time the transition runs. + +--- + +### features/flywheel.mdx + +Before: 189 lines, 0 dash lines, title "Flywheel: an autonomous loop that works your backlog", description 149 chars. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| 1 | A fifth step, parking, runs whenever | Another step, parking, runs whenever | The page lists five numbered phases first. `sync-sources/skills/pan-flywheel/SKILL.md:313` "## Phase 5 — Park what you cannot decide" | +| 2 | the only files it writes are `.pan/flywheel/state.md` and `.pan/flywheel/report.md`. | the only files it writes are `.pan/flywheel/state.md`, `.pan/flywheel/report.md` and its `.pan/parked.md` list. | `SKILL.md:317` "acceptance criteria. For those, write the issue to `.pan/parked.md` with a" | +| 3 | A failed UAT verdict at the head commit does block merge on its own, independent of this switch; | A failed UAT verdict at the head commit blocks merge only while the issue is held for UAT, so with this switch off and no `hold-for-uat` label or project hold, it does not block; | `src/lib/cloister/pr-facts.ts:971` "if (policy.uatRequired && facts.uatVerdict?.status === 'failed') {"; `src/lib/cloister/merge-gate.ts:101` "isFlywheelRequireUatBeforeMerge();" | +| 4 | They are global app settings, not per project. | They are global app settings, not per project, except that a project can opt out of the merge train with `merge_train: disabled` in `projects.yaml`. | `src/lib/overdeck/merge-sync.ts:78` "return project?.merge_train !== 'disabled';"; `src/lib/projects.ts:490` "merge_train?: 'enabled'" | +| 5 | The page never shows `idle` for a failed read; a failed read always shows `unreachable`. | A failed read never shows `idle`: before any status has loaded the chip shows `unreachable`; after that the chip keeps the last status and the Status tab notes that it is showing the last status. | `src/dashboard/frontend/src/pages/FlywheelPage.tsx:140` "const runChip = unreachable && !status"; `src/dashboard/frontend/src/components/flywheel/FlywheelStatusPane.tsx:71` "Showing the last status." | +| 6 | the merge train card (one per project, linking [Merge batches](/features/merge-batches)) | the **Merge train** card (every project's train in one card, with project filter chips; see [Merge batches](/features/merge-batches)) | `src/dashboard/frontend/src/components/flywheel/FlywheelMergeTrainRail.tsx:15` `label="Merge train"`; `:22` `placement="all-projects"`; `src/dashboard/frontend/src/components/merge-train/train/MergeTrain.tsx:4` "`all-projects` (Flywheel rail, Awaiting Merge): project filter chips" | +| 7 | **Start** then **Confirm start** | **Start `<ID>`** then **Confirm start** | `src/dashboard/frontend/src/components/flywheel/FlywheelNeedsYouCards.tsx:75` "Confirm start" (the label before it is `Start ${issueId}`) | +| 8 | **Show where this was raised** opens | The **show message** link (labelled "Show where this was raised" for screen readers) opens | `FlywheelNeedsYouCards.tsx:208` `aria-label="Show where this was raised"`; `:218` "show message" | +| 9 | those only ever show up on this page. | those show up on this page and as state `parked` in `pan show`. | `src/lib/overdeck/derived-issue-state.ts:212` "facts.parkedListed) return 'parked';" | +| 10 | There is no project picker yet. | There is no project picker yet, and a pass ranks only issues whose id starts with `PAN-` (Overdeck's own tracker), so on any other project the sequencer has nothing to rank. | `src/lib/backlog/sequencer-agent.ts:232` "const issues = allIssues.filter((issue) => issue.ref.toUpperCase().startsWith('PAN-'));" | + +#### Verified, keep +- `pan flywheel` verbs, flags and defaults: `src/cli/commands/flywheel.ts:239-284` +- Start refusals: `src/lib/flywheel/actions.ts:201-207` +- Phases, disk-low handling, cadence, idle stop, tick marker and rails: `SKILL.md:97-203`, `:260-295`, `:348-358` +- `maxAgents` defaults to 30 and only the loop's instructions enforce it: `src/lib/config-yaml/roles.ts:65`; no code reads `flywheel.maxAgents` +- `gh` shim refuses grant labels: `src/lib/launcher-git-guard.ts:31` +- Conversation name `conv-flywheel`: `src/lib/flywheel/constants.ts:7` +- Toolbar buttons and the Run config footer: `src/dashboard/frontend/src/components/flywheel/FlywheelConversationPane.tsx:175-272` +- Model `claude-opus-5-5` and effort `high`: `roles.ts:62-63` +- `pan orders start`: `src/cli/commands/orders.ts:144-145` +- Navigation entries: `src/dashboard/frontend/src/components/frame/LeftNav.tsx:98`, `src/dashboard/frontend/src/components/CommandPalette.tsx:483` +- Pickup rule: `src/lib/backlog/pickup.ts:123`. Autonomous dispatch checks the same labels: `src/lib/cloister/autonomous-work-dispatch.ts:194-234` +- Switch defaults: `control-settings.ts:189`, `:263`, `isMergeTrainEnabled` +- Settings → Merge Train: `MergeTrainBatchingSection.tsx:70-106` +- Header chip, freshness thresholds and counts: `FlywheelPage.tsx:140-172`, `FlywheelStatusPane.tsx:46` +- Rail tabs: `FlywheelPage.tsx:31` +- Seven lanes: `src/dashboard/frontend/src/components/flywheel/FlywheelLaneBoard.tsx:25-32` +- `pan parked` orbits and the 6 h threshold: `src/lib/parked/resolver.ts:75` +- Backlog nav entry, views, columns and buttons: `src/dashboard/frontend/src/components/frame/navGroups.ts:29`, `src/dashboard/frontend/src/pages/BacklogSequencerPage.tsx:330-401`, `:602`, `:613-621`, `:690-699`, `src/dashboard/frontend/src/components/backlog/BacklogForecast.tsx:141-142` +- Automatic pass at most every 30 min, on `roles.sequencer.model`: `src/lib/backlog/backlog-auto-trigger.ts:37`, `sequencer-agent.ts:273` +- `write-sequence` validation: `src/lib/backlog/types.ts:66-77`, `src/cli/commands/backlog-write-sequence.ts:32` +- Author gate: `SKILL.md:97-100`; #5544 is open + +#### Labels needed +- Already labeled early. Row 10 covers the Overdeck-only sequencer. + +#### Links +- All 9 internal links resolve. + +#### Frontmatter +- title: keep (sidebarTitle "Flywheel (early)"). description: keep (149 chars). + +#### Help section +- Yes, lines 187-189, with both links. + +#### Follow-ups +- `SKILL.md:251-252` tells the loop that `require_uat_before_merge` means UAT must pass before merge. The code does not require that. +- `SKILL.md:75-76` says the loop writes only two files, which contradicts its own Phase 5 (`:317`). +- `RolesPanel.tsx:92` falls back to `maxAgents: 8`, while the config default is 30. +- `roles.flywheel.scope` has no reader outside config validation and the Settings UI. +- The sequencer's `PAN-` filter is still in place (`sequencer-agent.ts:232`; PAN-1999 is meant to generalize it). +- #5544 (author gate) is open. + +## Appendix J: dashboard-views.mdx, costs.mdx, desktop-app.mdx (WI-J1 to WI-J3) + +Research pass output, base `2007e9a4d3c`, rows verified by the planner (anchor unique, evidence greps). + +### features/dashboard-views.mdx + +Before: 240 lines, 0 dash lines, title "Dashboard views: Home, Board, Pipeline and the Experimental switch", description 124 chars. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| 1 | `Analytics opens Metrics)` | `Analytics opens Metrics, which is experimental, so with [Experimental features](#experimental-features) off it lands on Home)` | `src/dashboard/frontend/src/components/Pipeline/PipelineView.tsx:478` "else if (label === 'Analytics') onTabChange('metrics');"; `src/dashboard/frontend/src/lib/experimentalFeatures.ts:11` "'metrics',"; `src/dashboard/frontend/src/App.tsx:410` "const nextTab = denyExperimental && isExperimentalTab(tab) ? 'home' : tab;" | +| 2 | `machine is linked. A memory line warns` | `machine is linked and Tailscale is not ready yet. A memory line warns` | `src/dashboard/frontend/src/components/home/AnywhereSetUpRow.tsx:21` "if (!noMachineLinked \|\| !tailscaleNotReady) return null;" | +| 3 | ``offers `list`, `edit`, `sync`, `diff`, `validate` and `migrate`.`` | ``offers `list`, `edit`, `sync`, `diff`, `validate`, `migrate` and `detach`.`` | `src/cli/index.ts:201` ".command('detach')" (a `pan context` subcommand) | +| 4 | `(only when non-empty), Just filed, Working now, Ready to merge, and Finished (up to 8 rows). Simple` | `(only when non-empty), Just filed, Working now, Ready to merge, and Finished (up to 8 rows); only Needs you and Working now show when empty. Simple` | `src/dashboard/frontend/src/components/simple/SimpleHomePage.tsx:316` "{filed.length > 0 && (", `:334` "{buckets.ready.length > 0 && (", `:343` "{buckets.finished.length > 0 && (" | + +#### Verified, keep +- Left nav: Project home (only with a real project selected), Flywheel with "running", Order books, and More with a menu labeled "More views". `src/dashboard/frontend/src/components/frame/LeftNav.tsx` "aria-label=\"More views\"", "data-testid=\"sidebar-flywheel-live\">running" +- More groups and items exactly as listed. `src/dashboard/frontend/src/components/frame/navGroups.ts` "export const MORE_GROUPS"; experimental items are filtered: `LeftNav.tsx` "experimentalFeaturesEnabled || !isExperimentalTab(item.id)" +- EXPERIMENTAL_TAB_IDS is agents, autopreso, resources, sessions, metrics, costs, health, god-view (not activity). `src/dashboard/frontend/src/lib/experimentalFeatures.ts` "export const EXPERIMENTAL_TAB_IDS" +- Every path in both tables. `src/dashboard/frontend/src/App/routes.ts` "export const TAB_PATHS" (kanban: '/board', etc.); `/command-deck/<project>/<issue>` and `/issues/<id>` are parsed in the same file. +- Experimental tabs redirect to Home once settings resolve to off. `App.tsx` "if (!experimentalFeaturesEnabled && isExperimentalTab(activeTab)) {" +- The brand opens Home. `src/dashboard/frontend/src/App/AppChrome.tsx` "title=\"Go to Home\"" +- Simple/Advanced: a fresh profile gets Simple, an existing one gets Advanced, stored per browser. `src/dashboard/frontend/src/lib/simple/uiMode.ts` "storage.getItem(LEGACY_FOOTPRINT_KEY) ? 'advanced' : 'simple'" +- Simple Home: "Hello.", the three stats, Finished capped at 8. `lib/simple/strings.ts` "greetingFallback: 'Hello.',"; `SimpleHomePage.tsx` "finished this week", "buckets.finished.slice(0, 8)" +- Advanced Home: "System briefing", the tiles Agents working, Paused, Ready to merge, Needs you and Cost today, and the Activity Feed, Workspaces, Knowledge Registry and Projects sections. `src/dashboard/frontend/src/pages/HomePage.tsx` +- Composer rows: `Ask <agent>:`, `Run in terminal:` (⌃↵), a Codex row when available and not selected, and Talk it through in Simple only. `home/homeComposerIntents.ts` "{ id: 'terminal', kind: 'terminal', keys: '⌃↵' }", "if (mode === 'simple') {"; `Stage/HomePane/Launcher.tsx` "return 'Run in terminal:'"; project chip "Add a project…" in `home/HomeComposerProjectChip.tsx` +- Get set up card: + - Title and subtitle: `lib/simple/strings.ts` "title: 'Get set up'," + - Herdr row only when the backend is not tmux: `GetSetUpCard.tsx` "if (report.backend && report.backend.name !== 'tmux') {" + - A failing required check keeps it visible after dismissal: `GetSetUpCard.tsx` "check.required && !check.found" + - The top banner is hidden on Home: `SetupChecklistBanner.tsx` "Hidden on the Home tab" +- Board: + - Columns Backlog, Plan, Work, Review, Done; Done capped at 12: `KanbanBoard/planColumns.ts` "export const DONE_DISPLAY_LIMIT = 12;" + - Needs-you kinds: `KanbanBoard/NeedsYouStrip.tsx` "label: 'Plan ready'" + - Filter bar: `KanbanBoard/views/KanbanFilterBar.tsx` "Cycle:", "Include closed-out", "Force refresh all trackers", "{projects.length > 1 && (" + - Keyboard j/k/Enter: `KanbanBoard.tsx` + - Drag only reorders within a column, in local state: `KanbanBoard/hooks/useDragDrop.ts` "if (activeStatus && activeStatus === overStatus) {" +- Pipeline: + - Tiles, List/Board/Analytics switch and URL filters: `PipelineView.tsx` + - Ready rule: `lib/pipeline-state.ts` "issue.labels?.includes('ready')", "export const PIPELINE_BOARD_PHASES" + - Blocked = red checks or not mergeable: "derived.pr.checks === 'red'" + - auto/hold/default badge: `AutoMergeToggle.tsx` "'auto' : autoMerge === false ? 'hold' : 'default'" +- Awaiting Merge: every label in the section. `AwaitingMergePage.tsx` "Nothing awaiting merge.", "Rebuild to UAT", "Blocked from Merge", "Pipeline Override", "confirmLabel: 'Force Merge'"; `merge-train/MergeTrainSection.tsx` "aria-label=\"Merge train\""; `merge-train/MergePolicySection.tsx` "Merge policy" +- Issue drawer: + - Escape closes it: `drawer/IssueDrawer.tsx` + - Open pull request is pinned in the action strip: `drawer/DrawerActionBar.tsx` "pinRight={['viewPr']}" + - Phase strip: `lib/simple/phases.ts` "export const PHASES = ['plan', 'work', 'review', 'test', 'ship', 'done']" + - Nine tabs and their sub-views: `issue-detail/issueTabs.ts` "ISSUE_DETAIL_TABS", "ISSUE_TAB_VIEWS" + - Decisions only for Deft: `IssueDetail.tsx` "if (!isDeft) hidden.add('decisions');" + - Skills hides when no project owns the issue: `skills/SkillOverridesPanel.tsx` "query.error.code === 'unknown-issue'" + - Open tracker: `Stage/cockpit/IssueMissionControl.tsx` +- Activity: the Needs you / Project / Global scopes and All / Chats / Activity tabs are in `ActivityFeedTab.tsx`. The streams are gated: `ActivityPanel.tsx` "const streams = experimentalFeaturesEnabled ? ACTIVITY_STREAMS : (['feed'] as const);" +- Knowledge: `knowledge/KnowledgePage.tsx` "No knowledge bundle configured", "/okf init", "viewer edits are discarded"; `pan knowledge open` in `src/cli/commands/knowledge.ts` +- Context: `context/ContextPage.tsx` "Agent context", "Edit source", "Preview for agent", "Save & refresh outputs" +- Skills: `skills/SkillOverridesPanel.tsx` "title: 'Project'", "['below', 'Overridden below']", "Filter skills by name or description" +- Settings: the section list matches `Settings/settingsPageConstants.ts` "SETTINGS_NAV_ITEMS" exactly. Desktop App renders only in the app: `DesktopSettingsSection.tsx` "if (!isDesktopApp()) return null;" +- Experimental section: its subtitle, the three other toggles, and a switch description that names Activity and Skills. `Settings/sections/ExperimentalSection.tsx` +- Experimental views: + - `/agents?view=history` opens the Agents Directory: `Agents/FleetAgentsView.tsx` + - Page headers: `ConversationsPage.tsx` "Session History", `MetricsPage.tsx` "Metrics Dashboard", `CostsPage.tsx` "Cost Tracking" +- AutoPreso: + - Canvas is view-only when live: `autopreso/AutoPresoView.tsx` "viewModeEnabled={mode === 'live'}" + - Controls: `autopreso/AutoPresoControls.tsx` "'Go live' : 'Back to staging'", "Reset session" + - Voice settings: `VoiceSettingsSection.tsx` "STT provider", "AutoPreso provider", "AutoPreso model" + - Moonshine is a local sidecar: `src/voice/transcription.ts` "Moonshine sidecar binary not found" + +#### Labels needed (experimental / early / testing) +- The eight experimental views are labeled. The only unlabeled route into one is the Pipeline Analytics button (row 1). + +#### Links +- all 20 internal links resolve + +#### Frontmatter +- title: keep +- description: keep (124 chars) + +#### Help section +- yes; `## Get help` (lines 237-240) has Discord and GitHub Issues. + +#### Follow-ups +- The Experimental features switch description (`ExperimentalSection.tsx:78`) still lists Activity and Skills, which aren't gated. The code text is stale. +- Pipeline filters: + - The `Blocked` and `No PR` buttons force the phase to Ship (`PipelineView.tsx:445` "updateFilter({ ...filter, phase: 'ship', [modifier]: !filter[modifier] }, 'ship');"). + - `No PR` keeps issues that have an open, not-ready PR (`isOpenMergeRequest`). The label contradicts the behavior. +- The Analytics button silently lands on Home with the switch off (same class as #5562 item 4). + +### features/costs.mdx + +Before: 164 lines, 0 dash lines, title "Costs and spend: how Overdeck tracks what agents cost", description 146 chars. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| 1 | `prices Claude Code, Codex, Kimi, Grok and Muse` | `prices Claude Code, Codex, Kimi and Muse` | `src/lib/costs/grok-collector.ts:53` "if (typeof usage.costUsd === 'number' && Number.isFinite(usage.costUsd)) return usage.costUsd;" | +| 2 | `sessions. Pi is the exception: a Pi session uses the cost Pi itself reports for a message when Pi` | `sessions. Pi and Grok are the exceptions: a Pi or Grok session uses the cost the harness itself reports when it` | `src/lib/costs/grok-collector.ts:53` (same quote); `src/lib/cost-parsers/ohmypi-parser.ts:334` "const hasInlineCost = usage.cost?.total !== undefined;" | +| 3 | ``and Pi and Muse record it with a cost of `0` `` (no trailing space: `and Pi and Muse record it with a cost of` then backtick 0 backtick) | ``and Pi, Grok and Muse record it with a cost of `0` `` | `src/lib/costs/grok-collector.ts:55` "if (!pricing) return 0;" | +| 4 | `followed by a number, the event` | ``followed by a hyphen and a number (for example `feature/pan-123`), the event`` | `sync-sources/hooks/heartbeat-hook:88` "if [[ \"$GIT_BRANCH\" =~ (pan\|min\|aud\|krux\|cli\|PAN\|MIN\|AUD\|KRUX\|CLI)[-]([0-9]+) ]]; then" | +| 5 | `the day seven days ago, and **month** covers the last 30 days.` | `the UTC day seven days ago, and **month** starts at the beginning of the UTC day 30 days ago.` | `src/lib/costs/request-digest.ts:76` "const day = (ms: number) => new Date(ms).toISOString().split('T')[0]!;", `:77` "week: day(now - 7 * 24 * 60 * 60 * 1000), month: day(now - MONTH_MS)" | + +All anchors checked with `grep -c -F`: each prints 1. + +#### Verified, keep +- Capture paths: + - `heartbeat-hook` is a PostToolUse hook: `src/lib/claude-hooks-registration.ts` "{ hookType: 'PostToolUse', scriptName: 'heartbeat-hook' }," + - An unpriced model is skipped: `sync-sources/hooks/record-cost-event.ts` "if (!pricing) continue;" + - Only Pi and Codex are swept, at startup and every 5 minutes: `src/dashboard/server/services/cost-reconcile-service.ts` "const RECONCILE_INTERVAL_MS = 5 * 60_000;", sources 'pi' and 'codex' only +- Storage: + - Archive: `src/lib/costs/events.ts` "return join(getCostsDir(), 'events.jsonl');" + - Table: `src/lib/overdeck/cost.ts` "sqliteTable('cost_events'" + - `pan cost backfill --write`: `src/cli/commands/cost.ts` "'--write', 'Persist non-duplicate reconstructed cost events'" +- Pricing exceptions: + - Pi `unpriced-model`: `ohmypi-parser.ts` "if (!pricing) return { cost: 0, reason: 'unpriced-model' };" + - Muse records 0: `muse-parser.ts` "const cost = pricing ? requests.reduce" +- Buckets: `src/dashboard/frontend/src/lib/cost-bucket-labels.ts` "FLYWHEEL: 'Flywheel orchestration'," +- Windows and project scope: + - Today = local midnight: `request-digest.ts` "return new Date(d.getFullYear(), d.getMonth(), d.getDate()).toISOString();" + - Project spend includes conversations: `src/dashboard/server/routes/costs.ts` "a project's spend includes its conversations' events" +- Project Home spend fact: + - Labels: `Stage/HomePane/HomeFacts.tsx` "Spend this week", "needs an issue prefix" + - Timeout: `useHomeData.ts` "export const SPEND_TIMEOUT_MS = 20_000" + - Click target: `Stage/ProjectHome.tsx` "onSpend={() => navigate('/costs', 'costs')}" +- Drawer and board: + - Total row: `issue-detail/IssueDrawerDetails.tsx` "Total" + - Cost breakdown renders `CostsTab`, which has "By stage" and "By model": `IssueDrawerDetails.tsx` "<CostsTab issueId={issueId} />" + - Board badge: `KanbanBoard/cards/KanbanCards.tsx` "<CostBreakdownModal" +- Costs page: + - Header, tabs, cards, trend, list and Full detail: `CostsPage.tsx` + - Event Count is the issue-row count: `services/dashboard-cost-snapshot.ts` "eventCount: issues.length" + - Budget warnings are always false: `src/lib/overdeck/cost-sync.ts` "budgetWarning: false," + - Experiments keys: `domain-mergers.ts` "if (caveman.ab_test !== undefined) {" + - Machines tab: `costs/FleetUsagePanel.tsx` "All machines" +- CLI: + - `pan cost issue` output, with `--days` ignored on the aggregate path: `src/cli/commands/cost.ts` "const aggregate = getCostForIssueAggregate(issueId);", "By Review Role", "By Agent" + - `pan cost effort` `--issue` and `--json`, `unrecorded` bucket: `cost-sync.ts` "NULL rows bucket as `unrecorded`" + - Zero reports: `src/lib/cost.ts` reads `costs-${date}.jsonl`, and the only `getCostFile(` calls are its definition and one read; `spent: 0,` is never updated + - `pan cost sync`: `src/lib/costs/wal.ts` ".pan/events/ISSUE-ID.jsonl" + - `pan conv cost`: `conversations/index.ts` "Summarize estimated API costs across discovered sessions" +- Cost limits: + - Keys and file: `src/lib/cloister/config.ts` "join(OVERDECK_HOME, 'cloister.toml')", "per_issue_usd?: number" + - `alert_threshold` default: `cost-monitor.ts` "config.alert_threshold ?? 0.8" + - Log line only: `grep -rn "cost_alert" src` matches only the emit in `service-health.ts` and two type unions + +#### Labels needed (experimental / early / testing) +- None missing. + +#### Links +- all 12 internal links resolve + +#### Frontmatter +- title: keep +- description: keep (146 chars) + +#### Help section +- yes; `## Get help` (lines 151-154) has both links. + +#### Follow-ups +- The comment at `src/lib/cloister/config.ts:282` says "config.yaml"; the loader reads `cloister.toml`. The comment is stale. +- The heartbeat hook also falls back to the workspace path (`heartbeat-hook:93`). This is undocumented; adding it is optional. + +### features/desktop-app.mdx + +Before: 179 lines, 0 dash lines, title "Desktop app for macOS, Windows and Linux", description 126 chars. + +#### Change table +| # | Grep anchor | Change | Evidence | +|---|---|---|---| +| 1 | ``On Linux, `pan up` also treats `~/.local/bin/overdeck` as the app. The install script puts the `overdeck` command there,`` | ``On Linux, `pan up` also treats `~/.local/bin/overdeck`, `~/.local/share/applications/overdeck` and `/usr/local/bin/overdeck` as the app, and checks them before `~/Applications/`. The install script puts the `overdeck` command in `~/.local/bin`,`` | `src/cli/index.ts:737` "join(home, '.local', 'share', 'applications', 'overdeck'),", `:738` "'/usr/local/bin/overdeck',"; these are pushed before the `~/Applications` glob and the first existing path wins; `scripts/install.sh:17` "INSTALL_PREFIX=${OVERDECK_INSTALL_PREFIX:-\"$HOME/.local\"}" | +| 2 | ``The app's embedded server listens on port `7825` (it is not the `pan up` dashboard's port).`` | ``The app's embedded server listens on port `7825` (it is not the `pan up` dashboard's port); while it restarts after crashes, the port is `7825` plus the number of consecutive restarts since the last healthy start, at most `7833`.`` | `apps/desktop/src/server.ts:23` "const BASE_PORT = 7825;", `:47` "return BASE_PORT + (restartAttempt % 10);", `:25` "const MAX_RESTART_ATTEMPTS = 8;", `:122` "restartAttempt = 0;" | +| 3 | `after five reminders, or once you enable it, the reminders stop.` | `the toasts count up to "Reminder 5 of 5" (four toasts after the first dialog); after that, or once you enable it, the reminders stop.` | `apps/desktop/src/autostart.ts:19` "const NAG_MAX = 5;", `:6` "Launch 2-5: In-app toasts"; `src/dashboard/frontend/src/App.tsx:708` "toast(`Reminder ${count} of ${max}" | +| 4 | ``(a version ending in `-canary`)`` | ``(a version containing `-canary`, such as `1.2.3-canary.1`)`` | `apps/desktop/src/main.ts:622` "const updateChannel = app.getVersion().includes(\"-canary\") ? \"beta\" : \"latest\";"; `.github/workflows/release.yml:30` "-canary\.[0-9]+$" | + +#### Verified, keep +- Build targets: AppImage x64, dmg arm64 and nsis x64 in `apps/desktop/package.json` (one arch each, so no Intel Mac or ARM Linux/Windows build). Release uploads `*.AppImage`, `*.dmg` and `*.exe` in `.github/workflows/release.yml`. +- npm package: + - Launcher message: `apps/desktop/bin/overdeck.mjs` "[overdeck] Node.js 22 or later is required (found ${process.versions.node})." + - Bin name: "overdeck-desktop": "./bin/overdeck.mjs" + - Electron becomes a runtime dependency on publish: `scripts/build-for-publish.mjs` "Promote electron to dependencies" +- `pan up`: + - Launch messages: `src/cli/index.ts` "Launching Overdeck desktop app...", "Could not launch desktop app", "Desktop app launched" + - `--no-open` skips the app: "if (electronAppPath && options.open !== false) {" + - The macOS and Windows candidate paths are in the same block. +- Window behavior: + - Single instance with `--open <path>`: `apps/desktop/src/main.ts` "if (!app.requestSingleInstanceLock()) {", "argv.indexOf(\"--open\")" + - Close hides on macOS and window-all-closed quits elsewhere: `main.ts` "if (!isQuitting && process.platform === \"darwin\") {", "app.on(\"window-all-closed\"" +- Tray: + - Menu items, and Use This Computer enabled only for a remote machine: `apps/desktop/src/tray.ts` "enabled: getActiveDashboard().kind === \"remote\"," + - Icon, tooltip and badge never change: they read `agentCount` and `attentionCount` from `/api/health`, whose body (`src/dashboard/server/health-response.ts` "interface DashboardHealthBody") has neither field. +- App menu: items, the disabled "Showing <label>" row, Help items and Install Update and Restart in `apps/desktop/src/menu.ts`. +- Notifications are the renderer's web Notifications, not the desktop switches: + - Permission prompt repeats: `usePermissionNotifications.ts` "PERMISSION_RENOTIFY_AFTER_MS = [5 * 60_000, 30 * 60_000]", "'Permission needed'" + - `grep -rn "bridge.*notify" src/dashboard/frontend/src` has no match. +- Desktop settings: + - Switch labels: `Settings/DesktopSettingsSection.tsx` "label: 'Merge Ready'", "System Tray", "Launch at login", "Reset reminder" + - Launch at login sets the login item: `main.ts` "app.setLoginItemSettings({ openAtLogin: value === true });" + - Settings file: `apps/desktop/src/settings.ts` "desktop-settings.json" +- Updater: + - Timing and no auto-download: `apps/desktop/src/updater.ts` "setTimeout(() => { void checkForUpdates(); }, 5_000);", "FOUR_HOURS_MS", "autoUpdater.autoDownload = false;" + - The version button opens the updater: `LeftColumnFooter.tsx` "the version button (opens the updater" +- Pairing: + - Pair a device: `Settings/sections/AnywhereSection.tsx` "Pair a device" + - Paired devices: `anywhere/DevicesPanel.tsx` "Paired devices" + - CLI: `src/cli/commands/pair.ts` "'--url <base>'", ".command('revoke <id>')" + - Device name: `machine-client.ts` "`Overdeck desktop on ${OS.hostname()}`" +- Connect window: `connect-window.ts` "Open another machine"; `resources/connect.html` "Use this computer", "Connect", "\"Open \" + machine.label", "\"Forget \" + machine.label" +- Address rules and refusal messages: `apps/desktop/src/machine-url.ts` "Paste the whole pairing link, including the address.", "100.64.0.0", "fd7a:115c:a1e0::", "127.0.0.0", ".ts.net" +- The five failure messages, verbatim: `apps/desktop/src/machine-client.ts` +- Credential storage: + - safeStorage, refusing basic_text/unknown backends: `machine-store.ts` "if (backend === \"basic_text\" || backend === \"unknown\")" + - Record file: "remote-machine.json" + - The remote session stays in memory: `connection.ts` "No `persist:` prefix" + +#### Labels needed (experimental / early / testing) +- None; the known-broken settings already cite #5556 and #5557. + +#### Links +- all 10 internal links resolve + +#### Frontmatter +- title: keep +- description: keep (126 chars) + +#### Help section +- yes; `## Get help` (lines 166-170) has both links. + +#### Follow-ups +- The Overdeck menu's **Open Workspace** submenu (`menu.ts:188`) only ever shows a disabled "Loading..." row: `buildWorkspaceSubmenu` (`menu.ts:68`) is never called. The page omits it; keep it omitted. +- `pan up` treating `/usr/local/bin/overdeck` as the desktop app has the same failure as #5557 for a global npm install under `/usr/local`. +- Notarization: `package.json` has `"notarize": false`, but `scripts/notarize.cjs` notarizes in CI when the Apple secrets exist. The page's "not notarized yet" can't be confirmed from the repo. diff --git a/.pan/specs/2026-11-19-PAN-5502-docs-accuracy-audit-features-14-pages.xbrief.json b/.pan/specs/2026-11-19-PAN-5502-docs-accuracy-audit-features-14-pages.xbrief.json new file mode 100644 index 00000000000..e4f9996d347 --- /dev/null +++ b/.pan/specs/2026-11-19-PAN-5502-docs-accuracy-audit-features-14-pages.xbrief.json @@ -0,0 +1,1846 @@ +{ + "xBRIEFInfo": { + "version": "0.8", + "created": "2026-11-19T07:00:00Z", + "author": "overdeck/0.0.0", + "description": "Plan for PAN-5502: docs: accuracy audit, Features (14 pages)", + "updated": "2026-11-19T05:28:52.680Z" + }, + "plan": { + "id": "pan-5502", + "title": "docs: accuracy audit, Features (14 pages)", + "status": "running", + "uid": "7116823f-d859-4aba-9833-11a97b0fc506", + "author": "agent:claude-opus-5-5", + "sequence": 5, + "created": "2026-11-19T07:00:00Z", + "updated": "2026-11-19T05:28:52.680Z", + "references": [ + { + "uri": "https://github.com/eltmon/overdeck/issues/5502", + "label": "PAN-5502", + "type": "issue" + }, + { + "uri": "https://github.com/eltmon/overdeck/issues/5467", + "label": "PAN-5467 (epic)", + "type": "issue" + } + ], + "tags": [ + "docs", + "audit", + "mintlify", + "features" + ], + "narratives": { + "Problem": "The Features docs pages describe removed views (mission-control Activity View, Badge Bar, Status Reviews), removed skills and subagents, wrong pan handoff flags, a test agent that is never dispatched, wrong workspace paths and planning artifacts, stale screenshots, and wrong merge-train behavior. Several pages have en/em dashes, generic titles and broken links.", + "Proposal": "The planner already audited all 20 pages in the Features nav group against main 2007e9a4d3c; .pan/drafts/PAN-5502.md holds verified change tables (grep anchor, replacement, code evidence) per page in Appendices A to J. One item per page (three section items for conversations.mdx, two for workspaces.mdx) applies its table, removes dashes, fixes frontmatter, deletes images of removed UI and checks links; a final item runs lint:docs and the Mintlify validators and drafts the per-page PR body. One PR.", + "NonGoals": "- No code, test, rule, docs.json, CLAUDE.md, README.md or changelog.d change; code bugs become PR-body Follow-ups.\n- No page outside the Features nav group.\n- No new pages, navigation changes, file renames or slug changes.\n- No heading renames or deletions except those listed in the PRD's NFR-2.\n- No screenshots added, replaced or recaptured and no image files deleted; only alt text changes and the ThemedImage removals listed in FR-8.\n- No help section added to pages without a troubleshooting section.\n- No change to the macOS ⌘W/⌘T shortcut lines (needs a real-Mac check).\n- No description of intended behavior as current (for example #5537's test dispatch)." + }, + "autoDecisions": [ + { + "summary": "Audit all 20 pages in the Features nav group, not only the 14 listed", + "rationale": "The issue's scope sentence is every published page in the group; the six added pages are in no sibling audit issue's body, and PAN-5503 made the same call." + }, + { + "summary": "Audit the five prerequisite-PR pages on top of their merged results, including swarm.mdx", + "rationale": "All of #5474, #5472, #5471, #5479 and #5482 merged and their commits are in each page's history; PAN-5482 landed, so its result is audited with six small rows." + }, + { + "summary": "Add Discord and GitHub Issues links only to pages with troubleshooting sections lacking them", + "rationale": "The issue asks for the links where a page talks about getting help; skill-packs, convoys and workspaces are the only such pages without them." + }, + { + "summary": "Rewrite wrong alt text, delete ThemedImage blocks that show removed UI, list recaptures as Follow-ups", + "rationale": "A screenshot of a removed harness picker is a wrong claim; recapturing images needs a live dashboard and is outside a text audit." + }, + { + "summary": "Retitle generic one- or two-word titles and keep the old title as sidebarTitle", + "rationale": "The issue asks for specific searchable titles; sidebarTitle keeps navigation labels short, matching PAN-5503." + }, + { + "summary": "Describe current code behavior where code is buggy and list the bug as a Follow-up", + "rationale": "The issue is docs-only; describing intended behavior (for example test dispatch after approval, #5537) would reintroduce inaccuracy." + }, + { + "summary": "Split conversations.mdx into three section items and workspaces.mdx into two, chained by blocks edges", + "rationale": "conversations.mdx is 1,346 lines with 48 rows and workspaces.mdx has 35 rows; section items stay reviewable and the edges serialize shared-file edits." + } + ], + "metadata": { + "sizeJustification": "Every item edits one Mintlify page in the single features/ directory; the finalize lint counts each features/<page>.mdx as its own subsystem, so 20 pages read as 20 subsystems. The epic (#5467) scopes one audit issue per docs nav group, and the pages share one validation pass and one PR body, so splitting into sibling issues would duplicate the validator and PR-body work without adding review isolation. The plan touches exactly 20 files, under the 25-file limit.", + "canonicalFilename": "2026-11-19-PAN-5502-docs-accuracy-audit-features-14-pages.xbrief.json", + "promotionIntent": "automatic" + }, + "items": [ + { + "id": "conv-surface", + "title": "conversations.mdx: fix lines 1-555 (hero alt, model lock, header menu, Machine field)", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/conversations.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "awk '/^## Why hand off/{exit} {print}' features/conversations.mdx | grep -cP '[\\x{2013}\\x{2014}]' || true", + "npm run lint:docs" + ], + "expected_outputs": [ + "the range-bounded dash count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Shares conversations.mdx with conv-handoff and conv-machines-to-end; the blocks edges serialize them.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-8" + ] + }, + "narrative": { + "Action": "Apply WI-A1 (Appendix A, 11 rows) to features/conversations.mdx from the frontmatter to the line before `## Why hand off?` only. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: conv-surface, the AC trailers and a 'PR-note: features/conversations.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "conv-surface.ac1", + "title": "features/conversations.mdx no longer contains `Hot-swap the model for the next message` and contains `the model is fixed once a conversation starts`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "conv-surface.ac2", + "title": "The hero ThemedImage alt text contains `Command Deck on a project's home tab` and no longer contains `the agent's turn-by-turn tool calls`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "conv-surface.ac3", + "title": "The New conversation with options field list contains a `**Machine.**` bullet naming `**Auto**` and `**Fly (new VM)**`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "conv-surface.ac4", + "title": "The header menu step 4 contains `**Add skills…**` and the status-line sentence contains `show only in a Command Deck tab`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "conv-surface.ac5", + "title": "`awk '/^## Why hand off/{exit} {print}' features/conversations.mdx | grep -cP '[\\x{2013}\\x{2014}]'` prints 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "conv-handoff", + "title": "conversations.mdx: fix lines 556-959 (handoff dialog, pan handoff flags, PRs)", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "complex", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/conversations.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "awk '/^## Why hand off/{f=1} /^## Conversations from your other machines/{exit} f' features/conversations.mdx | grep -cP '[\\x{2013}\\x{2014}]' || true", + "npm run lint:docs" + ], + "expected_outputs": [ + "the range-bounded dash count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Shares conversations.mdx with conv-surface and conv-machines-to-end; the blocks edges serialize them.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-8" + ] + }, + "narrative": { + "Action": "Apply WI-A2 (Appendix B, 28 rows and blocks B5, B6, B13, B19, B24) plus planner rows P1 and P2 (delete the continue-modal and continue-modal-advanced ThemedImage blocks) to features/conversations.mdx from `## Why hand off?` to the line before `## Conversations from your other machines` only. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: conv-handoff, the AC trailers and a 'PR-note: features/conversations.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "conv-handoff.ac1", + "title": "The `pan handoff` option table contains rows for `--allow-primary`, `--issue <id>`, `--role <role>` and `--title <title>`, and the `--harness` row contains `Accepted and ignored`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "conv-handoff.ac2", + "title": "The handoff bash example no longer contains `pan handoff source-conv --harness pi` or `--cwd ../isolated-worktree`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "conv-handoff.ac3", + "title": "The fallback table contains a `handoff-request-failed` row and the `source-ended` reason contains `(source-authored handoffs only)`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "conv-handoff.ac4", + "title": "features/conversations.mdx no longer contains `continue-modal-light.png` or `continue-modal-advanced-light.png` and still contains `continue-help-light.png`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "conv-handoff.ac5", + "title": "The page no longer contains `](../configuration/mcp.mdx)` and contains `/configuration/mcp#pull-requests`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "conv-machines-to-end", + "title": "conversations.mdx: fix lines 960-end and run the page-wide checks", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/conversations.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/conversations.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Shares conversations.mdx with conv-surface and conv-handoff; the blocks edges serialize them.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Apply WI-A3 (Appendix C, 9 rows) to features/conversations.mdx from `## Conversations from your other machines` to the end, then run the page-wide dash and link checks for the whole page. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: conv-machines-to-end, the AC trailers and a 'PR-note: features/conversations.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "conv-machines-to-end.ac1", + "title": "features/conversations.mdx no longer contains `Arrives in the next release (v0.65.0)`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "conv-machines-to-end.ac2", + "title": "The palette sentence contains `⌘K` / `Ctrl+K` and the stop sentence no longer contains `\"Stop agent\" in the row menu`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "conv-machines-to-end.ac3", + "title": "The search settings paragraph contains `Session embeddings` and the snooze sentence no longer contains `**Custom…**`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "conv-machines-to-end.ac4", + "title": "`grep -cP '[\\x{2013}\\x{2014}]' features/conversations.mdx` prints 0 for the whole page", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-skill-packs", + "title": "skill-packs.mdx: fix dashboard add, default refs, MCP harnesses and Atlassian auth", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/skill-packs.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/skill-packs.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6" + ] + }, + "narrative": { + "Action": "Apply WI-D1 (Appendix D, 10 rows), retitle with sidebarTitle 'Skill Packs', and remove all 19 dash lines in features/skill-packs.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-skill-packs, the AC trailers and a 'PR-note: features/skill-packs.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-skill-packs.ac1", + "title": "features/skill-packs.mdx no longer contains `The dashboard can turn packs on and off but not add them` and contains `Available packs`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-skill-packs.ac2", + "title": "The mattpocock sentence contains `has no default ref` and the MCP sentence names `grok` and `pi`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-skill-packs.ac3", + "title": "The Atlassian auth sentence contains `*.atlassian.net`, and the page contains `discord.gg/ZpHE2ZTv5P` after `## Troubleshooting`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-skill-packs.ac4", + "title": "The frontmatter contains `sidebarTitle: \"Skill Packs\"` and `grep -cP '[\\x{2013}\\x{2014}]' features/skill-packs.mdx` prints 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-skills", + "title": "skills.mdx: fix the Skills page, shipped skill list, harness targets and broken links", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "complex", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/skills.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/skills.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-8" + ] + }, + "narrative": { + "Action": "Apply WI-E1 (Appendix E part skills.mdx, 28 rows) plus planner row P3 (delete the skills screenshot block), retitle with sidebarTitle 'Skills System', change the description, and remove all 6 dash lines in features/skills.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-skills, the AC trailers and a 'PR-note: features/skills.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-skills.ac1", + "title": "features/skills.mdx no longer contains any of `pan-approve`, `pan-rescue`, `opus-plan`, `beads`, `Antigravity` or `Windsurf`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-skills.ac2", + "title": "The custom-skill example creates `SKILL.md` (not `skill.md`) and contains `name: my-custom-skill` frontmatter", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-skills.ac3", + "title": "The page no longer contains `/cli/core-commands` and no longer contains `skills-light.png`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-skills.ac4", + "title": "The page no longer contains `### Code Review Subagents` and contains `### Code review` linking `/features/convoys`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-skills.ac5", + "title": "The frontmatter contains `sidebarTitle: \"Skills System\"` and a description naming `Claude Code, Codex and Pi`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-safe-shutdown", + "title": "safe-shutdown.mdx: correct the reboot timeout, pan down scope and drain flags", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/safe-shutdown.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/safe-shutdown.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Apply WI-E2 (Appendix E part safe-shutdown.mdx, 4 rows) and retitle with sidebarTitle 'Safe shutdown' in features/safe-shutdown.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-safe-shutdown, the AC trailers and a 'PR-note: features/safe-shutdown.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-safe-shutdown.ac1", + "title": "features/safe-shutdown.mdx no longer contains `5 seconds to exit` and the `pan down` sentence contains `review sessions`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-safe-shutdown.ac2", + "title": "The command block contains `pan shutdown --no-wait` and the dashboard note contains `pan reload` or `pan restart` is in progress", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-safe-shutdown.ac3", + "title": "The frontmatter contains `sidebarTitle: \"Safe shutdown\"` and a title that contains `pan shutdown`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-swarm", + "title": "swarm.mdx: define slot-eligible and correct steal, Inherit global and defaults", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/swarm.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/swarm.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Apply WI-E3 (Appendix E part swarm.mdx, 6 rows) to features/swarm.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-swarm, the AC trailers and a 'PR-note: features/swarm.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-swarm.ac1", + "title": "features/swarm.mdx contains `files_scope_confidence` in the slot-eligible definition and contains `swarm.policy.mode=always`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-swarm.ac2", + "title": "The project select sentence contains `Inherit global` and the `--steal` sentence contains `nothing checks who passes it`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-swarm.ac3", + "title": "The Settings sentence contains the defaults `Off`, `3 slots` and `1 to 12`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "workspaces-layout-to-lifecycle", + "title": "workspaces.mdx: fix lines 1-340 (paths, planning artifacts, Docker, destroy)", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "complex", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/workspaces.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/workspaces.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Shares workspaces.mdx with workspaces-safeguards-to-end; the blocks edge serializes them.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-8" + ] + }, + "narrative": { + "Action": "Apply WI-F1 (Appendix F rows 1-20 and blocks 6, 7, 20) plus planner row P4 (board alt text) to features/workspaces.mdx from the frontmatter to the line before `## Main Project Branch Convention` only. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: workspaces-layout-to-lifecycle, the AC trailers and a 'PR-note: features/workspaces.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "workspaces-layout-to-lifecycle.ac1", + "title": "features/workspaces.mdx no longer contains `{project}/workspaces/{issue-id}/` and contains `workspaces/feature-<issue>/`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "workspaces-layout-to-lifecycle.ac2", + "title": "The section before `## Main Project Branch Convention` no longer contains `.planning/`, `STATE.md` or `beads`, and the planning section contains `.pan/drafts/<issue>.md`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "workspaces-layout-to-lifecycle.ac3", + "title": "The Docker section no longer contains `docker compose -p \"{project}-feature-{issue}\"` and the checkbox default contains `Off`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "workspaces-layout-to-lifecycle.ac4", + "title": "The destroy block no longer contains `safe - checks for uncommitted changes` or `pan workspace destroy MIN-123 --force`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "workspaces-layout-to-lifecycle.ac5", + "title": "The board alt text contains `Board view:` and no longer contains `cost badges`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "workspaces-safeguards-to-end", + "title": "workspaces.mdx: fix lines 341-end (roles, safeguards, Fly) and page-wide checks", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/workspaces.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/workspaces.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Shares workspaces.mdx with workspaces-layout-to-lifecycle; the blocks edge serializes them.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7" + ] + }, + "narrative": { + "Action": "Apply WI-F2 (Appendix F rows 21-35 and blocks 22, 23) to features/workspaces.mdx from `## Main Project Branch Convention` to the end, then run the page-wide dash and link checks. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: workspaces-safeguards-to-end, the AC trailers and a 'PR-note: features/workspaces.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "workspaces-safeguards-to-end.ac1", + "title": "features/workspaces.mdx no longer contains `### Specialist Agent Safeguards` and contains `### Agent safeguards` naming `OVERDECK_AUTO_REVERT_CHECKOUT` or the post-checkout hook", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "workspaces-safeguards-to-end.ac2", + "title": "The planning safeguard contains `Cannot start planning: work agent already running` and `**Accept plan**`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "workspaces-safeguards-to-end.ac3", + "title": "The Resources sentence contains `Experimental features` and the page contains `discord.gg/ZpHE2ZTv5P`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "workspaces-safeguards-to-end.ac4", + "title": "The page no longer contains `docs/prds/active/` and `grep -cP '[\\x{2013}\\x{2014}]' features/workspaces.mdx` prints 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-specialists", + "title": "specialists.mdx: describe today's test dispatch and merge paths", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/specialists.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/specialists.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Apply WI-G1 (Appendix G part specialists.mdx, 4 rows) to features/specialists.mdx; the Test step must describe today's behavior and link #5537. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-specialists, the AC trailers and a 'PR-note: features/specialists.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-specialists.ac1", + "title": "features/specialists.mdx contains `Nothing starts a test agent automatically after the review approves` with a link to issue 5537", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-specialists.ac2", + "title": "The Merge step contains `hold-for-uat`, `five minutes` and `merges a clean, up-to-date PR as it is`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-specialists.ac3", + "title": "The frontmatter description no longer contains `a review agent and a test agent check the work` and is 50 to 160 characters", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-convoys", + "title": "convoys.mdx: fix Role Models, synthesis format, Pipeline prose and labels", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/convoys.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/convoys.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "FR-8" + ] + }, + "narrative": { + "Action": "Apply WI-G2 (Appendix G part convoys.mdx, 7 rows), retitle with sidebarTitle 'Review convoy' and change the description in features/convoys.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-convoys, the AC trailers and a 'PR-note: features/convoys.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-convoys.ac1", + "title": "features/convoys.mdx no longer contains `Roles panel` and contains `Role Models`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-convoys.ac2", + "title": "The synthesis report block no longer contains `# Verdict: APPROVED | CHANGES_REQUESTED | FAILED` and contains `## Blocking Findings`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-convoys.ac3", + "title": "The Pipeline paragraph contains `Review running` and no longer contains `Review queue`, and its alt text no longer contains `live activity feed`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-convoys.ac4", + "title": "The God View paragraph contains `Experimental features` and the page contains `discord.gg/ZpHE2ZTv5P`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-cloister", + "title": "cloister.mdx: narrow the model-choice claim and name Tiered Execution", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/cloister.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/cloister.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Apply WI-G3 (Appendix G part cloister.mdx, 2 rows) to features/cloister.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-cloister, the AC trailers and a 'PR-note: features/cloister.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-cloister.ac1", + "title": "features/cloister.mdx no longer contains `Cloister does not choose models and does not decide merges.`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-cloister.ac2", + "title": "The model-routing sentence contains `Settings → Tiered Execution`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-merge-batches", + "title": "merge-batches.mdx: correct off-switch, batch-of-one, UAT button and host claims", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/merge-batches.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/merge-batches.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Apply WI-G4 (Appendix G part merge-batches.mdx, 10 rows), retitle with sidebarTitle 'UAT Batch Trains' and remove all 12 dash lines in features/merge-batches.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-merge-batches, the AC trailers and a 'PR-note: features/merge-batches.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-merge-batches.ac1", + "title": "features/merge-batches.mdx no longer contains `Open UAT frontend` and contains `**Open UAT**`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-merge-batches.ac2", + "title": "The off-switch sentence contains `GitLab and polyrepo projects never merge automatically`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-merge-batches.ac3", + "title": "The batch paragraph contains `batch_wait_minutes` and the UAT host contains `uat-<label>-<codename>-<mmdd>.overdeck.localhost`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-merge-batches.ac4", + "title": "The frontmatter contains `sidebarTitle: \"UAT Batch Trains\"` and `grep -cP '[\\x{2013}\\x{2014}]' features/merge-batches.mdx` prints 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-mission-control", + "title": "mission-control.mdx: delete removed views and fix tree, pipeline and projects", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "complex", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/mission-control.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/mission-control.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-7", + "FR-8" + ] + }, + "narrative": { + "Action": "Apply WI-H1 (Appendix H part mission-control.mdx, 14 rows and blocks M2-TEXT, M9-TEXT) to features/mission-control.mdx, deleting the four sections the rows name. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-mission-control, the AC trailers and a 'PR-note: features/mission-control.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-mission-control.ac1", + "title": "features/mission-control.mdx no longer contains `## Activity View`, `## Badge Bar`, `## Status Reviews` or `### Model Selection`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-mission-control.ac2", + "title": "The page no longer contains `## Planning Artifacts` and contains `## Issue documents` linking `/features/dashboard-views#issue-drawer-and-full-issue-view`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-mission-control.ac3", + "title": "The Pipeline View paragraph contains `Review running`, and neither it nor its alt text contains `live activity feed`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-mission-control.ac4", + "title": "The projects sentence contains `~/.overdeck/projects.yaml` and the Agents sentence contains `experimental`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-keyboard-shortcuts", + "title": "keyboard-shortcuts.mdx: label experimental keys and add page-only keys", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/keyboard-shortcuts.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/keyboard-shortcuts.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-7" + ] + }, + "narrative": { + "Action": "Apply WI-H2 (Appendix H part keyboard-shortcuts.mdx, 3 rows and block K3-INSERT) and retitle with sidebarTitle 'Keyboard shortcuts' in features/keyboard-shortcuts.mdx; leave the macOS ⌘W and ⌘T lines unchanged. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-keyboard-shortcuts, the AC trailers and a 'PR-note: features/keyboard-shortcuts.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-keyboard-shortcuts.ac1", + "title": "features/keyboard-shortcuts.mdx contains `Go to Agents (experimental` and no longer contains `` `Ctrl+W` go to the shell ``", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-keyboard-shortcuts.ac2", + "title": "The page contains a `## Keys on single pages` table with rows for Board undo and voice input `⌘⇧M`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-keyboard-shortcuts.ac3", + "title": "The frontmatter contains `title: \"Dashboard keyboard shortcuts\"` and `sidebarTitle: \"Keyboard shortcuts\"`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-file-explorer", + "title": "file-explorer.mdx: add tree keys and the upload limit", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/file-explorer.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/file-explorer.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Apply WI-H3 (Appendix H part file-explorer.mdx, 2 rows), retitle with sidebarTitle 'File explorer' and change the description in features/file-explorer.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-file-explorer, the AC trailers and a 'PR-note: features/file-explorer.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-file-explorer.ac1", + "title": "features/file-explorer.mdx contains `F2` renames and `100 MB` for uploads", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-file-explorer.ac2", + "title": "The frontmatter contains `title: \"File explorer and code editor\"` and `sidebarTitle: \"File explorer\"`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-open-in-overdeck", + "title": "open-in-overdeck.mdx: add the root-folder message and Windows pan lookup", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "trivial", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/open-in-overdeck.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/open-in-overdeck.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Apply WI-H4 (Appendix H part open-in-overdeck.mdx, 2 rows) to features/open-in-overdeck.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-open-in-overdeck, the AC trailers and a 'PR-note: features/open-in-overdeck.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-open-in-overdeck.ac1", + "title": "features/open-in-overdeck.mdx contains `Opened root folder in <project>`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-open-in-overdeck.ac2", + "title": "The pan lookup sentence contains `pan.cmd` for Windows", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-issue-pipeline", + "title": "issue-pipeline.mdx: correct verification.tests location, test target and Require UAT", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "trivial", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/issue-pipeline.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/issue-pipeline.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Apply WI-I1 (Appendix I part issue-pipeline.mdx, 3 rows) to features/issue-pipeline.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-issue-pipeline, the AC trailers and a 'PR-note: features/issue-pipeline.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-issue-pipeline.ac1", + "title": "features/issue-pipeline.mdx contains `verification.tests` setting in `projects.yaml`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-issue-pipeline.ac2", + "title": "The test sentence no longer contains `built dashboard` and the merge sentence contains `Require UAT switch`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-planning", + "title": "planning.mdx: correct probe effort, spec keys, Action rule and status triggers", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/planning.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/planning.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Apply WI-I2 (Appendix I part planning.mdx, 6 rows) to features/planning.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-planning, the AC trailers and a 'PR-note: features/planning.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-planning.ac1", + "title": "features/planning.mdx no longer contains `` `Xhigh` and `Max` add the probe pass `` and contains `High` and above", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-planning.ac2", + "title": "The xBRIEF section contains a root `status` field and `narrative.Action` with `at least 8 words`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-planning.ac3", + "title": "The status table no longer contains `The PR merges` as the completed trigger and contains `pan scope complete` and `pan scope cancel`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-flywheel", + "title": "flywheel.mdx: correct UAT blocking, sequencer scope and UI labels", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/flywheel.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/flywheel.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Apply WI-I3 (Appendix I part flywheel.mdx, 10 rows) to features/flywheel.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-flywheel, the AC trailers and a 'PR-note: features/flywheel.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-flywheel.ac1", + "title": "features/flywheel.mdx no longer contains `does block merge on its own, independent of this switch` and contains `only while the issue is held for UAT`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-flywheel.ac2", + "title": "The Known limits contain `PAN-` and the written-files sentence contains `.pan/parked.md`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-flywheel.ac3", + "title": "The page contains `merge_train: disabled` and `show message`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-dashboard-views", + "title": "dashboard-views.mdx: label Analytics, fix Anywhere row, pan context and Simple Home", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "trivial", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/dashboard-views.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/dashboard-views.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-7" + ] + }, + "narrative": { + "Action": "Apply WI-J1 (Appendix J part dashboard-views.mdx, 4 rows) to features/dashboard-views.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-dashboard-views, the AC trailers and a 'PR-note: features/dashboard-views.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-dashboard-views.ac1", + "title": "features/dashboard-views.mdx contains `Analytics opens Metrics, which is experimental`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-dashboard-views.ac2", + "title": "The pan context sentence contains `detach` and the Anywhere sentence contains `Tailscale is not ready`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-costs", + "title": "costs.mdx: correct Grok pricing, branch pattern and UTC windows", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "trivial", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/costs.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/costs.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Apply WI-J2 (Appendix J part costs.mdx, 5 rows) to features/costs.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-costs, the AC trailers and a 'PR-note: features/costs.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-costs.ac1", + "title": "features/costs.mdx contains `Pi and Grok are the exceptions` and no longer contains `prices Claude Code, Codex, Kimi, Grok and Muse`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-costs.ac2", + "title": "The branch sentence contains `a hyphen and a number` and the window sentence contains `UTC day`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-desktop-app", + "title": "desktop-app.mdx: correct Linux paths, crash port, reminders and canary", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "trivial", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/desktop-app.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' features/desktop-app.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; no other item touches it.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Apply WI-J3 (Appendix J part desktop-app.mdx, 4 rows) to features/desktop-app.mdx. Follow the PRD Common procedure in .pan/drafts/PAN-5502.md (apply the change table by grep anchor, residual rule, remove every en/em dash in the range, frontmatter rule, link check, MDX safety). Never change code or images. Commit with Item: audit-desktop-app, the AC trailers and a 'PR-note: features/desktop-app.mdx: <one line>' line, push, then pan task done." + }, + "items": [ + { + "id": "audit-desktop-app.ac1", + "title": "features/desktop-app.mdx contains `/usr/local/bin/overdeck` and `7833`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-desktop-app.ac2", + "title": "The reminder sentence contains `Reminder 5 of 5` and the canary sentence contains `1.2.3-canary.1`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "validate-and-pr-body", + "title": "Run the group validators and draft the per-page PR body", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T07:00:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5502", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "features/issue-pipeline.mdx", + "features/planning.mdx", + "features/flywheel.mdx", + "features/conversations.mdx", + "features/file-explorer.mdx", + "features/mission-control.mdx", + "features/dashboard-views.mdx", + "features/costs.mdx", + "features/convoys.mdx", + "features/specialists.mdx", + "features/merge-batches.mdx", + "features/swarm.mdx", + "features/skills.mdx", + "features/skill-packs.mdx", + "features/workspaces.mdx", + "features/cloister.mdx", + "features/safe-shutdown.mdx", + "features/open-in-overdeck.mdx", + "features/desktop-app.mdx", + "features/keyboard-shortcuts.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "npm run lint:docs", + "npx -y mint@4.3.49 validate", + "npx -y mint@4.3.49 broken-links --check-anchors" + ], + "expected_outputs": [ + "lint:docs prints 'docs lint passed' and exits 0", + "mint validate prints 'build passed' with no error in a features/ page", + "broken-links lists no features/ file" + ], + "readiness": "sequential", + "parallelSafeReason": "Runs last (blocked by every page item); touches a page only to fix a validator failure.", + "traces": [ + "FR-3", + "FR-4", + "FR-5", + "FR-9" + ] + }, + "narrative": { + "Action": "Run WI-Z1 in .pan/drafts/PAN-5502.md after every page item: the dash loop over the 20 pages, the frontmatter check, npm run lint:docs, npx -y mint@4.3.49 validate and npx -y mint@4.3.49 broken-links --check-anchors; fix any failure in a features/ page; then write the PR body draft (20 ticked page lines from the PR-note lines, validation output, Follow-ups) into this item's commit message above the trailers. Commit with Item: validate-and-pr-body." + }, + "items": [ + { + "id": "validate-and-pr-body.ac1", + "title": "The dash loop over all 20 features pages prints no line", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "validate-and-pr-body.ac2", + "title": "`npm run lint:docs` exits 0 and `npx -y mint@4.3.49 validate` prints no error for a features/ page", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "validate-and-pr-body.ac3", + "title": "`npx -y mint@4.3.49 broken-links --check-anchors` prints no broken link in a features/ page", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "validate-and-pr-body.ac4", + "title": "The validate-and-pr-body commit message contains 20 lines starting `- [x] features/` and a `## Follow-ups` section", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + } + ], + "edges": [ + { + "from": "conv-surface", + "to": "conv-handoff", + "type": "blocks" + }, + { + "from": "conv-handoff", + "to": "conv-machines-to-end", + "type": "blocks" + }, + { + "from": "workspaces-layout-to-lifecycle", + "to": "workspaces-safeguards-to-end", + "type": "blocks" + }, + { + "from": "conv-surface", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "conv-handoff", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "conv-machines-to-end", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-skill-packs", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-skills", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-safe-shutdown", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-swarm", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "workspaces-layout-to-lifecycle", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "workspaces-safeguards-to-end", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-specialists", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-convoys", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-cloister", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-merge-batches", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-mission-control", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-keyboard-shortcuts", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-file-explorer", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-open-in-overdeck", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-issue-pipeline", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-planning", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-flywheel", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-dashboard-views", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-costs", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-desktop-app", + "to": "validate-and-pr-body", + "type": "blocks" + } + ] + }, + "status": "active" +} \ No newline at end of file diff --git a/features/cloister.mdx b/features/cloister.mdx index c6f65b876a0..494c9b51549 100644 --- a/features/cloister.mdx +++ b/features/cloister.mdx @@ -6,7 +6,7 @@ description: "Cloister is the Overdeck watchdog. It checks every running agent, import { ThemedImage } from "/snippets/themed-image.mdx"; -Cloister is Overdeck's agent watchdog. It starts with the dashboard, checks the health of every running agent, and runs a patrol loop that recovers work that has stalled. Cloister does not choose models and does not decide merges. +Cloister is Overdeck's agent watchdog. It starts with the dashboard, checks the health of every running agent, and runs a patrol loop that recovers work that has stalled. Cloister does not choose the model an agent starts with and does not decide merges. ## Start, stop and check Cloister @@ -77,7 +77,7 @@ The Agents page shows each running agent's model, runtime and last activity. The ## Model routing -Cloister does not pick models. Roles, workhorse slots and tiered execution do that, configured in Settings → Model Routing; see [Model routing](/configuration/model-routing). +Cloister does not pick the model an agent starts with. Roles and workhorse slots (Settings → Model Routing) and tiered execution (Settings → Tiered Execution) do that; see [Model routing](/configuration/model-routing). ## Related diff --git a/features/conversations.mdx b/features/conversations.mdx index 48494a42e23..6d672803d0a 100644 --- a/features/conversations.mdx +++ b/features/conversations.mdx @@ -8,39 +8,39 @@ import { ThemedImage } from "/snippets/themed-image.mdx"; Overdeck is as much a tool for **managing conversations with agents** as it is a workflow engine. Command Deck treats every agent session as a first-class conversation: you spawn it, watch it work, talk to it mid-task, branch it to try -a different approach, and — when it nears the context wall or you want to switch -models — hand it off to a fresh conversation that inherits the context that +a different approach, and (when it nears the context wall or you want to switch +models) hand it off to a fresh conversation that inherits the context that matters. <ThemedImage light="/images/dashboard/command-deck-hero-light.png" dark="/images/dashboard/command-deck-hero-dark.png" - alt="Command Deck with a live conversation: the project's conversations and issues, and the agent's turn-by-turn tool calls" + alt="Command Deck on a project's home tab: the conversation list in the left column, and the project's agents, Needs you queue and pipeline in the main pane" /> ## The conversation surface Each conversation has a live **Conversation** view and a **Terminal** view of the -same session. The conversation pane streams the agent's turns — reasoning, tool -calls, file reads and edits, command output — as they happen. Below it sits the +same session. The conversation pane streams the agent's turns (reasoning, tool +calls, file reads and edits, command output) as they happen. Below it sits the composer, where you type to steer the agent the way you'd pair-program with a colleague. | Control | What it does | |:--------|:-------------| -| **Composer** | Send a message to the running agent mid-task — correct its approach, point it at a file, or tell it to stop and rethink | -| **Model picker** | Hot-swap the model for the next message — Sonnet → Opus → Kimi/GPT/Gemini — without losing the conversation | -| **Reasoning effort** | Tune how hard the model thinks per message (e.g. *Extra High*) | -| **Conversation / Terminal toggle** | Switch between the rendered conversation and the raw terminal of the same session (the native CLI for OpenCode and Codex) | +| **Composer** | Send a message to the running agent mid-task: correct its approach, point it at a file, or tell it to stop and rethink | +| **Model picker** | Shows the conversation's model. In the dashboard, the model is fixed once a conversation starts; click the button to see why, and hand off to a new conversation to use another model | +| **Reasoning effort** | The `Thinking: <level>` button changes how hard the model thinks while the session runs (e.g. *Extra High*); see [Changing effort while a conversation runs](#changing-effort-while-a-conversation-runs) | +| **Conversation / Terminal toggle** | Switch between the rendered conversation and the raw terminal of the same session (the native CLI for OpenCode and Codex). Shown only while the session is live | | **Copy link** | ⋯ → Copy link copies the `overdeck.localhost/conv/<id>` URL; ⋯ → Open in new window opens the conversation in its own window | -| **Context window meter** | See how much of the window is used — your cue that a handoff is coming | +| **Context window meter** | See how much of the window is used, your cue that a handoff is coming | | **Bookmarks** | Mark a message by clicking the icon beside it, then reopen the list from ⋯ → Bookmarks to jump back to it | | **Citations** | Select text in a reply (or your own message), click **Cite** (or press `C`), add an optional comment, and it goes out with your next prompt | ### The header and status line The first row of the conversation header holds the title, the Conversation / -Terminal toggle, and three buttons on the right: +Terminal toggle, and these buttons on the right: - **Changes** shows how many lines the conversation added and removed (`+86 −1`) and opens the side panel on its Changes tab, with the **This conversation** @@ -48,6 +48,7 @@ Terminal toggle, and three buttons on the right: - **Files** opens the side panel on its Files tab. `Ctrl Shift E` (`⌘⇧E`) shows or hides it. - **⋯** opens the conversation menu. A right-click on the header opens it too. +- A Pi conversation that is working also shows **Stop**, which stops the current turn. Changes and Files open the panel for the conversation whose header you click. They appear only when the conversation is a tab in the Command Deck; a popped-out @@ -58,8 +59,9 @@ The second row is the status line. It says, in words and in this order: the state (for example "Working"), the machine a linked conversation runs on, the folder (with your home directory shortened to `~`), the branch and its pull request, **N commits pushed**, **N commits not pushed**, **N files not -committed**, and the cost. A count of zero is left out. In a Command Deck tab -the folder opens the Files tab, the commit counts open the Changes tab on +committed**, and the cost. The commit and file counts +show only in a Command Deck tab, and a count of zero is left out. In a Command +Deck tab the folder opens the Files tab, the commit counts open the Changes tab on **This conversation**, and **N files not committed** opens it on **Not committed**. In a detached checkout the branch reads **detached**. When the checkout has no upstream branch, as in a detached checkout, a commit counts @@ -80,9 +82,10 @@ The ⋯ menu lists, in groups: [diff window](#reviewing-changes-in-the-diff-window) for the conversation. A linked conversation or a read-only vault copy does not show it. 3. **Favorite**, **Regenerate title**, and the pull request items. -4. **Hand off to new conversation**, **Create summary fork**, **Export - transcript**, pulling the conversation here, **Continue on another device**, - **Share**, and the handoff doc and target. +4. **Hand off to new conversation**, **Create summary fork** (not for Pi), + **Add skills…** (Claude Code and Codex), **Export transcript**, pulling the + conversation here, **Continue on another device**, **Share**, and the + handoff doc and target. 5. **Advanced** → **Delivery method** (Claude Code conversations only). 6. **Archive conversation** and **Stop the agent**. @@ -104,8 +107,8 @@ not committed, and the `+/−` on the card adds up those rows. Inside a Command Deck tab: - **Review** opens the side panel's Changes tab on the turn's first file. `J` - and `K` step through the turn's files, and **Back** shows the This - conversation list. + and `K` step through the turn's files, and the back arrow + (**Back to the list**) shows the This conversation list. - **Show in files** opens the Files tab with **Only what this conversation changed** selected. - Click a row to open that file's diff. Hover a row for **Open the file beside @@ -114,8 +117,8 @@ Inside a Command Deck tab: Outside a Command Deck tab (a popped-out window, a drawer or the phone app), the card shows the same files and counts, and **Review** and the rows open the [diff window](#reviewing-changes-in-the-diff-window). There is no side panel -there, so **Show in files** and the row's beside and reveal actions are not -shown. +there, so **Show in files** is not shown, and the row's beside and reveal +actions are greyed out. ### File paths in replies @@ -188,9 +191,10 @@ default for your own new sessions of that model in `~/.claude/settings.json`; Overdeck's sessions always launch with an explicit effort, so they are not affected. -The model picker spans the harness (Claude Code, Pi, Codex) and every routed -provider, each with live per-million pricing — so a mid-conversation swap is one -click: +The model and harness picker spans the harness (Claude Code, Pi, Codex) and +every routed provider, each with live per-million pricing. It picks the model +for a new conversation (on the Home composer and in the **New conversation** +caret menu); once a conversation starts, the dashboard keeps its model fixed: <ThemedImage light="/images/dashboard/model-picker-light.png" @@ -230,6 +234,9 @@ what the next quick create uses. Its fields are: - **Project** and **Working directory.** The project starts as the deck's project. The working directory starts as the project path, and you can point it at any directory inside the project, such as a package in a monorepo. +- **Machine.** This machine (the default), **Auto**, a linked machine, or + **Fly (new VM)**, which needs a project. On another machine, that machine + picks the working directory from its copy of the project. - **Model** and **Harness.** - **Effort.** It lists the levels the model supports and starts at the default effort, with its source shown beside it. A model with no effort setting @@ -265,8 +272,8 @@ Both Simple and Advanced Home carry a composer at the top of the page, so you can start a conversation or a terminal without opening the Command Deck or picking a project first: -- **Enter** asks the composer's current agent, exactly as typed — no seed - prompt, no project required. +- **Enter** asks the composer's current agent, exactly as typed, with no seed + prompt and no project required. - **Ctrl+Enter** (or choosing "Run in terminal:") opens the terminal drawer in the relevant deck and runs the typed text as a command in a fresh shell. - **"Talk it through first:"** (Simple mode only) sends the same text through @@ -274,8 +281,8 @@ picking a project first: issue only once you say it's ready. The composer's project chip lists every registered project, a **no project** -choice, and **Add a project…**. Choosing no project — or having none -registered yet — starts the conversation or terminal in your home folder +choice, and **Add a project…**. Choosing no project (or having none +registered yet) starts the conversation or terminal in your home folder (`~/Projects` if it exists, otherwise your home directory) instead of blocking you. In the Command Deck, that same no-project state is the **No project** deck, always reachable from the **No project** item in the project switcher's @@ -283,8 +290,8 @@ menu, and offered as "Start without a project" when nothing else is selected. The app bar reads **No project** when the No project deck is selected, never its internal key. -If a conversation ends up outside any project — started from Home before a -project existed, say — its pane shows a "Not in a project · Move to +If a conversation ends up outside any project (started from Home before a +project existed, say), its pane shows a "Not in a project · Move to project…" chip so you can attach it to a project later without losing the conversation. To move any conversation to another project, open its row menu in the left column and pick the project from **Move**. @@ -374,9 +381,9 @@ When the native CLI is not available, Terminal says why and nothing restarts: You can attach files to a composer message in three ways: -- **Paperclip button** — click the attach icon in the composer toolbar and select one or more files. -- **Drag and drop** — drop files directly onto the composer area. -- **Paste** — paste an image from your clipboard (screenshots, copied files, etc.). +- **Paperclip button**: click the attach icon in the composer toolbar and select one or more files. +- **Drag and drop**: drop files directly onto the composer area. +- **Paste**: paste an image from your clipboard (screenshots, copied files, etc.). Supported attachments include images (`png`, `jpg`, `gif`, `webp`) and text/code/PDF files such as `md`, `json`, `ts`, `py`, `log`, `csv`, `yaml`, and `pdf`. Files are @@ -407,8 +414,8 @@ vision-capable model (for example, Claude Sonnet 5.5) to include images. ## Citations -To push back on part of a reply, select the text — in an assistant message or -your own — and click the **Cite** button that appears over the selection (or +To push back on part of a reply, select the text (in an assistant message or +your own) and click the **Cite** button that appears over the selection (or press `C` while nothing else has focus). Write an optional comment explaining what's wrong or what to change, then save. The citation becomes a chip above the composer; the quoted text stays highlighted in its row until the citation @@ -416,7 +423,7 @@ is sent or removed. Chips can be expanded to show the full quote and edit the comment, or removed with the ✕. Citations persist across switching conversations and reloading the -page — they live in the browser, not the agent's transcript, so they survive +page: they live in the browser, not the agent's transcript, so they survive until you send or remove them. On send, every pending citation is prepended to your prompt as a block: @@ -433,9 +440,9 @@ Please revise. Numbering follows add order; a quote with no comment gets no comment line. If the send fails, the citations stay attached to the retry-outbox entry rather -than being lost — Retry resends the same block. Typing a slash command (for +than being lost; Retry resends the same block. Typing a slash command (for example `/compact`) sends the bare command and leaves any pending citations -untouched. You can only cite settled message text — not tool output, plan +untouched. You can only cite settled message text, not tool output, plan cards, choice cards, or a reply still streaming in. Cite is offered only when the conversation has a composer: it does not appear @@ -453,7 +460,7 @@ labeled with the file name, and a toast confirms **Citation added** with an To browse and edit any file of a project, use the [file explorer](/features/file-explorer). -Cite is not offered in **Edit** — only in **Preview** — and not while the +Cite is not offered in **Edit** (only in **Preview**), and not while the file has unsaved changes (save first; the agent reads the file from disk, not your draft). It is also not offered for a tab opened from somewhere other than a conversation, since there is nowhere for the citation to go. Opening @@ -478,13 +485,13 @@ URLs) are not included. Click the icon beside an assistant or user message to bookmark it, using its first line as the label. The icon turns into a filled bookmark; clicking it -again opens a popover to rename or remove the bookmark. ⋯ → **Bookmarks** opens a list showing each bookmark's label and time — clicking +again opens a popover to rename or remove the bookmark. ⋯ → **Bookmarks** opens a list showing each bookmark's label and time; clicking a label scrolls the timeline to that message and outlines it briefly. Bookmarks survive reloads and new messages because they point at the transcript message's stable id, not its position in the list. They are stored by Overdeck and never written into the agent's own transcript, and -they stay with this conversation — a handoff or fork does not copy them. If +they stay with this conversation; a handoff or fork does not copy them. If a bookmarked message is no longer in the loaded transcript, its row in the list shows "This message is not in the loaded transcript." @@ -561,8 +568,8 @@ on. When the context window fills up, that knowledge is the most expensive thing to lose. A naive "summarize and continue" throws away the nuance. A **handoff** is a deliberate context transfer. Instead of a passive summary, an -agent reads the conversation and writes a structured Markdown handoff document — -capturing the dead ends, the important files, and the suggested next steps — and +agent reads the conversation and writes a structured Markdown handoff document, +capturing the dead ends, the important files, and the suggested next steps, and that document becomes the seed message for a brand-new conversation. The new agent starts with a clean context window but inherits what mattered. @@ -578,21 +585,17 @@ Claude-Code-compatible session. ## Continue: the three ways to start a new conversation -Open the **Continue** dialog from a conversation's action menu, or type +Open the dialog (titled **Continue in a new conversation**) from a +conversation's menu: **Hand off to new conversation** opens it on Agent +handoff, **Create summary fork** on Fresh summary. Or type `/handoff` (optionally followed by focus text) in the composer to jump straight to handoff mode. The dialog presents three intents, ordered richest to lightest: -<ThemedImage - light="/images/handoff/continue-modal-light.png" - dark="/images/handoff/continue-modal-dark.png" - alt="The Continue dialog with Agent handoff selected, a new-conversation name, harness and launch-model pickers, and a focus field" -/> - | Intent | What it does | Best for | |:-------|:-------------|:---------| -| **Fresh summary** *(recommended)* | An LLM distills the prior context into a seed message. For very large conversations the history is chunked, each chunk building on the previous summary. | Most cases — a clean, structured starting point | +| **Fresh summary** *(recommended)* | An LLM distills the prior context into a seed message. For very large conversations the history is chunked, each chunk building on the previous summary. | Most cases: a clean, structured starting point | | **Agent handoff** | An agent writes a Markdown handoff document, optionally focused on a specific next task, that becomes the seed message. | Deliberate handoffs where dead ends, key files, and next steps matter | -| **Exact copy** | Copies the raw conversation history verbatim — no summary generated. | Picking up exactly where you left off, **same model only** | +| **Exact copy** | Copies the raw conversation history from the last compaction point, with no summary. Only a Claude Code conversation can be copied, and the copy launches under Claude Code. | Picking up exactly where you left off, **same model only** | The **Project** picker controls where the successor appears in the project tree, independently of its working directory. It defaults to **Same as source**, so an @@ -603,7 +606,7 @@ somewhere else. <Note> **Fast summary** is an advanced toggle under *Fresh summary* that skips the LLM and extracts a bullet list of user messages, files modified, and tools used -directly from the history — cheaper and instant, but rougher. +directly from the history. It is cheaper and instant, but rougher. </Note> <Warning> @@ -616,33 +619,28 @@ signed thinking blocks) that won't validate on a different provider. Use a Two model choices live in this dialog, and they are independent: -- **Launch model** — the model the *new conversation* will run on. Defaults to the parent conversation's model. -- **Authoring model** — the model that *writes the summary or handoff document*. Independent of the launch model; cheaper models like Haiku work well for straightforward cases, larger models for nuanced conversations. +- **Launch model**: the model the *new conversation* will run on. Defaults to the parent conversation's model. +- **Authoring model**: the model that *writes the summary or handoff document*. Independent of the launch model; cheaper models like Haiku work well for straightforward cases, larger models for nuanced conversations. ## Progressive disclosure: Advanced options The dialog keeps the common case to one screen. Everything else lives behind **Advanced options**, which expands to reveal the authoring controls: -<ThemedImage - light="/images/handoff/continue-modal-advanced-light.png" - dark="/images/handoff/continue-modal-advanced-dark.png" - alt="The Continue dialog with Advanced options expanded, showing the authored-by choice (external vs source), authoring harness, and authoring model" -/> - | Authored by | Behavior | |:------------|:---------| -| **External session** *(default)* | A clean session reads the transcript from disk and writes the document. The source conversation is never touched — its context stays clean, and the source can even be ended. Pick the authoring model and harness here. | -| **Source session** | The live source agent writes the document in-conversation. This adds the prompt and document to the source's context, and uses whatever model the source is running. Right when the source has live state — open files, recent commands, in-flight reasoning — a transcript reader would miss. | +| **External session** *(default)* | A clean session reads the transcript from disk and writes the document. The source conversation is never touched: its context stays clean, and the source can even be ended. Pick the authoring model here; the dialog has no harness picker. | +| **Source agent** | The live source agent writes the document in-conversation. This adds the prompt and document to the source's context, and uses whatever model the source is running. Right when the source has live state (open files, recent commands, in-flight reasoning) that a transcript reader would miss. Offered only for a Claude Code source, and Continue stays disabled until the source conversation is running. | -If a source-authored handoff stalls or produces an invalid document, Overdeck -falls back to a summary fork automatically. +If authoring fails (the document never arrives or fails validation, or the +authoring request errors), Overdeck falls back to a summary fork automatically, +whoever authors it. A missing authoring model is the exception: that handoff fails. Under **Agent handoff**, a **Fresh start** checkbox sits beside Hold. Checking it skips authoring entirely: the Focus field relabels to "First message", the Authored-by controls disappear, and Continue creates a root conversation with no parent link whose first message is the focus text verbatim. ## The help panel -Every option in the dialog is explained inline — click the **?** to open the +Every option in the dialog is explained inline. Click the **?** to open the *Continue Options* reference without leaving the flow: <ThemedImage @@ -653,22 +651,23 @@ Every option in the dialog is explained inline — click the **?** to open the ## Handing off from the CLI -The dialog is the visual front-end for `pan handoff`. The CLI does exactly what -the dialog does, and the two are interchangeable. +`pan handoff` is the CLI form of the dialog's **Agent handoff**, including Fresh +start and Hold. Fresh summary is `pan fork <conv>`, and Exact copy is +`pan fork <conv> --plain`. ```bash pan handoff [conv] [focus...] ``` -The trailing text after the conversation reference becomes the **focus** — no +The trailing text after the conversation reference becomes the **focus**, with no flag required. ### Hand off the conversation you're in If you're an agent inside a conversation and want to hand off *your own* conversation, omit `<conv>` (or pass `self`). The command identifies your -conversation deterministically from the session you're running in — no scanning, -no guessing. +conversation deterministically from the session you're running in, with no scanning +and no guessing. ```bash pan handoff # hand off this conversation, no focus @@ -676,7 +675,7 @@ pan handoff self wire the Stripe webhook # hand off this conversation, with foc ``` Because focus text is positional, prefer the explicit `self` token whenever you -pass focus — a bare first word like `pan handoff continue the wiring` is read as +pass focus: a bare first word like `pan handoff continue the wiring` is read as a *conversation reference* named "continue", not as focus. `self` removes the ambiguity. Run `pan conv current` (alias `pan conv whoami`) to print exactly which conversation you resolve to. @@ -687,9 +686,8 @@ which conversation you resolve to. pan handoff 42 pan handoff source-conv continue the API wiring pan handoff source-conv --model claude-sonnet-4-6 -pan handoff source-conv --harness pi -pan handoff source-conv --cwd /path/to/project -pan handoff source-conv --cwd ../isolated-worktree --project mind-your-now +pan handoff source-conv --cwd ~/Projects/myapp/workspaces/feature-myapp-42 +pan handoff source-conv --cwd ~/worktrees/isolated --project mind-your-now pan handoff source-conv --author source uses-source-agent-and-pollutes-its-context pan handoff source-conv --author external --author-model claude-haiku-4-5 cheap clean handoff ``` @@ -699,25 +697,28 @@ pan handoff source-conv --author external --author-model claude-haiku-4-5 cheap | Option | Description | |:-------|:------------| | `[conv]` | Conversation id or name. Omit (or pass `self`) to hand off the conversation you're in. | -| `[focus...]` | Positional focus text — what the successor should concentrate on. **≤ 10,000 characters.** | +| `[focus...]` | Positional focus text: what the successor should concentrate on. **≤ 10,000 characters.** | | `--model <model>` | Model for the new (forked) conversation. Defaults to the parent's model. | | `--effort <level>` | Reasoning effort for the new conversation (`low`, `medium`, `high`, `xhigh`, `max`). Defaults to the source conversation's effort, clamped to the new model. | -| `--harness <harness>` | Harness for the new conversation: `claude-code` or `pi`. | -| `--cwd <path>` | Working directory for the new conversation. | +| `--harness <harness>` | Accepted and ignored with a printed notice: the new conversation's harness follows its model's provider. | +| `--cwd <path>` | An absolute path to an existing directory under your home directory and, except with `--fresh`, inside a git working tree. A project's primary checkout is refused: use a worktree, or pass `--allow-primary`. | | `--project <key-or-name>` | Registered project for the successor. Defaults to inheriting the source conversation's project, even when `--cwd` points outside that project's directory. | +| `--allow-primary` | Operator only: allow `--cwd` to be a project's primary checkout. Refused for agent sessions. | +| `--issue <id>` | Issue ID to associate with the new conversation. Without `--cwd`, the new conversation starts in the issue's workspace when one exists. | +| `--role <role>` | Pane role for the new conversation: `conversation` (default), `work`, `review`, `test` or `plan`. With `--issue`, `review` makes the handoff the issue's Review row. | +| `--title <title>` | Title for the new conversation. Defaults to `Handoff: <focus>` (the first ~70 characters of the focus), or `Handoff: <source title>` without focus. | | `--author <who>` | Who authors the handoff doc: `external` (default) or `source`. | -| `--author-model <model>` | Model for the external authoring session (only when `--author=external`). Falls back to `conversations.handoff_author_model` in `config.yaml` when omitted — there is no built-in default, so set one of the two or the handoff fails with a clear error. | -| `--author-harness <harness>` | Harness for the external authoring session: `claude-code` or `pi` (external only). | +| `--author-model <model>` | Model for the external authoring session (only when `--author=external`). Falls back to `conversations.handoff_author_model` in `config.yaml` when omitted. There is no built-in default, so set one of the two or the handoff fails with a clear error. | +| `--author-harness <harness>` | Accepted and ignored with a printed notice; there is no authoring harness choice. | | `--skill <name>` | Turn this skill on for the new conversation only (repeatable). `<name>` is a native skill name or a pack skill id `<pack>/<skill>`. Claude Code and Codex only; a Pi successor stores the values but never applies them. | | `--pack <id>` | Turn on every non-opt-in skill of this cached skill pack, for the new conversation only (repeatable). Claude Code and Codex only; a Pi successor stores the values but never applies them. The values are a snapshot of the pack at creation. | | `--group <name>` | Turn on every cached pack of this [pack group](/features/skill-packs#pack-groups) (for example `video`), for the new conversation only (repeatable). Each member pack that is not added or not cached is skipped with a note. | | `--hold` | Create and launch the new conversation without sending the kickoff. Start it with Send in the dashboard composer, or `pan handoff start <conv>`. | -| `--fresh` | Start a clean conversation: no handoff document, no summary, no parent link. The focus becomes its first message. Project, cwd, model and effort still default from the source. | +| `--fresh` | Start a clean conversation: no handoff document, no summary, no parent link. The focus becomes its first message. Project, cwd, model and effort still default from the source. Cannot be combined with `--author source` or `--author-model`; with `--hold` it needs focus text. | <Note> -**Focus is hard-capped at 10,000 characters** (PAN-3737; multi-line is fine). A longer focus is rejected with -`focus must be 10000 characters or fewer` and no -conversation is created. Keep it short and task-oriented — the detail belongs in +**Focus is hard-capped at 10,000 characters** (PAN-3737; multi-line is fine). `pan handoff` refuses a longer focus before anything is created; the dashboard API refuses it with `focus must be 10000 characters or fewer`. No +conversation is created. Keep it short and task-oriented: the detail belongs in the transcript the author reads; the focus only steers what the author emphasizes. </Note> @@ -733,13 +734,13 @@ pan handoff self --hold Read .pan/handoff-brief.md FIRST and follow it exactly. The successor's dashboard composer shows a waiting notice with the kickoff text already filled in; pressing Send there starts it. From the terminal, run -`pan handoff start <conv>` (id or name) instead — it sends the held kickoff +`pan handoff start <conv>` (id or name) instead; it sends the held kickoff exactly once. A second `pan handoff start` on the same conversation, or one on a conversation that was never held, exits 1 with "No held kickoff: the conversation was already started or was never held". If the held conversation's session ends before you start it, its page shows -**Held handoff — kickoff not sent** with the focus, the working directory, the +a **Held handoff** notice that the kickoff was not sent, with the focus, the working directory, the handoff doc and the kickoff text. **Start** there does the same as `pan handoff start <conv>`: it relaunches the session and sends the kickoff. Resume Session is not offered, because a resume would start the agent without @@ -749,51 +750,54 @@ button takes you to the conversation. ### Starting fresh -`--fresh` starts a clean conversation that takes only the source's project, cwd, model and effort — not its context. No handoff document is authored, no summary is generated, the source transcript is never read, and the successor has no parent link (no `continues ← #<id>`). The focus is delivered verbatim as the successor's first message: +`--fresh` starts a clean conversation that takes only the source's project, cwd, model and effort, not its context. No handoff document is authored, no summary is generated, the source transcript is never read, and the successor has no parent link (no `continues ← #<id>`). The focus is delivered verbatim as the successor's first message: ```bash pan handoff self --fresh build a new Dwarf Fortress fort ``` -This is the right tool for starting unrelated work from a conversation you're already in — e.g. kicking off a fort-building session on a cheaper model from a research conversation — without carrying any of that context forward. +This is the right tool for starting unrelated work from a conversation you're already in (for example, kicking off a fort-building session on a cheaper model from a research conversation) without carrying any of that context forward. ### Fallback behavior `pan handoff <conv>` always tries to create a usable new conversation. If the -live-agent handoff can't complete, Overdeck falls back to a summary fork and +handoff can't be authored, Overdeck falls back to a summary fork and prints the reason: | Reason | Meaning | |:-------|:--------| -| `source-ended` | The source conversation is already ended. | -| `handoff-timeout` | The source didn't write both the document and its `.done` sentinel in time. | -| `handoff-validation` | The document didn't satisfy the handoff contract. | -| `source-workspace-devcontainer` | The source can't write to the host handoff directory from inside a workspace container. | - -A successful handoff prints the new conversation id, tmux session, model, -harness, dashboard link, and the handoff document path. Fallbacks print the same +| `source-ended` | The source conversation is already ended (source-authored handoffs only). | +| `handoff-timeout` | A source-authored handoff: the source didn't write both the document and its `.done` sentinel within 5 minutes. | +| `handoff-validation` | The document didn't satisfy the handoff contract, or the external authoring session never wrote it. | +| `handoff-request-failed` | Any other authoring failure, for example the external authoring session erroring or timing out. | +| `source-workspace-devcontainer` | The source can't write to the host handoff directory from inside a workspace container (source-authored handoffs only). | + +A successful handoff prints the new conversation id, terminal session, model, effort, +harness, project (when set), issue, handoff document path and dashboard link. Fallbacks print the same details plus a yellow fallback notice. ## Branch to explore -A handoff isn't only for the context wall — it's also how you **branch**. Fork a +A handoff isn't only for the context wall. It's also how you **branch**. Fork a conversation to try an alternative approach, keep the original intact, compare both, and continue with the one you like. Cheaper than restarting from scratch, and the original's context is never lost. ## What a conversation changed -Overdeck can list the commits and uncommitted edits each conversation made. +The work dock's **Changes** tab lists the commits and uncommitted edits each conversation made. Commits are tied to a conversation exactly by the `Overdeck-Conversation` trailer that Overdeck adds to every commit a conversation makes. Older commits, made before the trailer existed, are found from the `git commit` output in the conversation's own shell. Uncommitted edits are best effort. Claude Code conversations get per-line -counts, for example "4 of 6 uncommitted lines in this file are from this -conversation", and the other lines name the conversation that wrote them when -that conversation was opened recently. Conversations on other harnesses list -the file only. Edits made only through shell commands are not shown. +attribution: when other sessions also changed a file, its row says how many of +its uncommitted lines came from elsewhere and names the conversations that wrote +them when those conversations were opened recently. Conversations on other +harnesses list the file only, with a note that line attribution needs edit +records, which only Claude Code writes. Edits made only through shell commands +are not shown. A project's spend on its Home page now includes its conversations, and "today" follows the clock of the machine the dashboard runs on. @@ -821,7 +825,7 @@ checkout goes back to the default branch. The same sweep refreshes the stored state of linked PRs, so the badge renders without a live GitHub call. Open PRs refresh on every sweep, closed PRs at most every 15 minutes, and merged PRs are final and never re-read. A linked PR the project listing doesn't include (older -than its 100 most recent PRs, in another repository, or on a conversation +than the 100 most recent open and 100 most recent closed PRs it lists, in another repository, or on a conversation outside any GitHub project) is read on its own. After three failed reads in a row, Overdeck skips that repository for 15 minutes. @@ -857,14 +861,13 @@ pan conv prs <query> [--json] # * marks the PR shown `link-pr` records the source `agent` when it runs inside an agent (`OVERDECK_AGENT_ID` is set) and `manual` otherwise. The verbs go through the dashboard, so every open client updates at once. With the dashboard down they -write the link directly. They exit 2 when no conversation matches, and 1 on any +write the link directly. They exit 2 when no conversation matches or the match is ambiguous, and 1 on any other error. An Overdeck agent over MCP links a pull request with the `link_pull_request` tool instead (source `agent`), and can watch it with `watch_pull_request` to get a message here when its checks, review state, mergeability, or merged/closed -state changes — see [`configuration/mcp.mdx`](../configuration/mcp.mdx) -("Pull requests"). +state changes. See [MCP server: Pull requests](/configuration/mcp#pull-requests). Rules: @@ -891,9 +894,9 @@ by hand, linked by an agent, or on the same branch). Click one to open it. ### Issue links -Clicking an issue link in a conversation transcript — a GitHub issue of a +Clicking an issue link in a conversation transcript (a GitHub issue of a registered project, or a Linear issue whose prefix belongs to a registered -project — opens that issue's drawer in the dashboard instead of leaving the +project) opens that issue's drawer in the dashboard instead of leaving the page. The drawer still opens old closed issues the dashboard no longer lists, loading them on open. If the dashboard cannot load an issue, the drawer still shows the Issue button that opens the link's tracker page. Ctrl/Cmd-click, @@ -909,15 +912,15 @@ opens the tracker in a new tab. Inside a conversation transcript, text that names another conversation renders as a link once the dashboard resolves it: a name (`20261113-6031`, or `conv-20261113-6031`), a numbered form (`conv 3904`, `conversation 3904`, -`conv #3904`), or a `/conv/<id>` path — written as plain text, as the whole +`conv #3904`), or a `/conv/<id>` path, written as plain text, as the whole value of an inline code span, or as a hand-written Markdown link. The link's tooltip is the conversation's title, or its name when it has none. Fenced code never links, and a name the dashboard can't resolve (or hasn't resolved -yet) stays plain text — archived conversations still resolve and link. The +yet) stays plain text; archived conversations still resolve and link. The conversation currently being viewed is never turned into a link. A plain click opens the conversation in the dashboard, the same way clicking -its row in the left column does — no page reload. Ctrl/Cmd-click, +its row in the left column does, with no page reload. Ctrl/Cmd-click, middle-click and the browser's right-click menu open it in a new tab instead. As with issue links, this in-dashboard behaviour only applies to the main layout: in a pop-out window, the mobile app (`/m`), or the issue @@ -926,8 +929,8 @@ drawer, a plain click opens a new tab too. ### On issue and workspace rows The issue's row in the left column's Issues section (when you expand it), and -its row in the Workspaces section, show the same badge as a conversation's — the PR's number, -colored by state and review, with a `×` for failing checks — read from the +its row in the Workspaces section, show the same badge as a conversation's (the PR's number, +colored by state and review, with a `×` for failing checks), read from the issue's derived state rather than a conversation's link. It appears within seconds of `pan done` opening the PR. A PR that closed without merging is not shown there. @@ -959,7 +962,7 @@ GitLab merge request status, the Pull requests page, and search by PR number. ## Conversations from your other machines -Arrives in the next release (v0.65.0), and needs Session Vault set up on this machine +Needs Session Vault set up on this machine ([Session Vault](/configuration/session-vault)). Claude Code and Codex conversations that another machine saved to the vault appear in the @@ -992,7 +995,7 @@ for the CLI path instead of repeating it. ### Conversations that run on a linked machine With a [machine link](/configuration/linked-machines), the conversations another machine -runs appear in the list live, with an "on `<machine>`" chip, and open at +runs appear in the list live, with a chip naming the machine (tooltip "Runs on `<machine>`"), and open at `/conv/@<environment-id>/<name>`. You control them as if they ran here; the title bar shows which machine owns each one. @@ -1028,9 +1031,9 @@ main** and the per-turn chips, the window has a **Compare…** view for any two points in the conversation's repository. It works in a local-only repository too: no remote and no pull request are needed. -**All turns** lists the files this conversation changed — its own commits and +**All turns** lists the files this conversation changed (its own commits and the uncommitted files its edits touched, the same list as the Changes tab's -**This conversation** — and nothing other agents changed in the same +**This conversation**) and nothing other agents changed in the same checkout; **vs main** and **Compare…** show the wider comparisons. A file changed only through a shell command without a commit made by this conversation is not listed under All turns. Opening a file under All turns @@ -1064,30 +1067,30 @@ current file", since Compare can point at an arbitrary ref the window cannot read directly. A deleted file has no Preview. The bar's **Open file** action is not available in the diff window; inside a Command Deck tab, use the turn card's rows or a file path in the reply to open a file beside the chat. -Relative links in the preview show as plain text for now, until they resolve -to files. +Relative links in the preview show as plain text in the diff window, which has +no pane to open a file in; a link to a file that does not exist shows as not found. ## Settling and snoozing conversations The conversation list groups rows into four sections, top to bottom: **Needs you**, **Inbox**, **Snoozed**, and **Settled**. A group with any pending question, plan-mode prompt, or approval request always shows in Needs you, -regardless of its stored settle or snooze state — the group returns to +regardless of its stored settle or snooze state; the group returns to Snoozed or Settled once the question is answered. Inbox has no header. Snoozed and Settled each show a count and are collapsed by default; click the header to expand. -**Settling** marks a conversation done for now without stopping it — the +**Settling** marks a conversation done for now without stopping it: the session keeps running, and nothing about it changes except where it sits in the list. This is different from [stopping or archiving](#stopping-or-archiving-a-conversation), which end the session. Settle (and Unsettle) are available from the row's checkbox, the row's overflow menu, and the tab menu. **Snoozing** hides a conversation until a chosen time, after which it moves -back to Inbox on its own — there is no server timer and no dashboard restart +back to Inbox on its own. There is no server timer and no dashboard restart can lose or delay it, since the wake check runs on the client against the stored time. Choose **Snooze** from either menu for presets (1 hour, this -evening, tomorrow morning, next week) or **Custom…** for any future date and +evening, tomorrow morning, next week) or the date and time field under them, then **Snooze**, for any future date and time; **Unsnooze** clears it early. A snoozed row shows when it comes back, such as "back tomorrow 09:00". @@ -1127,22 +1130,22 @@ it off. Conversations also settle themselves when their pull requests merge [Pull requests on conversations](#pull-requests-on-conversations). A [scheduled run](#scheduled-runs) delivering its prompt also clears any -settle or snooze on that conversation — settling or snoozing never buries a +settle or snooze on that conversation, so settling or snoozing never buries a conversation past its next scheduled run. ## Stopping or archiving a conversation -Stop is the `X` on the row, "Stop agent" in the row menu or the tab menu, or -"Stop the agent" in the conversation header menu; Archive is in those same menus. After you stop +Stop is the `X` on the row, "Stop agent" in the tab menu, or +"Stop the agent" in the conversation header menu; Archive is in the row menu, the tab menu, and the header menu ("Archive conversation"). After you stop or confirm archive, the row dims and stops responding to clicks, and its second line reads "Stopping…" or "Archiving…" (a nested row shows the label after the title instead); the row's `X` becomes a spinner. The conversation header shows the same status. The row stays dimmed until the conversation -list has refreshed — then a stopped row shows its stopped (gray) dot, and an +list has refreshed. Then a stopped row shows its stopped (gray) dot, and an archived row leaves the list with a toast reading `Archived "<title>"` and its tab closes. On failure, an error toast shows the server's message and -the row returns to normal. Both end the session; settling (above) does not -— a settled conversation keeps running and can still be unsettled back to +the row returns to normal. Both end the session; settling (above) does not: +a settled conversation keeps running and can still be unsettled back to Inbox. ## Resuming a stopped conversation @@ -1190,9 +1193,11 @@ conversations stay stopped and you can still resume each one. It covers Herdr hosts, where the dashboard sees the backend's event stream drop and come back. See [Terminal backends](https://github.com/eltmon/overdeck/blob/main/docs/TERMINAL-BACKENDS.md#after-a-session-server-restart-pan-5091) for the details. +After `pan shutdown`, the same Needs you row offers the sessions the shutdown stopped (`Resume the <N> sessions shutdown stopped`), and Resume all resumes those conversations, then the work agents. + ## Search your conversations -The command palette (`⌘J` / `Ctrl+J`, see [Command palette](/features/keyboard-shortcuts#command-palette)) +The command palette (`⌘K` / `Ctrl+K`, or `⌘J` / `Ctrl+J` to open it on conversations; see [Command palette](/features/keyboard-shortcuts#command-palette)) searches conversation titles and transcript text. From the command line, `pan conv` searches a separate catalog instead, built by scanning and enriching your sessions; see [Search from the command line](#search-from-the-command-line) below. @@ -1308,7 +1313,7 @@ The Settings → Conversations card also has a **Semantic embeddings** switch, o **Embedding provider** (OpenAI, Voyage AI or Ollama), **Embedding model**, **Auto-embed after deep enrichment** and **Test connection**. `conversations.embeddings` turns this on; with `embedding_auto_on_deep` also on, it embeds a session right after a tier 2 or 3 `pan conv enrich` -run. In `~/.overdeck/config.yaml` under `conversations:`, the matching keys are `embeddings` +run. The automatic embed also needs **Settings → Background AI → Session embeddings** on (off by default) and low-cost mode off. In `~/.overdeck/config.yaml` under `conversations:`, the matching keys are `embeddings` (defaults to `false`), `embedding_provider` (`openai`, `voyage` or `ollama`), `embedding_model` and `embedding_auto_on_deep`. @@ -1320,11 +1325,11 @@ for every `pan conv` command too. ## See also - [Conversation Commands](/cli/conversation-commands): full CLI reference for `pan conv`, `pan handoff`, `pan fork`, `pan tell`, `pan resume`, `pan unarchive-conversation`, `pan open` and `pan share` -- [Mission Control](/features/mission-control) — the project tree and activity timeline around your conversations -- [Cloister](/features/cloister) — model routing, stuck-agent detection, and lifecycle management -- [Harnesses](/configuration/harnesses) — `claude-code` vs `pi`, and the ToS rules that gate them -- `pan conv current` (alias `pan conv whoami`) — print the conversation you're running inside -- `pan fork [conv]` — create a summary or plain fork without asking the source agent to author a handoff +- [Command Deck](/features/mission-control): the deck, panes and project tree around your conversations +- [Cloister](/features/cloister): model routing, stuck-agent detection, and lifecycle management +- [Harnesses](/configuration/harnesses): `claude-code` vs `pi`, and the ToS rules that gate them +- `pan conv current` (alias `pan conv whoami`): print the conversation you're running inside +- `pan fork [conv]`: create a summary or plain fork without asking the source agent to author a handoff - [Session Vault](/configuration/session-vault): save conversations off-machine and continue them elsewhere - [Command palette](/features/keyboard-shortcuts#command-palette): find actions, issues, files and conversations with Ctrl+K diff --git a/features/convoys.mdx b/features/convoys.mdx index 10c4d80f374..0e06bfcb10b 100644 --- a/features/convoys.mdx +++ b/features/convoys.mdx @@ -1,6 +1,7 @@ --- -title: "Review convoy" -description: The review convoy, four parallel reviewers and one synthesis parent +title: "Review convoy: four parallel reviewers and a synthesis parent" +sidebarTitle: "Review convoy" +description: "How Overdeck's review convoy works: four parallel reviewers for security, correctness, performance and requirements, and the synthesis parent." --- import { ThemedImage } from "/snippets/themed-image.mdx"; @@ -97,7 +98,7 @@ Four reviewers run at the same time, each focused on one concern: `<issue>` is the lowercase issue id, for example `agent-pan-123-review-security`. Each reviewer's model comes from `roles.review.sub.<lane>.model`, set in the -dashboard's Roles panel or in `~/.overdeck/config.yaml`. +Role Models panel of Settings → Model Routing, or in `~/.overdeck/config.yaml`. Each reviewer: - Reviews the PR's diff independently @@ -146,21 +147,22 @@ The reports are evidence, not votes. The parent decides the verdict. The synthesis report has this shape: ```markdown -# Verdict: APPROVED | CHANGES_REQUESTED | FAILED - -## Summary - -## Blockers - -## Evidence - -## Convoy Notes +# Review <issueId> +## Verdict: APPROVED / CHANGES REQUESTED +## Context +## Blocking Findings +## Non-blocking Findings +## Coverage +## Verification +## Scope Note ``` +A synthesis report also names each lane's signal and report, including any lane that failed or timed out. + ## Review modes The review mode decides whether a review runs as a convoy. Set it in the -dashboard's Roles settings panel, or with `roles.review.mode` in +**Review mode** field of Settings → Model Routing → Role Models, or with `roles.review.mode` in `~/.overdeck/config.yaml`. It applies to every review. | Mode | What runs | @@ -226,14 +228,14 @@ the next review runs. Reviewers appear in the issue view next to the work agent they review, with their status, model, cost and verdict. The Pipeline page groups every issue -and its agents by phase (Ship, Review, Verifying), with a metric strip across -the top (Active issues, Work running, Review queue, Ship, Spend) and a live -activity feed on the right. +and its agents by phase (Ship, Review, Work, Plan, Ready), with a metric strip +across the top (Active issues, Work running, Review running, Ship, Spend). Its +List, Board and Analytics buttons switch views. <ThemedImage light="/images/dashboard/pipeline-light.png" dark="/images/dashboard/pipeline-dark.png" - alt="Pipeline page: a metric strip showing Active issues, Work running, Review queue, Ship, and Spend over phase-grouped issue rows, with a live activity feed on the right." + alt="Pipeline page: a metric strip showing Active issues, Work running, Review running, Ship, and Spend over issue rows grouped by phase (Ship, Review, Work), with phase and project filter chips above them." /> **CLI:** @@ -259,7 +261,7 @@ backend. See [Reaching an agent from a shell](/configuration/terminal-backend#re - Performance reviews of hot paths - Checking a change against its acceptance criteria -When reviews run across several projects at once, the God View gives an +The God View is experimental: turn on Settings → Experimental → **Experimental features** to see it. When reviews run across several projects at once, the God View gives an aggregate cross-project picture of every agent's activity in one place. Review convoys orbit their issue, so a convoy whose reviewers have stalled or are burning more than expected is easy to spot. @@ -320,10 +322,14 @@ to post the PR review. - Check the lane report for permission or access errors - Check that the PR has a diff against its base branch +## Get help + +Ask on [Discord](https://discord.gg/ZpHE2ZTv5P) or open an issue on [GitHub Issues](https://github.com/eltmon/overdeck/issues). + ## Related Guides - [Issue pipeline](/features/issue-pipeline) - Every stage from start to merge - [Terminal backend](/configuration/terminal-backend) - Reaching an agent from a shell - [Skills](/features/skills) - Subagents and skill system -- [Specialists](/features/specialists) - Long-running specialist agents +- [Review and test agents](/features/specialists) - What checks an agent's work after pan done - [Cloister](/features/cloister) - AI lifecycle management diff --git a/features/costs.mdx b/features/costs.mdx index 8b1600038b8..f065f3f6e6d 100644 --- a/features/costs.mdx +++ b/features/costs.mdx @@ -27,8 +27,8 @@ Run on its own, it only prints what it would import, as a dry run. Run ## API prices, not your plan bill Every dollar figure is tokens multiplied by the published API price for the model, from -Overdeck's own price table. The same table prices Claude Code, Codex, Kimi, Grok and Muse -sessions. Pi is the exception: a Pi session uses the cost Pi itself reports for a message when Pi +Overdeck's own price table. The same table prices Claude Code, Codex, Kimi and Muse +sessions. Pi and Grok are the exceptions: a Pi or Grok session uses the cost the harness itself reports when it reports one, and falls back to Overdeck's price table only when it does not. This matters most on a subscription plan, such as Claude Max or a ChatGPT plan: Overdeck does not @@ -37,14 +37,15 @@ page and in `pan cost` is what the same tokens would cost at list API prices, no actually pay, and there is no separate plan-cost view. A model with no row in the price table records no cost: the Claude Code hook skips the event -entirely, and Pi and Muse record it with a cost of `0` and (for Pi) an `unpriced-model` warning. +entirely, and Pi, Grok and Muse record it with a cost of `0` and (for Pi) an `unpriced-model` warning. A Pi or Grok +session that reported its own cost for the message records that cost instead. Mis-priced models are tracked in [#4844](https://github.com/eltmon/overdeck/issues/4844). ## How spend is attributed Every cost event carries the issue id and agent id that Overdeck set when it launched the agent. -A Claude Code session with no issue id falls back to its git branch: if the branch name contains -one of five tracker prefixes (`pan`, `min`, `aud`, `krux`, `cli`) followed by a number, the event +A Claude Code session with no issue id falls back to its git branch, then to its working directory: if either contains +one of five tracker prefixes (`pan`, `min`, `aud`, `krux`, `cli`) followed by a hyphen and a number (for example `feature/pan-123`), the event is recorded against that issue. Do not expect this fallback to work for other prefixes or for other harnesses. @@ -57,7 +58,7 @@ Spend is also grouped by **stage**, the role the session ran as, such as `implem `review.security`; there are more stages than these two examples. **Today** starts at local midnight on the dashboard machine, **week** starts at the beginning of -the day seven days ago, and **month** covers the last 30 days. Project Home's weekly figure reads +the UTC day seven days ago, and **month** starts at the beginning of the UTC day 30 days ago. Project Home's weekly figure reads the archive for these windows, while the Costs page's issue list reads a separate rollup in the database; the two totals are not guaranteed to reconcile exactly. diff --git a/features/dashboard-views.mdx b/features/dashboard-views.mdx index c9fdeaa2533..15d0483b248 100644 --- a/features/dashboard-views.mdx +++ b/features/dashboard-views.mdx @@ -62,7 +62,7 @@ server setting. **Simple Home** leads with a headline that counts what needs you (or reads "Hello."), three stats (`being worked on`, `ready to merge`, `finished this week`), the composer, and the Get set up card. Below that, sections appear in order: Needs you, Ready to start (only when non-empty), Having trouble -(only when non-empty), Just filed, Working now, Ready to merge, and Finished (up to 8 rows). Simple +(only when non-empty), Just filed, Working now, Ready to merge, and Finished (up to 8 rows); only Needs you and Working now show when empty. Simple Home never merges on its own; you click **Merge to main** yourself. **Advanced Home** leads with the title "System briefing", the composer and the Get set up card, then @@ -83,7 +83,7 @@ before filing anything). A project chip picks which project the work lands in; i best. Nothing here stops you from starting." Its rows cover signing in to Claude, connecting GitHub, getting agents ready (shown only when the terminal backend is not tmux), installing a terminal helper, and Docker (optional); Advanced mode adds a row for reaching the machine remotely when no -machine is linked. A memory line warns that new agents may wait when free memory is low. **Set up** +machine is linked and Tailscale is not ready yet. A memory line warns that new agents may wait when free memory is low. **Set up** expands a row to the commands to run yourself (the card never installs anything for you), and **Re-check** re-runs the checks. The **Hide** (×) button dismisses the card for your browser, but it comes back while a required check still fails. On every other view, a top banner offers the same @@ -108,7 +108,7 @@ another column does nothing. To move an issue forward, use its action menu inste ## Pipeline The Pipeline (`/pipeline`) has a `List` / `Board` / `Analytics` switch (Board opens the Board view, -Analytics opens Metrics) and five metric tiles: Active issues, Work running, Review running, Ship, +Analytics opens Metrics, which is experimental, so with [Experimental features](#experimental-features) off it lands on Home) and five metric tiles: Active issues, Work running, Review running, Ship, and Spend (24h). Rows are grouped into five lanes, in order: **Ship**, **Review**, **Work**, **Plan**, **Ready**. Raw backlog issues are not shown; a backlog issue appears under Ready once it carries the `ready` label or the tracker marks it unstarted. @@ -175,7 +175,7 @@ Edits go through `/okf author`; anything typed in the viewer itself is discarded Context (`/context`) is headed "Agent context". Pick where text applies (Machine context, Project context, Workspace context), **Edit source** it, or use **Preview for agent** to see what a given harness actually receives, then **Save** or **Save & refresh outputs**. From the CLI, `pan context` -offers `list`, `edit`, `sync`, `diff`, `validate` and `migrate`. See +offers `list`, `edit`, `sync`, `diff`, `validate`, `migrate` and `detach`. See [Context layers](/configuration/context-layers). ## Skills diff --git a/features/desktop-app.mdx b/features/desktop-app.mdx index dd354476e4d..9fbca5f0427 100644 --- a/features/desktop-app.mdx +++ b/features/desktop-app.mdx @@ -65,11 +65,11 @@ If you already installed the app, `pan up` finds and launches it instead of star - **macOS**: `/Applications/Overdeck.app` or `~/Applications/Overdeck.app` - **Windows**: `%LOCALAPPDATA%\Programs\Overdeck\Overdeck.exe` -On Linux, `pan up` also treats `~/.local/bin/overdeck` as the app. The install script puts the `overdeck` command there, so `pan up` reports `Desktop app launched` and opens the dashboard in your browser instead ([#5557](https://github.com/eltmon/overdeck/issues/5557)). +On Linux, `pan up` also treats `~/.local/bin/overdeck`, `~/.local/share/applications/overdeck` and `/usr/local/bin/overdeck` as the app, and checks them before `~/Applications/`. The install script puts the `overdeck` command in `~/.local/bin`, so `pan up` reports `Desktop app launched` and opens the dashboard in your browser instead ([#5557](https://github.com/eltmon/overdeck/issues/5557)). ### What runs where -The app's embedded server listens on port `7825` (it is not the `pan up` dashboard's port). `pan open` always talks to the `pan up` dashboard; see [The desktop app](/features/open-in-overdeck#the-desktop-app) for how it reaches the app's own window. `pan down` stops the `pan up` dashboard only; it does not quit the app, which you quit from its tray or menu. +The app's embedded server listens on port `7825` (it is not the `pan up` dashboard's port); while it restarts after crashes, the port is `7825` plus the number of consecutive restarts since the last healthy start, at most `7833`. `pan open` always talks to the `pan up` dashboard; see [The desktop app](/features/open-in-overdeck#the-desktop-app) for how it reaches the app's own window. `pan down` stops the `pan up` dashboard only; it does not quit the app, which you quit from its tray or menu. Only one copy of the app runs at a time: launching it again focuses the existing window, and launching it with `--open <path>` opens that path in the running window. Closing the window keeps the app running in the background on macOS; on Linux and Windows, closing the last window quits the app and stops its embedded server. @@ -107,7 +107,7 @@ Clicking one reopens that question, plan or permission dialog, or brings the das **Settings → Desktop App → Auto-start → Launch at login** starts the app automatically when you log in. It works on macOS and Windows; on Linux it has no effect yet ([#5556](https://github.com/eltmon/overdeck/issues/5556)). -On the first launch, a dialog asks whether to start Overdeck automatically, with an option to enable it or skip for now. If you skip it, a reminder toast appears on the next few launches with a button to enable it; after five reminders, or once you enable it, the reminders stop. **Reset reminder** in the Auto-start card starts that sequence again. +On the first launch, a dialog asks whether to start Overdeck automatically, with an option to enable it or skip for now. If you skip it, a reminder toast appears on the next few launches with a button to enable it. The toasts count up to "Reminder 5 of 5" (four toasts after the first dialog). After that, or once you enable it, the reminders stop. **Reset reminder** in the Auto-start card starts that sequence again. Desktop settings, including this one, save to `desktop-settings.json` in the app's user data folder: `~/.config/Overdeck/` on Linux, `~/Library/Application Support/Overdeck/` on macOS, and `%APPDATA%\Overdeck\` on Windows. @@ -115,7 +115,7 @@ Desktop settings, including this one, save to `desktop-settings.json` in the app The app checks GitHub Releases 5 seconds after launch and every 4 hours after that, but it never downloads an update on its own. Use **Help → Check for Updates...**, or click the version number at the bottom of the left column, to open the updater, download the update, and restart into it. Once a download finishes, **Install Update and Restart** appears in the Help menu too. -A canary build (a version ending in `-canary`) only offers canary releases; a stable build only offers stable releases. +A canary build (a version containing `-canary`, such as `1.2.3-canary.1`) only offers canary releases; a stable build only offers stable releases. If an update cannot install, download the new installer from [GitHub Releases](https://github.com/eltmon/overdeck/releases/latest) and install it over the old one. This is the only way to update on macOS today, since the app is not notarized (see [Download and install](#download-and-install)). diff --git a/features/file-explorer.mdx b/features/file-explorer.mdx index 6d62f720ea9..7688012b04a 100644 --- a/features/file-explorer.mdx +++ b/features/file-explorer.mdx @@ -1,6 +1,7 @@ --- -title: File explorer -description: Browse, edit and ship changes to any project's files from the dashboard +title: "File explorer and code editor" +sidebarTitle: "File explorer" +description: "Browse, edit and ship changes to any project's files from the dashboard, with edit workspaces, search, trash and pull requests." --- # File explorer @@ -87,9 +88,9 @@ Files that are not plain text open in a viewer: images, PDF, audio, fonts, large ## File actions -Right-click in the tree, or use the header buttons, to create files and folders, rename, duplicate and delete. Drag rows to move them. A deleted entry goes to the Overdeck trash in `~/.overdeck/trash/` and stays there for 7 days. `Ctrl/Cmd+Z` undoes the last file action and `Ctrl/Cmd+Shift+Z` redoes it. +Right-click in the tree, or use the header buttons, to create files and folders, rename, duplicate and delete. Drag rows to move them. A deleted entry goes to the Overdeck trash in `~/.overdeck/trash/` and stays there for 7 days. With the tree focused, `F2` renames the selected row, `Delete` (or `⌘⌫` on macOS) deletes the selection, `Ctrl/Cmd+Z` undoes the last file action and `Ctrl/Cmd+Shift+Z` redoes it. -Drop files from your computer onto a folder to upload them. You can download a file, or a folder as a `.tar.gz` archive, and drag rows into a conversation composer to reference those files. +Drop files from your computer onto a folder to upload them. Each file can be up to 100 MB, and an upload never replaces a file of the same name. You can download a file, or a folder as a `.tar.gz` archive, and drag rows into a conversation composer to reference those files. ## Edit workspaces diff --git a/features/flywheel.mdx b/features/flywheel.mdx index 9c8e0b60824..c0b886d82fd 100644 --- a/features/flywheel.mdx +++ b/features/flywheel.mdx @@ -20,13 +20,13 @@ Each tick is one pass through five phases: 4. **Launch**: start the issue with `pan start`, the loop's only launcher. If `pan start` fails with a disk-low error, the loop launches nothing else that tick and raises a Needs-you item instead. 5. **Watch to landing**: follow the issue's pull request through review, tests and merge. -A fifth step, parking, runs whenever the loop cannot decide something on its own: it parks the issue and moves on rather than blocking the tick on a question only you can answer. +Another step, parking, runs whenever the loop cannot decide something on its own: it parks the issue and moves on rather than blocking the tick on a question only you can answer. The loop schedules its own next tick with a background sleep: 450 seconds while anything is in flight, 1000 seconds when idle, never longer than 1000 seconds. It stops on its own only when nothing is pickable and nothing is in flight, reporting itself idle with a Needs-you item saying so. Rails that hold regardless of what it picks: -- It orchestrates and never writes code, specs or plans; the only files it writes are `.pan/flywheel/state.md` and `.pan/flywheel/report.md`. +- It orchestrates and never writes code, specs or plans; the only files it writes are `.pan/flywheel/state.md`, `.pan/flywheel/report.md` and its `.pan/parked.md` list. - It keeps to `roles.flywheel.maxAgents` (default 30) as its own instruction, not a check `pan start` makes. - It never merges or deep-wipes anything itself; merges follow the merge policy, see [Auto-merge](/configuration/auto-merge). - It never adds or removes the operator-only labels `released`, `vetoed`, `auto-merge` or `hold-for-uat`; its `gh` access refuses those writes. @@ -79,7 +79,7 @@ Order matters too: a bound or running order book's items come first (see [Order ## The three switches -The Flywheel page header shows three switches. They are global app settings, not per project. +The Flywheel page header shows three switches. They are global app settings, not per project, except that a project can opt out of the merge train with `merge_train: disabled` in `projects.yaml`. | Switch | Default | What it does | | --- | --- | --- | @@ -87,7 +87,7 @@ The Flywheel page header shows three switches. They are global app settings, not | Require UAT | on | The global fallback of the merge policy: a ready PR waits for your Merge click unless the issue's Auto/Hold toggle or the project's `auto_merge_default` says otherwise. | | Merge train | off | On: normal-priority PRs wait and merge together as one batch once the batch checks are green; high-priority PRs such as strikes still merge on their own. Off: each ready PR that is not held merges on its own. | -Require UAT holds a ready PR for your Merge click; it never requires a passed UAT verdict before merge. A failed UAT verdict at the head commit does block merge on its own, independent of this switch; see [Issue pipeline](/features/issue-pipeline) for that distinction. +Require UAT holds a ready PR for your Merge click; it never requires a passed UAT verdict before merge. A failed UAT verdict at the head commit blocks merge only while the issue is held for UAT, so with this switch off and no `hold-for-uat` label or project hold, it does not block; see [Issue pipeline](/features/issue-pipeline) for that distinction. Batch size and wait for the merge train live in **Settings → Merge Train**; see [Auto-merge](/configuration/auto-merge) for the full merge policy and [Merge batches](/features/merge-batches) for how the train itself works. @@ -95,13 +95,13 @@ Batch size and wait for the merge train live in **Settings → Merge Train**; se ### Header -The header shows a run chip: `running · tick N`, `paused`, `idle`, or `unreachable` when the status read itself fails. The page never shows `idle` for a failed read; a failed read always shows `unreachable`. Next to it sits a freshness badge, the conversation's running duration, an in-flight count (`N in flight · M shipped today`), and the three switches. +The header shows a run chip: `running · tick N`, `paused`, `idle`, or `unreachable` when the status read itself fails. A failed read never shows `idle`: before any status has loaded the chip shows `unreachable`; after that the chip keeps the last status and the Status tab notes that it is showing the last status. Next to it sits a freshness badge, the conversation's running duration, an in-flight count (`N in flight · M shipped today`), and the three switches. Freshness has three states: `live` when the last tick was 60 seconds or less ago, `breathing` when it was 20 minutes or less ago, and `stalled` when it is older than that. ### The rail -The left rail stacks, top to bottom: the merge train card (one per project, linking [Merge batches](/features/merge-batches)), the running order book card when one is bound, and the Flywheel card itself, which has four tabs: **Status**, **State**, **Report** and **Stats**. The State tab renders `.pan/flywheel/state.md`, the Report tab renders `.pan/flywheel/report.md`, and the Stats tab shows the same substrate-bug stats as `pan flywheel stats`. The rail is resizable and stacks above the conversation on narrow screens. +The left rail stacks, top to bottom: the **Merge train** card (every project's train in one card, with project filter chips; see [Merge batches](/features/merge-batches)), the running order book card when one is bound, and the Flywheel card itself, which has four tabs: **Status**, **State**, **Report** and **Stats**. The State tab renders `.pan/flywheel/state.md`, the Report tab renders `.pan/flywheel/report.md`, and the Stats tab shows the same substrate-bug stats as `pan flywheel stats`. The rail is resizable and stacks above the conversation on narrow screens. ### The lane board @@ -117,9 +117,9 @@ The right column holds the `conv-flywheel` conversation itself, with its own com Needs-you items come from the tick marker's `needs-you=` field, one item per `; `-separated part. The loop keeps an item's wording identical until it is resolved, because the page matches items by their exact text. -Each card shows the question, why it came up, and when (`tick <n> · HH:MM · <age>`). An issue id opens that issue; text written as `owner/repo#<n>` links to the GitHub pull request or issue; an item ending in a URL inside angle brackets (for example `<https://...>`) renders as a link. A real control appears only where one applies: the test-removal waiver, **Start** then **Confirm start**, or **Open `<ID>`**. +Each card shows the question, why it came up, and when (`tick <n> · HH:MM · <age>`). An issue id opens that issue; text written as `owner/repo#<n>` links to the GitHub pull request or issue; an item ending in a URL inside angle brackets (for example `<https://...>`) renders as a link. A real control appears only where one applies: the test-removal waiver, **Start `<ID>`** then **Confirm start**, or **Open `<ID>`**. -**Show where this was raised** opens the `conv-flywheel` conversation at the message that first raised the item, or reopens a pending question. +The **show message** link (labelled "Show where this was raised" for screen readers) opens the `conv-flywheel` conversation at the message that first raised the item, or reopens a pending question. The top bar's `Needs you · N` button counts the one shared Needs-you list, which includes Flywheel items, and is always shown. See [Issue pipeline](/features/issue-pipeline) for Needs you in general. @@ -135,7 +135,7 @@ These are two different things, and the page keeps them apart. - `zombie-session`: a live agent on an issue that is already closed. - `idle-running`: a live agent idle for 6 hours or more with no pipeline stage owning the next move. -`--json` prints the raw rows. `pan parked` does not list issues parked by the `parked` label or by a `.pan/parked.md` listing; those only ever show up on this page. +`--json` prints the raw rows. `pan parked` does not list issues parked by the `parked` label or by a `.pan/parked.md` listing; those show up on this page and as state `parked` in `pan show`. ## The backlog sequencer @@ -171,7 +171,7 @@ The loop and the sequencer each keep their state in a few plain files under the ## Known limits - The loop's author gate names fixed GitHub logins: it acts only on issues whose author is `eltmon` (the Overdeck maintainer) or `panopticon-agent[bot]`, or that are assigned to `eltmon`. On any other repo or account the loop skips your issues, and the current GitHub App bot (`overdeck-agent[bot]`) does not pass it either. See [issue #5544](https://github.com/eltmon/overdeck/issues/5544). -- The Backlog page and its automatic pass read the sequence from the dashboard server's working directory, the Overdeck checkout or install it runs from. There is no project picker yet. +- The Backlog page and its automatic pass read the sequence from the dashboard server's working directory, the Overdeck checkout or install it runs from. There is no project picker yet, and a pass ranks only issues whose id starts with `PAN-` (Overdeck's own tracker), so on any other project the sequencer has nothing to rank. - The agent cap (`roles.flywheel.maxAgents`) and the pickup rule are applied by the loop's own instructions; `pan start` checks neither on its own. - There is one Flywheel conversation per Overdeck install, `conv-flywheel`. diff --git a/features/issue-pipeline.mdx b/features/issue-pipeline.mdx index 0d6ccf4236c..0dcabc4bd01 100644 --- a/features/issue-pipeline.mdx +++ b/features/issue-pipeline.mdx @@ -55,7 +55,7 @@ Once preflight passes, `pan done` rebases the branch onto the target branch and Once `pan done` pushes, the dashboard runs the project's quality gates against the PR head before review starts. Gates come from `quality_gates` in `projects.yaml` (see [Projects](/configuration/projects)), or default to typecheck, lint and test. -The `verification.tests` setting picks `ci` or `local` test mode, and when it is unset Overdeck detects it: `ci` when a GitHub Actions workflow runs a recognizable test job on pull requests, otherwise `local`. In CI mode the host skips its own test gate, because the CI test job on the PR head is the test gate. +The per-project `verification.tests` setting in `projects.yaml` picks `ci` or `local` test mode, and when it is unset Overdeck detects it: `ci` when a GitHub Actions workflow runs a recognizable test job on pull requests, otherwise `local`. In CI mode the host skips its own test gate, because the CI test job on the PR head is the test gate. A failed gate sends the work agent a message naming the failed check and asking it to fix, push and request review again. Review never starts until verification passes. Overdeck allows up to 3 attempts per PR head; on the last attempt, or when the same check fails twice in a row, it pauses the work agent with a Needs-you signal instead of retrying further. @@ -73,7 +73,7 @@ There is no hard limit on review rounds, but after at least 3 rounds where the b ## Tests and UAT -A single test role owns both ordinary test-suite execution and browser-based UAT; there is no separate UAT role. It runs the project's gates, decides from the issue's acceptance criteria whether browser UAT is needed, and when it is, drives the workspace's built dashboard with Playwright. It records two separate verdicts, tests and UAT. +A single test role owns both ordinary test-suite execution and browser-based UAT; there is no separate UAT role. It runs the project's gates, decides from the issue's acceptance criteria whether browser UAT is needed, and when it is, drives the workspace's own running app with Playwright. It records two separate verdicts, tests and UAT. For a project in CI mode, the CI test job on the PR head is the test gate, so the merge gate requires it directly. While an issue is held for UAT, the default (see [Merge](#merge)), a failed UAT verdict at the PR head blocks merge: it is treated as evidence the code does not work. With the hold off for that issue, a failed UAT verdict does not block merge. @@ -107,7 +107,7 @@ Every merge path, whether it is Awaiting Merge, the Merge button, auto-merge, th Clicking Merge asks the gate first. A PR that is already clean merges directly; otherwise the server rebases onto main for you, and if that rebase itself fails, it falls back to asking the work agent to rebase and push. Either way the merge itself is a squash merge. [Awaiting Merge](/features/dashboard-views#awaiting-merge) is where ready issues wait for this click. -By default a ready PR waits for you: the per-issue `auto-merge` or `hold-for-uat` label (set by the Awaiting Merge row's `Auto` / `Hold` toggle) wins if set, otherwise the project's own default, otherwise the global `require_uat_before_merge` setting, which defaults to true. With the hold off for an issue, its ready PR is scheduled and merges itself after a 5-minute cooldown; `pan merge cancel <id>` stops one during that window. See [Auto-merge](/configuration/auto-merge) for the full policy, and [Merge batches](/features/merge-batches) for the merge train, which is off by default. +By default a ready PR waits for you: the per-issue `auto-merge` or `hold-for-uat` label (set by the Awaiting Merge row's `Auto` / `Hold` toggle) wins if set, otherwise the project's own default, otherwise the global Require UAT switch on the [Flywheel](/features/flywheel) page (app setting `flywheel.require_uat_before_merge`), which defaults to on. With the hold off for an issue, its ready PR is scheduled and merges itself after a 5-minute cooldown; `pan merge cancel <id>` stops one during that window. See [Auto-merge](/configuration/auto-merge) for the full policy, and [Merge batches](/features/merge-batches) for the merge train, which is off by default. Awaiting Merge also has a Pipeline Override section for PRs that are not yet ready: `Force Approve` and `Force Merge` both bypass the pipeline, behind a confirmation step, for the rare case where you need to move a PR on without waiting for the gate. diff --git a/features/keyboard-shortcuts.mdx b/features/keyboard-shortcuts.mdx index 6b0b73001d2..3f7e43d9fb3 100644 --- a/features/keyboard-shortcuts.mdx +++ b/features/keyboard-shortcuts.mdx @@ -1,5 +1,6 @@ --- -title: Keyboard shortcuts +title: "Dashboard keyboard shortcuts" +sidebarTitle: "Keyboard shortcuts" description: "Every Overdeck dashboard keyboard shortcut, with its keys on macOS, Linux and Windows, and the pages where each shortcut works." --- @@ -18,7 +19,7 @@ Press `?` anywhere outside a text field to open the **Keyboard shortcuts** sheet | Search | `/` | `/` | | Go to Pipeline | `G` then `P` | `G` then `P` | | Go to Board | `G` then `B` | `G` then `B` | -| Go to Agents | `G` then `A` | `G` then `A` | +| Go to Agents (experimental; opens Home while Experimental features is off) | `G` then `A` | `G` then `A` | | Go to Command Deck | `G` then `C` | `G` then `C` | | Keyboard shortcuts sheet | `?` | `?` | | Go to Stage tab 1 to 9 | `⌘1` to `⌘9` | `Ctrl+Alt+1` to `Ctrl+Alt+9` | @@ -36,6 +37,19 @@ Press `?` anywhere outside a text field to open the **Keyboard shortcuts** sheet For the `G` shortcuts, press `G`, let go, then press the second key within one and a half seconds. For every view these shortcuts reach, see [Dashboard views](/features/dashboard-views). +## Keys on single pages + +These keys work only where named, and the `?` sheet does not list them. + +| Action | macOS | Linux and Windows | Where | +| --- | --- | --- | --- | +| Next or previous issue, then open it | `J` / `K`, then `↵` | `J` / `K`, then `↵` | Board and Pipeline, when you are not typing | +| Undo the last status move | `⌘Z` | `Ctrl+Z` | Board | +| Undo the last settle or snooze | `⌘Z` | `Ctrl+Z` | the Conversations list, when it has focus | +| Open the folder in your preferred editor | `⌘⇧O` | `Ctrl+Shift+O` | a conversation, or an issue's open-in picker | +| Voice input | `⌘⇧M` | `Ctrl+Shift+M` | the conversation composer | +| God View help, fullscreen | `H` or `?`, `F` | `H` or `?`, `F` | God View (experimental) | + ## Command palette Press `⌘K` (macOS) or `Ctrl+K` (Linux and Windows) to open the command palette with every result @@ -85,7 +99,7 @@ ranked. Single keys such as `N`, `?`, `/`, `[`, `J`, `K` and the `G` shortcuts, and the Stage tab keys, work only when you are not typing. They do nothing while focus is in a text field, a terminal or a code editor, so the key goes to what you are typing in. -Shortcuts with `⌘` or `Ctrl`, such as the command palette, also work in text fields and code editors. In a terminal, the terminal gets the key first: `Ctrl+K`, `Ctrl+J` and `Ctrl+W` go to the shell, as they would in any terminal. The emergency stop works from anywhere outside a terminal, including text fields. +Shortcuts with `⌘` or `Ctrl`, such as the command palette, also work in text fields and code editors. In a terminal, the terminal gets the key first: `Ctrl+K` and `Ctrl+J` go to the shell, as they would in any terminal. In a Chrome tab, `Ctrl+W` never reaches the terminal: Chrome keeps it and closes the browser tab. The emergency stop works from anywhere outside a terminal, including text fields. The four Files keys (show or hide Files, show or hide Changes, search file contents and Go to file) work only in the Command Deck, where the work dock is. There they work from anywhere, including text fields and the code editor, where they win over the editor's own keys: on macOS `⌘⇧G` opens Changes instead of Monaco's Find Previous. On other pages, `Ctrl+P` keeps the browser's print dialog. In a conversation, `Ctrl+F` (`⌘F`) without Shift opens the conversation's find bar. diff --git a/features/merge-batches.mdx b/features/merge-batches.mdx index 7b831f1d03c..7ba0d5ab1bc 100644 --- a/features/merge-batches.mdx +++ b/features/merge-batches.mdx @@ -1,27 +1,27 @@ --- -title: UAT Batch Trains -description: Always one tested batch of every ready feature, ready to merge in one click +title: "Merge train: batch CI and UAT batches for ready pull requests" +sidebarTitle: "UAT Batch Trains" +description: "How the merge train batches ready PRs: batch CI, UAT batches you test and merge, the Auto and Hold policy, and the merge train card." --- # UAT Batch Trains When agents land merge-ready features faster than you can review and merge them one at a time, the bottleneck becomes the last-mile UAT. **UAT batch trains** fix -that: Overdeck keeps **one assembled, testable batch of every ready feature** -available at all times, so you can exercise the combined result and then land -exactly what you tested — in a single click. +that: Overdeck assembles ready features into **one testable batch**, so you can +exercise the combined result and then land exactly what you tested in one +merge. <Note> Batches run only while the **Merge train** switch on the [Flywheel](/features/flywheel) page header -(`merge_train_enabled`) is on. With it on, normal-priority PRs in a project that +(`merge_train_enabled`, off by default) is on. With it on, normal-priority PRs in a GitHub single-repo project that does not hold for UAT merge together automatically once the batch's own CI run is green: when `batch_size` PRs are ready (default 3) or the oldest has waited `batch_wait_minutes` (default 30; both in **Settings → Merge Train**). High-priority PRs (strikes, `critical`, `blocks-main`, `P0`, `urgent`, or `substrate-improvement` plus `bug`) merge on their own. A PR only you may merge (held for UAT, an auto-merge you cancelled, or a Deft human-merge policy) waits -in its own batch for you. With the switch off, every ready PR merges on its own -and nothing batches. +in its own batch for you. With the switch off, nothing batches: every ready PR that is not held for UAT merges on its own five minutes after it is ready, and a held one waits for you to merge it from the issue page. GitLab and polyrepo projects never merge automatically: their batches wait for you to merge them, and with the switch off you merge each PR yourself. Automatic batches need batch CI: a GitHub Actions workflow named `CI` that runs on pushes to `uat/**` branches. Without it, a batch waits at most 10 minutes for @@ -33,13 +33,13 @@ See [CI integrations](/integrations/ci#merge-train-batches-need-a-ci-workflow) f ## What you see The merge train shows as one card per project: on the Flywheel page rail (all -projects, with filter chips) and on each project's Home (that project only). +projects, with filter chips), on the Awaiting Merge page (all projects, under a global **Merge train** switch), and on each project's Home (that project only). Each card has: - **A mode chip and a Train switch.** **Auto-merge** projects merge ready work on their own; **Holds for UAT** projects wait for you to test and merge a batch. The switch turns the train off for that project. When the train is - off, a banner says no batches assemble and each ready PR merges on its own + off, a banner says no batches assemble. In a Holds for UAT project held features then wait until the train is on again; in an Auto-merge project each ready PR merges on its own after the cooldown. - **The current batch**, when there is one. It names its members and any held-out features with the reason, offers **Open UAT** (a live stack serving @@ -76,29 +76,34 @@ Each card has: ## How it works -1. **Assemble.** A 60-second reconciler builds a generation — a throwaway - `uat/<label>-<codename>-<MMDD>` branch off `main` — merging each ready feature +1. **Assemble.** A 60-second reconciler builds a generation (a throwaway + `uat/<label>-<codename>-<MMDD>` branch off `main`), merging each ready feature in order. When two features conflict, a timeboxed assembly agent resolves the conflict *inside the batch*; if it can't, that feature is held out (never the whole batch). 2. **Accumulate.** New ready features trigger a new, larger generation in the - background. Generations accumulate — you can test and promote an earlier, - smaller batch if the newest isn't what you want. -3. **Test.** Click **Open UAT frontend** to exercise the combined branch on a + background. Generations accumulate, so you can test and promote an earlier, + smaller batch if the newest isn't what you want. With the batch window on, + a live batch keeps its members, and new ready features wait for the next + batch. +3. **Test.** Click **Open UAT** (**Start & open** when its stack is not running) to exercise the combined branch on a real running stack. The checklist pulls each feature's acceptance criteria, plus an explicit "verify the touchpoint" item wherever a conflict was resolved. -4. **Promote.** **Merge batch (N) to main** lands exactly the tree you tested — - conflict resolutions included — in one merge. Each feature then closes out +4. **Promote.** **Merge batch (N) to main** lands exactly the tree you tested, + conflict resolutions included, in one merge. Each feature then closes out through the normal post-merge flow. -Unless the ready feature is held for UAT, a batch assembles only when **two or -more** features are ready. With exactly one, the page reads "1 feature ready — -merges directly; batches assemble when 2+ are ready": a one-member batch is the -PR branch itself and its CI run a duplicate, so that feature merges on its own -(Merge button or `gh pr merge`). A feature held for UAT (its issue's -`hold-for-uat` label, else the project's `auto_merge_default: hold`, else the -global require-UAT setting when the project sets no default) keeps a batch when -it is the only one ready, because that batch is the stack you test on. +Outside the batch window, a batch assembles only when **two or more** features +are ready, unless the one ready feature is held for UAT. With exactly one +unheld feature ready, it merges on its own (Merge button or `gh pr merge`): a +one-member batch is the PR branch itself and its CI run a duplicate. A feature +held for UAT (its issue's `hold-for-uat` label, else the project's +`auto_merge_default: hold`, else the global **Require UAT** switch on the +Flywheel page header, which is on by default) keeps a batch when it is the +only one ready, because that batch is the stack you test on. The batch window +applies in a GitHub single-repo project that does not hold for UAT: there a +batch, even of one PR, assembles once its oldest PR has waited +`batch_wait_minutes`. **Each ready feature has one merge path.** Overdeck decides it with one rule, first match wins: @@ -107,7 +112,7 @@ first match wins: default, else the global setting) waits for a batch you test and merge. A hold always wins, even over priority. In a project that holds for UAT, that is every feature, so nothing reaches `main` until you merge a batch. -2. With the merge train off, every other feature merges on its own, five +2. With the merge train off, every other feature merges on its own (GitHub single-repo projects only), five minutes after it is ready. 3. A high-priority PR (a strike, or `critical`, `blocks-main`, `P0`, `urgent`, or `substrate-improvement` plus `bug`) merges on its own. @@ -136,9 +141,11 @@ count toward that limit, so the train recovers once the cause is fixed. ## Projects that span several repos -A polyrepo project — one where a single issue's work lands across several member -repositories — gets batch trains too, on the same terms as a single-repo -project. There is no separate setting: the merge-train flag is the only gate. +A polyrepo project, one where a single issue's work lands across several member +repositories, gets batch trains too. There is no separate setting: the +merge-train flag is the only gate. Polyrepo batches never merge on their own: +there is no batch window, no automatic batch merge and no per-PR auto-merge, so +each batch waits for you to test and merge it. A feature is ready there when **every** pull or merge request it has open across the member repos is approved, has green checks and can merge. Each @@ -153,7 +160,7 @@ actually touches**. Repos no feature touches are left alone entirely. The batch still behaves as one unit: - **A feature that conflicts anywhere is held out everywhere.** You never test a - feature that landed in the API repo but not the frontend one — if it can't be + feature that landed in the API repo but not the frontend one: if it can't be merged cleanly in every repo it contributes to, it waits for the next batch. - **Merging is all-or-nothing.** Overdeck first merges every repo locally, without publishing anything. Only once all of them succeed does it push. If @@ -164,20 +171,20 @@ still behaves as one unit: pending, and never rewrites a repo's `main` to undo one. Clicking merge again skips what already landed and finishes the rest. -The live UAT stack works the same way as for a single-repo project — one stack +The live UAT stack works the same way as for a single-repo project: one stack per batch, serving all of its repos together. ## Live UAT stacks Each generation can serve a live dashboard at -`uat-<codename>.overdeck.localhost`, spun on demand from the batch's worktree. +`uat-<label>-<codename>-<mmdd>.overdeck.localhost`, spun on demand from the batch's worktree. Overdeck runs **at most two UAT stacks at once** (Docker's network pool is limited) and tears down the oldest when you start a third; promoting or invalidating a batch always tears its stack down. ## Honest controls -Every action names its exact effect and confirms before anything happens — +Every action names its exact effect and confirms before anything happens. "Merge batch (3) to main" lists the three issues and states that it lands the tree you tested. **Merge alone…** on a batch member merges that one feature now, which voids the batch; the confirmation names the batch, and its other diff --git a/features/mission-control.mdx b/features/mission-control.mdx index 3fe8a77ff03..2eab3a6d950 100644 --- a/features/mission-control.mdx +++ b/features/mission-control.mdx @@ -12,7 +12,7 @@ Command Deck is where you work with a project's agents: the project's conversati The top bar spans the full window width. It starts with the Overdeck brand, which opens Home. Below it, Command Deck uses a two-panel layout: - **Left column**: the project switcher, navigation, and the selected project's conversations, issues and workspaces -- **Main panel (right)**: Feature activity view, planning artifacts, and status reviews +- **Main panel (right)**: the Stage, with the project's Home pane, conversations, issues and code files in tabs ## Left column @@ -55,22 +55,13 @@ The **All projects** deck lists the conversations of every project in one place **Layout presets.** At the right end of the tab strip, **Layout** has four buttons: **One**, **Two side by side**, **Three columns** and **Grid of four**. They arrange the open conversations into equal panes, starting with the ones on screen. Each split pane's header has a ⤢ button, **Make this the only pane**, which shows just that conversation and keeps the others as tabs (this button is in every deck). -**New conversation** in this deck starts the conversation in the last project you had open and opens it beside the focused pane; the button's second line names that project first. With nothing open, the deck reads "Pick conversations on the left. Ctrl+Click opens one beside another." +**New conversation** in this deck starts the conversation in the last project you had open and opens it beside the focused pane; the button's second line names that project first. With nothing open, the deck reads "Pick conversations on the left. Ctrl+Click opens one beside another." (Cmd+Click on macOS) The deck, its open conversations and its layout survive a reload, including a reload on a conversation's own `/conv/<id>` address. ## Project Tree -The Issues section lists the selected project's active features. Each one shows: - -| Element | Description | -|---------|-------------| -| Status indicator | Spinner if agent is running, circle if idle | -| Issue ID | PAN-123, MIN-456, etc. | -| State label | Idle, Planning, In Progress, In Review, Done, Has Context, Suspended | -| Pull request | The issue's PR number, colored by state and review; × marks failing checks; click to open | - -State labels are computed from multiple signals: tmux session presence, heartbeat freshness (10-minute threshold), review/test status from the central `review-status.json`, and agent state files. +The Issues section lists the selected project's issues in the pipeline. A collapsed row shows the issue ID, its title and its spend, then a meta line: the stage word (`Not started`, `Planning`, `Building`, `Ready`, `In review` or `Ready to merge`, or `Needs you` when it waits on you), the model of the newest active agent, and task progress such as `3 of 7 items`. Expand the row for its badges, pull request and sessions. ## Project home @@ -91,7 +82,7 @@ Per-project release resolution lives in `projects.yaml` under `publish` (`npm_pa **Facts.** Five numbers, each a link: -- **Agents working** counts every agent and conversation working in this project right now, by role (planning, building, reviewing, testing, conversations). It is the same number the project switcher shows. Click it for the Agents page. +- **Agents working** counts every agent and conversation working in this project right now, by role (planning, building, reviewing, testing, conversations). It is the same number the project switcher shows. Click it for the Agents page, which is experimental: with Experimental features off, the click lands on Home. - **Needs you** counts the items waiting on you in this project and shows the first one's question. - **In review** counts the issues in the In review lane and names their pull requests. - **Landed this week** counts first-parent commits on the default branch in the last 7 days (`500+` at the cap) and how many came through pull requests. Click it for the Changes dock. @@ -111,30 +102,10 @@ Backlog, queued and merged issues are not listed; **Open the board** shows them. **Recent changes on main.** Who changed what: today's commits on the default branch when there are at least ten, else the last ten. Each row names the conversation or agent behind the commit, read from its `Overdeck-Conversation` / `Overdeck-Agent` trailers. Click a conversation row to open that conversation, or an agent row to open its issue; commits with no trailer show as `unattributed`. Click a short SHA to copy the full one. The list refreshes every minute. -## Activity View - -When you click a feature, the main panel shows all agent sessions unified into one scrollable view. Each session appears as a collapsible section with: - -<ThemedImage - light="/images/dashboard/activity-light.png" - dark="/images/dashboard/activity-dark.png" - alt="Activity view: a real-time log of agent command output streaming as agents work" -/> - -- **Type badge**: PLANNING (blue), WORK (green), REVIEW (amber), TEST (indigo), MERGE (pink) -- **Model**: Which Claude/LLM model the agent used (e.g., Opus 4.6, Sonnet 4.5) -- **Duration**: How long the session ran -- **Status dot**: Green pulse (running), gray (completed), red (failed) -- **Transcript**: Full agent output with tail-anchored auto-scroll for running sessions - -### Section Isolation Mode - -Click a section header to view it full-screen. Press `Esc` or use the browser back button to return. The isolated view includes model display and a prominent keyboard hint. - ## Decisions Agents stop and wait for you: a question, a plan to approve, a permission -request, a rate-limit dialog, or simply a finished turn. **Decisions** is the one +request, a rate-limit dialog, or simply a finished turn. **Decisions**, the **Needs you** scope of the Activity page (`/activity`), is the one place that lists all of them, whether they come from a pipeline agent, a conversation, or the flywheel. @@ -143,7 +114,7 @@ carries a pulsing amber indicator; click it to bring the dialog back, including one you dismissed with `Esc`, and the whole issue row is shaded so you can spot it without opening the tree. -The list separates **Blocking work** from **Waiting**. Blocking means the agent +The list puts **System** items (Overdeck's own machine needs attention) first, then separates **Blocking work** from **Waiting**. Blocking means the agent has stopped until you answer, so it is burning wall-clock and nothing else will move; waiting means work continues around your decision. Within each group the oldest is first, since that is the one costing the most. Each row shows the @@ -182,63 +153,18 @@ The **Activity** page (`/activity`) opens on the **Feed** tab. It has three scop Within a scope, **All**, **Chats** and **Activity** narrow the feed. The page remembers the tab you last picked. The log streams (Activity Log, Detailed and TTS) appear as more tabs only when experimental features are on. -## Badge Bar - -Quick-access badges appear below the feature header: - -| Badge | What it shows | -|-------|---------------| -| Tasks | Opens beads task panel for the feature | -| STATE | Renders STATE.md from the workspace's `.planning/` directory | -| PRD | Renders PRD.md (grayed out if not generated) | -| Status | AI-generated progress review comparing code against PRD | -| Discussions | Synced issue tracker discussions | -| Transcripts | Uploaded meeting transcripts | -| Upload | Attach transcripts or notes to the feature | -| Sync | Pull latest discussions from GitHub/Linear | - -## Status Reviews +## Issue documents -Click the **Status** badge to generate an AI-powered progress review. The review: - -1. Gathers context: PRD, STATE.md, git diff, commit log, file changes, review/test status -2. Sends everything to the configured LLM (set via **Settings > Workflow Agents > Planning**) -3. Returns a structured analysis: summary, PRD coverage table, risk assessment, and recommendations - -If no API key is configured, a static template with raw data is shown as fallback. - -Any configured provider (Anthropic, OpenAI, Google, Kimi, Z.AI) can be used for status reviews. - -## Planning Artifacts - -Each feature workspace has a `.planning/` directory: - -``` -feature-pan-XXX/.planning/ -├── PRD.md # Product requirements (generated or manual) -├── STATE.md # Current progress notes -├── STATUS_REVIEW.md # Latest AI-generated status review -├── transcripts/ # Uploaded meeting transcripts -├── discussions/ # Synced tracker discussions -└── notes/ # Ad-hoc notes and documents -``` - -### Uploading Artifacts - -Use the **Upload** badge to attach markdown or text files. Files are categorized as transcripts or notes and stored in the appropriate subdirectory. - -### Syncing Discussions - -Click **Sync** to pull the latest comments from GitHub Issues or Linear. Discussions are converted to markdown and stored in `.planning/discussions/`. +An issue's plan and PRD, tasks, tracker discussion, changes and activity are tabs of the issue drawer and the full issue view. See [Issue drawer and full issue view](/features/dashboard-views#issue-drawer-and-full-issue-view). ## Pipeline View -Where the project tree organizes work by project and feature, the **Pipeline** page reorganizes the same issues by lifecycle phase. A metric strip (Active issues, Work running, Review queue, Ship, and Spend) sits above phase-grouped rows (Ship, Review, Verifying), with a live activity feed on the right. +Where the project tree organizes work by project and feature, the **Pipeline** page reorganizes the same issues by lifecycle phase. A metric strip (Active issues, Work running, Review running, Ship and Spend) sits above phase and project filters and the issue rows, grouped by phase: Ship, Review, Work, Plan and Ready. <ThemedImage light="/images/dashboard/pipeline-light.png" dark="/images/dashboard/pipeline-dark.png" - alt="Pipeline page: a metric strip over phase-grouped issue rows with a live activity feed" + alt="Pipeline page: five metric tiles over phase and project filters, with issue rows grouped under Ship, Review and Work" /> <Tip> @@ -249,15 +175,11 @@ Where the project tree organizes work by project and feature, the **Pipeline** p ### Adding Projects -Projects are configured in `~/.overdeck/config.yaml`. Any project with active workspaces appears in the project switcher. - -### Model Selection - -The model used for status reviews is configured in **Settings > Workflow Agents > Planning**. See [Configuration](/configuration/projects) for details. +Projects are registered in `~/.overdeck/projects.yaml`. Add one with **Add a project** in the project switcher or `pan project add <path>`; every registered project appears in the switcher. See [Projects](/configuration/projects). ## Related Features -- [Specialists](/features/specialists) - Review, test, and merge agents +- [Specialists](/features/specialists) - Review and test agents - [Cloister](/features/cloister) - AI lifecycle management - [Workspaces](/features/workspaces) - Feature workspace management - [Dashboard views](/features/dashboard-views) - Every view and how to reach it diff --git a/features/open-in-overdeck.mdx b/features/open-in-overdeck.mdx index 0abf1d8bff5..3eb188898c8 100644 --- a/features/open-in-overdeck.mdx +++ b/features/open-in-overdeck.mdx @@ -38,7 +38,7 @@ Before PAN-5349, `pan open <issue>` opened the issue's workspace in an editor. T When several dashboard tabs are open, the tab you focused last opens the path, and its window comes to the front. If that tab is gone (it crashed or its record is older than a day), any visible tab opens it after a short wait. When no dashboard tab is open, `pan open` opens the link below in your browser instead. -When a dashboard tab opens the path, `pan open` prints `Opened <path> in <project>`, naming the project as the project switcher shows it, or `Opened the <issue> workspace in <project>` for an issue workspace. The dashboard shows the same message. +When a dashboard tab opens the path, `pan open` prints `Opened <path> in <project>`, naming the project as the project switcher shows it, or `Opened the <issue> workspace in <project>` for an issue workspace, or `Opened root folder in <project>` for a root folder. The path it names is relative to the project or workspace folder. The dashboard shows the same message. ### The `/open` link @@ -58,7 +58,7 @@ pan integrate file-manager --dry-run # print what would be written, change not pan integrate file-manager --remove # remove exactly what was added ``` -Every entry runs the absolute path of `pan` (the shim `pan sync` writes in `~/.overdeck/cli-bin`, or the first `pan` on PATH), so it works without a login shell. If no `pan` is found, the command stops and tells you to run `pan sync` first. All entries are per user; nothing needs root or an administrator. +Every entry runs the absolute path of `pan` (on Linux and macOS the shim `pan sync` writes in `~/.overdeck/cli-bin`, or the first `pan` on PATH; on Windows the first `pan.cmd` or `pan.exe` on PATH), so it works without a login shell. If no `pan` is found, the command stops and tells you to run `pan sync` first. All entries are per user; nothing needs root or an administrator. `pan install` offers the same entries after the Ollama step: on a terminal it asks `Add "Open in Overdeck" to your file manager's right-click menu?` (default No). `pan install --file-manager-integration` adds them without asking, and `--skip-file-manager-integration` neither asks nor adds them. A failed install of the entries is a warning; it never fails `pan install`. diff --git a/features/planning.mdx b/features/planning.mdx index 5aaa19cba0b..41f52779dea 100644 --- a/features/planning.mdx +++ b/features/planning.mdx @@ -28,7 +28,7 @@ The start screen (`Start Planning Session`) explains that the issue moves to In - `Stay and watch planning`: keeps the dialog open and shows the agent's terminal. Default on. - `Start Docker containers`: the workspace is created with Docker started. Default off, and it applies only when planning creates the workspace. - `Model`: defaults to the `roles.plan.model` setting. -- `Effort`: `Low`, `Medium`, `High`, `Xhigh`, `Max`. Default `High`. `Xhigh` and `Max` add the probe pass. +- `Effort`: `Low`, `Medium`, `High`, `Xhigh`, `Max`. Default `High`. `High` and above add the probe pass, so the default effort runs it. There is no harness picker: the harness comes from `roles.plan.harness`, or Claude Code if that is unset. There is no probe checkbox either; use `pan plan --probe`, or an effort of `High` or above. @@ -80,11 +80,11 @@ The PRD is a markdown brief at `.pan/drafts/<issue>.md`. A human can write it, o ## The xBRIEF plan -The plan is an [xBRIEF](https://github.com/deftai/xBRIEF) document (current version 0.8; the old name was vBRIEF). A spec has exactly two top level keys, `xBRIEFInfo` and `plan`. `plan.items[]` is the checklist. Each item has an `id`, `title`, `status`, an optional `narrative.Action`, `metadata`, and nested acceptance criteria. +The plan is an [xBRIEF](https://github.com/deftai/xBRIEF) document (current version 0.8; the old name was vBRIEF). The planner writes exactly two top level keys, `xBRIEFInfo` and `plan`; the canonical spec in `.pan/specs/` also carries a root `status` field, the lifecycle status described under [Where the plan lives](#where-the-plan-lives). `plan.items[]` is the checklist. Each item has an `id`, `title`, `status`, a `narrative.Action` (finalize's quality lint requires at least 8 words), `metadata`, and nested acceptance criteria. ### Items and acceptance criteria -An item's acceptance criteria are child items with `metadata.kind: "acceptance_criterion"` and ids like `<item>.ac1`. The verification gate requires every acceptance criterion to be `completed` before review. A small example, two items and one dependency between them: +An item's acceptance criteria are child items with `metadata.kind: "acceptance_criterion"` and ids like `<item>.ac1`. The verification gate requires every acceptance criterion to be `completed` before review. A small example of the shape, two items and one dependency between them. It is not a finalize-ready plan: the quality lint (exit code `3`) also requires, per item, `metadata.files_scope`, `files_scope_confidence`, `readiness` and `requiresInspection`, a `narrative.Action` of at least 8 words, and 2 to 5 acceptance criteria (or `metadata.acJustification`) whose titles name observable behavior: ```json { @@ -174,8 +174,8 @@ draft -> proposed -> active -> completed | (new) to draft | `pan plan` starts; the PRD is written to `.pan/drafts/` | | draft to proposed | Planning completes; the xBRIEF is created in `.pan/specs/` | | proposed to active | `pan start` runs | -| active to completed | The PR merges | -| active to cancelled | The issue is closed | +| active to completed | Nothing automatic: close-out leaves the field alone and the merged PR is the evidence; `pan scope complete` sets it by hand | +| active to cancelled | Only `pan scope cancel` (the dashboard's `Cancel issue` action deletes the workspace first, so it skips the spec) | ## Finalize the plan diff --git a/features/safe-shutdown.mdx b/features/safe-shutdown.mdx index 86a43fd3668..5679d1789a1 100644 --- a/features/safe-shutdown.mdx +++ b/features/safe-shutdown.mdx @@ -1,5 +1,6 @@ --- -title: Safe shutdown +title: "Safe shutdown: drain agents with pan shutdown before a reboot" +sidebarTitle: "Safe shutdown" description: Drain every agent at a tool boundary before a reboot --- @@ -7,13 +8,14 @@ description: Drain every agent at a tool boundary before a reboot `pan shutdown` stops Overdeck without cutting any agent off in the middle of a tool call. Each session finishes the call it is running, ends its turn, and is stopped. Then Overdeck waits for its own server work, checks that nothing is still writing, stops its services, and tells you it is safe to reboot. -A plain reboot gives every session 5 seconds to exit and then kills it, wherever it is. `pan down` stops the dashboard and its services but leaves every agent running. Use `pan shutdown` when you want to reboot the machine or stop everything cleanly. +A plain reboot stops every session wherever it is: systemd sends each process SIGTERM, then SIGKILL once its stop timeout passes. `pan down` stops the dashboard, its services and any review sessions, but leaves work agents and conversations running. Use `pan shutdown` when you want to reboot the machine or stop everything cleanly. ```bash pan shutdown # drain, stop everything, report "Safe to reboot." pan shutdown --reboot # the same, then reboot the machine (Linux) pan shutdown --status # print the running drain pan shutdown --cancel # cancel a running drain +pan shutdown --no-wait # start the drain and return without following it ``` ## What happens, phase by phase @@ -53,7 +55,7 @@ The dashboard asks for confirmation first. The dialog lists what will stop, show If an agent or conversation runs `pan shutdown` itself, the command starts the drain and returns at once, so its own tool call can end. -`pan shutdown` needs the dashboard. If the dashboard is not running, start it with `pan up` first. +`pan shutdown` needs the dashboard. If the dashboard is not running, start it with `pan up` first. It also refuses to start while a `pan reload` or `pan restart` is in progress. ## After the restart diff --git a/features/skill-packs.mdx b/features/skill-packs.mdx index cc34f6df6b8..6e542cf429a 100644 --- a/features/skill-packs.mdx +++ b/features/skill-packs.mdx @@ -1,5 +1,6 @@ --- -title: Skill Packs +title: "Skill packs: third-party skill repositories pinned per project, issue or conversation" +sidebarTitle: "Skill Packs" description: Pin third-party skill repositories to a commit and turn them on per project, issue or conversation --- @@ -24,7 +25,7 @@ pan skills set --pack mattpocock inherit --project myapp # turn it off again pan skills pack remove mattpocock # unregister and delete the cache ``` -Changes apply at the next launch; a running agent keeps the skills it launched with. See [When pack changes apply](#when-pack-changes-apply). +Changes apply at the next launch; a running agent keeps the skills it launched with, but a running conversation can load new ones with `pan skills add` (see [Adding skills to a running conversation](#adding-skills-to-a-running-conversation)). See [When pack changes apply](#when-pack-changes-apply). ## Pack catalog @@ -65,11 +66,11 @@ A conversation value for a pack skill wins first. Whole-pack toggles have no con | Global | Project | Issue | Result | |--------|---------|-------|--------| -| pack on | `mattpocock/tdd` off | — | `tdd` off (project) | -| pack on | — | pack off | every skill off (issue pack) | -| — | `mattpocock/grilling` on | pack off | `grilling` off (the issue level decides first) | -| `mattpocock/grilling` on | — | — | only `grilling` on | -| pack on | — | — | `setup-matt-pocock-skills` off (opt-in) | +| pack on | `mattpocock/tdd` off | unset | `tdd` off (project) | +| pack on | unset | pack off | every skill off (issue pack) | +| unset | `mattpocock/grilling` on | pack off | `grilling` off (the issue level decides first) | +| `mattpocock/grilling` on | unset | unset | only `grilling` on | +| pack on | unset | unset | `setup-matt-pocock-skills` off (opt-in) | **Opt-in skills** are skills that change files Overdeck owns, such as `setup-matt-pocock-skills`, which edits `CLAUDE.md`/`AGENTS.md` and writes tracker docs. The pack toggle never turns them on; only a value for that skill does. @@ -77,7 +78,7 @@ A conversation value for a pack skill wins first. Whole-pack toggles have no con A conversation can carry its own pack values, the narrowest level of all. You can set them when you create the conversation, and you can add more while it runs. -When you create one in the dashboard, open **New conversation with options…**; its **Skills** section shows a summary (`{on} of {total} skills on`) with a **Customize** button. Customizing lists pack skills grouped by pack, each with **Inherit / On / Off** — there is no whole-pack toggle at this level, only per-skill values. +When you create one in the dashboard, open **New conversation with options…**; its **Skills** section shows a summary (`{on} of {total} skills on`) with a **Customize** button. Customizing lists pack skills grouped by pack, each with **Inherit / On / Off**. There is no whole-pack toggle at this level, only per-skill values. From the CLI, `pan handoff` has the same reach: @@ -180,7 +181,7 @@ video remotion, hyperframes, openmontage, video-use (built-in) ### Adding packs from the dashboard -The Skills page (`/skills`) lists **Available packs** under Skill packs: each pack group with members you have not added (for example `video · 4 packs not added`), then each known pack you have not added, with its source and disclosure. +The Skills page (`/skills`) lists **Available packs** under Skill packs: each pack group with members you have not added (for example `video` with `group · 4 packs not added`), then each known pack you have not added, with its source and disclosure. The dashboard adds a known pack only when it has a default ref and adding it builds nothing. Those packs, `remotion`, `hyperframes`, `openmontage`, `video-use`, `pstack` and `atlassian`, show an **Add…** button, and so does a group whose missing members are all among them. The other known packs show their CLI command instead: `mattpocock`, `deft` and `gstack` need a ref you choose, and adding `sageox` or `gstack` builds code on this machine. A config group member that is not a known pack makes its group CLI-only. @@ -228,7 +229,7 @@ pan skills pack update mattpocock # re-resolve the ref pan skills pack update mattpocock --ref v1.3.0 ``` -`update` prints the preview again with the skills added, removed, and changed since the trusted commit, plus any capabilities that are new. It moves the trusted commit only after you confirm. `pan skills pack list` shows `update available` only for a pack pinned to a tag or branch; a ref that is a 40-character commit never shows it (`packUpdateAvailable` in `src/lib/skill-packs/sources.ts`). `pstack` and `sageox` default to commit refs, so to move them, run `pan skills pack update <id> --ref <new commit or branch>`. `--offline` skips that network check. +`update` prints the preview again with the skills added, removed, and changed since the trusted commit, plus any capabilities that are new. It moves the trusted commit only after you confirm. `pan skills pack list` shows `update available` only for a pack pinned to a tag or branch; a ref that is a 40-character commit never shows it (`packUpdateAvailable` in `src/lib/skill-packs/sources.ts`). `pstack`, `sageox`, `atlassian` and the four video packs default to commit refs, so to move them, run `pan skills pack update <id> --ref <new commit or branch>`. `--offline` skips that network check. ### Fork-first policy @@ -277,7 +278,7 @@ pan skills set --group video on --project <key> # turn all four on for one pro ### Matt Pocock's skills from a fork -Overdeck's default source for the `mattpocock` pack is the operator-controlled fork `eltmon/skills`, pinned to the `v1.2.3` commit. A fork lets the operator decide when upstream changes arrive: sync the fork on GitHub, then run `pan skills pack update mattpocock --ref <tag>` to preview and re-pin. Any url works here; `KNOWN_PACKS` applies the `mattpocock` defaults by pack id, not by url. +Overdeck's default url for the `mattpocock` pack is the operator-controlled fork `eltmon/skills`. The pack has no default ref, so `pan skills pack add mattpocock` needs `--ref` (these docs use `--ref v1.2.3`, commit `6acc160`). A fork lets the operator decide when upstream changes arrive: sync the fork on GitHub, then run `pan skills pack update mattpocock --ref <tag>` to preview and re-pin. Any url works here; `KNOWN_PACKS` applies the `mattpocock` defaults by pack id, not by url. `setup-matt-pocock-skills` is opt-in: turning the pack on never turns it on. Only `pan skills set mattpocock/setup-matt-pocock-skills on [--project <key>|--issue <id>]` does. @@ -294,7 +295,7 @@ pan skills set --pack mattpocock inherit --issue <id> # issue: undo ### pstack -`pstack` is poteto's (Lauren Tan's) skill pack for Cursor — `principle-*`, `unslop`, `tdd`, `architect`, `poteto-mode`, and more — mounted from the operator's fork `https://github.com/eltmon/plugins`, pinned to `ae5650f`. Overdeck mounts Cursor's generated Claude Code build at `harness/pstack/claude-code`, not the Cursor source tree; the `KNOWN_PACKS.pstack` entry carries that subfolder as its `pluginRoot`, so the manifest, skill scan, and capability probes all read from inside it. Re-pin with `pan skills pack update pstack --ref <commit-or-branch>`. +`pstack` is poteto's (Lauren Tan's) skill pack for Cursor (`principle-*`, `unslop`, `tdd`, `architect`, `poteto-mode`, and more), mounted from the operator's fork `https://github.com/eltmon/plugins`, pinned to `ae5650f`. Overdeck mounts Cursor's generated Claude Code build at `harness/pstack/claude-code`, not the Cursor source tree; the `KNOWN_PACKS.pstack` entry carries that subfolder as its `pluginRoot`, so the manifest, skill scan, and capability probes all read from inside it. Re-pin with `pan skills pack update pstack --ref <commit-or-branch>`. ```bash pan skills pack add pstack @@ -324,14 +325,14 @@ pan skills set --pack pstack inherit --issue <id> # issue: undo Most pstack skills set `disable-model-invocation: true`, so the agent picks them up only when you invoke them directly, e.g. `/pstack:principle-laziness-protocol`. -Seven skills are opt-in — turning the pack on never turns them on: +Seven skills are opt-in; turning the pack on never turns them on: -- `setup-pstack` — writes `~/.claude/rules/pstack-models.md`, which every Claude Code session on the host loads, including sessions outside Overdeck. -- `automate-me` — writes a personal mode skill, then commits and opens a PR. -- `reflect` — copies a skill folder into a skills dir and edits it. -- `create-verification-skill`, `create-formal-verification-skill` — write a project-local skill under `.cursor/skills/` → `.claude/skills/`, an Overdeck sync target in workspaces. -- `maintain-verification-skill` — opens at most one PR of proven corrections. -- `make-bot-ui` — builds a webhook UI for a Grok bot and exposes it on Tailscale. +- `setup-pstack`: writes `~/.claude/rules/pstack-models.md`, which every Claude Code session on the host loads, including sessions outside Overdeck. +- `automate-me`: writes a personal mode skill, then commits and opens a PR. +- `reflect`: copies a skill folder into a skills dir and edits it. +- `create-verification-skill`, `create-formal-verification-skill`: write a project-local skill under `.cursor/skills/` → `.claude/skills/`, an Overdeck sync target in workspaces. +- `maintain-verification-skill`: opens at most one PR of proven corrections. +- `make-bot-ui`: builds a webhook UI for a Grok bot and exposes it on Tailscale. The mount also copies the plugin's `docs/` and `README.md` next to `skills/` (`KnownPack.mountExtras`), so the skills' link to the Claude Code adapter doc (`docs/harness/claude-code.md`) resolves instead of dangling. @@ -385,7 +386,7 @@ Each gstack skill is in one of five classes, fixed in Overdeck's skill map (revi | opt-in | autoplan, benchmark-models, captain, careful, codex, cso, document-generate, document-release, eval-plan, freeze, guard, modernize, ubicloud, unfreeze | Only with a per-skill `on`: they send code to OpenAI (`codex`), call paid or cloud APIs, push, or install hooks that block tool calls | | browser | benchmark, browse, devex-review, make-pdf, qa, qa-only, scrape, skillify, spec | On with the pack toggle once the browser runtime is built | | browser-opt-in | canary, design-consultation, design-html, design-review, design-shotgun, land-and-deploy, office-hours, plan-design-review, ship | Only with the browser runtime and a per-skill `on`: they push, merge, deploy, or call paid image APIs | -| excluded | connect-chrome, gstack-upgrade, plan-tune, setup-deploy, setup-gbrain, sync-gbrain, open-gstack-browser, pair-agent, setup-browser-cookies | Never: they upgrade the install in place, need setup's hooks, or edit `CLAUDE.md`; `open-gstack-browser` opens a visible browser that writes `~/.gstack/.auth.json`, `pair-agent` exposes the browser through an ngrok tunnel and writes `~/.codex`, and `setup-browser-cookies` reads your real browser cookies and keychain | +| excluded | connect-chrome, gstack-upgrade, plan-tune, setup-deploy, setup-gbrain, sync-gbrain, open-gstack-browser, pair-agent, setup-browser-cookies | Never: `connect-chrome` is a symlink alias (symlinked skills are never mounted); the others upgrade the install in place, need setup's hooks, or edit `CLAUDE.md`; `open-gstack-browser` opens a visible browser that writes `~/.gstack/.auth.json`, `pair-agent` exposes the browser through an ngrok tunnel and writes `~/.codex`, and `setup-browser-cookies` reads your real browser cookies and keychain | ```bash pan skills set --pack gstack on # every default skill, globally @@ -448,7 +449,7 @@ The browser skills start a browse daemon per project. It keeps its port, token a pan skills pack remove gstack ``` -`remove` deletes `~/.overdeck/packs/gstack/` (renders, state, extractions and the git cache), every mount that contains gstack, the launch links that leaves dangling, and the gstack copy in every Codex agent's plugin cache. `remove` deletes the mounts a running agent is using, and the next launch has no gstack skills either: run `pan skills pack add gstack --ref main` again to get them back. `remove` does not delete the `.gstack/` or `.gstack-worktrees/` dirs that skills wrote in your projects; it prints each one it finds under a registered project, with the `rm -rf` command. `remove` and `pan skills pack browser gstack off` also print each live browse daemon in a registered project as `Browse daemon still running in <project>: pid <n> — stop with: kill -INT <n>` (a headless daemon ignores a plain `kill`); they never stop one. `pan skills pack gc` also removes renders of commits other than the trusted one once no linked launch uses them and they are older than `--max-age-days` (using a render resets its age), and the `render/`, `state/` and `browser/` dirs of packs that are no longer registered once all are older than `--max-age-days`. If `config.yaml` cannot be read or parsed, gc removes nothing and exits 1, because it cannot tell which packs are registered. If removing a mount or cache fails, `remove` names it and exits 1; run it again to retry. +`remove` deletes `~/.overdeck/packs/gstack/` (renders, state, extractions and the git cache), every mount that contains gstack, the launch links that leaves dangling, and the gstack copy in every Codex agent's plugin cache. `remove` deletes the mounts a running agent is using, and the next launch has no gstack skills either: run `pan skills pack add gstack --ref main` again to get them back. `remove` does not delete the `.gstack/` or `.gstack-worktrees/` dirs that skills wrote in your projects; it prints each one it finds under a registered project, with the `rm -rf` command. `remove` and `pan skills pack browser gstack off` also print each live browse daemon in a registered project, with its path, its pid and the `kill -INT <n>` command that stops it (a headless daemon ignores a plain `kill`); they never stop one. `pan skills pack gc` also removes renders of commits other than the trusted one once no linked launch uses them and they are older than `--max-age-days` (using a render resets its age), and the `render/`, `state/` and `browser/` dirs of packs that are no longer registered once all are older than `--max-age-days`. If `config.yaml` cannot be read or parsed, gc removes nothing and exits 1, because it cannot tell which packs are registered. If removing a mount or cache fails, `remove` names it and exits 1; run it again to retry. #### Limits @@ -539,7 +540,7 @@ Each Overdeck-managed Claude Code or Codex launch detects a Directive project at | Directive project | `deft` toggle | Managed mode | Result | |-------------------|---------------|--------------|--------| -| no | any | — | Nothing exported; Claude gets the CLI deny list when deft skills are mounted | +| no | any | any | Nothing exported; Claude gets the CLI deny list when deft skills are mounted | | yes | explicit off (issue or project) | any | Kill switch: `DEFT_DIRECTIVE_DISABLE=1`, the flag file in issue worktrees, and the deposit's `deft-directive-*` pointer skills hidden | | yes | on, or default | managed | `DEFT_ORCHESTRATOR=overdeck` | | yes | on, or default | not managed | Nothing exported; Deft runs as the project configured it | @@ -591,7 +592,7 @@ pan skills deft back <ISSUE> [--json] # save, remove the install exac **Switching.** `use` stops the issue's agents, writes `pipeline: deft` into `.pan/skill-overrides/<ISSUE>.yaml`, creates the workspace if it is missing, and installs Directive. When the issue has no plan, it writes a one-item stand-in plan, so `pan start` works. `--start` then starts the work agent. That agent gets a Deft kickoff instead of Overdeck's: build with `deft-directive-build`, run `deft-directive-pre-pr` before pushing, run `deft-directive-review-cycle` when a supported bot reviewer exists, save the state archive, use `pan sync-main` instead of a rebase, and never merge. `back` saves the archive, removes the install, restores every file the install changed, and deletes the stand-in plan. `pan start <ISSUE>` then plans the issue the Overdeck way. A project whose default branch already tracks a Directive deposit gets no install: its tracked deposit is used as it is. Overdeck decides this from the default branch's committed files, never from the worktree, because a temporary install leaves the same files on disk. -**What the install writes, and how it is hidden.** npm and pnpm projects run Deft's installer, `npx --yes @deftai/directive install --yes`. Deft's installer refuses Bun projects, so for a project with `bun.lock` or `bun.lockb` Overdeck adds `@deftai/directive-runtime` with `bun add -d --exact` and then runs the runtime's own `setup` step. The deposit (pointer skills, slash wrappers, hook registrations, `.githooks/`, `AGENTS.md`, `Taskfile.yml`, `xbrief/`, `.deft/`, the `package.json` pin, and the lockfile change) stays out of git: +**What the install writes, and how it is hidden.** npm and pnpm projects run Deft's installer: `directive install --yes` when `directive` is on `PATH`, else `npx --yes @deftai/directive install --yes`. Deft's installer refuses Bun projects, so for a project with `bun.lock` or `bun.lockb` Overdeck adds `@deftai/directive-runtime` with `bun add -d --exact` and then runs the runtime's own `setup` step. The deposit (pointer skills, slash wrappers, hook registrations, `.githooks/`, `AGENTS.md`, `Taskfile.yml`, `xbrief/`, `.deft/`, the `package.json` pin, and the lockfile change) stays out of git: - New paths go into a `# overdeck:deft begin` … `# overdeck:deft end` block in a per-worktree exclude file, `<git-dir>/info/overdeck-exclude`, which starts with a copy of your global excludes. SageOx keeps its own block in the same file. - Tracked files that the install changed, such as `package.json`, `.gitignore`, and the lockfile, get `--skip-worktree`. @@ -627,7 +628,7 @@ Without a readable snapshot, `back` cannot undo the install exactly. It then cle - **Decisions tab.** A Deft issue's view gains a Decisions tab, in the issue drawer and in the Stage issue tab: Deft's escalations, open first, with SLA, due time, `overdue` and `dangerous` marks and a **Resolve** control; Deft's decision records; and Deft's policy, read-only, with `requireHumanMerge` first. - **Needs-you.** An open escalation that needs an answer appears in Needs-you and in the question dialog, with its SLA and a `dangerous` chip. Answering it rewrites the escalation file and tells the work agent. An open `external` escalation does not block: it shows as **Deft: waiting on external**. When a Claude Code Deft agent ends its message with one of Deft's numbered menus, the question dialog offers the menu's labels verbatim and sends the exact label. Codex agents keep the menu in the terminal. - **Plan tab.** Plan › Tasks lists Deft's scopes by folder (In progress, Planned, Proposed, Done, Cancelled) with each item's evidence and disposition. A disposition Deft will not accept yet (no provenance, or an agent's) gets **Sign off**, which records a human sign-off in Deft's own terms. Plan › Map draws the scopes' swarm dependencies. -- **Overview tab.** **Deft gates** lists Deft's own gate runs from its run summary. **Deft review cycle** shows Deft's review cycle for the PR: the verdict in Deft's names (`CLEAN`, `NEW_P0_P1`, `PENDING`), the five exit-predicate fields as met, unmet, or unknown, rounds with P0/P1/P2 counts and the fix commit, the review lease, and the `pr:watch` heartbeats and CLEAN records. Deft records no rounds, so the panel rebuilds them from Greptile's comments and the `fix: address Greptile review findings` commits, and says so. Greptile is the only reviewer that can end Deft's cycle: without it the panel says `No supported bot reviewer — Deft review cycle not running`. +- **Overview tab.** **Deft gates** lists Deft's own gate runs from its run summary. **Deft review cycle** shows Deft's review cycle for the PR: the verdict in Deft's names (`CLEAN`, `NEW_P0_P1`, `PENDING`), the five exit-predicate fields as met, unmet, or unknown, rounds with P0/P1/P2 counts and the fix commit, the review lease, and the `pr:watch` heartbeats and CLEAN records. Deft records no rounds, so the panel rebuilds them from Greptile's comments and the `fix: address Greptile review findings` commits, and says so. Greptile is the only reviewer that can end Deft's cycle: without it the panel says that there is no supported bot reviewer, so the Deft review cycle is not running. - **Other surfaces.** The phase rail shows `Deft: <delivery state>`. The project-tree row shows `spec drift <n>` (Deft's ledger of scope work the spec does not cover) and `install drift <n>` (hidden install files edited since the install). Changes › Files checks the changed files against Deft's approved scopes. Activity shows Deft's finish-loop progress. The agents lane lists Deft's subagents from their heartbeats, and a quiet one gets a `quiet` mark. A board card shows a `Deft` chip and its scope counts. ### SageOx @@ -769,13 +770,13 @@ pan skills set --pack atlassian on --issue <id> **Skills.** Three are on with the pack toggle: `atlassian-mcp-code-search`, `jira-sprint-dashboard` (read-only unless you ask it to write), and `search-company-knowledge`. Four are opt-in, because they create or edit Jira or Confluence content, so the pack toggle never turns them on: `capture-tasks-from-meeting-notes`, `generate-status-report`, `spec-to-backlog`, and `triage-issue`. -**Auth.** When your Jira email and API token are set (Settings → Tracker Keys, or `JIRA_EMAIL`/`JIRA_API_TOKEN` in `~/.overdeck.env`), Overdeck sends them to the server as `Authorization: Basic base64(email:token)`. An org admin must have enabled API token auth for the Rovo MCP server, and the token needs MCP scopes. +**Auth.** When your Jira email and API token are set (Settings → Tracker Keys, or `JIRA_EMAIL`/`JIRA_API_TOKEN` in `~/.overdeck.env`), Overdeck sends them to the server as `Authorization: Basic base64(email:token)`. With a Data Center Jira base URL no header is sent; with a Jira Cloud base URL (`*.atlassian.net`), or no base URL at all, the header is sent. An org admin must have enabled API token auth for the Rovo MCP server, and the token needs MCP scopes. Without those keys, a Claude Code agent reuses your own sign-in: run `claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcp` and `/mcp` once, from your own Claude Code session, with the same server name and URL the launch file uses. Agents cannot complete that interactive sign-in themselves. Codex agents have no such session to reuse, so without the Jira email and API token a Codex launch gets no `atlassian` server at all. For OAuth with Jira credentials also set, or for a Bearer service-account key, declare a project `mcp_servers` entry named `atlassian` (see [MCP servers](/configuration/mcp)); a project server with that name overrides the pack's. -**Harnesses.** Claude Code and Codex agents get the server (Codex with `defaultToolsApprovalMode: "approve"`, and only when it has an Authorization header). `acp` and `opencode` get no server: the ACP host drops non-`stdio` entries. `ohmypi`, `kimi-code`, `muse` and `prime-agent` provision no MCP at all. +**Harnesses.** Claude Code and Codex agents get the server (Codex with `defaultToolsApprovalMode: "approve"`, and only when it has an Authorization header). `acp`, `opencode` and `grok` get no server: the ACP host drops non-`stdio` entries. `pi`, `ohmypi`, `kimi-code`, `muse` and `prime-agent` provision no MCP at all. **`pan doctor`** adds an **Atlassian MCP** row only once the pack is registered; there is no row at all before that. Registered but off everywhere, it reports `ok` with no network request. Otherwise it probes the endpoint: with Jira credentials set, it reports whether the API token was accepted; without them, it reports that no Jira email and API token are configured (so Claude Code falls back to your own `/mcp` sign-in, which the probe cannot see); and either way, an unreachable endpoint reports as such. See [Pack MCP servers](/configuration/mcp#pack-mcp-servers) for consent, precedence, and the full auth rule. @@ -805,7 +806,7 @@ The cache lives in `~/.overdeck/packs/` and can be rebuilt at any time, except t Packs apply to Overdeck-managed **Claude Code** and **Codex** sessions at their next launch, like other skill changes. A running Claude Code conversation can also load packs in place with `pan skills add` (see [Adding skills to a running conversation](#adding-skills-to-a-running-conversation)). Claude Code receives the pack as `--plugin-dir`; Codex gets a local `overdeck-packs` plugin marketplace in the agent's own `$CODEX_HOME`. Remote (Fly) launches and other harnesses get no packs. Pi gets no packs: it accepts `pan handoff --pack` and the dialog's Skills choices, but never applies them. A launch never touches the network: if the trusted commit is not cached, the launch skips that pack and prints `run pan skills pack sync <id>`. If Claude Code also has the same upstream plugin installed, the dashboard warns that its skills will appear twice. See [Authoring a skill pack](/guides/skill-pack-authoring) for what a mount contains. -In the dashboard, packs appear below the skill list on the Skills page, in project settings, and in the issue view. The dashboard can turn packs on and off but not add them; it shows the `pan skills pack add` command instead. At project and issue level a pack and its skills keep the **Inherit / On / Off** control. +In the dashboard, packs appear below the skill list on the Skills page, in project settings, and in the issue view. The dashboard turns packs on and off. On the Skills page it can also add the known packs listed under **Available packs** (see [Adding packs from the dashboard](#adding-packs-from-the-dashboard)); for any other pack it shows the `pan skills pack add` command. At project and issue level a pack and its skills keep the **Inherit / On / Off** control. ## Troubleshooting @@ -815,7 +816,7 @@ In the dashboard, packs appear below the skill list on the Skills page, in proje | A pack skill is not visible to the agent | The pack or skill is off at the level that decides, the skill is opt-in, the harness is not Claude Code or Codex, or the launch is remote (Fly) | `pan skills list --project <key> --issue <id>`; turn on the pack (`--pack`) or the opt-in skill (`<pack>/<skill>`); packs apply only to Overdeck-managed Claude Code and Codex launches | | A running agent did not pick up a change | Packs resolve at launch | `pan skills add <conversation> --pack <id>` loads them into a running Claude Code conversation in place; for Codex, or for packs that need launch-time settings, add `--restart` | | Skills appear twice (`video-edit` and `openmontage:video-edit`) | A copy of the skill is also installed in `~/.claude/skills` (for example a symlink into an OpenMontage clone, or an `npx skills` install), and that copy loads in every session | Remove the global copy, or keep the pack off | -| The dashboard shows `also installed as a Claude plugin — skills will appear twice` | Claude Code also has the same upstream plugin installed | Uninstall the Claude Code plugin, or keep the pack off | +| The dashboard says the pack is also installed as a Claude plugin, so its skills will appear twice | Claude Code also has the same upstream plugin installed | Uninstall the Claude Code plugin, or keep the pack off | | Launch prints `[launcher] WARNING: gstack browser runtime not built; run pan skills pack sync gstack` | Browser consent is recorded but the runtime for the trusted commit is missing | `pan skills pack sync gstack` | | `pack gstack needs bun on PATH (https://bun.sh)` | `bun` is not installed or not on `PATH` | Install bun, then repeat the command | | An old gstack render stays after `pan skills pack gc` | A linked mount still uses it, or it is younger than `--max-age-days` (using a mount resets its age and its render's age) | Wait until no launch uses it, or run `pan skills pack gc --max-age-days <n>` with a smaller value | @@ -823,7 +824,8 @@ In the dashboard, packs appear below the skill list on the Skills page, in proje | Launch prints `[launcher] WARNING: SageOx not applied: ox is not built for the sageox pack (<commit>); run pan skills pack sync sageox` | The build for the trusted commit is missing or incomplete; launches never build | `pan skills pack sync sageox` (needs Go), then relaunch | | A PR is not mergeable with `PR changes SageOx link files (.sageox/) but <key> has not opted in to committing them; …` | The PR adds or changes `.sageox/`, and the project has not committed its link | Remove `.sageox/` from the PR, or run `pan skills pack sageox commit --project <key>` and merge that PR first | | A PR is not mergeable with `SageOx merge guard could not read the PR's changed files: …` | The guard could not read the PR's diff, so it fails closed | Fetch the PR head in the named directory (`git fetch origin <branch>`), then let the gate re-check | +Still stuck? Ask in [Discord](https://discord.gg/ZpHE2ZTv5P) or open a [GitHub issue](https://github.com/eltmon/overdeck/issues). ## Terminology: skill packs and skill bundles -The noun "skill bundle" means skill pack, everywhere in Overdeck's docs and skills. The adjective "bundled" (shipped with Overdeck, in `sync-sources/`) is unrelated — a bundled skill or a bundled rule is one Overdeck ships, not a skill pack. [Template Conversations](/reference/template-conversations) describes a separate, unbuilt proposal (PAN-1357) that calls its curated group a "skill set," not a skill bundle. Per-conversation skill values (PAN-4486), set in the **New conversation with options…** dialog or by `pan handoff --skill/--pack`, already cover part of that proposal: a conversation can turn on pack skills for itself. See [Template Conversations](/reference/template-conversations) and [Conversations](/features/conversations). +The noun "skill bundle" means skill pack, everywhere in Overdeck's docs and skills. The adjective "bundled" (shipped with Overdeck, in `sync-sources/`) is unrelated: a bundled skill or a bundled rule is one Overdeck ships, not a skill pack. [Template Conversations](/reference/template-conversations) describes a separate, unbuilt proposal (PAN-1357) that calls its curated group a "skill set," not a skill bundle. Per-conversation skill values (PAN-4486), set in the **New conversation with options…** dialog or by `pan handoff --skill/--pack`, already cover part of that proposal: a conversation can turn on pack skills for itself. See [Template Conversations](/reference/template-conversations) and [Conversations](/features/conversations). diff --git a/features/skills.mdx b/features/skills.mdx index bf74131eec1..6cec63972a5 100644 --- a/features/skills.mdx +++ b/features/skills.mdx @@ -1,34 +1,29 @@ --- -title: Skills System -description: "How Overdeck skills work: reusable SKILL.md workflows that pan sync installs for every supported harness, and how to turn each one on or off." +title: "Skills: bundled workflows, pan sync and on/off overrides" +sidebarTitle: "Skills System" +description: "How Overdeck skills work: reusable SKILL.md workflows that pan sync installs for Claude Code, Codex and Pi, and how to turn each one on or off." --- import { ThemedImage } from "/snippets/themed-image.mdx"; Overdeck's skills system provides reusable workflows and best practices for AI agents. -The dashboard's **Skills** page lists every skill side by side per harness — here `Overdeck (108)` and `Claude (123)` — with each skill's on-disk path, internal `name`, and a sync indicator linking to its `SKILL.md`. It's the quickest way to confirm a skill landed where the agent (or the conversation you're driving) can invoke it. - -<ThemedImage - light="/images/dashboard/skills-light.png" - dark="/images/dashboard/skills-dark.png" - alt="Skills page: per-harness columns (Overdeck and Claude) listing each skill's path, name, and SKILL.md sync status, with an activity feed on the right" -/> +The dashboard's **Skills** page (left column, More, System, Skills) lists every skill with its description and a global on/off switch, grouped as Core (locked on), Overdeck (`~/.overdeck/skills`) and Personal (`~/.claude/skills`, `~/.agents/skills`). Filter by name or description, or narrow the list with **All**, **Off**, **Core** and **Overridden below**. Skill packs are listed below the skills. ## What Are Skills Skills are reusable, shareable workflows that encode best practices for common development tasks. They are: -- **Universal** - Work across all AI coding tools (Claude Code, Codex, Cursor, Gemini CLI, Google Antigravity) -- **Shareable** - Distribute via `pan sync` to sync to all connected AI tools -- **Contextual** - Invoked with `/skill-name` in AI tool prompts +- **Multi-harness** - `pan sync` installs them for Claude Code (`~/.claude/skills`) and for Codex and Pi (`~/.agents/skills`) +- **Shareable** - `pan sync` copies them to every harness skill directory it manages +- **Contextual** - Invoked with `/skill-name` in an agent's prompt - **Best-practice-driven** - Encode proven workflows and checklists Skills eliminate the need to repeatedly explain how to do common tasks. Instead of telling an agent "please review this code for security issues", you invoke `/code-review-security` and the agent follows the established workflow. ## Built-In Skills -Overdeck ships with 70+ built-in skills organized by category: +Overdeck ships more than 120 built-in skills. A selection, by category: ### Development Workflows @@ -37,7 +32,6 @@ Overdeck ships with 70+ built-in skills organized by category: | `feature-work` | Standard feature implementation workflow | | `bug-fix` | Systematic bug investigation and fixing | | `refactor` | Safe refactoring with tests first | -| `code-review` | Comprehensive code review checklist | | `code-review-security` | OWASP Top 10 security analysis | | `code-review-performance` | Algorithm and resource optimization | | `release` | Step-by-step release process | @@ -62,24 +56,21 @@ Overdeck ships with 70+ built-in skills organized by category: | `pan-up` | Start dashboard and services | | `pan-down` | Stop dashboard and services | | `pan-status` | Show running agents | -| `pan-issue` | Spawn agent for an issue | +| `pan-start` | Spawn a work agent for an issue | | `pan-plan` | Create execution plan for issue | | `pan-tell` | Send message to running agent | | `pan-kill` | Kill a running agent | -| `pan-approve` | Approve agent work and merge | -| `pan-health` | Check system health | -| `pan-sync` | Sync skills to AI tools | +| `pan-doctor` | Check system health, dependencies and configuration | +| `pan-sync` | Sync skills to every harness skill directory | | `pan-install` | Install prerequisites | -| `pan-setup` | Initial setup wizard | | `pan-quickstart` | Quick start guide | | `pan-projects` | Manage registered projects | -| `pan-tracker` | Issue tracker operations | +| `pan-admin-tracker` | Tracker-specific operations (Linear states, cleanup) | | `pan-logs` | View agent logs | -| `pan-rescue` | Recover crashed agents | | `pan-diagnose` | Diagnose agent issues | | `pan-docker` | Docker operations | | `pan-network` | Network diagnostics | -| `pan-config` | Configuration management | +| `pan-admin-config` | View and edit project configuration | | `pan-restart` | Safely restart Overdeck dashboard and services | | `pan-code-review` | Orchestrate parallel code review (3 reviewers + synthesis) | | `pan-subagent-creator` | Create specialized subagents | @@ -94,12 +85,10 @@ Overdeck ships with 70+ built-in skills organized by category: | Skill | Description | |-------|-------------| -| `beads` | Git-backed issue tracking with dependencies | | `claude-skill-creator` | Guide for creating Claude Code skills | | `web-design-guidelines` | UI/UX review checklist | | `clear-writing` | Proven rules for clearer prose in docs, commits, and UI text | | `crash-investigation` | Investigate system crashes, OOM kills, and freezes | -| `opus-plan` | Opus-driven planning with PRD, STATE.md, and beads | | `spec-readiness` | Evaluate issue requirements readiness (scored 0-100) | | `check-merged` | Verify if a feature branch has been merged into main | | `react-best-practices` | React/Next.js performance optimization from Vercel | @@ -107,17 +96,17 @@ Overdeck ships with 70+ built-in skills organized by category: ## Using Skills -Skills are invoked via slash commands in any AI coding tool: +Skills are invoked as slash commands, for example in Claude Code: ``` -# In Claude Code, Cursor, Windsurf, etc: +# In Claude Code: /feature-work /code-review-security /bug-fix /pan-help ``` -When you invoke a skill, the AI tool injects the skill's prompt into the conversation, giving the agent detailed instructions on how to proceed. +When you invoke a skill, the harness injects the skill's prompt into the conversation, giving the agent detailed instructions on how to proceed. ## Creating Custom Skills @@ -129,7 +118,11 @@ Skills are markdown files stored in `~/.overdeck/skills/`. Create your own with: # Or manually create a skill mkdir -p ~/.overdeck/skills/my-custom-skill -cat > ~/.overdeck/skills/my-custom-skill/skill.md <<'EOF' +cat > ~/.overdeck/skills/my-custom-skill/SKILL.md <<'EOF' +--- +name: my-custom-skill +description: One line saying what the skill does and when to use it +--- # My Custom Skill Brief description of what this skill does. @@ -150,13 +143,18 @@ Describe when this skill should be invoked. - Tip 2 EOF -# Sync to all AI tools +# Install it for every harness. This overwrites a different file at the same +# path in ~/.claude/skills, so keep personal skills only in ~/.overdeck/skills. pan sync ``` **Skill anatomy:** ```markdown +--- +name: skill-name +description: One line saying what the skill does and when to use it +--- # Skill Title One-line description. @@ -189,25 +187,25 @@ When to invoke this skill (triggers). - /complementary-skill - Use together with this ``` -See the [Claude skill creator](/cli/core-commands) or use `/pan-skill-creator` for guided creation. +Use `/pan-skill-creator` or `/claude-skill-creator` for guided creation. ## Skill Distribution Skills can be distributed via: -1. **Project skills** — commit them to `.pan/skills/<name>/` in the project repo. See [Project skills](#project-skills). -2. **User-specific** - Store in `~/.overdeck/skills/` (synced to AI tools) -3. **Third-party skill repositories** — register them as a [skill pack](/features/skill-packs) with `pan skills pack add`; to publish your own, see [Authoring a skill pack](/guides/skill-pack-authoring). +1. **Project skills**: commit them to `.pan/skills/<name>/` in the project repo. See [Project skills](#project-skills). +2. **User-specific** - Store in `~/.overdeck/skills/` (installed for every harness by `pan sync`) +3. **Third-party skill repositories**: register them as a [skill pack](/features/skill-packs) with `pan skills pack add`; to publish your own, see [Authoring a skill pack](/guides/skill-pack-authoring). 4. **Overdeck's bundled skills** ship in `sync-sources/skills/` and reach every machine through `pan sync`. ### Project skills -Project skills live at `<projectRoot>/.pan/skills/<name>/` in the project's own repo. The catalog lists them last, so a project skill with the same name as a skill in `~/.overdeck/skills`, `~/.claude/skills` or `~/.agents/skills` is listed as that other skill instead. Project skills never appear on the global Skills page — only in that project's settings and its issues. +Project skills live at `<projectRoot>/.pan/skills/<name>/` in the project's own repo. The catalog lists them last, so a project skill with the same name as a skill in `~/.overdeck/skills`, `~/.claude/skills` or `~/.agents/skills` is listed as that other skill instead. Project skills never appear on the global Skills page, only in that project's settings and its issues. Overdeck copies `.pan/skills/<name>/` into `<workspace>/.claude/skills/<name>/` once, when the workspace manager creates an issue workspace (planning, the dashboard, swarm, or PR adoption). Two cases copy nothing: -- `pan workspace create` for a project with no `workspace:` block in `projects.yaml` — the CLI fallback does not copy project skills. -- An existing workspace — `pan workspace update`, `pan sync-main` and `pan sync` never copy project skills into it. +- `pan workspace create` for a project with no `workspace:` block in `projects.yaml`: the CLI fallback does not copy project skills. +- An existing workspace: `pan workspace update`, `pan sync-main` and `pan sync` never copy project skills into it. A target directory that already exists is never overwritten, and bundled skills are copied first, so a project skill with the same name as a bundled skill is skipped and the bundled skill wins. @@ -224,10 +222,10 @@ pan sync --dry-run ``` The `pan sync` command: -- Copies skills from `~/.overdeck/skills/` to each AI tool's config directory -- Updates existing skills if versions differ +- Copies skills from `~/.overdeck/skills/` to `~/.claude/skills` and `~/.agents/skills` +- Overwrites installed skill files you have not edited; a file you edited since Overdeck installed it is skipped and reported as user-modified (`pan sync --force` overwrites it). The vendored `okf` skill is the exception: when its skill directory is a real directory, not a symlink, `pan sync` replaces edited `okf` files in both targets and reports them as replaced vendored files - Removes manifest-managed skills from harness directories after their bundled source is removed -- Preserves user-owned and user-modified files, reporting modified stale files instead of deleting them +- Preserves files Overdeck did not install, except that in `~/.claude/skills` a file at the same path as any skill file in `~/.overdeck/skills`, bundled or your own, is overwritten and reported as adopted; when a bundled skill is removed, an installed copy you edited is reported instead of deleted - Ignores empty bundled skill directories so they do not reappear in caches or harness targets ## Turning skills on and off @@ -238,7 +236,7 @@ Every skill has an on/off state that you can set at three levels: a **global def A skill with no value at any level is on. The global level is two-state: a skill is either on (no stored value) or off. Project and issue levels are three-state: a skill inherits the level above, or is set on, or is set off, so a project can turn on a skill that is off globally, and an issue can turn off a skill its project turned on. -Conversation values are set only when the conversation is created, in the **New conversation with options…** dialog (see [Conversations](/features/conversations)). They are stored on the conversation row and applied at every launch, resume, restart and fork of that conversation. A conversation value for a pack skill (`pack/skill`) beats every level and every pack toggle, so a conversation can turn on one opt-in pack skill for itself. Core skills ignore conversation values too. +Conversation values are set when the conversation is created, in the **New conversation with options…** dialog (see [Conversations](/features/conversations)), and later with [`pan skills add`](/cli/skills-commands#pan-skills-add), the `add_skills` MCP tool or **Add skills…** in the conversation menu; a running Claude Code conversation loads added packs in place. They are stored on the conversation row and applied at every launch, resume, restart and fork of that conversation. A conversation value for a pack skill (`pack/skill`) beats every level and every pack toggle, so a conversation can turn on one opt-in pack skill for itself. Core skills ignore conversation values too. ### Core skills are always on @@ -294,23 +292,11 @@ A **skill pack** is a third-party git repository of skills that Overdeck pins to ## Subagents -Overdeck includes specialized subagent templates for common development tasks. Subagents are invoked via the Task tool or convoy orchestration for parallel execution. +Overdeck ships five pipeline agent definitions, `pan-work-agent`, `pan-review-agent`, `pan-test-agent`, `pan-uat-agent` and `pan-merge-agent`, which `pan sync` installs into `~/.claude/agents/` and Cloister uses when it launches the matching specialist. It ships no general-purpose subagent templates. -### Code Review Subagents - -| Subagent | Model | Focus | Output | -|----------|-------|-------|--------| -| `code-review-correctness` | haiku | Logic errors, edge cases, type safety | `.claude/reviews/<timestamp>-correctness.md` | -| `code-review-security` | sonnet | OWASP Top 10, vulnerabilities | `.claude/reviews/<timestamp>-security.md` | -| `code-review-performance` | haiku | Algorithms, N+1 queries, memory | `.claude/reviews/<timestamp>-performance.md` | -| `code-review-synthesis` | sonnet | Combines all findings into unified report | `.claude/reviews/<timestamp>-synthesis.md` | - -**Usage Example:** -```bash -/pan-code-review --files "src/auth/*.ts" -``` +### Code review -This spawns all three reviewers in parallel, then synthesizes their findings into a prioritized report. +Overdeck ships no code-review subagents. A full review runs as the [review convoy](/features/convoys): four reviewers (correctness, security, performance and requirements) whose prompts live in `roles/review-*.md` and are inlined when the review starts, plus a review parent that combines their findings. ### Planning & Exploration Subagents @@ -333,6 +319,5 @@ Overdeck ships no custom planning or exploration subagent files. Planning runs a ## Related Guides -- [Creating Skills](/cli/core-commands#pan-skill-creator) - Detailed skill creation guide -- [Convoys](/features/convoys) - Parallel subagent execution -- [Subagents](/cli/core-commands#pan-subagent-creator) - Custom subagent templates +- [Creating custom skills](#creating-custom-skills) - Write your own SKILL.md +- [Review convoy](/features/convoys) - Four parallel reviewers and one synthesis parent diff --git a/features/specialists.mdx b/features/specialists.mdx index c35bb22067b..4b17fc00185 100644 --- a/features/specialists.mdx +++ b/features/specialists.mdx @@ -1,19 +1,19 @@ --- title: "Review and test agents: checking an agent's work" sidebarTitle: "Specialists" -description: "After pan done, a review agent and a test agent check the work on the pull request. You click Merge when the PR is approved and its checks are green." +description: "After pan done, a review agent checks the pull request and its checks must pass. Then you click Merge, or auto-merge or the merge train lands it." --- import { ThemedImage } from "/snippets/themed-image.mdx"; -Work agents write the code. Two more agents check it before it can merge: a **review agent** and a **test agent**. The docs call them specialists. They run on the issue's pull request and post their verdicts to it, so GitHub shows the same state the dashboard does. +Work agents write the code. A **review agent** checks it before it can merge, and a **test agent** can run its tests and browser UAT. The docs call them specialists. They run on the issue's pull request and post their verdicts to it, so GitHub shows the same state the dashboard does. ## What happens after pan done 1. **Verification gate.** After `pan done`, Overdeck runs the project's quality gates. If a gate fails, the work agent gets the failure and fixes it. See [PIPELINE-GATES.md](https://github.com/eltmon/overdeck/blob/main/docs/PIPELINE-GATES.md). 2. **Review.** A review agent reads the diff, the plan and the acceptance criteria, then approves the PR or requests changes. By default one reviewer does a combined pass for correctness, security, performance and requirements (`quick` mode, see [Review commands](/cli/review-commands) "Review modes"). Set `roles.review.mode: full` to run the [review convoy](/features/convoys): four reviewers for security, correctness, performance and requirements, and a review parent that writes the verdict. -3. **Test.** A test agent runs the project's test commands. When the acceptance criteria describe UI behavior, it also drives a browser with Playwright and records a separate UAT verdict. There is no separate UAT agent. -4. **Merge.** When the PR is approved, its checks are green and GitHub says it can merge, the issue is ready. Overdeck rebases the branch onto `main` on the server. You click **Merge** on the issue, or on the Awaiting Merge page, and Overdeck squash-merges the PR. No agent merges code. +3. **Test.** Nothing starts a test agent automatically after the review approves ([#5537](https://github.com/eltmon/overdeck/issues/5537)). In a project that runs its tests on CI (`verification.tests: ci`, or a GitHub Actions workflow that runs a test job on pull requests), the CI test job must pass on the PR head before the PR can merge. Running `pan review request` on a PR that is approved at its head but whose checks are not green starts a test agent: it runs the project's test commands and, when the acceptance criteria describe UI behavior, drives a browser with Playwright and records a separate UAT verdict. There is no separate UAT agent. +4. **Merge.** When the PR is approved at its head commit, its checks are green and GitHub says it can merge, the issue is ready. Whether you click depends on whether the issue is held for UAT: its `hold-for-uat` or `auto-merge` label, else the project's `auto_merge_default`, else the global **Require UAT** switch on the Flywheel page header, which is on by default. A held issue waits for you to click **Merge** on the issue or on the Awaiting Merge page. In a GitHub single-repo project, an issue that is not held merges on its own five minutes after it is ready, or with the next batch while the [merge train](/features/merge-batches) is on; GitLab and polyrepo projects never merge on their own. To merge, the server merges a clean, up-to-date PR as it is; otherwise it rebases the branch onto `main` itself, and when that rebase fails during a merge you started, it asks the work agent to rebase and push. Overdeck then squash-merges the PR. No agent merges it. To ship without the click, turn on [auto-merge](/configuration/auto-merge). To land several PRs together, use [merge batches](/features/merge-batches). diff --git a/features/swarm.mdx b/features/swarm.mdx index 316d38ab92f..0c278fd9c3b 100644 --- a/features/swarm.mdx +++ b/features/swarm.mdx @@ -18,7 +18,7 @@ The foreman has two ways to dispatch a worker: a same-harness subagent running i ### Item worktrees and branches -Ordinarily, a worker runs in its own item worktree, `<workspace>/.swarm/<item>/`, on a branch named `<feature-branch>-<item>`; an existing worktree for the same item is reused rather than recreated. `pan spawn --shared` is the one exception: it runs the worker directly in the issue's own workspace, on the feature branch, with no item worktree or item branch. It is for the foreman or an operator only, and is meant for strictly serial use: run at most one `--shared` worker at a time, since nothing enforces that. +A `pan spawn` worker runs in its own item worktree, `<workspace>/.swarm/<item>/`, on a branch named `<feature-branch>-<item>`; an existing worktree for the same item is reused rather than recreated. `pan spawn --shared` is the one exception: it runs the worker directly in the issue's own workspace, on the feature branch, with no item worktree or item branch. It is for the foreman or an operator only, and is meant for strictly serial use: run at most one `--shared` worker at a time, since nothing enforces that. ### How work comes back @@ -26,7 +26,7 @@ Each worker commits once per item, with `Item: <id>` and one `Item: <id>.acN` li ## Claims and overlapping files -`pan task claim` refuses to claim an item that a live agent already holds, or whose `files_scope` overlaps an item a live agent holds. An item whose `files_scope_confidence` is `low` refuses any concurrent claim at all. `--steal` overrides this, for the foreman or an operator only. +`pan task claim` refuses to claim an item that a live agent already holds, or whose `files_scope` overlaps an item a live agent holds. An item whose `files_scope_confidence` is `low` refuses any concurrent claim at all. `--steal` overrides this. It is meant for the foreman or an operator; nothing checks who passes it. ## Who can message a worker @@ -34,11 +34,11 @@ Only the issue's own work pane, the worker's parent, or an operator conversation ## Gated slot swarm -A plan is eligible for the gated slot swarm when at least two items are slot-eligible, each one has a `files_scope`, and at least one slot-eligible item is currently dispatchable (not waiting on an unfinished dependency). A plan with two slot-eligible items that both depend on the same unfinished, unscoped item is not eligible until that blocker clears. A slot runs on its own branch, `feature/<issue>-slot-<N>`, in its own worktree. +A plan is eligible for the gated slot swarm when at least two items are slot-eligible (readiness `ready`, a non-empty `files_scope` whose `files_scope_confidence` is not `low`, and at least one `verify_commands` and one `expected_outputs` entry), and at least one slot-eligible item is currently dispatchable (not waiting on an unfinished dependency). A plan with two slot-eligible items that both depend on the same unfinished, unscoped item is not eligible until that blocker clears. A slot runs on its own branch, `feature/<issue>-slot-<N>`, in its own worktree. -`pan swarm <id>` starts or attaches the foreman; it does not dispatch slot work itself, and it prints that the foreman owns dispatch. The foreman is what drives slots forward, with `pan swarm dispatch`, `pan swarm wait`, `pan swarm merge` and the rest of the `pan swarm` subcommands. +`pan swarm <id>` starts or attaches the foreman; it does not dispatch slot work itself, and it prints that the foreman owns dispatch. It refuses a plan that is not eligible and lists the reasons. When the effective swarm mode is Off, it first stores `swarm.policy.mode=always` for that issue, so the foreman stays managed. The foreman is what drives slots forward, with `pan swarm dispatch`, `pan swarm wait`, `pan swarm merge` and the rest of the `pan swarm` subcommands. -Settings → Swarming holds the swarm policy for this mechanism: "Automatic selection" (Off, Auto, Always), "Maximum slots per issue", and "Advance waves automatically". A project's own "Automatic swarming" select (Inherit, Off, Auto, Always) overrides the global setting for that project. +Settings → Swarming holds the swarm policy for this mechanism: "Automatic selection" (Off, Auto, Always), "Maximum slots per issue", and "Advance waves automatically" (defaults: Off, 3 slots with a range of 1 to 12, advance on). A project's own "Automatic swarming" select (Inherit global, Off, Auto, Always) overrides the global setting for that project. ## CLI diff --git a/features/workspaces.mdx b/features/workspaces.mdx index a4df64bca9a..4f8f322fac8 100644 --- a/features/workspaces.mdx +++ b/features/workspaces.mdx @@ -13,7 +13,7 @@ Each workspace is where an agent's conversation and its work live together: the <ThemedImage light="/images/dashboard/board-light.png" dark="/images/dashboard/board-dark.png" - alt="Kanban board: issue columns with cost badges, agent status dots, and workspace controls, one card per issue/workspace" + alt="Board view: Backlog, Plan, Work, Review and Done columns of issue cards showing task progress, agent activity and actions such as Start work, under cycle and project filters and a Needs you strip" /> ## Workspace kinds @@ -30,10 +30,10 @@ Memory is kept per workspace, so a scratch or main workspace collects memory fro **Workspaces are git worktrees** - isolated working directories for each issue/feature. Each workspace: -- Has its own feature branch (e.g., `feature/min-123-add-login`) +- Has its own feature branch, named `feature/<issue>` (e.g., `feature/min-123`) - Shares git history with the main repo (no separate clone) - Can run independently (separate node_modules, builds, containers) -- Is located at `{project}/workspaces/{issue-id}/` +- Is located at `{project}/workspaces/feature-<issue>/` (lowercase, e.g. `workspaces/feature-min-123/`) This architecture allows multiple agents to work simultaneously without stepping on each other's toes. @@ -60,14 +60,14 @@ project/ ├── package.json └── workspaces/ ├── feature-min-123/ # Workspace for MIN-123 - │ ├── .git # Symlink to ../.git - │ ├── .planning/ # Planning artifacts (ephemeral) + │ ├── .git # File pointing at the shared ../../.git + │ ├── .overdeck/ # Workspace runtime state (plan copy, continue file, pipeline journal) │ ├── src/ # Feature branch code │ ├── node_modules/ # Independent dependencies │ └── docker-compose.yml └── feature-min-456/ # Workspace for MIN-456 ├── .git - ├── .planning/ + ├── .overdeck/ └── src/ ``` @@ -94,35 +94,27 @@ Git worktrees allow multiple working directories to share a single git repositor ``` workspaces/feature-min-123/ -├── .planning/ # Planning artifacts (ephemeral) -│ ├── STATE.md # Current planning state -│ ├── output.jsonl # Full conversation history -│ ├── PLANNING_PROMPT.md # Initial planning prompt -│ ├── CONTINUATION_PROMPT.md # Context for continued sessions -│ └── output-*.jsonl # Backup of previous rounds +├── .overdeck/ # Workspace runtime state +│ ├── spec.vbrief.json # Working copy of the xBRIEF plan +│ ├── continue.json # Item progress +│ ├── sessions.jsonl # Agent sessions in this workspace +│ └── pipeline.jsonl # Pipeline journal +├── .pan/ # Committed planning artifacts (drafts/, specs/, continues/) ├── src/ # Feature branch code ├── node_modules/ # Independent dependencies ├── package.json └── docker-compose.yml # Workspace-specific containers ``` -### Planning Artifacts +### Planning artifacts -> ⚠️ **Note: `.planning/` is currently ephemeral (not tracked in git)** -> -> The `.planning/` directory is listed in `.gitignore` to prevent cross-contamination between issues. When branches merge, planning state from issue A could contaminate issue B's workspace, causing agents to work on the wrong tasks. -> -> **Current behavior:** Planning state is local to your machine only. If you switch machines, you'll need to re-run the planning session. +Planning writes its artifacts under `.pan/` in the project repo and commits them on the feature branch, so they travel with the branch. A polyrepo project can name one sub-repo as the plan home with `pan_records.repo` in `projects.yaml`. -When planning completes, the AI generates: -- **STATE.md** - Current understanding, decisions made, and implementation plan -- **Beads tasks** - Trackable sub-tasks with dependencies -- **Feature PRD** - Copied to `docs/prds/active/{issue}-plan.md` for documentation +- `.pan/drafts/<issue>.md`: the PRD draft +- `.pan/specs/`: the xBRIEF plan +- `.pan/continues/`: the continue files that record item progress -**What persists:** -1. **Context recovery** - STATE.md and beads preserve planning decisions -2. **Audit trail** - See decisions made in STATE.md -3. **Beads tasks** - Sub-tasks ARE persisted (beads uses label-based isolation) +The workspace's `.overdeck/` directory holds runtime state: a working copy of the plan (`spec.vbrief.json`), `continue.json`, `sessions.jsonl`, `context.md`, `feedback/` and the pipeline journal `pipeline.jsonl`. Work items are xBRIEF items; agents claim and complete them with `pan task`. ## Docker Integration @@ -140,22 +132,21 @@ pan workspace create MIN-123 --docker **What happens:** 1. Creates the workspace (git worktree) -2. Looks for docker-compose files in workspace -3. Runs `docker compose -p "{project}-feature-{issue}" up -d --build` +2. Looks for a compose file in the workspace root or `.devcontainer/`, and regenerates `.devcontainer/` from the project template when none exists +3. Runs `docker compose -f <compose file> up -d --build` without `-p`, so the compose file names the stack **Docker Project Naming:** -Each workspace gets a unique Docker Compose project name: -- Format: `{project-name}-feature-{issue-id}` -- Example: `mind-your-now-feature-min-123` -- Container names: `{project}-{service}-1` +`pan workspace create --docker` passes no project name, so Docker Compose picks it: the compose file's top-level `name:` field, else `COMPOSE_PROJECT_NAME`, else the name of the folder that holds the compose file. Overdeck's own stack lookups, such as stack health, read the same `name:` field or `COMPOSE_PROJECT_NAME` in the workspace's `dev` script, and fall back to `overdeck-feature-<issue>`. +- Example: a compose file with `name: myn-feature-min-123` +- Container names: `{compose-project}-{service}-1` This prevents conflicts when running multiple workspaces simultaneously. ### Dashboard Integration The planning dialog includes a "Start Docker containers" checkbox: -- **Default:** Enabled (containers start automatically) +- **Default:** Off (planning agents don't need Docker) - **Preference saved:** Your choice is remembered in browser localStorage **Why this helps:** @@ -177,35 +168,31 @@ pan workspace create MIN-123 --docker **What happens:** 1. Creates git worktree at `{project}/workspaces/feature-min-123/` -2. Checks out feature branch `feature/min-123-*` +2. Creates and checks out the branch `feature/min-123` 3. Optionally starts Docker containers 4. Registers workspace in Overdeck registry ### 2. Usage Agents work inside the workspace: -- **Planning agents** - Explore codebase, create STATE.md and beads tasks +- **Planning agents** - Explore the codebase and write the PRD draft and the xBRIEF plan - **Work agents** - Implement features, run tests, commit changes -- **Specialists** - Review code, run tests, merge changes +- **Review and test agents** - Review the code and run the tests All activity isolated to the workspace directory. ### 3. Cleanup ```bash -# Destroy workspace (safe - checks for uncommitted changes) +# Destroy workspace (uncommitted changes are discarded, so commit and push first) pan workspace destroy MIN-123 - -# Force destroy (even with uncommitted changes) -pan workspace destroy MIN-123 --force ``` **What happens:** -1. Stops and removes Docker containers (if any) -2. Checks for uncommitted changes (unless --force) -3. Removes git worktree -4. Cleans up planning artifacts -5. Unregisters from Overdeck +1. Stops the workspace's Docker stack (projects with a `workspace` block in `projects.yaml`) +2. Removes every worktree for the issue (base, strike and slot; limit with `--shape`) with `git worktree remove --force`, so uncommitted changes are lost +3. Deletes the local feature branch +4. Removes the workspace's record; `--purge-memory` also deletes its memory After an issue's pull request merges, close it out with `pan close <id>` or the **Close Out** button; [Cleaning up after close-out](#cleaning-up-after-close-out) explains what that removes. @@ -343,7 +330,7 @@ Below the first control, a line reports how many closed issues still have a work > **CRITICAL:** The main project directory must **ALWAYS** stay on the `main` branch. All feature work happens in workspaces. **Why this matters:** -- **Specialists** (review-agent, test-agent) need a stable reference point +- **Review and test agents** need a stable reference point - **Merge operations** require a clean target - **Multiple agents** won't interfere with each other @@ -380,24 +367,17 @@ export OVERDECK_AUTO_REVERT_CHECKOUT=1 # Add to .bashrc/.zshrc ### Planning vs Work Agent Safeguard -The dashboard prevents starting a work agent (`agent-<issue>`) while a planning agent (`planning-<issue>`) is still running. This prevents conflicts where both agents try to modify the same workspace. +Planning refuses to start while a work agent (`agent-<issue>`) is running for the issue ("Cannot start planning: work agent already running"). A work agent refuses to start until the issue has a finalized xBRIEF plan with items. -If you see "Planning agent is still running": -1. **Complete planning** - Use "Complete Planning" button -2. **Or abort** - Use "Abort Planning" to discard -3. **Or kill manually** - `pan kill planning-<issue>` +To move from planning to work, accept the plan: the **Accept plan** action finalizes it (`pan plan finalize`). -### Specialist Agent Safeguards +To stop planning instead (neither of these finalizes the plan, so work stays blocked): +- **Abort Planning** in the planning dialog returns the issue to Todo and keeps the workspace. +- `pan kill planning-<issue>` stops the planning agent. -All specialist agents (review-agent, test-agent, merge-agent) are configured to: -1. **Run in workspaces only** - Never in main project directory -2. **Never checkout branches** - Work with branch already in workspace -3. **Create workspaces if needed** - Use `pan workspace create` instead of `git checkout` +### Agent safeguards -These safeguards are enforced through: -- **Prompt instructions** - Clear warnings in all specialist prompts -- **Code enforcement** - Specialists spawn with workspace as cwd -- **Git hooks** - Auto-revert if checkout detected in tmux sessions +Planning, work, review and test agents start with the issue workspace as their working directory, never the main project directory. The work prompt tells the agent never to check out another branch in its workspace. The post-checkout hook auto-reverts a checkout in the main project directory when it runs inside an Overdeck agent (`OVERDECK_AGENT=1` or `OVERDECK_AGENT_ID` set), a planning session, or a tmux session named `agent-*`, `planning-*` or `specialist-*`. ## Use Cases @@ -438,8 +418,8 @@ pan workspace create MIN-999-hotfix - Use `--docker` flag to warm up containers early **Branch Naming:** -- Follow convention: `feature/{issue-id}-{description}` -- Example: `feature/min-123-add-login` +- Branches are named `feature/<issue>`, lowercase +- Example: `feature/min-123` - Overdeck auto-generates appropriate names **Docker Usage:** @@ -448,9 +428,9 @@ pan workspace create MIN-999-hotfix - Keep docker-compose.yml in workspace (not main project) **Planning Artifacts:** -- `.planning/` is ephemeral - don't rely on it for cross-machine work -- STATE.md and beads persist the important context -- Feature PRD goes to `docs/prds/active/` for permanent storage +- The PRD draft and xBRIEF plan live under `.pan/` and are committed on the feature branch, so they move with the branch +- Item progress is kept in the continue file and updated with `pan task` +- The PRD is `.pan/drafts/<issue>.md` ## Remote workspaces on Fly @@ -459,7 +439,7 @@ Overdeck supports remote workspace execution via Fly.io Machines. Remote workspa ### Why Remote Workspaces? - **Resource isolation**: heavy builds and tests don't compete with your local machine. -- **On-demand provisioning**: machines spin up per workspace and shut down after merge. +- **On-demand provisioning**: machines spin up per workspace and are destroyed when the agent finishes and its branch is handed to review. - **Same workflow**: the CLI and dashboard work the same for local and remote workspaces. ### Setup @@ -480,14 +460,14 @@ pan admin remote resources ### Creating Remote Workspaces -Remote workspaces are created through the dashboard planning dialog or CLI: +Remote workspaces are created from the planning dialog (**Workspace Location**: **Remote (Fly.io)**) or the CLI: ```bash # Create workspace with remote execution pan workspace create MIN-123 --remote ``` -The workspace is provisioned on a Fly.io Machine with your project's dependencies pre-installed. Agents connect to the remote environment via the same tmux-based interface used for local workspaces. +The workspace is provisioned on a Fly.io Machine with your project's dependencies pre-installed. The agent runs in a tmux session on the machine. To start the work agent on Fly directly, use `pan start` with `--remote`: @@ -518,7 +498,7 @@ git worktree remove workspaces/feature-min-123 docker ps | grep feature-min-123 # Stop conflicting containers -docker compose -p mind-your-now-feature-min-123 down +docker compose -p myn-feature-min-123 down # the name: from the workspace's compose file ``` **Main project on wrong branch:** @@ -533,12 +513,13 @@ git checkout main # List all workspaces pan workspace list -# Destroy completed workspaces +# Show merged branches still on disk, with sizes, then destroy them +pan workspace list --stale pan workspace destroy MIN-123 pan workspace destroy MIN-456 ``` -Because each running workspace carries its own agents, conversations, and processes, parallel work also consumes RAM. The dashboard's Resources page breaks down system memory by agents, conversations, and processes so you can see which workspaces are heaviest before deciding which to destroy. +Because each running workspace carries its own agents, conversations, and processes, parallel work also consumes RAM. The dashboard's Resources page (experimental: turn on **Settings → Experimental → Experimental features**) breaks down system memory by agents, conversations, and processes so you can see which workspaces are heaviest before deciding which to destroy. <ThemedImage light="/images/dashboard/resources-light.png" @@ -546,8 +527,10 @@ Because each running workspace carries its own agents, conversations, and proces alt="Resources page: system RAM usage broken down by agents, conversations, and processes" /> +Still stuck? Ask in [Discord](https://discord.gg/ZpHE2ZTv5P) or open an issue on [GitHub](https://github.com/eltmon/overdeck/issues). + ## Related Guides - [Workspace Commands](/cli/workspace-commands) - CLI reference -- [Specialists](/features/specialists) - Specialist agent workspace usage +- [Review and test agents](/features/specialists) - How review and test agents check the work - [Planning](/features/planning) - Planning an issue before work starts