From f4fbe07f8376a875bb0c4e141f2b85d7385dd301 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:33:50 -0500 Subject: [PATCH 01/80] chore(plan): complete planning for PAN-5500 Plan-Finalized: cea016f08abe2751f01be168c5fd59926c8404f6d2a943fb9c656a634dde9b6f --- .pan/drafts/PAN-5500.md | 1519 +++++++++++ ...dit-overdeck-anywhere-21-pages.xbrief.json | 2256 +++++++++++++++++ 2 files changed, 3775 insertions(+) create mode 100644 .pan/drafts/PAN-5500.md create mode 100644 .pan/specs/2026-11-19-PAN-5500-docs-accuracy-audit-overdeck-anywhere-21-pages.xbrief.json diff --git a/.pan/drafts/PAN-5500.md b/.pan/drafts/PAN-5500.md new file mode 100644 index 00000000000..54ef05656fc --- /dev/null +++ b/.pan/drafts/PAN-5500.md @@ -0,0 +1,1519 @@ +# PAN-5500: accuracy audit of the Overdeck Anywhere docs group + +**Issue:** https://github.com/eltmon/overdeck/issues/5500 (part of epic #5467, docs overhaul) +**Priority:** P1. Docs-only change. No code changes, no `changelog.d` entry. +**Base:** `main` at `62f98b27ac6` (v0.89.1 plus later merges), 2026-11-18. PAN-5472 (#5535, merged as `94f8a78502d`) +already edited `configuration/phone.mdx`, so the issue's precondition for that page is met and this audit works on top +of its result. + +## Summary + +The issue asks for a line-by-line accuracy audit of every published page in the **Overdeck Anywhere** navigation +groups (21 pages). The planning session already did the audit. Eight research passes read all 21 pages (6,122 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 file exists. The planner also re-checked these high-stakes claims by hand against primary +sources: the billing and plan claims (`services/account/src/entitlement.ts`, `grants.ts`, +`migrations/0001_init.sql`, `billing/catalog.ts`, `wrangler.jsonc`); the `## What comes next` deletion on +`remote-access` (`gh issue view` shows #4402, #4403, #4404 and #4645 closed); the webhook-triggers release +(`changelog.mdx:511`, v0.73.0); the v0.73.0 known limitations (`changelog.mdx:515`, with #4863 still open); the phone +store status (`apps/mobile/RELEASE.md:186`); the Grok MCP claim (`packages/contracts/src/harness-capabilities.ts:281-282`); +the `pan triggers remove` inbox gap (`src/dashboard/server/routes/triggers.ts:148`); and the anchor slug (probe below). + +This PRD lists every wrong, stale or removed claim per page. Each one has the exact current text, the replacement text +and the code evidence (Appendices A to U). The planner's overrides are already patched into the appendix rows; the +Overrides section is the record of what changed and why. Every Missing bullet carries an `[ADD]` or `[SKIP]` tag. The +implementation agent applies the change tables and the overrides. It also removes the en and em dashes, fixes the +frontmatter, adds the help links, runs the Mintlify validators and 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 or when the code contradicts a +row (Common procedure step 0). + +## Glossary + +- **Anywhere group**: the two `docs.json` navigation groups that hold the 21 pages. `"group": "Overdeck Anywhere"` + holds `anywhere` and ten `configuration/` pages (`session-vault`, `remote-access`, `linked-machines`, + `shared-sessions`, `triggers`, `tailscale`, `mcp`, `bots`, `phone`, `push-notifications`). `"group": "Anywhere CLI"` + holds ten `cli/` pages (`vault`, `pair`, `tailscale`, `account`, `share`, `devices`, `machines`, `token`, `mcp`, + `triggers`). Each slug `` is the file `.mdx` at the repo root. +- **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 price, a list of supported harnesses or platforms, or a + maturity label ("next release", "planned", "TestFlight", "experimental"). +- **Primary source**: the code on the base (`git grep`), the commander definitions under `src/cli/`, `pan + --help` (installed `pan` is 0.89.1, the same as the base; when `--help` and the commander source disagree, the + source on the branch wins), `src/lib/config-yaml/defaults.ts`, the dashboard source under + `src/dashboard/frontend/src/` and `src/dashboard/server/`, the Workers under `services/`, the phone app under + `apps/mobile/`, and `changelog.mdx`. Other `.mdx` pages, `docs/*.md` and `README.md` are never proof. +- **Grep anchor**: the quoted current text in each change-table row (the "Current text" column). Line numbers drift as + earlier edits land, so find the text with `grep -n -F '' .mdx`, not by line number. A few anchors are + given as "the table row containing X" or as a `` line: find those by that text. +- **Evidence line numbers are approximate.** The research passes cited `file:line`. Some cited lines are off by a few + lines, and a few are off by more: the planner found `src/cli/commands/sharing/join.ts:216` (the URL line is really at + 146-152), `src/cli/commands/pairing-link.ts:85` (the `LOOPBACK_WARNING` constant is at line 16), and + `src/lib/triggers/deliver.ts:189,339,358` (the rate-limit code is at about 39 and 186-207). Evidence given only as a + file basename (for example `resume.ts`, `join.ts`, `triggers.ts`, `classify.ts`) means the file in the directory the + same row or appendix names, found with `git ls-files | grep '/$'`. Search for the quoted code, not the line. +- **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}]' .mdx` prints nothing. Replace a dash with a comma, colon, period, parentheses, or + the word "to" for a range. Box-drawing characters such as `─` (U+2500) and the arrow `→` are not dashes. +- **Frontmatter rule**: `title` is specific and searchable; `description` is 50 to 160 characters (count the text + between the quotes); neither contains a dash; a value that contains `: ` is double-quoted. When this PRD retitles a + page, it also adds `sidebarTitle: ""` so the navigation label stays short. All 21 descriptions already + pass (measured below); none changes. +- **Help sentence**: the exact sentence D3 adds: "Still stuck? Ask on the [Overdeck + Discord](https://discord.gg/ZpHE2ZTv5P) or file a [GitHub Issue](https://github.com/eltmon/overdeck/issues)." +- **Experimental**: a dashboard view hidden unless **Settings → Experimental → Experimental features** is on. The + gated views are listed in `EXPERIMENTAL_TAB_IDS` in `src/dashboard/frontend/src/lib/experimentalFeatures.ts:4-15` + (agents, autopreso, resources, sessions, metrics, costs, health, god-view). Two Anywhere pages mention gated views: + the Costs page's **Machines** tab (`linked-machines`, Appendix C row 14) and the **Health** page (`remote-access`, + Appendix N row 5). Nothing else in the group is experimental. +- **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: .mdx: `; WI-Z1 collects them into the PR body. + +## Background and evidence + +- **Before-state per page** (dash lines counted with the dash-rule grep; description length without quotes; every + description is already dash-free and 50 to 160 characters): + +| Page | Lines | Dash lines | Title | Desc chars | +| --- | --- | --- | --- | --- | +| anywhere | 516 | 0 | "Overdeck Anywhere: plans and pricing" (sidebar "Plans and pricing") | 125 | +| configuration/session-vault | 336 | 2 | Session Vault | 78 | +| configuration/remote-access | 454 | 1 | Remote access | 79 | +| configuration/linked-machines | 716 | 7 | Linked machines | 100 | +| configuration/shared-sessions | 199 | 1 | "Shared sessions" | 87 | +| configuration/triggers | 240 | 0 | Webhook triggers | 110 | +| configuration/tailscale | 169 | 0 | Tailscale | 125 | +| configuration/mcp | 782 | 9 | "MCP server" | 114 | +| configuration/bots | 334 | 8 | "Connect a bot" | 130 | +| configuration/phone | 211 | 0 | Use Overdeck on your phone | 98 | +| configuration/push-notifications | 306 | 5 | "Push notifications" | 152 | +| cli/vault | 232 | 0 | pan vault | 102 | +| cli/pair | 48 | 0 | pan pair | 76 | +| cli/tailscale | 100 | 1 | pan tailscale | 82 | +| cli/account | 139 | 7 | pan account | 77 | +| cli/share | 96 | 0 | pan share and pan join | 59 | +| cli/devices | 49 | 0 | pan devices | 63 | +| cli/machines | 658 | 1 | pan machines | 147 | +| cli/token | 79 | 0 | pan token | 137 | +| cli/mcp | 348 | 0 | pan mcp | 102 | +| cli/triggers | 110 | 0 | pan triggers | 59 | + +- **The headline problem is stale maturity labels.** Most of the group was written before v0.64.0 to v0.74.0 shipped. + Release facts, from `changelog.mdx`: Session Vault and `pan pair`/`pan devices` shipped in v0.64.0; Settings → + Session Vault, Settings → Anywhere (Pair a device, Revoke), Access Tokens and `pan token` in v0.65.0 (2026-10-04); + linked machines, Tailscale setup, the phone web app `/m`, push notifications, webhook triggers (with the inbox) and the + MCP server in v0.73.0 (2026-11-03, `changelog.mdx:496-515`); the native phone apps (TestFlight and Play internal + testing), shared sessions, bot connections, agent MCP tools and the dashboard Account card in v0.74.0 (2026-11-04, + `changelog.mdx:450-457`). The issue comment's known stale item ("Available from the next release" in + `configuration/triggers.mdx`) is Appendix Q row 1: webhook triggers shipped in v0.73.0 (`changelog.mdx:511`). +- **Anchor slug probe.** Four pages link `/configuration/remote-access#find-your-machines-through-overdeck-ai`. Several + research passes guessed that Mintlify drops the dot and proposed `#find-your-machines-through-overdeckai`. The planner + tested it with `npx -y mint@4.3.49 broken-links --check-anchors` on a scratch site that held the heading "Find your + machines through overdeck.ai": the `-overdeck-ai` link passed and the `-overdeckai` link was reported broken. So the + current links are correct (override O1). The same command over the 21 pages on the base printed "success no broken + links found". +- **Validators.** `npx -y mint@4.3.49 validate` and `npx -y mint@4.3.49 broken-links` pass on `main` (recorded in + `.overdeck/context/codebase/concerns.md`, "`npx mint validate` and `npx mint broken-links` pass on `main`"). The same + entry lists what breaks them: a bare `` in prose outside backticks (MDX reads it as a JSX tag), an unquoted + frontmatter `description` containing `: `, an `import ... from "react"` line 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; it prints `docs lint passed (...)` on success. Prices on `anywhere.mdx` are written `$` for that reason; + keep that form in every new price. +- **Headings code depends on.** `src/lib/mcp/connector/connect-output.ts:59` links + `/configuration/bots#no-webrtc-egress`, and the dashboard links `/configuration/session-vault#save-and-sync` + (`src/dashboard/frontend/src/components/Settings/anywhere/__tests__/AnywhereStatusCard.test.tsx:95`). Keep the + headings `### no-webrtc-egress` (bots) and `## Save and sync` (session-vault) unchanged. No row renames either. +- **No overlap.** No open PR touches these 21 files (checked with `gh pr list --state open` on 2026-11-18). The closed + siblings #5472, #5478, #5482 and #5483 already merged. The open siblings #5499, #5502 and #5504 list none of these + pages. + +## Requirements + +- **FR-1**: Every row in the change table of Appendices A to U is applied as written (wording may be adjusted for flow, + the fact may not), except the rows the Overrides section drops or rewrites. An override wins over its appendix row. +- **FR-2**: Every "Missing" bullet tagged `[ADD]` in Appendices A to U is added to its page, as at most two sentences + or one table row, in the section the bullet names (else at the end of the closest related section). A bullet tagged + `[ADD via D3]` is satisfied by the D3 help sentence. A bullet tagged `[SKIP: reason]` is not applied. +- **FR-3**: For any claim on a page that this PRD does not list, the executor applies the residual rule (Common + procedure step 3): verify it against a primary source only if it looks doubtful, fix the page to match the code, and + never change code. +- **FR-4**: Every page in the group satisfies the dash rule. +- **FR-5**: Every page in the group satisfies the frontmatter rule; the 19 pages in the D4 table get the listed `title` + and a `sidebarTitle` holding the old title. +- **FR-6**: Every internal link on every page resolves to an existing page and an existing heading for an anchor, + counting `docs.json` redirects. `npx -y mint@4.3.49 broken-links --check-anchors` reports no broken link. +- **FR-7**: Every page in the group ends with a help path to the Overdeck Discord (https://discord.gg/ZpHE2ZTv5P) and + GitHub Issues (https://github.com/eltmon/overdeck/issues), per D3. +- **FR-8**: The PR body ticks all 21 pages with a one-line note each. It also pastes the clean output of + `npx -y mint@4.3.49 validate`, `npx -y mint@4.3.49 broken-links --check-anchors` and `npm run lint:docs`, and lists + the Follow-ups. +- **NFR-1**: No file outside the 21 pages changes, except the PR body. No code, test, rule, `docs.json`, `CLAUDE.md`, + `README.md`, `docs/*.md` or `changelog.d` change. +- **NFR-2**: No heading text changes, so `#anchor` links keep working, with one exception: Appendix T row 2 renames + `## Before you start` on `phone.mdx` to `## Before you start (browser phone view)` (no page or code links its anchor + on the base). A section is deleted only where a row says so (Appendix N row 14 deletes `## What comes next` on + `remote-access`, which no page links to). +- **NFR-3**: Prose follows the repo writing rules: plain, active, short sentences; no em or en dashes; no hype. Issue + and PR references stay as markdown links. + +## Decisions + +- **D1 (scope)**: the 21 pages listed in the issue are exactly the two Anywhere navigation groups on the base. Nothing + is added or removed. +- **D2 (phone.mdx)**: the issue says to audit `configuration/phone.mdx` after #5472 merges. It merged as `94f8a78502d`, + and its store-status sentence (TestFlight and Play internal testing, not the public stores) is still correct + (`changelog.mdx:455`; `apps/mobile/RELEASE.md:186` "TestFlight internal testing works today"). Appendix T applies on + top of it. +- **D3 (help links)**: every page gets the help sentence (Glossary), because the issue asks for help links "where a page + talks about getting help", and on Anywhere pages setup failures are the common case. Placement rule: if the page has a + `## Troubleshooting` or `## Errors` section, append the sentence as its last paragraph (for a bullet list, as a final + paragraph after the list). Otherwise add a final section `## Get help` that holds only the sentence. One exception: + `remote-access.mdx` puts `## Get help` where `## What comes next` was (Appendix N row 14). `anywhere.mdx` gets only + the sentence in its `## Get help` section, with no pricing-feedback link: #4294 (billing) is closed. Where an appendix row words the help line + differently, use the Glossary sentence instead, so the group reads the same. +- **D4 (titles)**: retitle 19 pages; `anywhere` and `configuration/phone` keep their titles. Quote every new value and + add `sidebarTitle` with the old title: + +| Page | New `title` | `sidebarTitle` | +| --- | --- | --- | +| configuration/session-vault | "Session Vault: encrypted conversation backup and cross-machine resume" | "Session Vault" | +| configuration/remote-access | "Remote access: pair devices, scoped tokens and network exposure" | "Remote access" | +| configuration/linked-machines | "Linked machines: pair Overdeck machines and work across them" | "Linked machines" | +| configuration/shared-sessions | "Shared sessions: share a live conversation by link" | "Shared sessions" | +| configuration/triggers | "Webhook triggers: message or start conversations from GitHub, Stripe or CI" | "Webhook triggers" | +| configuration/tailscale | "Tailscale: reach your dashboard over HTTPS from your devices" | "Tailscale" | +| configuration/mcp | "Overdeck MCP server: tools, scopes and agent tokens" | "MCP server" | +| configuration/bots | "Connect a bot: give Hermes, OpenClaw or Grok scoped MCP access" | "Connect a bot" | +| configuration/push-notifications | "Push notifications: get alerted when an agent needs you" | "Push notifications" | +| cli/vault | "pan vault: back up and resume agent conversations across machines" | "pan vault" | +| cli/pair | "pan pair: pair a device with your dashboard" | "pan pair" | +| cli/tailscale | "pan tailscale: check and set up Tailscale access from the terminal" | "pan tailscale" | +| cli/account | "pan account: sign this machine in to overdeck.ai" | "pan account" | +| cli/share | "pan share and pan join: share a live conversation by link" | "pan share and pan join" | +| cli/devices | "pan devices: list and revoke paired devices" | "pan devices" | +| cli/machines | "pan machines: link, list and update your machines" | "pan machines" | +| cli/token | "pan token: create, list and revoke scoped API tokens" | "pan token" | +| cli/mcp | "pan mcp: serve MCP, manage OAuth sign-ins and run the connector" | "pan mcp" | +| cli/triggers | "pan triggers: create and manage webhook triggers" | "pan triggers" | + + Body `# ` H1 lines that repeat the old title (for example `# Session Vault`, `# Linked machines`, + `# pan account`) stay as they are (NFR-2); the duplicate-H1 warnings they cause are pre-existing and go to Follow-ups. +- **D5 (removed or unshipped features)**: delete a claim about a removed feature; do not keep it with a "removed" note. + A feature that is planned but not built (the hosted vault, `pan vault migrate`, the extra-storage add-on, the one-time + 50 GB top-up) is labeled "planned", as the appendix rows say. +- **D6 (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. Never describe intended behavior as current. Examples: `pan triggers remove` leaves the trigger's + overdeck.ai inbox in place (Appendix Q row 10, R row 8); `pan machines add-ssh` reports an SSH login refusal as a + token rejection (Appendix D row 2). +- **D7 (billing and prices)**: the repo cannot show whether production billing is on: Creem billing is built + (`services/account/src/billing/`) and stays off until the operator sets `CREEM_*` values + (`services/account/wrangler.jsonc:30` "Until all are set, billing stays off."), and that configuration is not in the + repo. So the page asserts neither "on sale now" nor "billing is off". It uses the account page's own public wording, + "Paid plans are invite-only for now." (`services/account/src/account-page/page.ts:23` `INVITE_ONLY_PAID_MESSAGE`). + Override O2 rewrites the rows that depend on this. Prices, plan limits, Creem fee figures and competitor figures + that the rows do not change stay as they are. The listed prices match `services/account/src/billing/catalog.ts:30-46`. + Confirming production billing state is a Follow-up. +- **D8 (one PR)**: one PR for the issue. All items commit to `feature/pan-5500`. +- **D9 (Missing bullets)**: FR-2 applies. The planner tagged every bullet `[ADD]`, `[ADD via D3]` or `[SKIP: reason]`; + skipped bullets are optional detail, internal implementation detail, or already covered by a row. + +## Overrides to the appendix rows (already applied in the appendices) + +The rows below are already patched in Appendices A, C and D. This section records what the planner changed and why, +so a reviewer can see the difference from the research passes. + +- **O1 (anchor slug, drop rows)**: the link `/configuration/remote-access#find-your-machines-through-overdeck-ai` is + correct (probe in Background). Appendix C row 16 and Appendix D row 7 are marked dropped. Appendix A rows 15 and 17 + apply only the `next release` → `v0.73.0` change. The "Links" notes now say OK, and the Follow-ups that called the + anchor broken are removed. A Missing bullet in Appendix C now links `/cli/machines#through-the-overdeck-ai-directory`. +- **O2 (billing wording, D7)**: these Appendix A rows were rewritten as follows: + - Row 1: in the replacement Note, replace the two sentences "Nothing on this page can be bought yet. Billing + ([PAN-4294](https://github.com/eltmon/overdeck/issues/4294)) is built into the account service and stays off until + it is turned on there." with "Paid plans are invite-only for now." + - Row 5: use this replacement instead: "**Availability:** paid plans are invite-only for now. When the account page's + Billing section offers the paid tiers (Anywhere, the founding price and the relay add-on), invited accounts + subscribe there, on the [account page](https://account.overdeck.ai/account). Creem handles the payment as merchant + of record; Overdeck never sees your card details. Sign-up is invite-only." + - Row 6: in the replacement, change "Once billing is on, it also lets you" to "When billing is available, it also + lets you". + - Row 14: use this replacement instead: "Paid plans are sold through [Creem](https://www.creem.io) as merchant of + record." + - Row 44: in the bold line, replace "Billing is built and not yet on; the hosted vault is planned." with "Paid plans + are invite-only for now; the hosted vault is planned."; in the paragraph, replace "Billing through Creem is built + into the account service and stays off until it is turned on there." with "Paid plans are invite-only for now." +- **O3 (evidence corrections, no text change)**: pair row 3 evidence is `src/cli/commands/pairing-link.ts:16`; share + rows 3 to 5 evidence is `src/cli/commands/sharing/join.ts:146-152` (and the same file for rows 4 and 5); triggers row + 5 evidence is `src/lib/triggers/deliver.ts` near lines 39 and 186-207. +- **O4 (help wording)**: wherever an appendix row or Missing bullet adds a help line in its own words (for example + Appendix C row 13, D row 15), use the Glossary help sentence and the D3 placement instead. +- **O5 (free-plan sentence)**: Appendix A row 3 no longer says "The free account applies to a former subscriber whose + invite has expired." The code supports it (`services/account/src/entitlement.ts:72-74`), but no admin path sets a + `free` grant, so whether the published free tier is reachable is an open product question. It is a Follow-up. +- **O6 (known limitations, new rows)**: `changelog.mdx:515` names three parts of Anywhere not verified end to end. + Appendix L row 8 covers **Set up Tailscale**. The planner added Appendix C row 17 and Appendix D row 16 (`connect` as + a systemd service on a fresh VPS, #4863 still open) and Appendix C row 18 (the relay's TURN-over-TCP fallback). + +## Repo rules that apply + +- Work only inside `workspaces/feature-pan-5500` on branch `feature/pan-5500`; never `git checkout` another branch; + never `git stash`. +- One commit per item with an `Item: <item-id>` trailer and the AC trailers, plus the `PR-note:` line. `pan task done` + checks the trailer on the pushed commit, so push before calling it. +- Docs-only: do not run the full `npm test`. The checks are the dash grep, `npm run lint:docs`, and (in WI-Z1) + `npx -y mint@4.3.49 validate` and `npx -y mint@4.3.49 broken-links --check-anchors`. +- Never send an HTTP request and never run a `pan` command other than `--help` while verifying a claim. +- Issue and PR references in prose stay as markdown links (`[#4512](https://github.com/eltmon/overdeck/issues/4512)`). +- No em or en dashes in anything written, including commit messages and the PR body. + +## 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 with the evidence in the commit + message (`pan task block` with the reason). Never write a claim the code contradicts to satisfy a row. Figures the + code cannot confirm (competitor prices, storage costs, measured latencies) stay as they are unless a row changes them. +1. **Apply the change table** of the page's appendix, with the Overrides. 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 (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. Literal `|` inside a table-cell replacement is written as a real pipe in the page table (the + appendix escapes it as `\|` or `|`). +2. **Add the Missing bullets** (FR-2, D9). +3. **Residual rule.** Read the whole page once. For a claim the appendix 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 them. +4. **Dashes.** Remove every en and em dash in the page or in the item's line range (dash rule), in the same commit. +5. **Frontmatter.** Apply the D4 title change with `sidebarTitle` if the page is in the D4 table; confirm the + description is still 50 to 160 characters and dash-free. +6. **Help link.** Add the help sentence per D3. +7. **Links.** For each internal link, `ls <path>.mdx` (and `grep -n "^#.*<heading words>"` for an anchor), counting + `docs.json` redirects. Fix any that fail. `npx -y mint@4.3.49 broken-links --check-anchors --files <page>.mdx` is + the authoritative check. +8. **MDX safety.** Keep any new `<word>` placeholder inside backticks; write a new `$` price as `$`. +9. **Commit** with `Item: <id>`, its AC trailers and `PR-note: <page>.mdx: <one line>`; push; `pan task done`. + +## Work items + +Each page item below names its appendix and the rows that must land. Items in the same file are chained by `blocks` +edges (WI-A1 → A2 → A3, WI-C1 → C2, WI-G1 → G2); all other page items are independent and may run in parallel. WI-Z1 +runs last. Each split item removes the dashes inside its own line range; the last item of a split page confirms the +whole file is clean and applies the frontmatter and help link. + +### WI-A1 to WI-A3: `anywhere.mdx` (516 lines, Appendix A, 48 rows, three section items) + +- **WI-A1**: lines 1 to 173 (Note, intro, Getting started, Plans, When a subscription ends, three-card group, What + stays free). Appendix A rows 1 to 14 with O2. Must land: the Note no longer says "next release" and names v0.64.0, + v0.73.0 and v0.74.0; invited accounts get the **Tester** plan (rows 1, 3, 7, with O5); "Paid plans are invite-only for now" + replaces every "on sale" and "we plan to sell" claim (O2); the command palette list includes **Connect a bot** (row + 2); the hosted vault, `pan vault migrate`, extra storage and the one-time 50 GB top-up are labeled planned (rows 4, 9 + to 12); deleting an account cancels any subscription (row 13). +- **WI-A2**: lines 175 to 321 (What has shipped table, Roadmap). Appendix A rows 15 to 44 with O1 and O2. Must land: + `grep -c 'next release' anywhere.mdx` returns 0 after this item; the shipped table gains the native phone apps row + (row 29) and the account page row (row 36); the MCP row names `grok` (row 32). +- **WI-A3**: lines 323 to 516 (How we arrived at these prices, What we still need to learn) plus page-wide checks. + Appendix A rows 45 to 48, the `## Get help` section (D3, the sentence only), the `[ADD]` Missing bullets, the dash + rule over the whole file and the link check. The title stays. + +### WI-B1: `cli/account.mdx` (Appendix B, 7 rows) + +Must land: the base-URL paragraph allows `http` on `localhost`, `127.0.0.1` or `[::1]` (row 2); the two missing +failure messages (row 3); the `--json` signed-out and failure output (row 5); the token file's `v` field (row 7); the +Missing line pointing to the account page for the plan; D4 title; help section; 7 dash lines removed. + +### WI-C1 and WI-C2: `configuration/linked-machines.mdx` (716 lines, Appendix C, 17 rows after O1 and O6) + +- **WI-C1**: lines 1 to 425 (intro through Remote control). Appendix C rows 1 to 7, 17 and 18: D4 title (row 1); the agent's link + request shows in **Needs you** and the conversation, not "the Decisions panel" (row 2); `test-ssh` runs steps 1 and + 2 (row 3); `--message` needs `--project` (row 4); the fingerprint shows in `pan machines list` and on Inbound rows + (row 5); the relay plan is invite-only (row 6); the remote-control exception for work this machine started (row 7); + the two maturity notes from `changelog.mdx:515` (rows 17 and 18, O6). +- **WI-C2**: lines 426 to 716 plus page-wide checks. Appendix C rows 8 to 15 and the Missing bullets: Grok Build and Pi + in the fleet-versions list and table (rows 8 to 10); `pan start --machine fly` starts a work agent on Fly, and only + `pan worker run` and `pan lane start` refuse it (row 11); only `pan lane start` prints "Passed over" (row 12); the + Costs page is experimental (row 14); "Settings → Anywhere → Machines" (row 15); the help sentence at the end of + `## Troubleshooting` (row 13 via O4); dash rule over the whole file (7 lines). + +### WI-D1: `cli/machines.mdx` (Appendix D, 15 rows after O1 and O6) + +Must land: the `connect` maturity note for #4863 (row 16, O6); the `auth-failed` remedy names the current mislabelled error (row 2, D6); the `fly-token-rejected` error row +(row 4); after a reboot a linked machine retries with a back-off of at most about 45 seconds and shows online within +about a minute (rows 12 and 13); **Update all** covers npm and Homebrew installs and Pi and Grok Build (row 10); the +watchdog restart rule (row 14); `directory` on a signed-out machine and `approve` without a terminal (rows 8, 9); the +`[ADD]` Missing bullets; D4 title; help sentence in `### Troubleshooting` (row 15 via O4); 1 dash line removed. + +### WI-E1: `cli/pair.mdx` (Appendix E, 4 rows) + +Must land: "Pair a device is in the next release (v0.65.0)" becomes the Settings → Anywhere → **Pair a device** +sentence (row 2); the loopback warning text (row 3, evidence per O3); the corrected token-rejection error text (row 4); +the `[ADD]` Missing bullets (other errors, the same link also links a machine, fragment-only credential, `--label` +limit); D4 title; help sentence in `## Errors`. + +### WI-F1: `cli/devices.mdx` (Appendix F, 5 rows) + +Must land: the stale "(next release, v0.65.0)" note is gone (row 2); `list` shows paired browser devices and paired +phones (row 3); the `--json` entry fields including `kind` (row 4); a phone cannot be revoked while the dashboard is +down (row 5); the `[ADD]` Missing bullets; D4 title; `## Get help`. + +### WI-G1 and WI-G2: `configuration/mcp.mdx` (782 lines, Appendix G, 24 rows, two section items) + +The appendix's research context lists the harness evidence: `grok` gets the `overdeck` MCP server because +`GROK_CAPABILITIES` spreads `OPENCODE_CAPABILITIES` (`packages/contracts/src/harness-capabilities.ts:281-282`), and +`pi` does not, because `PI_CAPABILITIES` spreads `OHMYPI_CAPABILITIES` (`overdeckMcp: false`, same file :155, :165-166). + +- **WI-G1**: lines 1 to 460. Appendix G rows 1 to 12: `grok` added to the harness list at line 17 (row 2); the + `schedule_message` "within a minute" fix (row 4); the missing tool parameters (rows 3, 5 to 8); agent-only tools that + call lane and worker routes (row 9); cross-reference links (rows 1, 10 to 12). +- **WI-G2**: lines 461 to 782 plus page-wide checks. Appendix G rows 13 to 24 and the Missing bullets: `grok` in every + provisioned-harness list and `pi` in every not-provisioned list (rows 13 to 20); the `semgrep` server in the + precedence order (row 21); the `operate` scope list (row 22); "the eight answer tools" (row 23); `machine` on + `start_issue`, `delegate_task` and `lane_start` (row 24); `## Get help` after `## Fleet reach`; D4 title; dash rule + over the whole file (9 lines). + +### WI-H1: `cli/mcp.mdx` (Appendix H, 7 rows) + +Must land: the refusal row covers every non-API token kind (row 1); the URL variables apply to `login` and `connect` +(rows 2, 3); the full Hermes key `plugins.entries.overdeck.mcp_allowlist` (row 4); the relay-down case for +`no-webrtc-egress` with its link (row 7); the `oauth` error-answer sentence (Missing); D4 title; `## Get help`. + +### WI-I1: `cli/token.mdx` (Appendix I, 3 rows) + +Must land: `list` shows only API tokens (row 1); the `revoke` refusal from a dashboard not started by `pan up` (row 2); +the internal function name `pruneEndedAccessTokens` is gone (row 3); D4 title; `## Get help`. The `create` output +sample is optional (skip). + +### WI-J1: `configuration/session-vault.mdx` (Appendix J, 13 rows) + +Must land: every "next release (v0.65.0)" and "planned (PAN-4446)" note is gone and the intro says setup, join and +unlock also work from the dashboard (rows 1, 4, 7, 8); the vault handles Claude Code and Codex transcripts only (rows +2, 3, 6); `pan vault exclude <workspace path>` with no `--path` flag (row 5); the rotate-key passphrase flags turn +passphrase unlock on (rows 9, 10); the Continue-here refusal for an unregistered dirty checkout (row 11); the config +keys with defaults (row 12); D4 title (row 13); the `[ADD]` Missing bullets; `## Get help`; 2 dash lines removed. +Keep the heading `## Save and sync` (the dashboard links to it). + +### WI-K1: `cli/vault.mdx` (Appendix K, 6 rows) + +Must land: the "In the dashboard" paragraph describes the shipped dashboard features (row 1); `--harness` takes +`claude-code` or `codex` (row 2); `save --all` scope (row 3); exclusion tombstones only with `--session` (row 4); the +`status` fields (row 5); D4 title (row 6); the Missing flag-combination notes; `## Get help`. + +### WI-L1: `configuration/tailscale.mdx` (Appendix L, 9 rows) + +Must land: the Ready step no longer claims to list the other machines (row 1); **Sign in** then **Open sign-in** (row +2b); the dashboard's **Try signing in again** button (row 3); Windows shows the `winget` command and does not run it +(row 4); the stale "Linking machines arrives with machine links" paragraph is replaced (row 5); "Overdeck stores +nothing about Tailscale" is corrected (row 7); the maturity Note that **Set up Tailscale** was not run end to end on a +real machine before release (row 8, `changelog.mdx:515`); D4 title (row 6); `## Get help`. + +### WI-M1: `cli/tailscale.mdx` (Appendix M, 3 rows) + +Must land: the not-installed message applies without `--json` (row 1); the 8-step limit exit case (row 2); the three +missing error messages (Missing); D4 title (row 3); the help sentence at the end of `## Errors`; 1 dash line removed. + +### WI-N1: `configuration/remote-access.mdx` (Appendix N, 14 rows) + +Must land: the opening `<Note>` about the v0.65.0 "next release" is deleted (row 1); the `GET /api/environment` sample +matches the current descriptor (row 2); the warning text (row 3); advertised endpoints are for linked machines, not +browser origins (row 4); the experimental **Health** page (row 5); Session Vault setup and unlock from the dashboard +(rows 6, 7); `GET /api/anywhere/status` needs `admin` for a scoped token (row 8); the `operate` row and the missing +`read:costs`, `read:settings` and `forward` scope rows (rows 9, 10); the Account card relay line and two-click sign-in +(rows 11, 12); the relay plan is invite-only (row 13); `## What comes next` deleted and `## Get help` in its place (row +14); D4 title; the `[ADD]` Missing bullets; 1 dash line removed. Keep every heading other pages link to: +`## Find your machines through overdeck.ai`, `### From the desktop app`, `## List and revoke devices`, +`## Local reverse proxies: \`require_token_mint\``, `## Open one conversation on another screen`, +`## Scoped API tokens`, `## What the LAN can reach`. + +### WI-O1: `configuration/shared-sessions.mdx` (Appendix O, 5 rows) + +Must land: "In this release" becomes "Shared sessions shipped in v0.74.0" (row 1); only Claude Code conversations +stream, and other harnesses show the transcript-unavailable text (row 2); browser viewers get no Terminal view (rows 3, +5); the ⋮ menu is in the conversation header (row 4); the Missing bullets (host needs `pan up`, the share record file); +D4 title; `## Get help`; 1 dash line removed. + +### WI-P1: `cli/share.mdx` (Appendix P, 5 rows) + +Must land: the exact dashboard-not-running message (row 1); the `Cannot share <name>: <reason>` line (row 2); the +opened URL is `<dashboard URL>/#/shared/<CODE>` and is printed (row 3); `--no-open` output (row 4); a browser on this +machine signs itself in even with `require_token_mint` on (row 5); the bad-target error (Missing); D4 title; +`## Get help`. The optional sign-in lines are skipped. + +### WI-Q1: `configuration/triggers.mdx` (Appendix Q, 11 rows) + +Must land: "Available from the next release." becomes "Added in v0.73.0." (row 1; the issue comment's known stale item); +model, harness and effort only through `pan triggers add` (row 2); the trigger name rule (row 3); **Set signing secret** +in the dashboard (row 4); rate limits count refused events (row 5, evidence per O3); Funnel also reaches the Public MCP +paths while Public MCP is on (row 6); the inbox checkbox label and conditions (row 7); the Funnel URL with an inbox +(row 8); the inbox limits (row 9); `pan triggers remove` leaves the inbox, only the dashboard's Remove deletes it (row +10, D6); the connect Worker's log contents (row 11); the `[ADD]` Missing bullets; D4 title; `## Get help`. + +### WI-R1: `cli/triggers.mdx` (Appendix R, 9 rows) + +Must land: "Available from the next release." becomes "Added in v0.73.0." (row 1); `add --inbox` needs the dashboard +(row 2); the `--inbox --json` output shape (row 3); the Stripe reminder line (row 4); the dashboard-not-running inbox +case (row 5); `-` for `none` triggers (row 6); the empty-list message without broken nested backticks (row 7, using the +"CLI row 7 replacement" text in the appendix); `remove` does not delete an inbox (row 8); the secret length rule (row +9); the name rule (Missing); D4 title; `## Get help`. + +### WI-S1: `configuration/bots.mdx` (Appendix S, 11 rows) + +Must land: the default access names Read state, Read conversations and Send messages (row 1); only a browser on this +machine manages bots (row 2); `read:events` among the scopes a bot never gets (row 3); Public MCP must be on first (row +4); "the HTTP config above" (row 5); the `connect` row in the command table (row 6, using the "Bots row 6 insert" text); +five connector files (rows 7, 8); only the Hermes and OpenClaw READMEs have a Tailscale route section (row 9); the +`#tailscale-instead-of-the-connector` link (row 10); the `TURN relay` doctor row appears only with the relay plan (row +11); the `[ADD]` Missing bullets, including the plain statement that there is no Slack, Discord or Telegram +integration; D4 title; the help sentence at the end of `## Troubleshooting`; 8 dash lines removed. Keep the heading +`### no-webrtc-egress`. + +### WI-T1: `configuration/phone.mdx` (Appendix T, 12 rows) + +Must land: the intro describes both ways to use a phone (row 1); `## Before you start (browser phone view)` (row 2; +this is a heading text change that the row requires. Run `grep -rn "phone#before-you-start" --include=*.mdx .` first +and repoint any hit to `#before-you-start-browser-phone-view`); **Set up Tailscale** for HTTPS (row 3); token sign-in +turns on by itself (row 4); the Overdeck app step 1 (row 5); the banner below the header (rows 6, 9); the issue row and +agent states (rows 7, 8); the two "as soon as the machine runs the new version" notes removed (rows 10, 11); removing a +phone from the app tab (row 12); the `[ADD]` Missing bullets; `## Get help`. The title stays. The store-status +sentence from #5472 stays. + +### WI-U1: `configuration/push-notifications.mdx` (Appendix U, 12 rows) + +Must land: D4 title (row 1); the disk thresholds and their keys (row 2); restart replay rules (row 3); "Until the Set up +Tailscale action ships" and "Once the phone shell at /m ships" are gone (rows 4, 6); pairing goes through **Set up a +phone** and the iPhone order (row 5); the config file is `~/.overdeck/config.yaml` (row 7); `enabled: false` still lets +**Send test** through (row 8); `includePreview` also reaches the Overdeck app (row 9); disk alerts send their own title +(row 10); Overdeck never stops sending after failures (rows 11, 12); the `[ADD]` Missing bullets; the help sentence +at the end of `## Troubleshooting`; 5 dash lines removed. + +### WI-Z1: validate the group and write the PR body + +Runs after every page item. + +1. Dash loop prints nothing: + `for f in anywhere configuration/{session-vault,remote-access,linked-machines,shared-sessions,triggers,tailscale,mcp,bots,phone,push-notifications} cli/{vault,pair,tailscale,account,share,devices,machines,token,mcp,triggers}; do grep -HnP '[\x{2013}\x{2014}]' "$f.mdx"; done` +2. `for f in <the 21 pages>; do tr '\n' ' ' < "$f" | grep -c 'next release'; done` prints 0 for each page (the `tr` + form catches text that wraps across lines), and + `grep -l 'Available from the next release' configuration/triggers.mdx cli/triggers.mdx` prints nothing. +3. Frontmatter check: each page's `description` is 50 to 160 characters, and each of the 19 D4 pages has the new + `title` and a `sidebarTitle`. +4. Help check: `grep -L 'discord.gg/ZpHE2ZTv5P' <the 21 pages>` prints nothing. +5. `npm run lint:docs` exits 0. +6. `npx -y mint@4.3.49 validate` and `npx -y mint@4.3.49 broken-links --check-anchors` (run from the repo root; `mint` + is not a repo dependency, so `npx` downloads it; 4.3.49 is the version PAN-5472, PAN-5501 and PAN-5503 validated with) + report success. 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, do not fix it: note it under Follow-ups and confirm the same failure exists on `origin/main`. The + `duplicate-h1` warnings are pre-existing and are listed as a Follow-up, not fixed. If `npx` cannot download the CLI + (no network), record the exact error in the commit-message draft instead of a clean result. +7. Write the PR body draft into this item's commit message, in the body 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 four parts: + `## Summary`; `## Pages` with 21 ticked lines `- [x] <page>.mdx: <PR note>`, collected by + `git log origin/main..HEAD --format=%B | grep '^PR-note:'`; `## Validation` with the output of steps 1, 5 and 6; and + `## Follow-ups`, holding the list below plus every "Follow-ups" bullet in Appendices A to U that O1 does not cancel + plus anything found during the work. The PR does not exist yet: `pan done` opens it after every item is done, with a + body holding only the acceptance-criteria checklist. +8. **Post-step after `pan done`** (not an item): append the draft to the PR body with + `gh pr view <pr> --json body -q .body > <scratch>/body.md`, add the draft from the validation commit message, then + `gh pr edit <pr> --body-file <scratch>/body.md`. PR #5569 (PAN-5503) and #5573 (PAN-5501) used this path and their + bodies carry the `## Pages` and `## Validation` sections. The review role checks the PR body for the 21 page lines. + +### Documentation work item + +This issue is documentation: every page item edits one of the 21 Mintlify pages, and WI-Z1 records the result. No other +documentation (`docs/*.md`, `CLAUDE.md`, rules, `README.md`) changes. The inconsistencies found there are Follow-ups. + +## Follow-ups found during planning (list in the PR body, do not fix) + +In addition to the per-appendix Follow-ups: + +- Confirm whether production billing is on (D7). If it is, `anywhere.mdx` can say the paid tiers are on sale to + invited accounts, and `.pan/notes/held-changelog/pan-4294.md` can move to `changelog.d/`. +- The free plan may be unreachable for new invitees: invites default to `tester` (`services/account/migrations/0001_init.sql:15`) + and no admin path sets a `free` grant; a lapsed subscriber with an expired invite sees "Tester" on the account page but + gets free limits in the directory (Appendix A Follow-ups 7 and 8). Decide what the published free tier means (O5). +- The founding-price window says "90 days after the Anywhere release"; the real end is the operator's + `FOUNDING_ENDS_AT` (`services/account/src/billing/catalog.ts:137-141`). Decide whether to reword it. +- The dashboard Account card cannot label a paid plan: `AccountPlan` is `'free' | 'tester'` + (`src/lib/account/client.ts:41`). +- The account page tells lapsed users to run `pan vault migrate`, which does not exist + (`services/account/src/billing/page-sections.ts:48`). +- The **Add 50 GB** link opens `https://overdeck.ai/anywhere` although no top-up product exists + (`src/dashboard/frontend/src/components/Settings/anywhere/AnywhereStatusCard.tsx:57`). +- `pan triggers remove` leaves the trigger's overdeck.ai inbox accepting events; only the dashboard route deletes it + (`src/dashboard/server/routes/triggers.ts:148`). +- `pan machines add-ssh` reports an SSH `auth-failed` (HTTP 401) as an internal-token rejection + (`src/cli/commands/machines-call.ts:29`). +- `TailscalePeersPanel.tsx:75` still renders "Linking machines arrives with machine links (#4645)." +- The phone setup dialog's App Store button opens `overdeck.ai/configuration/phone-app`, which is not a page or a + redirect. +- Pages that repeat their frontmatter title as a body `# H1` cause `duplicate-h1` warnings (`session-vault`, + `tailscale`, `cli/tailscale`, `linked-machines`, and others); a docs-wide cleanup is out of scope. +- `configuration/linked-machines.mdx` has two `### Gauntlet lanes` headings (about lines 271 and 613). + +## Acceptance criteria (map 1:1 to work items) + +Every page item: the change-table rows are applied (spot-checked by grepping two removed anchors and two added +phrases), the dash grep prints nothing for the item's range, the frontmatter passes, the help sentence is present (last +item of a page), and the commit carries a `PR-note:` line. The specific checks per item are in the xBRIEF. WI-Z1: the +dash loop, the "next release" grep and the help grep print nothing, lint and both Mintlify commands pass, and the PR body +draft has 21 ticked page lines. + +## Non-goals + +- No code, test, rule, `docs.json`, `CLAUDE.md`, `README.md`, `docs/*.md` or `changelog.d` change. Code bugs become + Follow-ups. +- No page outside the two Anywhere navigation groups. +- No new pages, no navigation changes, no file renames or slug changes. +- No heading renames, except the one Appendix T row 2 requires on `phone.mdx`; deleting a heading only where a row says + so (`## What comes next` on `remote-access.mdx`). +- No screenshots or images added or replaced. +- No changes to prices, plan limits, fee tables or competitor figures beyond the listed rows (D7). +- No claim that production billing is on or off (D7). + +## 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`: + +- **Billing state (D7)**: the repo cannot show whether billing is live, so the page uses the account page's own + "Paid plans are invite-only for now." wording and asserts neither state. +- **Anchor slug (O1)**: probed with `mint broken-links --check-anchors`; the existing `-overdeck-ai` anchors are correct, + so the rows that changed them are dropped. +- **Help links (D3)**: every page gets the same help sentence, in its troubleshooting or errors section or a final + `## Get help`. +- **Titles (D4)**: 19 generic titles get specific ones with a `sidebarTitle` keeping the short nav label. +- **Missing bullets (D9)**: the planner tagged each bullet `[ADD]` or `[SKIP: reason]`; `[ADD]` ones are added briefly. +- **Plan size**: one item per page, with three section items for `anywhere.mdx`, two for `linked-machines.mdx` and two + for `mcp.mdx`, plus one validation item. The plan sets `sizeJustification` because each page counts as its own + subsystem in the finalize lint, while the work is one docs group. + +## Appendices: per-page findings (research passes, base 62f98b27ac6) + +Each appendix holds one page's section map, the suggested title (D4 is authoritative where they differ), the change +table, the Missing bullets, the link check and the Follow-ups. The research passes' "Verified, keep" lists are omitted: +those claims were checked and need no change. The Overrides section above records the planner's changes, which are already applied here. Rows that cite "the +brief" refer to the research instructions, which this PRD replaces. + +### Appendix A: `anywhere.mdx` + +#### Research context + +Key context for the implementer (read once): + +- Every "next release" on anywhere.mdx is stale. The Anywhere release was **v0.73.0** (2026-11-03, changelog.mdx:496-515). Native phone apps, shared sessions, bots, agent MCP tools and the dashboard Account card came in **v0.74.0** (2026-11-04, changelog.mdx:450-457). +- Billing (PAN-4294) is **built but not on**. The code merged in 87c381fb8af (first tagged v0.88.0). It stays off until the operator sets `CREEM_API_KEY`, `CREEM_WEBHOOK_SECRET`, `CREEM_PRODUCTS` (`services/account/src/billing/catalog.ts:125-132`, `services/account/wrangler.jsonc:30` "Until all are set, billing stays off."). Commit cbb8ebefb9e held the changelog entry "until the account Workers are deployed" (`.pan/notes/held-changelog/pan-4294.md`). While billing is off, the account page's Billing section reads "Billing is not available yet. Paid plans are invite-only for now." (`services/account/src/account-page/page.ts:26,131-132`). +- Invited accounts are **Tester** accounts, not free accounts. Adding a grant never sets `entitlement` (`services/account/src/grants.ts:86`), and the column defaults to `'tester'` (`services/account/migrations/0001_init.sql:15`; `services/account/src/devices.ts:163` `entitlement: row.grant_entitlement ?? 'tester'`). Tester means no machine limit, the relay, the inbox and a 5 GiB cap (`services/account/src/entitlement.ts:12,50-52`). Nothing in `services/` writes `entitlement = 'free'`. So the free plan applies only to an account with an expired invite after its subscription lapsed (`entitlement.ts:72-74`). +- Prices in `$` below are written `$`, as the page does. + +Section map: frontmatter 1-5; Note 7-15; intro and CardGroup 17-37; `## Getting started` 39-55; `## Plans` 57-155 (`### When a subscription ends` 118-139, three-card group 140-155); `## What stays free and open source` 157-173; `## What has shipped` 175-210; `## Roadmap` 212-321; `## How we arrived at these prices` 323-502 (accordions 1-11); `## What we still need to learn` 504-516. +Suggested title: keep ("Overdeck Anywhere: plans and pricing"; sidebarTitle "Plans and pricing") +Help section: no + +#### Change table + +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 10 | "notifications, webhook triggers and the MCP server ship in the next release" | Replace the whole Note body (lines 8-14) with: "Everything Anywhere does on your own machines is free and open source. Session Vault and device pairing shipped in v0.64.0. Linked machines, Tailscale setup, the phone web app, push notifications, webhook triggers and the MCP server shipped in v0.73.0. The native phone apps (in TestFlight and Play internal testing), shared sessions and bot connections followed in v0.74.0. overdeck.ai accounts are invite-only for now, and invited accounts get the Tester plan: no machine limit, with the relay and the webhook inbox included. Paid plans are invite-only for now. We publish the prices now, with the reasoning, so you can see how we got there and tell us where we are wrong." | changelog.mdx:500-515 (v0.73.0 linked machines, Tailscale, phone app `/m`, push, triggers, MCP server); changelog.mdx:455 (v0.74.0) "The apps are in TestFlight and Play internal testing now"; `wrangler.jsonc:30` "Until all are set, billing stays off."; `grants.ts:86` + `0001_init.sql:15` `entitlement TEXT NOT NULL DEFAULT 'tester'`; `entitlement.ts:50-52` testerEntitlement `maxDevices: null, relay: true, inbox: true` | +| 2 | 47 | "**Set up Tailscale** open the same dialogs as the Settings buttons" | Replace lines 45-49 with: "The command palette (Cmd/Ctrl+K) has an **Anywhere** group. **Link a machine**, **Add a Fly machine**, **Add an SSH machine**, **Set up a phone**, **Pair a device**, **Set up Tailscale** and **Connect a bot** open the same dialogs as the Settings buttons, over the page you are on. **Open Anywhere settings** goes to the section. **Set up Tailscale** works only in a browser on this machine." | `src/dashboard/frontend/src/components/palette-anywhere-actions.ts:71-78` `label: 'Connect a bot'`; :93-94 `'Open Anywhere settings'`; `AnywhereDialogHost.tsx:38` "Tailscale can be set up only from a browser on this machine." | +| 3 | 77 | "- Invite-only for now" | "- Invite-only for now. Invited accounts get the Tester plan instead (no machine limit, with the relay and the webhook inbox)." | `0001_init.sql:15` default `'tester'`; `grants.ts:86` INSERT sets no entitlement; `entitlement.ts:72-74` (a `'free'` grant, else any grant → tester, else a subscriber row → free) | +| 4 | 99 | "**Relay add-on:** +$3 a month" | Replace lines 99-103 with: "**Relay add-on:** +$3 a month or +$30 a year on the Anywhere subscription ($13 a month or $126 a year in all, or $90 a year at the founding price), billed in the same charge. When two of your machines find no direct path, the relay connects them, still end-to-end encrypted. It includes 50 GB of relay traffic a month. At 50 GB the relay stops until the next month. An extra 50 GB for a one-time $3 is planned but cannot be bought yet. There is no per-gigabyte billing. The relay also carries an [Overdeck connector](/configuration/bots#run-the-overdeck-connector)'s traffic when a bot has no direct path to your machine; it relays only encrypted bytes." | `billing/catalog.ts:30-43` priceText `'$13 a month with the relay'`, `'$126 a year with the relay'`, `'$90 a year with the relay (founding price)'`; `catalog.ts:11-18` PRODUCT_KEYS has no traffic top-up; `page.ts:65` `Extra traffic: ${INVITE_ONLY_PAID_MESSAGE}` ("Paid plans are invite-only for now."); `services/connect/src/ice-relay.ts:39` refuses `relay_cap_reached`; `packages/contracts/src/connect.ts:21` `RELAY_MONTHLY_CAP_BYTES = 50_000_000_000`; `src/lib/mcp/connector/channel-api.ts:16` "relay only when the directory allows it" | +| 5 | 105 | "**Availability:** the paid tiers" | Replace lines 105-108 with: "**Availability:** paid plans are invite-only for now. When the account page's Billing section offers the paid tiers (Anywhere, the founding price and the relay add-on), invited accounts subscribe there, on the [account page](https://account.overdeck.ai/account). Creem handles the payment as merchant of record; Overdeck never sees your card details. Sign-up is invite-only." (override O2) | `page.ts:26` BILLING_MESSAGE; `page.ts:130-133` billing section only when `parseBillingConfig` is non-null; `billing/actions.ts:39` CARD_NOTE "Overdeck never sees your card details."; `grants.ts:63-73` isAllowed (owner, invite or subscriber) | +| 6 | 111 | "shows your plan, this month's relay use and your machines. From it you can subscribe, add or" | Replace lines 110-113 with: "**Your account page:** [account.overdeck.ai/account](https://account.overdeck.ai/account) shows your plan, this month's relay use and your machines. From it you can remove a machine (which signs it out and frees its place) or delete your account. When billing is available, it also lets you subscribe, add or remove the relay, open **Manage billing** (card, invoices, cancel) and see how many founding places are left." | `page.ts:134-141` sections Plan, Relay, Machines, Billing, Delete; `page.ts:27` REMOVE_NOTE; `billing/page-sections.ts:24-27` "Subscribe", "Add the relay", "Remove the relay", "Manage billing (card, invoices, cancel)"; `page-sections.ts:39-41` "founding places left" | +| 7 | 115 | "In the dashboard, **Settings → Anywhere → Account** shows the same plan" | Replace lines 115-116 with: "In the dashboard, the **Account** card in **Settings → Anywhere** shows the signed-in GitHub account, the plan (**Free account** or **Tester**) and this month's relay use. It links to the account page with **Manage account**. In a browser on this machine, its **Sign in** button signs the machine in without `pan account login`; other viewers see a `pan account login` hint." | `src/dashboard/frontend/src/components/Settings/anywhere/AccountCard.tsx:126-130` rows "Signed in as", "Plan", "Relay"; :144 "Manage account"; :44-49 hint when `!canSignIn`; `src/dashboard/server/routes/account.ts:54` `canSignIn = ...'root-session' && isTrustedLocalCaller(request)`; `accountApi.ts:55-63` planLabel 'Free account' / 'Tester' | +| 8 | 120 | "If you cancel, or a payment keeps failing (Creem retries a failed payment for 7 days), your plan" | Replace lines 120-121 with: "If you cancel, or a renewal payment keeps failing (the plan keeps paid access for 7 days past its paid-through date while Creem retries the card), your plan changes when the paid period ends. While your invite is active you return to the Tester plan. Without an active invite you return to the free account:" | `services/account/src/billing/access.ts:11-12` "a `past_due` row keeps paid access this long after `paid_through`" `PAST_DUE_GRACE_MS = 7 * DAY_MS`; `entitlement.ts:72-74` grant → tester before subscriber → free | +| 9 | 125 | "For 30 days your hosted vault data stays readable and you can export it with" | Replace lines 125-126 with: "- For 30 days your hosted vault data stays readable, and you can export it with `pan vault migrate` once that command ships with the hosted vault. Writes follow the free 1 GB, so a larger vault is read-only." | `pan vault --help` (0.89.1) lists setup, join, passphrase, rotate-key, status, save, sync, list, show, resume, exclude, include, allow-secret, evict, restore; no `migrate`; `wrangler.jsonc:31` VAULT binding commented "added by PAN-4297" | +| 10 | 131 | "`pan vault migrate` works throughout." | "The hosted vault and `pan vault migrate` are planned ([PAN-4297](https://github.com/eltmon/overdeck/issues/4297)); once they ship, `pan vault migrate` works throughout." (keep the next sentence "Subscribing again before the deletion date restores everything.") | same as row 9 | +| 11 | 134 | "**Extra storage:** +$3 a month" | "**Extra storage (planned with the hosted vault):** +$3 a month" | `catalog.ts:11-18` PRODUCT_KEYS has six subscription products and no storage add-on | +| 12 | 142 | "Transcripts are encrypted on your machine before upload, with a key only you hold. The" | "The hosted vault is planned. When it ships, transcripts are encrypted on your machine before upload, with a key only you hold. The" | `wrangler.jsonc:31` VAULT binding commented out; `entitlement.ts:6` "quotaDecision() is the rule the hosted vault (PAN-4297) enforces" | +| 13 | 148 | "Deleting your account deletes all of your hosted vault data within 24 hours, and removes" | Replace lines 148-149 with: "Deleting your account signs out every device, cancels any subscription, deletes all of your hosted data within 24 hours, and removes your machines and phones from the connect directory." | `page.ts:28-29` DELETE_STATEMENT "signs out every device, removes your machines from the directory and deletes all of your hosted data within 24 hours"; `services/account/src/deletion.ts:7-8` "The billing holder cancels every live subscription first" | +| 14 | 152 | "We plan to sell through [Creem](https://www.creem.io) as merchant of record." | "Paid plans are sold through [Creem](https://www.creem.io) as merchant of record." (override O2) | `services/account/src/billing/creem.ts` (checkout, upgrade, cancel, portal); `catalog.ts:125-132` billing off until configured | +| 15 | 187 | "The overdeck.ai directory: your machines in Settings → Anywhere → Directory" | In this row, replace `next release` with `v0.73.0`; keep the link as it is (O1) | changelog.mdx:501 (v0.73.0) "overdeck.ai sign-in and directory" | +| 16 | 188 | "Direct connections between your machines with no Tailscale" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:502 "Direct and relay routes" | +| 17 | 189 | "The relay add-on: relay routes, **Using relay**" | In this row, replace `next release` with `v0.73.0`; keep the link as it is (O1) | changelog.mdx:502 "the relay add-on ... 50 GB monthly allowance" | +| 18 | 190 | "The webhook inbox: triggers that hold events for 24 hours" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:511 "the directory's webhook inbox holds them for 24 hours"; `contracts/src/connect.ts:25` `INBOX_HOLD_MS = 86_400_000` | +| 19 | 191 | "Linked machines: link your machines over an end-to-end encrypted channel" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:500 | +| 20 | 192 | "Conversations across machines: one shared list" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:506 | +| 21 | 193 | "Work across machines: the Machine field" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:507 | +| 22 | 194 | "Gauntlet lanes on any linked machine" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:507 "`pan lane start --machine` runs gauntlet lanes on any linked machine"; `pan lane start --help` "--machine <label\|auto>" | +| 23 | 195 | "SSH machines: Overdeck starts or adopts" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:503 | +| 24 | 196 | "`pan connect`: one command turns a fresh server" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:504 | +| 25 | 197 | "Fly VMs as machines (`pan machines add-fly`)" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:505 | +| 26 | 198 | "Fleet versions and **Update all**, including harness CLIs" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:508 | +| 27 | 199 | "The desktop app opens a chosen machine's dashboard" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:512 "Desktop app without a local server" | +| 28 | 200 | "**Set up Tailscale**: install, sign in, Serve HTTPS" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:510 | +| 29 | 201 | "The phone app over Tailscale Serve: answer a question in three taps" | In this row, replace `next release` with `v0.73.0`. Then insert a new row after it: `\| Native iPhone and Android apps: pair by QR code, answer questions, push notifications sealed to each phone (TestFlight and Play internal testing) \| v0.74.0 \| [Phone](/configuration/phone) \|` (unescaped pipes in the page) | changelog.mdx:509 (web app `/m`, v0.73.0); changelog.mdx:455 (v0.74.0) "Native phone apps for iOS and Android ... in TestFlight and Play internal testing now" | +| 30 | 202 | "Push notifications sent from your machine with Web Push" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:509 | +| 31 | 203 | "Webhook triggers (`pan triggers`), published through Tailscale Funnel" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:511 | +| 32 | 204 | "The MCP server (`pan mcp serve`, **Copy MCP URL**)" | In this row, replace `next release` with `v0.73.0; agent tools v0.74.0`, and replace "every Claude Code, Codex, `acp` and `opencode` agent" with "every Claude Code, Codex, `acp`, `opencode` and `grok` agent" | changelog.mdx:513 (v0.73.0 MCP server, Copy MCP URL); changelog.mdx:453 (v0.74.0) "every managed agent now gets Overdeck's own tools over MCP"; `packages/contracts/src/harness-capabilities.ts:128,195,222,276` `overdeckMcp: true` for claude-code, codex, acp, opencode; :281-282 `GROK_CAPABILITIES = { ...OPENCODE_CAPABILITIES,` with no override, so grok inherits `true` | +| 33 | 205 | "OAuth sign-in for MCP clients, approved in your dashboard" | In this row, replace `next release` with `v0.74.0` | changelog.mdx:454 "A bot signs in with OAuth 2.1 and you approve it on an approval card"; `pan mcp --help` lists `oauth` | +| 34 | 206 | "Public MCP for hosted bots through Tailscale Funnel" | In this row, replace `next release` with `v0.74.0` | changelog.mdx:454 "An opt-in public `/mcp` endpoint over Tailscale Funnel" | +| 35 | 207 | "Connect a bot: Hermes, OpenClaw, Grok Build" | In this row, replace `next release` with `v0.74.0` | changelog.mdx:454; `pan mcp --help` lists `connector` | +| 36 | 208 | "Sign in to overdeck.ai (`pan account login`" | In this row, replace `next release` with `v0.73.0; dashboard **Sign in** v0.74.0`. Then insert a new row after it: `\| The account page at account.overdeck.ai: plan, relay use, machines, delete account \| v0.74.0 \| [pan account](/cli/account) \|` (unescaped pipes in the page) | changelog.mdx:501 (`pan account login`, v0.73.0); changelog.mdx:457 (v0.74.0) "Settings → Anywhere has an **Account** card with PKCE sign-in, and account.overdeck.ai has an account page" | +| 37 | 209 | "Pipeline agents' transcripts saved to the Session Vault automatically" | In this row, replace `next release` with `v0.73.0` | changelog.mdx:514 | +| 38 | 210 | "Shared sessions: share a conversation by link" | In this row, replace `next release` with `v0.74.0` | changelog.mdx:456 | +| 39 | 226 | `<Step title="One Overdeck server per machine, linked">` | On the next line (227), replace `**Shipped (next release). Free, open source.**` with `**Shipped (v0.73.0). Free, open source.**` | changelog.mdx:500-508 | +| 40 | 246 | `<Step title="Notifications, remote access and a mobile web app">` | On the next line (247), replace `**Shipped (next release). Free, open source.**` with `**Shipped (v0.73.0). Free, open source.**` | changelog.mdx:509-510 | +| 41 | 252 | "phone app is an installable web app reached over Tailscale." | "phone app is an installable web app reached over Tailscale. Native iPhone and Android apps that use the same end-to-end encrypted channel as linked machines followed in v0.74.0 and are in TestFlight and Play internal testing." | changelog.mdx:455 | +| 42 | 260 | "**Shipped (next release). Free, open source; you pay Fly directly.**" | "**Shipped (v0.73.0). Free, open source; you pay Fly directly.**" | changelog.mdx:505 "You pay Fly directly." | +| 43 | 274 | `<Step title="Webhook triggers and the MCP server">` | On the next line (275), replace `**Shipped (next release). Free, open source.**` with `**Shipped (v0.73.0). Free, open source.**` | changelog.mdx:511,513 | +| 44 | 289 | "**Account service, directory, relay add-on, webhook inbox and shared sessions built (next" | Replace lines 289-300 (through "contributors can send them.") with: "**Account service, directory, relay add-on and webhook inbox shipped in v0.73.0, and shared sessions and the account page in v0.74.0, all invite-only. Paid plans are invite-only for now; the hosted vault is planned. This is the paid plan above.**" then a blank line, then: "The account service, the directory with direct connections, the relay add-on and the webhook inbox shipped in v0.73.0. overdeck.ai accounts are invite-only: testers are added by the operator. A machine signs in with [`pan account login`](/cli/account), which runs once per machine and is optional. Paid plans are invite-only for now. The hosted Session Vault is still planned. Shared sessions shipped in v0.74.0: a host shares a conversation by link and viewers watch it live in their own Overdeck ([Shared sessions](/configuration/shared-sessions)); viewers can suggest prompts, and contributors can send them." | changelog.mdx:501-502,511 (v0.73.0); changelog.mdx:456-457 (v0.74.0); `wrangler.jsonc:30-31`; `services/share/src/protocol.ts:111,119` `contributor`, `set-contributor` | +| 45 | 439 | "push notifications and, later," | "push notifications and" (the sentence then reads "the same promise as the relay, push notifications and shared sessions.") | changelog.mdx:456 Shared Sessions shipped in v0.74.0 | +| 46 | 447 | "(It used to end" | Delete the parenthetical from "(It used to end" on line 447 through "because the relay ships in the same release.)" on line 448, so the paragraph ends "Founders add the relay at the normal $30 a year." | Brief rule: no history notes. `catalog.ts:36-42` founding_annual_relay `'$90 a year with the relay (founding price)'` (= $60 + $30) | +| 47 | 495 | "the Anywhere card says" | "the Anywhere status card in Settings → Anywhere says" | `AnywhereStatusCard.tsx:188-191` renders `RELAY_CAP_MESSAGE` when `status.relay?.stopped`; `contracts/src/connect.ts:57` `"Relay allowance used; install Tailscale or add 50 GB"` | +| 48 | 496 | "An extra 50 GB is a one-time" | Replace from "An extra 50 GB is a one-time" (line 496) through "$3 purchase." (line 497) with: "An extra 50 GB for a one-time $3 is planned; until it ships, the card's **Add 50 GB** link opens overdeck.ai/anywhere." | `AnywhereStatusCard.tsx:57` `ADD_RELAY_URL = 'https://overdeck.ai/anywhere'`, :191 "Add 50 GB"; `catalog.ts:11-18` no top-up product; `page.ts:65` "Extra traffic: Paid plans are invite-only for now." | + +#### Missing + +- [ADD via D3: use the Glossary help sentence only] A getting-help section. Add `## Get help` at the end: questions in the Overdeck Discord https://discord.gg/ZpHE2ZTv5P, bugs in GitHub Issues https://github.com/eltmon/overdeck/issues. Pricing feedback stays on PAN-4294/PAN-4297. +- [SKIP: covered by rows 1, 3 and 7] The plan name invited users actually see is **Tester**, on the account page and on the dashboard Account card. Rows 1, 3 and 7 add it (`billing/page-sections.ts:16` `PLAN_LABEL_TESTER = 'Tester'`; `accountApi.ts:59-60`). +- [SKIP: optional detail] On the account page, the paid plan shows as **Anywhere** or **Anywhere with the relay**, and a founding subscriber sees "Founding price, locked while you stay subscribed." (`page-sections.ts:13-17`). Optional one line under "Your account page". +- [SKIP: optional detail] `pan account status` does not show the plan. A user looks at the account page or the dashboard Account card (`src/cli/commands/account/status.ts:66-70`). Optional. + +#### Links + +- /configuration/shared-sessions OK; /configuration/remote-access OK; /configuration/linked-machines OK; /configuration/tailscale OK +- /configuration/bots#run-the-overdeck-connector OK +- /configuration/session-vault OK; /features/conversations OK +- /configuration/remote-access#open-one-conversation-on-another-screen OK; #from-the-desktop-app OK +- `/configuration/remote-access#find-your-machines-through-overdeck-ai` OK. The planner probed it with `mint broken-links --check-anchors`: the `-overdeck-ai` slug resolves (override O1). +- /configuration/triggers OK; #hold-events-with-the-directory-inbox OK +- /configuration/linked-machines#sharing-conversations, #start-work-on-another-machine, #ssh-machines, #fly-machines, #fleet-versions-and-update-all, #work-agents-on-fly OK +- /reference/lanes#lanes-on-other-machines OK; /cli/machines#connect OK +- /configuration/phone OK; /configuration/push-notifications OK +- /configuration/mcp OK; #sign-in-with-oauth OK; #public-mcp-for-hosted-bots OK +- /configuration/bots OK; /cli/account OK +- In-page `#how-we-arrived-at-these-prices` (line 138) OK (heading line 323) +- docs.json `redirects`: 8 entries. + +#### Follow-ups (do not fix here) + +1. **Confirm whether production billing is on.** If the operator has deployed the Workers with `CREEM_*` set, rows 1, 5, 6, 14 and 44 should instead say the paid tiers are on sale to invited accounts. Restore `.pan/notes/held-changelog/pan-4294.md` to `changelog.d/` at the same time (commit cbb8ebefb9e). +2. **Dashboard Account card cannot show a paid plan.** `AccountPlan` is `'free' | 'tester'` in `src/lib/account/client.ts:41`, `src/dashboard/server/services/account-view.ts:19` and `accountApi.ts:8`. `/v1/me` returns `entitlement.plan = 'anywhere'` for a subscriber (`services/account/src/api.ts:25-31`, `entitlement.ts:61`), so `planLabel` (`accountApi.ts:55-63`) shows "Shows when overdeck.ai is reachable". The card also always prints "Paid plans are invite-only for now." (`AccountCard.tsx:135`). +3. **The account page tells lapsed users to run a missing command.** It says "Export it now with pan vault migrate" (`billing/page-sections.ts:48`), and that command does not exist. +4. **The dashboard's Add 50 GB link leads nowhere useful.** It opens `https://overdeck.ai/anywhere` (`AnywhereStatusCard.tsx:57`), but no traffic top-up product exists (`catalog.ts:11-18`, `page.ts:65`). +5. **A tester who subscribes without the relay loses the relay.** Paid access wins over the tester grant and takes `relay` from the product (`entitlement.ts:60-65`). +6. **The founding window clock.** Lines 94 and 445-446 say the founding price is open "90 days after the Anywhere release". Once the page dates that release to v0.73.0 (2026-11-03), the 90 days run while billing is off. The real end is the operator's `FOUNDING_ENDS_AT` (`catalog.ts:137-141`). Decide whether to reword it as "90 days after paid plans go on sale". +7. **Expired invite: the account page and the directory disagree.** The account page computes the plan from the grant row even after it expires (`page.ts:123` `getGrant`; header comment line 5 "expired or not"). The directory uses only an active grant (`devices.ts:163` `grantActive ? ... : null`). So a lapsed subscriber with an expired invite sees "Tester" on the page but is held to free limits. +8. **The free plan is effectively unreachable for new invitees.** No admin path sets `grants.entitlement = 'free'` (`grants.ts:86`; `admin/screen.ts:53` only displays it). If the published "Free account" tier is meant to be the invitee default, the admin screen needs a way to set it. + +### Appendix B: `cli/account.mdx` + +Section map: frontmatter 1-4; `# pan account` 6-16; `## login` 18-69; `## status` 71-104; `## logout` 106-129; `## The token file` 131-139. +Suggested title: "pan account: sign this machine in to overdeck.ai" (sidebarTitle "pan account") +Help section: no + +#### Change table + +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 2 | "title: pan account" | `title: "pan account: sign this machine in to overdeck.ai"` and add `sidebarTitle: "pan account"` | Brief rule (generic title) | +| 2 | 41 | "variable, then the default `https://account.overdeck.ai`. An invalid URL (wrong scheme, a" | Replace lines 40-43 with: "The base URL resolves in order: `--base-url`, then the `OVERDECK_ACCOUNT_URL` environment variable, then the default `https://account.overdeck.ai`. It must use `https`, or `http` on `localhost`, `127.0.0.1` or `[::1]`, and have no path, query or fragment. Anything else exits 1 before any network call with `Invalid account service URL: <url>`." | `src/lib/account/client.ts:16` `LOCAL_HTTP_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]'])`; :66-81 resolveBaseUrl | +| 3 | 69 | "Other failures: `The sign-in code expired. Run: pan account login`;" | "Other failures: `The sign-in code expired. Run: pan account login`; `Cannot start sign-in at <baseUrl>: HTTP <status>` when the service answers the first request with an error status; `Sign-in failed: <error>` when polling returns an error other than pending, slow down, denied or expired;" (the rest of the line stays) | `client.ts:151` `Cannot start sign-in at ${baseUrl}: HTTP ${res.status}`; `client.ts:243-244` default → `reason: 'failed'`; `src/cli/commands/account/login.ts:88-89` `Sign-in failed: ${outcome.detail}` | +| 4 | 69 | "or when the service is unreachable for several consecutive polls" | "or when three polls in a row fail with a network error or an HTTP 5xx answer (then `<reason>` is `HTTP <status>`)" | `client.ts:205-216` `consecutiveFailures >= 3` on a thrown fetch or `res.status >= 500` → `detail: \`HTTP ${res.status}\`` | +| 5 | 98 | "Never includes the token." | Replace the Effect cell of the `--json` row with: "Print `{ signedIn, baseUrl, githubLogin, githubId, deviceId, label, access, reachable }`. `access` is `{ status, expiresAt }`, where `status` is `active` or `grant_expired`, or `null` when the service did not confirm the token. Signed out, it prints `{"signedIn":false}` and exits 0. A rejected token or an unreachable service still prints the JSON, with `reachable` true or false, and exits 1. Never includes the token." | `src/cli/commands/account/status.ts:47` `{ signedIn: false }`; :56-65 `access: me.me.access`; :75-93 `access: null`, `reachable: true` / `false`, `io.exit(1)`; `client.ts:52` `access: { status: 'active' \| 'grant_expired'; expiresAt }` | +| 6 | 120 | "If the service cannot be reached, the token file is still deleted locally, and this prints" | "If the service cannot be reached, or answers with a status other than 204, 401 or 404, the token file is still deleted locally, and this prints" | `client.ts:320-323` 204/401/404 → ok, else `{ ok: false, detail: \`HTTP ${res.status}\` }`; `logout.ts:36-37` | +| 7 | 133 | "`${OVERDECK_HOME}/account.json`, mode `0600`, written atomically. Holds `baseUrl`," | "`${OVERDECK_HOME}/account.json`, mode `0600`, written atomically. Holds a format version `v` (always 1), `baseUrl`," | `src/lib/account/store.ts:19-28` `v: 1;` first field; :40-41 `record.v === 1` checked on read | + +#### Missing + +- [ADD via D3: use the Glossary help sentence only] A getting-help line or section linking the Overdeck Discord https://discord.gg/ZpHE2ZTv5P and GitHub Issues https://github.com/eltmon/overdeck/issues. Fits naturally after the sign-in failure list, for "not on the invite list" cases. +- [ADD] `status` shows no plan. Add one line: "To see your plan and relay use, open the account page at https://account.overdeck.ai/account, or Settings → Anywhere → Account in the dashboard." (`status.ts:66-70` prints login, base URL, device, access only; `AccountCard.tsx:127-130` shows Plan and Relay). + +#### Links + +- /cli/share OK; /anywhere OK; /cli/vault OK. No anchors. + +#### Follow-ups (do not fix here) + +- None specific to this page. + +### Appendix C: `configuration/linked-machines.mdx` + +Section map: frontmatter 1-4 · H1 `# Linked machines` 6 · intro 8-15 · Link a machine 17-46 · SSH machines 48-110 (Requirements 73-84, Started by Overdeck 86-101, The forward 103-110) · Link a fresh server 112-124 · Fly machines 126-277 (Setup 161-194, Lifetime and cost 196-210, Work agents on Fly 212-238, Codex 240-259, Limits 261-269, Gauntlet lanes 271-277) · Access levels 279-287 · What is encrypted 289-296 · Routes 298-328 · States 330-353 · When a link does not open 355-367 · Sharing conversations 369-392 · Title-bar states 394-411 · Remote control 413-425 · Pull here 427-449 · Open preview 451-466 · Open in editor 468-478 · Fleet versions and Update all 480-521 · Start work on another machine 523-556 · Delegation 558-571 · Auto placement 573-620 (Gauntlet lanes 613-620) · Projects across machines 622-639 · Fleet Needs-You and search 641-651 · Fleet usage 653-660 · Compare settings 662-669 · Unlink 671-677 · Troubleshooting 679-716 + +Suggested title: "Linked machines: pair Overdeck machines and work across them" (sidebarTitle "Linked machines") + +Help section: yes, `## Troubleshooting` (679-716), but it has no Discord or GitHub Issues link (row 13). + +#### Change table + +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 2 | "title: Linked machines" | "title: \"Linked machines: pair Overdeck machines and work across them\"" and add the line "sidebarTitle: Linked machines" under it | Brief rule 6: the current title is generic. | +| 2 | 43-46 | "requested** card in the Decisions panel, and the card's **Link a machine…** button" | Rewrite lines 43-46 as: "An agent can ask you for a link. Its `link_machine` tool shows a **Machine link requested** card in **Needs you** and at the top of the agent's conversation. In a browser on this machine, the card's **Link a machine…** button opens this dialog. After the link succeeds, the agent learns the new machine's label, never the pairing link. See [Machine links](/configuration/mcp#machine-links)." | The UI calls it Needs you: `src/dashboard/frontend/src/components/sessionFeed/SessionFeedSidebar.tsx:130` "{ id: 'needs', label: 'Needs you', badge: needsCount }" renders `DecisionsPanel` (line 12). The conversation shows the card too: `src/dashboard/frontend/src/components/chat/ConversationPanel.tsx:29` "import { PendingAgentRequestCards }". The button is only for a browser on this machine: `src/dashboard/frontend/src/components/AgentRequestCard.tsx:16-18` "for a root-session viewer **Link a machine…**". Unreleased entry `changelog.d/pan-5541.md`: "the agent's conversation shows the request at the top". | +| 3 | 67 | "**Test** in the dialog (or `pan machines test-ssh <host>`) runs only step 2." | "**Test** in the dialog (or `pan machines test-ssh <host>`) runs only steps 1 and 2: it connects over SSH and compares the `pan` versions." | `src/dashboard/server/services/ssh-machine-service.ts:14` "`testSshHost` runs only the version probe (FR-9)"; the probe is an SSH call: line 164 "const result = await deps.runSsh(dest, remoteCommand({ pan: panPath, op: 'version' })". | +| 4 | 155 | "5. With `--message`, starts a Claude Code or Codex conversation (`--harness`) there and" | "5. With `--message` (which needs `--project`), starts a Claude Code or Codex conversation (`--harness`) there and" | `src/dashboard/server/services/fly-machine-service.ts:196-197` "if (input.message !== undefined && !input.projectKey) { throw new FlyMachineError('bad-request', 'A message needs a project: pass projectKey (--project) with it.')"; `pan machines add-fly --help`: "--message <text> Start a conversation with this first message (needs --project)". | +| 5 | 294-296 | "fingerprint (five groups of four hex characters) is shown next to each link so you can" | Replace lines 294-296 from "and its" onward with: "and its fingerprint (five groups of four hex characters) is printed for each link by `pan machines list` and shown on each **Inbound** row in Settings → Anywhere → Machines, so you can compare it with the other machine's **This machine** line." | Settings outbound rows render no fingerprint: `src/dashboard/frontend/src/components/Settings/anywhere/MachinesPanel.tsx:191-237` (row shows label, state, route, access, version, heartbeat, load only). Inbound rows do: line 312 "<span className=\"font-mono text-xs\">{inbound.fingerprint}</span>". CLI: `src/cli/commands/machines.ts:128` "link.fingerprint," in the list table. | +| 6 | 323 | "`direct` routes (`rtc://<environment id>`, a peer-to-peer WebRTC path) and, on the relay plan," | "`direct` routes (`rtc://<environment id>`, a peer-to-peer WebRTC path) and, on the relay plan (paid plans are invite-only for now)," | `services/account/src/account-page/page.ts:23` "export const INVITE_ONLY_PAID_MESSAGE = 'Paid plans are invite-only for now.';"; `changelog.mdx:499` "The hosted overdeck.ai services are optional, invite-only for now". | +| 7 | 419-422 | "allowed: an **agent-fenced** link can read but not change the other machine's" | Replace lines 419-422 from "The owner's own access rules" onward with: "The owner's own access rules decide what is allowed: an **agent-fenced** link, and an agent on a linked machine, can read but not change the other machine's conversations (`agent-fenced`). The one exception is work this machine started there, which it may message and stop (see [Start work on another machine](#start-work-on-another-machine))." | `src/dashboard/server/link-fence.ts:4-8` "may start work here only through the work doors ... It may change a conversation only when that conversation's provenance (`started_by_environment_id`) is the credential's own environment"; an agent-fenced link is an agent actor: `src/lib/anywhere/link-actor.ts:33` "actor = access === 'operator' ? 'operator' : { agentId: 'operator-fenced' };". | +| 8 | 484-485 | "installed there (Claude Code, Codex CLI, Kimi Code CLI, OpenCode, Muse Code, Prime Agent," | Change the list on lines 484-485 to: "installed there (Claude Code, Codex CLI, Kimi Code CLI, OpenCode, Grok Build, Muse Code, Prime Agent, OhMyPi, Pi)." | Every harness in `KNOWN_HARNESSES` is probed: `packages/contracts/src/types.ts:94` "['claude-code', 'pi', 'ohmypi', 'codex', 'acp', 'kimi-code', 'opencode', 'muse', 'prime-agent', 'grok']"; `src/lib/fleet/harness-versions.ts:169` "for (const name of KNOWN_HARNESSES)". Order: `packages/contracts/src/fleet-versions.ts:99` "[\"claude\", \"codex\", \"kimi\", \"opencode\", \"grok\", \"muse\", \"prime-agent\", \"omp\"]" (pi is unranked, so last). Labels: `packages/contracts/src/harness-capabilities.ts:283` "binaryLabel: \"Grok Build\"", line 167 "binaryLabel: \"Pi\"". | +| 9 | 513 | "\| OpenCode \| `opencode upgrade` \|" | Insert this table row after the OpenCode row (after line 513): "\| Grok Build \| `grok update` \| npm installs: `npm install -g --prefix <prefix> @xai-official/grok@latest` \|" | `packages/contracts/src/harness-capabilities.ts:281-287` "binaryLabel: \"Grok Build\" ... updateArgs: [\"update\"], npmPackage: \"@xai-official/grok\""; npm branch: `src/lib/fleet/harness-versions.ts:145` "[npmBin, 'install', '-g', '--prefix', prefix, `${npmPackage}@latest`]". | +| 10 | 516 | "\| OhMyPi \| none \| Listed with its version; Overdeck does not update it. \|" | Insert this table row after the OhMyPi row (after line 516): "\| Pi \| none \| npm installs: `npm install -g --prefix <prefix> @earendil-works/pi-coding-agent@latest`; other installs are listed with their version only. \|" | Pi inherits `updateArgs: null` from OhMyPi but has an npm package: `packages/contracts/src/harness-capabilities.ts:165-171` "...OHMYPI_CAPABILITIES, binaryLabel: \"Pi\", ... npmPackage: \"@earendil-works/pi-coding-agent\"" (line 146 OhMyPi "updateArgs: null"); plan order `src/lib/fleet/harness-versions.ts:139-161` (npm prefix branch, else updateArgs, else "Overdeck does not update ${binaryLabel}"). | +| 11 | 532-534 | "CLI takes the same per-machine choice for a conversation, but `--machine fly` refuses on" | Replace lines 532-534 from "The CLI takes" through the colon with: "The CLI takes the same per-machine choice for a conversation. `--machine fly` refuses on `pan worker run` and `pan lane start`; on `pan start` it starts the issue's work agent on a new Fly machine, the same as `--remote` (see [Work agents on Fly](#work-agents-on-fly) and [`pan machines add-fly`](/cli/machines#add-fly)):" | `src/cli/commands/start.ts:513-517` "// PAN-4734 FR-2: `--machine fly` starts a work agent on a new Fly machine, the same as --remote. if (options.machine?.toLowerCase() === 'fly') { options.remote = true;". Worker refuses: `src/cli/commands/worker-remote.ts:80` "if (machine.toLowerCase() === 'fly') return { kind: 'error', message: FLY_CLI_REFUSAL };". Lane refuses at the dashboard: `src/dashboard/server/services/fleet-target.ts:131-132` "if (wanted.toLowerCase() === 'fly') { if (!spawn) return refuse(400, 'fly-unavailable', FLY_CONVERSATIONS_ONLY);". The page itself says the opposite at lines 214-219. | +| 12 | 576-578 | "`Auto → desk (CPU pressure 3%, 41 GB free, 2 agents)`. When Auto passed over other machines it" | Replace lines 576-578 from "When Auto passed over" onward with: "`pan lane start` adds a second line when Auto passed over other machines, for example `Passed over: laptop: no docker; desk: offline`, and prints both lines when it picks this machine too. `pan start` and `pan worker run` print only the first line." | Only lane prints it: `src/cli/commands/lane.ts:267-268` "const passedOver = result.placement?.rejections ?? []; if (passedOver.length > 0) deps.stderr(`Passed over: ...`)". `src/cli/commands/start-machine.ts:61` and `src/cli/commands/worker.ts:304` print only "deps.stderr(target.reason)". A repo-wide grep for "Passed over" in `src/` finds only `lane.ts`. | +| 13 | 716 | "access turns it on; see [Remote access]" | After line 716, add a final bullet: "- **Still stuck?** Ask in the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or open an issue on [GitHub Issues](https://github.com/eltmon/overdeck/issues)." | Brief rule 5: a troubleshooting section must link Discord and GitHub Issues; lines 679-716 link neither. | +| 14 | 655 | "The Costs page's **Machines** tab shows today, week and month spend for each machine and an" | "The Costs page's **Machines** tab (Costs is an experimental view: turn on **Settings → Experimental → Experimental features** to see it) shows today, week and month spend for each machine and an" | `src/dashboard/frontend/src/lib/experimentalFeatures.ts:4-14` `EXPERIMENTAL_TAB_IDS` includes "'costs',"; the tab lives on that page: `src/dashboard/frontend/src/components/CostsPage.tsx:718` "{activeTab === 'machines' && <FleetUsagePanel />}"; toggle label `src/dashboard/frontend/src/components/Settings/sections/ExperimentalSection.tsx:76` "Experimental features". | +| 15 | 700 | "route itself is congested: check the machine's routes in Settings → Machines." | "route itself is congested: check the machine's routes in Settings → Anywhere → Machines." | Machines is a panel inside Settings → Anywhere: `src/dashboard/frontend/src/components/Settings/sections/AnywhereSection.tsx:53` "title=\"Anywhere\"" and line 94 "<MachinesPanel />". | +| 16 | 328 | (dropped by override O1: the existing anchor resolves) | no change | O1 | +| 17 | 124 | "for lingering, macOS, firewalls and removal." | After this paragraph, add: "<Note>Running `npx @overdeck/core connect` as a systemd service on a fresh VPS has not yet been tested end to end on a real VPS ([#4863](https://github.com/eltmon/overdeck/issues/4863)).</Note>" | `changelog.mdx:515` (v0.73.0 Known limitations) "Running `npx @overdeck/core connect` as a systemd service on a fresh VPS has not been tested on a real VPS ([#4863]...)"; `gh issue view 4863` is OPEN (planner, 2026-11-18) | +| 18 | 325 | "server over TLS on port 443 first, so a network that blocks UDP can still reach it." | Append after this sentence: "This TCP fallback is covered by tests but has not yet connected on a live Fly VM." | `changelog.mdx:515` "The relay's TURN-over-TCP fallback for networks that block UDP is covered by tests but has not yet connected on a live Fly VM."; no later `changelog.mdx` or `changelog.d/` entry says otherwise (planner grep for "TURN-over-TCP", "over TCP") | + +#### Missing + +- [ADD] SSH dialog has no access-level choice; the CLI does: `pan machines add-ssh --agent-fenced` and `--one-way` (`pan machines add-ssh --help`; dialog fields are host, Link both ways and Advanced pan path only, `src/dashboard/frontend/src/components/Settings/anywhere/AddSshMachineDialog.tsx:4-5`). +- [ADD] `pan machines link --one-way` is the CLI form of unticking **Link both ways** (`pan machines link --help`: "--one-way Only this machine reaches the other"). +- [ADD] `add-fly` flags the page never names: `--region` (default `remote.fly.region`, else `iad`), `--image` (default `registry.fly.io/<app>:latest`), `--effort` (`src/cli/commands/machines-fly.ts:119-123`). Line 147's "`pan-workspace` image" could say the default ref is `registry.fly.io/<app>:latest` (`src/lib/remote/fly-provider.ts:58-59`). Link to [`pan machines add-fly`](/cli/machines#add-fly). +- [SKIP: minor label] The Fly button reads **Add a Fly machine (remote off)** while remote is off (`MachinesPanel.tsx:349`); line 177 could name it. +- [ADD] Each Online row also has **Add a project** (operator-level links only), which pushes this machine's project to that machine (`MachinesPanel.tsx:211-214`). Projects across machines mentions only the sidebar's **Add this project to <machine>**. The CLI also has `--file`, `--no-env` and `--parent-dir` (`pan machines add-project --help`). +- [ADD] **Compare settings** and **Add a project** show only on Online rows (`MachinesPanel.tsx:206,211`). +- [ADD] `pan conv pull --stop-turn` is the CLI form of **Stop it now** (`pan conv pull --help`: "--stop-turn Stop a running turn instead of waiting for it"). +- [ADD] The macOS Local Network message also says what to do: "open System Settings → Privacy & Security → Local Network and turn on node (<path>)" (`src/lib/anywhere/local-network.ts:8,57`). +- [SKIP: internal back-off detail] A route that answers with the wrong key backs off to 300 s, not 45 s, so the "closed the connection before proving the pinned machine key" case retries slowly (`src/dashboard/server/services/link-supervisor.ts:14,67` "IDENTITY_BACKOFF_CAP_MS = 300_000"). +- [ADD] The directory paragraph names only `pan machines join`. The full verb set is `directory`, `join`, `accept`, `reject`, `approve`, `forget` (`pan machines --help`); link [the CLI page](/cli/machines#through-the-overdeck-ai-directory). + +#### Links + +- `/configuration/mcp#machine-links` OK (`configuration/mcp.mdx:137` "### Machine links"). +- `/cli/machines#connect` OK (`cli/machines.mdx:483`). +- `/cli/machines#forward` OK (`cli/machines.mdx:317`). +- `/cli/machines#add-fly` OK (`cli/machines.mdx:103`). +- `/reference/lanes#lanes-on-other-machines` OK (`reference/lanes.mdx:96`), used twice. +- `/configuration/remote-access#find-your-machines-through-overdeck-ai` OK. The planner probed it with `mint broken-links --check-anchors`: the `-overdeck-ai` slug resolves (override O1). +- `/configuration/remote-access#local-reverse-proxies-require_token_mint` OK (`remote-access.mdx:328` "## Local reverse proxies: `require_token_mint`"; underscores are kept). +- `/cli/agent-commands` OK (file exists). A sharper target exists: `/cli/agent-commands#a-conversation-on-a-linked-machine` (`cli/agent-commands.mdx:105`). +- `/features/costs` OK. +- In-page anchors `#link-a-fresh-server`, `#start-work-on-another-machine`, `#remote-control`, `#pull-here` (x3), `#work-agents-on-fly`, `#ssh-machines`, `#lifetime-and-cost`, `#fly-machines`, `#projects-across-machines`: all OK. +- docs.json: 8 redirects, none involve this page; the page is in nav (`docs.json:53`). + +#### Follow-ups + +- The page has two `### Gauntlet lanes` headings (lines 271 and 613), so the second one gets a deduplicated slug. Consider renaming one, for example "### Gauntlet lanes on Fly". +- `# Linked machines` (line 6) repeats the frontmatter title, and Mintlify renders the title as the page H1 already. +- `docs/ANYWHERE-ARCHITECTURE.md` was not used as proof (per the brief). + +### Appendix D: `cli/machines.mdx` + +#### Research context + +Base: feature/pan-5500 @ 62f98b27ac6 (v0.89.1). Installed `pan` is 0.89.1. Every subcommand's `--help` was run and +compared with the commander definitions. All flags, arguments and option descriptions on the three pages match +`--help` exactly (no missing or extra flags). The errors are in behavior, output text and stale release notes. + +Commander sources: `src/cli/commands/pair.ts` (pair, devices, connect, and it registers machines), +`src/cli/commands/machines.ts` (link, list, unlink, forward, directory, join, accept, reject, approve, forget, versions, +update), `machines-ssh.ts` (add-ssh, test-ssh, hidden ssh-helper), `machines-fly.ts` (add-fly), `machines-who.ts`, +`machines-add-project.ts`, `connect.ts` + `connect-systemd.ts` + `connect-launchd.ts`, shared `machines-call.ts`, +`dashboard-call.ts`, `pairing-link.ts`. + +Experimental check (brief step 3): `git grep -i experimental` over `Settings/anywhere/`, `AnywhereSection.tsx`, +`src/lib/anywhere/`, `src/cli/commands/machines*.ts`, `pair.ts`, `connect*.ts` finds nothing. None of these commands or +their Settings panels are experimental; no maturity labels needed. + +Unreleased entries: no `changelog.d/*.md` file mentions machines, pair, devices or connect. Released history: +`pan pair`/`pan devices` v0.64.0 (`changelog.mdx:737,747`), Pair a device and Revoke in Settings v0.65.0 +(`changelog.mdx:677,682`), `pan machines` family and `pan connect` v0.73.0 (`changelog.mdx:496,500-508`). + +UNVERIFIED: none. Every claim listed under "Verified, keep" was read in source (or in `--help` for `pan account login` +and `pan tailscale setup`). + +Section map: frontmatter 1-4; intro 6-15; `## link` 17-40; `## add-ssh` 42-85; `## test-ssh` 87-101; `## add-fly` 103-150; +`## list` 152-190; `## Starting work on another machine` 192-216; `## Messaging a conversation on another machine` 218-228; +`## who` 230-247; `## add-project` 249-268; `## unlink` 270-315; `## forward` 317-338; `## Through the overdeck.ai directory` +340-417 (`### directory` 346-359, `### join` 361-378, `### approve` 380-394, `### accept and reject` 396-404, `### forget` +406-417); `## versions` 419-449; `## update` 451-481; `## connect` 483-658 (`### Lingering (Linux)` 541-560, `### macOS` +562-580, `### No systemd` 582-593, `### Which address the link uses` 595-609, `### After a reboot` 611-617, +`### Updating and removing` 619-645, `### Troubleshooting` 647-658). + +Suggested title: "pan machines: link, list and update your machines" (sidebarTitle "pan machines") +Help section: partial. `### Troubleshooting` (line 647) covers only the `pan connect` watchdog and has no Discord or +GitHub Issues links (change row 15). + +#### Change table + +Anchors contain no `|` characters, so `grep -n -F '<anchor>' cli/machines.mdx` matches each exactly once. For table-row +anchors, replace only the anchored cell text as stated. + +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 2 | "title: pan machines" | Replace line 2 with `title: "pan machines: link, list and update your machines"` and add a new line after it: `sidebarTitle: pan machines` | Brief rule 6 (generic title). | +| 2 | 79 | "SSH refused the login. The dashboard needs a key or agent it can use without a prompt." | "SSH refused the login. The dashboard needs a key or agent it can use without a prompt. `add-ssh` currently reports this error as \"The dashboard rejected this machine's internal token\"; run `pan machines test-ssh <host>` to see the SSH message." (Remedy cell of the `auth-failed` row.) | `src/dashboard/server/services/ssh-machine-service.ts:67` "'auth-failed': 401"; `src/cli/commands/machines-call.ts:29` "if (response.status === 401) return fail(NEEDS_PAN_UP);". test-ssh answers failures in a 200 body: `src/dashboard/server/routes/machines-ssh.ts:7-9`. Bug in Follow-ups. | +| 3 | 84 | "The port forward did not come up within 15 s." | "The port forward did not come up within 15 s, or this server is not the primary dashboard started by `pan up` (only the primary keeps SSH forwards)." | `src/dashboard/server/services/ssh-forward-supervisor.ts:41` "FORWARD_READY_TIMEOUT_MS = 15_000"; `ssh-machine-service.ts:151` "'SSH machines are run by the primary dashboard (pan up); this server does not keep SSH forwards.'" | +| 4 | 140 | "or the variable `[remote.fly] api_token_env` names). " (end of the `no-fly-token` row) | Keep the row. Insert a new table row on the line after line 140: "| `fly-token-rejected` | Fly refused the token. Run `fly auth login`, or set `FLY_API_TOKEN` (or the variable `[remote.fly] api_token_env` names) to a long-lived token from `fly tokens create deploy -a <app>`. |" (use real pipe characters). | `src/lib/anywhere/fly/provision-shared.ts:16` "'fly-token-rejected'", `:72` "throw new FlyMachineError('fly-token-rejected', flyTokenRejectedMessage(error) ..."; `src/lib/remote/fly-api.ts:103-107` "run `fly auth login`, or set FLY_API_TOKEN (or the variable remote.fly.api_token_env names) to a long-lived token from `fly tokens create deploy -a <app>`" | +| 5 | 142 | "`--harness codex` needs `--model`, or a field was empty." | "`--harness codex` needs `--model`, the `--model` is not a known model, or a field was empty." | `src/dashboard/server/services/fly-machine-service.ts:211-213` "if (!(error instanceof UnknownModelError)) throw error; throw new FlyMachineError('bad-request', `${error.message} Pass --model with an OpenAI model id.`" | +| 6 | 310 | "The host could not be reached; the link was removed anyway." | "The stop on the host failed or the host could not be reached; the link was removed anyway." | `ssh-machine-service.ts:226-234` "if (result?.ok && result.op === 'stop') return ...; deps.log(`ssh-helper stop on ... failed ...`) ... return { stopped: false, reason: 'stop-failed' };" | +| 7 | 343 | (dropped by override O1: the existing anchor resolves) | no change | O1 | +| 8 | 344 | "Each one exits 1 with the dashboard's error text." | "Each one exits 1 with the dashboard's error text. On a machine that is not signed in, `pan machines directory` prints `Sign in with pan account login to find your machines through overdeck.ai.` and exits 0." | `src/dashboard/server/routes/directory.ts:18` "signedIn: false,"; `src/cli/commands/machines.ts:220-222` "if (!directory.signedIn) { console.log('Sign in with pan account login to find your machines through overdeck.ai.'); return; }" | +| 9 | 387 | "`Approve? [y/N]` unless `--yes`, then approves." | "`Approve? [y/N]` unless `--yes`, then approves. Answering no rejects the request and prints `Rejected.` Without a terminal and without `--yes`, it prints `Pass --yes to approve without a prompt.` and exits 1." | `machines.ts:302-308` "if (!deps.isTTY()) return fail('Pass --yes to approve without a prompt.'); if (!(await deps.ask('Approve? [y/N] '))) { await call('reject', ...); console.log('Rejected.');" | +| 10 | 457-458 | "Code, Codex CLI, Kimi Code CLI, OpenCode) with their own update commands, then updates" | Replace the sentence on lines 457-458 ("Starts **Update all**: each online machine updates its installed harness CLIs (Claude Code, Codex CLI, Kimi Code CLI, OpenCode) with their own update commands, then updates") with: "Starts **Update all**: each online machine updates the harness CLIs installed there that it knows how to update (Claude Code, Codex CLI, Kimi Code CLI, OpenCode, Grok Build, and Pi when it was installed with npm). A CLI installed with npm is updated with `npm install -g` into its own npm prefix; otherwise the CLI's own update command runs. A CLI installed with Homebrew, or one with no update command, is left alone. Then it updates" (the rest of line 459 onward stays). | `src/lib/fleet/harness-versions.ts:119-161` "a binary under `<prefix>/lib/node_modules/<npmPackage>/` is updated with npm into that prefix; a Homebrew install is shown, not run; otherwise the declared `updateArgs`; otherwise nothing"; detection loops every harness: `:170-179` "for (const name of KNOWN_HARNESSES)"; `packages/contracts/src/harness-capabilities.ts:168-169` Pi "npmPackage: \"@earendil-works/pi-coding-agent\"" (Pi inherits `updateArgs: null` from OhMyPi, `:146`), `:283-286` "binaryLabel: \"Grok Build\" ... updateArgs: [\"update\"]". | +| 11 | 477 | "Cancel waiting updates (on every machine, or on the `--machine` ones)." | "Cancel waiting updates (on every machine, or on the `--machine` ones) and print `Cancelled on <label>` for each." | `machines.ts:405-407` "console.log(options.cancel ? `Cancelled on ${entry.label}` : `Started on ${entry.label} (${entry.job.mode})`);" | +| 12 | 615 | "within about 6 minutes. A linked machine retries with a back-off of up to 5 minutes, so it" | "within about 6 minutes. A linked machine retries a failed connection with a back-off of at most about 45 seconds, so it" | `src/dashboard/server/services/link-supervisor.ts:65-68` "BACKOFF_MIN_MS = 1_000; BACKOFF_CAP_MS = 45_000; IDENTITY_BACKOFF_CAP_MS = 300_000; BACKOFF_JITTER = 0.2"; `:484-488` the cap is 45 s unless `backoffKind === 'identity'`, which is set only when the peer fails to prove its pinned key or another machine answers (`:595-596,644,681-683`); a dashboard that is down refuses the connection, which is a network failure. | +| 13 | 616 | "shows this machine **online** again within about 15 minutes." | "shows this machine **online** again within about a minute after the dashboard answers." | Same as row 12. | +| 14 | 649 | "The watchdog stops restarting the dashboard after three failed restarts in a row, and it" | "The watchdog stops restarting the dashboard after three restarts within five minutes that do not bring it back healthy, and it" | `src/supervisor/watchdog.ts:139-140` "maxRestarts: ... 3", "windowMs: ... 5 * 60_000"; `:378-384` "this.pruneRestartAttempts(startedAt); ... if (!foreignDashboard && this.state.restartAttempts.length >= this.config.maxRestarts) { this.state.gaveUp = true;"; `:282-287` attempts clear on a healthy check. | +| 15 | 657-658 | "(terminal backend and sidecars), which a fresh server may not have." | Keep the sentence, then add a new paragraph after line 658: "Still stuck? Ask in the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or open a [GitHub issue](https://github.com/eltmon/overdeck/issues)." | Brief step 5 (help sections must link Discord and GitHub Issues). | +| 16 | 491 | "lasting linked machine. It installs the Overdeck server as a service that survives logout" | After the paragraph that contains this line, add: "<Note>Running `npx @overdeck/core connect` as a systemd service on a fresh VPS has not yet been tested end to end on a real VPS ([#4863](https://github.com/eltmon/overdeck/issues/4863)).</Note>" | `changelog.mdx:515` (v0.73.0 Known limitations); `gh issue view 4863` is OPEN (planner, 2026-11-18) | + +#### Missing + +- [ADD] `list`: with no inbound links it prints `Inbound: no machine links to this one.` instead of the Inbound table (`src/cli/commands/machines.ts:138-139`). +- [ADD] `who`: with no matches it prints `No machine runs an agent or conversation for <ISSUE>.`; the issue id is upper-cased and must look like `PAN-7` (`src/cli/commands/machines-who.ts:48,66`; `src/dashboard/server/routes/fleet-awareness.ts:175`). +- [SKIP: verbose output detail] `add-project`: prints progress `Cloning <key> from <machine>…` on stderr, then `Added <key> to this machine.` and one ` <path>: written|skipped|failed` line per file; a file over 1 MiB is refused with `file-too-large` (`machines-add-project.ts:77,92-93`; `src/dashboard/server/services/fleet-add-project.ts:114`). +- [SKIP: output format detail] `forward --list` line format `<id> <label>:<port> → <url> (<n> open)`, `No forwards are open.` when empty, and `--stop` prints `Stopped forward <id>.` (`machines.ts:425-433`). +- [ADD] `join`: after `y` it prints `Accepted. The link appears in pan machines list when the approver finishes.`; a rejected or expired request prints `The approval was rejected or expired.` and exits 1; no answer in 10 minutes prints `No machine opened the approval request within 10 minutes.` and exits 1 (`machines.ts:260,274,277`). +- [SKIP: output detail] `versions`: a machine whose report failed gets a `<label>: <error>` line after the table (`machines.ts:372-375`). +- [ADD] `pan tell @<machine>/<conv>` refuses `--force` and `--when-limit-resets` with `<flag> does not work for a conversation on another machine. Nothing was sent.` (`src/cli/commands/tell.ts:32-34`). +- [SKIP: output detail] `unlink --keep-server` on a Fly machine prints `Left the Fly machine behind <target> running (--keep-server). ...` (`machines.ts:176`); the page shows only the destroyed line. +- [SKIP: marked optional] `add-fly`: `--model` is also checked against the codex policy (`harness-unsupported` with the policy reason) (`fly-machine-service.ts:220-223`). Optional. + +#### Links + +- `/configuration/linked-machines` (line 8) OK. +- `#connect` (line 14) OK (`## connect` line 483). +- `/configuration/linked-machines#ssh-machines` (52) OK (heading line 48). +- `/configuration/linked-machines#fly-machines` (113) OK (126). +- `/configuration/linked-machines#codex` (120) OK (240). +- `/configuration/linked-machines#auto-placement` (179) OK (573). +- `/configuration/linked-machines#work-agents-on-fly` (212) OK (212). +- `/configuration/linked-machines#start-work-on-another-machine` (216) OK (523). +- `/cli/agent-commands` (228) OK (`## pan tell` at line 81; could link `/cli/agent-commands#pan-tell`). +- `/configuration/remote-access#find-your-machines-through-overdeck-ai` OK. The planner probed it with `mint broken-links --check-anchors`: the `-overdeck-ai` slug resolves (override O1). +- `docs.json` has 8 `redirects`; `cli/machines` is in navigation (`docs.json:72`). + +#### Follow-ups + +- Code bug: `pan machines add-ssh` maps the SSH `auth-failed` error (HTTP 401) to the internal-token message. `SSH_MACHINE_ERROR_STATUS['auth-failed'] = 401` (`ssh-machine-service.ts:67`) collides with `call()`'s 401 check (`machines-call.ts:29`). Fix: use another status (for example 424) for `auth-failed`, or have `call()` read the body's `error` code before treating 401 as token rejection. +- `pan machines who` and `pan machines add-project` do not map a 401 to the internal-token message; they print `pan machines who failed: ...` with whatever the server said (`machines-who.ts:56-58`, `machines-add-project.ts:71-73`). Minor inconsistency. + +### Appendix E: `cli/pair.mdx` + +Section map: frontmatter 1-4; `# pan pair` 6-21 (usage 8-10, intro 12-15, flags 17-21); `## Output` 23-39; `## Errors` 41-48. + +Suggested title: "pan pair: pair a device with your dashboard" (sidebarTitle "pan pair") +Help section: no. + +#### Change table + +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 2 | "title: pan pair" | Replace line 2 with `title: "pan pair: pair a device with your dashboard"` and add a new line after it: `sidebarTitle: pan pair` | Brief rule 6. | +| 2 | 13-14 | "in the next release (v0.65.0)." | Replace the sentence that starts on line 13 ("The dashboard's **Pair a device** dialog is in the next release (v0.65.0).") with "**Settings → Anywhere → Pair a device** in the dashboard does the same and also shows a QR code." | `changelog.mdx:677,682` v0.65.0 "Settings → Anywhere has **Pair a device**, which makes a pairing link and QR code"; `src/dashboard/frontend/src/components/Settings/sections/AnywhereSection.tsx:79-85` "Pair a device" button; QR still in current code: `Settings/anywhere/PairDeviceDialog.tsx:3,286` "a one-time pairing link, its QR code", "<QrImage link={pairing.link} alt=\"Pairing QR code\" />". | +| 3 | 38 | "URL only works on this machine. With `--json` the warning goes to stderr; the JSON itself" | "URL only works on this machine and tells you to pass `--url` with an address the other device can reach and add that origin to `OVERDECK_TRUSTED_ORIGINS`. With `--json` the warning goes to stderr; the JSON itself" | `src/cli/commands/pairing-link.ts:85` "LOOPBACK_WARNING = 'This URL only works on this machine. Pass --url with an address another device can reach, and add that origin to OVERDECK_TRUSTED_ORIGINS.'" | +| 4 | 45-48 | "pair` needs a dashboard started by `pan up` (a `pan serve` server does not share" | Replace the whole second bullet (lines 45-48) with: "- A dashboard that rejects this machine's internal token: `` The dashboard rejected this machine's internal token (from $OVERDECK_HOME/internal-token, default ~/.overdeck/internal-token). The running dashboard holds a different token: it uses another OVERDECK_HOME, or it was started before that file existed. Restart it with `pan up` or `npx @overdeck/core`, then run this command again. ``, exit 1." | `src/cli/commands/pairing-link.ts:82-84` "TOKEN_REJECTED = 'The dashboard rejected this machine\\'s internal token (from $OVERDECK_HOME/internal-token, default ~/.overdeck/internal-token). ' + 'The running dashboard holds a different token: ...' + 'Restart it with `pan up` or `npx @overdeck/core`, then run this command again.'"; `pair.ts:53` prints it via `fail`. | + +#### Missing + +- [ADD] Any other dashboard error prints `pan pair failed: <message>` and exits 1 (`pairing-link.ts:114`; `pair.ts:45-49,53`). Add as a third bullet under `## Errors`. +- [ADD] The same link also links a machine: run `pan machines link '<url>'` on the other machine (the first use wins, browser or machine). Link to `/cli/machines#link` (`src/dashboard/server/pairing-credentials.ts:13-17` "the same credential also pairs a machine ... whichever side (browser device or machine) uses a code first wins"). +- [ADD] The credential is always in the URL fragment (`#pair=`), never a query string, so it never reaches a server log (`pair.ts:12-13`; `pairing-link.ts:87-90`). +- [ADD] `--label` must be a non-empty string of at most 200 characters, or the dashboard answers 400 (`src/dashboard/server/routes/pairing.ts:51,66-70,85-88`). +- [ADD via D3: use the Glossary help sentence only] Help section: add the Discord and GitHub Issues links (brief step 5). + +#### Links + +- `/configuration/remote-access` (line 14) OK. +- `/cli/devices` (line 15) OK. + +#### Follow-ups + +- None in code. `cli/devices.mdx` shares the stale "next release" note (below). + +### Appendix F: `cli/devices.mdx` + +Section map: frontmatter 1-4; `# pan devices` 6-10; `## list` 12-26; `## revoke` 28-49. + +Suggested title: "pan devices: list and revoke paired devices" (sidebarTitle "pan devices") +Help section: no. + +#### Change table + +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 2 | "title: pan devices" | Replace line 2 with `title: "pan devices: list and revoke paired devices"` and add a new line after it: `sidebarTitle: pan devices` | Brief rule 6. | +| 2 | 8-9 | "Anywhere's **Revoke** has the same effect (next release, v0.65.0)." | Replace the sentence that starts on line 8 ("Settings → Anywhere's **Revoke** has the same effect (next release, v0.65.0).") with "The **Revoke** button in **Settings → Anywhere → Paired devices** does the same." | `changelog.mdx:677,682` v0.65.0 "The section lists paired devices with **Revoke**"; `src/dashboard/frontend/src/components/Settings/anywhere/DevicesPanel.tsx:32,50` "confirmLabel: 'Revoke'", "Paired devices". | +| 3 | 18 | "Lists paired devices with columns `ID NAME CREATED LAST USED REVOKED`." | "Lists paired browser devices and paired phones (the Overdeck app) with columns `ID NAME CREATED LAST USED REVOKED`." | `src/dashboard/server/routes/pairing.ts:13-14` "`GET /api/devices` lists paired devices and paired phones (PAN-4835)", `:180` "records.filter(isPairedDeviceRecord)"; `src/lib/access-tokens.ts:473-474` "(record.kind ?? 'device') === 'device' \|\| record.kind === 'phone'". | +| 4 | 22 | "Print the device array as JSON." | "Print the device array as JSON; each entry has `id`, `name`, `kind` (`device` or `phone`), `scopes`, `createdAt`, `lastUsedAt` and `revokedAt`." (Effect cell of the `--json` row.) | `routes/pairing.ts:161-170` deviceView "{ id, name, kind: record.kind === 'phone' ? 'phone' : 'device', scopes, createdAt, lastUsedAt, revokedAt }"; `pair.ts:83-84` prints it unchanged. | +| 5 | 42 | "With no dashboard running it writes the revocation into `~/.overdeck/access-tokens.json`" | "With no dashboard running it writes the revocation of a paired browser device into `~/.overdeck/access-tokens.json`" and, after the offline output code block (lines 45-47), add: "A phone cannot be revoked this way: with the dashboard down, a phone's id prints `No paired device with id <id>.` Start the dashboard and run the command again." | `src/cli/commands/pair.ts:106` "find((record) => record.id === id && record.kind === 'device')", `:107` "No paired device with id ${id}."; online path accepts phones: `routes/pairing.ts:199` "isPairedDeviceRecord(record)". | + +#### Missing + +- [ADD] A dashboard that rejects the internal token prints the same token message as `pan pair` (see pair.mdx row 4) and exits 1, for both `list` and `revoke` (`pair.ts:79,113`; `pairing-link.ts:82-84`). +- [ADD] Any other dashboard error prints `pan devices list failed: <message>` or `pan devices revoke failed: <message>` and exits 1 (`pair.ts:80,114`). +- [ADD] Revoking a phone also closes its secure-channel connections (`routes/pairing.ts:207` "if (target.kind === 'phone' && target.phoneKey) closeChannelsForPeer(target.phoneKey);"). +- [ADD via D3: use the Glossary help sentence only] Help section: add the Discord and GitHub Issues links (brief step 5). + +#### Links + +- `/configuration/remote-access#list-and-revoke-devices` (line 10) OK (`configuration/remote-access.mdx:177` "## List and revoke devices"). + +#### Follow-ups + +- Code inconsistency: offline `pan devices revoke` matches only `kind === 'device'` (`pair.ts:106`), while the server and `isPairedDeviceRecord` also accept phones and legacy records with no `kind` (`access-tokens.ts:473-474`). A legacy browser device record without `kind` is reported as unknown offline. Fix: use `isPairedDeviceRecord(record)` offline too, and close nothing extra (no connections are open). + +### Appendix G: `configuration/mcp.mdx` + +#### Research context + +Base: feature/pan-5500 at 62f98b27ac6 (v0.89.1). Tool registry: `src/lib/mcp/server.ts:48` (`ALL_TOOLS`), tool files `src/lib/mcp/tools-*.ts`, route scopes `src/dashboard/server/route-scopes.ts`. Every tool name, scope and audience in both tool tables was checked one by one against the `name`/`scope`/`audience` fields; all 27 shared tools and all 26 agent-only tools exist with the scopes the page states. `pan mcp *` and `pan token *` `--help` output (installed 0.89.1) matches the commander definitions and the pages' flag tables exactly. + +Headline: the harness lists are wrong in seven places. `grok` (Grok Build) gets the `overdeck` server, because `GROK_CAPABILITIES` spreads `OPENCODE_CAPABILITIES` (`overdeckMcp: true`) and `GROK_BEHAVIOR` spreads `ACP_BEHAVIOR` (`launchCommandKind: "acp-host"`). `pi` does not get it, because `PI_CAPABILITIES` spreads `OHMYPI_CAPABILITIES` (`overdeckMcp: false`). The page names neither. + +Harness evidence used by rows 2, 12 to 18 below (cite these): +- `packages/contracts/src/harness-capabilities.ts:276` OPENCODE `overdeckMcp: true`; `:281-282` `export const GROK_CAPABILITIES = { ...OPENCODE_CAPABILITIES,` +- `packages/contracts/src/harness-capabilities.ts:155` OHMYPI `overdeckMcp: false`; `:165-166` `export const PI_CAPABILITIES = { ...OHMYPI_CAPABILITIES,` +- `packages/contracts/src/harness-behavior.ts:201` ACP `launchCommandKind: "acp-host"`; `:254-255` `export const GROK_BEHAVIOR = { ...ACP_BEHAVIOR,` +- `src/lib/mcp/agent-injection.ts:149` `new Set(['claude-code', 'acp-host'])`; `src/lib/mcp/overdeck-mcp-gate.ts:12` `getHarnessBehavior(harness).capabilities.overdeckMcp` +- `src/lib/acp/mcp-config.ts:23-24` acp-host skips non-stdio entries: `type ${String(entry.type)} is not stdio` +- `packages/contracts/src/harness-behavior.ts:155-156` `PI_BEHAVIOR = { ...OHMYPI_BEHAVIOR,` so pi keeps `launchCommandKind: "ohmypi-rpc"` and `usesCodexHome: false` (:127, :139): `prepareClaudeOverdeckMcp` returns `{}` and only warns (`agent-injection.ts:159-161`) +- `src/lib/launcher-generator.ts:797` (inside `buildAcpCommand`, :758) `if (config.overdeckMcpConfig) tokens.push('--mcp-config', ...)`: not gated on harness name, so `grok` launches get the file + +Section map: intro 1-26; Tools 27-205 (table 29-57, Agent-only tools 67-108, Secrets 109-136, Machine links 137-167, Memory 168-182, Pull requests 183-205); Over HTTP 206-254; Over stdio 255-294; Sign in with OAuth 295-361; Public MCP for hosted bots 362-459; Agents get these tools 460-533 (What the agent is told 521-533); Project MCP servers 534-638; Pack MCP servers 639-694 (Atlassian auth 683-694); Scopes and the approve scope 695-717; Revoking 718-736; Bots 737-747; Fleet reach 748-782. +Suggested title: "Overdeck MCP server: tools, scopes and agent tokens" (sidebarTitle "MCP server") +Help section: no + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 9 | "machines it is linked to (see Fleet reach)." | "machines it is linked to (see [Fleet reach](#fleet-reach))." | heading `## Fleet reach` at line 748 | +| 2 | 17 | "Every agent Overdeck launches on Claude Code, Codex, `acp` or `opencode` gets" | "Every agent Overdeck launches on Claude Code, Codex, `acp`, `opencode` or `grok` gets" | Harness evidence above (GROK spreads OPENCODE caps and ACP behavior) | +| 3 | 34 | "Pass a page cursor as `before` for older messages." | "Pass a page cursor as `before` for older messages, with an optional `limit` of 1 to 500 rows." | `src/lib/mcp/tools-read.ts:125` `limit: { type: 'integer', minimum: 1, maximum: 500, ...}` (description: How many timeline rows to return with before) | +| 4 | 43 | "or at once if it is not limited" | "or within a minute if it is not limited. Takes `conversation` and `message`" | `src/lib/mcp/tools-schedule.ts:30` "If the conversation is not rate-limited, Overdeck sends it within a minute."; `src/lib/overdeck/scheduled-message-delivery.ts:42` `SCHEDULED_MESSAGES_INTERVAL_MS = 60_000` | +| 5 | 44 | "Not for agent conversations." | "Takes `conversation`. Agent conversations and Session Vault copies cannot be scheduled; at most 20 schedules per conversation." | `src/lib/mcp/tools-schedule.ts:54` "Agent conversations and Session Vault copies cannot be scheduled; at most 20 schedules per conversation."; `:66` `required: ['conversation', 'prompt', 'cron']` | +| 6 | 51 | "Answers a Claude Code permission prompt with `allow-once`, `allow-always` or `deny`." | "Answers a Claude Code permission prompt: `conversation`, the prompt's `signature` from `list_pending_input`, and `choice` (`allow-once`, `allow-always` or `deny`)." | `src/lib/mcp/tools-approve.ts:203-206` `signature: ... 'The prompt signature from list_pending_input.'`, `required: ['conversation', 'signature', 'choice']` | +| 7 | 77 | "Records a worker's report with `status` `done`, `blocked` or `failed`" | "Records a worker's Markdown `report` with `status` `done`, `blocked` or `failed`" | `src/lib/mcp/tools-self.ts:158-161` `report: { type: 'string', description: 'Your report, in Markdown.' }`, `required: ['status', 'report']` | +| 8 | 86 | "Searches memory by running `pan memory search --facts`:" | "Searches memory for `query` (at most 500 characters) by running `pan memory search --facts`:" | `src/lib/mcp/tools-self.ts:313` `query: { type: 'string', maxLength: 500, ...}`, `:316` `required: ['query']` | +| 9 | 106-107 | "Agent-only tools call routes under `/api/self/`, which refuse any token that" | Replace the two-line sentence (lines 106-107) with: "Most agent-only tools call routes under `/api/self/`, which refuse any token that is not an agent token. `lane_status` and `lane_stop` call the lane routes, and `task_cancel` calls the worker stop route after an owner check, so the token's scopes judge those." | `src/lib/mcp/tools-lanes.ts:61` `GET /api/lanes/${...}`; `:74` `POST /api/lanes/${...}/stop`; `src/lib/mcp/tools-delegate.ts:105-108` reads `/api/self/workers/${id}` then posts `/api/fleet/workers/${id}/stop` or `/api/workers/${id}/stop` | +| 10 | 377-378 | "(see Triggers → Publish with" | Replace "(see Triggers → Publish with" plus the next line's "Tailscale Funnel)" with "(see [Publish with Tailscale Funnel](/configuration/triggers#publish-with-tailscale-funnel))" | `configuration/triggers.mdx:94` `## Publish with Tailscale Funnel` | +| 11 | 416 | "Triggers). Every other path gets 404:" | "[Triggers](/configuration/triggers)). Every other path gets 404:" | `configuration/triggers.mdx` exists | +| 12 | 458 | "(see Revoking below)." | "(see [Revoking](#revoking))." | heading `## Revoking` at line 718 | +| 13 | 462 | "Every Claude Code, Codex, Kimi Code ACP (`acp`) and OpenCode (`opencode`) agent" | "Every Claude Code, Codex, Kimi Code ACP (`acp`), OpenCode (`opencode`) and Grok Build (`grok`) agent" | Harness evidence above | +| 14 | 477 | "An ACP agent gets the same `overdeck-mcp.json`." | "An ACP-hosted agent (`acp`, `opencode` or `grok`) gets the same `overdeck-mcp.json`." | `packages/contracts/src/harness-behavior.ts:245-246` `OPENCODE_BEHAVIOR = { ...ACP_BEHAVIOR,`; `:254-255` GROK same; `src/lib/launcher-generator.ts:797` `tokens.push('--mcp-config', ...)` | +| 15 | 516 | "Claude Code, Codex, `acp` and `opencode`. When the token cannot be" | "Claude Code, Codex, `acp`, `opencode` and `grok`. When the token cannot be" | Harness evidence above | +| 16 | 530 | "`kimi-code`, `ohmypi`, `muse`, `prime-agent`, any agent in" | "`pi`, `kimi-code`, `ohmypi`, `muse`, `prime-agent`, any agent in" | `packages/contracts/src/harness-capabilities.ts:165-166` PI spreads OHMYPI (`overdeckMcp: false` at :155); `src/lib/context-layers/materialize.ts:52` `overdeckInstructionsBlock(opts.overdeckMcp === true)` | +| 17 | 599 | "stdio only, through the same `overdeck-mcp.json`." | In the table row that contains this text, change the first cell from "`acp`, `opencode`" to "`acp`, `opencode`, `grok`" | Harness evidence above; `src/lib/acp/mcp-config.ts:23-24` | +| 18 | 600 | "not provisioned. Each launch logs one warning naming the harness" | In the table row that contains this text, change the first cell from "`ohmypi`, `kimi-code`, `muse`, `prime-agent`" to "`pi`, `ohmypi`, `kimi-code`, `muse`, `prime-agent`" | `src/lib/mcp/agent-injection.ts:159-160` non-claude/acp kinds that do not use a Codex home warn; `:234` "harness ${owner.harness} does not provision MCP" | +| 19 | 680 | "none: the ACP host drops http entries" | In the table row that contains this text, change the first cell from "`acp`, `opencode`" to "`acp`, `opencode`, `grok`" | Harness evidence above | +| 20 | 681 | the table row directly below the row containing "none: the ACP host drops http entries" | Change its first cell from "`ohmypi`, `kimi-code`, `muse`, `prime-agent`" to "`pi`, `ohmypi`, `kimi-code`, `muse`, `prime-agent`" | as row 18 | +| 21 | 666 | "launching role's own servers, then the project's `mcp_servers`, then pack" | "launching role's own servers, then the `semgrep` server when Semgrep's MCP server is on (see [Semgrep](/configuration/semgrep#semgrep-mcp-server)), then the project's `mcp_servers`, then pack" | `src/lib/mcp/agent-injection.ts:177` project servers resolved with `semgrep ? [SEMGREP_MCP_SERVER_NAME] : []` reserved; `:185-190` pack reserved names include project and semgrep; `configuration/semgrep.mdx:85` `### semgrep MCP server` | +| 22 | 699 | "start tools and the stop and interrupt tools." | "start tools, the stop, resume and interrupt tools, and `add_skills`." | `src/lib/mcp/tools-write.ts:184` conversation control tools `scope: 'operate'` (stop, resume, interrupt); `:222` add_skills `scope: 'operate'` | +| 23 | 712 | "the keystroke-driven answers and the two answer tools." | "the keystroke-driven answers and the eight answer tools." | `src/lib/mcp/tools-approve.ts:383-393` `APPROVE_TOOLS` holds 8 `answer_*` tools, each `scope: 'approve'`; the page's own line 703 says "any of the eight answer tools" | +| 24 | 758 | "- `start_conversation` and `start_worker` take `machine`: omit it for this machine, give a" | "- `start_conversation`, `start_worker` and `start_issue` take `machine`, and so do the agent tools `delegate_task` and `lane_start`: omit it for this machine, give a" | `src/lib/mcp/tools-write.ts:83,115,152` `machine: MACHINE_PROPERTY`; `src/lib/mcp/tools-delegate.ts:26`; `src/lib/mcp/tools-lanes.ts:35` | + +#### Missing +- [ADD via D3: use the Glossary help sentence only] A troubleshooting / getting-help section linking the Overdeck Discord https://discord.gg/ZpHE2ZTv5P and GitHub Issues https://github.com/eltmon/overdeck/issues. Natural home: after `## Fleet reach`, covering `Unknown tool <name>` (hidden by scope), `HTTP 403: insufficient_scope (missingScope: ...)` (`src/lib/mcp/tool.ts:140-145`), and `[agent-injection] overdeck MCP skipped for <id>: <reason>` (`src/lib/mcp/agent-injection.ts:173`). +- [ADD] "Agents get these tools" does not mention that work agents and the review security lane also get a `semgrep` MCP server when `security.semgrep.mcp` is on; one sentence plus a link to `/configuration/semgrep#semgrep-mcp-server` (`src/lib/mcp/agent-injection.ts:163,182`; changelog.mdx:63). +- [SKIP: reorganization only] Lines 179-181 ("A tool the token's scopes hide answers `Unknown tool <name>`...") sit under `### Memory` but describe every tool; move them to the end of the paragraph at lines 62-65 (no content change). + +#### Links +- /configuration/telemetry OK; /configuration/memory OK; /configuration/projects#project-credentials OK (projects.mdx:382); /configuration/permissions OK; /features/skill-packs OK; /features/skill-packs#atlassian OK (skill-packs.mdx:759 `### atlassian`); /configuration/remote-access OK; /configuration/bots OK; /configuration/bots#connect-in-one-paste OK (bots.mdx:27); /configuration/bots#run-the-overdeck-connector OK (bots.mdx:203); /cli/mcp OK; /configuration/linked-machines OK. +- Same page: #agents-get-these-tools OK (line 460); #atlassian-auth OK (line 683). +- External: https://github.com/eltmon/overdeck/tree/main/integrations/grok-bot (directory exists in repo). +- Unlinked cross references to add: rows 1, 10, 11, 12. +- docs.json: 8 redirects total, none touch these pages; all three pages are in navigation (docs.json:57,73,74). + +#### Follow-ups +- `src/lib/projects/project-mcp.ts:123` warns "the launching role declares a server with this name" for every reserved name, including `semgrep` (reserved at `agent-injection.ts:177`), so a project server named `semgrep` gets a misleading reason. Cosmetic. +- The `grok` gain of the `overdeck` server comes from capability spreads, not an explicit decision; if Grok Build was not meant to get it, that is a code question for the harness owner (`harness-capabilities.ts:281`). + +### Appendix H: `cli/mcp.mdx` + +Section map: intro 1-12; serve 13-58; oauth 59-161 (levels 66-76, issue 78-97, list 98-112, revoke 113-121, pending 122-136, approve 137-152, deny 153-161); connector 162-348 (env and home 174-188, connect 189-283, login 284-297, pair 298-309, serve 310-327, status 328-340, logout 341-348). +Suggested title: "pan mcp: serve MCP, manage OAuth sign-ins and run the connector" (sidebarTitle "pan mcp") +Help section: no + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 41 | "The token is a paired device credential" | "The token is not an API token (a paired device, linked machine, phone or connector credential)" | `src/cli/commands/mcp.ts:98-99` `if (record.kind !== 'token')` refuses every non-token kind; kinds at `src/lib/access-token-records.ts:19` `'device' \| 'token' \| 'machine' \| 'phone' \| 'connector'` | +| 2 | 181 | "The overdeck.ai directory URL when `login` has no `--directory-url`." | "The overdeck.ai directory URL when `login` or `connect` has no `--directory-url`." | `src/lib/mcp/connector/connect-signin.ts:151` `opts.directoryUrl ?? opts.env.OVERDECK_CONNECTOR_DIRECTORY_URL`; `account.ts:47` same for login | +| 3 | 182 | "The overdeck.ai account service URL when `login` has no `--account-url`." | "The overdeck.ai account service URL when `login` or `connect` has no `--account-url`." | `src/lib/mcp/connector/connect-signin.ts:147` `resolveBaseUrl(opts.accountUrl, opts.env)`; `src/lib/account/client.ts:68` `flag ?? env.OVERDECK_ACCOUNT_URL ?? DEFAULT_ACCOUNT_BASE_URL` | +| 4 | 235 | "plugin needs `mcp_allowlist" | Replace "the Overdeck Hermes plugin needs `mcp_allowlist: ["overdeck"]`" with "the Overdeck Hermes plugin needs `plugins.entries.overdeck.mcp_allowlist: ["overdeck"]` in the same file" | `src/lib/mcp/connector/connect-output.ts:160` "The Overdeck Hermes plugin also needs plugins.entries.overdeck.mcp_allowlist: ["overdeck"] in the same file." | +| 5 | 236 | "plugin's summary and chat tools still need the connector's HTTP route" | "plugin's summary and its `overdeck_pending` and `overdeck_answer` tools still need the connector's HTTP route (`serve` and its local token)" | `src/lib/mcp/connector/connect-output.ts:166` "summary and its overdeck_pending and overdeck_answer tools still need the connector's HTTP route (serve and localToken)" | +| 6 | 277 | "usually because it cannot reach TLS 443 or send UDP" | "usually because it cannot reach TLS on turn.cloudflare.com:443 or send UDP" | `src/lib/mcp/connector/connect-output.ts:59` "blocks TLS to turn.cloudflare.com:443 and UDP" | +| 7 | 277 | "if its TURN relay row is ok, use Public MCP or a host with WebRTC egress." | "if its TURN relay row is ok, use Public MCP or a host with WebRTC egress; if that row warns too, the relay is down, so run the command again once it passes. See [no-webrtc-egress](/configuration/bots#no-webrtc-egress)." | `src/lib/mcp/connector/connect-output.ts:59` "if it warns too, the relay is down and this command can be run again once it passes. See https://overdeck.ai/configuration/bots#no-webrtc-egress"; `configuration/bots.mdx:311` `### no-webrtc-egress` | + +#### Missing +- [ADD via D3: use the Glossary help sentence only] A getting-help line or section linking Discord https://discord.gg/ZpHE2ZTv5P and GitHub Issues https://github.com/eltmon/overdeck/issues (none on the page). +- [ADD] `oauth`: an error answer other than 404 prints the dashboard's error text and exits 1 (`src/cli/commands/mcp-oauth.ts:40`). One sentence after line 64. + +#### Links +- /configuration/mcp OK; /configuration/bots OK; /cli/token#create OK (token.mdx:10); /configuration/mcp#sign-in-with-oauth OK (mcp.mdx:295); /configuration/bots#run-the-overdeck-connector OK (bots.mdx:203). + +#### Follow-ups +- None. + +### Appendix I: `cli/token.mdx` + +Section map: intro 1-9; create 10-28; list 29-60; revoke 61-79. +Suggested title: "pan token: create, list and revoke scoped API tokens" (sidebarTitle "pan token") +Help section: no + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 35 | "Lists access tokens with columns `ID NAME SCOPES CREATED LAST USED REVOKED`. Works without a" | "Lists API tokens (your own, agent and OAuth tokens) with columns `ID NAME SCOPES CREATED LAST USED REVOKED`. Paired devices, linked machines, phones and connectors are not listed. Works without a" | `src/cli/commands/token.ts:66` `(await listAccessTokens()).filter((record) => record.kind === 'token')` | +| 2 | 79 | "An unknown id prints `No access token with id <id>.` and exits 1." | "An unknown id prints `No access token with id <id>.` and exits 1. A dashboard that was not started by `pan up` (for example `pan serve`) rejects this machine's internal token; the command then says `pan token revoke` needs a dashboard started by `pan up` and exits 1. Any other refusal prints `pan token revoke failed: <reason>` and exits 1." | `src/cli/commands/token.ts:23` NEEDS_PAN_UP text; `:98` `if (response.status === 401) return fail(NEEDS_PAN_UP)`; `:99` `` fail(`pan token revoke failed: ${...}`) `` | +| 3 | 59 | "(`pruneEndedAccessTokens`, `src/lib/access-tokens.ts`)." | Delete the parenthetical so the sentence ends "still sees the revocation." (internal function name in user docs; the behavior it cites is correct) | `src/lib/access-tokens.ts:547-562`; prune runs in the dashboard (`src/dashboard/server/services/agent-token-sweep.ts:28,99` `AGENT_TOKEN_PRUNE_AFTER_MS = 7 * 24 * 60 * 60_000`) | + +#### Missing +- [ADD via D3: use the Glossary help sentence only] A getting-help line linking Discord https://discord.gg/ZpHE2ZTv5P and GitHub Issues https://github.com/eltmon/overdeck/issues (none on the page). +- [SKIP: marked optional] `create` output shape: the text form prints `Created access token <id>`, `name:` and `scopes:` lines, then the bare token on its own line (`src/cli/commands/token.ts:57-61`). Optional: show it as a sample block. + +#### Links +- /configuration/remote-access#scoped-api-tokens OK (remote-access.mdx:230); /configuration/mcp#agents-get-these-tools OK (mcp.mdx:460); /cli/mcp#oauth OK (cli/mcp.mdx:59). + +#### Follow-ups +- None. + +### Appendix J: `configuration/session-vault.mdx` + +#### Research context + +Overall: flags and subcommands on both CLI pages match the commander definitions and `--help` exactly. The main problems are stale "next release (v0.65.0)" and "planned (PAN-4446)" notes (v0.65.0 shipped 2026-10-04 with all of it), one invented flag (`pan vault exclude --path`), overbroad "every transcript"/"conversations" claims (the vault only handles Claude Code and Codex), and a Tailscale "Ready" step that claims to show the peer list (the dialog does not; the Anywhere section does). + +Section map: frontmatter 1-4; H1 `# Session Vault` 6; intro 8-15; `## Set up the first machine` 17-41; `### From the dashboard` 42-58; `## Join from a second machine` 59-73; `## Passphrase unlock` 74-105; `## Lost a device? Rotate the key` 106-156; `## Save and sync` 157-186; `## Continue on another machine` 187-217; `### From the conversation` 218-243; `### Your uncommitted code comes along` 244-269; `## Exclude what should never leave the machine` 270-278; `## Free local disk space (optional)` 279-297; `## Windows` 298-324; `## Where things live` 325-336 +Suggested title: "Session Vault: encrypted conversation backup and cross-machine resume" (sidebarTitle "Session Vault") +Help section: no + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 14-15 | "Setting up, joining and unlocking the vault happen in a terminal." (replace this sentence and the next one, through "[PAN-4446](https://github.com/eltmon/overdeck/issues/4446)." on line 15) | "Setting up, joining and unlocking the vault also work from the dashboard; see [From the dashboard](#from-the-dashboard)." | `src/dashboard/server/routes/vault.ts:271` "'/api/vault/setup'", `:284` "'/api/vault/join'"; `src/dashboard/frontend/src/components/Settings/sections/SessionVaultSection.tsx:119-128` renders `SessionVaultSetupForm`, `SessionVaultJoinForm mode="join"`, and `mode="unlock"`; `changelog.mdx:683` (v0.65.0) "The same section now sets up a new vault ... joins an existing vault ... unlocks a machine" (#4461) | +| 2 | 160 | "# every transcript on this machine" | "# every Claude Code and Codex transcript on this machine" | `src/lib/vault/discover.ts:65-67` "const [claude, codex] = await Promise.all([discoverClaudeTranscripts(), discoverCodexTranscripts()])"; `:6-8` "walks the two harness homes it can resume itself: Claude Code (`~/.claude/projects/<slug>/<id>.jsonl`) and Codex" | +| 3 | 170 | "With the dashboard running, conversations started from it are saved automatically 30 seconds" | "With the dashboard running, Claude Code and Codex conversations started from it are saved automatically 30 seconds" | `src/dashboard/server/services/vault-settle-poller.ts:71` "conv.status === 'active' && (conv.harness === 'claude-code' \|\| conv.harness === 'codex')"; `src/lib/vault/config.ts:42` "debounceSec: 30" | +| 4 | 171-172 | "no hook is needed. This arrives in the next" | Delete the sentence "This arrives in the next release (v0.65.0)." (end of line 171 and all of line 172); keep "no hook is needed." | `changelog.mdx:677` "<Update label=\"v0.65.0\" description=\"2026-10-04\">", `:683` "Session Vault in the dashboard: ... saved to the vault 30 seconds after they go quiet and synced every 5 minutes" | +| 5 | 180 | "Run `pan vault exclude --path <workspace>` to opt a project's agents out." | "Run `pan vault exclude <workspace path>` to opt a project's agents out." | `src/cli/commands/vault/index.ts:107-112` "command('exclude [path]')" with only `--origin` and `--session`; `pan vault exclude --help` lists no `--path` | +| 6 | 201-202 | "Other harnesses receive a markdown digest of the" (replace line 201's second sentence and all of line 202) | "Session Vault saves only these two harnesses." | Every save path is Claude Code or Codex only: `src/cli/commands/vault/save.ts:93-95` `harnessForPath` returns "'codex' : 'claude-code'"; `discover.ts:65-67`; `vault-settle-poller.ts:71`; `src/dashboard/server/services/vault-agent-subjects.ts:47-50` `HARNESS_BY_KIND` claude/codex; `vault-handoff.ts:91` "Hand-off works for Claude Code and Codex conversations". Machine-link transfers also refuse other harnesses: `conversation-release-service.ts:236-237` `isResumableHarness` (`src/lib/vault/resumable.ts:7-9` claude-code or codex). Caller list: `git grep -n "settle(" -- src` shows only `save.ts:146,192`, `vault-service.ts:274` (poller and hand-off), `conversation-release-service.ts:195`. The digest fallback in `resume.ts:220-227` is unreachable for records this version writes. | +| 7 | 210 | "Browse rows and **Continue here** arrive in the next release (v0.65.0)." | Delete this sentence. | `changelog.mdx:684` (v0.65.0) "Conversations from your other machines", `:685` "Continue here: a read-only copy has a Continue here button" | +| 8 | 295-296 | "Entries marked failed are never deleted. This panel arrives in the next" | Keep "Entries marked failed are never deleted." and delete the sentence "This panel arrives in the next release (v0.65.0)." (end of line 295 and line 296). | `changelog.mdx:683` (v0.65.0) "the transcripts waiting for deletion, which you can review and delete there" | +| 9 | 125 | "Keep passphrase unlock, with the passphrase in this file, for the new key." | "Use passphrase unlock for the new key, with the passphrase in this file. This also turns passphrase unlock on if it was off." | `src/cli/commands/vault/rotate-key.ts:81-85` a file passphrase returns a new wrap regardless of `hasWrap`; `:153` "wrapVaultKey(newKey, plan.passphrase)" | +| 10 | 126 | "Keep passphrase unlock with a generated 6-word passphrase, printed once." | "Use passphrase unlock for the new key with a generated 6-word passphrase, printed once. This also turns passphrase unlock on if it was off." | `rotate-key.ts:86` "if (options.generatePassphrase) return { passphrase: generatePassphrase(), generated: true };" (before the `!hasWrap` check on `:87`) | +| 11 | 263 | "in place, and a checkout with uncommitted changes gets a new workspace for it instead." | "in place, and a checkout with uncommitted changes gets a new workspace for it instead. If that dirty checkout is not a registered project, the dialog cannot make a workspace and shows the `pan vault resume <id> --worktree <dir>` command instead." | `src/dashboard/frontend/src/components/chat/VaultContinueDialog.tsx:139` "has uncommitted changes and is not a registered project, so no workspace can be created for the code snapshot. ... run: pan vault resume ${id8} --worktree <dir>" | +| 12 | 331 | "Backend URL, exclusions, `evict`, `liveQuietMinutes`, `syncIntervalSec` (seconds between dashboard syncs)." | "Backend URL, exclusions, `evict`, `liveQuietMinutes` (minutes a transcript must be quiet before eviction, default 30), `syncIntervalSec` (seconds between dashboard syncs, default 300), `debounceSec` (seconds of quiet before the dashboard saves, default 30) and `wipMaxBytes` (largest code snapshot, default 50 MB)." | `src/lib/vault/config.ts:39-47` "syncIntervalSec: 300, debounceSec: 30, evict: false, liveQuietMinutes: 30, ... wipMaxBytes: 50 * 1024 * 1024"; `src/lib/vault/evict.ts:159-161` liveQuietMinutes gates eviction | +| 13 | 2 | "title: Session Vault" | `title: "Session Vault: encrypted conversation backup and cross-machine resume"` (quoted, the value has a colon) and add `sidebarTitle: Session Vault` | n/a (searchable title) | + +#### Missing +- [ADD via D3: use the Glossary help sentence only] A troubleshooting / getting-help section linking the Overdeck Discord (https://discord.gg/ZpHE2ZTv5P) and GitHub Issues (https://github.com/eltmon/overdeck/issues). Candidates for its content: the vault-off message `Session Vault is off. Run: pan vault setup <git-url>` (`src/lib/vault/config.ts:18`), key-missing `Session Vault backend is set to <backend> but the key file is missing. Run: pan vault join <backend>` (`src/cli/commands/vault/shared.ts:181`), and the key-mismatch line (`shared.ts:185`). +- [ADD] The dashboard's code snapshot is throttled: automatic saves capture code at most once every 5 minutes; `pan vault save` and **Hand off now** always capture (`src/lib/vault/wip-capture.ts:31-32` "WIP_MIN_INTERVAL_SEC = 300"; `vault-settle-poller.ts:144` `'auto'`; `save.ts:198` `wip: 'force'`). +- [ADD] "Where things live" omits `~/.overdeck/vault/allowed-secrets.json` (allowed blocked lines, `src/lib/vault/secrets.ts:22`), `eviction-batch.json` (`evict.ts:34`) and `browse/` (copies of other machines' conversations, `browse.ts:24`). +- [ADD] `pan vault resume` in a script with drift and no `--on-drift` cancels by default (`resume.ts:81` "if (!io.isTTY) return 'cancel';"). + +#### Links +- `/features/conversations#conversations-from-your-other-machines` → OK (`features/conversations.mdx:960` "## Conversations from your other machines"). +- `#where-things-live` → OK (line 325). +- `#from-the-dashboard` (new, row 1) → OK (line 42). +- `https://github.com/eltmon/overdeck/blob/main/docs/SESSION-VAULT.md` → file exists in repo. +- docs.json: page in navigation (`docs.json:51`); 8 redirects total, none for vault. + +#### Follow-ups +- The page repeats the frontmatter title as `# Session Vault` (line 6), so Mintlify shows two titles; same on `configuration/tailscale.mdx:6` and `cli/tailscale.mdx:6`. +- `resume.ts:220-227` keeps a seed-digest path for harnesses no save path can produce; either drop it or document why it stays. + +### Appendix K: `cli/vault.mdx` + +Section map: frontmatter 1-4; intro 6-12; `## setup` 14-28; `## join` 30-42; `## passphrase set` 44-55; `## passphrase remove` 57-63; `## rotate-key` 65-79; `## status` 81-91; `## save` 93-106; `## sync` 108-115; `## list` 117-127; `## show` 129-139; `## resume` 141-157; `## exclude` 159-171; `## include` 173-184; `## allow-secret` 186-197; `## evict` 199-214; `## restore` 216-226; `## In the dashboard` 228-232 +Suggested title: "pan vault: back up and resume agent conversations across machines" (sidebarTitle "pan vault") +Help section: no + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 230-232 | "Settings → Session Vault and **Continue here** are in the next release (v0.65.0). Setting" (replace the whole paragraph, lines 230-232) | "Settings → Session Vault sets up, joins and unlocks a vault, runs **Sync now**, lists the machines and reviews transcripts waiting for deletion. A conversation's ⋮ menu has **Continue on another device**, and a read-only copy from another machine has **Continue here**. See [Session Vault](/configuration/session-vault#from-the-dashboard)." | `changelog.mdx:677` v0.65.0 (2026-10-04), `:683` (#4444, #4461), `:685`, `:686`; `SessionVaultSection.tsx:119-128,158-162,319-325` | +| 2 | 105 | "only this harness (`claude-code`, `codex`, ...)." | "only this harness, `claude-code` or `codex`." | `src/lib/vault/discover.ts:16-19` "harness: 'claude-code' \| 'codex'"; `:65-67` | +| 3 | 103 | "Settle every discovered transcript." | "Save every Claude Code transcript under `~/.claude/projects` and every Codex transcript under `~/.codex/sessions`." | `discover.ts:6-8,33-67` | +| 4 | 165-166 | "Exclude conversations by cwd path, git origin or session id. An excluded saved record" (replace lines 165-166) | "Exclude conversations by cwd path, git origin or session id. With `--session`, the conversation's saved record becomes a tombstone; a path or origin exclusion stops future saves only." | `src/cli/commands/vault/exclude.ts:64-71` path and origin only call `addExclusion`; `:79-81` only `--session` calls `tombstoneRecord` | +| 5 | 87 | "Show backend, this machine, owned records, last sync and the machine list." | "Show the backend, when the key was last rotated, this machine, owned and listed records, last sync, whether eviction is on, and the machine list." | `src/cli/commands/vault/status.ts:48-60` prints "Key rotated:", "Listed records:", "Eviction:" | +| 6 | 2 | "title: pan vault" | "title: \"pan vault: back up and resume agent conversations across machines\"" and add "sidebarTitle: pan vault" | n/a | + +#### Missing +- [ADD via D3: use the Glossary help sentence only] A troubleshooting / getting-help section with the Discord and GitHub Issues links (same candidates as the configuration page). +- [ADD] `rotate-key`: `--passphrase-file` and `--generate-passphrase` also turn passphrase unlock on when it was off (`rotate-key.ts:81-87`); only one of the three passphrase flags may be given (`:59-60,104-108`). +- [ADD] `join`: `--phrase-file` and `--passphrase-file` cannot be combined (`join.ts:303-305`); `setup`: `--passphrase-file` and `--generate-passphrase` cannot be combined (`setup.ts:33-35`). + +#### Links +- `/configuration/session-vault` → OK. `/configuration/session-vault#from-the-dashboard` (new) → OK (`configuration/session-vault.mdx:42`). PAN-4446 link removed by row 1. + +#### Follow-ups +- none + +### Appendix L: `configuration/tailscale.mdx` + +Section map: frontmatter 1-4; H1 `# Tailscale` 6; intro 8-21; `## What Set up Tailscale does` 23-43; `## Per platform` 45-59; `## Userspace mode` 61-87; `## Serve HTTPS and token sign-in` 89-125; `## Funnel on port 8443` 127-139; `## Tailnet settings` 141-147; `## The phone app` 149-154; `## Discovering other machines` 156-169 +Suggested title: "Tailscale: reach your dashboard over HTTPS from your devices" (sidebarTitle "Tailscale") +Help section: no + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 36 | "Shows the Serve address, the phone app QR code and the other Overdeck machines on the tailnet." | "Shows the Serve address and the phone app QR code. Settings → Anywhere then lists the other Overdeck machines on the tailnet (see [Discovering other machines](#discovering-other-machines))." | `src/dashboard/frontend/src/components/Settings/anywhere/TailscaleSetupDialog.tsx:342-349` ready step (`:342-349`) renders only `serveUrl` and `TailscalePhoneQr`; peers panel lives in `AnywhereSection.tsx:97` "{status?.tailscale?.nextStep === 'ready' && <TailscalePeersPanel />}" | +| 2 | 32 | "Tailscale is signed out or stopped." | "Tailscale is not signed in and running." | `src/lib/tailscale/state.ts:224` "if (input.backendState !== 'Running') return 'login';" (any state other than Running) | +| 2b | 32 | "Starts sign-in and shows **Open sign-in**." | "In the dashboard, click **Sign in**, then **Open sign-in**. `pan tailscale setup` prints the sign-in link." | `TailscaleSetupDialog.tsx:302-316` button "Sign in" (`:314`), then link "Open sign-in" (`:308`); `src/cli/commands/tailscale.ts:254` "Open this link to sign in:" | +| 3 | 43 | "operator. Setup then shows the operator step and tries sign-in again once." | "operator. The dashboard then shows the operator step with a **Try signing in again** button; `pan tailscale setup` runs the operator command and retries sign-in once by itself." | `TailscaleSetupDialog.tsx:116-119` 409 with `nextStep === 'operator'` sets the override; `:298` "Try signing in again"; `src/cli/commands/tailscale.ts:263-271` "make us the operator, then retry once" | +| 4 | 55 | "`winget install tailscale.tailscale`, or the [Windows download page](https://tailscale.com/download/windows)." | "Overdeck shows `winget install tailscale.tailscale` and the [Windows download page](https://tailscale.com/download/windows). You run the install, sign in, then press **Check again**." | `src/lib/tailscale/installer.ts:92-98` `kind: 'manual'`, "Install Tailscale for Windows, sign in, then press Check again.", `command: 'winget install tailscale.tailscale'` | +| 5 | 167-169 | "Linking machines arrives with machine links" (replace the whole paragraph, lines 167-169) | "The list has no **Link** action. To link one of these machines, use **Link a machine** in Settings → Anywhere or `pan machines link <pairing-url>`; see [Linked machines](/configuration/linked-machines)." | Machine links shipped in v0.73.0: `changelog.mdx:500` "run `pan pair` on one machine and `pan machines link <url>` on the other" (#4715); `pan machines --help` "link [options] <pairing-url>"; `src/dashboard/frontend/src/components/Settings/anywhere/MachinesPanel.tsx:355` "Link a machine"; `TailscalePeersPanel.tsx:57-67` no Link button | +| 7 | 19 | "Overdeck stores nothing about Tailscale." | "Overdeck keeps no copy of Tailscale's state. The only things setup saves are **Require a token to sign in** and the trusted address `https://<MagicDNS name>`." | `src/lib/tailscale/serve.ts:137` `saveRequireTokenMint`, `:138` `addSavedTrustedOrigin(url, ...)`; `changelog.mdx:682` trusted origins "stored in `~/.overdeck/trusted-origins.json`" | +| 8 | 21 (insert after) | "picks it up." | Insert a new paragraph after line 21: `<Note>Set up Tailscale is new. Its guided steps were not run end to end on a real machine before release. If a step does not work for you, report it on [GitHub Issues](https://github.com/eltmon/overdeck/issues).</Note>` | `changelog.mdx:515` (v0.73.0) "The **Set up Tailscale** step has not been run on a real machine."; no later `changelog.mdx` or `changelog.d/` entry mentions Tailscale verification (grep) | +| 6 | 2 | "title: Tailscale" | "title: \"Tailscale: reach your dashboard over HTTPS from your devices\"" and add "sidebarTitle: Tailscale" | n/a | + +#### Missing +- [ADD via D3: use the Glossary help sentence only] A troubleshooting / getting-help section with the Discord and GitHub Issues links; useful content: Serve refusals "Tailscale Serve already serves something else on port 443..." and "Update Tailscale to 1.52 or later." (`src/lib/tailscale/serve.ts:121,128,132`), and the self-check waits up to 15 s (`serve.ts:32`). +- [ADD] **Set up Tailscale** is also in the command palette (`changelog.mdx:485`). + +#### Links +- `/cli/tailscale` → OK. `#per-platform`, `#serve-https-and-token-sign-in` → OK (headings lines 45, 89). `/configuration/triggers` → OK. `/configuration/mcp#public-mcp-for-hosted-bots` → OK (`configuration/mcp.mdx:362` "## Public MCP for hosted bots"). New: `#discovering-other-machines` → OK (line 156); `/configuration/linked-machines` → OK (file exists, `## Link a machine` at line 17). +- docs.json: in navigation (`docs.json:56`); no redirects for tailscale. + +#### Follow-ups +- Stale UI text: `TailscalePeersPanel.tsx:75` still renders "Linking machines arrives with machine links (#4645)." although machine links shipped in v0.73.0; the file header comment (`:5-6`) says the same. +- PAN-1254 (userspace live check) still gates `USERSPACE_MODE_AVAILABLE = false` (`installer.ts:43`); open state not checked (no tracker call). + +### Appendix M: `cli/tailscale.mdx` + +Section map: frontmatter 1-4; H1 6; synopsis and intro 8-17; `## \`pan tailscale status\`` 19-50; `## \`pan tailscale setup\`` 52-83; `## Exit codes` 85-90; `## Errors` 92-100 +Suggested title: "pan tailscale: check and set up Tailscale access from the terminal" (sidebarTitle "pan tailscale") +Help section: no (has an `## Errors` list, but no help links) + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 48 | "When Tailscale is not installed it prints" | "Without `--json`, when Tailscale is not installed it prints" (rest of the sentence unchanged) | `src/cli/commands/tailscale.ts:95-101` the `--json` branch prints `{ state, peers }` before the `!state.installed` check | +| 2 | 90 | "or the dashboard is not running." | "the dashboard is not running, or setup did not reach ready within 8 steps." | `tailscale.ts:126` "MAX_SETUP_STEPS = 8"; `:321` "Setup did not finish within ${MAX_SETUP_STEPS} steps." | +| 3 | 2 | "title: pan tailscale" | "title: \"pan tailscale: check and set up Tailscale access from the terminal\"" and add "sidebarTitle: pan tailscale" | n/a | + +#### Missing +- [ADD] Errors list lacks the generic stop message `Setup stopped at "<step>". Run \`pan tailscale setup\` again after fixing it.` (`tailscale.ts:318`) and the step-limit message `Setup did not finish within 8 steps. Run \`pan tailscale status\` to see where it stands.` (`:321`), and the `--userspace` text `Installing Tailscale without an administrator password is not available yet. Run \`pan tailscale setup\` without --userspace to use the installer.` (`:125`). +- [ADD via D3: use the Glossary help sentence only] A getting-help section with the Discord and GitHub Issues links. + +#### Links +- `/configuration/tailscale` (x2) → OK. `/configuration/tailscale#userspace-mode` → OK (`configuration/tailscale.mdx:61` "## Userspace mode"). +- docs.json: in navigation (`docs.json:68`). + +#### Follow-ups +- none + +### Appendix N: `configuration/remote-access.mdx` + +#### Research context + +Note on the brief: `docs/SHARED-SESSIONS.md` is not a pointer. It is a 560-line service design doc (slice map, room rules). It points at code (`services/share/`, `packages/contracts/src/sharing*.ts`); I used only the code as proof. + +Replacement convention: when a row says "Replace lines a-b from X through Y", replace exactly that span (X is the grep anchor, Y is the verbatim end of the span). Otherwise replace only the anchor text itself. + +Section map: H1 6; intro + descriptor + Warning 8-41; `## Reach this machine with Tailscale` 43-54; `## Pair a device` 56-175 (`### From the dashboard` 58-73, `### From the terminal` 75-108, `### From the desktop app` 110-129, `### Open one conversation on another screen` 131-148, `### Open the dashboard at a non-default address` 150-175); `## List and revoke devices` 177-196; `## Anywhere status` 198-228; `## Scoped API tokens` 230-293; `## What the LAN can reach` 295-316; `## What the internet can reach` 318-326; `## Local reverse proxies: require_token_mint` 328-363 (`### On automatically` 365-373, `### Use HTTPS` 375-382); `## Find your machines through overdeck.ai` 384-434; `## What pairing is not` 436-443; `## What comes next` 445-454. +Suggested title: "Remote access: pair devices, scoped tokens and network exposure" (sidebarTitle "Remote access") +Help section: no (add a short "Get help" section at the end linking https://discord.gg/ZpHE2ZTv5P and https://github.com/eltmon/overdeck/issues) +Do not rename these headings: other pages link to `#what-the-lan-can-reach` (voice.mdx:193), `#local-reverse-proxies-require_token_mint` (linked-machines.mdx:716), `#find-your-machines-through-overdeck-ai` (linked-machines.mdx:328, cli/machines.mdx:343, anywhere.mdx:187,189), `#scoped-api-tokens` (cli/token.mdx:8, changelog.mdx:680), `#list-and-revoke-devices` (cli/devices.mdx:10), `#from-the-desktop-app` (anywhere.mdx:199). + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 14-18 | "arrive in the next release" | Delete the whole `<Note>` block, lines 14-18 from `<Note>` through `</Note>`. Pairing shipped in v0.64.0; Settings → Anywhere, Settings → Access Tokens and `pan token` shipped in v0.65.0; the page is read on v0.89.1. | `changelog.mdx:677` `<Update label="v0.65.0"`, `:680` "**Scoped API tokens:** `pan token create`", `:681` "**Access tokens in Settings:**", `:682` "**Pair a device from the dashboard:**", `:747` (v0.64.0) "`pan pair --url <address>`" | +| 2 | 23-35 | "\"serverVersion\": \"0.63.0\"," | Replace lines 23-35, from the opening ` ```json ` through "The descriptor contains no paths, usernames or tokens.", with a ` ```json ` block containing (pretty-printed, one key per line as today): `{ "descriptorVersion": 1, "environmentId": "3f0c…", "label": "desk", "platform": { "os": "linux", "arch": "x64" }, "serverVersion": "0.89.1", "protocolVersion": 1, "capabilities": { "pairing": true, "deviceSessions": true, "terminalAuth": true, "machineLinks": true, "phoneApp": true, "connector": true }, "machineKey": "<64 hex>", "linkProtocol": 1, "endpoints": [{ "kind": "tailnet", "url": "wss://desk.tailnet-1234.ts.net/ws/link" }] }`, followed by the paragraph: "The descriptor contains no paths, usernames or tokens. `machineKey` is this machine's public key, and `endpoints` lists the LAN and Tailscale addresses that linked machines can use." | `src/dashboard/server/routes/environment.ts:33-49` builds `capabilities: { pairing, deviceSessions, terminalAuth, machineLinks: true, phoneApp: true, connector: true }, machineKey, linkProtocol: LINK_PROTOCOL_VERSION, endpoints`; `packages/contracts/src/machines.ts:15` `LINK_PROTOCOL_VERSION = 1`, `:35-38` `kind: Schema.Literals(["lan", "tailnet"])`, "`tcp://host:port` or `wss://host[:port]/ws/link`" | +| 3 | 38-40 | "Do not expose a dashboard on a network until" | Keep the `<Warning>` and `</Warning>` lines. Replace the three lines inside it (38-40, from "Do not expose a dashboard on a network until" through "(terminals, RPC, voice) requires a credential.") with: "Every `/ws/*` connection (terminals, RPC, voice) requires a credential, and `GET /api/environment` reports this as `capabilities.terminalAuth: true`. A dashboard older than v0.64.0 does not, so do not expose one on a network." | `src/dashboard/server/ws-auth.ts:27-30` "Every `/ws/*` upgrade requires a credential ... `export const WS_UPGRADE_REQUIRES_CREDENTIAL = true;`" (a constant, always true); `changelog.mdx:764` (v0.64.0) "Every WebSocket connection (terminals, RPC, voice) requires one too" | +| 4 | 174-175 | "A later release discovers and advertises endpoints automatically" | Replace lines 174-175, from "A later release discovers" through "issues/4403))." with: "Machines advertise their LAN and Tailscale addresses to linked machines on their own (see [Linked machines](/configuration/linked-machines)), but browser addresses are still added by hand as described above." | `src/lib/anywhere/endpoints.ts:1-15` "Advertised endpoints (PAN-4645 ...; closes #4403) ... addresses at which this dashboard accepts secure channels"; `src/dashboard/server/routes/origin-validation.ts:49-95` `getTrustedOrigins()` reads env, the Traefik domain and `readSavedTrustedOriginsSync()` only, never the advertised endpoints | +| 5 | 200-201 | "appears in **Settings → Anywhere** and on the **Health** page" | "appears in **Settings → Anywhere** and on the experimental **Health** page" | `src/dashboard/frontend/src/lib/experimentalFeatures.ts:4` `EXPERIMENTAL_TAB_IDS` (includes `health`); `src/dashboard/frontend/src/components/HealthDashboard.tsx:298` `<AnywhereStatusCard` | +| 6 | 212-215 | "which shows the `pan vault setup <git-url>` command to run in a" | Replace lines 212-215, from "Vault, which shows the `pan vault setup" (start of line 212; line 211 ending "**Set up** opens Settings → Session" stays) through "vault is a valid choice, not a problem." with: "Vault, where **Set up a new vault** creates a vault and **Join an existing vault** joins one. Not using the vault is a valid choice, not a problem." | `src/dashboard/frontend/src/components/Settings/sections/SessionVaultSection.tsx:119-124` state `off` renders `<SessionVaultSetupForm>` and `<SessionVaultJoinForm mode="join">`; `SessionVaultSetupForm.tsx:143` "Set up a new vault"; `SessionVaultJoinForm.tsx:68` "Join an existing vault"; `gh issue view 4446` state CLOSED | +| 7 | 223 | "which shows the command to run in a terminal on this machine: `pan vault join <backend>`" | Replace the whole Fix cell of that table row (from "**Open Session Vault** goes to" through "issues/4446). |") with: "**Open Session Vault** goes to Settings → Session Vault, where **Unlock this machine** takes the vault passphrase or the recovery phrase. |" | `SessionVaultSection.tsx:127-128` `key-missing`/`key-mismatch` render `<SessionVaultJoinForm mode="unlock"`; `SessionVaultJoinForm.tsx:2-8` "Unlock ... Posts to `POST /api/vault/join` with the passphrase or the 24-word recovery phrase", `:68` "Unlock this machine" | +| 8 | 227-228 | "which any dashboard credential may" | Replace lines 227-228, from "The card reads" through "call." with: "The card reads `GET /api/anywhere/status`. The root session, a paired device and an `admin` scoped token may call it; a narrower scoped token gets `403`." | `src/dashboard/server/route-scopes.ts:337-346` `requiredScopeFor` returns `row?.scope ?? 'admin'`, and the table has no `/api/anywhere/status` row; `src/dashboard/server/remote-request-gate.ts:150-152` `scopeSatisfies(credentialScopes(credential), required) ? null : { status: 403 ...}`; `src/lib/access-tokens.ts:13` "Pairing always grants `['admin']`" | +| 9 | 256 | "| `operate` | Everything `tell` allows, plus terminal WebSockets (`/ws/terminal`) and starting a conversation or a worker. |" | Replace the whole row with: "| `operate` | Everything `tell` allows, plus terminal WebSockets (`/ws/terminal`), starting a conversation, worker or lane, stopping or resuming a conversation, and changing a conversation's model, effort or compaction. |" | `route-scopes.ts:89-97` `POST /api/conversations`, `/api/workers`, `.../stop`, `.../abort`, `/api/lanes` → `operate`; `:217-220` `switch-model`, `compact`, `thinking-level`, `resume` → `operate`; `src/lib/access-tokens.ts:174-176` operate satisfies tell | +| 10 | 258 | "| `admin` | Everything, like a paired device. |" | Insert three rows immediately before this row (keep the row): "| `read:costs` | Cost summaries, the request digest and one issue's costs. |", "| `read:settings` | The resolved settings (`GET /api/settings/resolved`, secrets shown only as set or not set). |", "| `forward` | Port forwards (`/ws/forward`) for **Open preview**. Only a linked machine's credential uses it. |" | `pan token create --help` "Comma-separated scopes: read:events, read:state, read:conversations, read:costs, read:settings, tell, operate, approve, forward, admin"; `src/lib/access-token-records.ts:6-17` `ACCESS_TOKEN_SCOPES`; `route-scopes.ts:38,146-149` `read:costs`, `read:settings`; `src/dashboard/server/ws-forward.ts:4-6` "Only a caller on a secure channel with a `machine` credential that holds the `forward` scope" | +| 11 | 397-398 | "the plan (Free account or Tester), this month's relay use against the 50 GB" | Replace from "the plan (Free account or Tester), this month's relay use against the 50 GB" (line 397) through "allowance with its reset date," (line 398) with: "the plan (Free account or Tester), the relay line (\"Not included in the free account\" on the free plan, otherwise this month's relay use against the 50 GB allowance with its reset date in UTC)," and keep the following " and **Manage account**, which opens your account page at overdeck.ai." unchanged. | `src/dashboard/frontend/src/components/Settings/anywhere/AccountCard.tsx:31-36` `if (account.plan === 'free') return 'Not included in the free account'` ... "Resets on ... (UTC)"; `accountApi.ts:55-62` `'Free account'`, `'Tester'` | +| 12 | 399-401 | "it opens overdeck.ai in a" | Replace from "**Sign in** appears only in a browser on this machine; it opens overdeck.ai in a" (line 399) through "`pan account login` hint." (line 401) with: "**Sign in** appears only in a browser on this machine, and only while the machine is not signed in. Click it, then click **Open overdeck.ai sign-in**, which opens overdeck.ai in a new tab and returns to `http://127.0.0.1:<port>/oauth/account/callback`. Other devices see the `pan account login` hint." | `AccountCard.tsx:6-8` "Sign in is two steps: the POST answers the overdeck.ai URL, then the card shows a link to open it"; `:52-56` "Open overdeck.ai sign-in"; `:152` `(!account.signedIn \|\| account.tokenRejected) && <SignInArea`; `:44-48` hint "Sign in on this machine with pan account login" | +| 13 | 415 | "- **The relay plan.** When no direct path exists (for example strict firewalls on both sides)," | Replace only "- **The relay plan.**" with "- **The relay plan (invite-only).** Paid plans, the relay plan among them, are invite-only for now." and keep the rest of the bullet. | `AccountCard.tsx:135` "Paid plans are invite-only for now."; `packages/contracts/src/connect.ts:83-85` `planAllowsRelay(plan) { return plan === "tester" \|\| plan === "anywhere_relay" }` (the free plan never relays) | +| 14 | 445-454 | "## What comes next" | Delete the section, lines 445-454 from "## What comes next" through the PAN-4404 line (end of file). PAN-4402, PAN-4403, PAN-4404 and PAN-4645 are all closed and shipped (the desktop app's Connect to a Machine is documented above; SSH machines are `pan machines add-ssh`). Put the new "Get help" section here instead. | `gh issue view` 4402/4403/4404/4645: all CLOSED; `apps/desktop/src/menu.ts:178` "Connect to a Machine…"; `pan machines --help` "add-ssh [options] <host> Link a machine reached over SSH"; `changelog.mdx:503` (v0.73.0) "**SSH machines:**" | + +#### Missing +- [ADD] The Anywhere status card also has a **Directory** row ("Connected (free account)", "Connected", "Connecting", "Refused", "Off") and a **Relay** row; the bullet list at 203-215 omits them. Evidence `AnywhereStatusCard.tsx:64-76,169-181`. +- [ADD] Default trusted origins: the dashboard also trusts `https://<OVERDECK_TRAEFIK_DOMAIN>` when `OVERDECK_TRAEFIK_ENABLED=1` (or the `config.yaml` Traefik domain when no origin env is set), and `localhost:3010`. Evidence `origin-validation.ts:53-84`. One sentence in "Open the dashboard at a non-default address". +- [ADD] Auto-on `require_token_mint` counts only non-loopback addresses saved in `trusted-origins.json`, not `OVERDECK_TRUSTED_ORIGINS`. Evidence `src/lib/remote-access/config.ts:67-70` `readSavedTrustedOriginsSync().some(...)`. Add to line 369 ("a trusted address you added that is not loopback"). +- [SKIP: internal storage detail] The directory also stores each machine's Overdeck version (`serverVersion`) and device id; line 392-394 omits them. Evidence `services/connect/src/directory-state.ts:40-52` `MachineRow { ... serverVersion, deviceId, registeredAt, lastSeenAt }`. +- [ADD] Phones, machine links and Overdeck connectors are also credentials in the same registry (`kind: 'device' | 'token' | 'machine' | 'phone' | 'connector'`, `access-token-records.ts:19`); line 298 lists only four. Link to [Phone app](/configuration/phone) and [Bots](/configuration/bots). +- [ADD via D3: use the Glossary help sentence only] No "Get help" section (Discord + GitHub Issues). + +#### Links +- `/configuration/tailscale` OK; `/configuration/tailscale#serve-https-and-token-sign-in` OK (`tailscale.mdx:89`) +- `/features/desktop-app#open-another-machine` OK (`desktop-app.mdx:124`) +- `/configuration/session-vault` OK; `/configuration/triggers` OK +- `/configuration/mcp#public-mcp-for-hosted-bots` OK (`mcp.mdx:362`) +- `/configuration/linked-machines` OK (x2) +- `#find-your-machines-through-overdeck-ai` OK (line 384) +- External PAN-4403/4434/4446/4402/4404/4645 links resolve but point at closed work; rows 4, 6, 7, 14 remove the stale ones. PAN-4434 (line 335) is fine as a citation. +- docs.json: page listed at `docs.json:52`; 8 `redirects` entries in total, none for this page. + +#### Follow-ups +- `LOOPBACK_WARNING` in `src/cli/commands/pairing-link.ts:16` still tells the user to "add that origin to OVERDECK_TRUSTED_ORIGINS"; the dashboard pair dialog's **Add to trusted addresses** (no restart) is now the easier path. CLI wording only. +- `src/dashboard/server/routes/anywhere.ts:17-18` says the status route "Any dashboard credential may read it", but the gate requires `admin` for scoped tokens (no `route-scopes.ts` row). Either add a `read:state` row or fix the comment. + +### Appendix O: `configuration/shared-sessions.mdx` + +Section map: H1 6; intro 8-9; `## What it is` 11-27; `## Before you start` 29-38; `## Share a conversation` 40-62; `## Join a shared conversation` 64-85 (`### From a terminal` 81-85); `## Join in a browser` 87-105; `## Roles` 107-115; `## Suggestions and contributor prompts` 117-133; `## Hand over control` 135-148; `## What viewers see` 150-181; `## Networks and privacy` 183-189; `## Limits` 191-199. +Suggested title: "Shared sessions: share a live conversation by link" (sidebarTitle "Shared sessions") +Help section: no (add "Get help" at the end with Discord and GitHub Issues links) + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 18 | "In this release:" | "Shared sessions shipped in v0.74.0. What they cover:" | `changelog.mdx:450` `<Update label="v0.74.0"`, `:456` "**Shared Sessions:** share a live conversation with someone else" | +| 2 | 20 | "- Only Claude Code conversations can be shared." | Replace the whole line with: "- Only Claude Code conversations stream. **Share this conversation** appears on every conversation that runs on this machine, but viewers of a conversation from another harness see \"The host's conversation transcript is not available.\" instead of messages." | `src/dashboard/frontend/src/components/chat/sharing/ShareDialog.tsx:62-64` "renders nothing for a conversation this machine does not run" (`runsHere` only, no harness check); `src/dashboard/server/sharing/conversation-bridge.ts:11` "Claude JSONL transcripts only", `:230-237` returns `null` for no Claude session or a Pi file, `:92-96` then sends `{ kind: 'unavailable', reason: 'transcript_not_found' }`; `webrtc-viewer.ts:517-518` → `transcript_unavailable`; `SharedConversationView.tsx:213` "The host's conversation transcript is not available." | +| 3 | 23-25 | "Every admitted viewer can also open the **Terminal** view and watch the conversation's" | Replace lines 23-25, from "- Every admitted viewer can also open" through "calls or thinking the agent prints there.", with: "- A viewer who joins from their own Overdeck can also open the **Terminal** view and watch the conversation's live terminal, read-only. Anything that terminal shows is visible to them, including tool calls or thinking the agent prints there. A browser viewer has no Terminal view." | `services/share/web/main.ts:98-100` "The browser viewer has no terminal (PRD PAN-4481 NonGoals): it never calls setTerminalWatch"; `SharedConversationView.tsx:346` toggle in the local viewer | +| 4 | 43 | "2. Open the ⋮ menu and choose **Share this conversation**, then **Create link**." | Replace the whole line with: "2. Open the ⋮ menu in the conversation header and choose **Share this conversation**, then **Create link**." | `src/dashboard/frontend/src/components/chat/header/ConversationHeaderMenu.tsx:309` `<ShareConversationMenuItem` (its only mount; the row menu has no share item) | +| 5 | 102-103 | "A browser viewer is read-only: it shows the messages and the people in the room, with no" | Replace from "A browser viewer is read-only: it shows the messages and the people in the room, with no" (line 102) through "prompt box." (start of line 103) with: "A browser viewer is read-only: it shows the messages and the people in the room, with no prompt box and no Terminal view." Keep the rest of the paragraph ("If the connection to the host drops, ..."). | `services/share/web/view.ts:7` "The viewer is read-only in this slice: there is no composer"; `services/share/web/main.ts:98` "The browser viewer has no terminal" | + +#### Missing +- [ADD] What the host needs running: `pan share` and the share dialog need the full dashboard (`pan up`); `pan share` never starts one. Evidence `src/cli/commands/sharing/share.ts:5-6`. One line in "Before you start". +- [ADD] The share record lives in `~/.overdeck/shared-sessions.json` (mode 0600) and is re-parked on boot; a corrupt file must be deleted by hand. Evidence `src/lib/sharing/share-record.ts:1-11`, `services/share-host.ts:11`. Useful for troubleshooting. +- [ADD via D3: use the Glossary help sentence only] No "Get help" section (Discord + GitHub Issues). + +#### Links +- `/cli/account` OK (line 32); `#join-in-a-browser` OK (x2, heading line 87); `/cli/share` OK (x2) +- docs.json lists the page (`docs.json:54`); no redirects. + +#### Follow-ups +- **Share this conversation** is offered for non-Claude conversations, and viewers then get only "transcript not available" (`ShareDialog.tsx:62-64` vs `conversation-bridge.ts:230-237`). The menu item could check the harness, or the dialog could warn before **Create link**. +- `docs/SHARED-SESSIONS.md` is a full design doc, not a pointer, contrary to the audit brief's description. + +### Appendix P: `cli/share.mdx` + +Section map: H1 6; intro 8-10; `## pan share` 12-42; `## pan join` 44-96 (`### Without Overdeck installed` 78-86, `### Headless machines` 88-91, `### Token-mint lockdown` 93-96). +Suggested title: "pan share and pan join: share a live conversation by link" (sidebarTitle "pan share and pan join") +Help section: no (add "Get help" at the end with Discord and GitHub Issues links) + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 40 | "- the dashboard is not running (`Start it with pan up`);" | Replace the whole line with: "- the dashboard is not running (`The Overdeck dashboard is not running. Start it with pan up, then run pan share again.`);" | `src/cli/commands/sharing/share.ts:45` exact string | +| 2 | 41-42 | "- the dashboard refuses the share, for example `Sign in with pan account login to share" | Replace lines 41-42, from "- the dashboard refuses the share, for example" through "conversations.` or a conversation that was released to another machine.", with: "- the dashboard refuses the share. The line reads `Cannot share <name>: <reason>`, for example `Sign in with pan account login to share conversations.`, or a refusal for a conversation that was released to another machine." | `share.ts:48-50` `` io.err(`Cannot share ${conversation.name}: ${await errorText(response)}`) ``; `src/dashboard/server/services/share-host.ts:348` "Sign in with pan account login to share conversations."; `routes/shares.ts:104-105` `conversationWriteRefusalBody` → 409 | +| 3 | 60-61 | "4. Opens `http://localhost:<port>/#/shared/<CODE>` in your browser, where you wait in the lobby" | Replace lines 60-61, from "4. Opens `http://localhost:<port>/#/shared/<CODE>`" through "until the host lets you in.", with: "4. Opens `<dashboard URL>/#/shared/<CODE>` (for example `http://localhost:3011/#/shared/BCDFGHJK`) in your browser and prints it as `Shared conversation: <url>`. You wait in the lobby there until the host lets you in." | `src/cli/commands/sharing/join.ts:216-222` `` const url = `${dashboard.apiUrl}/#/shared/${code}` `` ... `` io.out(`Shared conversation: ${url}`) ``; `local-dashboard.ts:78-79` `apiUrl` from `getDashboardApiUrl()` | +| 4 | 90-91 | "`--no-open` prints the URL instead of opening a browser. With no page open, the join closes after" | Replace only the first sentence, "`--no-open` prints the URL instead of opening a browser.", with "`--no-open` prints the URL instead of opening a browser, followed by `Opening the page later rejoins automatically.`" Keep "With no page open, the join closes after about 60 seconds. Opening the URL later rejoins automatically." unchanged. | `join.ts:217-223`; `src/dashboard/server/services/share-join.ts:36` `JOIN_UNSUBSCRIBED_GRACE_MS = 60_000`, `:362,447-465` state `away` | +| 5 | 95-96 | "With `dashboard.require_token_mint: true`, the browser must already be signed in to the dashboard;" | Replace lines 95-96, from "With `dashboard.require_token_mint: true`," through "carries no token.", with: "The URL `pan join` opens carries no token. A browser on this machine still signs in by itself with `dashboard.require_token_mint: true`, so the lobby opens normally. Only a browser that reaches the dashboard through a reverse proxy must already hold a dashboard session or be paired; see [Remote access](/configuration/remote-access#local-reverse-proxies-require_token_mint)." | `join.ts:78` "The browser URL carries no token (D-6)"; `src/dashboard/server/routes/dashboard-auth.ts:481-489` `isTrustedLocalCaller` returns true for a loopback peer without forwarding headers, `:516-519` "A browser on this machine always mints". Anchor form matches the existing link at `configuration/linked-machines.mdx:716` | + +#### Missing +- [SKIP: marked optional] `pan join` prints `Sign in to overdeck.ai to join this conversation.` before the device flow and `Started Overdeck at <url>.` when it auto-starts the dashboard. Evidence `join.ts:160,181`. Optional one line under steps 1-2. +- [ADD] A bad target exits 1 with `Not a share link or join code: <target>. A join code looks like BCDF-GHJK.` Evidence `join.ts:152-155`. Add a sentence after the state table. +- [ADD via D3: use the Glossary help sentence only] No "Get help" section (Discord + GitHub Issues). + +#### Links +- `/configuration/shared-sessions` OK; `/cli/account` OK +- docs.json lists the page (`docs.json:70`); no redirects. + +#### Follow-ups +- None. + +### Appendix Q: `configuration/triggers.mdx` + +#### Research context + +Base: feature/pan-5500 at 62f98b27ac6 (v0.89.1). Installed `pan` 0.89.1. + +**Webhook triggers shipped in v0.73.0 (2026-11-03).** `changelog.mdx:496` `<Update label="v0.73.0" description="2026-11-03">`; `changelog.mdx:511` "**Webhook triggers:** `pan triggers` (or Settings → Anywhere → Triggers) creates a secret URL ... or the directory's webhook inbox holds them for 24 hours while the machine is offline. ([#4700]..., [#4726]...)". The inbox (`--inbox`) shipped in the same release. No `changelog.d/*.md` entry touches triggers or bots (`changelog.d/` holds only pan-5526, pan-5540, pan-5541). + +Section map: frontmatter 1-4; `# Webhook triggers` 6-17 (Note 13-16); `## What a trigger does` 18-35; `## Create a trigger` 36-67; `## Signing secrets` 68-93; `## Publish with Tailscale Funnel` 94-135; `## What the agent sees` 136-158; `## Limits and refusals` 159-186; `## Security` 187-204; `## Hold events with the directory inbox` 205-231; `### What the inbox can see` 232-240. +Suggested title: "Webhook triggers: message or start conversations from GitHub, Stripe or CI" (sidebarTitle "Webhook triggers") +Help section: no (add one; see Missing) + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 14 | "Available from the next release. Manage triggers with [`pan triggers`](/cli/triggers) or" | "Added in v0.73.0. Manage triggers with [`pan triggers`](/cli/triggers) or" | `changelog.mdx:496` "v0.73.0 ... 2026-11-03"; `changelog.mdx:511` "**Webhook triggers:** `pan triggers` (or Settings → Anywhere → Triggers)" | +| 2 | 27-28 | "target needs a prompt template. You can also set the model, harness and effort for the" | "target needs a prompt template. With `pan triggers add` you can also set the model, harness and effort for the" (keep the rest of the sentence; the Add trigger dialog has no model, harness or effort fields) | `src/cli/commands/triggers.ts:235-237` `--model`, `--harness`, `--effort`; `src/dashboard/frontend/src/components/Settings/anywhere/AddTriggerDialog.tsx:100-108` form state has only name, target, template, verify, signingSecret, inbox | +| 3 | 45 | "`--conversation` takes a conversation name or its numeric id; the trigger stores the name." | "`--conversation` takes a conversation name or its numeric id; the trigger stores the name. A trigger name is 1 to 64 characters: letters, digits, spaces, `.`, `_` and `-`." | `src/lib/triggers/store.ts:30` `const NAME_PATTERN = /^[A-Za-z0-9 ._-]{1,64}$/;`, `store.ts:214` "Trigger name must be 1-64 characters from letters, digits, space, ".", "_" and "-"" | +| 4 | 87 | "`set-secret` reads the secret from one line of standard input (or pass `--secret`). Stripe" | "`set-secret` reads the secret from one line of standard input (or pass `--secret`). In the dashboard, click **Set signing secret** on the trigger's row in Settings → Anywhere → Triggers. Stripe" | `src/dashboard/frontend/src/components/Settings/anywhere/TriggersPanel.tsx:96-103` button "Set signing secret" shown when `trigger.verify !== 'none'` | +| 5 | 173-174 | "- **Rate limits.** A project trigger starts at most 6 conversations per rolling hour; a" | "- **Rate limits.** A project trigger handles at most 6 events per rolling hour and a conversation trigger at most 60. Every event that passes the signature and CPU checks counts, including one then refused because the conversation waits for an answer or is gone. The count lives in the dashboard's memory and resets when the dashboard restarts." (replace lines 173-175 whole bullet) | `src/lib/triggers/deliver.ts:38-40` `TRIGGER_PROJECT_STARTS_PER_HOUR = 6`, `TRIGGER_CONVERSATION_MESSAGES_PER_HOUR = 60`; `deliver.ts:188` `recent.push(now);` before step 6; `deliver.ts:207` "Reaching here keeps the reserved rate-limit slot." | +| 6 | 191 | "- **Funnel requests reach only `POST /hooks/*`.** Tailscale marks every funneled request" | "- **Funnel requests reach only `POST /hooks/*`, plus the Public MCP paths while Public MCP is on.** Tailscale marks every funneled request" | `src/dashboard/server/remote-request-gate.ts:130-133` `if (request.method === 'POST' && pathname.startsWith('/hooks/')) return null; return isPublicMcpEnabled() && publicMcpSurface(...) !== null ? null : { status: 404 };` | +| 7 | 212-213 | "- **Create one** with `pan triggers add <name> … --inbox`, or tick **Hold events while this" | "- **Create one** with `pan triggers add <name> … --inbox`, or tick **Hold events while this machine is offline (overdeck.ai inbox, Anywhere plan)** in **Settings → Anywhere → Add trigger**. The checkbox appears only while this machine is signed in, the directory is online and the account's plan includes the inbox." (replace lines 212-213 up to "Add trigger**.") | `AddTriggerDialog.tsx:266` label "Hold events while this machine is offline (overdeck.ai inbox, Anywhere plan)"; `AddTriggerDialog.tsx:263` `{canUseInbox && (`; `src/dashboard/frontend/src/components/Settings/anywhere/directoryApi.ts:32-33` `return directory?.state === 'online' && directory.plan === 'tester';`; `packages/contracts/src/connect.ts:94-95` every paid plan is sent as `tester` | +| 8 | 214-215 | "Funnel URL keeps working too." | "trigger's Funnel URL also works, but neither the dashboard nor `pan triggers add` prints it when you add an inbox; `pan triggers add … --inbox --json` includes it as `hookPath` and `url`." (the word "The" that ends line 214 stays, so the sentence reads "The trigger's Funnel URL also works, ...") | `src/cli/commands/triggers.ts:136-145` inbox path prints only the inbox URL; `AddTriggerDialog.tsx:153-161` shows only "Inbox URL" when `created.inboxUrl`; `src/dashboard/server/routes/triggers.ts:116` response has `hookPath`, `url` | +| 9 | 227-229 | "- **The inbox answers at once** with `202 { \"queued\": true }`; it never waits for this" | Replace the bullet (lines 227-229) with: "- **The inbox answers at once** with `202 { \"queued\": true }`; it never waits for this machine. A full inbox (200 events in this inbox, or 64 MiB for the account) answers `429` with `Retry-After: 3600`. More than 120 events a minute to one inbox answer `429` with `Retry-After: 60`. When the account's plan no longer includes the inbox, it answers `403`." | `services/connect/src/inbox.ts:17-18` `MAX_PENDING_PER_INBOX = 200`, `MAX_SEALED_BYTES_PER_ACCOUNT = 64 * 1024 * 1024`; `inbox.ts:191-192` 429 "inbox full" retryAfter 3600; `services/connect/src/inbox-intake.ts:57-59` 429 `'Retry-After': '60'`; `services/connect/wrangler.jsonc:10` `INBOX_LIMIT ... "limit": 120, "period": 60`; `inbox.ts:169` 403 "the inbox needs the Anywhere plan" | +| 10 | 230 | "- **Removing the trigger** deletes its inbox and every event it holds." | "- **Removing the trigger** in Settings → Anywhere → Triggers deletes its inbox and every event it holds. `pan triggers remove` deletes only the trigger: its inbox keeps accepting events, and this machine discards them because no trigger owns them. Remove inbox triggers from the dashboard." | `src/dashboard/server/routes/triggers.ts:143-148` DELETE route sends `{ type: 'inbox-delete', inboxId }`; `src/cli/commands/triggers.ts:179-189` `runTriggersRemove` calls only `removeTrigger(id)` from the store; `src/lib/triggers/inbox.ts:148-151` no owning record → `ack` ("not found 404") | +| 11 | 239 | "signature check. Its logs name the inbox and the outcome, never the body." | "signature check. Its logs name the message type, the machine and the outcome, never the body or the inbox URL." | `services/connect/src/log.ts:1-8` "a log line names the frame type, the environment id or the phone's client id, and the outcome, and never a label, key, address or payload"; `services/connect/src/directory.ts:261,264` `logFrame('inbox-event', result.event.environmentId, ...)` | + +#### Missing +- [ADD via D3: use the Glossary help sentence only] Troubleshooting / getting help section with the Overdeck Discord https://discord.gg/ZpHE2ZTv5P and GitHub Issues https://github.com/eltmon/overdeck/issues. None present on the page. +- [ADD] Limits table lacks the `400` `{ "error": "could not read event body" }` row for a body stream that fails mid-read. `src/dashboard/server/routes/trigger-hooks.ts:146`. +- [ADD] A conversation that was pulled to another machine (read-only copy) gets `409` from the message door, which the trigger turns into `503` with `Retry-After: 300`, not `410`; senders retry forever. `src/lib/overdeck/conversation-release.ts:88-101` (409 "conversation-released"); `src/lib/triggers/deliver.ts:215-216` only 404/422 map to 410. Could add "or the conversation is read-only on this machine" to the 503 row. +- [ADD] Link the Public MCP mention on line 98 ("see MCP server → Public MCP for hosted bots") to `/configuration/mcp#public-mcp-for-hosted-bots` (heading exists at `configuration/mcp.mdx:362`). +- [ADD] `pan triggers add` for a `stripe` trigger without a secret prints a `set-secret` reminder line. `src/cli/commands/triggers.ts:105-107`. + +#### Links +- `/cli/triggers` (lines 14, 46) OK (`cli/triggers.mdx`). +- `#limits-and-refusals` (line 34) OK (heading line 159). +- `#hold-events-with-the-directory-inbox` (line 183) OK (heading line 205). +- `docs.json` has 8 redirects; none affect these pages. + +#### Follow-ups +- `pan triggers remove` does not delete the trigger's overdeck.ai inbox, so the inbox keeps accepting (202) and the machine silently acks events for a trigger that no longer exists. `src/cli/commands/triggers.ts:179-189` vs `src/dashboard/server/routes/triggers.ts:143-148`. Fix: route `remove` through the dashboard when the record has `inbox`, or have the dashboard reconcile orphan inbox ids. +- Dashboard DELETE comment says "offline, the inbox expires unused" (`routes/triggers.ts:147`), but the Worker expires only events, never inbox rows (`services/connect/src/inbox.ts:246-249`; `inboxes` rows are deleted only by `delete`/`forgetEnvironment`). +- Read-only (pulled) conversation target answers 503 forever instead of 410 (`deliver.ts:215-216`). + +### Appendix R: `cli/triggers.mdx` + +Section map: frontmatter 1-4; heading "# `pan triggers`" 6-16 (Note 8-10); `## add` 17-61; `## list` 62-77; `## remove` 78-91; `## set-secret` 92-110. +Suggested title: "pan triggers: create and manage webhook triggers" (sidebarTitle "pan triggers") +Help section: no (add one; see Missing) + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 9 | "Available from the next release." | "Added in v0.73.0." | `changelog.mdx:496,511` | +| 2 | 13-14 | "an event to a conversation or start a conversation in a project. Every subcommand works" | "an event to a conversation or start a conversation in a project. Every subcommand except `add --inbox` works" (rest of the sentence unchanged) | `src/cli/commands/triggers.ts:16-18` "`add --inbox` ... goes through the running dashboard instead"; `triggers.ts:122` "--inbox needs the running dashboard. Start it with pan up, then retry." | +| 3 | 35 | "as JSON. `url` is `null` when no `.ts.net` address is saved." | "as JSON. `url` is `null` when no `.ts.net` address is saved. With `--inbox`, it prints the dashboard's answer instead: `{ trigger, hookPath, url, urlSecretShownOnce, generatedSigningSecret, inboxUrl }`." (the table cell's closing pipe stays) | `triggers.ts:94-96` (store path JSON); `triggers.ts:132-134` `console.log(JSON.stringify(created))` of the `/api/triggers` body; `src/dashboard/server/routes/triggers.ts:116` `{ trigger, hookPath, url, urlSecretShownOnce: true, generatedSigningSecret, inboxUrl }` | +| 4 | 40-42 | "any generated signing secret, the Funnel command, and then:" | "any generated signing secret, a `set-secret` reminder for a `stripe` trigger without a secret, the Funnel command, and then:" | `triggers.ts:102-109` | +| 5 | 58-59 | "On a free account, signed out, or when the directory does not answer within 10 seconds, it" | "With the dashboard not running, on a free account, signed out, or when the directory does not answer within 10 seconds, it" (rest unchanged) | `triggers.ts:121-125`; `src/dashboard/server/services/directory-inbox.ts:10,22,32`; `src/dashboard/server/routes/triggers.ts:102-110` (trigger removed, 409) | +| 6 | 68-70 | "`conversation <name>` or `project <key>`; `SIGNING SECRET` is `secret set` or" | "`conversation <name>` or `project <key>`; `SIGNING SECRET` is `-` for `none` triggers and `secret set` or" (rest unchanged) | `triggers.ts:170` `t.verify === 'none' ? '-' : t.signingSecretSet ? 'secret set' : 'secret not set'` | +| 7 | 76 | "With no triggers: `` `No triggers. Create one with `pan triggers add`.` ``" | Replace the whole line with the text in "CLI row 7 replacement" below the table (the current nested-backtick inline code renders stray backticks) | `src/cli/commands/triggers.ts:161` prints exactly: No triggers. Create one with (backtick)pan triggers add(backtick). | +| 8 | 84 | "Removes the trigger. Its URL answers `404` from the next event on:" | "Removes the trigger. Its URL answers `404` from the next event on. It does not delete a directory inbox; remove an inbox trigger in Settings → Anywhere → Triggers so its inbox is deleted too:" | `triggers.ts:179-189` (store only); `src/dashboard/server/routes/triggers.ts:143-148` (dashboard sends `inbox-delete`) | +| 9 | 110 | "An empty value exits 1. An unknown id prints `No trigger with id <id>.` and exits 1." | "On success it prints `Set the signing secret for trigger <id>.` An empty value, or one that is not 8 to 256 characters without whitespace, exits 1. An unknown id prints `No trigger with id <id>.` and exits 1." | `triggers.ts:210,218-219`; `src/lib/triggers/store.ts:31,186-189` "Signing secret must be 8-256 characters with no whitespace" | + +CLI row 7 replacement (verbatim, five lines): + +```` +With no triggers it prints: + +``` +No triggers. Create one with `pan triggers add`. +``` +```` + +#### Missing +- [ADD via D3: use the Glossary help sentence only] Getting help section with the Overdeck Discord https://discord.gg/ZpHE2ZTv5P and GitHub Issues https://github.com/eltmon/overdeck/issues. +- [ADD] `add`: trigger name rule (1-64 chars of letters, digits, space, `.`, `_`, `-`). `src/lib/triggers/store.ts:30,214`. + +#### Links +- `/configuration/triggers` (line 15) OK. +- `/configuration/triggers#hold-events-with-the-directory-inbox` (line 60) OK (`configuration/triggers.mdx:205`). + +#### Follow-ups +- Same as triggers page: `pan triggers remove` leaves the overdeck.ai inbox in place. + +### Appendix S: `configuration/bots.mdx` + +Section map: frontmatter 1-4; `# Connect a bot` 6-26; `## Connect in one paste` 27-41; `### Waiting requests` 42-50; `### After the bot connects` 51-58; `## The Connect a bot dialog` 59-92; `## Platforms` 93-94; `### Hermes` 95-122 (line 100 is a YAML comment, not a heading); `### OpenClaw` 123-149; `### Grok Build` 150-168; `### Grok Bot` 169-185; `### xAI API` 186-202; `## Run the Overdeck connector` 203-223; `### The connector home` 224-238; `### The local endpoint` 239-258; `### Routes and reconnects` 259-269; `### What a connector can reach` 270-280; `### Re-pairing and logout` 281-293; `## Tailscale instead of the connector` 294-308; `## Troubleshooting` 309-326 (`### no-webrtc-egress` 311-326); `## Remove a bot` 327-334. +Suggested title: "Connect a bot: give Hermes, OpenClaw or Grok scoped MCP access" (sidebarTitle "Connect a bot") +Help section: yes, `## Troubleshooting`, but it has no Discord or GitHub Issues links (add them; keep the `### no-webrtc-egress` heading, because `src/lib/mcp/connector/connect-output.ts:59` links to `/configuration/bots#no-webrtc-egress`). + +Scope note: the page covers MCP clients only. Overdeck has no Slack, Discord or Telegram bot integration; the supported platforms are exactly the five in `src/dashboard/frontend/src/components/Settings/anywhere/botSnippets.ts:17-23` (Hermes, OpenClaw, Grok Build, Grok Bot, xAI API). A `git grep -i "telegram|discord|slack"` over `src/` and `integrations/*/README.md` finds no chat-platform bot code (only an unrelated `slack_webhook` cloister key at `src/lib/cloister/config.ts:168`). + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 29 | "Pick the bot in **Connect a bot**, pick its access (default Read + Tell), and" | "Pick the bot in **Connect a bot**, pick its access (by default Read state, Read conversations and Send messages), and" | `ConnectBotDialog.tsx:45-51` labels "Read state", "Read conversations", "Send messages", "Operate", "Approve"; `botsApi.ts:17` `BOT_DEFAULT_SCOPES = ['read:state', 'read:conversations', 'tell']` | +| 2 | 63 | "bot** from **Settings → Anywhere → Bots**, or from the command palette." | "bot** from **Settings → Anywhere → Bots**, or from the command palette. Only a browser on this machine can connect or manage bots; a paired device sees \"Only a browser on this machine can manage bots.\"" | `BotsPanel.tsx:183-184` forbidden text; `ConnectBotDialog.tsx:278-279` "Only a browser on this machine can connect bots."; `src/dashboard/server/routes/connectors.ts:5-7` root only; palette row `palette-anywhere-actions.ts:71-77` | +| 3 | 76-77 | "is always on. `operate` and `approve` are off by default. A bot never gets" | "is always on. `operate` and `approve` are off by default. A bot never gets `admin`, `forward`, `read:settings`, `read:costs` or `read:events`, regardless of what is ticked." (replace lines 76-77 through "ticked.") | `src/lib/access-tokens.ts:114-115` connector scopes "never admin, forward, read:settings, read:costs or read:events", enforced at `:407`; `access-tokens.ts:350,439` `OAUTH_FORBIDDEN_SCOPES` adds the same five for OAuth sign-ins; `src/dashboard/frontend/src/components/Settings/anywhere/botsApi.ts:15,20-23` `botScopes` limits Tailscale and This computer tokens to `read:state`, `read:conversations`, `tell`, `operate`, `approve` | +| 4 | 90-91 | "the public URL plus, for the xAI API, the" | "- **Public MCP**: the public URL plus, for the xAI API, the `pan mcp oauth issue` command that mints its token. Public MCP must be on first; while it is off the dialog shows **Show Public MCP settings** instead." (replace lines 90-91) | `ConnectBotDialog.tsx:255-277` "Public MCP is off. Hosted bots need it ..." and button "Show Public MCP settings"; `ConnectBotOutput.tsx` public branch "Get a token" | +| 5 | 148 | "summary and chat tools still need the HTTP config below." | "summary and chat tools still need the HTTP config above." | The HTTP config block is at lines 136-144, before line 148 | +| 6 | 218 | "Signs the connector in to overdeck.ai with the device flow: open the URL it prints and enter the code." | Insert a new table row directly above the `login` row (line 218), with the exact text in "Bots row 6 insert" below the table | `pan mcp connector connect --help` (flags `--name`, `--platform` grok-bot/grok-build/hermes/openclaw/other default other, `--wait` default 120, `--account-url`, `--directory-url`); `src/cli/commands/mcp-connector.ts:2` | +| 7 | 227-230 | "`~/.overdeck-connector`, mode 0700. It holds four files, each mode 0600:" | "`~/.overdeck-connector`, mode 0700. It holds up to five files, each mode 0600:" and, after "`local-token`" on line 230, add ", plus `pending-signin.json` while a `connect` sign-in waits for approval" | `src/lib/mcp/connector/home.ts:4-14` "in five files, each mode 0600 ... `pending-signin.json`: a device sign-in `connect` started"; `home.ts:37` | +| 8 | 289 | "revokes its overdeck.ai sign-in, and deletes the four files. A step that fails" | "revokes its overdeck.ai sign-in, and deletes its files. A step that fails" | `home.ts:303-306` `removeConnectorFiles` deletes `PENDING_SIGNIN_FILE, PAIRING_FILE, LOCAL_TOKEN_FILE, IDENTITY_FILE, ACCOUNT_FILE`; `src/lib/mcp/connector/pair.ts:17-20` "delete the five home files" | +| 9 | 304-305 | "dashboard host on port 443. Each integration README has a \"Tailscale route\"" | "dashboard host on port 443. The Hermes and OpenClaw READMEs have a \"Tailscale route\" section with the exact config." (replace through "section with the exact config." on line 305; keep the Grok Build sentence that follows) | `integrations/hermes/README.md:132` "## Tailscale route"; `integrations/openclaw/README.md:127` "## Tailscale route"; `integrations/grok-build/README.md:136` only the #5029 not-working note; no such heading in `integrations/grok-bot/README.md` | +| 10 | 321 | "use Tailscale instead (`#tailscale-instead-of-the-connector`)." | "use [Tailscale instead of the connector](#tailscale-instead-of-the-connector)." | Heading `## Tailscale instead of the connector` at line 294; current text is inline code, not a link | +| 11 | 323-325 | "How to tell a relay outage from a blocked bot: run `pan doctor` on the" | "How to tell a relay outage from a blocked bot: run `pan doctor` on the machine. The `TURN relay` row appears only when the machine is signed in to overdeck.ai with the relay plan. If the row is `ok`, the block is on the bot's side; if it warns, the relay or the machine's own network is the problem." (replace lines 323-325) | `src/cli/commands/doctor-anywhere-relay.ts:13` `const ROW = 'TURN relay'`; `:31-32` "silent unless this machine is signed in with the relay plan"; `:49` returns `[]` when directory not online or `relay` null | + +Bots row 6 insert (one Markdown table row, verbatim): + +``` +| `pan mcp connector connect '<pairing string>' [--name <bot>] [--platform <id>] [--wait <seconds>] [--account-url <url>] [--directory-url <url>]` | Signs in, pairs, verifies and prints the MCP registration in one command a bot can run again; the message from Connect a bot runs it. `--platform` is `grok-bot`, `grok-build`, `hermes`, `openclaw` or `other` (default). See [`pan mcp connector connect`](/cli/mcp#connect). | +``` + +#### Missing +- [ADD via D3: use the Glossary help sentence only] Getting help: add the Overdeck Discord https://discord.gg/ZpHE2ZTv5P and GitHub Issues https://github.com/eltmon/overdeck/issues to `## Troubleshooting`. +- [ADD] State plainly that there is no native Slack, Discord or Telegram integration (see Scope note above), so readers looking for chat-app bots land on the right expectation. +- [ADD] Link `integrations/hermes/README.md` (lines 117, 121) to https://github.com/eltmon/overdeck/tree/main/integrations/hermes like the other platforms. +- [SKIP: internal timing detail] Waiting requests stay listed for 24 hours past their code's 30-minute expiry, then disappear. `src/dashboard/server/connector-pairing.ts:13-16,30-31`. + +#### Links +- `/configuration/mcp` (line 9) OK. +- `/configuration/mcp#public-mcp-for-hosted-bots` (lines 21, 176, 319) OK (`configuration/mcp.mdx:362`). +- `/cli/mcp#connect` (line 39) OK (`cli/mcp.mdx:189` `### connect`). +- `/configuration/harnesses#grok-build-cli` (line 164) OK (`configuration/harnesses.mdx:768`). +- `/configuration/mcp#sign-in-with-oauth` (line 184) OK (`configuration/mcp.mdx:295`). +- `/cli/mcp#oauth` (line 200) OK (`cli/mcp.mdx:59`). +- `#connect-in-one-paste` (line 172) OK (line 27). +- External: `integrations/openclaw`, `integrations/grok-build`, `integrations/grok-bot`, `integrations/grok-bot/examples` all exist in the repo. +- `#tailscale-instead-of-the-connector` (line 321) is inline code, not a link: see row 10. + +#### Follow-ups +- Stale version pins: `integrations/grok-bot/mcp.json` pins `@overdeck/core@0.77.0`; `integrations/grok-build/scripts/run-mcp.sh` defaults `OVERDECK_CORE_VERSION` to `0.74.0`. Current release is 0.89.1. +- The Connect a bot dialog still offers the Tailscale reach for Grok Build although it does not work (#5029). `botSnippets.ts:20`. +- `src/dashboard/frontend/src/components/Settings/anywhere/directoryApi.ts:33` gates the inbox checkbox on `plan === 'tester'`, relying on the directory sending every paid plan as `tester` (`packages/contracts/src/connect.ts:89-95`); works today but is fragile. + +### Appendix T: `configuration/phone.mdx` + +#### Research context + +Base: feature/pan-5500 at 62f98b27ac6 (v0.89.1). All anchors checked with `grep -c -F` = 1. Renaming phone.mdx `## Before you start` is safe: `git grep 'configuration/phone#'` finds no inbound anchor links. + +Section map: frontmatter 1-4; `# Use Overdeck on your phone` 6-12; `## Before you start` 14-25; `## Set up a phone` 27-30; `### Overdeck app` 32-44; `### Browser on the phone` 46-60; `## Android` 62-66; `## iPhone` 68-79; `## Answer a question` 81-90; `## See the pipeline` 92-102; `## What the phone can and cannot do` 104-129; `## Notifications` 131-155; `## Appearance` 157-169; `## Look and feel` 171-180; `## Diagnostics` 182-195; `## Remove a phone` 197-201; `## Delete your account` 203-211. +Suggested title: keep ("Use Overdeck on your phone" is specific and searchable). +Help section: no. + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 8-12 | "The phone app is a small version of the dashboard at `/m`." | Replace the whole intro paragraph (lines 8-12) with: "Overdeck runs on a phone in two ways. The browser phone view is a small version of the dashboard at `/m`: you install it from the phone's browser to the home screen, and it reaches one machine at that machine's Tailscale HTTPS address. The Overdeck app for iPhone and Android is still in testing (see below) and reaches your machines through overdeck.ai, with no Tailscale. Both show what needs you, your conversations and the pipeline, answer agent questions, and sign in with their own pairing, never with the machine's root token." | The page intro describes only the `/m` web view, but the dialog it documents opens on the native-app tab: `SetUpPhoneDialog.tsx:4-13` "Overdeck app ... native app's pairing QR" / "Browser on the phone ... install Tailscale"; `SetUpPhoneDialog.tsx:336` `useState<'app' \| 'browser'>('app')`; `SetUpPhoneAppPanel.tsx:2-7` "native phone app ... Needs this machine to be signed in to overdeck.ai"; the app runs the same `/m` screens including the Pipeline tab: `apps/mobile/src/shell/MachineView.tsx:2,12,103` ("`MobileApp` runs unchanged"), `MobileApp.tsx:109-111` tabs Needs you / Conversations / Pipeline with no native gate | +| 2 | 14 | "## Before you start" | "## Before you start (browser phone view)" | The two prerequisites (Tailscale Serve, token sign-in) belong to the browser tab only: `SetUpPhoneDialog.tsx:7-13` (BrowserPhoneSetup steps); page line 43-44 itself says "No Tailscale is needed for the app." | +| 3 | 17-18 | "Publish the dashboard port with `tailscale serve`, so the" | "Select **Set up Tailscale** in Settings → Anywhere (or run `pan tailscale setup`) to turn on HTTPS access through Tailscale Serve, so the" | `AnywhereSection.tsx:56-64` button "Set up Tailscale"; `pan tailscale --help`: "setup ... Install Tailscale, sign in and turn on protected HTTPS access to this dashboard" | +| 4 | 25 | "browser on the machine and gives it full access without pairing." | "browser on the machine and gives it full access without pairing. The setting turns on by itself, and cannot be turned off, once the machine has a trusted remote address, a paired device or a machine link. **Set up Tailscale** also turns it on." | `src/lib/remote-access/config.ts:12-18` "on when the YAML says so OR this machine has any remote access at all: a saved non-loopback trusted address, an active paired device, or a machine link ... An explicit `false` cannot turn it off"; `config.ts:76-82`; `RequireTokenMintRow.tsx:30,47-48` `disabled={forcedOn}`; `TailscaleSetupDialog.tsx:330` "This also turns on 'Require a token to sign in'" | +| 5 | 34 | "This machine must be signed in to overdeck.ai first (`pan account login`);" | "Step 1 asks you to install the Overdeck app and sign in to it with the same overdeck.ai account as this machine. This machine must be signed in to overdeck.ai first (`pan account login`);" | `SetUpPhoneAppPanel.tsx:105-107` Step 1 "Install the Overdeck app": "Install Overdeck on the phone and sign in with the same overdeck.ai account as this machine." | +| 6 | 65 | "it. Then select **Install app** at the top of the screen to add it to the home" | "it. Then select **Install app** in the banner below the header to add it to the home" | `MobileChrome.tsx:68-77` `Install app` button rendered by `InstallAffordance`; `MobileChrome.tsx:206-209` "The install hint and the notifications control, below the `/m` header" | +| 7 | 96 | "title. **Needs you** marks an issue that waits for you." | "title, with its project and how long ago it changed. **Needs you** marks an issue that waits for you." | `MobilePipeline.tsx:78-85` row shows `issue.identifier`, `issue.project.name`, `issue.title`, `formatRelativeTime(issue.updatedAt, now)` | +| 8 | 97 | "issue: its phase, state, agent (live, idle or stopped, with its last" | "issue: its phase, state, agent (Live, Idle, Waiting for you, Done or Stopped, with its last" | `issueSheetData.ts:46-53` `DIRECTORY_STATE_LABELS = { working: 'Live', idle: 'Idle', blocked: 'Waiting for you', done: 'Done', stopped: 'Stopped', unknown: 'Status not available' }` | +| 9 | 133 | "In the phone app, tap **Turn on notifications** at the top of the screen and" | "In the browser phone view, tap **Turn on notifications** in the banner below the header, or in Settings (the gear in the header), and" (then add a new sentence after line 134: "In the Overdeck app, turn on **Notifications** in the app's Settings; see [Push notifications](/configuration/push-notifications#on-android) for Android permission.") | `MobileChrome.tsx:171-174` Settings sheet "Notifications" holds `TurnOnNotificationsButton`; `MobileChrome.tsx:206-240` banner below header; native app: `apps/mobile/src/shell/SettingsScreen.tsx:113-124` "Notifications" switch; `MobileChrome.tsx:2-4` "None of it renders in the phone app" | +| 10 | 141-144 | "The browser phone view (`/m`) opens the issue sheet as soon as the machine" | Replace lines 141-144 with: "The installed Overdeck app bundles its own copy of the phone screens, so a change to them reaches the app only with a new app build." | Transitional "new version" note for a released feature: `changelog.mdx:247` "Issue notifications open the issue ... (#5219)" is already in a shipped release; bundling: `apps/mobile/src/shell/ShellApp.tsx:15` imports `src/dashboard/frontend/src/components/mobile/LogoSting` (screens compiled into the app) | +| 11 | 150-152 | "The browser phone view (`/m`) shows this row as soon as the machine runs the new" | Delete from "The browser phone view (`/m`) shows this row" through the end of line 152 ("because the app bundles its own copy of the screens."); keep "machine list to see its items." | Transitional note for a released feature: `changelog.mdx:404` "Can't reach rows in Needs you ... (#5115)" already released; row text verified at `MobileNeedsYou.tsx:164` | +| 12 | 200-201 | "**Revoke** next to the phone. The next time the phone app opens, it shows" | Replace lines 200-201 with: "**Revoke** next to the phone, or select **Remove** under Phones paired with this machine in the Set up a phone dialog's Overdeck app tab. The next time the browser phone view opens, it shows **Pair this phone** again. The Overdeck app shows \"This phone was removed from <machine>. Pair again.\" with **Pair again** and **Forget**." | `DevicesPanel.tsx:50` "Paired devices", `:84` "Revoke"; `PairedPhonesList.tsx:50` "Phones paired with this machine", `:31` "Remove"; `MobilePairScreen.tsx:56` "Pair this phone"; `apps/mobile/src/shell/RemovedScreen.tsx:9-19` "Pair again" / "Forget"; `apps/mobile/src/shell/connection.ts:46` "`This phone was removed from ${label}. Pair again.`" | + +#### Missing +- [ADD via D3: use the Glossary help sentence only] No troubleshooting or getting-help section. Add `## Get help` linking the Overdeck Discord https://discord.gg/ZpHE2ZTv5P and GitHub Issues https://github.com/eltmon/overdeck/issues (brief rule 5). +- [SKIP: minor list detail] Needs you on the phone also shows low-disk rows ("N GiB free · biggest: ... · free space on the desktop"): `MobileNeedsYou.tsx:28-33,166` `diskAlertPhoneText`. +- [ADD] The Overdeck app's Settings lists **Paired machines** with **Forget**, which removes a machine from the phone only; removing the phone on the machine needs Settings → Anywhere: `apps/mobile/src/shell/SettingsScreen.tsx:130-145` "Forget removes a machine from this phone only. Remove the phone on the machine in Settings → Anywhere." +- [ADD] The Set up a phone dialog can also be opened from the command palette ("Set up a phone"): `palette-anywhere-actions.ts:49`. +- [ADD] Needs you on the phone also shows read-only rows for MCP sign-in ("Approve on the desktop"), harness update failures, restart resumes, bot connections and agent requests: `MobileNeedsYou.tsx:167-179`. The page's list at lines 110-113 could add "MCP sign-ins and other machine notices". +- [SKIP: minor hint text] When the browser cannot offer an install prompt, the gear's Install section says "Use your browser menu to add Overdeck to your Home Screen.": `MobileChrome.tsx:87-90`. + +#### Links +- `/configuration/remote-access` (line 19) OK. +- `/configuration/push-notifications` (line 138) OK. +- `/configuration/telemetry` (line 191) OK. +- `https://account.overdeck.ai/account` (line 211) external, matches `ACCOUNT_BASE_URL` + `/account`. +- Suggested new link `/configuration/push-notifications#on-android` (row 9): heading `### On Android` exists at push-notifications.mdx:197. +- docs.json: 8 redirects total; none for these pages. + +#### Follow-ups +- The Overdeck app tab's **App Store** button opens `https://overdeck.ai/configuration/phone-app` (`SetUpPhoneAppPanel.tsx:31`), but there is no `configuration/phone-app.mdx` and no redirect in `docs.json`: the button lands on a 404. Point it at `/configuration/phone` or add a redirect. +- The **Google Play** button opens the public store listing (`SetUpPhoneAppPanel.tsx:25`), but the app is only on the internal testing track (`RELEASE.md:3`), so the listing is not public for non-testers. +- Step 3 of the browser tab reads `/api/settings`, which reports the enforced value (`settings-api.ts:771`), so after step 2 adds a trusted https address the step shows "On" automatically; the dialog never says why. Low priority. + +### Appendix U: `configuration/push-notifications.mdx` + +Section map: frontmatter 1-4; `# Push notifications` 6-11; `## What you get` 13-34; `## How it works` 36-62; `## Set up your phone` 64-86; `## Configuration` 88-119; `## The Overdeck app` 121-141; `### Pause and notification types` 143-175; `### Live Activity (iPhone)` 177-195; `### On Android` 197-223; `## Optional: ntfy` 225-240; `## Privacy` 242-255; `## Recent notifications` 257-276; `## Troubleshooting` 278-306. +Suggested title: "Push notifications: get alerted when an agent needs you" (sidebarTitle "Push notifications") +Help section: yes, `## Troubleshooting`, but it has no Discord or GitHub Issues link. + +#### Change table +| # | Line | Current text (grep anchor) | Change to | Evidence | +|---|------|----------------------------|-----------|----------| +| 1 | 2 | "title: \"Push notifications\"" | "title: \"Push notifications: get alerted when an agent needs you\"" and add "sidebarTitle: \"Push notifications\"" | Generic title (brief rule 6) | +| 2 | 22 | "or free disk space dropped below the alert or critical level (PAN-5093)." | "or free disk space dropped below the alert level (5 GiB by default, `resources.disk_warn_gb`) or the critical level (2 GiB by default, `resources.disk_critical_gb`)." | `disk-alert-service.ts:185` initial `diskAlertThresholds({ diskWarnGb: 5, diskCriticalGb: 2 })`, re-read each poll `:117` `s.thresholds = await s.deps.readThresholds()`; `config-yaml/merge.ts:868` `mergeDiskResources(config.resources, ...)`; keys `disk_warn_gb`/`disk_critical_gb` in `src/lib/config-yaml/__tests__/merge-disk.test.ts:20-21`; `changelog.mdx:430` "below 5 GiB, and again below 2 GiB" | +| 3 | 26 | "does not replay questions that were already waiting." | "does not replay questions or plan approvals that were already waiting a minute before it started. An agent's permission prompt has no start time, so a restart notifies it again." (line 25 "A dashboard restart" stays) | `dispatcher.ts:43` `PRIMING_GRACE_MS = 60_000`; `dispatcher.ts:284-288` `if (item.askedAt === null) return false; ... askedAt < startedAt - PRIMING_GRACE_MS`; `classify.ts:126` agent permission item `askedAt: null`. No test covers a null `askedAt` (`tests/unit/lib/push/dispatcher.test.ts:99-108` primes only items with an old `askedAt`); see Follow-ups | +| 4 | 67-68 | "**Set up Tailscale** action ships, run this on the machine:" | Replace "Until the" (end of line 67) and line 68 with: "Select **Set up Tailscale** in Settings → Anywhere, or run `pan tailscale setup`. To do it by hand, run this on the machine:" | The action shipped: `AnywhereSection.tsx:56-64` "Set up Tailscale"; `TailscaleSetupDialog.tsx:1-9`; `pan tailscale --help` "setup ... turn on protected HTTPS access" | +| 5 | 77-81 | "2. **Pair the phone.** Run `pan pair` and open the link on the phone, or use" | Replace steps 2 and 3 (lines 77-81) with one step: "2. **Pair the phone.** On the machine, open Settings → Anywhere → **Set up a phone** → **Browser on the phone** and follow its steps; see [Phone](/configuration/phone). On iPhone, add the app to the Home Screen first (Safari offers push only to a Home Screen web app, iOS 16.4 or later) and pair inside the installed app, because it cannot use a pairing made in Safari. You can also run `pan pair` and open its link; see [`pan pair`](/cli/pair)." Then renumber step 4 to 3 and step 5 to 4. | Current order (pair in Safari, then install) fails on iPhone: `MobilePairScreen.tsx:2-8` "An installed iPhone app cannot reuse a Safari pairing cookie"; `SetUpPhoneDialog.tsx:297-300` iPhone flow: "1. Open in Safari, then Share → Add to Home Screen" then "2. In the installed app, tap Scan pairing code" | +| 6 | 84 | "Once the phone shell at `/m` ships, the same control is in its header." | "In the browser phone view (`/m`), the same control is in the banner below the header and in Settings (the gear in the header)." | `/m` shipped: `App.tsx:146`; `MobileChrome.tsx:171-174` (Settings sheet Notifications), `:206-240` (banner below header) | +| 7 | 90 | "Push is on by default; subscribing a device is the opt-in. Every key is" | "Push is on by default; subscribing a device is the opt-in. The block goes in `~/.overdeck/config.yaml`. Every key is" | Page never names the file. `needs-you-push-service.ts:105` `loadConfigSync().config.push`; `config-yaml/merge.ts:764` `mergePushConfig(result.push, config)` | +| 8 | 110 | "\| `enabled` \| `true` \| `false` stops every push and the conversation scan. \|" | "\| `enabled` \| `true` \| `false` stops every push except **Send test**, and stops the conversation scan. \|" | `dispatcher.ts:266` `if (!cfg.enabled) return null;` only in `dispatch`; `dispatcher.ts:364-369` `sendNow` has no config check; `needs-you-push-service.ts:242-258` test uses `sendNow` | +| 9 | 112 | "cut to 140 characters, to Web Push notifications. Never sent to ntfy." | "cut to 140 characters, to Web Push and Overdeck app notifications. Never sent to ntfy." | `classify.ts:168-180` `body: preview ?? DEFAULT_BODY[item.kind]`; `native-provider.ts:66-78` sealed payload carries `body: n.body` | +| 10 | 231 | "**titles only**: the kind plus the issue id, or the words `a conversation`." | "**titles only**: the kind plus the issue id, or the words `a conversation`. A low-disk alert sends its own title, such as `Disk low · 3.2 GiB free`." | `disk-alert.ts:87-100` `publicTitle: title` where title is `` `Disk low · ${availableGib} GiB free` ``; `ntfy-provider.ts:43,53` sends `n.publicTitle` | +| 11 | 304 | "**Notifications stopped after many failures.** The panel shows a failure count" | "**A device shows failures.** The panel shows a failure count" | No code stops sending on failures: `subscription-store.ts:200-211` only increments/clears `failureCount`; the only reader is the status view `needs-you-push-service.ts:305` | +| 12 | 305-306 | "for each device. Other `4xx` answers count as failures; a successful send" | Replace lines 305-306 with: "for each device. Other `4xx` answers and network errors count as failures. Overdeck keeps sending to the device, and a successful send clears the count. If the count keeps growing, select **Remove** and tap **Turn on notifications** on that device again." | `webpush-provider.ts:150-168` network error and non-404/410 status both call `recordPushDelivery(record.id, 'failure')`; send loop never skips on count | + +#### Missing +- [ADD via D3: use the Glossary help sentence only] Troubleshooting has no getting-help line. Add at the end: "Still stuck? Ask in the Overdeck Discord (https://discord.gg/ZpHE2ZTv5P) or open a GitHub issue (https://github.com/eltmon/overdeck/issues)." +- [ADD] "There is no Turn on notifications button" omits the fourth reason, "This browser cannot receive push notifications." (no service worker or Push API outside iPhone): `TurnOnNotificationsButton.tsx:24`. +- [ADD] ntfy topic format: the topic must match `^[A-Za-z0-9_-]{1,64}$`, else the panel shows "topic must match ..."; also `url` must be http or https: `push-config.ts:45,85-89`. +- [SKIP: minor status text] The Phone notifications panel's native line also reads "Overdeck app: no phones paired." or "... · not connected to overdeck.ai, so no notifications reach them": `PushPanel.tsx:24-28`. +- [ADD] Setting up the Overdeck app (no Tailscale, pairing by QR) is only linked from `## The Overdeck app`; `## Set up your phone` could say in one line that it covers the browser view and point app users to [Phone](/configuration/phone#overdeck-app) (heading `### Overdeck app` exists at phone.mdx:32). + +#### Links +- `/configuration/remote-access` (lines 75, 76) OK. +- `/cli/pair` (line 78) OK (`cli/pair.mdx` exists; `pan pair --help` matches). +- `/configuration/phone` (line 132) OK. +- `https://ntfy.sh` (line 227) external. +- Suggested new links: `/configuration/phone` (row 5) OK; `/configuration/phone#overdeck-app` (Missing) OK, heading `### Overdeck app` at phone.mdx:32. + +#### Follow-ups +- Likely bug: after a dashboard restart, an agent's pending permission prompt notifies again, because its item has `askedAt: null` (`classify.ts:126`) and `primed()` returns false for null (`dispatcher.ts:285`), so it is dispatched instead of adopted. Untested (`tests/unit/lib/push/dispatcher.test.ts`). The doc row 3 states today's behavior. +- ntfy `Click` header sends `clickBaseUrl` + the item URL, which for a conversation item is `/m?subject=<conversation name>` (`ntfy-provider.ts:47`, `classify.ts:92-94,138`), so the conversation name does reach the ntfy server even though the page promises "Conversation titles ... never reach ntfy". Names are usually not titles, but check whether a user-named conversation leaks through. +- An agent that stops responding with no issue gets the public title `Failed · a conversation` (`classify.ts:164-166,198-216`), which is misleading for an agent; consider `Failed · an agent`. +- Low-disk notifications ignore the ntfy "titles only: kind plus issue id" rule by design (free GiB in the title); fine, but the classifier comment in `classify.ts:7-10` implies otherwise. diff --git a/.pan/specs/2026-11-19-PAN-5500-docs-accuracy-audit-overdeck-anywhere-21-pages.xbrief.json b/.pan/specs/2026-11-19-PAN-5500-docs-accuracy-audit-overdeck-anywhere-21-pages.xbrief.json new file mode 100644 index 00000000000..cd0460467d4 --- /dev/null +++ b/.pan/specs/2026-11-19-PAN-5500-docs-accuracy-audit-overdeck-anywhere-21-pages.xbrief.json @@ -0,0 +1,2256 @@ +{ + "xBRIEFInfo": { + "version": "0.8", + "created": "2026-11-19T03:25:00Z", + "author": "overdeck/0.0.0", + "description": "Plan for PAN-5500: docs: accuracy audit, Overdeck Anywhere (21 pages)", + "updated": "2026-11-19T03:33:49.242Z" + }, + "plan": { + "id": "pan-5500", + "title": "docs: accuracy audit, Overdeck Anywhere (21 pages)", + "status": "proposed", + "uid": "241bbda8-2ad9-4df4-8576-0a1a11ed2789", + "author": "agent:claude-opus-5-5", + "sequence": 2, + "created": "2026-11-19T03:25:00Z", + "updated": "2026-11-19T03:33:49.242Z", + "references": [ + { + "uri": "https://github.com/eltmon/overdeck/issues/5500", + "label": "PAN-5500", + "type": "issue" + }, + { + "uri": "https://github.com/eltmon/overdeck/issues/5467", + "label": "Docs overhaul epic", + "type": "issue" + } + ], + "tags": [ + "docs", + "audit", + "anywhere", + "mintlify" + ], + "metadata": { + "sizeJustification": "Every item edits one Mintlify page in the two Overdeck Anywhere nav groups (anywhere.mdx, ten configuration/ pages, ten cli/ pages); the finalize lint counts each page as its own subsystem, so 21 pages read as many 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.", + "canonicalFilename": "2026-11-19-PAN-5500-docs-accuracy-audit-overdeck-anywhere-21-pages.xbrief.json", + "promotionIntent": "automatic" + }, + "narratives": { + "Problem": "The 21 pages in the Overdeck Anywhere docs nav groups describe features shipped in v0.64.0 to v0.74.0 as 'next release' or 'planned' (about 40 stale labels, including the known triggers note), sell add-ons that do not exist, omit Grok from the MCP harness list, misstate CLI output, error texts and limits, and lack help links and searchable titles.", + "Proposal": "The planning session audited all 21 pages against code and recorded every finding with grep anchor, replacement text and evidence in .pan/drafts/PAN-5500.md (Appendices A to U), with planner overrides (anchor slug probe, billing wording). One docs item per page (anywhere.mdx split into three section items, linked-machines.mdx and mcp.mdx into two, chained by blocks edges because they share a file) applies the change table, the Missing bullets, the dash rule, the D4 title, the help sentence and the link check. A final item runs lint:docs and the Mintlify validators and writes the per-page PR body with Follow-ups for code bugs.", + "NonGoals": "- No code, test, rule, docs.json, CLAUDE.md, README.md, docs/*.md or changelog.d change; code bugs found go to the PR body's Follow-ups\n- No edits to pages outside the two Overdeck Anywhere nav groups\n- No new pages, navigation changes, file renames or slug changes\n- No heading renames except `## Before you start` on phone.mdx (Appendix T row 2); a heading is deleted only where the PRD says so (`## What comes next` on remote-access.mdx)\n- No screenshots or images added or replaced\n- No changes to prices, plan limits, fee tables or competitor figures beyond the listed rows\n- No claim that production billing is on or off\n- No change to the `#find-your-machines-through-overdeck-ai` anchors (they resolve)" + }, + "autoDecisions": [ + { + "summary": "The page asserts neither 'billing is on' nor 'billing is off'; it uses the account page's own wording 'Paid plans are invite-only for now.'", + "rationale": "Creem billing is built but gated on CREEM_* deployment config that is not in the repo (services/account/wrangler.jsonc:30), so production state cannot be verified from code; the invite-only message is code-backed (services/account/src/account-page/page.ts:23)." + }, + { + "summary": "Keep the existing #find-your-machines-through-overdeck-ai anchors and drop the rows that changed them", + "rationale": "Probe with npx mint@4.3.49 broken-links --check-anchors on a scratch site: the -overdeck-ai form resolves and the -overdeckai form is reported broken." + }, + { + "summary": "Every one of the 21 pages gets the same help sentence linking Discord and GitHub Issues", + "rationale": "The issue asks for help links where a page talks about getting help; Anywhere pages are setup pages where failure is the common case, and one sentence keeps the group consistent." + }, + { + "summary": "Retitle 19 generic titles with a sidebarTitle keeping the old nav label; anywhere and phone keep theirs", + "rationale": "The issue requires specific searchable titles; PAN-5501 and PAN-5503 used the same sidebarTitle pattern." + }, + { + "summary": "Add every non-optional Missing bullet briefly; skip bullets the research marked Optional", + "rationale": "The issue asks to add what a user needs that is missing, kept short; Optional bullets are nice-to-have detail." + } + ], + "items": [ + { + "id": "anywhere-plans", + "title": "anywhere.mdx: fix the Note, plans and account claims (lines 1-173)", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "anywhere.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -c 'Paid plans are invite-only for now' anywhere.mdx", + "npm run lint:docs" + ], + "expected_outputs": [ + "the count prints 1 or more", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-A1: apply Appendix A rows 1 to 14 with override O2 (billing wording) to lines 1 to 173. Do not run the whole-page dash or help checks; WI-A3 does." + }, + "items": [ + { + "id": "anywhere-plans.ac1", + "title": "The opening Note names v0.64.0, v0.73.0 and v0.74.0 and contains `Paid plans are invite-only for now.`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "anywhere-plans.ac2", + "title": "`grep -c 'We plan to sell through' anywhere.mdx` returns 0 and the page shows `Paid plans are sold through [Creem](https://www.creem.io) as merchant of record.`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "anywhere-plans.ac3", + "title": "The Plans section shows invited accounts get the **Tester** plan, and the command palette sentence contains **Connect a bot**", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "anywhere-plans.ac4", + "title": "The page shows the hosted vault and `pan vault migrate` as planned with a link to #4297, and the Extra storage line contains `(planned with the hosted vault)`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "anywhere-plans.ac5", + "title": "The deletion paragraph shows that deleting an account cancels any subscription", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "anywhere-shipped-roadmap", + "title": "anywhere.mdx: date every shipped row and roadmap step (lines 175-321)", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "anywhere.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "tr '\\n' ' ' < anywhere.mdx | grep -c 'next release'", + "npm run lint:docs" + ], + "expected_outputs": [ + "the next-release count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-A2: apply Appendix A rows 15 to 44 with overrides O1 (keep the -overdeck-ai anchors) and O2 (row 44 wording)." + }, + "items": [ + { + "id": "anywhere-shipped-roadmap.ac1", + "title": "`tr '\\n' ' ' < anywhere.mdx | grep -c 'next release'` returns 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "anywhere-shipped-roadmap.ac2", + "title": "The What has shipped table contains a row for the native iPhone and Android apps with v0.74.0 and a row for the account page at account.overdeck.ai", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "anywhere-shipped-roadmap.ac3", + "title": "The MCP server row names the `grok` harness, and `grep -c 'remote-access#find-your-machines-through-overdeck-ai' anywhere.mdx` returns 2", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "anywhere-shipped-roadmap.ac4", + "title": "The Roadmap account-service step contains `Paid plans are invite-only for now` and no longer contains `(next`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "anywhere-reasoning-and-page", + "title": "anywhere.mdx: fix the pricing reasoning and run page-wide checks (lines 323-516)", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "anywhere.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' anywhere.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-4", + "FR-6", + "FR-7" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-A3: apply Appendix A rows 45 to 48 and the `[ADD]` Missing bullets, add `## Get help` with the help sentence only (D3), then run the dash rule, frontmatter check and link check over the whole file. The title stays." + }, + "items": [ + { + "id": "anywhere-reasoning-and-page.ac1", + "title": "`grep -c 'It used to end' anywhere.mdx` returns 0 and the Add 50 GB sentence shows the one-time top-up is planned", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "anywhere-reasoning-and-page.ac2", + "title": "The page ends with a `## Get help` section that contains https://discord.gg/ZpHE2ZTv5P and https://github.com/eltmon/overdeck/issues", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "anywhere-reasoning-and-page.ac3", + "title": "The relay-cap paragraph contains `the Anywhere status card in Settings → Anywhere`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "anywhere-reasoning-and-page.ac4", + "title": "`npx -y mint@4.3.49 broken-links --check-anchors --files anywhere.mdx` returns no broken links and the frontmatter still contains `title: \"Overdeck Anywhere: plans and pricing\"`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-account", + "title": "cli/account.mdx: correct base URL, failure messages, JSON output and token file", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "cli/account.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' cli/account.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-B1: apply Appendix B rows 1 to 7 and the `[ADD]` Missing bullets." + }, + "items": [ + { + "id": "audit-account.ac1", + "title": "The base-URL paragraph shows `http` is allowed on `localhost`, `127.0.0.1` or `[::1]`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-account.ac2", + "title": "The failure list contains `Cannot start sign-in at <baseUrl>: HTTP <status>` and `Sign-in failed: <error>`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-account.ac3", + "title": "The `--json` row shows `{\"signedIn\":false}` for a signed-out machine and the token file section lists the version field `v`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-account.ac4", + "title": "The frontmatter shows `title: \"pan account: sign this machine in to overdeck.ai\"` with `sidebarTitle: \"pan account\"`, and the page ends with a `## Get help` section containing the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-account.ac5", + "title": "`grep -nP '[\\x{2013}\\x{2014}]' cli/account.mdx` prints nothing", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "linked-machines-top", + "title": "linked-machines.mdx: fix link request, SSH test, Fly message, fingerprint and remote-control claims (lines 1-425)", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "configuration/linked-machines.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -c 'Decisions panel' configuration/linked-machines.mdx", + "npm run lint:docs" + ], + "expected_outputs": [ + "the count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-3", + "FR-4", + "FR-5" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-C1: apply Appendix C rows 1 to 7, 17 and 18 to lines 1 to 425 (row 16 is dropped by O1). Remove the dashes inside this range." + }, + "items": [ + { + "id": "linked-machines-top.ac1", + "title": "The frontmatter shows `title: \"Linked machines: pair Overdeck machines and work across them\"` with `sidebarTitle: \"Linked machines\"`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "linked-machines-top.ac2", + "title": "`grep -c 'Decisions panel' configuration/linked-machines.mdx` returns 0 and the link-request paragraph names **Needs you**", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "linked-machines-top.ac3", + "title": "The add-fly `--message` step contains `needs \\`--project\\``, and the fingerprint sentence names `pan machines list` and **Inbound** rows", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "linked-machines-top.ac4", + "title": "The Remote control section shows that an agent may message and stop work its own machine started on the other machine", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "linked-machines-top.ac5", + "title": "The Link a fresh server section contains a Note linking #4863, and the relay TLS sentence is followed by `This TCP fallback is covered by tests but has not yet connected on a live Fly VM.`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "linked-machines-bottom", + "title": "linked-machines.mdx: fix fleet versions, --machine fly, placement output and page-wide checks (lines 426-716)", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "configuration/linked-machines.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' configuration/linked-machines.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-C2: apply Appendix C rows 8 to 15 and the `[ADD]` Missing bullets to lines 426 to 716, add the help sentence at the end of `## Troubleshooting` (O4), and run the dash rule and link check over the whole file." + }, + "items": [ + { + "id": "linked-machines-bottom.ac1", + "title": "The Fleet versions table contains a Grok Build row with `grok update` and a Pi row", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "linked-machines-bottom.ac2", + "title": "The CLI paragraph shows `--machine fly` refuses on `pan worker run` and `pan lane start` and starts a Fly work agent on `pan start`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "linked-machines-bottom.ac3", + "title": "The `Passed over:` line is attributed to `pan lane start`, and the Fleet usage paragraph shows the Costs page is experimental behind Settings → Experimental", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "linked-machines-bottom.ac4", + "title": "`grep -nP '[\\x{2013}\\x{2014}]' configuration/linked-machines.mdx` prints nothing and the `## Troubleshooting` section contains https://discord.gg/ZpHE2ZTv5P and https://github.com/eltmon/overdeck/issues", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-machines", + "title": "cli/machines.mdx: correct error remedies, reboot timing, Update all and directory output", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "cli/machines.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' cli/machines.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-D1: apply Appendix D rows 1 to 6 and 8 to 16 (row 7 is dropped by O1; row 16 is the #4863 connect Note) and the `[ADD]` Missing bullets." + }, + "items": [ + { + "id": "audit-machines.ac1", + "title": "The add-fly error table contains a `fly-token-rejected` row and the `auth-failed` remedy names `pan machines test-ssh <host>`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-machines.ac2", + "title": "`grep -c 'within about 15 minutes' cli/machines.mdx` returns 0 and the reboot paragraph shows a back-off of at most about 45 seconds", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-machines.ac3", + "title": "The Update all sentence names Pi and Grok Build and shows npm installs update through npm, and the watchdog sentence contains `within five minutes`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-machines.ac4", + "title": "The `## connect` section contains a Note that links #4863 and says the systemd service has not been tested end to end on a real VPS", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-machines.ac5", + "title": "The frontmatter shows `title: \"pan machines: link, list and update your machines\"` with `sidebarTitle: \"pan machines\"`, `### Troubleshooting` contains the Discord link, `grep -nP '[\\x{2013}\\x{2014}]' cli/machines.mdx` prints nothing, and `grep -c 'remote-access#find-your-machines-through-overdeck-ai' cli/machines.mdx` returns 1", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-pair", + "title": "cli/pair.mdx: replace the stale release note and correct error texts", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "cli/pair.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' cli/pair.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-E1: apply Appendix E rows 1 to 4 (row 3 evidence per O3) and the `[ADD]` Missing bullets." + }, + "items": [ + { + "id": "audit-pair.ac1", + "title": "`tr '\\n' ' ' < cli/pair.mdx | grep -c 'next release'` returns 0 and the page names **Settings → Anywhere → Pair a device**", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-pair.ac2", + "title": "The loopback warning sentence contains `OVERDECK_TRUSTED_ORIGINS`, and the Errors list contains `pan pair failed: <message>`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-pair.ac3", + "title": "The page shows the same pairing link also links a machine with `pan machines link`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-pair.ac4", + "title": "The frontmatter shows `title: \"pan pair: pair a device with your dashboard\"` with `sidebarTitle: \"pan pair\"`, and `## Errors` ends with the Discord help sentence", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-devices", + "title": "cli/devices.mdx: remove the stale release note and cover paired phones", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "cli/devices.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' cli/devices.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-F1: apply Appendix F rows 1 to 5 and the `[ADD]` Missing bullets." + }, + "items": [ + { + "id": "audit-devices.ac1", + "title": "`tr '\\n' ' ' < cli/devices.mdx | grep -c 'next release'` returns 0 and the page names **Settings → Anywhere → Paired devices**", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-devices.ac2", + "title": "The `list` row shows paired phones too and the `--json` row lists the `kind` field (`device` or `phone`)", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-devices.ac3", + "title": "The revoke section shows a phone cannot be revoked while the dashboard is down", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-devices.ac4", + "title": "The frontmatter shows `title: \"pan devices: list and revoke paired devices\"` with `sidebarTitle: \"pan devices\"`, and the page ends with `## Get help` containing the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "mcp-top", + "title": "mcp.mdx: fix harness list, tool parameters and agent-only routes (lines 1-460)", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "configuration/mcp.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -c 'within a minute' configuration/mcp.mdx", + "npm run lint:docs" + ], + "expected_outputs": [ + "the count prints 1 or more", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-3", + "FR-4", + "FR-6" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-G1: apply Appendix G rows 1 to 12 to lines 1 to 460. Remove the dashes inside this range." + }, + "items": [ + { + "id": "mcp-top.ac1", + "title": "The agents sentence near the top contains Claude Code, Codex, `acp`, `opencode` and `grok`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "mcp-top.ac2", + "title": "The `schedule_message` row contains `within a minute` and the `answer_permission` row names the `signature` parameter", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "mcp-top.ac3", + "title": "The `worker_report` row contains the Markdown `report` parameter and the `memory_search` row contains `query`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "mcp-top.ac4", + "title": "The agent-only routes sentence names `lane_status`, `lane_stop` and `task_cancel`, and the page links `#fleet-reach` and `#revoking`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "mcp-bottom", + "title": "mcp.mdx: fix provisioning tables, scopes and fleet reach, then page-wide checks (lines 461-782)", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "configuration/mcp.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' configuration/mcp.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-G2: apply Appendix G rows 13 to 24 and the `[ADD]` Missing bullets to lines 461 to 782, add `## Get help` after `## Fleet reach` (D3), apply the D4 title, and run the dash rule and link check over the whole file." + }, + "items": [ + { + "id": "mcp-bottom.ac1", + "title": "Every provisioned-harness table row and list in the section contains `grok`, and both not-provisioned rows contain `pi` as the first harness", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "mcp-bottom.ac2", + "title": "`grep -c 'the two answer tools' configuration/mcp.mdx` returns 0 and the page contains `the eight answer tools`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "mcp-bottom.ac3", + "title": "The precedence sentence contains the `semgrep` server and the fleet-reach list contains `start_issue`, `delegate_task` and `lane_start`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "mcp-bottom.ac4", + "title": "The frontmatter shows `title: \"Overdeck MCP server: tools, scopes and agent tokens\"` with `sidebarTitle: \"MCP server\"`, and `## Get help` contains the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "mcp-bottom.ac5", + "title": "`grep -nP '[\\x{2013}\\x{2014}]' configuration/mcp.mdx` prints nothing", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-cli-mcp", + "title": "cli/mcp.mdx: correct refusal kinds, URL variables, Hermes key and relay advice", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "cli/mcp.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' cli/mcp.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-H1: apply Appendix H rows 1 to 7 and the `[ADD]` Missing bullets." + }, + "items": [ + { + "id": "audit-cli-mcp.ac1", + "title": "The refusal row shows any token that is not an API token is refused", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-cli-mcp.ac2", + "title": "The page contains `plugins.entries.overdeck.mcp_allowlist` and the URL variable rows name both `login` and `connect`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-cli-mcp.ac3", + "title": "The `no-webrtc-egress` advice covers the relay-down case and links `/configuration/bots#no-webrtc-egress`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-cli-mcp.ac4", + "title": "The frontmatter shows `title: \"pan mcp: serve MCP, manage OAuth sign-ins and run the connector\"` with `sidebarTitle: \"pan mcp\"`, and `## Get help` contains the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-token", + "title": "cli/token.mdx: list scope, revoke refusal and internal name", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "cli/token.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' cli/token.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-I1: apply Appendix I rows 1 to 3 and the `[ADD]` Missing bullets (the create output sample is optional; skip it)." + }, + "items": [ + { + "id": "audit-token.ac1", + "title": "The `list` sentence shows only API tokens are listed and paired devices, machines, phones and connectors are not", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-token.ac2", + "title": "The revoke section shows the refusal from a dashboard not started by `pan up`, and `grep -c pruneEndedAccessTokens cli/token.mdx` returns 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-token.ac3", + "title": "The frontmatter shows `title: \"pan token: create, list and revoke scoped API tokens\"` with `sidebarTitle: \"pan token\"`, and `## Get help` contains the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-session-vault", + "title": "session-vault.mdx: remove stale release notes and limit harness claims", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "configuration/session-vault.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' configuration/session-vault.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-J1: apply Appendix J rows 1 to 13 and the `[ADD]` Missing bullets. Keep the heading `## Save and sync`." + }, + "items": [ + { + "id": "audit-session-vault.ac1", + "title": "`tr '\\n' ' ' < configuration/session-vault.mdx | grep -c 'next release'` returns 0 and `grep -c 4446 configuration/session-vault.mdx` returns 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-session-vault.ac2", + "title": "`grep -c 'exclude --path' configuration/session-vault.mdx` returns 0 and `grep -c 'markdown digest' configuration/session-vault.mdx` returns 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-session-vault.ac3", + "title": "The save section contains `every Claude Code and Codex transcript`, and both rotate-key passphrase lines contain `turns passphrase unlock on if it was off`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-session-vault.ac4", + "title": "The Where things live section contains `debounceSec` and `wipMaxBytes` with defaults, and the page preserves the heading `## Save and sync`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-session-vault.ac5", + "title": "`grep -nP '[\\x{2013}\\x{2014}]' configuration/session-vault.mdx` prints nothing, the frontmatter shows the D4 title with `sidebarTitle: \"Session Vault\"`, and `## Get help` contains the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-vault", + "title": "cli/vault.mdx: describe the shipped dashboard features and correct save, exclude and status", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "cli/vault.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' cli/vault.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-K1: apply Appendix K rows 1 to 6 and the `[ADD]` Missing bullets." + }, + "items": [ + { + "id": "audit-vault.ac1", + "title": "`tr '\\n' ' ' < cli/vault.mdx | grep -c 'next release'` returns 0 and the In the dashboard paragraph names **Continue on another device** and **Continue here**", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-vault.ac2", + "title": "The `--harness` row shows `claude-code` or `codex` and the exclude section shows a tombstone only with `--session`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-vault.ac3", + "title": "The `status` row names the key-rotation date, listed records and eviction state", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-vault.ac4", + "title": "The frontmatter shows `title: \"pan vault: back up and resume agent conversations across machines\"` with `sidebarTitle: \"pan vault\"`, and `## Get help` contains the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-tailscale", + "title": "tailscale.mdx: correct the setup steps, stored state and machine-link note, and add the maturity note", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "configuration/tailscale.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' configuration/tailscale.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-L1: apply Appendix L rows 1 to 8 (including 2b) and the `[ADD]` Missing bullets." + }, + "items": [ + { + "id": "audit-tailscale.ac1", + "title": "The Ready step no longer claims to list other machines and points to Settings → Anywhere, and the sign-in step names **Sign in** then **Open sign-in**", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-tailscale.ac2", + "title": "`grep -c 'Linking machines arrives with machine links' configuration/tailscale.mdx` returns 0 and `grep -c 'Overdeck stores nothing about Tailscale' configuration/tailscale.mdx` returns 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-tailscale.ac3", + "title": "The page contains a Note that Set up Tailscale was not run end to end on a real machine before release, and the operator step names **Try signing in again**", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-tailscale.ac4", + "title": "The Windows row shows Overdeck shows the `winget` command and you run it yourself", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-tailscale.ac5", + "title": "The frontmatter shows `title: \"Tailscale: reach your dashboard over HTTPS from your devices\"` with `sidebarTitle: \"Tailscale\"`, and `## Get help` contains the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-cli-tailscale", + "title": "cli/tailscale.mdx: correct status output and exit cases, add missing errors", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "cli/tailscale.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' cli/tailscale.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-M1: apply Appendix M rows 1 to 3 and the `[ADD]` Missing bullets." + }, + "items": [ + { + "id": "audit-cli-tailscale.ac1", + "title": "The not-installed sentence contains `Without \\`--json\\``, and the exit-code list contains the case where setup does not reach ready within 8 steps", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-cli-tailscale.ac2", + "title": "The Errors list contains `Setup stopped at`, `Setup did not finish within 8 steps` and the `--userspace` not-available message, and ends with the Discord help sentence", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-cli-tailscale.ac3", + "title": "`grep -nP '[\\x{2013}\\x{2014}]' cli/tailscale.mdx` prints nothing and the frontmatter shows the D4 title with `sidebarTitle: \"pan tailscale\"`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-remote-access", + "title": "remote-access.mdx: remove stale notes and roadmap, update the descriptor and scope table", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "configuration/remote-access.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' configuration/remote-access.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-N1: apply Appendix N rows 1 to 14 and the `[ADD]` Missing bullets. Keep every heading other pages link to (listed in the PRD)." + }, + "items": [ + { + "id": "audit-remote-access.ac1", + "title": "`tr '\\n' ' ' < configuration/remote-access.mdx | grep -c 'next release'` returns 0 and `grep -c '\"serverVersion\": \"0.63.0\"' configuration/remote-access.mdx` returns 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-remote-access.ac2", + "title": "The scope table contains rows for `read:costs`, `read:settings` and `forward`, and the status-card paragraph shows a scoped token needs `admin` for `GET /api/anywhere/status`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-remote-access.ac3", + "title": "The page names the **Health** page as experimental, shows the relay plan is invite-only, and describes Session Vault setup and unlock from the dashboard", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-remote-access.ac4", + "title": "`grep -c '## What comes next' configuration/remote-access.mdx` returns 0 and the page ends with `## Get help` containing the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-remote-access.ac5", + "title": "`grep -nP '[\\x{2013}\\x{2014}]' configuration/remote-access.mdx` prints nothing and the frontmatter shows the D4 title with `sidebarTitle: \"Remote access\"`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-shared-sessions", + "title": "shared-sessions.mdx: date the release and correct harness and terminal claims", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "configuration/shared-sessions.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' configuration/shared-sessions.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-O1: apply Appendix O rows 1 to 5 and the `[ADD]` Missing bullets." + }, + "items": [ + { + "id": "audit-shared-sessions.ac1", + "title": "`grep -c 'In this release:' configuration/shared-sessions.mdx` returns 0 and the page contains `Shared sessions shipped in v0.74.0`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-shared-sessions.ac2", + "title": "The page shows that only Claude Code conversations stream and that other harnesses show `The host's conversation transcript is not available.`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-shared-sessions.ac3", + "title": "The page shows a browser viewer gets no Terminal view and the share step names the ⋮ menu in the conversation header", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-shared-sessions.ac4", + "title": "`grep -nP '[\\x{2013}\\x{2014}]' configuration/shared-sessions.mdx` prints nothing, the frontmatter shows the D4 title with `sidebarTitle: \"Shared sessions\"`, and `## Get help` contains the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-share", + "title": "cli/share.mdx: correct messages, join URL and token-mint behavior", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "cli/share.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' cli/share.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-P1: apply Appendix P rows 1 to 5 (evidence per O3) and the `[ADD]` Missing bullets." + }, + "items": [ + { + "id": "audit-share.ac1", + "title": "The error list contains `The Overdeck dashboard is not running. Start it with pan up, then run pan share again.` and `Cannot share <name>: <reason>`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-share.ac2", + "title": "The join steps contain `<dashboard URL>/#/shared/<CODE>` and shows it is printed as `Shared conversation: <url>`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-share.ac3", + "title": "The token-mint paragraph shows a browser on this machine signs in by itself with `dashboard.require_token_mint: true`, and the page contains `Not a share link or join code`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-share.ac4", + "title": "The frontmatter shows `title: \"pan share and pan join: share a live conversation by link\"` with `sidebarTitle: \"pan share and pan join\"`, and `## Get help` contains the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-triggers", + "title": "triggers.mdx: date the release and correct rate-limit, Funnel and inbox claims", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "configuration/triggers.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' configuration/triggers.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-Q1: apply Appendix Q rows 1 to 11 (row 5 evidence per O3) and the `[ADD]` Missing bullets." + }, + "items": [ + { + "id": "audit-triggers.ac1", + "title": "`grep -c 'Available from the next release' configuration/triggers.mdx` returns 0 and the Note contains `Added in v0.73.0.`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-triggers.ac2", + "title": "The rate-limit bullet shows refused events count toward the 6 and 60 per-hour limits, and the Funnel bullet names the Public MCP paths", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-triggers.ac3", + "title": "The removal bullet shows `pan triggers remove` keeps the inbox and only the dashboard's Remove deletes it", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-triggers.ac4", + "title": "The inbox bullet shows the `429` limits (200 events, 64 MiB, 120 events a minute)", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-triggers.ac5", + "title": "The frontmatter shows the D4 title with `sidebarTitle: \"Webhook triggers\"`, and `## Get help` contains the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-cli-triggers", + "title": "cli/triggers.mdx: date the release and correct inbox, JSON and remove behavior", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "cli/triggers.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' cli/triggers.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-R1: apply Appendix R rows 1 to 9 (row 7 uses the appendix's 'CLI row 7 replacement' text) and the `[ADD]` Missing bullets." + }, + "items": [ + { + "id": "audit-cli-triggers.ac1", + "title": "`grep -c 'Available from the next release' cli/triggers.mdx` returns 0 and the page contains `Added in v0.73.0.`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-cli-triggers.ac2", + "title": "The intro shows `add --inbox` needs the running dashboard, and the `--json` row shows the `--inbox` output with `inboxUrl`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-cli-triggers.ac3", + "title": "The `remove` section shows it does not delete a directory inbox, and the empty-list line renders without nested backticks", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-cli-triggers.ac4", + "title": "The frontmatter shows `title: \"pan triggers: create and manage webhook triggers\"` with `sidebarTitle: \"pan triggers\"`, and `## Get help` contains the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-bots", + "title": "bots.mdx: correct default access, connector files and troubleshooting", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "configuration/bots.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' configuration/bots.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-S1: apply Appendix S rows 1 to 11 (row 6 uses the appendix's 'Bots row 6 insert' text) and the `[ADD]` Missing bullets. Keep the heading `### no-webrtc-egress`." + }, + "items": [ + { + "id": "audit-bots.ac1", + "title": "The setup sentence names Read state, Read conversations and Send messages as the default access, and the never-gets list contains `read:events`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-bots.ac2", + "title": "The command table contains a `connect` row and `grep -c 'four files' configuration/bots.mdx` returns 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-bots.ac3", + "title": "`grep -c 'HTTP config below' configuration/bots.mdx` returns 0 and the page states there is no Slack, Discord or Telegram integration", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-bots.ac4", + "title": "The page preserves the heading `### no-webrtc-egress`, and `## Troubleshooting` contains the Discord help sentence as its last paragraph", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-bots.ac5", + "title": "`grep -nP '[\\x{2013}\\x{2014}]' configuration/bots.mdx` prints nothing and the frontmatter shows the D4 title with `sidebarTitle: \"Connect a bot\"`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-phone", + "title": "phone.mdx: describe both phone setups and remove transitional notes", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "configuration/phone.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' configuration/phone.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-T1: apply Appendix T rows 1 to 12 and the `[ADD]` Missing bullets on top of PAN-5472's result. Row 2 renames `## Before you start`; first run `grep -rn 'phone#before-you-start' --include=*.mdx .` (empty on the base) and repoint any hit." + }, + "items": [ + { + "id": "audit-phone.ac1", + "title": "The intro describes the browser phone view at `/m` and the Overdeck app, and the page shows `## Before you start (browser phone view)`", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-phone.ac2", + "title": "`grep -c 'as soon as the machine runs the new' configuration/phone.mdx` returns 0 and **Install app** is placed in the banner below the header", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-phone.ac3", + "title": "The token sign-in paragraph shows the setting turns on by itself once the machine has a trusted remote address, a paired device or a machine link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-phone.ac4", + "title": "The store-status sentence still names TestFlight and Play internal testing, the title is still `Use Overdeck on your phone`, and `## Get help` contains the Discord link", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + }, + { + "id": "audit-push", + "title": "push-notifications.mdx: remove stale ship notes and correct config and failure behavior", + "status": "pending", + "priority": "medium", + "created": "2026-11-19T03:25:00Z", + "metadata": { + "difficulty": "medium", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "configuration/push-notifications.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "grep -nP '[\\x{2013}\\x{2014}]' configuration/push-notifications.mdx | wc -l", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash grep count prints 0", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "ready", + "parallelSafeReason": "Edits only its own page file; items that share a file are serialized by blocks edges.", + "traces": [ + "FR-1", + "FR-2", + "FR-3", + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "NFR-2", + "NFR-3" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-U1: apply Appendix U rows 1 to 12 and the `[ADD]` Missing bullets." + }, + "items": [ + { + "id": "audit-push.ac1", + "title": "`grep -c 'action ships' configuration/push-notifications.mdx` returns 0 and `grep -c 'Once the phone shell' configuration/push-notifications.mdx` returns 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-push.ac2", + "title": "The config section names `~/.overdeck/config.yaml`, and the `enabled` row shows **Send test** still works when `enabled` is false", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-push.ac3", + "title": "The disk bullet names `resources.disk_warn_gb` and `resources.disk_critical_gb`, and `grep -c 'Notifications stopped after many failures' configuration/push-notifications.mdx` returns 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "audit-push.ac4", + "title": "`grep -nP '[\\x{2013}\\x{2014}]' configuration/push-notifications.mdx` prints nothing, the frontmatter shows the D4 title with `sidebarTitle: \"Push notifications\"`, and `## Troubleshooting` ends with the Discord help sentence", + "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-19T03:25:00Z", + "metadata": { + "difficulty": "simple", + "kind": "docs", + "issueLabel": "pan-5500", + "requiresInspection": false, + "inspectionDepth": "fast", + "files_scope": [ + "anywhere.mdx", + "configuration/session-vault.mdx", + "configuration/remote-access.mdx", + "configuration/linked-machines.mdx", + "configuration/shared-sessions.mdx", + "configuration/triggers.mdx", + "configuration/tailscale.mdx", + "configuration/mcp.mdx", + "configuration/bots.mdx", + "configuration/phone.mdx", + "configuration/push-notifications.mdx", + "cli/vault.mdx", + "cli/pair.mdx", + "cli/tailscale.mdx", + "cli/account.mdx", + "cli/share.mdx", + "cli/devices.mdx", + "cli/machines.mdx", + "cli/token.mdx", + "cli/mcp.mdx", + "cli/triggers.mdx" + ], + "files_scope_confidence": "high", + "verify_commands": [ + "for f in anywhere configuration/{session-vault,remote-access,linked-machines,shared-sessions,triggers,tailscale,mcp,bots,phone,push-notifications} cli/{vault,pair,tailscale,account,share,devices,machines,token,mcp,triggers}; do grep -HnP '[\\x{2013}\\x{2014}]' \"$f.mdx\"; done | wc -l", + "npx -y mint@4.3.49 broken-links --check-anchors", + "npm run lint:docs" + ], + "expected_outputs": [ + "the dash loop count prints 0", + "mint prints 'success no broken links found'", + "lint:docs prints 'docs lint passed' and exits 0" + ], + "readiness": "sequential", + "parallelSafeReason": "Runs after every page item; touches a page only to fix a validator failure.", + "traces": [ + "FR-4", + "FR-5", + "FR-6", + "FR-7", + "FR-8", + "NFR-1" + ] + }, + "narrative": { + "Action": "Follow the PRD .pan/drafts/PAN-5500.md: Common procedure steps 0 to 9, the Overrides section (O1 to O4, which win over appendix rows), D3 help sentence placement, D4 title table, D9 Missing-bullet rule. WI-Z1: run steps 1 to 6 over the 21 pages, fix any failure on a group page in this item's commit, and write the PR body draft (21 page lines, validation output, Follow-ups) into this item's commit message above the trailers. After `pan done`, append the draft to the PR body (step 8)." + }, + "items": [ + { + "id": "validate-and-pr-body.ac1", + "title": "The dash loop over all 21 group pages prints nothing and `npm run lint:docs` exits 0", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "validate-and-pr-body.ac2", + "title": "`tr '\\n' ' '` piped to `grep -c 'next release'` returns 0 for every group page, and `grep -L 'discord.gg/ZpHE2ZTv5P'` over the 21 pages prints nothing", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "validate-and-pr-body.ac3", + "title": "`npx -y mint@4.3.49 validate` and `npx -y mint@4.3.49 broken-links --check-anchors` report success, and the validation commit message contains their output (or the exact download error when the CLI cannot be fetched)", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + }, + { + "id": "validate-and-pr-body.ac4", + "title": "The validation commit message contains a PR-body draft with 21 ticked `<page>.mdx` lines with one note each and a `## Follow-ups` section", + "status": "pending", + "metadata": { + "kind": "acceptance_criterion" + } + } + ] + } + ], + "edges": [ + { + "from": "anywhere-plans", + "to": "anywhere-shipped-roadmap", + "type": "blocks" + }, + { + "from": "anywhere-shipped-roadmap", + "to": "anywhere-reasoning-and-page", + "type": "blocks" + }, + { + "from": "anywhere-plans", + "to": "anywhere-reasoning-and-page", + "type": "blocks" + }, + { + "from": "linked-machines-top", + "to": "linked-machines-bottom", + "type": "blocks" + }, + { + "from": "mcp-top", + "to": "mcp-bottom", + "type": "blocks" + }, + { + "from": "anywhere-plans", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "anywhere-shipped-roadmap", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "anywhere-reasoning-and-page", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-account", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "linked-machines-top", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "linked-machines-bottom", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-machines", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-pair", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-devices", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "mcp-top", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "mcp-bottom", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-cli-mcp", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-token", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-session-vault", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-vault", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-tailscale", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-cli-tailscale", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-remote-access", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-shared-sessions", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-share", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-triggers", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-cli-triggers", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-bots", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-phone", + "to": "validate-and-pr-body", + "type": "blocks" + }, + { + "from": "audit-push", + "to": "validate-and-pr-body", + "type": "blocks" + } + ] + }, + "status": "proposed" +} \ No newline at end of file From b058d98ccf68350dfd006895c255348b0a85df97 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:34:33 -0500 Subject: [PATCH 02/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .pan/continues/PAN-5500.xbrief.json diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json new file mode 100644 index 00000000000..a855f44a84b --- /dev/null +++ b/.pan/continues/PAN-5500.xbrief.json @@ -0,0 +1,18 @@ +{ + "version": "1", + "issueId": "PAN-5500", + "created": "2026-11-19T03:34:33.510Z", + "updated": "2026-11-19T03:34:33.510Z", + "gitState": {}, + "decisions": [], + "hazards": [], + "resumePoint": null, + "sessionHistory": [], + "items": { + "anywhere-plans": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T03:34:33.510Z" + } + } +} From b40e869492be1fba7757d26720fa994c5af9d83e Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:36:37 -0500 Subject: [PATCH 03/80] docs(anywhere): fix Note, plans and account claims (lines 1-173) Applies Appendix A rows 1-14 (with override O2 billing wording) to anywhere.mdx: the Note now cites v0.64.0/v0.73.0/v0.74.0 instead of "next release"; invited accounts are named as the Tester plan; every "on sale"/"we plan to sell" claim becomes "Paid plans are invite-only for now."; the command palette list adds Connect a bot; the hosted vault, pan vault migrate, extra storage and the relay top-up are labeled planned; and the deletion paragraph notes subscription cancellation. Item: anywhere-plans Item: anywhere-plans.ac1 Item: anywhere-plans.ac2 Item: anywhere-plans.ac3 Item: anywhere-plans.ac4 Item: anywhere-plans.ac5 PR-note: anywhere.mdx: fixed Note/plans/account claims, lines 1-173 (Appendix A rows 1-14, O2) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- ...dit-overdeck-anywhere-21-pages.xbrief.json | 10 +- anywhere.mdx | 92 +++++++++++-------- 2 files changed, 57 insertions(+), 45 deletions(-) diff --git a/.pan/specs/2026-11-19-PAN-5500-docs-accuracy-audit-overdeck-anywhere-21-pages.xbrief.json b/.pan/specs/2026-11-19-PAN-5500-docs-accuracy-audit-overdeck-anywhere-21-pages.xbrief.json index cd0460467d4..e476ef5549b 100644 --- a/.pan/specs/2026-11-19-PAN-5500-docs-accuracy-audit-overdeck-anywhere-21-pages.xbrief.json +++ b/.pan/specs/2026-11-19-PAN-5500-docs-accuracy-audit-overdeck-anywhere-21-pages.xbrief.json @@ -4,17 +4,17 @@ "created": "2026-11-19T03:25:00Z", "author": "overdeck/0.0.0", "description": "Plan for PAN-5500: docs: accuracy audit, Overdeck Anywhere (21 pages)", - "updated": "2026-11-19T03:33:49.242Z" + "updated": "2026-11-19T03:34:21.927Z" }, "plan": { "id": "pan-5500", "title": "docs: accuracy audit, Overdeck Anywhere (21 pages)", - "status": "proposed", + "status": "running", "uid": "241bbda8-2ad9-4df4-8576-0a1a11ed2789", "author": "agent:claude-opus-5-5", - "sequence": 2, + "sequence": 5, "created": "2026-11-19T03:25:00Z", - "updated": "2026-11-19T03:33:49.242Z", + "updated": "2026-11-19T03:34:21.927Z", "references": [ { "uri": "https://github.com/eltmon/overdeck/issues/5500", @@ -2252,5 +2252,5 @@ } ] }, - "status": "proposed" + "status": "active" } \ No newline at end of file diff --git a/anywhere.mdx b/anywhere.mdx index 0290f10bc37..1a718c962cb 100644 --- a/anywhere.mdx +++ b/anywhere.mdx @@ -6,12 +6,14 @@ description: "What Overdeck Anywhere is, what has shipped, what stays free and o <Note> Everything Anywhere does on your own machines is free and open source. Session Vault and -device pairing shipped in v0.64.0. Linked machines, Tailscale setup, the phone app, push -notifications, webhook triggers and the MCP server ship in the next release. overdeck.ai -accounts are invite-only for now, and nothing on this page can be bought yet: the paid tiers -are available to invite-allowlisted accounts until billing -([PAN-4294](https://github.com/eltmon/overdeck/issues/4294)) ships. We publish the prices now, -with the reasoning, so you can see how we got there and tell us where we are wrong. +device pairing shipped in v0.64.0. Linked machines, Tailscale setup, the phone web app, push +notifications, webhook triggers and the MCP server shipped in v0.73.0. The native phone apps +(in TestFlight and Play internal testing), shared sessions and bot connections followed in +v0.74.0. overdeck.ai accounts are invite-only for now, and invited accounts get the Tester +plan: no machine limit, with the relay and the webhook inbox included. +Paid plans are invite-only for now. +We publish the prices now, with the reasoning, so you can see how we got there and tell us +where we are wrong. </Note> Overdeck runs on your own machine. Your agents, workspaces and conversations live there. @@ -42,11 +44,11 @@ Everything Anywhere does on this machine is in **Settings → Anywhere**. The qu there is **Machines** in the left column footer; its tooltip says how many linked machines are online now. -The command palette (Cmd/Ctrl+K) has an **Anywhere** group: **Link a machine**, +The command palette (Cmd/Ctrl+K) has an **Anywhere** group. **Link a machine**, **Add a Fly machine**, **Add an SSH machine**, **Set up a phone**, **Pair a device**, -**Set up Tailscale** open the same dialogs as the Settings buttons, over the page you are -on; **Open Anywhere settings** goes to the section. **Set up Tailscale** works only in a -browser on this machine. +**Set up Tailscale** and **Connect a bot** open the same dialogs as the Settings buttons, +over the page you are on. **Open Anywhere settings** goes to the section. **Set up Tailscale** +works only in a browser on this machine. Until a machine is linked or Tailscale is set up, the Home page's **Get set up** card shows **Reach this machine from anywhere**, which opens the same section. @@ -74,7 +76,8 @@ Links: [Remote access](/configuration/remote-access), - The directory and direct connections for up to 3 machines - 1 GB of hosted vault storage, synced on 2 machines, when the hosted vault ships (planned) - End-to-end encrypted - - Invite-only for now + - Invite-only for now. Invited accounts get the Tester plan instead (no machine limit, with + the relay and the webhook inbox). </Card> <Card title="Anywhere" icon="globe"> <div style={{ fontSize: '1.75rem', fontWeight: 600, lineHeight: 1.2, margin: '0.25rem 0' }}>$8 / month</div> @@ -97,60 +100,69 @@ Links: [Remote access](/configuration/remote-access), </CardGroup> **Relay add-on:** +$3 a month or +$30 a year on the Anywhere subscription ($13 a month -or $126 a year in all), billed in the same charge. When two of your machines find no direct -path, the relay connects them, still end-to-end encrypted. It includes 50 GB of relay traffic a -month; at 50 GB the relay stops until the next month, and an extra 50 GB is a one-time $3 -purchase. There is no per-gigabyte billing. The relay also carries an [Overdeck connector](/configuration/bots#run-the-overdeck-connector)'s traffic when a bot has no direct path to your machine; it relays only encrypted bytes. +or $126 a year in all, or $90 a year at the founding price), billed in the same charge. +When two of your machines find no direct path, the relay connects them, still end-to-end +encrypted. It includes 50 GB of relay traffic a month. At 50 GB the relay stops until the next +month. An extra 50 GB for a one-time $3 is planned but cannot be bought yet. There is no +per-gigabyte billing. The relay also carries an [Overdeck connector](/configuration/bots#run-the-overdeck-connector)'s traffic when a bot has no direct path to your machine; it relays only encrypted bytes. -**Availability:** the paid tiers (Anywhere, the founding price and the relay add-on) are sold to -invited accounts on the [account page](https://account.overdeck.ai/account). Creem handles the -payment as merchant of record; Overdeck never sees your card details. Sign-up is still -invite-only. +**Availability:** paid plans are invite-only for now. When the account page's Billing section +offers the paid tiers (Anywhere, the founding price and the relay add-on), invited accounts +subscribe there, on the [account page](https://account.overdeck.ai/account). Creem handles the +payment as merchant of record; Overdeck never sees your card details. Sign-up is invite-only. **Your account page:** [account.overdeck.ai/account](https://account.overdeck.ai/account) -shows your plan, this month's relay use and your machines. From it you can subscribe, add or -remove the relay, open **Manage billing** (card, invoices, cancel), remove a machine (which signs -it out and frees its place) or delete your account. +shows your plan, this month's relay use and your machines. From it you can remove a machine +(which signs it out and frees its place) or delete your account. When billing is available, it +also lets you subscribe, add or remove the relay, open **Manage billing** (card, invoices, +cancel) and see how many founding places are left. -In the dashboard, **Settings → Anywhere → Account** shows the same plan and relay use and links -to the account page with **Manage account**; **Sign in** there replaces `pan account login`. +In the dashboard, the **Account** card in **Settings → Anywhere** shows the signed-in GitHub +account, the plan (**Free account** or **Tester**) and this month's relay use. It links to the +account page with **Manage account**. In a browser on this machine, its **Sign in** button +signs the machine in without `pan account login`; other viewers see a `pan account login` hint. ### When a subscription ends -If you cancel, or a payment keeps failing (Creem retries a failed payment for 7 days), your plan -returns to the free account when the paid period ends: +If you cancel, or a renewal payment keeps failing (the plan keeps paid access for 7 days past +its paid-through date while Creem retries the card), your plan changes when the paid period +ends. While your invite is active you return to the Tester plan. Without an active invite you +return to the free account: - The relay and the webhook inbox stop at once. Machines already in the directory stay; you only cannot add more than 3. -- For 30 days your hosted vault data stays readable and you can export it with - `pan vault migrate`. Writes follow the free 1 GB, so a larger vault is read-only. +- For 30 days your hosted vault data stays readable, and you can export it with + `pan vault migrate` once that command ships with the hosted vault. Writes follow the free + 1 GB, so a larger vault is read-only. - For 30 more days the same holds, and the account page warns of the deletion date. - After 60 days, hosted vault data above the free 1 GB is deleted, and the account continues as a free account. A vault within 1 GB is kept. -`pan vault migrate` works throughout. Subscribing again before the deletion date restores -everything. +The hosted vault and `pan vault migrate` are planned +([PAN-4297](https://github.com/eltmon/overdeck/issues/4297)); once they ship, `pan vault migrate` +works throughout. Subscribing again before the deletion date restores everything. -**Extra storage:** +$3 a month or +$30 a year per 100 GB of hosted vault, for the few who -pass 100 GB and prefer not to prune old records. +**Extra storage (planned with the hosted vault):** +$3 a month or +$30 a year per 100 GB +of hosted vault, for the few who pass 100 GB and prefer not to prune old records. **Team:** not at launch. A team plan needs a key-sharing design first (see [why there is no team plan yet](#how-we-arrived-at-these-prices)). <CardGroup cols={3}> <Card title="Encryption" icon="lock"> - Transcripts are encrypted on your machine before upload, with a key only you hold. The - hosted service stores ciphertext it cannot read, and your account never gains the ability - to decrypt it. This also means we cannot recover your vault if you lose every device and - your recovery phrase. + The hosted vault is planned. When it ships, transcripts are encrypted on your machine + before upload, with a key only you hold. The hosted service stores ciphertext it cannot + read, and your account never gains the ability to decrypt it. This also means we cannot + recover your vault if you lose every device and your recovery phrase. </Card> <Card title="Deletion" icon="trash"> - Deleting your account deletes all of your hosted vault data within 24 hours, and removes - your machines and phones from the connect directory. + Deleting your account signs out every device, cancels any subscription, deletes all of + your hosted data within 24 hours, and removes your machines and phones from the connect + directory. </Card> <Card title="Payments" icon="credit-card"> - We plan to sell through [Creem](https://www.creem.io) as merchant of record. Creem is the - legal seller, so it collects and remits VAT, GST and sales tax where they apply. + Paid plans are sold through [Creem](https://www.creem.io) as merchant of record. Creem is + the legal seller, so it collects and remits VAT, GST and sales tax where they apply. </Card> </CardGroup> From d321d0fcaf8c3c643836248276018d0c54432e2f Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:37:00 -0500 Subject: [PATCH 04/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index a855f44a84b..815e4ed5c2d 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:34:33.510Z", + "updated": "2026-11-19T03:37:00.595Z", "gitState": {}, "decisions": [], "hazards": [], @@ -10,9 +10,30 @@ "sessionHistory": [], "items": { "anywhere-plans": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T03:34:33.510Z" + "claimedAt": "2026-11-19T03:34:33.510Z", + "doneAt": "2026-11-19T03:37:00.594Z" + }, + "anywhere-plans.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:37:00.594Z" + }, + "anywhere-plans.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:37:00.594Z" + }, + "anywhere-plans.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:37:00.594Z" + }, + "anywhere-plans.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:37:00.594Z" + }, + "anywhere-plans.ac5": { + "status": "completed", + "doneAt": "2026-11-19T03:37:00.594Z" } } } From 6fbfb701d8abf4672033edaa6a57fac92fdfaa0d Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:37:06 -0500 Subject: [PATCH 05/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 815e4ed5c2d..d09192c1688 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:37:00.595Z", + "updated": "2026-11-19T03:37:06.338Z", "gitState": {}, "decisions": [], "hazards": [], @@ -34,6 +34,11 @@ "anywhere-plans.ac5": { "status": "completed", "doneAt": "2026-11-19T03:37:00.594Z" + }, + "anywhere-shipped-roadmap": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T03:37:06.337Z" } } } From 0e89654c1329f9a94d017620a9089ad6ce4312f8 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:38:41 -0500 Subject: [PATCH 06/80] docs(anywhere): date every shipped row and roadmap step (lines 175-321) Applies Appendix A rows 15-44 (with overrides O1, O2) to anywhere.mdx: replaces every "next release" with the version that actually shipped it (v0.73.0 or v0.74.0, with agent-tools split noted on the MCP row); adds the native phone apps row and the account page row to the shipped table; names grok alongside the other MCP harnesses; and rewrites the Roadmap steps and the hosted-services paragraph to match. Item: anywhere-shipped-roadmap Item: anywhere-shipped-roadmap.ac1 Item: anywhere-shipped-roadmap.ac2 Item: anywhere-shipped-roadmap.ac3 PR-note: anywhere.mdx: dated shipped table and roadmap (A rows 15-44) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- anywhere.mdx | 78 +++++++++++++++++++++++++++------------------------- 1 file changed, 41 insertions(+), 37 deletions(-) diff --git a/anywhere.mdx b/anywhere.mdx index 1a718c962cb..c592ee8c85a 100644 --- a/anywhere.mdx +++ b/anywhere.mdx @@ -196,30 +196,32 @@ to add one. | Settings → Anywhere: pair dialog, paired devices, status card | v0.65.0 | [Remote access](/configuration/remote-access) | | Scoped API tokens (`pan token`, Settings → Access Tokens) | v0.65.0 | [Remote access](/configuration/remote-access) | | **Continue on another device** from a conversation: open it on another screen, or hand it off through the vault | v0.65.0 | [Remote access](/configuration/remote-access#open-one-conversation-on-another-screen) | -| The overdeck.ai directory: your machines in Settings → Anywhere → Directory, linking by two-screen approval, the free account's 3 machines | next release | [Remote access](/configuration/remote-access#find-your-machines-through-overdeck-ai) | -| Direct connections between your machines with no Tailscale (`direct` routes) | next release | [Linked machines](/configuration/linked-machines) | -| The relay add-on: relay routes, **Using relay**, the 50 GB monthly allowance | next release | [Remote access](/configuration/remote-access#find-your-machines-through-overdeck-ai) | -| The webhook inbox: triggers that hold events for 24 hours while a machine is offline | next release | [Triggers](/configuration/triggers#hold-events-with-the-directory-inbox) | -| Linked machines: link your machines over an end-to-end encrypted channel on LAN, Tailscale, direct or relay routes | next release | [Linked machines](/configuration/linked-machines) | -| Conversations across machines: one shared list, remote control, **Pull here**, **Open preview** | next release | [Linked machines](/configuration/linked-machines#sharing-conversations) | -| Work across machines: the Machine field, **Auto** placement, delegation, fleet Needs-You, usage and **Compare settings** | next release | [Linked machines](/configuration/linked-machines#start-work-on-another-machine) | -| Gauntlet lanes on any linked machine (`pan lane start --machine`) | next release | [Lanes](/reference/lanes#lanes-on-other-machines) | -| SSH machines: Overdeck starts or adopts `pan up` over SSH and links it | next release | [Linked machines](/configuration/linked-machines#ssh-machines) | -| `pan connect`: one command turns a fresh server into a lasting linked machine | next release | [pan machines](/cli/machines#connect) | -| Fly VMs as machines (`pan machines add-fly`) | next release | [Linked machines](/configuration/linked-machines#fly-machines) | -| Fleet versions and **Update all**, including harness CLIs | next release | [Linked machines](/configuration/linked-machines#fleet-versions-and-update-all) | -| The desktop app opens a chosen machine's dashboard with no local server | next release | [Remote access](/configuration/remote-access#from-the-desktop-app) | -| **Set up Tailscale**: install, sign in, Serve HTTPS and peer discovery | next release | [Tailscale](/configuration/tailscale) | -| The phone app over Tailscale Serve: answer a question in three taps | next release | [Phone](/configuration/phone) | -| Push notifications sent from your machine with Web Push, optional ntfy | next release | [Push notifications](/configuration/push-notifications) | -| Webhook triggers (`pan triggers`), published through Tailscale Funnel | next release | [Webhook triggers](/configuration/triggers) | -| The MCP server (`pan mcp serve`, **Copy MCP URL**), with its tools in every Claude Code, Codex, `acp` and `opencode` agent | next release | [MCP server](/configuration/mcp) | -| OAuth sign-in for MCP clients, approved in your dashboard (`pan mcp oauth`) | next release | [MCP server](/configuration/mcp#sign-in-with-oauth) | -| Public MCP for hosted bots through Tailscale Funnel | next release | [MCP server](/configuration/mcp#public-mcp-for-hosted-bots) | -| Connect a bot: Hermes, OpenClaw, Grok Build, Grok Bot and the xAI API, and the Overdeck connector (`pan mcp connector`) | next release | [Connect a bot](/configuration/bots) | -| Sign in to overdeck.ai (`pan account login`, `status`, `logout`, or **Sign in** on the dashboard Account card) | next release | [pan account](/cli/account) | -| Pipeline agents' transcripts saved to the Session Vault automatically | next release | [Session Vault](/configuration/session-vault) | -| Shared sessions: share a conversation by link, viewers watch it live in their own Overdeck | next release | [Shared sessions](/configuration/shared-sessions) | +| The overdeck.ai directory: your machines in Settings → Anywhere → Directory, linking by two-screen approval, the free account's 3 machines | v0.73.0 | [Remote access](/configuration/remote-access#find-your-machines-through-overdeck-ai) | +| Direct connections between your machines with no Tailscale (`direct` routes) | v0.73.0 | [Linked machines](/configuration/linked-machines) | +| The relay add-on: relay routes, **Using relay**, the 50 GB monthly allowance | v0.73.0 | [Remote access](/configuration/remote-access#find-your-machines-through-overdeck-ai) | +| The webhook inbox: triggers that hold events for 24 hours while a machine is offline | v0.73.0 | [Triggers](/configuration/triggers#hold-events-with-the-directory-inbox) | +| Linked machines: link your machines over an end-to-end encrypted channel on LAN, Tailscale, direct or relay routes | v0.73.0 | [Linked machines](/configuration/linked-machines) | +| Conversations across machines: one shared list, remote control, **Pull here**, **Open preview** | v0.73.0 | [Linked machines](/configuration/linked-machines#sharing-conversations) | +| Work across machines: the Machine field, **Auto** placement, delegation, fleet Needs-You, usage and **Compare settings** | v0.73.0 | [Linked machines](/configuration/linked-machines#start-work-on-another-machine) | +| Gauntlet lanes on any linked machine (`pan lane start --machine`) | v0.73.0 | [Lanes](/reference/lanes#lanes-on-other-machines) | +| SSH machines: Overdeck starts or adopts `pan up` over SSH and links it | v0.73.0 | [Linked machines](/configuration/linked-machines#ssh-machines) | +| `pan connect`: one command turns a fresh server into a lasting linked machine | v0.73.0 | [pan machines](/cli/machines#connect) | +| Fly VMs as machines (`pan machines add-fly`) | v0.73.0 | [Linked machines](/configuration/linked-machines#fly-machines) | +| Fleet versions and **Update all**, including harness CLIs | v0.73.0 | [Linked machines](/configuration/linked-machines#fleet-versions-and-update-all) | +| The desktop app opens a chosen machine's dashboard with no local server | v0.73.0 | [Remote access](/configuration/remote-access#from-the-desktop-app) | +| **Set up Tailscale**: install, sign in, Serve HTTPS and peer discovery | v0.73.0 | [Tailscale](/configuration/tailscale) | +| The phone app over Tailscale Serve: answer a question in three taps | v0.73.0 | [Phone](/configuration/phone) | +| Native iPhone and Android apps: pair by QR code, answer questions, push notifications sealed to each phone (TestFlight and Play internal testing) | v0.74.0 | [Phone](/configuration/phone) | +| Push notifications sent from your machine with Web Push, optional ntfy | v0.73.0 | [Push notifications](/configuration/push-notifications) | +| Webhook triggers (`pan triggers`), published through Tailscale Funnel | v0.73.0 | [Webhook triggers](/configuration/triggers) | +| The MCP server (`pan mcp serve`, **Copy MCP URL**), with its tools in every Claude Code, Codex, `acp`, `opencode` and `grok` agent | v0.73.0; agent tools v0.74.0 | [MCP server](/configuration/mcp) | +| OAuth sign-in for MCP clients, approved in your dashboard (`pan mcp oauth`) | v0.74.0 | [MCP server](/configuration/mcp#sign-in-with-oauth) | +| Public MCP for hosted bots through Tailscale Funnel | v0.74.0 | [MCP server](/configuration/mcp#public-mcp-for-hosted-bots) | +| Connect a bot: Hermes, OpenClaw, Grok Build, Grok Bot and the xAI API, and the Overdeck connector (`pan mcp connector`) | v0.74.0 | [Connect a bot](/configuration/bots) | +| Sign in to overdeck.ai (`pan account login`, `status`, `logout`, or **Sign in** on the dashboard Account card) | v0.73.0; dashboard **Sign in** v0.74.0 | [pan account](/cli/account) | +| The account page at account.overdeck.ai/account: plan, relay use, machines, delete account | v0.74.0 | [pan account](/cli/account) | +| Pipeline agents' transcripts saved to the Session Vault automatically | v0.73.0 | [Session Vault](/configuration/session-vault) | +| Shared sessions: share a conversation by link, viewers watch it live in their own Overdeck | v0.74.0 | [Shared sessions](/configuration/shared-sessions) | ## Roadmap @@ -236,7 +238,7 @@ consists of hosted services. [PAN-2609](https://github.com/eltmon/overdeck/issues/2609) </Step> <Step title="One Overdeck server per machine, linked"> - **Shipped (next release). Free, open source.** + **Shipped (v0.73.0). Free, open source.** Each machine runs its own Overdeck server with its own identity, and your machines link over an end-to-end encrypted channel on any route: LAN, Tailscale, a direct connection or @@ -256,12 +258,14 @@ consists of hosted services. [PAN-4654](https://github.com/eltmon/overdeck/issues/4654) </Step> <Step title="Notifications, remote access and a mobile web app"> - **Shipped (next release). Free, open source.** + **Shipped (v0.73.0). Free, open source.** Needs-you notifications are sent from your own machine with Web Push, encrypted so the push service cannot read them, with ntfy as an option. Remote access goes through Tailscale Serve, which Overdeck installs and sets up for you, instead of a tunnel. The - phone app is an installable web app reached over Tailscale. See + phone app is an installable web app reached over Tailscale. Native iPhone and Android + apps that use the same end-to-end encrypted channel as linked machines followed in + v0.74.0 and are in TestFlight and Play internal testing. See [Push notifications](/configuration/push-notifications), [Tailscale](/configuration/tailscale) and [Phone](/configuration/phone). [PAN-2354](https://github.com/eltmon/overdeck/issues/2354), @@ -269,7 +273,7 @@ consists of hosted services. [PAN-1254](https://github.com/eltmon/overdeck/issues/1254) </Step> <Step title="Fly VMs as machines"> - **Shipped (next release). Free, open source; you pay Fly directly.** + **Shipped (v0.73.0). Free, open source; you pay Fly directly.** `pan machines add-fly` starts a Fly.io VM that runs Overdeck and links to your machine, so it runs conversations and gauntlet lanes like any other linked machine. `pan start <id> @@ -284,7 +288,7 @@ consists of hosted services. ([PAN-1676](https://github.com/eltmon/overdeck/issues/1676)). </Step> <Step title="Webhook triggers and the MCP server"> - **Shipped (next release). Free, open source.** + **Shipped (v0.73.0). Free, open source.** Webhook triggers start or message a conversation when a service such as GitHub or Stripe posts to it, published through Tailscale Funnel or held by the directory inbox while a @@ -298,16 +302,16 @@ consists of hosted services. ([PAN-2353](https://github.com/eltmon/overdeck/issues/2353)). </Step> <Step title="Hosted services on overdeck.ai"> - **Account service, directory, relay add-on, webhook inbox and shared sessions built (next - release, invite-only); billing and the hosted vault planned. This is the paid plan - above.** + **Account service, directory, relay add-on and webhook inbox shipped in v0.73.0, and + shared sessions and the account page in v0.74.0, all invite-only. Paid plans are + invite-only for now; the hosted vault is planned. This is the paid plan above.** The account service, the directory with direct connections, the relay add-on and the - webhook inbox are built and ship in the next release. overdeck.ai accounts are invite-only: - testers are added by the operator. A machine signs in with - [`pan account login`](/cli/account), which runs once per machine and is optional. Still - planned: billing and the hosted Session Vault. Shared sessions are built: - a host shares a conversation by link and viewers watch it live in their own Overdeck + webhook inbox shipped in v0.73.0. overdeck.ai accounts are invite-only: testers are added + by the operator. A machine signs in with [`pan account login`](/cli/account), which runs + once per machine and is optional. Paid plans are invite-only for now. The hosted Session + Vault is still planned. Shared sessions shipped in v0.74.0: a host shares a conversation by + link and viewers watch it live in their own Overdeck ([Shared sessions](/configuration/shared-sessions)); viewers can suggest prompts, and contributors can send them. From 1b2a67dbb21bec9081236fd7b1fa48552d7d079d Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:38:59 -0500 Subject: [PATCH 07/80] docs(anywhere): record anywhere-shipped-roadmap.ac4 evidence Item: anywhere-shipped-roadmap.ac4 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 From 61fee6581792bc137b7ba14202f8e23ef7128356 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:39:22 -0500 Subject: [PATCH 08/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index d09192c1688..fdc6ed889ea 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:37:06.338Z", + "updated": "2026-11-19T03:39:22.672Z", "gitState": {}, "decisions": [], "hazards": [], @@ -36,9 +36,26 @@ "doneAt": "2026-11-19T03:37:00.594Z" }, "anywhere-shipped-roadmap": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T03:37:06.337Z" + "claimedAt": "2026-11-19T03:37:06.337Z", + "doneAt": "2026-11-19T03:39:22.672Z" + }, + "anywhere-shipped-roadmap.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:39:22.672Z" + }, + "anywhere-shipped-roadmap.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:39:22.672Z" + }, + "anywhere-shipped-roadmap.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:39:22.672Z" + }, + "anywhere-shipped-roadmap.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:39:22.672Z" } } } From a579de1c87373ace8a972d0fa6dd9732f0485e1a Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:39:28 -0500 Subject: [PATCH 09/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index fdc6ed889ea..44d34b6256d 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:39:22.672Z", + "updated": "2026-11-19T03:39:28.774Z", "gitState": {}, "decisions": [], "hazards": [], @@ -56,6 +56,11 @@ "anywhere-shipped-roadmap.ac4": { "status": "completed", "doneAt": "2026-11-19T03:39:22.672Z" + }, + "anywhere-reasoning-and-page": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T03:39:28.774Z" } } } From 067ef91e4b7b573e273e20be3d46089a74e7ba7b Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:40:52 -0500 Subject: [PATCH 10/80] docs(anywhere): fix pricing reasoning and run page-wide checks Applies Appendix A rows 45-48 to anywhere.mdx: drops the dead "later, shared sessions" and the removed founding-price history note, points the relay-cap message at the Anywhere status card in Settings, and marks the one-time 50 GB top-up as planned with its real link. Adds the Get help section (D3 help sentence, no pricing-feedback link). Dash rule, frontmatter and mint broken-links check pass over the whole file; the title stays unchanged. Item: anywhere-reasoning-and-page Item: anywhere-reasoning-and-page.ac1 Item: anywhere-reasoning-and-page.ac2 Item: anywhere-reasoning-and-page.ac3 Item: anywhere-reasoning-and-page.ac4 PR-note: anywhere.mdx: fixed pricing reasoning, added Get help (A rows 45-48) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- anywhere.mdx | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/anywhere.mdx b/anywhere.mdx index c592ee8c85a..6a0f8040ed8 100644 --- a/anywhere.mdx +++ b/anywhere.mdx @@ -452,7 +452,7 @@ The full reasoning, section by section. Open any one that interests you. What the vault does that nothing else does is let your work follow you: continue on your laptop while your desktop is off, from any saved version, across harnesses, with a key - only you hold. That is the same promise as the relay, push notifications and, later, + only you hold. That is the same promise as the relay, push notifications and shared sessions. So the vault anchors one Anywhere subscription instead of being a separate product. @@ -460,8 +460,7 @@ The full reasoning, section by section. Open any one that interests you. the hosted vault does not yet. The founding price addresses that: $60 a year, locked for as long as you stay subscribed, for the first 500 subscribers or 90 days after the Anywhere release, whichever comes first. Founders add the relay at the normal $30 a - year. (It used to end "when the relay ships", which would have ended it on launch day, - because the relay ships in the same release.) + year. </Accordion> <Accordion title="7. Why self-hosting stays ungated" icon="lock-open"> @@ -508,9 +507,10 @@ The full reasoning, section by section. Open any one that interests you. - The relay is billed inside the Anywhere charge, never as a charge of its own. Creem's $0.40 fixed fee would take about 17% of a separate $3 charge. - The 50 GB monthly cap bounds what one user can cost us and means we need no usage - billing. At the cap the relay stops until the next month and the Anywhere card says - "Relay allowance used; install Tailscale or add 50 GB". An extra 50 GB is a one-time - $3 purchase. + billing. At the cap the relay stops until the next month and the Anywhere status card in + Settings → Anywhere says "Relay allowance used; install Tailscale or add 50 GB". An extra + 50 GB for a one-time $3 is planned; until it ships, the card's **Add 50 GB** link opens + overdeck.ai/anywhere. - We will check the allowance against the real monthly use of the first relay users. If dev-server previews push typical use near the cap, we will lower the allowance or keep previews off the relay. @@ -530,3 +530,8 @@ If you have a view on any of this, comment on [PAN-4294](https://github.com/eltmon/overdeck/issues/4294) (subscription and billing) or [PAN-4297](https://github.com/eltmon/overdeck/issues/4297) (hosted Session Vault). </Info> + +## Get help + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From db4aa8412f1a5cc020f8b2e72882626a163b0cc9 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:41:15 -0500 Subject: [PATCH 11/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 44d34b6256d..f878c9dc400 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:39:28.774Z", + "updated": "2026-11-19T03:41:15.584Z", "gitState": {}, "decisions": [], "hazards": [], @@ -58,9 +58,26 @@ "doneAt": "2026-11-19T03:39:22.672Z" }, "anywhere-reasoning-and-page": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T03:39:28.774Z" + "claimedAt": "2026-11-19T03:39:28.774Z", + "doneAt": "2026-11-19T03:41:15.584Z" + }, + "anywhere-reasoning-and-page.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:41:15.584Z" + }, + "anywhere-reasoning-and-page.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:41:15.584Z" + }, + "anywhere-reasoning-and-page.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:41:15.584Z" + }, + "anywhere-reasoning-and-page.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:41:15.584Z" } } } From 4c24c48f82b674cca6bb9cf5bfb09169cb186f54 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:41:22 -0500 Subject: [PATCH 12/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index f878c9dc400..1fcf317cf46 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:41:15.584Z", + "updated": "2026-11-19T03:41:22.454Z", "gitState": {}, "decisions": [], "hazards": [], @@ -78,6 +78,11 @@ "anywhere-reasoning-and-page.ac4": { "status": "completed", "doneAt": "2026-11-19T03:41:15.584Z" + }, + "audit-account": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T03:41:22.454Z" } } } From d00b5d7a8384627aa324cec7b497ab8b41c55cf4 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:42:50 -0500 Subject: [PATCH 13/80] docs(cli/account): fix base URL, failure messages, JSON output, token file Applies Appendix B rows 1-7 to cli/account.mdx: the base-URL paragraph now allows http on localhost/127.0.0.1/[::1]; the failure list adds the two missing sign-in error messages; the --json row documents the access object, the signed-out and failure shapes; the token file section adds the format version field v; and a missing line points status's plan gap at the account page. Retitles per D4, adds Get help per D3, and removes every em/en dash on the page. Item: audit-account Item: audit-account.ac1 Item: audit-account.ac2 Item: audit-account.ac3 Item: audit-account.ac4 Item: audit-account.ac5 PR-note: cli/account.mdx: fixed base URL, failures, JSON, token file (Appendix B) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- cli/account.mdx | 51 +++++++++++++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 21 deletions(-) diff --git a/cli/account.mdx b/cli/account.mdx index c4c93e4df04..aa12a298c90 100644 --- a/cli/account.mdx +++ b/cli/account.mdx @@ -1,5 +1,6 @@ --- -title: pan account +title: "pan account: sign this machine in to overdeck.ai" +sidebarTitle: "pan account" description: Optional overdeck.ai sign-in for this machine (directory and hosted features) --- @@ -9,7 +10,7 @@ Sign this machine in to your overdeck.ai account with GitHub's device flow. Sign optional: `pan share` needs it, and `pan join` runs this sign-in itself when the machine is not signed in (see [`pan share and pan join`](/cli/share)). It is the prerequisite for the directory ([PAN-2356](https://github.com/eltmon/overdeck/issues/2356)) -and Shared Sessions — see [`anywhere`](/anywhere). +and Shared Sessions; see [`anywhere`](/anywhere). You can also sign in from the dashboard: **Settings → Anywhere → Account → Sign in**, in a browser on this machine. It writes the same `account.json` as `pan account login`, and the @@ -38,9 +39,9 @@ hardcodes the sign-in host. | `--base-url <url>` | Account service URL. | The base URL resolves in order: `--base-url`, then the `OVERDECK_ACCOUNT_URL` environment -variable, then the default `https://account.overdeck.ai`. An invalid URL (wrong scheme, a -path, a query, or a fragment) exits 1 before any network call with -`Invalid account service URL: <url>`. +variable, then the default `https://account.overdeck.ai`. It must use `https`, or `http` on +`localhost`, `127.0.0.1` or `[::1]`, and have no path, query or fragment. Anything else exits +1 before any network call with `Invalid account service URL: <url>`. An unsupported platform exits 1 before any network call: @@ -54,7 +55,7 @@ Signing in again on a machine that already has a token prints: Already signed in as <login>; signing in again replaces this machine's token. ``` -and still runs the flow — the service rotates this machine's token in place. On success: +and still runs the flow: the service rotates this machine's token in place. On success: ``` Signed in to <baseUrl> as <githubLogin> (device <label>, <deviceId>). @@ -66,7 +67,7 @@ If your GitHub account is not on the invite list, or you cancel the GitHub step: This GitHub account is not on the overdeck.ai invite list, or sign-in was cancelled. Ask the operator to allow it, then run: pan account login ``` -Other failures: `The sign-in code expired. Run: pan account login`; `Cannot reach <baseUrl>: <reason>` when the first request fails with a network error three times in a row (it is retried after 1 s and 2 s), or when the service is unreachable for several consecutive polls. `<reason>` names the underlying network cause when there is one, for example `fetch failed (ECONNRESET: socket hang up)`; or, if a token arrived but reading the account afterward failed, the token is still saved and it prints `Signed in (device <label>, <deviceId>), but could not read the account: <reason>. Run: pan account status`. +Other failures: `The sign-in code expired. Run: pan account login`; `Cannot start sign-in at <baseUrl>: HTTP <status>` when the service answers the first request with an error status; `Sign-in failed: <error>` when polling returns an error other than pending, slow down, denied or expired; `Cannot reach <baseUrl>: <reason>` when the first request fails with a network error three times in a row (it is retried after 1 s and 2 s), or when three polls in a row fail with a network error or an HTTP 5xx answer (then `<reason>` is `HTTP <status>`). `<reason>` names the underlying network cause when there is one, for example `fetch failed (ECONNRESET: socket hang up)`; or, if a token arrived but reading the account afterward failed, the token is still saved and it prints `Signed in (device <label>, <deviceId>), but could not read the account: <reason>. Run: pan account status`. ## status @@ -80,7 +81,7 @@ With no stored token: Not signed in. Run: pan account login ``` -(exit 0 — sign-in is optional). Otherwise this calls `GET /v1/me` against the stored base +(exit 0; sign-in is optional). Otherwise this calls `GET /v1/me` against the stored base URL and prints: ``` @@ -95,14 +96,17 @@ operator to renew the invite.` | Flag | Effect | | --- | --- | -| `--json` | Print `{ signedIn, baseUrl, githubLogin, githubId, deviceId, label, access, reachable }`. Never includes the token. | +| `--json` | Print `{ signedIn, baseUrl, githubLogin, githubId, deviceId, label, access, reachable }`. `access` is `{ status, expiresAt }`, where `status` is `active` or `grant_expired`, or `null` when the service did not confirm the token. Signed out, it prints `{"signedIn":false}` and exits 0. A rejected token or an unreachable service still prints the JSON, with `reachable` true or false, and exits 1. Never includes the token. | If this machine's token was revoked or the account was deleted: `This machine's sign-in is -no longer valid (<error>). Run: pan account login`, exit 1 — the token file is kept so you +no longer valid (<error>). Run: pan account login`, exit 1; the token file is kept so you can see this message again rather than silently sign you out. If the account service is unreachable: `Signed in as <login> (account service unreachable: <reason>)`, exit 1, using the login cached in the token file. +`status` shows no plan. To see your plan and relay use, open the account page at +https://account.overdeck.ai/account, or Settings → Anywhere → Account in the dashboard. + ## logout ```bash @@ -110,30 +114,35 @@ pan account logout ``` Revokes this machine's device on the account service (`DELETE /v1/devices/<deviceId>`) and -deletes the local token file either way — a 204, 401 or 404 all mean the device is gone or -already invalid: +deletes the local token file either way, since a 204, 401 or 404 all mean the device is gone +or already invalid: ``` Signed out. This machine's device token was revoked. ``` -If the service cannot be reached, the token file is still deleted locally, and this prints -to stderr and exits 1: +If the service cannot be reached, or answers with a status other than 204, 401 or 404, the +token file is still deleted locally, and this prints to stderr and exits 1: ``` Signed out locally, but could not revoke the device on <baseUrl>: <reason>. Revoke it from another signed-in machine or ask the operator. ``` With no stored token: `Not signed in.`, exit 0, no network call. `logout` never touches -anything under `${OVERDECK_HOME}` besides `account.json` — not the Session Vault key, not +anything under `${OVERDECK_HOME}` besides `account.json`: not the Session Vault key, not `environment-id.json`. ## The token file -`${OVERDECK_HOME}/account.json`, mode `0600`, written atomically. Holds `baseUrl`, -`accessToken`, `deviceId`, `label`, `githubLogin`, `githubId` and `signedInAt`. A corrupt or -unreadable file is never rewritten silently: reading it fails with a message naming the -path and `Delete it to sign out locally.` +`${OVERDECK_HOME}/account.json`, mode `0600`, written atomically. Holds a format version `v` +(always 1), `baseUrl`, `accessToken`, `deviceId`, `label`, `githubLogin`, `githubId` and +`signedInAt`. A corrupt or unreadable file is never rewritten silently: reading it fails with +a message naming the path and `Delete it to sign out locally.` + +It never holds the Session Vault key, a vault passphrase, or any conversation content; see +[`pan vault`](/cli/vault) for those. + +## Get help -It never holds the Session Vault key, a vault passphrase, or any conversation content — -see [`pan vault`](/cli/vault) for those. +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From fed8d672e97ecc3db39240cb3b3e1f6129d149f3 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:43:14 -0500 Subject: [PATCH 14/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 1fcf317cf46..7af0303cc65 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:41:22.454Z", + "updated": "2026-11-19T03:43:14.194Z", "gitState": {}, "decisions": [], "hazards": [], @@ -80,9 +80,30 @@ "doneAt": "2026-11-19T03:41:15.584Z" }, "audit-account": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T03:41:22.454Z" + "claimedAt": "2026-11-19T03:41:22.454Z", + "doneAt": "2026-11-19T03:43:14.193Z" + }, + "audit-account.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:43:14.193Z" + }, + "audit-account.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:43:14.193Z" + }, + "audit-account.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:43:14.193Z" + }, + "audit-account.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:43:14.193Z" + }, + "audit-account.ac5": { + "status": "completed", + "doneAt": "2026-11-19T03:43:14.193Z" } } } From 9e5dc92ceacf99cf7e73c1498d8a0a0077881d7a Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:43:20 -0500 Subject: [PATCH 15/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 7af0303cc65..d8e1d47acf8 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:43:14.194Z", + "updated": "2026-11-19T03:43:20.891Z", "gitState": {}, "decisions": [], "hazards": [], @@ -104,6 +104,11 @@ "audit-account.ac5": { "status": "completed", "doneAt": "2026-11-19T03:43:14.193Z" + }, + "linked-machines-top": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T03:43:20.891Z" } } } From 9d55bb41dfce6514698f2be1884b89af01a6bec5 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:45:13 -0500 Subject: [PATCH 16/80] docs(linked-machines): fix link request, SSH, Fly, fingerprint and remote-control Applies Appendix C rows 1-7, 17 and 18 (O1, O6) to lines 1-425 of configuration/linked-machines.mdx: the agent link-request paragraph names Needs you instead of the removed Decisions panel; the SSH Test button is documented as running two steps; add-fly --message now states its --project requirement; the fingerprint sentence points to pan machines list and Inbound rows; the relay-plan mention gets the invite-only wording; Remote control documents the agent-fenced exception for work this machine started; and a new Note covers the untested systemd-on-VPS case (#4863) with the TURN-over-TCP caveat. Retitles per D4 and removes every em/en dash in the item's range. Item: linked-machines-top Item: linked-machines-top.ac1 Item: linked-machines-top.ac2 Item: linked-machines-top.ac3 Item: linked-machines-top.ac4 Item: linked-machines-top.ac5 PR-note: linked-machines.mdx: fixed link/SSH/Fly/remote-control (C 1-7,17,18) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- configuration/linked-machines.mdx | 46 +++++++++++++++++++------------ 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/configuration/linked-machines.mdx b/configuration/linked-machines.mdx index fb1a67dde08..4c50b607608 100644 --- a/configuration/linked-machines.mdx +++ b/configuration/linked-machines.mdx @@ -1,5 +1,6 @@ --- -title: Linked machines +title: "Linked machines: pair Overdeck machines and work across them" +sidebarTitle: Linked machines description: Link two machines' dashboards over an encrypted channel, learn routes, and watch each other's health --- @@ -41,9 +42,10 @@ Both servers on one host (for a test) need `--allow-loopback`, because a `localh pairing link only works on the machine that printed it. An agent can ask you for a link. Its `link_machine` tool shows a **Machine link -requested** card in the Decisions panel, and the card's **Link a machine…** button -opens this dialog. After the link succeeds, the agent learns the new machine's label, -never the pairing link. See [Machine links](/configuration/mcp#machine-links). +requested** card in **Needs you** and at the top of the agent's conversation. In a +browser on this machine, the card's **Link a machine…** button opens this dialog. After +the link succeeds, the agent learns the new machine's label, never the pairing link. See +[Machine links](/configuration/mcp#machine-links). ## SSH machines @@ -64,7 +66,8 @@ so it works from any browser that can open this dashboard: 4. It forwards a loopback port on this machine to the host's dashboard port. 5. It pairs over that forwarded port and saves a machine link whose route has kind `ssh`. -**Test** in the dialog (or `pan machines test-ssh <host>`) runs only step 2. The host field +**Test** in the dialog (or `pan machines test-ssh <host>`) runs only steps 1 and 2: it +connects over SSH and compares the `pan` versions. The host field suggests the concrete `Host` aliases of this machine's `~/.ssh/config`. To set a server up from the server itself instead (a lasting service that survives @@ -123,6 +126,9 @@ npx @overdeck/core connect Then run the `pan machines link '…'` line it prints on your laptop. See [`pan connect`](/cli/machines#connect) for lingering, macOS, firewalls and removal. +<Note>Running `npx @overdeck/core connect` as a systemd service on a fresh VPS has not yet +been tested end to end on a real VPS ([#4863](https://github.com/eltmon/overdeck/issues/4863)).</Note> + ## Fly machines A Fly machine is a [Fly.io](https://fly.io) VM that runs Overdeck (`pan serve`) and is @@ -138,7 +144,7 @@ pan machines add-fly --project overdeck --harness codex --model gpt-6.1-sol --me Settings → Anywhere → Machines has the same door as a dialog: **Add a Fly machine**, next to **Add an SSH machine** (also the command palette's **Add a Fly machine**). It takes an optional project and, under Advanced, an optional -region; it has no message, harness or model field, because it only links the machine — start +region; it has no message, harness or model field, because it only links the machine: start a conversation on it from the new-conversation dialog's **Fly (new VM)** choice (see [Start work on another machine](#start-work-on-another-machine)) or with `--message` above. @@ -152,7 +158,7 @@ This one command, which takes a few minutes: advertises no private addresses, so this machine reaches it only over `wss://<app>.fly.dev`. 4. With `--project`, clones that project onto the VM (GitHub projects only). -5. With `--message`, starts a Claude Code or Codex conversation (`--harness`) there and +5. With `--message` (which needs `--project`), starts a Claude Code or Codex conversation (`--harness`) there and prints its URL. The conversation then streams in this dashboard like any linked conversation: use @@ -172,7 +178,7 @@ also uses to start [work agents on Fly](#work-agents-on-fly): `remote.enabled` lives only in config.toml. The global `~/.overdeck/config.yaml` also has a `remote:` section, but it holds only `resiliency_tier` and - `max_concurrent_agents` — an `enabled` key there does nothing, and + `max_concurrent_agents`; an `enabled` key there does nothing, and `pan admin config set remote.enabled <value>` refuses rather than write it. In the dashboard, Settings → Anywhere → Machines → **Add a Fly machine** shows a "Remote is off" notice with a **Turn on remote** button that writes the @@ -221,7 +227,7 @@ pan start PAN-123 --machine fly - The command pushes the feature branch, then asks the running dashboard to start a Fly machine with the project, add the issue's worktree there and start the work agent as a - conversation in it. It waits 5–15 minutes and prints the conversation's URL. It needs + conversation in it. It waits 5 to 15 minutes and prints the conversation's URL. It needs `pan up`. - The transcript streams in this dashboard while the agent works, with the `fly-<machineId>` chip. The issue's row in the project tree lists the conversation and opens it. @@ -292,8 +298,9 @@ Everything, on every route. The channel is a Noise protocol session (X25519, ChaCha20-Poly1305) between the two machine keys; the pairing code only introduces the keys. Every request, the event stream and every terminal that crosses a link runs inside the channel. A machine's key lives in `~/.overdeck/machine-key.json`, mode 0600, and its -fingerprint (five groups of four hex characters) is shown next to each link so you can -compare it with the other machine's **This machine** line. +fingerprint (five groups of four hex characters) is printed for each link by +`pan machines list` and shown on each **Inbound** row in Settings → Anywhere → Machines, +so you can compare it with the other machine's **This machine** line. ## Routes @@ -320,9 +327,11 @@ it answered last time. overdeck.ai account, you can also link them without a pairing link: click **Link** in **Settings → Anywhere → Directory** (or run `pan machines join`), then approve on the other machine after checking that both screens show the same six-digit code. The directory also adds -`direct` routes (`rtc://<environment id>`, a peer-to-peer WebRTC path) and, on the relay plan, -`relay` routes (`rtc+turn://<environment id>`, through a TURN relay). The relay tries the TURN -server over TLS on port 443 first, so a network that blocks UDP can still reach it. These routes are tried only when +`direct` routes (`rtc://<environment id>`, a peer-to-peer WebRTC path) and, on the relay plan +(paid plans are invite-only for now), `relay` routes (`rtc+turn://<environment id>`, through a +TURN relay). The relay tries the TURN server over TLS on port 443 first, so a network that +blocks UDP can still reach it. This TCP fallback is covered by tests but has not yet connected +on a live Fly VM. These routes are tried only when no LAN, Tailscale, SSH or public route answers, appear with the source `directory`, and are never saved with the link. See [Find your machines through overdeck.ai](/configuration/remote-access#find-your-machines-through-overdeck-ai). @@ -341,7 +350,7 @@ never saved with the link. See instead of the raw connection error. The dashboard only shows this when two signals agree: every LAN route to the peer failed with the same `EHOSTUNREACH` errno, and a probe of this process's own network access confirms macOS denied it. A powered-off peer, which also fails -fast with `EHOSTUNREACH`, keeps the raw error instead — turning on Local Network access +fast with `EHOSTUNREACH`, keeps the raw error instead, since turning on Local Network access would not help there. When a link drops, the row says why. **froze** means the other dashboard's event loop @@ -417,9 +426,10 @@ the phone at `/m?conversation=@<environment-id>/<name>`. Its transcript streams live through this machine's server, and you can send, answer questions and approvals, stop, abort, switch model, compact and open its terminal, as if it were local. Images load from the owner. The owner's own access rules decide what is -allowed: an **agent-fenced** link can read but not change the other machine's -conversations, and an agent on a linked machine is always refused changes -(`agent-fenced`). +allowed: an **agent-fenced** link, and an agent on a linked machine, can read but not +change the other machine's conversations (`agent-fenced`). The one exception is work this +machine started there, which it may message and stop (see +[Start work on another machine](#start-work-on-another-machine)). From the CLI, `pan tell @<machine>/<conv> "<message>"` delivers to a conversation on a linked machine (see [`pan tell`](/cli/agent-commands)). From fbac19e36e49ebb45aacb4e4ff1169249737932e Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:45:35 -0500 Subject: [PATCH 17/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index d8e1d47acf8..debbb2247e6 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:43:20.891Z", + "updated": "2026-11-19T03:45:35.867Z", "gitState": {}, "decisions": [], "hazards": [], @@ -106,9 +106,30 @@ "doneAt": "2026-11-19T03:43:14.193Z" }, "linked-machines-top": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T03:43:20.891Z" + "claimedAt": "2026-11-19T03:43:20.891Z", + "doneAt": "2026-11-19T03:45:35.867Z" + }, + "linked-machines-top.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:45:35.867Z" + }, + "linked-machines-top.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:45:35.867Z" + }, + "linked-machines-top.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:45:35.867Z" + }, + "linked-machines-top.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:45:35.867Z" + }, + "linked-machines-top.ac5": { + "status": "completed", + "doneAt": "2026-11-19T03:45:35.867Z" } } } From d903e7a17831ad05fb6a7cb709735e95ec070bdc Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:45:43 -0500 Subject: [PATCH 18/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index debbb2247e6..4eea8488948 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:45:35.867Z", + "updated": "2026-11-19T03:45:43.557Z", "gitState": {}, "decisions": [], "hazards": [], @@ -130,6 +130,11 @@ "linked-machines-top.ac5": { "status": "completed", "doneAt": "2026-11-19T03:45:35.867Z" + }, + "linked-machines-bottom": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T03:45:43.557Z" } } } From cf4bfbec3ab3e5bbee08c8fefec0211ca657ad4c Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:48:37 -0500 Subject: [PATCH 19/80] docs(linked-machines): fix fleet versions, --machine fly, placement output Applies Appendix C rows 8-15 and every [ADD] Missing bullet (lines 426-716, O4) to configuration/linked-machines.mdx: adds Grok Build and Pi to the Fleet versions table and harness list; corrects --machine fly's refusal set and pan start behavior; attributes the Passed over line to pan lane start; marks the Costs Machines tab experimental; fixes the Settings path in Troubleshooting; and adds the help sentence there. Also adds the SSH/link access-level, add-fly flag, directory verb, macOS Local Network, pull --stop-turn and Online-row project Missing bullets found earlier in the page. Removes every remaining em/en dash in the file. Item: linked-machines-bottom Item: linked-machines-bottom.ac1 Item: linked-machines-bottom.ac2 Item: linked-machines-bottom.ac3 Item: linked-machines-bottom.ac4 PR-note: linked-machines.mdx: fixed fleet/fly/placement, Missing bullets (C 8-15) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- configuration/linked-machines.mdx | 63 ++++++++++++++++++++++--------- 1 file changed, 45 insertions(+), 18 deletions(-) diff --git a/configuration/linked-machines.mdx b/configuration/linked-machines.mdx index 4c50b607608..a3688d3742e 100644 --- a/configuration/linked-machines.mdx +++ b/configuration/linked-machines.mdx @@ -36,7 +36,8 @@ or **Settings → Anywhere → Machines → Link a machine** (also the command p **Link a machine**). The dialog takes the pairing link, the access level and the **Link both ways** checkbox. Linking takes a few seconds: the two machines prove their keys to each other through the pairing code, exchange -tokens, and the new link shows up as **Online** on both sides. +tokens, and the new link shows up as **Online** on both sides. `pan machines link --one-way` +is the CLI form of unticking **Link both ways**. Both servers on one host (for a test) need `--allow-loopback`, because a `localhost` pairing link only works on the machine that printed it. @@ -70,6 +71,9 @@ so it works from any browser that can open this dashboard: connects over SSH and compares the `pan` versions. The host field suggests the concrete `Host` aliases of this machine's `~/.ssh/config`. +The dialog has no access-level choice; the CLI does: `pan machines add-ssh --agent-fenced` +and `--one-way`. + To set a server up from the server itself instead (a lasting service that survives logout and reboot), use [Link a fresh server](#link-a-fresh-server). @@ -161,6 +165,10 @@ This one command, which takes a few minutes: 5. With `--message` (which needs `--project`), starts a Claude Code or Codex conversation (`--harness`) there and prints its URL. +`pan machines add-fly` also takes `--region` (default `remote.fly.region`, else `iad`), +`--image` (default `registry.fly.io/<app>:latest`) and `--effort`, which the page does not +otherwise name; see [`pan machines add-fly`](/cli/machines#add-fly). + The conversation then streams in this dashboard like any linked conversation: use [Remote control](#remote-control) to steer it, or [Pull here](#pull-here) to bring it home. @@ -326,7 +334,9 @@ it answered last time. **Through the overdeck.ai directory.** When both machines are signed in to the same overdeck.ai account, you can also link them without a pairing link: click **Link** in **Settings → Anywhere → Directory** (or run `pan machines join`), then approve on the other -machine after checking that both screens show the same six-digit code. The directory also adds +machine after checking that both screens show the same six-digit code. The full CLI verb +set is `directory`, `join`, `accept`, `reject`, `approve` and `forget`; see +[the CLI page](/cli/machines#through-the-overdeck-ai-directory). The directory also adds `direct` routes (`rtc://<environment id>`, a peer-to-peer WebRTC path) and, on the relay plan (paid plans are invite-only for now), `relay` routes (`rtc+turn://<environment id>`, through a TURN relay). The relay tries the TURN server over TLS on port 443 first, so a network that @@ -346,8 +356,10 @@ never saved with the link. See | **Unsupported** | The other machine runs an Overdeck without machine links, or another link protocol. The state names the exact version, where to install it, and the `npm install -g @overdeck/core@<version>` command. It is not retried until **Reconnect** or a restart. | | **Revoked** | The other machine removed this machine's access. Link again with a new pairing link. | -**On a Mac**, a route stuck in **Offline** can say "macOS is blocking local network access for Overdeck." -instead of the raw connection error. The dashboard only shows this when two signals agree: +**On a Mac**, a route stuck in **Offline** can say "macOS is blocking local network access for +Overdeck. Open System Settings → Privacy & Security → Local Network and turn on node +(<path>)." instead of the raw connection error. The dashboard only shows this when two +signals agree: every LAN route to the peer failed with the same `EHOSTUNREACH` errno, and a probe of this process's own network access confirms macOS denied it. A powered-off peer, which also fails fast with `EHOSTUNREACH`, keeps the raw error instead, since turning on Local Network access @@ -441,7 +453,8 @@ conversation runs on one machine at a time. The pull has four steps: 1. **Release.** The owner settles the conversation, with its uncommitted and unpushed code changes, and stops its harness. If a turn is running you choose **Wait for this - turn** (up to 30 minutes) or **Stop it now**. + turn** (up to 30 minutes) or **Stop it now** (`pan conv pull --stop-turn` is the CLI + form of stopping a running turn instead of waiting for it). 2. **Transfer.** The settled conversation crosses the encrypted channel. 3. **Adopt.** This machine continues it in its own checkout and resumes the harness. It keeps the title it had on the owner. @@ -472,7 +485,7 @@ dashboard port) are refused with `port-refused`. A forward closes when you stop the link goes away, or after 30 minutes with no open connection. It needs an operator-level link. -Escape closes the Preview popover. A running forward keeps running until you stop it — +Escape closes the Preview popover. A running forward keeps running until you stop it: Escape never stops it. ## Open in editor @@ -491,8 +504,9 @@ shown disabled: their remote-SSH launch could not be verified. **Settings → Anywhere → Fleet versions** (or `pan machines versions`) shows one row per machine, this machine first: the Overdeck version and the version of each harness CLI -installed there (Claude Code, Codex CLI, Kimi Code CLI, OpenCode, Muse Code, Prime Agent, -OhMyPi). A linked machine that is not online shows its last known Overdeck version. A +installed there (Claude Code, Codex CLI, Kimi Code CLI, OpenCode, Grok Build, Muse Code, +Prime Agent, OhMyPi, Pi). A linked machine that is not online shows its last known Overdeck +version. A linked machine on an Overdeck from before fleet updates shows the version to install and its command. @@ -521,9 +535,11 @@ latest version; it never lets anyone pick a version. | Codex CLI | `codex update` | npm installs: `npm install -g --prefix <prefix> @openai/codex@latest` | | Kimi Code CLI | `kimi upgrade --yes` | | | OpenCode | `opencode upgrade` | npm installs: `npm install -g --prefix <prefix> opencode-ai@latest` | +| Grok Build | `grok update` | npm installs: `npm install -g --prefix <prefix> @xai-official/grok@latest` | | Muse Code | none | Listed with its version; Overdeck does not update it. | | Prime Agent | none | Overdeck pins it to 0.8, so it is not updated to latest. | | OhMyPi | none | Listed with its version; Overdeck does not update it. | +| Pi | none | npm installs: `npm install -g --prefix <prefix> @earendil-works/pi-coding-agent@latest`; other installs are listed with their version only. | Homebrew installs, Windows, and an npm prefix Overdeck cannot write show the command to run yourself instead of running it. Offline, connecting, unsupported and revoked machines @@ -536,11 +552,12 @@ The new-conversation dialog has a **Machine** field: **This machine** (the defau **Auto**, each online linked machine by label, and **Fly (new VM)**. **Fly (new VM)** is enabled once the dialog has a project (it needs one to clone) and needs an admin credential; choosing it starts a new Fly machine, clones the project, runs the conversation -there and takes a few minutes — the dialog shows "Starting a Fly machine." while it works. +there and takes a few minutes: the dialog shows "Starting a Fly machine." while it works. The machine is destroyed, like any Fly machine, once no conversation on it has been active for `[remote.fly] machine_idle_minutes` (see [Lifetime and cost](#lifetime-and-cost)). The -CLI takes the same per-machine choice for a conversation, but `--machine fly` refuses on -`pan start`, `pan worker run` and `pan lane start` (see [Fly machines](#fly-machines) and +CLI takes the same per-machine choice for a conversation. `--machine fly` refuses on +`pan worker run` and `pan lane start`; on `pan start` it starts the issue's work agent on a +new Fly machine, the same as `--remote` (see [Work agents on Fly](#work-agents-on-fly) and [`pan machines add-fly`](/cli/machines#add-fly)): ```bash @@ -583,9 +600,10 @@ remote worker's reports exactly like a local worker's. ## Auto placement **Auto** (`--machine auto`) picks a machine for you and prints why, for example -`Auto → desk (CPU pressure 3%, 41 GB free, 2 agents)`. When Auto passed over other machines it -adds a second line, for example `Passed over: laptop: no docker; desk: offline`. It prints both -lines when it picks this machine too. +`Auto → desk (CPU pressure 3%, 41 GB free, 2 agents)`. `pan lane start` adds a second line +when Auto passed over other machines, for example `Passed over: laptop: no docker; desk: +offline`, and prints both lines when it picks this machine too. `pan start` and +`pan worker run` print only the first line. 1. Candidates are this machine and every online, visible linked machine. 2. A machine is skipped when it is offline, has no project for the repository, lacks a @@ -610,7 +628,7 @@ machines with every listed tag. The Machines list (`pan machines list`, Settings Machines) shows each machine's load and tags. For a **conversation**, when nothing fits, `remote.auto_fly = true` lets Auto create a Fly -machine instead of answering "no machine fits" — only when the project is on GitHub and +machine instead of answering "no machine fits", only when the project is on GitHub and `needs` stays within what a Fly machine can have (`linux`, `docker`). It is off by default, and it never applies to a worker, an issue start or a lane: @@ -648,6 +666,11 @@ pan machines add-project desk overdeck # desk's overdeck, cloned here pan machines add-project laptop overdeck --to desk # this machine's overdeck, cloned on desk ``` +The CLI also takes `--file`, `--no-env` and `--parent-dir`. Each Online row in Settings → +Anywhere → Machines also has **Add a project** (operator-level links only), which pushes +this machine's project to that machine; **Compare settings** and **Add a project** show +only on Online rows. + ## Fleet Needs-You and search **Needs you** lists questions and permission prompts waiting on every online linked @@ -662,8 +685,10 @@ machine is switched off. ## Fleet usage -The Costs page's **Machines** tab shows today, week and month spend for each machine and an -**All machines** total. An offline machine shows its last known numbers with "cached <time>". +The Costs page's **Machines** tab (Costs is an experimental view: turn on +**Settings → Experimental → Experimental features** to see it) shows today, week and month +spend for each machine and an **All machines** total. An offline machine shows its last known +numbers with "cached <time>". A provider request recorded on two machines (for example a conversation pulled from one to the other) is counted once in All machines. @@ -707,7 +732,7 @@ connections. - **"Secure channel to … did not open within 10000 ms" while the machine shows Online**: the route reached the other machine but the connection and handshake took longer than 10 seconds. This is usually a slow moment on the route (for example the public Fly edge); run the command again. If it keeps happening, the - route itself is congested: check the machine's routes in Settings → Machines. + route itself is congested: check the machine's routes in Settings → Anywhere → Machines. - **`add-fly` fails with `unreachable`**: the Fly app has no public IPs. Run `fly ips allocate-v4 --shared -a <app>` and `fly ips allocate-v6 -a <app>` once, then try again. The failed VM was already destroyed. @@ -724,3 +749,5 @@ connections. `fly tokens create deploy -a <app>` (PAN-4748). - The link exists but `require_token_mint` turned itself on: that is expected. Any remote access turns it on; see [Remote access](/configuration/remote-access#local-reverse-proxies-require_token_mint). +- **Still stuck?** Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a + [GitHub Issue](https://github.com/eltmon/overdeck/issues). From ee212abe9fc13647ad07a915d9a541e944541837 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:49:00 -0500 Subject: [PATCH 20/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 4eea8488948..5b7d8fa0a45 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:45:43.557Z", + "updated": "2026-11-19T03:49:00.910Z", "gitState": {}, "decisions": [], "hazards": [], @@ -132,9 +132,26 @@ "doneAt": "2026-11-19T03:45:35.867Z" }, "linked-machines-bottom": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T03:45:43.557Z" + "claimedAt": "2026-11-19T03:45:43.557Z", + "doneAt": "2026-11-19T03:49:00.910Z" + }, + "linked-machines-bottom.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:49:00.910Z" + }, + "linked-machines-bottom.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:49:00.910Z" + }, + "linked-machines-bottom.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:49:00.910Z" + }, + "linked-machines-bottom.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:49:00.910Z" } } } From 80fbf65ba3d0304df8bae903b4ee1a0a93d2d0dc Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:49:07 -0500 Subject: [PATCH 21/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 5b7d8fa0a45..22d97ac7b13 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:49:00.910Z", + "updated": "2026-11-19T03:49:07.644Z", "gitState": {}, "decisions": [], "hazards": [], @@ -152,6 +152,11 @@ "linked-machines-bottom.ac4": { "status": "completed", "doneAt": "2026-11-19T03:49:00.910Z" + }, + "audit-machines": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T03:49:07.643Z" } } } From 1b6121fe2f1476936bd4adc9d167ae8ad7c3a590 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:51:20 -0500 Subject: [PATCH 22/80] docs(cli/machines): fix error remedies, reboot timing, Update all, directory output Applies Appendix D rows 1-6 and 8-16 (O1) and every [ADD] Missing bullet to cli/machines.mdx: adds the fly-token-rejected error and corrects auth-failed, forward-failed, bad-request and stop-failed remedies; fixes the after-reboot timing to the real 45-second back-off cap; names Grok Build and Pi in Update all; documents list/who/join/ directory/approve/pan-tell edge cases; adds the #4863 connect Note; and adds the Troubleshooting help sentence. Retitles per D4 and removes every em/en dash on the page. Item: audit-machines Item: audit-machines.ac1 Item: audit-machines.ac2 Item: audit-machines.ac3 Item: audit-machines.ac4 Item: audit-machines.ac5 PR-note: cli/machines.mdx: fixed errors/timing/update/directory (Appendix D) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- cli/machines.mdx | 63 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 44 insertions(+), 19 deletions(-) diff --git a/cli/machines.mdx b/cli/machines.mdx index 0a2479f9af7..34f8f577221 100644 --- a/cli/machines.mdx +++ b/cli/machines.mdx @@ -1,5 +1,6 @@ --- -title: pan machines +title: "pan machines: link, list and update your machines" +sidebarTitle: pan machines description: "Link this machine's dashboard to other machines, list or remove links, check or update versions on every machine, or keep a server linked for good." --- @@ -76,12 +77,12 @@ Failures print the server's message and exit 1: | `unresolvable` | The host name does not resolve from this machine. | | `unreachable` | SSH could not connect (refused, timed out, no route). | | `host-key` | The host key is unknown or changed. Run `ssh <host>` once in a terminal on this machine and check it. | -| `auth-failed` | SSH refused the login. The dashboard needs a key or agent it can use without a prompt. | +| `auth-failed` | SSH refused the login. The dashboard needs a key or agent it can use without a prompt. `add-ssh` currently reports this error as "The dashboard rejected this machine's internal token"; run `pan machines test-ssh <host>` to see the SSH message. | | `pan-missing` | `pan` is not on the host. Install it there: `npm install -g @overdeck/core@<version>`, or pass `--pan-path`. | | `version-mismatch` | The host has another `pan` version; the message names both. Install this machine's version there: `npm install -g @overdeck/core@<version>`. | | `helper-failed` | The helper on the host failed. The message carries the last lines it printed. | | `start-failed` | `pan up` on the host did not bring a dashboard up. The message carries its last output lines. | -| `forward-failed` | The port forward did not come up within 15 s. | +| `forward-failed` | The port forward did not come up within 15 s, or this server is not the primary dashboard started by `pan up` (only the primary keeps SSH forwards). | | `self-link` | The host is this machine. | ## test-ssh @@ -138,8 +139,9 @@ the server's message, then exits 1: | --- | --- | | `remote-disabled` | Set `remote.enabled = true` in `~/.overdeck/config.toml`. | | `no-fly-token` | Run `fly auth login`, or set `FLY_API_TOKEN` (or the variable `[remote.fly] api_token_env` names). | +| `fly-token-rejected` | Fly refused the token. Run `fly auth login`, or set `FLY_API_TOKEN` (or the variable `[remote.fly] api_token_env` names) to a long-lived token from `fly tokens create deploy -a <app>`. | | `harness-unsupported` | The harness cannot run on a Fly machine (only Claude Code and Codex can), or the model does not belong to the harness. | -| `bad-request` | `--message` needs `--project`, `--harness codex` needs `--model`, or a field was empty. | +| `bad-request` | `--message` needs `--project`, `--harness codex` needs `--model`, the `--model` is not a known model, or a field was empty. | | `cap-reached` | `remote.max_concurrent_agents` is full. Unlink a Fly machine, stop a remote agent, or raise the cap. | | `credentials-failed` | This machine's Claude Code credentials did not reach the VM. Log in to Claude Code here (`~/.claude/.credentials.json`), then try again. With `--harness codex`: this machine has no Codex CLI or no valid Codex sign-in, or the sign-in did not reach the VM. Run `codex login` here, then try again. | | `version-mismatch` | The VM could not install this machine's Overdeck version, or with `--harness codex` this machine's `@openai/codex` version; the message names both. | @@ -188,6 +190,7 @@ cell shows `<destination> (<forward state>, <managed|external>)` for an SSH mach | `--json` | Print `{ self, links, inbound }` as JSON. | With no links: `` No linked machines. Link one with `pan machines link <pairing-url>` using a `pan pair` link from the other machine. `` +With no inbound links, the Inbound table is replaced by `Inbound: no machine links to this one.` ## Starting work on another machine: `--machine`, `--machine auto`, `--needs` @@ -224,7 +227,9 @@ pan tell @desk/20261102-1a2b "Run the tests again" `pan tell @<machine>/<conv>` sends a message to a conversation on a linked machine, through this machine's dashboard and the encrypted link. `<machine>` is the link's label or environment id. It prints `Delivered to <conv> on <machine>`, or the other machine's error -and exits 1. Only conversations are accepted after `@<machine>/`. See +and exits 1. Only conversations are accepted after `@<machine>/`. `--force` and +`--when-limit-resets` are refused for a conversation on another machine with +`<flag> does not work for a conversation on another machine. Nothing was sent.` See [`pan tell`](/cli/agent-commands) for `--message-id` and `--steer`. ## who @@ -246,6 +251,9 @@ desk conversation conv-a1b2 working | --- | --- | | `--json` | Print `{ machines: [{ environmentId, label, self, agents, conversations, error? }] }`. | +With no matches: `No machine runs an agent or conversation for <ISSUE>.` The issue id is +upper-cased and must look like `PAN-7`. + ## add-project ```bash @@ -307,7 +315,7 @@ Left the Overdeck server on vps running (in-use). | `in-use` | Another machine holds an active link to that server. | | `restarted` | The server was restarted since this machine started it. | | `not-running` | No server was running on the host. | -| `stop-failed` | The host could not be reached; the link was removed anyway. | +| `stop-failed` | The stop on the host failed or the host could not be reached; the link was removed anyway. | | Flag | Effect | | --- | --- | @@ -341,7 +349,9 @@ as JSON. The dashboard's **Preview** button in a remote conversation does the sa These verbs need a signed-in machine (`pan account login`). See [Find your machines through overdeck.ai](/configuration/remote-access#find-your-machines-through-overdeck-ai). -Each one exits 1 with the dashboard's error text. +Each one exits 1 with the dashboard's error text. On a machine that is not signed in, +`pan machines directory` prints `Sign in with pan account login to find your machines +through overdeck.ai.` and exits 0. ### directory @@ -376,6 +386,10 @@ Accept? [y/N] Accept only if the approving machine shows the same code. Without a terminal (for example over a script) it prints `Confirm with: pan machines accept <requestId>` and exits 0; run that command after comparing the codes. `--json` prints `{ requestId, sas, fingerprint, approver }`. +After `y` it prints `Accepted. The link appears in pan machines list when the approver +finishes.` A rejected or expired request prints `The approval was rejected or expired.` and +exits 1; no answer in 10 minutes prints `No machine opened the approval request within 10 +minutes.` and exits 1. ### approve @@ -384,8 +398,9 @@ pan machines approve <request-id> [--yes] ``` Opens a direct connection to the requesting machine, prints the code and its fingerprint, asks -`Approve? [y/N]` unless `--yes`, then approves. The link appears in `pan machines list` once -the other machine accepts. +`Approve? [y/N]` unless `--yes`, then approves. Answering no rejects the request and prints +`Rejected.` Without a terminal and without `--yes`, it prints `Pass --yes to approve without a +prompt.` and exits 1. The link appears in `pan machines list` once the other machine accepts. ``` Code: 123 456 · fingerprint 4c2e-91aa-0d13-7f60-be52 @@ -454,8 +469,11 @@ Exit codes: 0 when the table printed; 1 when the dashboard is not running or ref pan machines update [--now] [--machine <label>]... [--cancel] [--json] ``` -Starts **Update all**: each online machine updates its installed harness CLIs (Claude -Code, Codex CLI, Kimi Code CLI, OpenCode) with their own update commands, then updates +Starts **Update all**: each online machine updates the harness CLIs installed there that +it knows how to update (Claude Code, Codex CLI, Kimi Code CLI, OpenCode, Grok Build, and +Pi when it was installed with npm). A CLI installed with npm is updated with +`npm install -g` into its own npm prefix; otherwise the CLI's own update command runs. A +CLI installed with Homebrew, or one with no update command, is left alone. Then it updates Overdeck itself on an `npm install -g` install or a machine set up with `pan connect` (into its `~/.overdeck/runtime`), and restarts its dashboard. By default each machine waits until no turn is running there. A development checkout or the desktop app @@ -474,7 +492,7 @@ Run `pan machines versions` to follow the update. | --- | --- | | `--now` | Do not wait for running turns to end. On a machine already waiting, this starts its update at once. | | `--machine <label>` | Only this machine; repeat for more. An unknown label prints `No machine named <label>` and exits 1. | -| `--cancel` | Cancel waiting updates (on every machine, or on the `--machine` ones). | +| `--cancel` | Cancel waiting updates (on every machine, or on the `--machine` ones) and print `Cancelled on <label>` for each. | | `--json` | Print `{ started, skipped }` as JSON. | Exit codes: 0 when the request went out, even if some machines were skipped; 1 when the @@ -495,6 +513,9 @@ login shell: it saves that shell's `PATH` for the service, so agents started lat `node` and the harness CLIs. Linux and macOS only; on Windows it exits 1 and asks you to run it inside WSL. +<Note>Running `npx @overdeck/core connect` as a systemd service on a fresh VPS has not yet +been tested end to end on a real VPS ([#4863](https://github.com/eltmon/overdeck/issues/4863)).</Note> + | Flag | Effect | | --- | --- | | `--url <base>` | Address the other machine reaches this one at, such as `https://box.example.com`. Default: picked automatically (see below). | @@ -575,7 +596,7 @@ macOS blocks the server's connections to other machines on this network until yo Turn on `node` at the printed path in **System Settings → Privacy & Security → Local Network**; the entry only appears there after the server's first attempt to reach another machine, so it will not be listed immediately after `pan connect`. Homebrew's `node` is -ad-hoc signed, so macOS can treat an upgraded binary as a new app — check the grant again +ad-hoc signed, so macOS can treat an upgraded binary as a new app: check the grant again after `brew upgrade node`. When `node` is not in the list at all, link over Tailscale instead (`pan tailscale setup`). @@ -612,9 +633,10 @@ machine must reach. If a firewall blocks that port, open it or set up Tailscale On a Linux machine with lingering on, systemd starts the supervisor at boot. The watchdog waits out its 5-minute boot grace and then starts the dashboard, so the dashboard answers -within about 6 minutes. A linked machine retries with a back-off of up to 5 minutes, so it -shows this machine **online** again within about 15 minutes. If Traefik is enabled here, -the output adds that Traefik and CLIProxy wait for `pan up` after a reboot. +within about 6 minutes. A linked machine retries a failed connection with a back-off of at +most about 45 seconds, so it shows this machine **online** again within about a minute +after the dashboard answers. If Traefik is enabled here, the output adds that Traefik and +CLIProxy wait for `pan up` after a reboot. ### Updating and removing @@ -646,9 +668,9 @@ harness CLIs and Herdr: run `~/.overdeck/runtime/node_modules/.bin/pan install` ### Troubleshooting -The watchdog stops restarting the dashboard after three failed restarts in a row, and it -remembers that across supervisor restarts (and so across reboots). If the dashboard is -still down after a reboot, start it by hand: +The watchdog stops restarting the dashboard after three restarts within five minutes that +do not bring it back healthy, and it remembers that across supervisor restarts (and so +across reboots). If the dashboard is still down after a reboot, start it by hand: ```bash ~/.overdeck/runtime/node_modules/.bin/pan restart --dashboard --now @@ -656,3 +678,6 @@ still down after a reboot, start it by hand: Do not use `pan up` for this on a server: it expects the full host setup from `pan install` (terminal backend and sidecars), which a fresh server may not have. + +Still stuck? Ask in the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or open a +[GitHub issue](https://github.com/eltmon/overdeck/issues). From 667033c27b1587a634868f04408c7b04cd0dad98 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:51:45 -0500 Subject: [PATCH 23/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 22d97ac7b13..f421ae8ddda 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:49:07.644Z", + "updated": "2026-11-19T03:51:45.647Z", "gitState": {}, "decisions": [], "hazards": [], @@ -154,9 +154,30 @@ "doneAt": "2026-11-19T03:49:00.910Z" }, "audit-machines": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T03:49:07.643Z" + "claimedAt": "2026-11-19T03:49:07.643Z", + "doneAt": "2026-11-19T03:51:45.647Z" + }, + "audit-machines.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:51:45.647Z" + }, + "audit-machines.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:51:45.647Z" + }, + "audit-machines.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:51:45.647Z" + }, + "audit-machines.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:51:45.647Z" + }, + "audit-machines.ac5": { + "status": "completed", + "doneAt": "2026-11-19T03:51:45.647Z" } } } From c6b56a560bc57fc47e22c87b0cc7966841282c8d Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:51:53 -0500 Subject: [PATCH 24/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index f421ae8ddda..10df5eb642a 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:51:45.647Z", + "updated": "2026-11-19T03:51:53.269Z", "gitState": {}, "decisions": [], "hazards": [], @@ -178,6 +178,11 @@ "audit-machines.ac5": { "status": "completed", "doneAt": "2026-11-19T03:51:45.647Z" + }, + "audit-pair": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T03:51:53.269Z" } } } From 1f0e6ef3d956e2229fc59b7aad7de93f6c7871b7 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:53:13 -0500 Subject: [PATCH 25/80] docs(cli/pair): replace stale release note and fix error texts Applies Appendix E rows 1-4 and every [ADD] Missing bullet to cli/pair.mdx: the dashboard pairing dialog is no longer "in the next release" (it shipped in v0.65.0); the loopback warning now names OVERDECK_TRUSTED_ORIGINS; the token-rejection error matches the real message; adds the pan pair failed fallback, the shared-credential note for pan machines link, the URL-fragment privacy note and the --label length limit. Retitles per D4 and appends the help sentence to ## Errors per D3. Item: audit-pair Item: audit-pair.ac1 Item: audit-pair.ac2 Item: audit-pair.ac3 Item: audit-pair.ac4 PR-note: cli/pair.mdx: fixed release note and error texts (Appendix E) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- cli/pair.mdx | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/cli/pair.mdx b/cli/pair.mdx index 6f0d17b5ddd..08f44b3c1a0 100644 --- a/cli/pair.mdx +++ b/cli/pair.mdx @@ -1,5 +1,6 @@ --- -title: pan pair +title: "pan pair: pair a device with your dashboard" +sidebarTitle: pan pair description: Print a one-time URL that pairs another device with this machine's dashboard --- @@ -10,13 +11,18 @@ pan pair [--label <name>] [--url <base>] [--json] ``` Prints a one-time URL that pairs another device (a laptop, a tablet, a second desktop) with -this machine's dashboard. Released in v0.64.0. The dashboard's **Pair a device** dialog is -in the next release (v0.65.0). See [Remote access](/configuration/remote-access) and -[pan devices](/cli/devices). +this machine's dashboard. Released in v0.64.0. **Settings → Anywhere → Pair a device** in +the dashboard does the same and also shows a QR code. See +[Remote access](/configuration/remote-access) and [pan devices](/cli/devices). + +The same link also links a machine: run `pan machines link '<url>'` on the other machine +(the first use wins, browser or machine). See [`pan machines link`](/cli/machines#link). +The credential is always in the URL fragment (`#pair=`), never a query string, so it never +reaches a server log. | Flag | Effect | | --- | --- | -| `--label <name>` | Name recorded for the pairing in the activity log. | +| `--label <name>` | Name recorded for the pairing in the activity log. Must be a non-empty string of at most 200 characters, or the dashboard answers 400. | | `--url <base>` | Base URL the other device can reach (default: this dashboard's API URL). | | `--json` | Print `{ url, credential, expiresAt }` as JSON. | @@ -35,14 +41,20 @@ The credential works once, expires 10 minutes after it is created, and a dashboa invalidates every credential that has not been used yet. When the base is `localhost`, `127.0.0.1`, `::1` or `*.localhost`, `pan pair` warns that the -URL only works on this machine. With `--json` the warning goes to stderr; the JSON itself -still goes to stdout. +URL only works on this machine and tells you to pass `--url` with an address the other +device can reach and add that origin to `OVERDECK_TRUSTED_ORIGINS`. With `--json` the +warning goes to stderr; the JSON itself still goes to stdout. ## Errors - No running dashboard: `` `Overdeck dashboard is not running; start it with `pan up`.` ``, exit 1. -- A dashboard that rejects this machine's internal token (for example a `pan serve` server, - which does not share it): `` `The dashboard rejected this machine's internal token. `pan - pair` needs a dashboard started by `pan up` (a `pan serve` server does not share - it).` ``, exit 1. +- A dashboard that rejects this machine's internal token: `` The dashboard rejected this + machine's internal token (from $OVERDECK_HOME/internal-token, default + ~/.overdeck/internal-token). The running dashboard holds a different token: it uses + another OVERDECK_HOME, or it was started before that file existed. Restart it with + `pan up` or `npx @overdeck/core`, then run this command again. ``, exit 1. +- Any other dashboard error: `pan pair failed: <message>`, exit 1. + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From d0421f959e0976801704d294808feb9d34a1f653 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:53:37 -0500 Subject: [PATCH 26/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 10df5eb642a..08ce2b5f0ec 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:51:53.269Z", + "updated": "2026-11-19T03:53:37.218Z", "gitState": {}, "decisions": [], "hazards": [], @@ -180,9 +180,26 @@ "doneAt": "2026-11-19T03:51:45.647Z" }, "audit-pair": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T03:51:53.269Z" + "claimedAt": "2026-11-19T03:51:53.269Z", + "doneAt": "2026-11-19T03:53:37.217Z" + }, + "audit-pair.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:53:37.217Z" + }, + "audit-pair.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:53:37.217Z" + }, + "audit-pair.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:53:37.217Z" + }, + "audit-pair.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:53:37.217Z" } } } From b55fe8a087dc7f5b3456bb30df219c6d203eead0 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:53:43 -0500 Subject: [PATCH 27/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 08ce2b5f0ec..319803d98fc 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:53:37.218Z", + "updated": "2026-11-19T03:53:43.678Z", "gitState": {}, "decisions": [], "hazards": [], @@ -200,6 +200,11 @@ "audit-pair.ac4": { "status": "completed", "doneAt": "2026-11-19T03:53:37.217Z" + }, + "audit-devices": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T03:53:43.677Z" } } } From 8dfb60196a16ca36d553b9634bb246627a320d00 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:54:18 -0500 Subject: [PATCH 28/80] docs(cli/devices): remove stale release note, cover paired phones Applies Appendix F rows 1-5 and every [ADD] Missing bullet to cli/devices.mdx: the dashboard Revoke button is no longer "next release"; list and --json now cover paired phones and the kind field; revoke documents the phone secure-channel close and the offline phone-revoke limitation; and both verbs document the token-rejection and generic failure errors. Retitles per D4 and adds Get help per D3. Item: audit-devices Item: audit-devices.ac1 Item: audit-devices.ac2 Item: audit-devices.ac3 Item: audit-devices.ac4 PR-note: cli/devices.mdx: removed stale note, covered phones (Appendix F) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- cli/devices.mdx | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/cli/devices.mdx b/cli/devices.mdx index 04c10e7e514..cfd13e91b34 100644 --- a/cli/devices.mdx +++ b/cli/devices.mdx @@ -1,12 +1,13 @@ --- -title: pan devices +title: "pan devices: list and revoke paired devices" +sidebarTitle: pan devices description: List or revoke the devices paired with this machine's dashboard --- # `pan devices` -Manage the devices paired with this machine's dashboard. Released in v0.64.0. Settings → -Anywhere's **Revoke** has the same effect (next release, v0.65.0). See +Manage the devices paired with this machine's dashboard. Released in v0.64.0. The +**Revoke** button in **Settings → Anywhere → Paired devices** does the same. See [Remote access](/configuration/remote-access#list-and-revoke-devices). ## list @@ -15,15 +16,19 @@ Anywhere's **Revoke** has the same effect (next release, v0.65.0). See pan devices list [--json] ``` -Lists paired devices with columns `ID NAME CREATED LAST USED REVOKED`. +Lists paired browser devices and paired phones (the Overdeck app) with columns +`ID NAME CREATED LAST USED REVOKED`. | Flag | Effect | | --- | --- | -| `--json` | Print the device array as JSON. | +| `--json` | Print the device array as JSON; each entry has `id`, `name`, `kind` (`device` or `phone`), `scopes`, `createdAt`, `lastUsedAt` and `revokedAt`. | With no paired devices: `` `No paired devices. Pair one with `pan pair`.` `` It needs the running dashboard: without one it prints the not-running message and exits 1. +A dashboard that rejects the internal token prints the same token message as `pan pair` +and exits 1. Any other dashboard error prints `pan devices list failed: <message>` and +exits 1. ## revoke @@ -31,7 +36,8 @@ It needs the running dashboard: without one it prints the not-running message an pan devices revoke <id> ``` -Revoke a paired device and close its live connections. +Revoke a paired device and close its live connections. Revoking a phone also closes its +secure-channel connections. Through the dashboard it prints: @@ -39,11 +45,21 @@ Through the dashboard it prints: Revoked device "<name>" (<id>); its live connections were closed. ``` -With no dashboard running it writes the revocation into `~/.overdeck/access-tokens.json` -and prints: +With no dashboard running it writes the revocation of a paired browser device into +`~/.overdeck/access-tokens.json` and prints: ``` Dashboard not running; revoked in the registry. No live connections were open. ``` -An unknown id prints `No paired device with id <id>.` and exits 1. +A phone cannot be revoked this way: with the dashboard down, a phone's id prints +`No paired device with id <id>.` Start the dashboard and run the command again. + +An unknown id prints `No paired device with id <id>.` and exits 1. A dashboard that +rejects the internal token prints the same token message as `pan pair` and exits 1. Any +other dashboard error prints `pan devices revoke failed: <message>` and exits 1. + +## Get help + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From 75a2ecf4a4d3f7593c3204daec17b30835c31616 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:54:40 -0500 Subject: [PATCH 29/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 319803d98fc..c13fcb433b9 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:53:43.678Z", + "updated": "2026-11-19T03:54:40.530Z", "gitState": {}, "decisions": [], "hazards": [], @@ -202,9 +202,26 @@ "doneAt": "2026-11-19T03:53:37.217Z" }, "audit-devices": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T03:53:43.677Z" + "claimedAt": "2026-11-19T03:53:43.677Z", + "doneAt": "2026-11-19T03:54:40.529Z" + }, + "audit-devices.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:54:40.529Z" + }, + "audit-devices.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:54:40.529Z" + }, + "audit-devices.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:54:40.529Z" + }, + "audit-devices.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:54:40.529Z" } } } From ee2cb33ed20b22e932fc5b24c96221292bf013a4 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:54:47 -0500 Subject: [PATCH 30/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index c13fcb433b9..27a212f5d07 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:54:40.530Z", + "updated": "2026-11-19T03:54:47.158Z", "gitState": {}, "decisions": [], "hazards": [], @@ -222,6 +222,11 @@ "audit-devices.ac4": { "status": "completed", "doneAt": "2026-11-19T03:54:40.529Z" + }, + "mcp-top": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T03:54:47.158Z" } } } From c6dca9646ff3d8c8c6bd87c8330ca721873fed95 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:56:29 -0500 Subject: [PATCH 31/80] docs(mcp): fix harness list, tool parameters and agent-only routes Applies Appendix G rows 1-12 to lines 1-461 of configuration/mcp.mdx: adds grok to the launched-agent harness list; links Fleet reach and Revoking instead of naming unlinked sections; documents missing tool parameters (read_conversation limit, schedule_message/recurring fields, answer_permission's signature, worker_report's Markdown report, memory_search's query); and corrects which agent-only tools go through /api/self/ versus the lane and worker-stop routes directly. Links the triggers cross references. Removes every em/en dash in the item's range. Item: mcp-top Item: mcp-top.ac1 Item: mcp-top.ac2 Item: mcp-top.ac3 Item: mcp-top.ac4 PR-note: mcp.mdx: fixed harness list, tool parameters (Appendix G 1-12) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- configuration/mcp.mdx | 40 +++++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/configuration/mcp.mdx b/configuration/mcp.mdx index 2f2f2e21040..72779f28334 100644 --- a/configuration/mcp.mdx +++ b/configuration/mcp.mdx @@ -6,7 +6,7 @@ description: "Overdeck's MCP server: the tools every managed agent gets, and sco Overdeck serves a Model Context Protocol (MCP) server, so another tool (Claude Desktop, another agent harness, a chat bot) can list conversations, read one, send a message, start a conversation or a worker, and answer prompts that wait -on you. It reaches this machine and the machines it is linked to (see Fleet reach). +on you. It reaches this machine and the machines it is linked to (see [Fleet reach](#fleet-reach)). Overdeck's anonymous telemetry records which MCP surface, protocol revision and client family opened a session and which tools were called, at most once a day @@ -14,7 +14,7 @@ each (a connector that restarts during the day can send again), never names, versions, tokens or arguments. See [Telemetry](/configuration/telemetry) to turn it off. -Every agent Overdeck launches on Claude Code, Codex, `acp` or `opencode` gets +Every agent Overdeck launches on Claude Code, Codex, `acp`, `opencode` or `grok` gets this server with its own token (see [Agents get these tools](#agents-get-these-tools)), and outside tools and bots reach it with a token you create. It is separate from the Channels bridge (`overdeck-bridge`), which delivers messages into one @@ -29,9 +29,9 @@ There is no second path to any operation. | Tool | What it does | Scope the token needs | | --- | --- | --- | | `list_machines` | Lists this machine and its linked machines with their state, load and capability tags. | `read:state` | -| `list_conversations` | Lists recent conversations with status, harness, model and pending input. `limit` 1–200, default 50. | `read:conversations` | -| `search_conversations` | Searches conversations by title and content. `query`, `limit` 1–50, default 20. | `read:conversations` | -| `read_conversation` | Reads one conversation's messages. Pass a page cursor as `before` for older messages. | `read:conversations` | +| `list_conversations` | Lists recent conversations with status, harness, model and pending input. `limit` 1 to 200, default 50. | `read:conversations` | +| `search_conversations` | Searches conversations by title and content. `query`, `limit` 1 to 50, default 20. | `read:conversations` | +| `read_conversation` | Reads one conversation's messages. Pass a page cursor as `before` for older messages, with an optional `limit` of 1 to 500 rows. | `read:conversations` | | `send_message` | Sends a message to a running conversation. | `tell` (`operate` includes it) | | `start_conversation` | Starts a conversation with a first message. Optional `projectKey`, `model`, `harness`, `effort`, `issueId`, `machine` (a label, environment id or `auto`), `needs`. | `operate` | | `start_worker` | Starts a registered worker on an issue that has a workspace on the chosen machine. `issueId`, `prompt`, optional `model`, `harness`, `effort`, `readOnly`, `name`, `machine`, `needs`. | `operate` | @@ -40,15 +40,15 @@ There is no second path to any operation. | `resume_conversation` | Resumes a stopped conversation on its transcript, as the dashboard's Resume button does. A conversation that still runs is reattached, not started twice. `conversation` (`@<machine>/<name>` for one on a linked machine). | `operate` | | `add_skills` | Loads skill packs or pack skills into a conversation, by default the caller's own. Claude Code loads them in place (from the caller's own conversation they arrive when its current turn ends); Codex and native skills need a restart. `conversation` (omit for your own), `packs` (pack ids; every non-opt-in skill), `skills` (`pack/skill` ids), `restart` (restart a named conversation that cannot load them in place). | `operate` | | `interrupt_conversation` | Interrupts the current turn of a Pi conversation. Other harnesses answer an error; use `stop_conversation` to end them. | `operate` | -| `schedule_message` | Queues a message for a Claude Code conversation that Overdeck sends after its usage limit resets, or at once if it is not limited. At most 20 queued; `/pan` commands are refused. | `tell` | -| `schedule_recurring` | Creates a recurring schedule: `prompt`, a 5-field `cron` (runs at least 15 minutes apart), optional `timeZone` (default: the Overdeck machine's zone) and `enabled`. Not for agent conversations. | `tell` | +| `schedule_message` | Queues a message for a Claude Code conversation that Overdeck sends after its usage limit resets, or within a minute if it is not limited. Takes `conversation` and `message`. At most 20 queued; `/pan` commands are refused. | `tell` | +| `schedule_recurring` | Creates a recurring schedule: `prompt`, a 5-field `cron` (runs at least 15 minutes apart), optional `timeZone` (default: the Overdeck machine's zone) and `enabled`. Takes `conversation`. Agent conversations and Session Vault copies cannot be scheduled; at most 20 schedules per conversation. | `tell` | | `list_scheduled` | Lists a conversation's pending one-shot messages (`once`) and its schedules (`recurring`). | `read:conversations` | | `update_scheduled` | `kind: once` replaces a pending message's text; `kind: recurring` changes `prompt`, `cron`, `timeZone` or `enabled` (pause or resume). | `tell` | | `delete_scheduled` | `kind: once` cancels an unsent message; `kind: recurring` deletes a schedule. | `tell` | | `link_pull_request` | Links a pull or merge request (`ref`: a URL, `#42`, or `owner/repo#42`) to a conversation (`conversation`, `@<machine>/<name>` for one on a linked machine). An Overdeck agent may omit `conversation` to link to its own conversation. | `tell` | | `list_pending_input` | Lists what waits on input on this machine and every online linked machine, conversations and agents, grouped by machine. | `read:conversations` | | `answer_question` | Answers a pending question of a Claude Code conversation (`conversation`) or of an agent on this machine (`agentId`, optional `toolUseId`). | `tell` and `approve` | -| `answer_permission` | Answers a Claude Code permission prompt with `allow-once`, `allow-always` or `deny`. | `approve` | +| `answer_permission` | Answers a Claude Code permission prompt: `conversation`, the prompt's `signature` from `list_pending_input`, and `choice` (`allow-once`, `allow-always` or `deny`). | `approve` | | `answer_pane_choice` | Chooses an option (`selectedIndex` 0-8) in a numbered menu shown in a Claude Code conversation, with its `signature`. | `approve` | | `answer_codex_approval` | Answers a Codex conversation's approval prompt with the 1-based `optionNumber`, and `toolUseId` when the app-server transport needs it. | `approve` | | `answer_pi_ask` | Answers a Pi conversation's ask prompt: `toolUseId` and exactly one `answers` entry. | `approve` | @@ -74,7 +74,7 @@ agent tokens. | `task_block` | Marks a checklist item blocked, optionally on issues or PRs (`on`), and wakes the agent when they merge (`pan task block`). | `tell` (agent tokens only) | | `done` | Signals the issue's work is complete: push, PR, tracker In Review, review started (`pan done`). | `operate` (agent tokens only) | | `handoff` | Hands the conversation off to a new one with a `focus` and optional `title` (`pan handoff self`). Not for work agents, which have no conversation. | `tell` (agent tokens only) | -| `worker_report` | Records a worker's report with `status` `done`, `blocked` or `failed` (`pan worker report`). Workers only. | `tell` (agent tokens only) | +| `worker_report` | Records a worker's Markdown `report` with `status` `done`, `blocked` or `failed` (`pan worker report`). Workers only. | `tell` (agent tokens only) | | `request_secret` | Asks the operator for a secret, such as an API key, by an environment-variable-style `name` and a short `prompt`; answers a `requestId` and `next`, the `secret_wait` call to make. | `tell` (agent tokens only) | | `secret_wait` | Waits up to 50 s for the operator's answer. Answers `pending` with `next`, `delivered` with `file` (the path of the secret, never the value), `declined` or `expired`. | `read:state` (agent tokens only) | | `watch_pull_request` | Watches a GitHub pull request (`url`); get a message in this conversation when its checks fail or pass, its review changes, it gets merge conflicts, or it is merged or closed. | `tell` (agent tokens only) | @@ -83,7 +83,7 @@ agent tokens. | `link_machine` | Asks the operator to link a machine the agent was told about, by a `hint` such as "my desk Mac"; answers a `requestId` and `next`, the `link_machine_wait` call to make. | `tell` (agent tokens only) | | `link_machine_wait` | Waits up to 50 s. Answers `pending` with `next`, `linked` with `machine` (`environmentId` and `label`), `declined` or `expired`. | `read:state` (agent tokens only) | | `memory_add` | Records a curated memory fact by running `pan memory add` in the agent's checkout: `id`, `type` (`feedback`, `project`, `reference`, `user`), a one-line `description`, optional `title`, `body`, `tags` and `store` (`project` by default, `user` for type `user`, or `machine`). A project fact is written uncommitted, so the agent commits `.overdeck/memory/<id>.md`. | `tell` (agent tokens only) | -| `memory_search` | Searches memory by running `pan memory search --facts`: up to 5 matching facts from the agent's checkout, the operator store and the machine store, each with its file path, then observations from the agent's project (`limit` 1-20, default 10). | `read:state` (agent tokens only) | +| `memory_search` | Searches memory for `query` (at most 500 characters) by running `pan memory search --facts`: up to 5 matching facts from the agent's checkout, the operator store and the machine store, each with its file path, then observations from the agent's project (`limit` 1-20, default 10). | `read:state` (agent tokens only) | | `delegate_task` | Starts a worker on your own issue to do `task`, here or on `machine`; you are its parent. Optional `harness`, `model`, `effort`, `readOnly`, `name`, `needs`. A caller without an issue gets `delegate_task needs an issue; use start_conversation`. | `operate` (agent tokens only) | | `task_wait` | Waits up to 50 s for one of your workers to report. Answers `done` with the report, `ended` when it stopped without one (with its last message), or `running` with `next`. Pass `afterSeq` for the report after the one you consumed. | `read:state` (agent tokens only) | | `task_status` | One of your workers: state, idle time, where it runs and its newest report's seq, time and status. Your workers only, including ones on linked machines. | `read:state` (agent tokens only) | @@ -103,8 +103,9 @@ output, or `running` with `next`, a `wait_job` call to make again. A non-zero exit code means `pan` refused; stderr says why. Review, test and ship agents lack `operate`, so `done` is hidden from them. -Agent-only tools call routes under `/api/self/`, which refuse any token that -is not an agent token. +Most agent-only tools call routes under `/api/self/`, which refuse any token that is not +an agent token. `lane_status` and `lane_stop` call the lane routes, and `task_cancel` +calls the worker stop route after an owner check, so the token's scopes judge those. ### Secrets @@ -185,7 +186,7 @@ still refuse a listed tool, for example a linked machine's ceiling, with `watch_pull_request` gets an agent a message when a GitHub pull request it cares about changes, without needing a conversation of its own. Overdeck checks watched pull requests about once a minute, through the existing PR -sync sweep on this machine's primary dashboard — never a separate poller. +sync sweep on this machine's primary dashboard, never a separate poller. GitHub pull requests only; GitLab merge requests are refused. A watch delivers one message per change, naming every event the change @@ -304,11 +305,11 @@ names it. 1. Your app opens a sign-in page in your browser. The page shows the app's name, where it will send you back, and an approval code such as `KQZT-MWRB`. 2. The dashboard's Needs you panel shows a card with the app's name, the - redirect host, and the same approval code — or run `pan mcp oauth pending` + redirect host, and the same approval code, or run `pan mcp oauth pending` from a terminal on this machine. Only this machine's own session can see it: on its desktop layout that's the full card below; on its mobile layout, which has no room for the card, it's "Approve on the desktop" - instead. A paired device never receives the pending sign-in at all — there + instead. A paired device never receives the pending sign-in at all: there is nothing to approve from someone else's phone. 3. You check that the card's code matches the page you opened, pick an access level (the select starts at the level the app asked for), and click @@ -374,8 +375,9 @@ for hosted bots", or with `PUT /api/mcp/public` and the body `{ "enabled": true it on. The dashboard reads the value once and keeps it, so a hand edit of `config.yaml` takes effect after a dashboard restart or the next switch change. -**Prerequisites** are the same as for triggers (see Triggers → Publish with -Tailscale Funnel): HTTPS certificates on the tailnet, the `funnel` node +**Prerequisites** are the same as for triggers (see +[Publish with Tailscale Funnel](/configuration/triggers#publish-with-tailscale-funnel)): +HTTPS certificates on the tailnet, the `funnel` node attribute for this machine, `sudo tailscale set --operator=$USER`, and this machine's `.ts.net` address saved as a trusted address. Without that trusted address the dashboard cannot build the public URL, and the sign-in documents @@ -413,7 +415,7 @@ pass the access token in the `authorization` field of an `mcp` tool, with **What is reachable.** While the switch is on, a Funnel request reaches only these nine surfaces, matched on the exact path, plus the trigger route `POST /hooks/*`, which Funnel reaches whether or not Public MCP is on (see -Triggers). Every other path gets 404: +[Triggers](/configuration/triggers)). Every other path gets 404: - `POST /mcp` - `GET /.well-known/oauth-protected-resource` @@ -455,7 +457,7 @@ time. `POST /hooks/*` keeps working for triggers. It does not end any sign-in: approved apps keep working on the tailnet and this machine. End a sign-in under **Settings → Access Tokens → Sign-ins** or with -`pan mcp oauth revoke <sign-in id>` (see Revoking below). +`pan mcp oauth revoke <sign-in id>` (see [Revoking](#revoking)). ## Agents get these tools From a3dad9d41871a75c153068486f8f870f51350ab7 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:56:51 -0500 Subject: [PATCH 32/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 27a212f5d07..62b6b11c796 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:54:47.158Z", + "updated": "2026-11-19T03:56:51.524Z", "gitState": {}, "decisions": [], "hazards": [], @@ -224,9 +224,26 @@ "doneAt": "2026-11-19T03:54:40.529Z" }, "mcp-top": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T03:54:47.158Z" + "claimedAt": "2026-11-19T03:54:47.158Z", + "doneAt": "2026-11-19T03:56:51.523Z" + }, + "mcp-top.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:56:51.523Z" + }, + "mcp-top.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:56:51.523Z" + }, + "mcp-top.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:56:51.523Z" + }, + "mcp-top.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:56:51.523Z" } } } From 3ffad5f8ef4d8f816da9514d2347665a4edbf744 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:56:58 -0500 Subject: [PATCH 33/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 62b6b11c796..6d291e1e724 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:56:51.524Z", + "updated": "2026-11-19T03:56:58.778Z", "gitState": {}, "decisions": [], "hazards": [], @@ -244,6 +244,11 @@ "mcp-top.ac4": { "status": "completed", "doneAt": "2026-11-19T03:56:51.523Z" + }, + "mcp-bottom": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T03:56:58.778Z" } } } From 31e77d7ba1ee894190e9bae0ade4b5f520d24ef5 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:59:06 -0500 Subject: [PATCH 34/80] docs(mcp): fix provisioning tables, scopes and fleet reach Applies Appendix G rows 13-24 and every [ADD] Missing bullet (lines 461-782, D4) to configuration/mcp.mdx: adds grok everywhere agents get the overdeck server and to the provisioning/pack-server tables; adds pi to the not-provisioned rows; documents the semgrep MCP server for work agents and in the precedence sentence; corrects operate's and approve's tool counts; and adds start_issue/delegate_task/lane_start to the fleet-reach machine-param list. Retitles per D4 and adds ## Get help after Fleet reach per D3. Removes every remaining em/en dash in the file. Item: mcp-bottom Item: mcp-bottom.ac1 Item: mcp-bottom.ac2 Item: mcp-bottom.ac3 Item: mcp-bottom.ac4 Item: mcp-bottom.ac5 PR-note: mcp.mdx: fixed provisioning/scopes/fleet reach (Appendix G 13-24) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- configuration/mcp.mdx | 54 ++++++++++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 19 deletions(-) diff --git a/configuration/mcp.mdx b/configuration/mcp.mdx index 72779f28334..38bb62d9cd0 100644 --- a/configuration/mcp.mdx +++ b/configuration/mcp.mdx @@ -1,5 +1,6 @@ --- -title: "MCP server" +title: "Overdeck MCP server: tools, scopes and agent tokens" +sidebarTitle: "MCP server" description: "Overdeck's MCP server: the tools every managed agent gets, and scoped, revocable access for outside tools and bots" --- @@ -461,8 +462,8 @@ sign-in under **Settings → Access Tokens → Sign-ins** or with ## Agents get these tools -Every Claude Code, Codex, Kimi Code ACP (`acp`) and OpenCode (`opencode`) agent -that Overdeck launches on this machine starts with the `overdeck` server: work +Every Claude Code, Codex, Kimi Code ACP (`acp`), OpenCode (`opencode`) and Grok Build +(`grok`) agent that Overdeck launches on this machine starts with the `overdeck` server: work agents, role runs (plan, review, test, ship, worker and the others), planning sessions and conversations. You do not create a token for them. @@ -476,7 +477,7 @@ launcher script holds the token. The launcher passes prompt. Roles with a `tools:` list (review, test) get `mcp__overdeck` in that list instead. -An ACP agent gets the same `overdeck-mcp.json`. The launcher passes +An ACP-hosted agent (`acp`, `opencode` or `grok`) gets the same `overdeck-mcp.json`. The launcher passes `--mcp-config <file>` to the ACP host, which sends the server to the agent in `session/new` and `session/load`. The ACP host approves the agent's permission requests itself, so no allow-list is needed. @@ -489,7 +490,7 @@ MCP allow-list, so instead of a launcher flag it gets an conversation), alongside any MCP servers the role itself declares. The table names only the token file in its `env`, never the token. It also carries `default_tools_approval_mode = "approve"`, because Overdeck's MCP tools carry -no `readOnlyHint` annotations — without that key, Codex refuses every +no `readOnlyHint` annotations: without that key, Codex refuses every model-initiated call with "MCP tool call requires approval, but approval policy is never" under `approval_policy = "never"`. @@ -506,6 +507,9 @@ The token's scopes follow the agent's role: A resumed, recovered or relaunched agent keeps the same server and reuses its live token. Stopping the agent revokes the token. +Work agents and the review security lane also get a `semgrep` MCP server when +Semgrep's MCP server is on; see [Semgrep](/configuration/semgrep#semgrep-mcp-server). + To turn injection off, set this in `config.yaml`: ```yaml @@ -515,7 +519,7 @@ mcp: These launches get no server: Docker workspaces (`OVERDECK_DOCKER_WORKSPACE=1` or `PAN_DOCKER=1`), bare conversations, Fly machines, and harnesses other than -Claude Code, Codex, `acp` and `opencode`. When the token cannot be +Claude Code, Codex, `acp`, `opencode` and `grok`. When the token cannot be minted or the config cannot be written, the agent starts without the server and the log shows one `[agent-injection] overdeck MCP skipped for <id>: <reason>` warning. The agent can still reach Overdeck through `pan`. @@ -529,9 +533,9 @@ the MCP tools to `pan`; never poll, call `next` again when a wait tool answers `running` or `pending`; checklist with `task_claim`/`task_done`, finish with `done`; get a secret with `request_secret`; link a machine the operator names with `link_machine`; link a PR with `link_pull_request`/`watch_pull_request`. -Every other agent — `kimi-code`, `ohmypi`, `muse`, `prime-agent`, any agent in -a Docker workspace, and every agent when `mcp.agents` is `false` — is told -"Overdeck commands" instead, with the `pan` equivalent for each of those. +Every other agent is told "Overdeck commands" instead, with the `pan` equivalent for +each: `pi`, `kimi-code`, `ohmypi`, `muse`, `prime-agent`, any agent in a Docker +workspace, and every agent when `mcp.agents` is `false`. ## Project MCP servers @@ -598,8 +602,8 @@ never in `projects.yaml` or the repo. | --- | --- | | `claude-code` | stdio and http, in the same `overdeck-mcp.json` as the `overdeck` server | | `codex` | stdio and http (`url` plus `http_headers`) in `codex-home-v2/config.toml`, each with `default_tools_approval_mode = "approve"`. Codex skips an `npx` server whose package has no exact version, the same rule as role servers (PAN-2698). | -| `acp`, `opencode` | stdio only, through the same `overdeck-mcp.json`. The ACP host drops http entries with a warning. | -| `ohmypi`, `kimi-code`, `muse`, `prime-agent` | not provisioned. Each launch logs one warning naming the harness and the servers it cannot use. | +| `acp`, `opencode`, `grok` | stdio only, through the same `overdeck-mcp.json`. The ACP host drops http entries with a warning. | +| `pi`, `ohmypi`, `kimi-code`, `muse`, `prime-agent` | not provisioned. Each launch logs one warning naming the harness and the servers it cannot use. | The launch file is written whenever at least one server resolves, so project servers still load when `mcp.agents` is `false` or the agent token could not be @@ -665,8 +669,9 @@ of its skills resolves on for that launch, including the conversation layer. A pack that is off contributes nothing, consented or not. **Precedence.** Names are claimed in this order: `overdeck`, then the -launching role's own servers, then the project's `mcp_servers`, then pack -servers, lowest pack id first. A later source's server with a name an earlier +launching role's own servers, then the `semgrep` server when Semgrep's MCP +server is on (see [Semgrep](/configuration/semgrep#semgrep-mcp-server)), then +the project's `mcp_servers`, then pack servers, lowest pack id first. A later source's server with a name an earlier source already claimed is skipped with one warning, `[pack-mcp] <pack>: server <name> skipped: <reason>`. A project `mcp_servers` entry named `atlassian` therefore overrides the `atlassian` pack's own server, @@ -679,8 +684,8 @@ which is the escape for an OAuth-only or Bearer-key setup (see | --- | --- | | `claude-code` | the same `overdeck-mcp.json` as `overdeck` and project servers, after them; `--allowedTools=` gains each pack server name | | `codex` | `codex-home-v2/config.toml`, each with `default_tools_approval_mode = "approve"` | -| `acp`, `opencode` | none: the ACP host drops http entries | -| `ohmypi`, `kimi-code`, `muse`, `prime-agent` | not provisioned | +| `acp`, `opencode`, `grok` | none: the ACP host drops http entries | +| `pi`, `ohmypi`, `kimi-code`, `muse`, `prime-agent` | not provisioned | ### Atlassian auth @@ -698,7 +703,7 @@ gets no `atlassian` server at all, with one warning naming it. See An MCP token is an ordinary access token. Copy MCP URL gives it `read:state`, `read:conversations` and `operate` by default. `operate` covers `tell`, the -start tools and the stop and interrupt tools. +start tools, the stop, resume and interrupt tools, and `add_skills`. The box **Allow answering questions and approving permissions** adds `approve`. It is off by default, and only `approve` or `admin` satisfies it. @@ -711,7 +716,7 @@ for the full scope table. <Warning> `approve` does not stop text from reaching a conversation that waits on a question. A token with `tell` can still send any message with `send_message`. -What `approve` gates is the keystroke-driven answers and the two answer tools. +What `approve` gates is the keystroke-driven answers and the eight answer tools. </Warning> MCP never accepts an `admin` token, the machine's internal token or the @@ -740,7 +745,7 @@ tokens; click it to reveal and revoke an individual agent's token. Hermes, OpenClaw, Grok Build, Grok Bot and the xAI API reach this server through **Connect a bot** in Settings → Anywhere → Bots. A bot with a shell -connects in one paste with **Copy for <bot>** — see +connects in one paste with **Copy for <bot>**; see [Connect in one paste](/configuration/bots#connect-in-one-paste); the xAI API uses Public MCP above, and Grok Bot can too. See [Connect a bot](/configuration/bots) for each platform's setup and @@ -757,7 +762,8 @@ One MCP URL reaches every machine this one is linked to (see A conversation on another machine is named `@<label|environment-id>/<name>`; pass that name to `read_conversation`, `send_message`, the `answer_*` tools, and `schedule_message`, `schedule_recurring`, `list_scheduled`, `update_scheduled` and `delete_scheduled`. -- `start_conversation` and `start_worker` take `machine`: omit it for this machine, give a +- `start_conversation`, `start_worker` and `start_issue` take `machine`, and so do the + agent tools `delegate_task` and `lane_start`: omit it for this machine, give a linked machine's label or environment id, or `auto` to place the work by load. With `auto`, `needs` (a list of capability tags such as `docker`) limits the choice. @@ -782,3 +788,13 @@ agents `remote: true`. The linked machine must run a version with the schedule scopes (PAN-4939); an older one answers `403 insufficient_scope` for recurring schedules. + +## Get help + +A tool the token's scopes hide answers `Unknown tool <name>`. A tool the token's scopes +do not cover answers `HTTP 403: insufficient_scope (missingScope: ...)`. A launch that +could not get the `overdeck` server logs `[agent-injection] overdeck MCP skipped for +<id>: <reason>`. + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From df8e45693a72c58b5ed0b23e6352c1a900803494 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:59:29 -0500 Subject: [PATCH 35/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 6d291e1e724..2cae313a1b3 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:56:58.778Z", + "updated": "2026-11-19T03:59:29.326Z", "gitState": {}, "decisions": [], "hazards": [], @@ -246,9 +246,30 @@ "doneAt": "2026-11-19T03:56:51.523Z" }, "mcp-bottom": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T03:56:58.778Z" + "claimedAt": "2026-11-19T03:56:58.778Z", + "doneAt": "2026-11-19T03:59:29.325Z" + }, + "mcp-bottom.ac1": { + "status": "completed", + "doneAt": "2026-11-19T03:59:29.325Z" + }, + "mcp-bottom.ac2": { + "status": "completed", + "doneAt": "2026-11-19T03:59:29.325Z" + }, + "mcp-bottom.ac3": { + "status": "completed", + "doneAt": "2026-11-19T03:59:29.325Z" + }, + "mcp-bottom.ac4": { + "status": "completed", + "doneAt": "2026-11-19T03:59:29.325Z" + }, + "mcp-bottom.ac5": { + "status": "completed", + "doneAt": "2026-11-19T03:59:29.325Z" } } } From ab30f2abbde8efd7d8d90749d7a9bb7c173ba96c Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:59:36 -0500 Subject: [PATCH 36/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 2cae313a1b3..f0247825e01 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:59:29.326Z", + "updated": "2026-11-19T03:59:36.428Z", "gitState": {}, "decisions": [], "hazards": [], @@ -270,6 +270,11 @@ "mcp-bottom.ac5": { "status": "completed", "doneAt": "2026-11-19T03:59:29.325Z" + }, + "audit-cli-mcp": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T03:59:36.428Z" } } } From 7a88d26a8f963318d40822f89f5ac30bfa31e4d2 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:00:45 -0500 Subject: [PATCH 37/80] docs(cli/mcp): fix refusal kinds, URL variables, Hermes key, relay advice Applies Appendix H rows 1-7 and every [ADD] Missing bullet to cli/mcp.mdx: broadens the non-token refusal to every non-API-token kind; the URL env vars now also cover connect, not just login; the Hermes allowlist key gets its full plugins.entries path; the OpenClaw note names its actual tools; and no-webrtc-egress advice covers the relay-down case with its doc link. Retitles per D4, adds the oauth generic-error sentence, and appends ## Get help per D3. Item: audit-cli-mcp Item: audit-cli-mcp.ac1 Item: audit-cli-mcp.ac2 Item: audit-cli-mcp.ac3 Item: audit-cli-mcp.ac4 PR-note: cli/mcp.mdx: fixed refusal/URL vars/Hermes/relay advice (Appendix H) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- cli/mcp.mdx | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/cli/mcp.mdx b/cli/mcp.mdx index c7f5472d3ea..9f7ae5fe5a6 100644 --- a/cli/mcp.mdx +++ b/cli/mcp.mdx @@ -1,5 +1,6 @@ --- -title: pan mcp +title: "pan mcp: serve MCP, manage OAuth sign-ins and run the connector" +sidebarTitle: pan mcp description: Serve Overdeck's MCP tools over stdio, manage OAuth sign-ins, and run the Overdeck connector for a bot --- @@ -38,7 +39,7 @@ It exits 1 and prints one of these lines when it refuses to start: | The file is empty | `OVERDECK_MCP_TOKEN_FILE is empty: <path>` | | The file cannot be opened | `OVERDECK_MCP_TOKEN_FILE could not be read: <error>` | | The token is unknown or revoked | `OVERDECK_MCP_TOKEN is refused: the token is unknown or revoked. Create a token with: pan token create mcp --scopes read:state,read:conversations,operate` | -| The token is a paired device credential | `OVERDECK_MCP_TOKEN is refused: a paired device credential cannot drive MCP.` | +| The token is not an API token (a paired device, linked machine, phone or connector credential) | `OVERDECK_MCP_TOKEN is refused: a paired device credential cannot drive MCP.` | | The token carries `admin` | `OVERDECK_MCP_TOKEN is refused: MCP tokens cannot carry admin. Create a token with: pan token create mcp --scopes read:state,read:conversations,operate` | Create the token with [`pan token create`](/cli/token#create). A client configured in the @@ -60,7 +61,8 @@ Claude Desktop style points at a token file, so the token never appears in the c Manage OAuth sign-ins to `/mcp`. Every subcommand calls the dashboard on this machine, so the dashboard must be running. When it is not, the command prints -`The dashboard is not running. Start it with pan up.` and exits 1. See +`The dashboard is not running. Start it with pan up.` and exits 1. An error answer other +than 404 prints the dashboard's error text and exits 1. See [Sign in with OAuth](/configuration/mcp#sign-in-with-oauth) for the browser flow. A sign-in has one of four access levels: @@ -178,8 +180,8 @@ exact version. | Variable | Effect | | --- | --- | | `OVERDECK_CONNECTOR_HOME` | The connector home. Default `~/.overdeck-connector`. | -| `OVERDECK_CONNECTOR_DIRECTORY_URL` | The overdeck.ai directory URL when `login` has no `--directory-url`. Default `https://connect.overdeck.ai`. | -| `OVERDECK_ACCOUNT_URL` | The overdeck.ai account service URL when `login` has no `--account-url`. Default `https://account.overdeck.ai`. | +| `OVERDECK_CONNECTOR_DIRECTORY_URL` | The overdeck.ai directory URL when `login` or `connect` has no `--directory-url`. Default `https://connect.overdeck.ai`. | +| `OVERDECK_ACCOUNT_URL` | The overdeck.ai account service URL when `login` or `connect` has no `--account-url`. Default `https://account.overdeck.ai`. | The connector home is mode 0700 and holds up to five files, each mode 0600: `account.json`, `identity.json`, `pairing.json`, `local-token`, and `pending-signin.json`, which exists only @@ -232,8 +234,8 @@ in the shape the bot's platform reads: | --- | --- | | `grok-bot` | The `mcpServers` block for the Grok Bot plugin's `mcp.json`. | | `grok-build` | A note that the Overdeck plugin's `scripts/run-mcp.sh` starts the connector on its own, then the generic stdio JSON for use without the plugin. | -| `hermes` | The `mcp_servers.overdeck` entry (`command`, `args`) for Hermes's `config.yaml`, then a reminder to run `/reload-mcp` and that the Overdeck Hermes plugin needs `mcp_allowlist: ["overdeck"]`. | -| `openclaw` | The command `openclaw mcp set overdeck '<json>'`, which OpenClaw applies without a restart, then a note that the Overdeck OpenClaw plugin's summary and chat tools still need the connector's HTTP route. | +| `hermes` | The `mcp_servers.overdeck` entry (`command`, `args`) for Hermes's `config.yaml`, then a reminder to run `/reload-mcp` and that the Overdeck Hermes plugin needs `plugins.entries.overdeck.mcp_allowlist: ["overdeck"]` in the same file. | +| `openclaw` | The command `openclaw mcp set overdeck '<json>'`, which OpenClaw applies without a restart, then a note that the Overdeck OpenClaw plugin's summary and its `overdeck_pending` and `overdeck_answer` tools still need the connector's HTTP route (`serve` and its local token). | | `other` | The generic stdio JSON `{ "command": "npx", "args": [...] }`. | The last line of stdout is always one status line: `OVERDECK_CONNECT ` and then one line of @@ -274,7 +276,7 @@ the same command again. | `machine-not-in-account` | error | You signed in with an account that does not own this machine. Log out and rerun, and ask the user to authorize with the account their Overdeck uses. | | `machine-offline` | retry | The machine is offline. Ask the user to start Overdeck there, then run the same command again. | | `relay-plan-needed` | error | This network blocks direct connections and the account has no relay plan. Tell the user. | -| `no-webrtc-egress` | error | This computer got no TURN relay connection, usually because it cannot reach TLS 443 or send UDP; running again will not help then. Tell the user to run `pan doctor` on their machine: if its TURN relay row is ok, use Public MCP or a host with WebRTC egress. | +| `no-webrtc-egress` | error | This computer got no TURN relay connection, usually because it cannot reach TLS on turn.cloudflare.com:443 or send UDP; running again will not help then. Tell the user to run `pan doctor` on their machine: if its TURN relay row is ok, use Public MCP or a host with WebRTC egress; if that row warns too, the relay is down, so run the command again once it passes. See [no-webrtc-egress](/configuration/bots#no-webrtc-egress). | | `machine-unreachable` | retry | The machine could not be reached. Run the same command again in a minute. | | `pairing-code-refused` | error | The pairing code expired, was cancelled or was already used. Copy again. | | `key-mismatch` | error | The machine's key does not match the message. Copy again. | @@ -346,3 +348,8 @@ pan mcp connector logout Remove this connector from its machine and overdeck.ai, then delete its files, including a waiting `pending-signin.json`. + +## Get help + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From 0b3cf0868b554af1cf812a33104355a7fd6d4fe0 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:01:09 -0500 Subject: [PATCH 38/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index f0247825e01..7c6bebe7678 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T03:59:36.428Z", + "updated": "2026-11-19T04:01:09.391Z", "gitState": {}, "decisions": [], "hazards": [], @@ -272,9 +272,26 @@ "doneAt": "2026-11-19T03:59:29.325Z" }, "audit-cli-mcp": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T03:59:36.428Z" + "claimedAt": "2026-11-19T03:59:36.428Z", + "doneAt": "2026-11-19T04:01:09.390Z" + }, + "audit-cli-mcp.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:01:09.390Z" + }, + "audit-cli-mcp.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:01:09.390Z" + }, + "audit-cli-mcp.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:01:09.390Z" + }, + "audit-cli-mcp.ac4": { + "status": "completed", + "doneAt": "2026-11-19T04:01:09.390Z" } } } From 5c8b1c4f550d09dab7eeb7fed99a8a8e7371ad63 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:01:16 -0500 Subject: [PATCH 39/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 7c6bebe7678..514fa269c43 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:01:09.391Z", + "updated": "2026-11-19T04:01:16.415Z", "gitState": {}, "decisions": [], "hazards": [], @@ -292,6 +292,11 @@ "audit-cli-mcp.ac4": { "status": "completed", "doneAt": "2026-11-19T04:01:09.390Z" + }, + "audit-token": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:01:16.414Z" } } } From 54b8bf700bc805725e2eaeb1e8d229e749431d18 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:02:02 -0500 Subject: [PATCH 40/80] docs(cli/token): fix list scope, revoke refusal and internal name Applies Appendix I rows 1-3 and the [ADD] Missing bullet to cli/token.mdx: list now says it covers only API tokens, not paired devices, machines, phones or connectors; revoke documents the not-started-by-pan-up refusal and generic failure; and the internal function name pruneEndedAccessTokens is dropped from user docs. Retitles per D4 and adds Get help per D3. Item: audit-token Item: audit-token.ac1 Item: audit-token.ac2 Item: audit-token.ac3 PR-note: cli/token.mdx: fixed list scope and revoke refusal (Appendix I) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- cli/token.mdx | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/cli/token.mdx b/cli/token.mdx index 9a7e13cfc2b..668ed4b3f24 100644 --- a/cli/token.mdx +++ b/cli/token.mdx @@ -1,5 +1,6 @@ --- -title: pan token +title: "pan token: create, list and revoke scoped API tokens" +sidebarTitle: pan token description: "Create, list or revoke scoped API tokens for programs such as event sidecars and notifiers, instead of giving them a full device session." --- @@ -32,8 +33,9 @@ Works without a running dashboard; it writes the registry directly. pan token list [--json] ``` -Lists access tokens with columns `ID NAME SCOPES CREATED LAST USED REVOKED`. Works without a -running dashboard. +Lists API tokens (your own, agent and OAuth tokens) with columns +`ID NAME SCOPES CREATED LAST USED REVOKED`. Paired devices, linked machines, phones and +connectors are not listed. Works without a running dashboard. | Flag | Effect | | --- | --- | @@ -55,8 +57,7 @@ prints every field, including `agentId`, `agentKind` and `role` for an agent token and `oauthClientId`, `oauthFamilyId` and `expiresAt` for an OAuth token. An agent token leaves the list 7 days after it is revoked, and an expired OAuth token 7 days after it expires. A revoked OAuth token stays 90 days longer, so a -later refresh with its old refresh token still sees the revocation -(`pruneEndedAccessTokens`, `src/lib/access-tokens.ts`). +later refresh with its old refresh token still sees the revocation. ## revoke @@ -76,4 +77,12 @@ With no dashboard running it writes the registry and prints: Dashboard not running; revoked in the registry. No live connections were open. ``` -An unknown id prints `No access token with id <id>.` and exits 1. +An unknown id prints `No access token with id <id>.` and exits 1. A dashboard that was +not started by `pan up` (for example `pan serve`) rejects this machine's internal token; +the command then says `pan token revoke` needs a dashboard started by `pan up` and exits +1. Any other refusal prints `pan token revoke failed: <reason>` and exits 1. + +## Get help + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From 4296664d0e15f1ada84e5ab5514b89b48a56a61f Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:02:30 -0500 Subject: [PATCH 41/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 514fa269c43..d8521b8b4c6 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:01:16.415Z", + "updated": "2026-11-19T04:02:29.978Z", "gitState": {}, "decisions": [], "hazards": [], @@ -294,9 +294,22 @@ "doneAt": "2026-11-19T04:01:09.390Z" }, "audit-token": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:01:16.414Z" + "claimedAt": "2026-11-19T04:01:16.414Z", + "doneAt": "2026-11-19T04:02:29.977Z" + }, + "audit-token.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:02:29.977Z" + }, + "audit-token.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:02:29.977Z" + }, + "audit-token.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:02:29.977Z" } } } From c157702e7975aa5b83f7e5fa1d043e61f3853bad Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:02:37 -0500 Subject: [PATCH 42/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index d8521b8b4c6..18e44563df6 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:02:29.978Z", + "updated": "2026-11-19T04:02:36.968Z", "gitState": {}, "decisions": [], "hazards": [], @@ -310,6 +310,11 @@ "audit-token.ac3": { "status": "completed", "doneAt": "2026-11-19T04:02:29.977Z" + }, + "audit-session-vault": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:02:36.968Z" } } } From 151e7b7c4e55d89cd996859343b44fd8f21a1af1 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:04:38 -0500 Subject: [PATCH 43/80] docs(session-vault): remove stale release notes, limit harness claims Applies Appendix J rows 1-13 and every [ADD] Missing bullet to configuration/session-vault.mdx: dashboard setup/join/unlock is no longer "planned"; drops four stale "next release (v0.65.0)" notes that already shipped; save and resume now say Claude Code and Codex only, not every transcript or harness; the invented exclude --path flag is corrected; rotate-key's passphrase flags note they turn unlock on; Where things live gets debounceSec, wipMaxBytes and three missing paths; and a Get help section covers the vault-off, key-missing and key-mismatch messages. Retitles per D4. Keeps ## Save and sync. Item: audit-session-vault Item: audit-session-vault.ac1 Item: audit-session-vault.ac2 Item: audit-session-vault.ac3 Item: audit-session-vault.ac4 Item: audit-session-vault.ac5 PR-note: session-vault.mdx: removed stale notes, limited harness claims (Appendix J) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- configuration/session-vault.mdx | 58 +++++++++++++++++++++------------ 1 file changed, 38 insertions(+), 20 deletions(-) diff --git a/configuration/session-vault.mdx b/configuration/session-vault.mdx index 317f6da9356..0f9d8654df1 100644 --- a/configuration/session-vault.mdx +++ b/configuration/session-vault.mdx @@ -1,5 +1,6 @@ --- -title: Session Vault +title: "Session Vault: encrypted conversation backup and cross-machine resume" +sidebarTitle: Session Vault description: Encrypted off-machine storage and cross-machine resume for agent conversations --- @@ -11,8 +12,8 @@ contents: everything is encrypted on your machine with a key only you hold, and `pan vault` commands send no telemetry. It also works without the dashboard: `npm install -g @overdeck/core`, then `pan vault` on any -machine. Setting up, joining and unlocking the vault happen in a terminal. Doing them from -the dashboard is planned: [PAN-4446](https://github.com/eltmon/overdeck/issues/4446). +machine. Setting up, joining and unlocking the vault also work from the dashboard; see +[From the dashboard](#from-the-dashboard). ## Set up the first machine @@ -122,8 +123,8 @@ opens the vault. | Flag | Effect | | --- | --- | | `--yes` | Rotate without the confirmation prompt. Required when the command does not run in a terminal. | -| `--passphrase-file <path>` | Keep passphrase unlock, with the passphrase in this file, for the new key. | -| `--generate-passphrase` | Keep passphrase unlock with a generated 6-word passphrase, printed once. | +| `--passphrase-file <path>` | Use passphrase unlock for the new key, with the passphrase in this file. This also turns passphrase unlock on if it was off. | +| `--generate-passphrase` | Use passphrase unlock for the new key with a generated 6-word passphrase, printed once. This also turns passphrase unlock on if it was off. | | `--no-passphrase` | Turn passphrase unlock off. | If the vault has a passphrase, the command asks for a new one in a terminal (Enter generates @@ -157,7 +158,7 @@ Run the command again: it finishes with the same new key and prints the phrase. ## Save and sync ```bash -pan vault save --all # every transcript on this machine +pan vault save --all # every Claude Code and Codex transcript on this machine pan vault save <session-id> # one conversation pan vault sync # push what grew, pull what others saved pan vault status # backend, this machine, last sync, machines @@ -167,23 +168,25 @@ If a new line contains something that looks like a credential, the save is block output names the line number and pattern, never the value. Rotate the secret if it is real, then run `pan vault allow-secret <id> <line>` or `pan vault exclude --session <id>`. -With the dashboard running, conversations started from it are saved automatically 30 seconds -after they go quiet, and synced every 5 minutes; no hook is needed. This arrives in the next -release (v0.65.0). +With the dashboard running, Claude Code and Codex conversations started from it are saved +automatically 30 seconds after they go quiet, and synced every 5 minutes; no hook is needed. -The dashboard also saves pipeline agents automatically — work, review, test, planning and the -other Overdeck agents running Claude Code or Codex — while they run and for up to 30 minutes +The dashboard also saves pipeline agents automatically (work, review, test, planning and the +other Overdeck agents running Claude Code or Codex) while they run and for up to 30 minutes after they stop. Each saved agent is titled `<issue> <role> agent (<agent id>)`, so another machine shows, for example, "PAN-4630 work agent (agent-pan-4630)" as a read-only "from `<machine>`" copy after its next sync. Agents that stopped earlier are not saved automatically: `pan vault save --all` saves older Claude Code transcripts, and older Codex agent transcripts -are not covered. Run `pan vault exclude --path <workspace>` to opt a project's agents out. +are not covered. Run `pan vault exclude <workspace path>` to opt a project's agents out. To sync right away, click **Sync now** in Settings → Session Vault. The button appears only in the primary dashboard, which runs the sync loop; the section then shows the new last-sync time. Change the interval with `syncIntervalSec` in `~/.overdeck/vault/config.json` (see [Where things live](#where-things-live)). +The dashboard's automatic code snapshot is throttled: it captures code at most once every 5 +minutes. `pan vault save` and **Hand off now** always capture. + ## Continue on another machine ```bash @@ -196,10 +199,10 @@ pan vault resume <id>@3 # fork at version 3 instead `resume` compares the target directory's git state with the state saved with the conversation. If the branch, commit or dirty state differs, it asks whether to continue, continue with a short note as the first message, or cancel. Use `--on-drift continue|note|cancel` -in scripts and `--no-launch` to print the command instead of running it. +in scripts and `--no-launch` to print the command instead of running it. In a script with +drift and no `--on-drift`, it cancels by default. -Claude Code and Codex resume natively. Other harnesses receive a markdown digest of the -conversation in the target directory to paste into a new session. +Claude Code and Codex resume natively. Session Vault saves only these two harnesses. With the dashboard running, Claude Code and Codex conversations saved on your other machines also appear in the conversation list, marked "from `<machine>`". You can read them there. They @@ -207,7 +210,7 @@ are read-only copies: to continue one on this machine, click **Continue here** i (or run the `pan vault resume <id>` command it shows). If this machine has no checkout of the project, the dialog offers to clone and register it first. If another machine continued the conversation in the meantime, the dialog says `Already continued on <machine>.` and changes -nothing. Browse rows and **Continue here** arrive in the next release (v0.65.0). See +nothing. See [Conversations](/features/conversations#conversations-from-your-other-machines). Back on the first machine, the dashboard then marks that conversation "continued on @@ -260,7 +263,9 @@ checkout must be clean: with uncommitted changes it offers a fresh worktree at a otherwise stops and asks for `--worktree <dir>`. Nothing in the dirty checkout is touched. **Continue here** in the dashboard follows the same rule: a clean checkout gets the snapshot -in place, and a checkout with uncommitted changes gets a new workspace for it instead. +in place, and a checkout with uncommitted changes gets a new workspace for it instead. If +that dirty checkout is not a registered project, the dialog cannot make a workspace and +shows the `pan vault resume <id> --worktree <dir>` command instead. A snapshot larger than 50 MB (`wipMaxBytes` in the vault config) is skipped, and `resume` says so. If the uncommitted code contains something that looks like a credential, the @@ -292,8 +297,7 @@ anything on its own. To use it: list without deleting anything. With the dashboard running, open Settings → Session Vault, review the list, and click "Yes, -delete these". Entries marked failed are never deleted. This panel arrives in the next -release (v0.65.0). +delete these". Entries marked failed are never deleted. ## Windows @@ -328,9 +332,23 @@ dual-booting the same machine were not verified. | --- | --- | | `~/.overdeck/vault/key` | Your vault key (mode 0600). Back it up as the recovery phrase. | | `~/.overdeck/vault/key.next` | Present only while a key rotation is in progress. Finish it with `pan vault rotate-key`. | -| `~/.overdeck/vault/config.json` | Backend URL, exclusions, `evict`, `liveQuietMinutes`, `syncIntervalSec` (seconds between dashboard syncs). | +| `~/.overdeck/vault/config.json` | Backend URL, exclusions, `evict`, `liveQuietMinutes` (minutes a transcript must be quiet before eviction, default 30), `syncIntervalSec` (seconds between dashboard syncs, default 300), `debounceSec` (seconds of quiet before the dashboard saves, default 30) and `wipMaxBytes` (largest code snapshot, default 50 MB). | | `~/.overdeck/vault/git/` | Local clone of your vault remote. | | `~/.overdeck/vault/index.json` | This machine's saved-transcript index and list cache. Never uploaded. | +| `~/.overdeck/vault/allowed-secrets.json` | Lines allowed past the secret scan. | +| `~/.overdeck/vault/eviction-batch.json` | The reviewed list from the last `pan vault evict`, pending confirmation. | +| `~/.overdeck/vault/browse/` | Cached copies of other machines' conversations. | The developer reference, including the wire format and the module map, is [docs/SESSION-VAULT.md](https://github.com/eltmon/overdeck/blob/main/docs/SESSION-VAULT.md). + +## Get help + +`Session Vault is off. Run: pan vault setup <git-url>` means no vault is configured yet. +`Session Vault backend is set to <backend> but the key file is missing. Run: pan vault join +<backend>` means this machine never joined, or lost its key file. A key-mismatch message +means the backend's vault key does not match this machine's: re-join with the current +recovery phrase or passphrase. + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From 1e981fa24622bc745f1993da8b90688c1af2e63d Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:05:04 -0500 Subject: [PATCH 44/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 18e44563df6..d8ee549ebcb 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:02:36.968Z", + "updated": "2026-11-19T04:05:04.007Z", "gitState": {}, "decisions": [], "hazards": [], @@ -312,9 +312,30 @@ "doneAt": "2026-11-19T04:02:29.977Z" }, "audit-session-vault": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:02:36.968Z" + "claimedAt": "2026-11-19T04:02:36.968Z", + "doneAt": "2026-11-19T04:05:04.006Z" + }, + "audit-session-vault.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:05:04.006Z" + }, + "audit-session-vault.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:05:04.006Z" + }, + "audit-session-vault.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:05:04.006Z" + }, + "audit-session-vault.ac4": { + "status": "completed", + "doneAt": "2026-11-19T04:05:04.006Z" + }, + "audit-session-vault.ac5": { + "status": "completed", + "doneAt": "2026-11-19T04:05:04.006Z" } } } From 6029c1015895bdd74ca5c681bd2c41922ee1f581 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:05:11 -0500 Subject: [PATCH 45/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index d8ee549ebcb..07d66259438 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:05:04.007Z", + "updated": "2026-11-19T04:05:11.378Z", "gitState": {}, "decisions": [], "hazards": [], @@ -336,6 +336,11 @@ "audit-session-vault.ac5": { "status": "completed", "doneAt": "2026-11-19T04:05:04.006Z" + }, + "audit-vault": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:05:11.377Z" } } } From 823e44d248ab2e3e763becbe0897a4fdb88998db Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:06:22 -0500 Subject: [PATCH 46/80] docs(cli/vault): describe shipped dashboard features, fix save/exclude/status Applies Appendix K rows 1-6 and every [ADD] Missing bullet to cli/vault.mdx: the dashboard section drops the stale "next release" and PAN-4446 planned note and describes Session Vault setup/join/ unlock, Sync now, Continue on another device and Continue here as shipped; save/--harness now say Claude Code or Codex only; exclude clarifies that only --session makes a tombstone; status documents key-rotation date, listed records and eviction state; and the passphrase flag combinations on setup, join and rotate-key are noted. Retitles per D4 and adds Get help per D3. Item: audit-vault Item: audit-vault.ac1 Item: audit-vault.ac2 Item: audit-vault.ac3 Item: audit-vault.ac4 PR-note: cli/vault.mdx: described dashboard features, fixed save/exclude/status (Appendix K) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- cli/vault.mdx | 41 ++++++++++++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 11 deletions(-) diff --git a/cli/vault.mdx b/cli/vault.mdx index fdb7b04c830..f646bc16a69 100644 --- a/cli/vault.mdx +++ b/cli/vault.mdx @@ -1,5 +1,6 @@ --- -title: pan vault +title: "pan vault: back up and resume agent conversations across machines" +sidebarTitle: pan vault description: "Session Vault commands: encrypted off-machine storage and cross-machine resume for agent conversations" --- @@ -27,6 +28,8 @@ may also be `dir:<path>` for a local directory or NAS mount. | `--generate-passphrase` | Also enable passphrase unlock with a generated 6-word passphrase, printed once. | | `--no-passphrase` | Do not offer passphrase unlock. | +`--passphrase-file` and `--generate-passphrase` cannot be combined. + ## join ```bash @@ -41,6 +44,8 @@ phrase. | `--phrase-file <path>` | Read the 24-word recovery phrase from a file instead of prompting. | | `--passphrase-file <path>` | Read the vault passphrase from a file instead of prompting. | +`--phrase-file` and `--passphrase-file` cannot be combined. + ## passphrase set ```bash @@ -74,17 +79,20 @@ chunks readable, print a new recovery phrase. | Flag | Effect | | --- | --- | | `--yes` | Rotate without the confirmation prompt. | -| `--passphrase-file <path>` | Re-wrap passphrase unlock under the new key with the passphrase in this file. | -| `--generate-passphrase` | Re-wrap passphrase unlock under the new key with a generated 6-word passphrase, printed once. | +| `--passphrase-file <path>` | Re-wrap passphrase unlock under the new key with the passphrase in this file. Also turns passphrase unlock on if it was off. | +| `--generate-passphrase` | Re-wrap passphrase unlock under the new key with a generated 6-word passphrase, printed once. Also turns passphrase unlock on if it was off. | | `--no-passphrase` | Turn passphrase unlock off. | +Only one of `--passphrase-file`, `--generate-passphrase` and `--no-passphrase` may be given. + ## status ```bash pan vault status ``` -Show backend, this machine, owned records, last sync and the machine list. +Show the backend, when the key was last rotated, this machine, owned and listed records, +last sync, whether eviction is on, and the machine list. | Flag | Effect | | --- | --- | @@ -100,9 +108,9 @@ Settle one transcript (by session id or path) or many into the vault. | Flag | Effect | | --- | --- | -| `--all` | Settle every discovered transcript. | +| `--all` | Save every Claude Code transcript under `~/.claude/projects` and every Codex transcript under `~/.codex/sessions`. | | `--since <date>` | With `--all`: only transcripts modified on or after this date. | -| `--harness <harness>` | With `--all`: only this harness (`claude-code`, `codex`, ...). | +| `--harness <harness>` | With `--all`: only this harness, `claude-code` or `codex`. | | `--hook` | Claude Code Stop-hook mode: read `{session_id, transcript_path}` JSON from stdin, print nothing, exit 0. | ## sync @@ -162,8 +170,9 @@ forks at that version instead of the latest. pan vault exclude [path] ``` -Exclude conversations by cwd path, git origin or session id. An excluded saved record -becomes a tombstone. +Exclude conversations by cwd path, git origin or session id. With `--session`, the +conversation's saved record becomes a tombstone; a path or origin exclusion stops future +saves only. | Flag | Effect | | --- | --- | @@ -227,6 +236,16 @@ Rebuild an evicted transcript byte for byte at its original path. ## In the dashboard -Settings → Session Vault and **Continue here** are in the next release (v0.65.0). Setting -up, joining and unlocking the vault from the dashboard is planned: -[PAN-4446](https://github.com/eltmon/overdeck/issues/4446). +Settings → Session Vault sets up, joins and unlocks a vault, runs **Sync now**, lists the +machines and reviews transcripts waiting for deletion. A conversation's ⋮ menu has +**Continue on another device**, and a read-only copy from another machine has +**Continue here**. See [Session Vault](/configuration/session-vault#from-the-dashboard). + +## Get help + +`Session Vault is off. Run: pan vault setup <git-url>` means no vault is configured yet. +`Session Vault backend is set to <backend> but the key file is missing. Run: pan vault join +<backend>` means this machine never joined, or lost its key file. + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From ff8a5da8090a3be77a4a7ff8b8386633ac014d88 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:06:48 -0500 Subject: [PATCH 47/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 07d66259438..33cd717bc0a 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:05:11.378Z", + "updated": "2026-11-19T04:06:48.039Z", "gitState": {}, "decisions": [], "hazards": [], @@ -338,9 +338,26 @@ "doneAt": "2026-11-19T04:05:04.006Z" }, "audit-vault": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:05:11.377Z" + "claimedAt": "2026-11-19T04:05:11.377Z", + "doneAt": "2026-11-19T04:06:48.038Z" + }, + "audit-vault.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:06:48.038Z" + }, + "audit-vault.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:06:48.038Z" + }, + "audit-vault.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:06:48.038Z" + }, + "audit-vault.ac4": { + "status": "completed", + "doneAt": "2026-11-19T04:06:48.038Z" } } } From 975738128b532cc6aea15f83cfc42864369c7ea6 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:06:55 -0500 Subject: [PATCH 48/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 33cd717bc0a..f1c962a2e7b 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:06:48.039Z", + "updated": "2026-11-19T04:06:54.994Z", "gitState": {}, "decisions": [], "hazards": [], @@ -358,6 +358,11 @@ "audit-vault.ac4": { "status": "completed", "doneAt": "2026-11-19T04:06:48.038Z" + }, + "audit-tailscale": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:06:54.994Z" } } } From 2315fb4d2a2fe75d1645d1b1fbcc0034f51803eb Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:07:54 -0500 Subject: [PATCH 49/80] docs(tailscale): fix setup steps, stored state and machine-link note Applies Appendix L rows 1-8 and every [ADD] Missing bullet to configuration/tailscale.mdx: the Ready step no longer claims to list peers itself; Sign in names the real Sign in / Open sign-in buttons; the operator retry step names Try signing in again; Windows setup is corrected to a manual winget/download flow; the stale PAN-4645 "arrives with machine links" note is replaced with the shipped Link a machine flow; "stores nothing about Tailscale" is corrected to name the two things it does save; adds the not-tested-on-a-real-machine Note and the command palette entry; and adds a Get help section. Retitles per D4. Item: audit-tailscale Item: audit-tailscale.ac1 Item: audit-tailscale.ac2 Item: audit-tailscale.ac3 Item: audit-tailscale.ac4 Item: audit-tailscale.ac5 PR-note: tailscale.mdx: fixed setup steps, stored state, machine-link note (Appendix L) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- configuration/tailscale.mdx | 45 +++++++++++++++++++++++++------------ 1 file changed, 31 insertions(+), 14 deletions(-) diff --git a/configuration/tailscale.mdx b/configuration/tailscale.mdx index b40cc770fed..1945f3531d6 100644 --- a/configuration/tailscale.mdx +++ b/configuration/tailscale.mdx @@ -1,5 +1,6 @@ --- -title: Tailscale +title: "Tailscale: reach your dashboard over HTTPS from your devices" +sidebarTitle: Tailscale description: Install Tailscale, sign in, turn on protected HTTPS access to the dashboard, and find other Overdeck machines on your tailnet --- @@ -11,14 +12,19 @@ private network (a **tailnet**), gives each machine a name such as `desk.tailnet-1234.ts.net` (its **MagicDNS name**), and can serve the dashboard over HTTPS at that name with **Tailscale Serve**. -Overdeck sets this up for you in **Settings → Anywhere → Set up Tailscale**, or -in a terminal with [`pan tailscale setup`](/cli/tailscale). Both walk the same -steps. **Set up Tailscale** appears only in a browser on this machine (the root +Overdeck sets this up for you in **Settings → Anywhere → Set up Tailscale**, also in the +command palette, or in a terminal with [`pan tailscale setup`](/cli/tailscale). Both walk +the same steps. **Set up Tailscale** appears only in a browser on this machine (the root session); a paired device cannot change Tailscale settings. -Overdeck stores nothing about Tailscale. Every step reads the live state from -the `tailscale` command, so you can also make any change by hand and Overdeck -picks it up. +Overdeck keeps no copy of Tailscale's state. The only things setup saves are +**Require a token to sign in** and the trusted address `https://<MagicDNS name>`. Every +step reads the live state from the `tailscale` command, so you can also make any change by +hand and Overdeck picks it up. + +<Note>Set up Tailscale is new. Its guided steps were not run end to end on a real machine +before release. If a step does not work for you, report it on +[GitHub Issues](https://github.com/eltmon/overdeck/issues).</Note> ## What Set up Tailscale does @@ -29,18 +35,20 @@ Setup reads Tailscale's state and shows the first step that is not done yet: | Install | No `tailscale` command is found. | Runs the installer for your platform (see [Per platform](#per-platform)). | | Start the daemon | The `tailscale` command cannot reach `tailscaled`. | Linux: runs `sudo systemctl enable --now tailscaled` in a terminal. macOS: asks you to open the Tailscale app. | | Operator | Linux, Tailscale installed as root, and this user is not the Tailscale operator. | Runs `sudo tailscale set --operator=<you>` in a terminal, so Overdeck can sign in and turn on Serve without `sudo`. | -| Sign in | Tailscale is signed out or stopped. | Starts sign-in and shows **Open sign-in**. The step finishes when Tailscale reports `Running`. | +| Sign in | Tailscale is not signed in and running. | In the dashboard, click **Sign in**, then **Open sign-in**. `pan tailscale setup` prints the sign-in link. The step finishes when Tailscale reports `Running`. | | Turn on HTTPS | MagicDNS or HTTPS certificates are off for the tailnet. | Links to [the tailnet DNS settings](https://login.tailscale.com/admin/dns). | | Turn on HTTPS access | Serve does not yet send `https://<MagicDNS name>` to this dashboard. | Turns on protected Serve HTTPS (see [Serve HTTPS and token sign-in](#serve-https-and-token-sign-in)). | | Protect the dashboard | Serve already sends visitors here, but a token is not required to sign in. | Turns on token sign-in without changing Serve. | -| Ready | Everything above is done. | Shows the Serve address, the phone app QR code and the other Overdeck machines on the tailnet. | +| Ready | Everything above is done. | Shows the Serve address and the phone app QR code. Settings → Anywhere then lists the other Overdeck machines on the tailnet (see [Discovering other machines](#discovering-other-machines)). | Any command that may need an administrator password runs in a terminal inside the dialog (or in your own terminal for `pan tailscale setup`). You type the password there. Overdeck never asks for it, sees it or stores it. If the sign-in attempt says access is denied, this user is not the Tailscale -operator. Setup then shows the operator step and tries sign-in again once. +operator. The dashboard then shows the operator step with a **Try signing in again** +button; `pan tailscale setup` runs the operator command and retries sign-in once by +itself. ## Per platform @@ -52,7 +60,7 @@ operator. Setup then shows the operator step and tries sign-in again once. | macOS | Homebrew is installed | `brew install --cask tailscale-app && open -a Tailscale` in a terminal. | | macOS | No Homebrew | Download and open the [Tailscale package](https://pkgs.tailscale.com/stable/#macos), open Tailscale, allow its VPN configuration, then press **Check again**. | | WSL2 | Always | Install Tailscale on Windows (not inside WSL) from the [Windows download page](https://tailscale.com/download/windows). Then run `tailscale serve --bg --https=443 http://127.0.0.1:<port>` in Windows PowerShell, where `<port>` is the dashboard port. | -| Windows | Always | `winget install tailscale.tailscale`, or the [Windows download page](https://tailscale.com/download/windows). | +| Windows | Always | Overdeck shows `winget install tailscale.tailscale` and the [Windows download page](https://tailscale.com/download/windows). You run the install, sign in, then press **Check again**. | If your user name contains characters that are unsafe in a shell command, Overdeck shows the Linux installer command and the operator step as text @@ -164,6 +172,15 @@ Overdeck identity. It shows each machine's label, host name, Overdeck version and address, and counts the other tailnet devices. The list loads when the page opens and on **Refresh**. `pan tailscale status` prints the same list. -Linking machines arrives with machine links -([PAN-4645](https://github.com/eltmon/overdeck/issues/4645)). Until then the -list has no **Link** action. +The list has no **Link** action. To link one of these machines, use **Link a machine** in +Settings → Anywhere or `pan machines link <pairing-url>`; see +[Linked machines](/configuration/linked-machines). + +## Get help + +Tailscale Serve may refuse to start with "Tailscale Serve already serves something else on +port 443" or "Update Tailscale to 1.52 or later." The self-check that confirms Serve is +working waits up to 15 seconds. + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From db2c6c8ebb17f344ae4df2114b2237a5504435fe Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:08:17 -0500 Subject: [PATCH 50/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index f1c962a2e7b..2a9717e1918 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:06:54.994Z", + "updated": "2026-11-19T04:08:17.731Z", "gitState": {}, "decisions": [], "hazards": [], @@ -360,9 +360,30 @@ "doneAt": "2026-11-19T04:06:48.038Z" }, "audit-tailscale": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:06:54.994Z" + "claimedAt": "2026-11-19T04:06:54.994Z", + "doneAt": "2026-11-19T04:08:17.731Z" + }, + "audit-tailscale.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:08:17.731Z" + }, + "audit-tailscale.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:08:17.731Z" + }, + "audit-tailscale.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:08:17.731Z" + }, + "audit-tailscale.ac4": { + "status": "completed", + "doneAt": "2026-11-19T04:08:17.731Z" + }, + "audit-tailscale.ac5": { + "status": "completed", + "doneAt": "2026-11-19T04:08:17.731Z" } } } From fda886f2e426ef0cb8000230f00c267c30f7d8f3 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:08:25 -0500 Subject: [PATCH 51/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 2a9717e1918..3fcee49aa0e 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:08:17.731Z", + "updated": "2026-11-19T04:08:25.303Z", "gitState": {}, "decisions": [], "hazards": [], @@ -384,6 +384,11 @@ "audit-tailscale.ac5": { "status": "completed", "doneAt": "2026-11-19T04:08:17.731Z" + }, + "audit-cli-tailscale": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:08:25.302Z" } } } From 202673ecfaff5df1b8d0e41a286d7bb1a01cb471 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:09:23 -0500 Subject: [PATCH 52/80] docs(cli/tailscale): fix status output, exit cases, add missing errors Applies Appendix M rows 1-3 and every [ADD] Missing bullet to cli/tailscale.mdx: the not-installed message is scoped to the non-JSON path; exit code 1 and the Errors list now cover the 8-step limit and the --userspace not-available message; adds the generic setup-stopped error; and removes the em dash from the sample status output. Retitles per D4 and appends the Discord help sentence to ## Errors per D3. Item: audit-cli-tailscale Item: audit-cli-tailscale.ac1 Item: audit-cli-tailscale.ac2 Item: audit-cli-tailscale.ac3 PR-note: cli/tailscale.mdx: fixed status/exit codes, added errors (Appendix M) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- cli/tailscale.mdx | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/cli/tailscale.mdx b/cli/tailscale.mdx index 80d6020a7c5..4357d368f9a 100644 --- a/cli/tailscale.mdx +++ b/cli/tailscale.mdx @@ -1,5 +1,6 @@ --- -title: pan tailscale +title: "pan tailscale: check and set up Tailscale access from the terminal" +sidebarTitle: pan tailscale description: Show Tailscale state and set up protected HTTPS access to this machine's dashboard --- @@ -38,14 +39,14 @@ Tailscale HTTPS certificates: on Serve: https://desk.tailnet-1234.ts.net Token sign-in: required - Next step: ready — New browsers must pair: run `pan pair --url https://desk.tailnet-1234.ts.net`. + Next step: ready: New browsers must pair: run `pan pair --url https://desk.tailnet-1234.ts.net`. Overdeck on your tailnet HOST LABEL VERSION URL laptop laptop 0.72.0 https://laptop.tailnet-1234.ts.net ``` -When Tailscale is not installed it prints +Without `--json`, when Tailscale is not installed it prints `` Tailscale is not installed. Run `pan tailscale setup`. `` and exits 0. `status` always exits 0; it only reads. @@ -87,7 +88,7 @@ userspace mode is off until it passes a live check (see | Code | Meaning | | --- | --- | | 0 | `status` printed, or `setup` reached ready. | -| 1 | `setup` stopped: a command failed, a step needs you (tailnet DNS settings, a manual install, opening the Tailscale app), a step did not move on after one retry, sign-in did not finish within 10 minutes, or the dashboard is not running. | +| 1 | `setup` stopped: a command failed, a step needs you (tailnet DNS settings, a manual install, opening the Tailscale app), a step did not move on after one retry, sign-in did not finish within 10 minutes, the dashboard is not running, or setup did not reach ready within 8 steps. | ## Errors @@ -98,3 +99,14 @@ userspace mode is off until it passes a live check (see `pan tailscale setup` needs a dashboard started by `pan up`. ``, exit 1. - A step that stays the same after its action and one retry: `Setup is still at "<step>".` with what to do, exit 1. +- Any other stop: `` Setup stopped at "<step>". Run `pan tailscale setup` again after fixing + it. ``, exit 1. +- Setup does not reach ready within 8 steps: + `` Setup did not finish within 8 steps. Run `pan tailscale status` to see where it + stands. ``, exit 1. +- `--userspace` in this release: + `` Installing Tailscale without an administrator password is not available yet. Run `pan + tailscale setup` without --userspace to use the installer. ``, exit 1. + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From 5389304776a9cd2cc5f7fe9306ffada22e7d731e Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:09:45 -0500 Subject: [PATCH 53/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 3fcee49aa0e..4b4cdf3fce5 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:08:25.303Z", + "updated": "2026-11-19T04:09:45.640Z", "gitState": {}, "decisions": [], "hazards": [], @@ -386,9 +386,22 @@ "doneAt": "2026-11-19T04:08:17.731Z" }, "audit-cli-tailscale": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:08:25.302Z" + "claimedAt": "2026-11-19T04:08:25.302Z", + "doneAt": "2026-11-19T04:09:45.640Z" + }, + "audit-cli-tailscale.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:09:45.640Z" + }, + "audit-cli-tailscale.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:09:45.640Z" + }, + "audit-cli-tailscale.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:09:45.640Z" } } } From 20bb76cff010ff4aee3c794f4b3e13a470ec3484 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:09:59 -0500 Subject: [PATCH 54/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 4b4cdf3fce5..601054ec0f9 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:09:45.640Z", + "updated": "2026-11-19T04:09:59.586Z", "gitState": {}, "decisions": [], "hazards": [], @@ -402,6 +402,11 @@ "audit-cli-tailscale.ac3": { "status": "completed", "doneAt": "2026-11-19T04:09:45.640Z" + }, + "audit-remote-access": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:09:59.586Z" } } } From 23e795eb862f856f3ad7a0f6a4a6f79b4c805225 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:12:17 -0500 Subject: [PATCH 55/80] docs(remote-access): remove stale notes and roadmap, fix descriptor and scopes Applies Appendix N rows 1-14 and every [ADD] Missing bullet to configuration/remote-access.mdx: drops the stale v0.65.0 Note and the 0.63.0 descriptor sample for a current one with machineKey and endpoints; the Anywhere status card gains Directory and Relay rows and drops the PAN-4446 planned notes; the scope table adds read:costs, read:settings and forward and corrects operate's scope; the account card documents the invite-only relay line and the real two-click sign-in; and the stale, all-closed "What comes next" section is replaced with Get help. Retitles per D4. Keeps every heading other pages link to. Item: audit-remote-access Item: audit-remote-access.ac1 Item: audit-remote-access.ac2 Item: audit-remote-access.ac3 Item: audit-remote-access.ac4 Item: audit-remote-access.ac5 PR-note: remote-access.mdx: removed stale notes/roadmap, fixed descriptor/scopes (Appendix N) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- configuration/remote-access.mdx | 90 ++++++++++++++++++--------------- 1 file changed, 49 insertions(+), 41 deletions(-) diff --git a/configuration/remote-access.mdx b/configuration/remote-access.mdx index 0130447d976..752163ed362 100644 --- a/configuration/remote-access.mdx +++ b/configuration/remote-access.mdx @@ -1,5 +1,6 @@ --- -title: Remote access +title: "Remote access: pair devices, scoped tokens and network exposure" +sidebarTitle: Remote access description: Pair another device with a machine's dashboard, revoke it, and keep the LAN out --- @@ -11,12 +12,6 @@ state. Another device (a laptop, a tablet, a second desktop) reaches a machine by **pairing** with it. Pairing gives that device its own revocable session. The machine's root internal token never leaves the machine. -<Note> -Pairing from the terminal (`pan pair`, `pan devices`) is in v0.64.0. Settings → Anywhere, -Settings → Access Tokens and scoped API tokens (`pan token`) arrive in the next release -(v0.65.0). -</Note> - Every machine has a stable public identity. `GET /api/environment` returns it without a credential: @@ -26,18 +21,23 @@ without a credential: "environmentId": "3f0c…", "label": "desk", "platform": { "os": "linux", "arch": "x64" }, - "serverVersion": "0.63.0", + "serverVersion": "0.89.1", "protocolVersion": 1, - "capabilities": { "pairing": true, "deviceSessions": true, "terminalAuth": true } + "capabilities": { "pairing": true, "deviceSessions": true, "terminalAuth": true, "machineLinks": true, "phoneApp": true, "connector": true }, + "machineKey": "<64 hex>", + "linkProtocol": 1, + "endpoints": [{ "kind": "tailnet", "url": "wss://desk.tailnet-1234.ts.net/ws/link" }] } ``` -The descriptor contains no paths, usernames or tokens. +The descriptor contains no paths, usernames or tokens. `machineKey` is this machine's +public key, and `endpoints` lists the LAN and Tailscale addresses that linked machines can +use. <Warning> -Do not expose a dashboard on a network until `GET /api/environment` reports -`capabilities.terminalAuth: true`. That value means every `/ws/*` connection -(terminals, RPC, voice) requires a credential. +Every `/ws/*` connection (terminals, RPC, voice) requires a credential, and +`GET /api/environment` reports this as `capabilities.terminalAuth: true`. A dashboard +older than v0.64.0 does not, so do not expose one on a network. </Warning> ## Reach this machine with Tailscale @@ -171,8 +171,13 @@ export OVERDECK_TRUSTED_ORIGINS=https://desk.tailnet.ts.net pan up ``` -A later release discovers and advertises endpoints automatically -([PAN-4403](https://github.com/eltmon/overdeck/issues/4403)). +The dashboard also trusts `https://<OVERDECK_TRAEFIK_DOMAIN>` when +`OVERDECK_TRAEFIK_ENABLED=1` (or the `config.yaml` Traefik domain when no origin +environment variable is set), and `localhost:3010`, by default. + +Machines advertise their LAN and Tailscale addresses to linked machines on their own (see +[Linked machines](/configuration/linked-machines)), but browser addresses are still added +by hand as described above. ## List and revoke devices @@ -198,7 +203,7 @@ dashboard accepts no device session and logs an error naming the file. ## Anywhere status The **Anywhere** card shows whether other devices can use this machine. It -appears in **Settings → Anywhere** and on the **Health** page, and shows: +appears in **Settings → Anywhere** and on the experimental **Health** page, and shows: - **This machine:** its label and the start of its environment id. - **Reachable at:** the trusted addresses another device can open, or "Only @@ -209,10 +214,10 @@ appears in **Settings → Anywhere** and on the **Health** page, and shows: Serve address, or "Set up unfinished". See [Tailscale](/configuration/tailscale). - **Session Vault:** "Not set up", "Locked on this machine", "Key rotation unfinished", or "Ready" with its backend. **Set up** opens Settings → Session - Vault, which shows the `pan vault setup <git-url>` command to run in a - terminal. Setting up from the dashboard is planned - ([PAN-4446](https://github.com/eltmon/overdeck/issues/4446)). Not using the - vault is a valid choice, not a problem. + Vault, where **Set up a new vault** creates a vault and **Join an existing + vault** joins one. Not using the vault is a valid choice, not a problem. +- **Directory:** "Connected (free account)", "Connected", "Connecting", "Refused" or "Off". +- **Relay:** this month's relay use, or that the relay is not available. Below that, the card lists each problem with its fix: @@ -220,12 +225,12 @@ Below that, the card lists each problem with its fix: | --- | --- | | Tailscale Serve sends tailnet visitors to this dashboard, but a token is not required to sign in. | **Protect the dashboard** opens Set up Tailscale, which turns on token sign-in. | | No address another device can reach is trusted yet. | **Add an address** opens the pair dialog, where you can add one. | -| Session Vault is set up, but this machine cannot open it. | **Open Session Vault** goes to Settings → Session Vault, which shows the command to run in a terminal on this machine: `pan vault join <backend>`, then the vault passphrase or the recovery phrase. Unlocking from the dashboard is planned: [PAN-4446](https://github.com/eltmon/overdeck/issues/4446). | +| Session Vault is set up, but this machine cannot open it. | **Open Session Vault** goes to Settings → Session Vault, where **Unlock this machine** takes the vault passphrase or the recovery phrase. | | A vault key rotation started on this machine has not finished. | **How to fix** links to [Session Vault](/configuration/session-vault). Finish the rotation on this machine before syncing again. | | This machine's identity file is unreadable. | **How to fix** links to this page. Repair or restore `~/.overdeck/environment-id.json`; it is never re-created automatically. | -The card reads `GET /api/anywhere/status`, which any dashboard credential may -call. +The card reads `GET /api/anywhere/status`. The root session, a paired device and an +`admin` scoped token may call it; a narrower scoped token gets `403`. ## Scoped API tokens @@ -253,8 +258,11 @@ The scopes: | `read:state` | Issue, agent, agent-directory, Flywheel and pipeline reads. | | `read:conversations` | Conversation lists, one conversation, its messages and its summary, conversation search, and a conversation's scheduled messages and schedules. | | `tell` | Sending a message to an agent or a conversation, and creating, changing and deleting a conversation's scheduled messages and schedules. | -| `operate` | Everything `tell` allows, plus terminal WebSockets (`/ws/terminal`) and starting a conversation or a worker. | +| `operate` | Everything `tell` allows, plus terminal WebSockets (`/ws/terminal`), starting a conversation, worker or lane, stopping or resuming a conversation, and changing a conversation's model, effort or compaction. | | `approve` | Answering blocking prompts: permission prompts, menus, pi asks, Codex approvals, plan approvals and agent questions. Off unless you add it. | +| `read:costs` | Cost summaries, the request digest and one issue's costs. | +| `read:settings` | The resolved settings (`GET /api/settings/resolved`, secrets shown only as set or not set). | +| `forward` | Port forwards (`/ws/forward`) for **Open preview**. Only a linked machine's credential uses it. | | `admin` | Everything, like a paired device. | Anything not in the table needs `admin`. A request whose token lacks the scope @@ -289,7 +297,7 @@ confirmation. A browser signed in as a paired device can see the list but cannot create or revoke tokens; the section explains why. The table folds the one access token each running agent holds behind a collapsed **Show agent tokens (N)** toggle, and a **Sign-ins** list follows it with every MCP OAuth -client currently signed in — its access level, timestamps and a Revoke button +client currently signed in: its access level, timestamps and a Revoke button that ends the sign-in at once. ## What the LAN can reach @@ -299,7 +307,9 @@ does not come from this machine must carry a credential (the root session, a device session, a scoped API token, or the internal token), or it gets `401`. A scoped token is always judged by its scopes, even from this machine. "From this machine" means a loopback address, or the host-local Traefik and Docker networks that -front `overdeck.localhost`. +front `overdeck.localhost`. Paired [phones](/configuration/phone), [machine +links](/configuration/linked-machines) and [Overdeck connectors](/configuration/bots) are +also credentials in the same registry. These routes answer without a credential: @@ -365,7 +375,8 @@ dashboard, a Settings save that turns it off keeps it on; turn Serve off first ### On automatically Since v0.73.0 `require_token_mint` is on by itself whenever this machine has any -remote access: a trusted address that is not loopback, an active paired device, or +remote access: a trusted address you added that is not loopback (only an address saved +in `trusted-origins.json`, not `OVERDECK_TRUSTED_ORIGINS`), an active paired device, or a [machine link](/configuration/linked-machines) in either direction. The toggle in Settings then shows **On automatically because this machine has …** and cannot be turned off. A `false` in `config.yaml` cannot turn it off either while remote access @@ -394,10 +405,12 @@ Tailscale. A machine that is not signed in opens no connection and nothing else addresses it advertises. It also passes the short connection setup messages between two of your machines. It never carries your conversations and never vouches for a key. - **The Account card** (**Settings → Anywhere → Account**) shows the GitHub account this machine - is signed in as, the plan (Free account or Tester), this month's relay use against the 50 GB - allowance with its reset date, and **Manage account**, which opens your account page at - overdeck.ai. **Sign in** appears only in a browser on this machine; it opens overdeck.ai in a - new tab and returns to `http://127.0.0.1:<port>/oauth/account/callback`. Other devices see the + is signed in as, the plan (Free account or Tester), the relay line ("Not included in the free + account" on the free plan, otherwise this month's relay use against the 50 GB allowance with + its reset date in UTC), and **Manage account**, which opens your account page at + overdeck.ai. **Sign in** appears only in a browser on this machine, and only while the machine + is not signed in. Click it, then click **Open overdeck.ai sign-in**, which opens overdeck.ai in + a new tab and returns to `http://127.0.0.1:<port>/oauth/account/callback`. Other devices see the `pan account login` hint. - **See your machines:** **Settings → Anywhere → Directory**, or `pan machines directory`. - **Link two machines (approval):** on the new machine, click **Link** on the other machine's @@ -412,7 +425,8 @@ Tailscale. A machine that is not signed in opens no connection and nothing else crosses the network. - **The free account includes 3 machines.** A fourth machine is refused with "The free account includes 3 machines". **Remove from directory** (or `pan machines forget`) frees a slot. -- **The relay plan.** When no direct path exists (for example strict firewalls on both sides), +- **The relay plan (invite-only).** Paid plans, the relay plan among them, are invite-only + for now. When no direct path exists (for example strict firewalls on both sides), a relay plan connects the two machines through a Cloudflare TURN relay, still carrying the same secure channel. Without it, the link says "No direct path; install Tailscale or use the relay plan". Relay traffic counts against a 50 GB monthly allowance per account (UTC calendar @@ -442,13 +456,7 @@ Tailscale. A machine that is not signed in opens no connection and nothing else device use a machine's dashboard. To resume a conversation on a different machine, use [Session Vault](/configuration/session-vault). -## What comes next +## Get help -- A desktop connection list, environment switcher and version gating: - [PAN-4402](https://github.com/eltmon/overdeck/issues/4402). -- Discovered LAN and Tailscale endpoints shipped with machine links in v0.73.0 - ([PAN-4403](https://github.com/eltmon/overdeck/issues/4403), - [PAN-4645](https://github.com/eltmon/overdeck/issues/4645)); see - [Linked machines](/configuration/linked-machines). -- Launching Overdeck on an SSH host from the desktop app: - [PAN-4404](https://github.com/eltmon/overdeck/issues/4404). +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From bb1a527c878607c1539a8022dcee242a01685f00 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:12:40 -0500 Subject: [PATCH 56/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 601054ec0f9..fd4818f7baf 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:09:59.586Z", + "updated": "2026-11-19T04:12:40.472Z", "gitState": {}, "decisions": [], "hazards": [], @@ -404,9 +404,30 @@ "doneAt": "2026-11-19T04:09:45.640Z" }, "audit-remote-access": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:09:59.586Z" + "claimedAt": "2026-11-19T04:09:59.586Z", + "doneAt": "2026-11-19T04:12:40.472Z" + }, + "audit-remote-access.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:12:40.472Z" + }, + "audit-remote-access.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:12:40.472Z" + }, + "audit-remote-access.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:12:40.472Z" + }, + "audit-remote-access.ac4": { + "status": "completed", + "doneAt": "2026-11-19T04:12:40.472Z" + }, + "audit-remote-access.ac5": { + "status": "completed", + "doneAt": "2026-11-19T04:12:40.472Z" } } } From af5d31bb715f87e5594c9116449c872d52b2bb76 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:12:47 -0500 Subject: [PATCH 57/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index fd4818f7baf..51aa9831343 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:12:40.472Z", + "updated": "2026-11-19T04:12:47.588Z", "gitState": {}, "decisions": [], "hazards": [], @@ -428,6 +428,11 @@ "audit-remote-access.ac5": { "status": "completed", "doneAt": "2026-11-19T04:12:40.472Z" + }, + "audit-shared-sessions": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:12:47.587Z" } } } From 7998c5917e9eec3c6d9af3e051580d89d90a436b Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:14:06 -0500 Subject: [PATCH 58/80] docs(shared-sessions): date the release, fix harness and terminal claims Applies Appendix O rows 1-5 and every [ADD] Missing bullet to configuration/shared-sessions.mdx: "In this release" becomes "shipped in v0.74.0"; only Claude Code conversations actually stream, with the unavailable-transcript message for other harnesses; only a viewer joining from their own Overdeck gets the Terminal view, never a browser viewer; the share step names the conversation header's menu; adds the pan up prerequisite and the share-record file location; and adds a Get help section. Retitles per D4. Removes the em dash from the host-disconnected banner text. Item: audit-shared-sessions Item: audit-shared-sessions.ac1 Item: audit-shared-sessions.ac2 Item: audit-shared-sessions.ac3 Item: audit-shared-sessions.ac4 PR-note: shared-sessions.mdx: dated release, fixed harness/terminal claims (Appendix O) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- configuration/shared-sessions.mdx | 37 ++++++++++++++++++++++--------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/configuration/shared-sessions.mdx b/configuration/shared-sessions.mdx index 6d6ec00e0e9..e4301ccf192 100644 --- a/configuration/shared-sessions.mdx +++ b/configuration/shared-sessions.mdx @@ -1,5 +1,6 @@ --- -title: "Shared sessions" +title: "Shared sessions: share a live conversation by link" +sidebarTitle: "Shared sessions" description: "Share one live conversation by link and let other people watch it in their own Overdeck" --- @@ -15,14 +16,17 @@ decide who gets in. Once you admit someone, the conversation streams to their Ov directly from yours, peer to peer. The share service at overdeck.ai only introduces the two machines and checks who is allowed in. It never sees the conversation. -In this release: +Shared sessions shipped in v0.74.0. What they cover: -- Only Claude Code conversations can be shared. +- Only Claude Code conversations stream. **Share this conversation** appears on every + conversation that runs on this machine, but viewers of a conversation from another + harness see "The host's conversation transcript is not available." instead of messages. - Viewers see the messages. Tool calls, thinking, the work log, cost and context usage are not shared in the conversation view. -- Every admitted viewer can also open the **Terminal** view and watch the conversation's - live terminal, read-only. Anything that terminal shows is visible to them, including tool - calls or thinking the agent prints there. +- A viewer who joins from their own Overdeck can also open the **Terminal** view and watch + the conversation's live terminal, read-only. Anything that terminal shows is visible to + them, including tool calls or thinking the agent prints there. A browser viewer has no + Terminal view. - Viewers can suggest prompts. Contributors can also send prompts straight to the conversation. @@ -30,6 +34,8 @@ In this release: - The host runs Overdeck on their own computer and is signed in to overdeck.ai with [`pan account login`](/cli/account), which the host needs to create the link. +- The host needs the full dashboard running (`pan up`); `pan share` and the share dialog + never start one. - A viewer can join in three ways: from their own Overdeck (signed in with `pan account login`), without installing it with `npx @overdeck/core join <CODE>` (Node 22 or newer), or from a browser (see [Join in a browser](#join-in-a-browser)). @@ -40,7 +46,8 @@ In this release: ## Share a conversation 1. Open the conversation in the dashboard. -2. Open the ⋮ menu and choose **Share this conversation**, then **Create link**. +2. Open the ⋮ menu in the conversation header and choose **Share this conversation**, then + **Create link**. 3. Click **Copy** and send the link to the people you want to invite. The share dialog lists the people waiting to join and the people in the room. For each @@ -100,9 +107,9 @@ overdeck.ai is invite-only. If your GitHub account is not on the allowlist yet, page tells you so; ask the person who shared the link to get you added, then sign in again. A browser viewer is read-only: it shows the messages and the people in the room, with no -prompt box. If the connection to the host drops, click **Reconnect**. Reloading the page -rejoins without another click. Click **Leave** to leave, and **Sign out** on the page to -sign this browser out of overdeck.ai. +prompt box and no Terminal view. If the connection to the host drops, click **Reconnect**. +Reloading the page rejoins without another click. Click **Leave** to leave, and **Sign +out** on the page to sign this browser out of overdeck.ai. ## Roles @@ -158,7 +165,7 @@ prompts run on your machine, with your agent's permissions. host's live terminal for that conversation. It is read-only: nothing you type reaches the host's machine. **The host's terminal is not running.** means the conversation has no live terminal; **The host's terminal session ended.** means it stopped while you watched. -- **Host disconnected — reconnecting…**: the host's machine lost its connection to the +- **Host disconnected, reconnecting…**: the host's machine lost its connection to the share service. You keep the messages you already have. If the host comes back within 5 minutes, the conversation returns on its own and you do not wait in the lobby again. - **Reconnecting to the share service…**: your own machine lost its connection to the share @@ -197,3 +204,11 @@ through it. through the lobby. - A queue holds at most 20 prompts, at most 3 from one contributor, each up to 8,000 characters. + +## Get help + +The host's share record lives in `~/.overdeck/shared-sessions.json` (mode 0600) and is +re-parked on boot; a corrupt file must be deleted by hand. + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From d46c79de022a3d78976440c5c13dce6b0a0153d3 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:14:30 -0500 Subject: [PATCH 59/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 51aa9831343..a3c8482607b 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:12:47.588Z", + "updated": "2026-11-19T04:14:30.055Z", "gitState": {}, "decisions": [], "hazards": [], @@ -430,9 +430,26 @@ "doneAt": "2026-11-19T04:12:40.472Z" }, "audit-shared-sessions": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:12:47.587Z" + "claimedAt": "2026-11-19T04:12:47.587Z", + "doneAt": "2026-11-19T04:14:30.055Z" + }, + "audit-shared-sessions.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:14:30.055Z" + }, + "audit-shared-sessions.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:14:30.055Z" + }, + "audit-shared-sessions.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:14:30.055Z" + }, + "audit-shared-sessions.ac4": { + "status": "completed", + "doneAt": "2026-11-19T04:14:30.055Z" } } } From 651cc1cbbf5b571a501ec3a4592bacfb0257245a Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:14:36 -0500 Subject: [PATCH 60/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index a3c8482607b..c055e31cf37 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:14:30.055Z", + "updated": "2026-11-19T04:14:36.734Z", "gitState": {}, "decisions": [], "hazards": [], @@ -450,6 +450,11 @@ "audit-shared-sessions.ac4": { "status": "completed", "doneAt": "2026-11-19T04:14:30.055Z" + }, + "audit-share": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:14:36.734Z" } } } From cabc906b9e1739f3a8eb9e5a146bec38a80c8e26 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:15:32 -0500 Subject: [PATCH 61/80] docs(cli/share): fix messages, join URL and token-mint behavior Applies Appendix P rows 1-5 (O3 evidence) and every [ADD] Missing bullet to cli/share.mdx: pan share's error messages now match the real not-running and generic-refusal text; pan join documents the real dashboard-URL join link and its printed confirmation; adds the bad-target error; and the token-mint section corrects which browsers actually need a prior session (a reverse-proxied one, not a local one). Retitles per D4 and adds Get help per D3. Item: audit-share Item: audit-share.ac1 Item: audit-share.ac2 Item: audit-share.ac3 Item: audit-share.ac4 PR-note: cli/share.mdx: fixed messages/join URL/token-mint (Appendix P) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- cli/share.mdx | 36 ++++++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/cli/share.mdx b/cli/share.mdx index 5f7217422d4..3dd395edf8e 100644 --- a/cli/share.mdx +++ b/cli/share.mdx @@ -1,5 +1,6 @@ --- -title: pan share and pan join +title: "pan share and pan join: share a live conversation by link" +sidebarTitle: "pan share and pan join" description: Share a conversation by link and join one from the terminal --- @@ -37,9 +38,11 @@ JSON and nothing else. `pan share` exits 1 with a one-line reason when: - no conversation matches the id or name; -- the dashboard is not running (`Start it with pan up`); -- the dashboard refuses the share, for example `Sign in with pan account login to share - conversations.` or a conversation that was released to another machine. +- the dashboard is not running (`The Overdeck dashboard is not running. Start it with pan + up, then run pan share again.`); +- the dashboard refuses the share. The line reads `Cannot share <name>: <reason>`, for + example `Sign in with pan account login to share conversations.`, or a refusal for a + conversation that was released to another machine. ## pan join @@ -57,8 +60,9 @@ pan join <link-or-code> [--no-open] agents. A later `pan up` replaces it. Auto-start runs only for a local `http://` API URL with a port; otherwise `pan join` asks you to run `pan up`. 3. Asks the dashboard to join and waits up to 15 seconds for the share service to answer. -4. Opens `http://localhost:<port>/#/shared/<CODE>` in your browser, where you wait in the lobby - until the host lets you in. +4. Opens `<dashboard URL>/#/shared/<CODE>` (for example `http://localhost:3011/#/shared/BCDFGHJK`) + in your browser and prints it as `Shared conversation: <url>`. You wait in the lobby + there until the host lets you in. | State | Message | Browser | Exit | | --- | --- | --- | --- | @@ -75,6 +79,9 @@ pan join <link-or-code> [--no-open] | disconnected | `Cannot reach the share service (<reason>).` | no | 1 | | any other | `The join ended (<state>). Run pan join again.` | no | 1 | +A target that is neither a share link nor a join code exits 1 with +`Not a share link or join code: <target>. A join code looks like BCDF-GHJK.` + ### Without Overdeck installed On a computer with Node 22 or newer and no Overdeck, run: @@ -87,10 +94,19 @@ It does the same four steps. It needs no global install, tmux or Herdr. ### Headless machines -`--no-open` prints the URL instead of opening a browser. With no page open, the join closes after -about 60 seconds. Opening the URL later rejoins automatically. +`--no-open` prints the URL instead of opening a browser, followed by `Opening the page +later rejoins automatically.` With no page open, the join closes after about 60 seconds. +Opening the URL later rejoins automatically. ### Token-mint lockdown -With `dashboard.require_token_mint: true`, the browser must already be signed in to the dashboard; -the URL `pan join` opens carries no token. +The URL `pan join` opens carries no token. A browser on this machine still signs in by +itself with `dashboard.require_token_mint: true`, so the lobby opens normally. Only a +browser that reaches the dashboard through a reverse proxy must already hold a dashboard +session or be paired; see +[Remote access](/configuration/remote-access#local-reverse-proxies-require_token_mint). + +## Get help + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From 9dbe40a76b17445066a208b64c2a27665b131098 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:15:52 -0500 Subject: [PATCH 62/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index c055e31cf37..8b17fceb7bb 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:14:36.734Z", + "updated": "2026-11-19T04:15:52.649Z", "gitState": {}, "decisions": [], "hazards": [], @@ -452,9 +452,26 @@ "doneAt": "2026-11-19T04:14:30.055Z" }, "audit-share": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:14:36.734Z" + "claimedAt": "2026-11-19T04:14:36.734Z", + "doneAt": "2026-11-19T04:15:52.649Z" + }, + "audit-share.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:15:52.649Z" + }, + "audit-share.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:15:52.649Z" + }, + "audit-share.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:15:52.649Z" + }, + "audit-share.ac4": { + "status": "completed", + "doneAt": "2026-11-19T04:15:52.649Z" } } } From 68f9f6100b8f574a221eaaa6a9b476929cd9e7b2 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:16:00 -0500 Subject: [PATCH 63/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 8b17fceb7bb..22882a0e369 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:15:52.649Z", + "updated": "2026-11-19T04:16:00.558Z", "gitState": {}, "decisions": [], "hazards": [], @@ -472,6 +472,11 @@ "audit-share.ac4": { "status": "completed", "doneAt": "2026-11-19T04:15:52.649Z" + }, + "audit-triggers": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:16:00.558Z" } } } From edae561a1fa270663c3c6c617e08417c6c8c5a39 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:17:27 -0500 Subject: [PATCH 64/80] docs(triggers): date the release, fix rate-limit, Funnel and inbox claims Applies Appendix Q rows 1-11 (O3 evidence) and every [ADD] Missing bullet to configuration/triggers.mdx: the stale "next release" Note becomes "Added in v0.73.0"; rate limits now count every event that passes signature/CPU checks, not just successful ones; the Funnel section links Public MCP and documents its extra paths; the inbox section corrects its size/rate/plan 429 and 403 responses and the real pan triggers remove behavior (it leaves the inbox running); and a 400 body-read row and the read-only-conversation 503 case are added to the limits table. Retitles per D4 and adds Get help per D3. Item: audit-triggers Item: audit-triggers.ac1 Item: audit-triggers.ac2 Item: audit-triggers.ac3 Item: audit-triggers.ac4 Item: audit-triggers.ac5 PR-note: triggers.mdx: dated release, fixed rate-limit/Funnel/inbox (Appendix Q) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- configuration/triggers.mdx | 65 ++++++++++++++++++++++++++------------ 1 file changed, 44 insertions(+), 21 deletions(-) diff --git a/configuration/triggers.mdx b/configuration/triggers.mdx index 028c5b06cea..c03032ecd87 100644 --- a/configuration/triggers.mdx +++ b/configuration/triggers.mdx @@ -1,5 +1,6 @@ --- -title: Webhook triggers +title: "Webhook triggers: message or start conversations from GitHub, Stripe or CI" +sidebarTitle: "Webhook triggers" description: Let GitHub, Stripe, CI or a chat bot message a conversation or start one, through a secret URL on this machine --- @@ -11,7 +12,7 @@ project. Events reach the machine directly through Tailscale Funnel, so overdeck sees them and you need no overdeck.ai account. <Note> -Available from the next release. Manage triggers with [`pan triggers`](/cli/triggers) or +Added in v0.73.0. Manage triggers with [`pan triggers`](/cli/triggers) or Settings → Anywhere → Triggers. </Note> @@ -24,8 +25,9 @@ Every trigger has one target: archived conversation answers `410`. - **Project target.** Each event starts one new conversation in a registered project. The conversation's first message is your prompt template followed by the event. A project - target needs a prompt template. You can also set the model, harness and effort for the - conversations it starts; unset values follow the normal defaults. + target needs a prompt template. With `pan triggers add` you can also set the model, + harness and effort for the conversations it starts; unset values follow the normal + defaults. A trigger delivers **every event type** it receives, including GitHub's `ping` event. It has no repository or event-type filter, because the URL is the authorization and GitHub and @@ -43,6 +45,7 @@ pan triggers add deploys --project overdeck --prompt "A deploy event arrived. Ch ``` `--conversation` takes a conversation name or its numeric id; the trigger stores the name. +A trigger name is 1 to 64 characters: letters, digits, spaces, `.`, `_` and `-`. See [`pan triggers`](/cli/triggers) for every flag. From the dashboard: open **Settings → Anywhere**, then **Add trigger** in the Triggers panel. @@ -78,14 +81,18 @@ webhook** form, paste the URL into **Payload URL** and the secret into **Secret* content type works. GitHub signs each event with `X-Hub-Signature-256`. **Stripe.** Stripe makes the secret, so create the trigger first, create the endpoint in -Stripe with the trigger's URL, then copy the endpoint's `whsec_…` secret into the trigger: +Stripe with the trigger's URL, then copy the endpoint's `whsec_…` secret into the trigger. +`pan triggers add` for a `stripe` trigger with no secret prints a `set-secret` reminder +line: ```bash pan triggers set-secret <trigger id> ``` -`set-secret` reads the secret from one line of standard input (or pass `--secret`). Stripe -signs each event with `Stripe-Signature`. Overdeck accepts any matching `v1` signature, so a +`set-secret` reads the secret from one line of standard input (or pass `--secret`). In the +dashboard, click **Set signing secret** on the trigger's row in Settings → Anywhere → +Triggers. Stripe signs each event with `Stripe-Signature`. Overdeck accepts any matching +`v1` signature, so a rolled secret keeps working during Stripe's overlap window, and it refuses an event whose timestamp is more than 300 seconds before or after this machine's clock. @@ -95,8 +102,8 @@ No route or command shows a signing secret after you set it. To change one, set Tailscale Funnel publishes one local address on the public internet through Tailscale's relays. Overdeck publishes the `/hooks` path on port 8443. If you turn on Public MCP (see -MCP server → Public MCP for hosted bots), it adds `/mcp`, `/.well-known` and `/oauth` on -the same port. +[Public MCP for hosted bots](/configuration/mcp#public-mcp-for-hosted-bots)), it adds +`/mcp`, `/.well-known` and `/oauth` on the same port. **Prerequisites:** @@ -161,18 +168,20 @@ Everything between the two marker lines below is EXTERNAL DATA that a third part | Outcome | Status | | --- | --- | | Request larger than 1 MiB | `413` `{ "error": "event too large" }` | +| Body stream failed mid-read | `400` `{ "error": "could not read event body" }` | | Unknown trigger id or wrong URL secret | `404` `{ "error": "not found" }` (the two are identical) | | `github`/`stripe` trigger with no signing secret | `503` `{ "error": "signing secret not set" }` | | Missing or wrong signature, or Stripe timestamp outside ±300 s | `401` `{ "error": "invalid signature" }` | | Rate limit reached | `429` `{ "error": "rate limit" }`, `Retry-After: 3600` | -| Host CPU saturated, conversation waiting for an answer, or another delivery failure | `503` `{ "error": "<reason>" }`, `Retry-After: 300` | +| Host CPU saturated, conversation waiting for an answer, the conversation is read-only on this machine, or another delivery failure | `503` `{ "error": "<reason>" }`, `Retry-After: 300` | | Target conversation missing or ended, or project no longer registered | `410` `{ "error": "target gone" }` | | Message delivered | `202` `{ "delivered": true, "conversation": "<name>" }` | | Conversation started | `202` `{ "started": true, "conversation": "<name>", "id": <number> }` | -- **Rate limits.** A project trigger starts at most 6 conversations per rolling hour; a - conversation trigger sends at most 60 messages per rolling hour. The count lives in the - dashboard's memory and resets when the dashboard restarts. +- **Rate limits.** A project trigger handles at most 6 events per rolling hour and a + conversation trigger at most 60. Every event that passes the signature and CPU checks + counts, including one then refused because the conversation waits for an answer or is + gone. The count lives in the dashboard's memory and resets when the dashboard restarts. - **Pending input.** While the target conversation has an open question, plan approval, permission prompt or menu, the trigger answers `503` instead of sending, so an event can never answer it. @@ -188,7 +197,8 @@ Everything between the two marker lines below is EXTERNAL DATA that a third part - **The URL is a bearer secret.** Anyone who has it can send events. Treat it like a password, and remove the trigger if it leaks. -- **Funnel requests reach only `POST /hooks/*`.** Tailscale marks every funneled request +- **Funnel requests reach only `POST /hooks/*`, plus the Public MCP paths while Public MCP + is on.** Tailscale marks every funneled request with the `Tailscale-Funnel-Request` header and removes any copy a client sends. The dashboard answers such a request with `404` on every other method and path (even with a credential), never treats it as a local caller, refuses it a dashboard session, and @@ -210,9 +220,12 @@ delivers them when it comes back. It needs a signed-in machine (`pan account log Anywhere plan; the free account does not include it. - **Create one** with `pan triggers add <name> … --inbox`, or tick **Hold events while this - machine is offline** in **Settings → Anywhere → Add trigger**. The inbox URL is printed or - shown once, in place of the Funnel URL. Paste it into the sender's webhook settings. The - Funnel URL keeps working too. + machine is offline (overdeck.ai inbox, Anywhere plan)** in **Settings → Anywhere → Add + trigger**. The checkbox appears only while this machine is signed in, the directory is + online and the account's plan includes the inbox. The inbox URL is printed or shown once, + in place of the Funnel URL. Paste it into the sender's webhook settings. The trigger's + Funnel URL also works, but neither the dashboard nor `pan triggers add` prints it when you + add an inbox; `pan triggers add … --inbox --json` includes it as `hookPath` and `url`. - **Size.** The inbox takes events of at most 256 KiB and answers `413` for anything larger (the Funnel URL takes up to 1 MiB). - **Hold time.** Each event waits up to 24 hours. An event that is still undelivered after @@ -225,9 +238,13 @@ Anywhere plan; the free account does not include it. - **Stripe timestamps.** A Stripe signature must be within 300 s of when the inbox received the event, not of when this machine processes it, so a held Stripe event still verifies. - **The inbox answers at once** with `202 { "queued": true }`; it never waits for this - machine. A full inbox (200 events, or 64 MiB for the account) answers `429` with - `Retry-After: 3600`. -- **Removing the trigger** deletes its inbox and every event it holds. + machine. A full inbox (200 events in this inbox, or 64 MiB for the account) answers `429` + with `Retry-After: 3600`. More than 120 events a minute to one inbox answer `429` with + `Retry-After: 60`. When the account's plan no longer includes the inbox, it answers `403`. +- **Removing the trigger** in Settings → Anywhere → Triggers deletes its inbox and every + event it holds. `pan triggers remove` deletes only the trigger: its inbox keeps accepting + events, and this machine discards them because no trigger owns them. Remove inbox + triggers from the dashboard. ### What the inbox can see @@ -236,5 +253,11 @@ overdeck.ai sees each event once, in memory, while it accepts it: the body and t `Stripe-Signature` headers. It seals that copy at once to this machine's public key (`crypto_box_seal`) and stores **only the sealed copy**, which only this machine can open. It never holds the trigger's signing secret, so it cannot forge an event that passes the -signature check. Its logs name the inbox and the outcome, never the body. +signature check. Its logs name the message type, the machine and the outcome, never the +body or the inbox URL. + +## Get help + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From dc619fd846b02a329e82ad62715491e7d92c7946 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:17:49 -0500 Subject: [PATCH 65/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 22882a0e369..f20f2221351 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:16:00.558Z", + "updated": "2026-11-19T04:17:49.762Z", "gitState": {}, "decisions": [], "hazards": [], @@ -474,9 +474,30 @@ "doneAt": "2026-11-19T04:15:52.649Z" }, "audit-triggers": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:16:00.558Z" + "claimedAt": "2026-11-19T04:16:00.558Z", + "doneAt": "2026-11-19T04:17:49.762Z" + }, + "audit-triggers.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:17:49.762Z" + }, + "audit-triggers.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:17:49.762Z" + }, + "audit-triggers.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:17:49.762Z" + }, + "audit-triggers.ac4": { + "status": "completed", + "doneAt": "2026-11-19T04:17:49.762Z" + }, + "audit-triggers.ac5": { + "status": "completed", + "doneAt": "2026-11-19T04:17:49.762Z" } } } From 9423e966ada8fecec97dc5d0d6f9b451f46db8f6 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:17:58 -0500 Subject: [PATCH 66/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index f20f2221351..791e7860c03 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:17:49.762Z", + "updated": "2026-11-19T04:17:58.919Z", "gitState": {}, "decisions": [], "hazards": [], @@ -498,6 +498,11 @@ "audit-triggers.ac5": { "status": "completed", "doneAt": "2026-11-19T04:17:49.762Z" + }, + "audit-cli-triggers": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:17:58.919Z" } } } From b6c3897a2be26c92892a04b299fa8f238ae6ff8c Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:19:02 -0500 Subject: [PATCH 67/80] docs(cli/triggers): date the release, fix inbox, JSON and remove behavior Applies Appendix R rows 1-9 and every [ADD] Missing bullet to cli/triggers.mdx: the stale "next release" Note becomes "Added in v0.73.0"; the intro now says add --inbox needs the running dashboard; --json documents the --inbox response shape; list's SIGNING SECRET column covers none-verify triggers and its empty-list line drops the stray nested backticks; remove now says it leaves a directory inbox running; and set-secret documents its success message and length validation. Retitles per D4 and adds Get help per D3. Item: audit-cli-triggers Item: audit-cli-triggers.ac1 Item: audit-cli-triggers.ac2 Item: audit-cli-triggers.ac3 Item: audit-cli-triggers.ac4 PR-note: cli/triggers.mdx: dated release, fixed inbox/JSON/remove (Appendix R) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- cli/triggers.mdx | 48 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 15 deletions(-) diff --git a/cli/triggers.mdx b/cli/triggers.mdx index 0e5c18d59e9..bcf77ad43ad 100644 --- a/cli/triggers.mdx +++ b/cli/triggers.mdx @@ -1,18 +1,20 @@ --- -title: pan triggers +title: "pan triggers: create and manage webhook triggers" +sidebarTitle: pan triggers description: Manage webhook triggers that message or start conversations --- # `pan triggers` <Note> -Available from the next release. +Added in v0.73.0. </Note> Create, list, remove and set the signing secret of webhook triggers: secret URLs that send -an event to a conversation or start a conversation in a project. Every subcommand works -without a running dashboard; it writes `~/.overdeck/triggers.json` directly, and the -dashboard reads that file on every event. See [Webhook triggers](/configuration/triggers). +an event to a conversation or start a conversation in a project. Every subcommand except +`add --inbox` works without a running dashboard; it writes `~/.overdeck/triggers.json` +directly, and the dashboard reads that file on every event. See +[Webhook triggers](/configuration/triggers). ## add @@ -32,14 +34,16 @@ pan triggers add <name> (--conversation <name-or-id> | --project <key>) [options | `--harness <name>` | Harness for conversations a project trigger starts. | | `--effort <level>` | Reasoning effort for conversations a project trigger starts. | | `--inbox` | Also create an overdeck.ai directory inbox that holds events while this machine is offline (Anywhere plan; needs the running dashboard and `pan account login`). Prints the inbox URL instead of the Funnel lines. | -| `--json` | Print `{ trigger, hookPath, url, localUrl, funnelCommand, generatedSigningSecret }` as JSON. `url` is `null` when no `.ts.net` address is saved. | +| `--json` | Print `{ trigger, hookPath, url, localUrl, funnelCommand, generatedSigningSecret }` as JSON. `url` is `null` when no `.ts.net` address is saved. With `--inbox`, it prints the dashboard's answer instead: `{ trigger, hookPath, url, urlSecretShownOnce, generatedSigningSecret, inboxUrl }`. | Pass exactly one of `--conversation` and `--project`; otherwise it exits 1. An unknown -conversation or project exits 1. +conversation or project exits 1. A trigger name is 1 to 64 characters: letters, digits, +spaces, `.`, `_` and `-`. It prints the hook path, the local test URL (`http://127.0.0.1:<port>/hooks/…`), the Funnel URL (`https://<machine>.<tailnet>.ts.net:8443/hooks/…` unless a `.ts.net` address is saved), -any generated signing secret, the Funnel command, and then: +any generated signing secret, a `set-secret` reminder for a `stripe` trigger without a +secret, the Funnel command, and then: ``` The URL is shown once. Save it now. @@ -55,8 +59,8 @@ Created trigger trg_3f9a1c2b7d4e ("deploys") with an overdeck.ai inbox The inbox holds events for 24 hours while this machine is offline. The URL is shown once. Save it now. ``` -On a free account, signed out, or when the directory does not answer within 10 seconds, it -creates nothing and exits 1 with the reason. See +With the dashboard not running, on a free account, signed out, or when the directory does +not answer within 10 seconds, it creates nothing and exits 1 with the reason. See [Hold events with the directory inbox](/configuration/triggers#hold-events-with-the-directory-inbox). ## list @@ -66,14 +70,19 @@ pan triggers list [--json] ``` Lists triggers with columns `ID NAME TARGET VERIFY SIGNING SECRET CREATED`. `TARGET` is -`conversation <name>` or `project <key>`; `SIGNING SECRET` is `secret set` or -`secret not set` for `github` and `stripe` triggers. It never prints a secret. +`conversation <name>` or `project <key>`; `SIGNING SECRET` is `-` for `none` triggers and +`secret set` or `secret not set` for `github` and `stripe` triggers. It never prints a +secret. | Flag | Effect | | --- | --- | | `--json` | Print the triggers as JSON. | -With no triggers: `` `No triggers. Create one with `pan triggers add`.` `` +With no triggers it prints: + +``` +No triggers. Create one with `pan triggers add`. +``` ## remove @@ -81,7 +90,9 @@ With no triggers: `` `No triggers. Create one with `pan triggers add`.` `` pan triggers remove <id> ``` -Removes the trigger. Its URL answers `404` from the next event on: +Removes the trigger. Its URL answers `404` from the next event on. It does not delete a +directory inbox; remove an inbox trigger in Settings → Anywhere → Triggers so its inbox is +deleted too: ``` Removed trigger <id>. Its URL now answers 404. @@ -107,4 +118,11 @@ pbpaste | pan triggers set-secret trg_3f9a0c1d2e4b | --- | --- | | `--secret <value>` | The signing secret. | -An empty value exits 1. An unknown id prints `No trigger with id <id>.` and exits 1. +On success it prints `Set the signing secret for trigger <id>.` An empty value, or one that +is not 8 to 256 characters without whitespace, exits 1. An unknown id prints `No trigger +with id <id>.` and exits 1. + +## Get help + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From 39bda096000fdf02a0ddf29cd3490cd0ee521284 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:19:25 -0500 Subject: [PATCH 68/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 791e7860c03..4bbfd5e3d12 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:17:58.919Z", + "updated": "2026-11-19T04:19:25.135Z", "gitState": {}, "decisions": [], "hazards": [], @@ -500,9 +500,26 @@ "doneAt": "2026-11-19T04:17:49.762Z" }, "audit-cli-triggers": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:17:58.919Z" + "claimedAt": "2026-11-19T04:17:58.919Z", + "doneAt": "2026-11-19T04:19:25.134Z" + }, + "audit-cli-triggers.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:19:25.134Z" + }, + "audit-cli-triggers.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:19:25.134Z" + }, + "audit-cli-triggers.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:19:25.134Z" + }, + "audit-cli-triggers.ac4": { + "status": "completed", + "doneAt": "2026-11-19T04:19:25.134Z" } } } From cece92b29135bb5cf62f3c5a28b18be3ce7515e7 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:19:32 -0500 Subject: [PATCH 69/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 4bbfd5e3d12..863a4cb6055 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:19:25.135Z", + "updated": "2026-11-19T04:19:32.212Z", "gitState": {}, "decisions": [], "hazards": [], @@ -520,6 +520,11 @@ "audit-cli-triggers.ac4": { "status": "completed", "doneAt": "2026-11-19T04:19:25.134Z" + }, + "audit-bots": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:19:32.212Z" } } } From 94044e5c8bc4499829ca5aff67183af13d1a8064 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:21:32 -0500 Subject: [PATCH 70/80] docs(bots): fix default access, connector files and troubleshooting Applies Appendix S rows 1-11 and every [ADD] Missing bullet to configuration/bots.mdx: default bot access is spelled out as Read state, Read conversations and Send messages; the never-gets list adds read:events; the connector command table gains the connect row; the connector home now documents the fifth pending-signin file; OpenClaw's "HTTP config below" reference is fixed to "above"; the Tailscale section names only the two READMEs that actually document a Tailscale route and links the connector-instead anchor; the relay-outage advice documents the TURN relay row's visibility condition; adds the no-chat-platform-integration note and the Hermes README link; and appends the Discord help sentence to Troubleshooting. Retitles per D4 and removes every remaining em/en dash. Item: audit-bots Item: audit-bots.ac1 Item: audit-bots.ac2 Item: audit-bots.ac3 Item: audit-bots.ac4 Item: audit-bots.ac5 PR-note: bots.mdx: fixed default access/connector files/troubleshooting (Appendix S) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- configuration/bots.mdx | 68 +++++++++++++++++++++++++----------------- 1 file changed, 41 insertions(+), 27 deletions(-) diff --git a/configuration/bots.mdx b/configuration/bots.mdx index 58d5b2bc30f..4c52f84c48e 100644 --- a/configuration/bots.mdx +++ b/configuration/bots.mdx @@ -1,5 +1,6 @@ --- -title: "Connect a bot" +title: "Connect a bot: give Hermes, OpenClaw or Grok scoped MCP access" +sidebarTitle: "Connect a bot" description: Give a chat bot or a hosted assistant scoped, revocable access to Overdeck through the Overdeck connector, Tailscale or public MCP --- @@ -8,12 +9,13 @@ description: Give a chat bot or a hosted assistant scoped, revocable access to O A bot is an MCP client that Overdeck did not launch: Hermes, OpenClaw, Grok Build, Grok Bot, or a script that calls the xAI API. It uses the same [MCP server](/configuration/mcp) and tools as everything else, with a token -you can scope and revoke. +you can scope and revoke. Overdeck has no native Slack, Discord or Telegram +bot integration; this page covers MCP clients only. There are two ways in, and both keep the traffic encrypted until it reaches hardware you control: -- **A bot with a shell** — Hermes, OpenClaw, Grok Build, Grok Bot — runs the +- **A bot with a shell** (Hermes, OpenClaw, Grok Build, Grok Bot) runs the Overdeck connector next to it. The connector pairs with one machine and reaches it over an end-to-end encrypted channel, directly or through the relay. You can use Tailscale instead. @@ -26,7 +28,8 @@ Nothing on overdeck.ai ever sees a tool call in plain text. ## Connect in one paste -Pick the bot in **Connect a bot**, pick its access (default Read + Tell), and +Pick the bot in **Connect a bot**, pick its access (by default Read state, Read +conversations and Send messages), and click **Copy for <bot>**. Paste the copied message into the bot's chat. The bot runs the command inside it, shows you one link, and you click it and **Authorize**; the bot runs the command again and reports it is ready. @@ -58,9 +61,11 @@ connects, when dismissed, or when the connector is removed. ## The Connect a bot dialog -Give an outside MCP client — Hermes, OpenClaw, Grok Build, Grok Bot, or a script -calling the xAI API — scoped, revocable access to this machine. Open **Connect a -bot** from **Settings → Anywhere → Bots**, or from the command palette. +Give an outside MCP client (Hermes, OpenClaw, Grok Build, Grok Bot, or a script +calling the xAI API) scoped, revocable access to this machine. Open **Connect a +bot** from **Settings → Anywhere → Bots**, or from the command palette. Only a +browser on this machine can connect or manage bots; a paired device sees "Only +a browser on this machine can manage bots." The dialog picks a reach by platform: @@ -73,22 +78,23 @@ The dialog picks a reach by platform: Access defaults to `read:state`, `read:conversations` and `tell`; `read:state` is always on. `operate` and `approve` are off by default. A bot never gets -`admin`, `forward`, `read:settings` or `read:costs`, regardless of what is -ticked. +`admin`, `forward`, `read:settings`, `read:costs` or `read:events`, regardless +of what is ticked. Each reach produces a different setup: -- **Overdeck connector** — a message to paste into the bot, built around a +- **Overdeck connector**: a message to paste into the bot, built around a pairing code that works once, within 30 minutes. It runs `pan mcp connector connect` for you; the manual pairing string and commands (`login`, `pair`, `serve`) live under "Set up by hand instead" in the dialog's output. -- **Tailscale, This computer** — an access token, shown once. The config +- **Tailscale, This computer**: an access token, shown once. The config snippet never carries it: it goes only into the one-time "Token setup" field, kept out of the config through `OVERDECK_MCP_TOKEN` or `OVERDECK_MCP_TOKEN_FILE`. -- **Public MCP** — the public URL plus, for the xAI API, the - `pan mcp oauth issue` command that mints its token. +- **Public MCP**: the public URL plus, for the xAI API, the + `pan mcp oauth issue` command that mints its token. Public MCP must be on + first; while it is off the dialog shows **Show Public MCP settings** instead. ## Platforms @@ -97,7 +103,7 @@ Each reach produces a different setup: The Hermes connector config, for example: ```yaml -# ~/.hermes/config.yaml — connector route (default) +# ~/.hermes/config.yaml: connector route (default) mcp_servers: overdeck: url: "http://127.0.0.1:7466/mcp" @@ -114,11 +120,13 @@ plugins: ``` The plugin reads `summary` and `allow_answers` from `settings`; `mcp_allowlist` -grants it the `overdeck` server. See `integrations/hermes/README.md` for the -`/overdeck` commands. +grants it the `overdeck` server. See +[`integrations/hermes/README.md`](https://github.com/eltmon/overdeck/tree/main/integrations/hermes) +for the `/overdeck` commands. Connect in one paste registers the connector as a stdio server in -`mcp_servers` instead of this HTTP entry; see `integrations/hermes/README.md`. +`mcp_servers` instead of this HTTP entry; see +[`integrations/hermes/README.md`](https://github.com/eltmon/overdeck/tree/main/integrations/hermes). ### OpenClaw @@ -145,7 +153,7 @@ plugins: { entries: { overdeck: { config: { localToken: "${OVERDECK_CONNECTOR_LO Connect in one paste registers the connector with `openclaw mcp set` as a stdio server, which gives the agents the Overdeck tools; the plugin's -summary and chat tools still need the HTTP config below. +summary and chat tools still need the HTTP config above. ### Grok Build @@ -168,7 +176,7 @@ plugin's own `overdeck` server also loads into those sessions. ### Grok Bot -Pick **Grok Bot** in Connect a bot and click **Copy for Grok Bot** — see +Pick **Grok Bot** in Connect a bot and click **Copy for Grok Bot**; see [Connect in one paste](#connect-in-one-paste). Paste the message into Grok Bot's chat; it runs `pan mcp connector connect` itself, shows you a link to click and **Authorize**, then reports it is ready. @@ -215,6 +223,7 @@ shows the exact version. | Command | What it does | | --- | --- | +| `pan mcp connector connect '<pairing string>' [--name <bot>] [--platform <id>] [--wait <seconds>] [--account-url <url>] [--directory-url <url>]` | Signs in, pairs, verifies and prints the MCP registration in one command a bot can run again; the message from Connect a bot runs it. `--platform` is `grok-bot`, `grok-build`, `hermes`, `openclaw` or `other` (default). See [`pan mcp connector connect`](/cli/mcp#connect). | | `pan mcp connector login [--account-url <url>] [--directory-url <url>]` | Signs the connector in to overdeck.ai with the device flow: open the URL it prints and enter the code. | | `pan mcp connector pair '<pairing string>' [--label <name>]` | Pairs with the machine named in the string from "Connect a bot". `--label` names the connector on the machine (default: the host name). | | `pan mcp connector serve [--port <port>] [--stdio] [--label <name>]` | Serves the tools on `127.0.0.1:<port>` (default 7466) until stopped, or one stdio session with `--stdio`. | @@ -224,10 +233,11 @@ shows the exact version. ### The connector home All connector state lives in `$OVERDECK_CONNECTOR_HOME`, default -`~/.overdeck-connector`, mode 0700. It holds four files, each mode 0600: +`~/.overdeck-connector`, mode 0700. It holds up to five files, each mode 0600: `account.json` (the overdeck.ai sign-in), `identity.json` (the connector id and its keys), `pairing.json` (the paired machine and its connector token) and -`local-token`. The connector never reads or writes `~/.overdeck`, so it can run +`local-token`, plus `pending-signin.json` while a `connect` sign-in waits for +approval. The connector never reads or writes `~/.overdeck`, so it can run on an Overdeck machine without touching that machine's sign-in or keys. A file that other users can read is refused with a `chmod 600` hint. @@ -286,7 +296,7 @@ the machine and keeps `local-token`, so the bot's config keeps working. Restart `logout` does four steps in order: it removes the connector from the machine (`DELETE /api/connectors/self`), removes it from the overdeck.ai directory, -revokes its overdeck.ai sign-in, and deletes the four files. A step that fails +revokes its overdeck.ai sign-in, and deletes its files. A step that fails prints one line and the next step still runs; the files are always deleted. If the machine was unreachable, remove the connector there under **Settings → Anywhere → Bots**. @@ -301,8 +311,8 @@ ticked and shows it once in the "Token setup" field. The bot then calls For a bot in a container, run Tailscale inside the container with an ephemeral, tagged auth key, and give the tag an ACL that reaches only the -dashboard host on port 443. Each integration README has a "Tailscale route" -section with the exact config. Grok Build's Tailscale route is not working yet +dashboard host on port 443. The Hermes and OpenClaw READMEs have a "Tailscale +route" section with the exact config. Grok Build's Tailscale route is not working yet ([#5029](https://github.com/eltmon/overdeck/issues/5029)); use the connector or "This computer" for Grok Build. @@ -318,11 +328,15 @@ result, so check that first (next point). What to do: use [Public MCP](/configuration/mcp#public-mcp-for-hosted-bots) (see Grok Bot above), or run the connector on a host with WebRTC egress, or -use Tailscale instead (`#tailscale-instead-of-the-connector`). +use [Tailscale instead of the connector](#tailscale-instead-of-the-connector). How to tell a relay outage from a blocked bot: run `pan doctor` on the -machine. If its `TURN relay` row is `ok`, the block is on the bot's side; if -it warns, the relay or the machine's own network is the problem. +machine. The `TURN relay` row appears only when the machine is signed in to +overdeck.ai with the relay plan. If the row is `ok`, the block is on the bot's +side; if it warns, the relay or the machine's own network is the problem. + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). ## Remove a bot From a029f80d4f7f5b1b277f6f4500b63e6464d00049 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:21:56 -0500 Subject: [PATCH 71/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 863a4cb6055..7550ce8886c 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:19:32.212Z", + "updated": "2026-11-19T04:21:56.265Z", "gitState": {}, "decisions": [], "hazards": [], @@ -522,9 +522,30 @@ "doneAt": "2026-11-19T04:19:25.134Z" }, "audit-bots": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:19:32.212Z" + "claimedAt": "2026-11-19T04:19:32.212Z", + "doneAt": "2026-11-19T04:21:56.265Z" + }, + "audit-bots.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:21:56.265Z" + }, + "audit-bots.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:21:56.265Z" + }, + "audit-bots.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:21:56.265Z" + }, + "audit-bots.ac4": { + "status": "completed", + "doneAt": "2026-11-19T04:21:56.265Z" + }, + "audit-bots.ac5": { + "status": "completed", + "doneAt": "2026-11-19T04:21:56.265Z" } } } From 4f80c9cf0969ce0bf6783c489a8e07a188fe64cd Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:22:04 -0500 Subject: [PATCH 72/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 7550ce8886c..82a1c13faec 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:21:56.265Z", + "updated": "2026-11-19T04:22:04.010Z", "gitState": {}, "decisions": [], "hazards": [], @@ -546,6 +546,11 @@ "audit-bots.ac5": { "status": "completed", "doneAt": "2026-11-19T04:21:56.265Z" + }, + "audit-phone": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:22:04.010Z" } } } From 9df1ce2e479106d3141d98f28acd35155da7d580 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:24:02 -0500 Subject: [PATCH 73/80] docs(phone): describe both phone setups, remove transitional notes Applies Appendix T rows 1-12 and every [ADD] Missing bullet (on top of PAN-5472) to configuration/phone.mdx: the intro now describes both the browser phone view and the Overdeck app instead of only /m; "Before you start" is scoped to the browser view; token sign-in documents its own auto-on condition; the Install app and Turn on notifications locations match the real banner UI; the pipeline row and agent state labels match the code; the two "as soon as the machine runs the new version" transitional notes for already-shipped features are replaced with the real bundled-app caveat; and Remove a phone covers both the dashboard and in-app removal paths. Adds the command-palette, Forget-paired-machine and Needs-you-notice-kinds Missing bullets, and a final Get help section. Keeps the title and store-status sentence. Item: audit-phone Item: audit-phone.ac1 Item: audit-phone.ac2 Item: audit-phone.ac3 Item: audit-phone.ac4 PR-note: phone.mdx: described both setups, removed transitional notes (Appendix T) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- configuration/phone.mdx | 76 +++++++++++++++++++++++++---------------- 1 file changed, 47 insertions(+), 29 deletions(-) diff --git a/configuration/phone.mdx b/configuration/phone.mdx index 611905985cd..e740be82ada 100644 --- a/configuration/phone.mdx +++ b/configuration/phone.mdx @@ -5,16 +5,18 @@ description: Install one machine's dashboard on a phone over Tailscale and answe # Use Overdeck on your phone -The phone app is a small version of the dashboard at `/m`. It shows what needs -you, your conversations and the pipeline, and it answers agent questions. You install it -from the browser to the home screen. It connects to one machine through that -machine's Tailscale address and signs in with its own pairing, never with the -machine's root token. +Overdeck runs on a phone in two ways. The browser phone view is a small version of the +dashboard at `/m`: you install it from the phone's browser to the home screen, and it +reaches one machine at that machine's Tailscale HTTPS address. The Overdeck app for iPhone +and Android is still in testing (see below) and reaches your machines through overdeck.ai, +with no Tailscale. Both show what needs you, your conversations and the pipeline, answer +agent questions, and sign in with their own pairing, never with the machine's root token. -## Before you start +## Before you start (browser phone view) - **Tailscale Serve with HTTPS on the machine.** A phone app needs an - `https://` address. Publish the dashboard port with `tailscale serve`, so the + `https://` address. Select **Set up Tailscale** in Settings → Anywhere (or run + `pan tailscale setup`) to turn on HTTPS access through Tailscale Serve, so the machine is reachable at an address such as `https://desk.tailnet.ts.net`. See [Remote access](/configuration/remote-access) for trusted addresses and pairing. @@ -22,17 +24,22 @@ machine's root token. token to sign in (`dashboard.require_token_mint: true` in `~/.overdeck/config.yaml`). Tailscale Serve forwards phone traffic from the machine itself. With the setting off, the dashboard treats the phone as a - browser on the machine and gives it full access without pairing. + browser on the machine and gives it full access without pairing. The setting + turns on by itself, and cannot be turned off, once the machine has a trusted + remote address, a paired device or a machine link. **Set up Tailscale** also + turns it on. ## Set up a phone -On the machine, open Settings → Anywhere → **Set up a phone**. The dialog has -two tabs: **Overdeck app** (first) and **Browser on the phone**. +On the machine, open Settings → Anywhere → **Set up a phone**, or run **Set up a phone** +from the command palette. The dialog has two tabs: **Overdeck app** (first) and +**Browser on the phone**. ### Overdeck app -This machine must be signed in to overdeck.ai first (`pan account login`); -otherwise the tab says so and shows no code. +Step 1 asks you to install the Overdeck app and sign in to it with the same overdeck.ai +account as this machine. This machine must be signed in to overdeck.ai first +(`pan account login`); otherwise the tab says so and shows no code. The iOS and Android apps are in TestFlight and Google Play internal testing. They are not in the public App Store or Google Play yet, so most people should use the browser phone view @@ -41,7 +48,9 @@ with the app. The code works once and expires after 10 minutes; select **Create another code** for a new one. The tab lists the phones paired with this machine; **Remove** signs a phone out of this machine and closes its open connections. No Tailscale is -needed for the app. +needed for the app. In the Overdeck app's Settings, **Paired machines** has its own +**Forget**, which removes a machine from the phone only; to remove the phone from the +machine, use Settings → Anywhere there. ### Browser on the phone @@ -62,7 +71,7 @@ The dialog has four steps: ## Android Scan the pairing code with the camera. Chrome opens the phone app and pairs -it. Then select **Install app** at the top of the screen to add it to the home +it. Then select **Install app** in the banner below the header to add it to the home screen. ## iPhone @@ -93,8 +102,9 @@ question. To give an answer that is not an option, tap **Type an answer**. Tap **Pipeline** (or open `/m/pipeline`) to see the active issues grouped by phase: Ship, Review, Work, Plan and Ready. Each row shows the issue ID and -title. **Needs you** marks an issue that waits for you. Tap a row to see the -issue: its phase, state, agent (live, idle or stopped, with its last +title, with its project and how long ago it changed. **Needs you** marks an issue that +waits for you. Tap a row to see the +issue: its phase, state, agent (Live, Idle, Waiting for you, Done or Stopped, with its last activity), cost so far by stage, pull request with its review and checks, description (long ones collapsed behind **Show more**), project, labels and a link to the tracker. A value the machine cannot read says "not available". @@ -109,8 +119,10 @@ the desktop dialog. Other kinds of waiting input are shown but not answered on the phone. These include permission prompts, plan approvals, choice menus, rate-limit menus, -session resume, held handoffs and turns that ended. For a conversation, tap -**Open** to read it. For an agent, answer it on the desktop. +session resume, held handoffs and turns that ended. Needs you also shows read-only rows +for MCP sign-ins and other machine notices, such as "Approve on the desktop", harness +update failures, restart resumes, bot connections and agent requests. For a conversation, +tap **Open** to read it. For an agent, answer it on the desktop. The phone groups conversations by project. Each project gets its own header, with No project last. Every group starts collapsed, and the phone remembers @@ -130,26 +142,25 @@ Overdeck app updates when you install a new build and shows no banner. ## Notifications -In the phone app, tap **Turn on notifications** at the top of the screen and -allow notifications. A notification for a question or an approval opens its +In the browser phone view, tap **Turn on notifications** in the banner below the header, +or in Settings (the gear in the header), and allow notifications. In the Overdeck app, turn +on **Notifications** in the app's Settings; see +[Push notifications](/configuration/push-notifications#on-android) for Android permission. +A notification for a question or an approval opens its card in Needs you. A notification that an issue finished, failed or stopped opens that issue's sheet instead, with a **What happened** line naming the event and when it happened. See [Push notifications](/configuration/push-notifications) for what is sent and how it is encrypted. -The browser phone view (`/m`) opens the issue sheet as soon as the machine -runs the new version; the installed Overdeck app opens it after its next app -update, because the app bundles its own copy of the screens. Before that -update, tapping the notification on Android opens the machine list instead. +The installed Overdeck app bundles its own copy of the phone screens, so a change to them +reaches the app only with a new app build. A notification for a question that is no longer waiting opens Needs you with "This question was already answered." When this machine cannot read a linked machine's list, Needs you shows `Can't reach <machine>; it may have items waiting.` Open that machine from the -machine list to see its items. The browser phone view (`/m`) shows this row as soon as the machine runs the new -version; the installed Overdeck app shows it after its next app update, -because the app bundles its own copy of the screens. +machine list to see its items. The phone app's service worker only shows notifications. It never stores pages, so the phone always shows the current state of the machine. @@ -197,8 +208,10 @@ phone the next time it successfully connects to that machine. ## Remove a phone On the machine, open Settings → Anywhere → Paired devices and select -**Revoke** next to the phone. The next time the phone app opens, it shows -**Pair this phone** again. +**Revoke** next to the phone, or select **Remove** under Phones paired with this machine +in the Set up a phone dialog's Overdeck app tab. The next time the browser phone view +opens, it shows **Pair this phone** again. The Overdeck app shows "This phone was removed +from <machine>. Pair again." with **Pair again** and **Forget**. ## Delete your account @@ -209,3 +222,8 @@ undone. The phone then signs out and shows **Your account is being deleted.** If the request fails, the phone stays signed in and offers **Delete on the web** instead. You can also delete the account at [https://account.overdeck.ai/account](https://account.overdeck.ai/account). + +## Get help + +Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a +[GitHub Issue](https://github.com/eltmon/overdeck/issues). From 67a25f2e4163525bce7aafbeb6624924b10f50b5 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:24:25 -0500 Subject: [PATCH 74/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 82a1c13faec..be4c0127890 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:22:04.010Z", + "updated": "2026-11-19T04:24:25.757Z", "gitState": {}, "decisions": [], "hazards": [], @@ -548,9 +548,26 @@ "doneAt": "2026-11-19T04:21:56.265Z" }, "audit-phone": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:22:04.010Z" + "claimedAt": "2026-11-19T04:22:04.010Z", + "doneAt": "2026-11-19T04:24:25.756Z" + }, + "audit-phone.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:24:25.756Z" + }, + "audit-phone.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:24:25.756Z" + }, + "audit-phone.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:24:25.756Z" + }, + "audit-phone.ac4": { + "status": "completed", + "doneAt": "2026-11-19T04:24:25.756Z" } } } From d884beae2b42e3feca9f4e088d3b760b73fdab8d Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:24:33 -0500 Subject: [PATCH 75/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index be4c0127890..7065b4a5d51 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:24:25.757Z", + "updated": "2026-11-19T04:24:33.726Z", "gitState": {}, "decisions": [], "hazards": [], @@ -568,6 +568,11 @@ "audit-phone.ac4": { "status": "completed", "doneAt": "2026-11-19T04:24:25.756Z" + }, + "audit-push": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:24:33.726Z" } } } From a90ce2e6efba7f4a31c4df6929cafb571a30b6f4 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:26:30 -0500 Subject: [PATCH 76/80] docs(push-notifications): remove stale ship notes, fix config and failure behavior Applies Appendix U rows 1-12 and every [ADD] Missing bullet to configuration/push-notifications.mdx: the shipped Set up Tailscale action and /m phone shell notes are no longer "ships"/"once ... ships"; pairing steps follow the real Set up a phone dialog and the iPhone Safari-pairing limitation; the disk alert row names the actual config keys; the config section names ~/.overdeck/config.yaml; enabled: false is corrected to still allow Send test; a low-disk alert's own title and the ntfy topic/URL validation rules are documented; and Troubleshooting's failure wording and the fourth no-button reason are corrected, with the Discord help sentence appended. Retitles per D4 and removes every em dash on the page. Item: audit-push Item: audit-push.ac1 Item: audit-push.ac2 Item: audit-push.ac3 Item: audit-push.ac4 PR-note: push-notifications.mdx: removed stale ship notes, fixed config/failures (Appendix U) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 --- configuration/push-notifications.mdx | 75 ++++++++++++++++++---------- 1 file changed, 48 insertions(+), 27 deletions(-) diff --git a/configuration/push-notifications.mdx b/configuration/push-notifications.mdx index 00384757115..a4a3956222e 100644 --- a/configuration/push-notifications.mdx +++ b/configuration/push-notifications.mdx @@ -1,5 +1,6 @@ --- -title: "Push notifications" +title: "Push notifications: get alerted when an agent needs you" +sidebarTitle: "Push notifications" description: "Get a phone notification when an agent or conversation needs you, sent by your own machine with end-to-end encrypted Web Push and an optional ntfy topic" --- @@ -19,11 +20,13 @@ A notification for four kinds of item: | **Question** | An agent or conversation asks an AskUserQuestion, or a `pan ask` decision is waiting for you. | | **Approval needed** | A plan waits for approval, or a permission prompt waits in an agent or conversation. | | **Finished** | A work agent ran `pan done` (verification started), or an issue merged. | -| **Failed** | An agent stopped responding, a merge failed, a stalled review escalated, a conflict repair escalated, or free disk space dropped below the alert or critical level (PAN-5093). An agent that ended normally, such as a planning agent after its plan is finalized, does not notify. | +| **Failed** | An agent stopped responding, a merge failed, a stalled review escalated, a conflict repair escalated, or free disk space dropped below the alert level (5 GiB by default, `resources.disk_warn_gb`) or the critical level (2 GiB by default, `resources.disk_critical_gb`). An agent that ended normally, such as a planning agent after its plan is finalized, does not notify. | Each item notifies once, when it first appears. When you answer it and a new question arrives later, that new question notifies again. A dashboard restart -does not replay questions that were already waiting. +does not replay questions or plan approvals that were already waiting a minute +before it started. An agent's permission prompt has no start time, so a +restart notifies it again. The default notification says what kind of item it is and where it is, for example `Question · Refactor the billing module` with the body `Tap to answer.` @@ -63,9 +66,13 @@ A subscription to any other address is refused. ## Set up your phone +This covers the browser phone view. If you use the Overdeck app instead, see +[Phone](/configuration/phone#overdeck-app). + 1. **Reach the dashboard over HTTPS.** Browsers allow push only on a secure - page. `http://localhost` counts, but a phone needs HTTPS. Until the - **Set up Tailscale** action ships, run this on the machine: + page. `http://localhost` counts, but a phone needs HTTPS. Select + **Set up Tailscale** in Settings → Anywhere, or run `pan tailscale setup`. + To do it by hand, run this on the machine: ```bash tailscale serve --bg 3011 @@ -74,20 +81,24 @@ A subscription to any other address is refused. Then open the `https://<machine>.<tailnet>.ts.net` address on the phone. See [Remote access](/configuration/remote-access) for how other devices reach the dashboard. -2. **Pair the phone.** Run `pan pair` and open the link on the phone, or use - **Pair a device** in Settings → Anywhere. See [`pan pair`](/cli/pair). -3. **On iPhone, install the app first.** Safari offers push only to a Home - Screen web app (iOS 16.4 or later). Tap **Share → Add to Home Screen**, then - open Overdeck from the new icon. -4. **Turn it on.** Open Settings → Anywhere → **Phone notifications** and tap +2. **Pair the phone.** On the machine, open Settings → Anywhere → **Set up a + phone** → **Browser on the phone** and follow its steps; see + [Phone](/configuration/phone). On iPhone, add the app to the Home Screen + first (Safari offers push only to a Home Screen web app, iOS 16.4 or later) + and pair inside the installed app, because it cannot use a pairing made in + Safari. You can also run `pan pair` and open its link; see + [`pan pair`](/cli/pair). +3. **Turn it on.** Open Settings → Anywhere → **Phone notifications** and tap **Turn on notifications**, then allow notifications when the browser asks. - Once the phone shell at `/m` ships, the same control is in its header. -5. **Send a test.** Tap **Send test**. The phone should show + In the browser phone view (`/m`), the same control is in the banner below + the header and in Settings (the gear in the header). +4. **Send a test.** Tap **Send test**. The phone should show `Overdeck test notification` within a few seconds. ## Configuration -Push is on by default; subscribing a device is the opt-in. Every key is +Push is on by default; subscribing a device is the opt-in. The block goes in +`~/.overdeck/config.yaml`. Every key is optional. This is the full block with its defaults (the `ntfy` part is an example; it is off unless you set it): @@ -107,9 +118,9 @@ push: | Key | Default | Effect | | --- | --- | --- | -| `enabled` | `true` | `false` stops every push and the conversation scan. | +| `enabled` | `true` | `false` stops every push except **Send test**, and stops the conversation scan. | | `events` | all four | Which kinds notify. Unknown entries are ignored. | -| `includePreview` | `false` | Adds the first question text (or the plan's first line), cut to 140 characters, to Web Push notifications. Never sent to ntfy. | +| `includePreview` | `false` | Adds the first question text (or the plan's first line), cut to 140 characters, to Web Push and Overdeck app notifications. Never sent to ntfy. | | `webpush.subject` | `https://overdeck.ai` | The VAPID contact URL. Apple rejects values that are not `https:` or `mailto:`. | | `ntfy.*` | off | See below. | @@ -161,7 +172,7 @@ In the app's Settings, below the Notifications switch: Your machine applies pause and the muted types before sealing a notification, so a filtered notification never reaches connect.overdeck.ai, Apple or Google -at all — it is simply not sent. **Send test** always arrives, pause or no +at all: it is simply not sent. **Send test** always arrives, pause or no pause, because it is your own check that the pipe works. A machine only applies settings it has received: it must run a version that @@ -208,7 +219,7 @@ else: no titles, no conversation text, no machine names. metadata, such as this phone's registration token, the message priority and when it was sent. - **When a notification cannot be opened**, the phone shows - "Overdeck — Something needs you" instead. + "Overdeck · Something needs you" instead. - **Tapping a notification** opens the machine and the screen it came from. A notification from a machine this phone is no longer paired with opens the machine list. A notification tapped while signed out waits until you sign in. @@ -228,16 +239,19 @@ else: no titles, no conversation text, no machine names. Overdeck can publish to an ntfy topic as well as, or instead of, Web Push. An ntfy server sees what you publish in plain text, so Overdeck sends it -**titles only**: the kind plus the issue id, or the words `a conversation`. +**titles only**: the kind plus the issue id, or the words `a conversation`. A +low-disk alert sends its own title, such as `Disk low · 3.2 GiB free`. Conversation titles, question text and previews never reach ntfy. - **Treat the topic name as a secret.** Anyone who knows it can subscribe to it. Use an unguessable topic, such as `deck-` followed by 16 or more random - characters. + characters. The topic must match `^[A-Za-z0-9_-]{1,64}$`; anything else shows + "topic must match ..." in the panel. - **Use a publish token** (`token`) so nobody else can post to your topic. - **Prefer a self-hosted server**, so the titles never leave your network. - Set `clickBaseUrl` to the HTTPS address of your dashboard if tapping the - ntfy notification should open it. + ntfy notification should open it. `url` must be an `http:` or `https:` + address. ## Privacy @@ -286,12 +300,14 @@ that linked machine's list, so open that machine to see its items. **There is no Turn on notifications button.** The panel explains why in its place: -- *Open this dashboard over HTTPS* — the page is not a secure context. Use the +- *Open this dashboard over HTTPS*: the page is not a secure context. Use the Tailscale Serve address, or `http://localhost` on the machine itself. -- *On iPhone, add Overdeck to your Home Screen* — Safari tabs cannot receive +- *On iPhone, add Overdeck to your Home Screen*: Safari tabs cannot receive push. Install the app and open it from the Home Screen icon. -- *Notifications are blocked for this site* — allow notifications for the +- *Notifications are blocked for this site*: allow notifications for the dashboard's address in the browser's site settings. +- *This browser cannot receive push notifications*: the browser has no + service worker or Push API support (outside iPhone). **The test sends, but nothing arrives.** Check the phone's notification settings for the browser or the installed app, and turn off Focus or Do Not @@ -301,6 +317,11 @@ Disturb. On Android, check that battery saving does not restrict the browser. `410`, the subscription has expired or the browser removed it, so Overdeck deletes it. Tap **Turn on notifications** on that device again. -**Notifications stopped after many failures.** The panel shows a failure count -for each device. Other `4xx` answers count as failures; a successful send -clears the count. +**A device shows failures.** The panel shows a failure count +for each device. Other `4xx` answers and network errors count as failures. +Overdeck keeps sending to the device, and a successful send clears the count. +If the count keeps growing, select **Remove** and tap **Turn on notifications** +on that device again. + +Still stuck? Ask in the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or open a +[GitHub issue](https://github.com/eltmon/overdeck/issues). From 54e369361a5b9f45c2d9d144cf10743661b91ac2 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:26:56 -0500 Subject: [PATCH 77/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 7065b4a5d51..01901f90882 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:24:33.726Z", + "updated": "2026-11-19T04:26:56.130Z", "gitState": {}, "decisions": [], "hazards": [], @@ -570,9 +570,26 @@ "doneAt": "2026-11-19T04:24:25.756Z" }, "audit-push": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:24:33.726Z" + "claimedAt": "2026-11-19T04:24:33.726Z", + "doneAt": "2026-11-19T04:26:56.129Z" + }, + "audit-push.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:26:56.129Z" + }, + "audit-push.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:26:56.129Z" + }, + "audit-push.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:26:56.129Z" + }, + "audit-push.ac4": { + "status": "completed", + "doneAt": "2026-11-19T04:26:56.129Z" } } } From e5357815c88cb1f73514c6d1a4abc2a8fcb1f9dc Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:27:05 -0500 Subject: [PATCH 78/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index 01901f90882..b5f7f551b38 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:26:56.130Z", + "updated": "2026-11-19T04:27:05.917Z", "gitState": {}, "decisions": [], "hazards": [], @@ -590,6 +590,11 @@ "audit-push.ac4": { "status": "completed", "doneAt": "2026-11-19T04:26:56.129Z" + }, + "validate-and-pr-body": { + "status": "in_progress", + "claimedBy": "agent-pan-5500", + "claimedAt": "2026-11-19T04:27:05.917Z" } } } From 61691790a81dc064fc0f0ce256895ec4a9ec783f Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:30:13 -0500 Subject: [PATCH 79/80] docs: validate the Anywhere docs group and draft the PR body MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Ran the WI-Z1 group validators (dash rule, stale "next release" check, frontmatter check, help-link check, lint:docs, mint validate, mint broken-links) over all 21 Overdeck Anywhere pages after every page item landed. Every check passes; no page needed a fix in this commit. Drafted the PR body below for appending to the PR after `pan done`. ## Pages - [x] anywhere.mdx: fixed the Note, Plans and account claims (lines 1-173, Appendix A rows 1-14, O2); dated the shipped table and Roadmap (rows 15-44); fixed the pricing reasoning and added Get help (rows 45-48) - [x] configuration/session-vault.mdx: removed stale release notes, limited harness claims to Claude Code and Codex (Appendix J) - [x] configuration/remote-access.mdx: removed stale notes and the closed-issue roadmap, fixed the descriptor sample and the scope table (Appendix N) - [x] configuration/linked-machines.mdx: fixed the link-request, SSH, Fly and remote-control claims (lines 1-425, Appendix C rows 1-7,17,18); fixed fleet versions, --machine fly and placement output, added every Missing bullet (lines 426-716, rows 8-15) - [x] configuration/shared-sessions.mdx: dated the release, fixed harness and terminal claims (Appendix O) - [x] configuration/triggers.mdx: dated the release, fixed rate-limit, Funnel and inbox claims (Appendix Q) - [x] configuration/tailscale.mdx: fixed the setup steps, stored-state claim and machine-link note (Appendix L) - [x] configuration/mcp.mdx: fixed the harness list, tool parameters and agent-only routes (lines 1-461, Appendix G rows 1-12); fixed provisioning tables, scopes and Fleet reach, added Get help (lines 461-782, rows 13-24) - [x] configuration/bots.mdx: fixed default access, connector files and troubleshooting (Appendix S) - [x] configuration/phone.mdx: described both phone setups, removed transitional ship notes (Appendix T) - [x] configuration/push-notifications.mdx: removed stale ship notes, fixed config and failure behavior (Appendix U) - [x] cli/vault.mdx: described the shipped dashboard features, fixed save, exclude and status (Appendix K) - [x] cli/pair.mdx: replaced the stale release note, fixed error texts (Appendix E) - [x] cli/tailscale.mdx: fixed status output and exit cases, added missing errors (Appendix M) - [x] cli/account.mdx: fixed base URL, failure messages, JSON output and the token file (Appendix B) - [x] cli/share.mdx: fixed messages, the join URL and token-mint behavior (Appendix P) - [x] cli/devices.mdx: removed the stale release note, covered paired phones (Appendix F) - [x] cli/machines.mdx: corrected error remedies, reboot timing, Update all and directory output (Appendix D) - [x] cli/token.mdx: fixed list scope, revoke refusal and the internal format-version field (Appendix I) - [x] cli/mcp.mdx: corrected refusal kinds, URL variables, the Hermes key and relay advice (Appendix H) - [x] cli/triggers.mdx: dated the release, corrected inbox, JSON and remove behavior (Appendix R) ## Validation Step 1, dash loop over all 21 pages (`grep -HnP '[\x{2013}\x{2014}]'`): no output. Step 5, `npm run lint:docs`: ``` docs lint passed (88 docs files, 100 published pages, 3 changelog entries) ``` Step 6, `npx -y mint@4.3.49 validate` (run from the repo root): `success build passed`, `success passed with 23 warnings`, all 23 `duplicate-h1` (first heading repeats the frontmatter title), pre-existing across the repo including `configuration/phone.mdx` (kept per NFR-2: the H1 is not removed). None are new. `npx -y mint@4.3.49 broken-links --check-anchors`: `found 3 broken links in 2 files`, both outside the Anywhere group and pre-existing on `origin/main` (confirmed with `git show origin/main:<file>`): - `features/skills.mdx` → `/cli/core-commands#pan-skill-creator`, `/cli/core-commands#pan-subagent-creator` - `guides/docker-setup.mdx` → `/reference/troubleshooting#slow-vitereact-frontend-with-multiple-workspaces` Also verified: `tr '\n' ' ' | grep -c 'next release'` is 0 for all 21 pages, and `grep -L 'discord.gg/ZpHE2ZTv5P'` over the 21 pages prints nothing (every page ends with a help section). ## Follow-ups **anywhere.mdx** 1. Confirm whether production billing is on; if so, rows 1, 5, 6, 14 and 44 should say the paid tiers are on sale, and `.pan/notes/held-changelog/pan-4294.md` should move back to `changelog.d/`. 2. The dashboard Account card cannot show a paid plan: `AccountPlan` is `'free' | 'tester'` only, so a subscriber's `planLabel` falls through to "Shows when overdeck.ai is reachable"; the card also always prints "Paid plans are invite-only for now." 3. The account page tells lapsed users to run `pan vault migrate`, which does not exist. 4. The dashboard's Add 50 GB link opens `overdeck.ai/anywhere`, which has no top-up product yet. 5. A tester who subscribes without the relay loses the relay (paid access wins over the tester grant). 6. The founding-price window is worded as "90 days after the Anywhere release"; the real end is the operator's `FOUNDING_ENDS_AT`, independent of the page's dates. 7. Expired invite: the account page computes the plan from the grant row even after it expires, but the directory uses only an active grant, so a lapsed subscriber can see "Tester" on the page while held to free limits. 8. The free plan is effectively unreachable for new invitees: no admin path sets `grants.entitlement = 'free'`. **configuration/linked-machines.mdx** 9. Two `### Gauntlet lanes` headings (Fly and lane-placement sections) collide on slug; consider renaming one. 10. `# Linked machines` repeats the frontmatter title (Mintlify already renders the title as H1). 11. `docs/ANYWHERE-ARCHITECTURE.md` was not used as proof for this page, per the brief. **cli/machines.mdx** 12. Code bug: `pan machines add-ssh` maps the SSH `auth-failed` error (401) to the internal-token-rejected message, because its status collides with `call()`'s 401 check. Fix: use a different status for `auth-failed`, or have `call()` read the body's error code first. 13. `pan machines who` and `pan machines add-project` do not map a 401 to the internal-token message either; minor inconsistency with the same root cause. **cli/devices.mdx** 14. Offline `pan devices revoke` matches only `kind === 'device'`, while the server also accepts phones and legacy no-`kind` records; a legacy browser device is reported as unknown offline. **configuration/mcp.mdx** 15. A project MCP server literally named `semgrep` gets a misleading "reserved name" warning, since `semgrep` is also a reserved server name. 16. Grok Build's gain of the `overdeck` MCP server comes from capability spreads (`GROK_CAPABILITIES` extends `OPENCODE_CAPABILITIES`), not an explicit decision; worth confirming with the harness owner that this is intended. **configuration/session-vault.mdx** 17. The page repeats its frontmatter title as `# Session Vault` (same pattern on `configuration/tailscale.mdx` and `cli/tailscale.mdx`). 18. `resume.ts` keeps an unreachable markdown-digest fallback path for harnesses no save path can produce; either drop it or document why it stays. **configuration/tailscale.mdx** 19. `TailscalePeersPanel.tsx` still renders stale UI text ("Linking machines arrives with machine links (#4645)") although machine links shipped in v0.73.0. 20. PAN-1254 (userspace Tailscale live check) still hard-gates `USERSPACE_MODE_AVAILABLE = false`; no tracker call checks whether it has since passed. **configuration/remote-access.mdx** 21. `LOOPBACK_WARNING` in `pairing-link.ts` still tells users to edit `OVERDECK_TRUSTED_ORIGINS`; the pair dialog's **Add to trusted addresses** (no restart needed) is now the easier path. CLI wording only. 22. `routes/anywhere.ts`'s comment says "Any dashboard credential may read it" for the status route, but the gate actually requires `admin` for scoped tokens; fix the comment or add a `read:state` route-scopes row. **configuration/shared-sessions.mdx** 23. **Share this conversation** is offered for non-Claude conversations, and viewers then only see "transcript not available"; the menu item could check the harness first, or the dialog could warn before **Create link**. 24. `docs/SHARED-SESSIONS.md` is a full service-design doc, not a pointer, contrary to how the audit brief described it. **configuration/triggers.mdx / cli/triggers.mdx** 25. `pan triggers remove` does not delete the trigger's overdeck.ai inbox, so the inbox keeps accepting events (202) for a trigger that no longer exists; the machine silently acks them. Fix: route `remove` through the dashboard when the record has an inbox, or reconcile orphan inbox ids server-side. 26. The dashboard's DELETE route comment says "offline, the inbox expires unused", but the Worker only expires individual events, never inbox rows. 27. A read-only (pulled) conversation target answers `503` forever instead of `410`, so senders retry indefinitely. **configuration/bots.mdx** 28. Stale version pins: `integrations/grok-bot/mcp.json` pins `@overdeck/core@0.77.0`, and `integrations/grok-build/scripts/run-mcp.sh` defaults to `0.74.0`; current release is 0.89.1. 29. The Connect a bot dialog still offers the Tailscale reach for Grok Build, although it does not work yet ([#5029](https://github.com/eltmon/overdeck/issues/5029)). 30. The inbox checkbox's visibility gate relies on the directory sending every paid plan as `tester`; works today but is fragile if that convention changes. **configuration/phone.mdx** 31. The Overdeck app tab's **App Store** button opens `overdeck.ai/configuration/phone-app`, which has no corresponding doc page or redirect and 404s. Point it at `/configuration/phone` or add a redirect. 32. The **Google Play** button opens the public store listing, but the app is only on the internal testing track, so the listing is not public for non-testers yet. 33. Step 3 of the browser-phone setup shows "On" automatically once a trusted HTTPS address exists, without explaining why; low priority. **configuration/push-notifications.mdx** 34. Likely bug: after a dashboard restart, an agent's pending permission prompt (which has no start time) notifies again instead of being treated as already-primed; untested in the current suite. 35. The ntfy `Click` header includes the conversation name in its URL, which may contradict the page's "conversation titles never reach ntfy" claim when the name itself reads like a title; worth checking whether user-named conversations leak through. 36. An agent that stops responding with no issue gets the public title `Failed · a conversation`, which is misleading for an agent; consider `Failed · an agent`. 37. Low-disk notifications intentionally put the free-GiB figure in the ntfy title, which looks like it contradicts the "titles only: kind plus issue id" rule; the classifier's own comment implies otherwise and could be updated. **Outside the group (pre-existing on `origin/main`, not fixed here)** 38. `features/skills.mdx` links `/cli/core-commands#pan-skill-creator` and `#pan-subagent-creator`, both broken. 39. `guides/docker-setup.mdx` links `/reference/troubleshooting#slow-vitereact-frontend-with-multiple-workspaces`, broken. 40. 23 `duplicate-h1` warnings across the docs tree (including `configuration/phone.mdx`) predate this issue; NFR-2 keeps the repeated H1 intentionally for the Anywhere pages, so these are cosmetic only. Item: validate-and-pr-body Item: validate-and-pr-body.ac1 Item: validate-and-pr-body.ac2 Item: validate-and-pr-body.ac3 Item: validate-and-pr-body.ac4 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Overdeck-Agent: agent-pan-5500 From 52026b85384c0528e2021c04758a878f23e6ce00 Mon Sep 17 00:00:00 2001 From: "overdeck-agent[bot]" <4205044+overdeck-agent[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:30:37 -0500 Subject: [PATCH 80/80] chore(workspace): plan artifacts for PAN-5500 Overdeck-Agent: agent-pan-5500 --- .pan/continues/PAN-5500.xbrief.json | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.pan/continues/PAN-5500.xbrief.json b/.pan/continues/PAN-5500.xbrief.json index b5f7f551b38..358090f56bb 100644 --- a/.pan/continues/PAN-5500.xbrief.json +++ b/.pan/continues/PAN-5500.xbrief.json @@ -2,7 +2,7 @@ "version": "1", "issueId": "PAN-5500", "created": "2026-11-19T03:34:33.510Z", - "updated": "2026-11-19T04:27:05.917Z", + "updated": "2026-11-19T04:30:37.690Z", "gitState": {}, "decisions": [], "hazards": [], @@ -592,9 +592,26 @@ "doneAt": "2026-11-19T04:26:56.129Z" }, "validate-and-pr-body": { - "status": "in_progress", + "status": "completed", "claimedBy": "agent-pan-5500", - "claimedAt": "2026-11-19T04:27:05.917Z" + "claimedAt": "2026-11-19T04:27:05.917Z", + "doneAt": "2026-11-19T04:30:37.689Z" + }, + "validate-and-pr-body.ac1": { + "status": "completed", + "doneAt": "2026-11-19T04:30:37.689Z" + }, + "validate-and-pr-body.ac2": { + "status": "completed", + "doneAt": "2026-11-19T04:30:37.689Z" + }, + "validate-and-pr-body.ac3": { + "status": "completed", + "doneAt": "2026-11-19T04:30:37.689Z" + }, + "validate-and-pr-body.ac4": { + "status": "completed", + "doneAt": "2026-11-19T04:30:37.689Z" } } }