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

package/lib/session-tool.ts

@@ -0,0 +1,184 @@
+/**
+ * The `session` tool, as the extensions that are not `session-bus` call it.
+ *
+ * `board` and `team` are the user's surface for the team; the bus is the transport
+ * underneath, and neither may import it (`test/structure.test.ts`). So the one place
+ * that turns a call into a typed answer lives here, next to the tool's name in
+ * `lib/tool-names.ts` — two copies would be two copies of the details-shape
+ * knowledge, and a bus that renamed a field would be broken in one of them.
+ *
+ * There are two transports, and the difference is the context, not the caller's
+ * choice: `join` travels as an in-process request on `pi.events` because a *command*
+ * context has no `ctx.executeTool` — the same constraint `lib/plan-entry.ts` exists
+ * for — while `peers` and `send` are nested tool calls, which only ever run inside a
+ * tool. One function either way, so a caller never has to know which it is holding.
+ *
+ * Every function returns a result and none throws: "the bus is not loaded", "a plan
+ * is open", and "that label is taken" are all answers a caller reports, not reasons
+ * to abandon a board write or a card operation that has nothing to do with the bus.
+ *
+ * This module is the *caller* side only. Reading the bus's records from disk is
+ * `session-roster.ts`, which is what works when the bus is not loaded at all.
+ */
+
+import type { ExtensionAPI, ExtensionContext, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import { messageOf } from "./errors.ts";
+import { watchingOf } from "./session-roster.ts";
+import { SESSION_TOOL } from "./tool-names.ts";
+
+/**
+ * The `session send` text limit, which is also the longest handoff or offer.
+ *
+ * It is copied from the bus's protocol rather than imported — the dependency runs one
+ * way — and it lives here so `team` and `board` clip to one number instead of two.
+ */
+export const MAX_MESSAGE_TEXT = 4_000;
+
+/** Whether a session is listening for mail, and whether it raises a turn. */
+export interface Watching {
+	armed: boolean;
+	wake: boolean;
+}
+
+/** One session the bus lists. */
+export interface Peer {
+	id: string;
+	label: string;
+	/** Absent when the record does not say, which is not the same as "not listening". */
+	listening?: boolean;
+}
+
+/** What a join did: the label it landed on, and whether mail will reach the session. */
+export type JoinResult = { ok: true; label: string; watching: Watching } | { ok: false; error: string };
+
+/** EventBus channel on which a caller asks `session-bus` to join the team for it. */
+export const TEAM_JOIN_REQUEST = "my-pi-agent/team-join/request";
+
+/** What a caller sends on {@link TEAM_JOIN_REQUEST}. */
+export interface TeamJoinRequest {
+	/** The caller's context; the bus starts and names through it. */
+	ctx: ExtensionContext;
+	/** What to join as and how to listen. */
+	input: { label?: string; wake?: boolean; listen?: boolean };
+	/** Called once, when the bus has answered. */
+	respond(result: JoinResult): void;
+}
+
+/** What a send did. */
+export type SendResult = { ok: true; delivered: string[] } | { ok: false; error: string };
+
+/** One nested call's answer: the details on success, the sentence on failure. */
+type Answer = { details: Record<string, unknown> } | { error: string };
+
+/**
+ * Call the `session` tool once.
+ *
+ * A nested call reports failure in its result rather than by rejecting; a rejection
+ * is still caught, because a bus that is not registered at all throws before the
+ * tool runs and the caller deserves the sentence rather than an exception.
+ */
+async function call(ctx: ExtensionToolContext, args: Record<string, unknown>): Promise<Answer> {
+	const outcome = await ctx.executeTool(SESSION_TOOL, args).catch((error: unknown) => ({
+		isError: true as const,
+		result: { content: [{ type: "text", text: messageOf(error) }], details: undefined },
+	}));
+	if (outcome.isError) return { error: nestedMessage(outcome.result) };
+	const details = outcome.result.details;
+	return { details: typeof details === "object" && details !== null ? (details as Record<string, unknown>) : {} };
+}
+
+/** The message a failed nested call carries, or a sentence that says only that it failed. */
+function nestedMessage(result: { content?: Array<{ type: string; text?: string }> } | undefined): string {
+	const text = result?.content?.find((block) => block.type === "text")?.text;
+	return text !== undefined && text !== "" ? text.replace(/^Error:\s*/, "") : "the session bus did not answer.";
+}
+
+/**
+ * How an extension joins the team, whatever kind of context it is holding.
+ *
+ * Two extensions ask — `board` when the page opens or a card is worked, `team` for
+ * `/team join` — and both hold a command or a tool context, so the request is the one
+ * transport that works from either.
+ */
+export interface TeamJoin {
+	/** Join the team, naming this session when `label` is given. Never throws. */
+	join(ctx: ExtensionContext, label?: string): Promise<JoinResult>;
+}
+
+/** The production join, bound to one extension's `pi`. */
+export function createTeamJoin(pi: Pick<ExtensionAPI, "events" | "getAllTools">): TeamJoin {
+	return {
+		join: (ctx, label) => join(pi, ctx, label === undefined ? {} : { label }),
+	};
+}
+
+/**
+ * Join the team: on the bus, named when a label is given, and listening for mail.
+ *
+ * One call for all three, because that is one act — see `join` in
+ * `extensions/session-bus` — and one transport for both kinds of caller: the request
+ * travels on `pi.events` and the bus answers it.
+ *
+ * With no bus loaded there is no listener, so the answer is the sentence the caller
+ * reports rather than a promise that never settles: the `session` tool's presence is
+ * the same check `lib/plan-entry.ts` makes, and the listener always answers.
+ */
+export async function join(
+	pi: Pick<ExtensionAPI, "events" | "getAllTools">,
+	ctx: ExtensionContext,
+	input: { label?: string; wake?: boolean; listen?: boolean } = {},
+): Promise<JoinResult> {
+	if (!pi.getAllTools().some((tool) => tool.name === SESSION_TOOL)) {
+		return { ok: false, error: "the session bus is not loaded" };
+	}
+	return new Promise<JoinResult>((resolve) => {
+		let settled = false;
+		const respond = (result: JoinResult): void => {
+			if (settled) return;
+			settled = true;
+			resolve(result);
+		};
+		pi.events.emit(TEAM_JOIN_REQUEST, { ctx, input, respond } satisfies TeamJoinRequest);
+	});
+}
+
+/**
+ * Every session the bus lists, or `undefined` when it cannot answer.
+ *
+ * Named `listPeers` rather than `peers` so it cannot be mistaken for a caller's own
+ * formatting helper — `wechat`'s doctor has one — and a caller reads the verb.
+ *
+ * A caller renders "the record does not say" differently from "nobody is here", so a
+ * failed read is not an empty list.
+ */
+export async function listPeers(ctx: ExtensionToolContext): Promise<Peer[] | undefined> {
+	const answer = await call(ctx, { action: "status" });
+	if ("error" in answer) return undefined;
+	const status = answer.details.status;
+	if (typeof status !== "object" || status === null) return undefined;
+	const sessions = (status as { sessions?: unknown }).sessions;
+	if (!Array.isArray(sessions)) return undefined;
+	const peers: Peer[] = [];
+	for (const entry of sessions) {
+		if (typeof entry !== "object" || entry === null) continue;
+		const { id, label, watching } = entry as Record<string, unknown>;
+		if (typeof id !== "string" || typeof label !== "string") continue;
+		const state = watchingOf(watching);
+		peers.push({ id, label, ...(state === undefined ? {} : { listening: state.armed }) });
+	}
+	return peers;
+}
+
+/** Send one message, and report the labels a message file was written for. */
+export async function send(
+	ctx: ExtensionToolContext,
+	input: { kind: "handoff" | "event"; to: string; text: string },
+): Promise<SendResult> {
+	const answer = await call(ctx, { action: "send", kind: input.kind, to: input.to, text: input.text });
+	if ("error" in answer) return { ok: false, error: answer.error };
+	const delivered = answer.details.delivered;
+	return {
+		ok: true,
+		delivered: Array.isArray(delivered) ? delivered.filter((label): label is string => typeof label === "string") : [],
+	};
+}

package/lib/tool-names.ts

@@ -4,8 +4,9 @@
  * Tool names are otherwise owned by the extension that registers the tool, and
  * no extension imports another's modules (see this directory's README). When an
  * orchestrating tool calls another extension's tool through `ctx.executeTool`,
