@gavin-hu/my-pi-agent 0.18.0 → 0.20.0

package/lib/web/markup.ts

@@ -8,6 +8,7 @@
 
 import { escapeHtml } from "../escape.ts";
 import { THEME_JS_PATH } from "./runtime.ts";
+import { WEB_THEME_TOKENS } from "./tokens.ts";
 
 /** Options for {@link docHead}. */
 export interface DocHeadOptions {
@@ -17,6 +18,29 @@ export interface DocHeadOptions {
 	css: string;
 }
 
+/**
+ * A page's browser-tab title: `<page> · <subject> · <count>`.
+ *
+ * One convention across the served pages, so a strip of tabs reads as one product. The
+ * page's name comes first, lowercase and the same word its header's `brandLockup`
+ * carries; then what the page is showing; then the count a reader opens the tab for. A
+ * part the page does not have is left out rather than drawn empty, so a board with
+ * nothing open reads `board · my-pi-agent` and a plan reads `plan review · <its title>`.
+ */
+export function tabTitle(product: string, subject?: string, count?: string): string {
+	const kept = [product, subject, count];
+	return kept.filter((part) => part !== undefined && part !== "").join(" · ");
+}
+
+/**
+ * The same body, as the browser receives it.
+ *
+ * The board's count is live, so its tab is repainted on every frame and this rule has to
+ * cross into the bundle. It is written as concatenation with no backtick and no
+ * interpolation, because the bundle is a template the source is spliced into.
+ */
+export const TAB_TITLE_JS = String(tabTitle);
+
 /**
  * The shared document head: charset, viewport, colour scheme, title, the page
  * CSS, and the pre-paint theme bootstrap. The body and its scripts stay with
@@ -27,17 +51,80 @@ export function docHead(options: DocHeadOptions): string {
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="color-scheme" content="dark light">
 <title>${escapeHtml(options.title)}</title>
+${markIcon()}
 <style>${options.css}</style>
 <script src="${THEME_JS_PATH}"></script>`;
 }
 
+/**
+ * The mark's blocks: `█▀█` over `█▀ █`, as `[x, height]` per row in a 4x2 grid.
+ *
+ * One shape, three places — the header lockup, the tab icon, and the TUI header's
+ * half-blocks — so it is written once. The rows differ: the top fills x=2, the bottom
+ * leaves it empty and fills x=3, which is what makes the mark read as two glyphs.
+ */
+const MARK_ROWS: ReadonlyArray<{ group: "top" | "bottom"; rects: ReadonlyArray<readonly [number, number]> }> = [
+	{
+		group: "top",
+		rects: [
+			[0, 1],
+			[1, 0.5],
+			[2, 1],
+		],
+	},
+	{
+		group: "bottom",
+		rects: [
+			[0, 1],
+			[1, 0.5],
+			[3, 1],
+		],
+	},
+];
+
+/** One row of the mark, as `<rect>`s starting at `y`. */
+function markRowRects(row: (typeof MARK_ROWS)[number], y: number): string {
+	return row.rects.map(([x, height]) => `<rect x="${x}" y="${y}" width="1" height="${height}"/>`).join("");
+}
+
+/**
+ * The mark as a standalone SVG, in one appearance's colours.
+ *
+ * A favicon is its own document: it cannot read the page's tokens, so the fills are
+ * resolved here from the same palette the page paints with, and each appearance gets
+ * its own icon.
+ */
+function markSvg(fills: { top: string; bottom: string }): string {
+	const rows = MARK_ROWS.map((row, index) => `<g fill="${fills[row.group]}">${markRowRects(row, index)}</g>`);
+	return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 4 2">${rows.join("")}</svg>`;
+}
+
+/**
+ * The tab icon: the mark, in the appearance the reader's system is in.
+ *
+ * The dark icon is the plain `rel="icon"` — the page paints dark at `:root`, and a
+ * browser that reads no `media` query on an icon keeps it. The light one is the
+ * override, so a light tab does not carry a mark tuned for a dark one.
+ */
+export function markIcon(): string {
+	const dark = encodeURIComponent(
+		markSvg({ top: WEB_THEME_TOKENS.dark["--accent"], bottom: WEB_THEME_TOKENS.dark["--warn"] }),
+	);
+	const light = encodeURIComponent(
+		markSvg({ top: WEB_THEME_TOKENS.light["--accent"], bottom: WEB_THEME_TOKENS.light["--warn"] }),
+	);
+	return `<link rel="icon" type="image/svg+xml" href="data:image/svg+xml,${dark}">
+<link rel="icon" type="image/svg+xml" media="(prefers-color-scheme: light)" href="data:image/svg+xml,${light}">`;
+}
+
 /**
  * The Bytefly nameplate: the two-tone half-block mark, the `bytefly` wordmark,
  * and the product name. The mark mirrors the TUI header (`█▀█` / `█▀ █`), drawn
  * as a 4x2 grid so the accent and warning rows stay crisp at any zoom.
  */
 export function brandLockup(product: string): string {
-	return `<span class="bf-brand"><svg class="bf-mark" viewBox="0 0 4 2" aria-hidden="true"><g class="bf-mark__top"><rect x="0" y="0" width="1" height="1"/><rect x="1" y="0" width="1" height="0.5"/><rect x="2" y="0" width="1" height="1"/></g><g class="bf-mark__bottom"><rect x="0" y="1" width="1" height="1"/><rect x="1" y="1" width="1" height="0.5"/><rect x="3" y="1" width="1" height="1"/></g></svg><span class="bf-wordmark">bytefly</span><span class="bf-context">${escapeHtml(product)}</span></span>`;
+	const rows = MARK_ROWS.map((row, index) => `<g class="bf-mark__${row.group}">${markRowRects(row, index)}</g>`);
+	return `<span class="bf-brand"><svg class="bf-mark" viewBox="0 0 4 2" aria-hidden="true">${rows.join("")}</svg><span class="bf-wordmark">bytefly</span><span class="bf-context">${escapeHtml(product)}</span></span>`;
 }
 
 /**

package/lib/web/names.ts

@@ -0,0 +1,42 @@
+/**
+ * A page's class names, as a table a bundle can carry.
+ *
+ * A browser page in this package is a TypeScript document plus a client script held in
+ * a template literal, so the two halves cannot import from each other: a class name is a
+ * string in one and a string in the other, and a name built by concatenation
+ * (`"board-card__reason" + kind`) cannot be found by reading either. A table fixes both:
+ * the document and the bundle read the same values, and a test can compare the set the
+ * page wears with the set its stylesheet draws.
+ *
+ * The bundle carries the table as **source**, so every value must survive being spliced
+ * into a template literal: a backtick would end the string, and `${` would interpolate
+ * at build time. `KEBAB` is that contract, and {@link namesScript} throws rather than
+ * trusting a caller — a bad name is a build error here, not a mystery on the page.
+ */
+
+/** A page's vocabulary: a key per thing it dresses, and the class it wears. */
+export type ClassNames = Readonly<Record<string, string>>;
+
+/** What a class name may be: lowercase, hyphenated, and nothing a script could misread. */
+export const KEBAB = /^[a-z][a-z0-9_-]*$/;
+
+/** What the global the table is bound to may be: a JavaScript identifier, and nothing else. */
+export const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/** The declared global the table is bound to in a page's bundle. */
+export const NAMES_GLOBAL = "N";
+
+/**
+ * The table as one script statement, for a client bundle to start with.
+ *
+ * `JSON.stringify` is the serializer because the values are already strings that pass
+ * {@link KEBAB}; the check before it is what makes that true, and its message names the
+ * offending key and value so the fix is obvious.
+ */
+export function namesScript(table: ClassNames, global: string = NAMES_GLOBAL): string {
+	for (const [key, value] of Object.entries(table)) {
+		if (!KEBAB.test(value)) throw new Error(`the class name for "${key}" is not a kebab-case name: "${value}"`);
+	}
+	if (!IDENTIFIER.test(global)) throw new Error(`"${global}" is not a name a script can declare`);
+	return `var ${global} = ${JSON.stringify(table)};`;
+}

package/lib/web/runtime.ts

@@ -123,9 +123,15 @@ export function dialogScript(options: DialogOptions): string {
   // A button inside a closed dialog has no boxes, so the rects are the test that
   // survives a hidden attribute, a collapsed panel, and a stylesheet swap alike.
   function focusables() {
-    return Array.prototype.filter.call(dialog.querySelectorAll('${FOCUSABLE}'), function (node) {
+    var nodes = Array.prototype.filter.call(dialog.querySelectorAll('${FOCUSABLE}'), function (node) {
       return node.getClientRects && node.getClientRects().length > 0;
     });
+    // A panel that names itself focusable is where focus lands on open, so the close
+    // button is not the first thing a dialog says with its ring. It stays first in the
+    // list, which is what keeps Shift+Tab wrapping inside instead of escaping the scrim.
+    var panel = dialog.querySelector('[role="dialog"][tabindex]');
+    if (panel && panel.getClientRects && panel.getClientRects().length > 0) nodes.unshift(panel);
+    return nodes;
   }
   function toggle(force) {
     var open = force === undefined ? dialog.hidden : force;

package/lib/web/tokens.ts

@@ -21,8 +21,8 @@ interface ThemeJson {
 const DARK = darkTheme as unknown as ThemeJson;
 const LIGHT = lightTheme as unknown as ThemeJson;
 
-/** Web custom property -> Bytefly theme var. `--accent-soft`, `--on-accent`, `--scrim`,
- * and `--shadow` are derived, so no appearance-only colour enters the kit. */
+/** Web custom property -> Bytefly theme var. `--accent-soft`, `--raised`, `--on-accent`,
+ * `--scrim`, and `--shadow` are derived, so no appearance-only colour enters the kit. */
 const VAR_TOKENS: ReadonlyArray<readonly [string, string]> = [
 	["--canvas", "canvas"],
 	["--surface", "canvasSubtle"],
@@ -73,6 +73,16 @@ function resolve(theme: ThemeJson, value: string | number): string {
 	return theme.vars[value] ?? value;
 }
 
+/** `#rrggbb` mixed toward another colour: `t` of the way from `a` to `b`. */
+function mix(a: string, b: string, t: number): string {
+	const channel = (hex: string, at: number): number => Number.parseInt(hex.replace("#", "").slice(at, at + 2), 16);
+	const between = (x: number, y: number): number => Math.round(x + (y - x) * t);
+	const r = between(channel(a, 0), channel(b, 0));
+	const g = between(channel(a, 2), channel(b, 2));
+	const bl = between(channel(a, 4), channel(b, 4));
+	return `#${[r, g, bl].map((value) => value.toString(16).padStart(2, "0")).join("")}`;
+}
+
 /** `#rrggbb` (or `#rgb`) plus alpha -> `rgba(r,g,b,a)`. */
 function rgba(hex: string, alpha: number): string {
 	const raw = hex.replace("#", "");
@@ -94,6 +104,15 @@ function rgba(hex: string, alpha: number): string {
  * lifts a panel off it, so each appearance needs its own alpha rather than the
  * theme's colours.
  */
+/**
+ * How far `--raised` sits above `--surface`: enough to see, not enough to shout.
+ *
+ * The light theme takes a smaller step because its accent is darker: at the dark
+ * step, `--accent` on `--raised` falls to 4.34:1 and the owner chips on a raised row
+ * stop being readable.
+ */
+const RAISED_STEP: Record<"dark" | "light", number> = { dark: 0.06, light: 0.03 };
+
 const OVERLAYS: Record<"dark" | "light", { scrim: string; shadow: string }> = {
 	dark: { scrim: "rgba(0,0,0,.5)", shadow: "0 8px 24px rgba(0,0,0,.4)" },
 	light: { scrim: "rgba(15,23,42,.3)", shadow: "0 8px 24px rgba(15,23,42,.14)" },
@@ -104,6 +123,10 @@ function paletteOf(theme: ThemeJson, appearance: "dark" | "light", accentAlpha:
 	const palette: Record<string, string> = {};
 	for (const [token, name] of VAR_TOKENS) palette[token] = theme.vars[name];
 	palette["--accent-soft"] = rgba(palette["--accent"] ?? "#000000", accentAlpha);
+	// One step above `--surface`, for a block that must read as a plane rather than an
+	// outline: the theme offers only two neutral fills, and a surface one hairline
+	// lighter than the page is what made a dashboard look like a wireframe.
+	palette["--raised"] = mix(palette["--surface"] ?? "#000000", palette["--text"] ?? "#ffffff", RAISED_STEP[appearance]);
 	// A label on the accent fill is the canvas colour: a light blue button takes dark
 	// text, and the same derivation gives white on the light theme's darker blue.
 	palette["--on-accent"] = palette["--canvas"];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.18.0",
-  "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, file-read, check, memory, context, session-bus, wechat, and bytefly.",
+  "version": "0.20.0",
+  "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, file-read, check, memory, context, session-bus, board, team, wechat, and bytefly.",
   "keywords": [
     "pi-package",
     "pi",
@@ -49,6 +49,12 @@
     "excel",
     "read_doc",
     "memory",
+    "board",
+    "cards",
+    "backlog",
+    "team",
+    "handoff",
+    "assign",
     "cross-session",
     "context",
     "compaction",
@@ -74,6 +80,7 @@
   },
   "files": [
     "extensions/**",
+    "docs/extensions/**",
     "lib/**",
     "skills/**",
     "themes/**",
@@ -101,6 +108,8 @@
       "./extensions/file-open/index.ts",
       "./extensions/memory/index.ts",
       "./extensions/context/index.ts",
+      "./extensions/board/index.ts",
+      "./extensions/team/index.ts",
       "./extensions/session-bus/index.ts",
       "./extensions/wechat/index.ts",
       "./extensions/bytefly/index.ts"
@@ -111,7 +120,7 @@
     "themes": [
       "./themes/*.json"
     ],
-    "image": "https://raw.githubusercontent.com/gavin-hu/my-pi-agent/main/assets/chrome.png"
+    "image": "https://raw.githubusercontent.com/gavin-hu/my-pi-agent/main/assets/screens/chrome.png"
   },
   "scripts": {
     "test": "bun test --parallel=4 --timeout 30000",
@@ -127,12 +136,15 @@
     "config:migrate": "bun run scripts/migrate-config.ts",
     "compat:versions": "bun run scripts/peer-versions.ts",
     "bench:render": "bun run scripts/render-bench.ts",
-    "screenshot:file-browse": "bun run scripts/file-browse-shot.ts",
-    "screenshot:plan-flow": "bun run scripts/plan-flow-shot.ts",
-    "screenshot:plan": "bun run scripts/plan-review-shot.ts",
-    "screenshot:tools": "bun run scripts/tool-renderings.ts gallery assets/tool-renderings.png",
-    "screenshot:tool-pngs": "bun run scripts/tool-renderings.ts tools assets/tools",
-    "screenshots": "bun run scripts/screenshots.ts"
+    "screenshot:board": "bun run scripts/shots/board.ts",
+    "screenshot:cards": "bun run scripts/shots/cards.ts",
+    "screenshot:file-browse": "bun run scripts/shots/file-browse.ts",
+    "screenshot:plan": "bun run scripts/shots/plan-review.ts",
+    "screenshot:tools": "bun run tools:render gallery assets/screens/tool-renderings.png",
+    "screenshot:tool-pngs": "bun run tools:render tools assets/tools",
+    "probe:wechat": "bun run scripts/wechat-poll.ts",
+    "screenshots": "bun run scripts/screenshots.ts",
+    "tools:render": "bun run scripts/tools/index.ts"
   },
   "dependencies": {
     "exceljs": "^4.4.0",
@@ -153,15 +165,15 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",
-    "@earendil-works/pi-agent-core": "^1.0.4",
-    "@earendil-works/pi-ai": "^1.0.4",
-    "@earendil-works/pi-coding-agent": "^1.0.4",
-    "@earendil-works/pi-tui": "^1.0.4",
+    "@earendil-works/pi-agent-core": "^1.4.0",
+    "@earendil-works/pi-ai": "^1.4.0",
+    "@earendil-works/pi-coding-agent": "^1.4.0",
+    "@earendil-works/pi-tui": "^1.4.0",
     "@types/bun": "latest",
     "@types/qrcode": "^1.5.5",
     "get-east-asian-width": "^1.6.0",
     "playwright-core": "^1.64.1",
-    "typebox": "^1.3.27",
+    "typebox": "^1.4.3",
     "typescript": "^5.6.0"
   }
 }

package/skills/next/SKILL.md

@@ -16,9 +16,10 @@ The conversation decides where the candidates come from (section 3); the request
 decides only what to ask and where to look.
 
 Two sibling skills, where they are installed, own a narrower question: an audit
-of *where to refactor* is `refactor`, and *what the last tag owes the changelog*
-is `changelog`. When the request is already scoped to one of those, name the
-skill that answers it and hand over, instead of returning a generic list.
+of *where to refactor* is `refactor`, and *whether a document still tells the
+truth* — the changelog, the roadmap, the front door — is `project-docs`. When the
+request is already scoped to one of those, name the skill that answers it and
+hand over, instead of returning a generic list.
 
 A next-steps block that the host draws itself is not this skill's output: that is
 the reply's suggested follow-up, a turn-level hint. This skill inspects state, so

package/skills/project-docs/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: project-docs
+description: "Keep a project's documents true to its tree: a read-only audit of the front door, the roadmap, the contributor path, and the changelog against the code and against each other, then one mode per act that writes — record a changelog bullet in the same commit as the change, curate a release section from the project's own rules, delete a shipped roadmap item and renumber, and sync the README front door. Use when a doc claim looks stale, before a release, or when a change lands owing an entry; prioritisation stays with `next` and structure with `refactor`."
+compatibility: "Bun for scripts/state.ts; git for the roadmap and the audit."
+---
+
+# Keep the docs true to the tree
+
+Goal: the documents a reader trusts — the front door, the plan of record, the record
+of what shipped, and the contributor path — so a claim the tree no longer meets is
+found, and each act that needs writing has one owner. This is a procedure, not a
+second policy: the project's instructions and release document win, and where they
+are silent this file says ask.
+
+A bare `/skill:project-docs` reads and reports. Nothing is written until a mode is
+named.
+
+## Pick the mode
+
+| The words after `/skill:project-docs` | Mode | Owns | Writes | Follow |
+|---|---|---|---|---|
+| nothing | audit | every document, read-only | no | [`references/audit.md`](./references/audit.md) |
+| `changelog` | changelog | the unreleased window of the changelog | yes | [`references/changelog.md`](./references/changelog.md) |
+| `release <version>` | release | one version's section and link refs | yes | [`references/release.md`](./references/release.md) |
+| `roadmap` | roadmap | items, ids, and buckets | yes | [`references/roadmap.md`](./references/roadmap.md) |
+| `readme` | readme | the front door and its mirror | yes | [`references/readme.md`](./references/readme.md) |
+| anything else | refuse, and name the five | — | no | — |
+
+Audit is the default because the skill spans four documents: a bare invocation that
+writes would edit a document nobody asked about.
+
+## Start here
+
+Read [`references/discovery.md`](./references/discovery.md) first, in every mode. It
+finds the project's documents, the version's single source, the changelog's local
+conventions, the roadmap's rules, the check command, and the guards by name. State
+that profile in one paragraph before writing anything; it is how a misread is caught
+in a line instead of in a diff.
+
+For the changelog's mechanical half, run the state script, resolved against this
+skill's own directory:
+
+```bash
+bun <skill>/scripts/state.ts <project-root>
+```
+
+It prints the changelog file it found, the last tag and the commits since it, the
+`[Unreleased]` categories with counts and line numbers, the empty and duplicate
+headings, the scope prefixes in use, and the link refs. That is the state; read the
+diffs for judgement, not for counting. When it finds no changelog, no repository, or no
+Bun to run it with, say so and fall back to discovery by hand. The git commands these
+references give are git's; use the project's VCS where it differs.
+
+## Non-negotiables
+
+1. **Discover, don't impose.** The project's document set, category spelling, scope
+   prefix, bullet shape, item ids, bucket caps, and release procedure are the rules.
+   State the profile in one paragraph, and ask when two sources disagree.
+2. **One bullet per user-visible outcome**, in the same commit as the change. A
+   feature and the bug it fixed before release are one bullet; two observable
+   changes are two.
+3. **A shipped item is deleted here, with its reason, never ticked.** A roadmap that
+   keeps what already landed describes a tree that no longer exists.
+4. **One id per thing, across every document.** A README row, a roadmap item, and a
+   changelog entry that name the same feature use the same name. A mismatch is
+   reported, never renamed.
+5. **A judgement is not a finding.** Positioning, priority, dates, non-goals, and
+   contribution policy are the maintainer's: list them and ask.
+6. **One owner per artefact.** The changelog belongs here; what to do next belongs to
+   the `next` skill; structure belongs to `refactor`.
+
+## Modes
+
+- **Audit** — read-only, five faces: the tree against the docs, the docs against each
+  other, the changelog's commit window, the roadmap's own ids and caps, and the front
+  door's examples. Every finding names the mode that fixes it.
+- **Changelog** — one bullet under the project's category for one user-visible
+  outcome, re-reading the file first. It never decides whether something has already
+  shipped.
+- **Release** — only for a version the user named, and only after the project's
+  release document has been read; everything after moving the entries follows it.
+- **Roadmap** — re-derived from the commits since the last tag rather than from the
+  last tag: shipped items deleted, ids renumbered, every citation and link fixed.
+- **Readme** — the front door's catalog rows, counts, examples, and mirror, kept equal
+  to the tree; deep detail stays in the project's own guides.
+
+## Handover
+
+- **A changelog entry, an audit, or a release** is this skill: do not look for
+  another one.
+- **What to do next** is `next`, where it is installed: it triages loose work and
+  broken promises across the project, and its candidates are not a doc audit's findings.
+- **A structural change to the docs or the code** is `refactor`, where it is installed.
+- **Who may contribute, and how** is a decision for the maintainer: ask, and edit
+  nothing until it is answered.
+
+## Report
+
+Open with the profile in one paragraph, then:
+
+- **Stale** — the claim, `path:line`, the evidence in the tree, and the mode that
+  fixes it.
+- **Missing** — a document, a row, an entry, or an item the project's own rules call
+  for and the tree does not have.
+- **Suggested edit** — the diff or the exact replacement, for the mechanical items
+  only, and never applied until the user says so.
+- **Needs a decision** — one line each: the question, and what it changes.
+
+Nothing found is a valid result, and the whole report may be empty. Say what was
+checked and stop; an audit that invents four entries to look thorough is worse than
+one that finds nothing.
+
+## Quality gate
+
+- The project's own check passes, including any guard on the release window, the
+  documentation's parity, or the roadmap's ids.
+- Every edit names the document and the line, and every bullet names a scope in the
+  project's spelling and a user outcome.
+- No judgement is smuggled into a diff, and the changelog entry is in the change's
+  own commit.
+
+## Stop conditions
+
+- The project has only a README, no roadmap, and no changelog: say so. Whether to
+  adopt one is the maintainer's decision, not an edit.
+- The changelog is generated — by `semantic-release`, `changesets`, `git-cliff`, or a
+  step in the release workflow: the entry lands upstream, in the commit message, a
+  changeset fragment, or the generator's config. Never hand-edit the file.
+- Two sources disagree — two changelogs, a version in two places, a roadmap item the
+  changelog contradicts: ask instead of averaging them.
+- The change would reverse a documented non-goal: it is a decision, and the item is
+  listed rather than written.
+- The request is really triage or a refactor: name the sibling skill and stop.

package/skills/project-docs/references/audit.md

@@ -0,0 +1,131 @@
+# Audit
+
+Read-only. The audit answers one question per claim: is this still true, and if not,
+which mode fixes it? It never edits — not even a typo, not even "while we are here".
+If the user asks for the fixes, finish the report first, then enter the mode it names.
+
+Read [`discovery.md`](./discovery.md) first and open the report with the profile. The
+five faces below are a reading order, not a checklist: a face with no evidence
+produces no findings.
+
+## 1. The tree against the docs
+
+The claims a reader acts on: a catalog row, a limit stated in a package README, a
+default in a configuration table, a roadmap item, a non-goal, a "supported format"
+list. For each, find the code that does it — the registration, the branch, the config
+default — and name where it disagrees.
+
+| Where the claim lives | What falsifies it |
+|---|---|
+| A catalog row or feature bullet | The tool, command, flag, or route no longer registers |
+| A limitations section | The gap was closed, or widened, and the text did not move |
+| A configuration default | The loader's default differs from the table |
+| A roadmap item | The tree already does it (see face 4) |
+| A non-goal | The changelog records the thing being shipped anyway |
+
+## 2. The docs against each other
+
+- **Counts** — a number a doc states about the code (modules, tools, extensions,
+  screens) belongs to the tree. A project that derives it in a test has the count; one
+  that does not is a finding, and the fix is a guard, not a number.
+- **Catalog rows** — every row names a thing that exists; every existing thing the
+  catalog claims to cover has a row. Both directions.
+- **Cross-reference ids** — the same feature named in a front-door row, a roadmap item,
+  and a changelog entry. Report a mismatch; never rename one side to match.
+- **The version** — the source of truth, the newest dated changelog heading, the tag,
+  and any badge, badge-adjacent prose, or install instruction that repeats it.
+- **The mirror** — a translated README carries the original's sections, table rows, and
+  links. A row that exists in one and not the other is a finding even when the prose is
+  deliberately translated.
+- **The contributor path** — the commands `CONTRIBUTING.md` tells a newcomer to run,
+  against the manifest's `scripts` and the CI workflow's steps. A command the docs promise
+  and the manifest does not define is the one stale claim a new contributor hits first,
+  and a step CI runs that the docs never mention is the one they skip.
+
+## 3. The changelog's commit window
+
+Run `scripts/state.ts` (see the skill's *Start here*). It gives the file, the last tag,
+the commits since it, the `[Unreleased]` categories, and the scopes in use.
+
+When discovery says a tool generates the file, the window's entries live in that tool's
+input — the changeset queue, the commit-message convention — so audit those, and report
+a missing fragment rather than a missing bullet.
+
+Read every commit it lists: `git show <sha>` for the diff, or the pull request when the
+repository squashes. A subject line is not enough — `fix bug` and `wip` hide
+user-visible changes, and `feat: rewrite the config loader` is often invisible to users.
+For each commit, decide whether a user can observe it, which bullet covers it, whether
+that bullet's scope is right, and whether a reader of the bullet alone would know what
+changed for them.
+
+| Commit | User-visible | Evidence | Existing entry | Action |
+|---|---|---|---|---|
+| `3f19a02` | yes | `src/load.ts:42` now rejects an unknown key | — | add |
+| `b81c4de` | no | test-only | — | leave |
+| `0ad9f12` | yes | retry limit 3 → 5 | `Changed`: "`api`: retries are now bounded" | update: the bullet never names the limit |
+| `77e0a1e` | unclear | touches the public `--json` shape | — | ask |
+
+`Action` is one of **add** (user-visible, no bullet), **update** (a bullet exists and is
+wrong, unscopeable, or too vague to act on), **leave** (covered, internal, or recorded
+under an older release), or **ask** (the outcome depends on intent the diff cannot show).
+
+Report separately:
+
+- Duplicate `##` or `###` headings — some tools render the second as its own section,
+  and a reader sees half the entries.
+- An empty category heading, or a heading a release guard rejects.
+- An `[Unreleased]` section that is missing or empty while the window contains
+  user-visible changes.
+- An entry for something already shipped under a dated heading: the same outcome twice,
+  which reads as a second change.
+- A stale link reference pointing at an older tag than the newest dated heading — where
+  the file uses link references at all. A generated or non-Keep-a-Changelog file may have
+  none, and the state script reports that absence as a missing reference without it being
+  a defect.
+
+## 4. The roadmap's own ids and caps
+
+Re-derive the window before judging an item: `git log --oneline <last-tag>..HEAD` plus
+the changelog's newest dated heading. A roadmap describes the tree, so work that landed
+but has not shipped is already part of what it should describe.
+
+- An item the tree already does is a deletion, with its reason recorded where the item
+  was.
+- An id used twice, skipped in a sequence, or cited from nowhere the file defines.
+- A bucket over the cap the file states; a bucket that keeps growing stops being a
+  priority.
+- A ledger row whose items all closed, or an open item with no ledger row.
+- A relative link or a `path:line` citation that no longer resolves.
+
+## 5. The front door's examples
+
+- The quickstart command, run as written. A command that no longer exists is a stale
+  promise, and it is the most expensive one because it is the reader's first step.
+- An example that imports, configures, or calls something the code no longer accepts.
+- A screenshot or a recording that shows a surface that has since changed.
+- A link to a guide that moved, a section anchor that was renamed, or a badge whose
+  target is gone.
+
+## Report
+
+Open with the profile, then the four sections from the skill: **Stale**, **Missing**,
+**Suggested edit**, **Needs a decision**. Every stale finding carries the document,
+`path:line`, the evidence in the tree, and the mode that fixes it. Group by the mode
+when there are more than a handful, so the user can act one mode at a time.
+
+Nothing found is a valid result for the whole audit or for any face. Say what was
+checked — the files read, the commands run, the commits examined — and stop. An audit
+that invents findings to look thorough is worse than one that reports none.
+
+## What the audit cannot see
+
+Name these in a closing line instead of guessing:
+
+- Whether a change is user-visible to someone the diff does not show — a default that
+  only matters on one platform, a behavior the docs promised and the tests never
+  covered.
+- Whether a commit message describes what the code does; only the diff does.
+- Whether an item shipped: a merged change to a document is not a release, and only the
+  maintainer knows whether the front door's promise is meant to hold today or next
+  version.
+- Whether a roadmap priority is still right, and whether a non-goal still stands.