- * or reads another extension's registered parameter schema, the shared name
- * lives here so a rename breaks the build on both sides instead of silently
+ * reads another extension's registered parameter schema, lists the name in a
+ * read-only policy, or passes it on a child's `--tools` allowlist, the shared
+ * name lives here so a rename breaks the build on both sides instead of silently
  * disabling the integration.
  */
 
@@ -31,9 +32,31 @@ export const SUBAGENT_TOOL = "subagent";
  */
 export const ASK_USER_QUESTION_TOOL = "ask_user_question";
 
+/**
+ * The `session` tool. `session-bus` registers it, and `team` calls it through
+ * `ctx.executeTool` to send a handoff, so a rename breaks both sides.
+ */
+export const SESSION_TOOL = "session";
+
 /**
  * Parameter on the `subagent` tool that forces every spawned agent to a
  * read-only tool set. Plan mode sets it on every call while planning, and
  * refuses a `subagent` whose schema does not declare it.
  */
 export const SUBAGENT_READ_ONLY_PARAM = "readOnly";
+
+/**
+ * The `read_doc` tool. `file-read` registers it, and the plan, rewind, and
+ * subagent reader lists carry the name, so the document reader is one reader
+ * everywhere instead of three spellings.
+ */
+export const READ_DOC_TOOL = "read_doc";
+
+/**
+ * The `web_search` tool. `web-access` registers it; plan's and subagent's reader
+ * lists carry the name, so a rename cannot silently drop the web reader.
+ */
+export const WEB_SEARCH_TOOL = "web_search";
+
+/** The `web_fetch` tool, shared the same way as {@link WEB_SEARCH_TOOL}. */
+export const WEB_FETCH_TOOL = "web_fetch";

package/lib/tui/glyphs.ts

@@ -30,6 +30,7 @@ export const GLYPHS = {
 	jobsFailure: "✗",
 	stopped: "⊘",
 	browse: "◉",
+	board: "▤",
 	delegation: "↳",
 	wechat: "✆",
 	gaugeFull: "▰",
@@ -71,6 +72,7 @@ export const STATUS_KEYS = {
 	watch: "watch",
 	watchMatches: "watch-matches",
 	browse: "browse",
+	board: "board",
 	rewind: "rewind",
 	agents: "agents",
 	wechat: "wechat",

package/lib/web/README.md

@@ -3,7 +3,7 @@
 The tokens, base rules, app shell, `bf-*` components, HTML atoms, and client
 runtime the two loopback pages draw with: the plan review
 ([`../../extensions/plan/web-page.ts`](../../extensions/plan/web-page.ts)) and
-file browse ([`../../extensions/file-browse/styles.ts`](../../extensions/file-browse/styles.ts)).
+file browse ([`../../extensions/file-browse/view/styles.ts`](../../extensions/file-browse/view/styles.ts)).
 The module-by-module inventory is the `web/` row of [`../README.md`](../README.md);
 this file is the conventions those modules exist to make easy.
 
@@ -34,7 +34,10 @@ are computed rather than mapped:
 - `--scrim` and `--shadow` — per appearance, because a dimming layer and a lifted
   panel need their own alpha rather than a palette entry.
 
-Components read tokens only: no literal hex or `rgba()` in `components.ts`, and a
+`--raised` is the one derived neutral: `--surface` mixed 6% (dark) or 3% (light)
+toward `--text`, for a block that has to read as a plane above the page rather than
+as an outline — the light step is smaller because a darker accent on a lighter step
+falls below AA. Components read tokens only: no literal hex or `rgba()` in `components.ts`, and a
 test fails one. Contrast is asserted, not assumed — text, muted, and accent at
 4.5:1 on both surfaces, the primary label at 4.5:1 on the accent fill, `--dim` at
 3:1 because it carries the line-number gutter, and the status colours at 3:1.

package/lib/web/components.ts

@@ -18,6 +18,8 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .bf-btn:hover{border-color:var(--accent);color:var(--accent);text-decoration:none}
 .bf-btn[aria-pressed="true"]{border-color:var(--accent);color:var(--accent);background:var(--accent-soft)}
 .bf-btn--primary{background:var(--accent);border-color:var(--accent);color:var(--on-accent)}
+.bf-btn--danger{border-color:var(--danger);color:var(--danger)}
+.bf-btn--danger:hover{border-color:var(--danger);background:var(--danger);color:var(--on-accent)}
 .bf-btn--primary:hover{filter:brightness(1.06);color:var(--on-accent)}
 .bf-btn--ghost{border-color:transparent;background:none;padding:0;font:inherit;color:inherit}
 .bf-btn--ghost:hover{color:var(--accent)}
@@ -36,6 +38,9 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .bf-segmented__item[aria-current="page"],.bf-segmented__item[aria-pressed="true"]{background:var(--accent-soft);color:var(--accent)}
 .bf-input{border:0;background:transparent;color:var(--text);font:var(--fs-sm) var(--font-mono);width:100%;outline:none}
 .bf-field{display:flex;align-items:center;gap:var(--space-1);background:var(--canvas);border:1px solid var(--border);border-radius:var(--radius-md);padding:var(--space-1) var(--space-2);color:var(--muted);font-size:var(--fs-sm)}
+/* The field is the control: ringing the input inside it drew a border within a border. */
+.bf-field:focus-within{outline:var(--focus-ring) solid var(--accent);outline-offset:2px}
+.bf-field .bf-input:focus-visible{outline:none}
 .bf-textarea{width:100%;min-height:72px;padding:var(--space-2);font:inherit;color:var(--text);background:var(--canvas);border:1px solid var(--border);border-radius:var(--radius-md);resize:vertical}
 .bf-panel{min-width:0;overflow:auto;overscroll-behavior:contain}
 .bf-panel__summary{display:none}

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.19.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.