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

package/extensions/board/seat.ts

@@ -1,28 +0,0 @@
-/**
- * The seat: the name the page serves as, and the actor it is shown as.
- *
- * A page outlives the session that opened it — a `/resume`, a rename, or a fresh
- * session taking the page over would otherwise change who the page says it is. So the
- * page is a *seat* rather than a session: one fixed name, one fixed id derived from it,
- * and the same identity however many sessions have served it.
- *
- * The page writes nothing, so the id decides no ownership: it is what the page's own
- * roster and the `you` chip are read against, and it keeps a page's reads the same
- * across a handover. The board's tools write as the session — which is why the label is
- * shared with the session serving the page and the ids are not.
- */
-
-import type { Actor } from "../../lib/board/rules.ts";
-import { normalizeLabel } from "../../lib/session-label.ts";
-
-/** The name a repository's page always serves under, so the lead is a role and not a session. */
-export const DEFAULT_SEAT = "team-lead";
-
-/** The prefix of a page's actor id, so one is never mistaken for a session id. */
-export const SEAT_ID_PREFIX = "board:";
-
-/** The actor a page reads as: the seat, and an id derived from it. */
-export function pageActor(label: string = DEFAULT_SEAT): Actor {
-	const seat = normalizeLabel(label, DEFAULT_SEAT);
-	return { id: `${SEAT_ID_PREFIX}${seat.toLowerCase()}`, label: seat };
-}

package/lib/tui/index.ts

@@ -1,34 +0,0 @@
-/**
- * The Bytefly terminal design system: one kit for every interactive surface.
- *
- * Import from `lib/tui/index.ts` rather than a leaf module so the surface reads
- * as one system. The leaves: `tokens.ts` (semantic role -> theme token),
- * `glyphs.ts` (the shared glyph, separator, and status-key vocabulary),
- * `chrome.ts` (screen frame, hints, viewport, overlay), `cursor.ts` (list
- * scroll and navigation), `columns.ts` (width math), `rules.ts` (the rule
- * grammar), `rows.ts` (list rows, checkboxes, chips, empty states), `gauge.ts`
- * (the context gauge), `indent.ts` (the transcript block indent), and
- * `line-pane.ts` (the scrollable log/match pane), and
- * (the shared tool-transcript kit: call title, width-safe call line,
- * sanitized error, and the running timer), and `render-cache.ts` (the
- * per-instance line memo a derived component renders through).
- *
- * Value-only, like every `lib/` module: pure functions, constants, and classes,
- * with no module-level state.
- */
-
-export * from "./chrome.ts";
-export * from "./columns.ts";
-export * from "./confirm.ts";
-export * from "./cursor.ts";
-export * from "./dock-screen.ts";
-export * from "./gauge.ts";
-export * from "./glyphs.ts";
-export * from "./line-pane.ts";
-export * from "./indent.ts";
-export * from "./render-cache.ts";
-export * from "./rows.ts";
-export * from "./rules.ts";
-export * from "./status-controller.ts";
-export * from "./tokens.ts";
-export * from "./tool.ts";

package/skills/project-docs/SKILL.md

@@ -1,133 +0,0 @@
----
-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

@@ -1,131 +0,0 @@
-# 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.

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

@@ -1,105 +0,0 @@
-# Record one bullet
-
-This mode writes one thing: a bullet in the changelog for a change that just landed.
-It does not decide whether something shipped, and it does not curate a release — that
-is the `release` mode, and only for a version the user named.
-
-Read [`discovery.md`](./discovery.md) first for the file, the categories, their order,
-the scope spelling, and whether the entry ships with the change. Where a tool owns the
-file — `semantic-release`, `changesets`, `git-cliff`, or a step in the release workflow —
-this mode does not write it: the entry belongs upstream, in the commit message's
-convention, a changeset fragment, or the generator's config.
-
-## Where the bullet goes
-
-- Re-read the changelog before editing: another session, another contributor, or the
-  user may have written since the state script ran.
-- Under `[Unreleased]`, in the category the project uses for this kind of change, in
-  the file's own order and spelling. Never create a second heading for a category that
-  already exists in the section.
-- When the file keeps no `[Unreleased]` section, ask where the change is recorded — the
-  preamble decides, and a project that writes entries only at release has a different
-  procedure.
-- Insert without disturbing any other bullet, keep the file's wrap column, and write it
-  in the same commit as the change it describes.
-
-## Does it qualify
-
-It qualifies when a user can observe it: behavior, a CLI or tool or command surface, a
-config default, packaging and dependencies a user installs, security, or a documented
-promise that is now true or false.
-
-It does not qualify when only the implementation moved: an internal refactor, a rename
-with no behavior change, a test, formatting, a comment, a dependency bump with no
-behavior change, or a typo fixed in the changelog itself.
-
-When a change is both — a refactor that also fixes a rounding bug — the bullet is the
-rounding bug, and the refactor is not mentioned.
-
-## One outcome, one bullet
-
-- A feature and the bug it fixed before release are one bullet: users never saw the
-  broken version.
-- Two observable changes are two bullets, even in one commit.
-- Two commits that produce one outcome are one bullet, written where the outcome became
-  true.
-- A breaking change is its own bullet with the required action; do not bury it in a
-  feature's sentence.
-
-When the outcome is unclear, ask. Reading the diff tells you what changed; only the
-author knows what a user will notice.
-
-## The shape
-
-Follow the file's newest released section. Where the project states nothing, the shape
-is one bullet that leads with the scope in backticks, a colon, then what the user can
-now do:
-
-```text
-- `billing`: invoices show tax as a separate line. Amounts that used to be bundled
-  into `total` are summed on the printed total, so an invoice stored by an older
-  release still reconciles.
-- `cli`: `--legacy-auth` is no longer read; run `mytool migrate auth` first.
-```
-
-- **Scope**: the area a user would name — an extension, package, module, or subsystem,
-  in the project's own spelling. Never a file path, a function, or a ticket number. A
-  bullet with no scope is a defect where the project uses scopes, and noise where it
-  does not.
-- **Outcome first**: what is different for the user, then the mechanism if it matters,
-  then any action they must take.
-- **Length**: a bullet may run to several sentences when the outcome needs them — what
-  the user sees, what it replaced, what to do about it. Brevity is not the goal;
-  vagueness is the defect.
-- **Voice**: match the file. Most changelogs are present tense and third person; do not
-  switch to marketing, and do not add praise for the change.
-- **Wrap**: match the file's column, usually near 80, and let one bullet be one
-  paragraph.
-
-## What does not belong
-
-File names and paths, internal helper names, test counts and coverage, commit hashes
-and pull-request numbers as the subject (a link at the end is fine where the file does
-it), and empty words such as "various", "improvements", "cleanup", "refactor", "misc".
-A reader who cannot tell from the bullet whether the change affects them has been told
-nothing.
-
-## The two failure modes
-
-```text
-- `billing`: refactored invoice rendering and added tests.
-- `misc`: improvements.
-```
-
-The first names no outcome and reports the implementation. The second names no scope,
-no outcome, and would fit any release.
-
-```text
-- `api`: `POST /v2/charge` now refuses an amount with more than two decimals
-  instead of truncating it, so a client that relied on the old rounding sees a
-  `422` with `code: "amount_precision"`. Truncation moved to `POST /v2/charge/draft`,
-  which is what the old behavior should have been.
-```
-
-Three sentences, one outcome, one scope, and the migration named. Long is fine when
-each sentence tells the reader something they must know.

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

@@ -1,127 +0,0 @@
-# Discover the project's documents
-
-A document is a convention before it is a file: which documents exist, what each one
-promises, how a version is spelled, and when an entry is written are all things a
-project chose. Read what it chose. Do not import a template where the project says
-something else, and do not average two sources — when they disagree, ask.
-
-Find these five things, in this order. The first one locates the rest.
-
-## 1. The document set
-
-The documents this skill looks for, in the order it looks, and where a project keeps
-them. A project that has only some of them is normal: the skill maintains what exists,
-and whether to adopt a missing one is the maintainer's decision rather than an edit.
-
-- **The front door** — `README.md` first, then `README.rst`, `README`, or `docs/README.md`.
-  A mirror (`README.zh-CN.md`, `README.ja.md`) is part of the front door, not a
-  separate document: it carries the same sections, table rows, and links.
-- **The plan of record** — `ROADMAP.md`, then `ROADMAP`, `docs/roadmap.md`, a
-  `ROADMAP` section in the front door, or an issue tracker label the project's docs
-  name. A project with none is maintained from the changelog and the tree alone; say so.
-- **The record of what shipped** — `CHANGELOG.md`, then `CHANGELOG`, `CHANGES.md`,
-  `HISTORY.md`, `NEWS.md`, `docs/CHANGELOG.md`, `docs/changelog.md`. The bundled script
-  takes the first name in that order. Several changelogs belonging to several packages
-  are a scope question, not a choice: ask which package is in scope, and never treat one
-  package's file as a copy of another's.
-- **The contributor path** — `CONTRIBUTING.md`, then `.github/CONTRIBUTING.md`,
-  `docs/contributing.md`, and the instruction file the project's agent reads
-  (`AGENTS.md`, `CLAUDE.md`), which usually states the rules the other three obey.
-
-Deep guides (`docs/`, `documentation/`) are where detail belongs. Their existence is
-the reason the front door can stay short: it summarizes and links, and the skill must
-not move a guide's content up into it, or copy the front door's catalog down.
-
-These rules are written in Markdown's vocabulary because most projects write their docs
-in it. Read the format the project actually uses — reStructuredText, AsciiDoc, plain
-text — and fix it in that format: a heading anchor, a link reference, and a fenced
-example are spelled differently in each, and converting a document is not this skill's
-job.
-
-## 2. The version's single source
-
-One file decides the version: `package.json`, `pyproject.toml`, `Cargo.toml`, a
-`VERSION` file, or a `version` module. Everything else repeats it — the newest dated
-changelog heading, a tag, a badge, a lockfile. Read the source and the repeats
-together; a version that disagrees in one place is the most common stale claim a
-release leaves behind.
-
-## 3. The changelog's local conventions
-
-- **Who writes the file** — a preamble that says "generated", a `.changeset/` or
-  `.changes/` directory, a release workflow step that writes the changelog, or a
-  generator named in the manifest or its config: `semantic-release`, `release-please`,
-  `changesets`, `git-cliff`, `goreleaser`, `cargo-release`, `standard-version`. Where a
-  tool owns the file, the entry is written upstream — in the commit message's
-  convention, in a changeset fragment, or in the generator's config — and never by hand.
-- **The preamble** — whether it names Keep a Changelog, Semantic Versioning, a
-  different convention, and whether unreleased entries are kept in the file at all.
-- **The category names and their order** — Keep a Changelog's set is `Added`,
-  `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`, in that order, and a
-  project may use a subset, add its own, or reorder them. Copy the spelling exactly:
-  `Fix` is not `Fixed`.
-- **The bullet's shape** — read the newest *released* section, not the first one. Note
-  the scope prefix (`- \`core\`: …`, `- [core] …`, or none), whether a bullet may run
-  several sentences, the wrap column, and whether backticks or bold carry the scope.
-- **Whether the entry ships with the change** — `CONTRIBUTING.md`, the instruction
-  file, and a pull-request template say it in one line. Silence is not permission to
-  defer: ask, because a changelog maintained per release is a different procedure.
-- **The release procedure** — a release document outranks everything here:
-  `docs/release.md`, `RELEASING.md`, `CONTRIBUTING.md`'s release section, a
-  `publish.yml` job, or a `release` script in the manifest. Read it for the link-ref
-  update, the tag format, and the push and publish order.
-
-## 4. The roadmap's rules
-
-- **The item form** — how an item is written and whether it carries an id: `**P1 — …**`,
-  `- [ ] …`, `R1: …`, a bare heading. Ids are what a citation elsewhere points at.
-- **The buckets and their caps** — horizon names (`Now` / `Next` / `Later`, or
-  quarters), and any limit the file states on how many items a bucket holds.
-- **The ledger, if there is one** — the table tying a promise in the front door to the
-  items that keep it; a row is open while any of its items are.
-- **What happens to a shipped item** — the stated rule, usually one line: delete it and
-  record the reason, or renumber the rest. Never tick it and leave it, unless the file
-  says to.
-- **The non-goals** — the "deliberately left thin" or "won't do" list, with the reason
-  each carries. Reversing one is a decision, not an edit.
-
-## 5. The check and the guards
-
-The project's check command (`bun run check`, `npm test`, `make check`, a CI workflow)
-is the finish line for any edit. Find the guards on these documents by name, because a
-guard states the rule better than a summary of it: `release.test.ts`,
-`changelog.test.ts`, `docs-parity.test.ts`, `roadmap.test.ts`, a link checker, or a CI
-step that compares a count in the docs with the tree.
-
-Quote a guard's name and what it holds; do not restate its rule. Run the guard
-directly while iterating — a failing guard names the rule you just broke.
-
-## State the profile
-
-Before editing, write one short paragraph: the documents found, the version's source,
-the changelog's categories and scope spelling, the roadmap's item form and caps, the
-check command, and the guards. It is how the user catches a misread in one line
-instead of in a diff. Do not invent a rule the project never stated; ask instead.
-
-## A worked example
-
-When you are in this repository, the answers are already written down:
-
-- `README.md` and `README.zh-CN.md` — the front door and its mirror; `test/docs-parity.test.ts`
-  holds the two to the same headings, table rows, and links.
-- `CHANGELOG.md` — Keep a Changelog preamble, categories in the standard order,
-  `[Unreleased]` kept in the file, scope in backticks followed by a colon.
-- `ROADMAP.md` — items as `**P1 — …**`, `Now` and `Next` capped at ten, a promise
-  ledger, and the rule that a shipped item is deleted with its reason;
-  `test/roadmap.test.ts` pins the ids, links, and caps, and cannot see that an item
-  has shipped.
-- `CONTRIBUTING.md` and `AGENTS.md` — the entry lands in the same commit as the
-  change, and a behavior change also updates the catalog table in both entry READMEs
-  and the relevant guide.
-- `docs/development.md` — the normative release procedure.
-- `test/release.test.ts` — the guard on subsection names, order, emptiness, and the
-  version pin against the newest tag.
-- `bun run check` — the finish line; `bun test test/roadmap.test.ts` for one guard alone.
-
-The paths are named, not linked: a skill is installed into projects that do not
-contain them, so a link would point nowhere from the place it is read.

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

@@ -1,80 +0,0 @@
-# Readme
-
-The front door is the only document a reader is guaranteed to see, so it carries two
-burdens at once: it must be *enough* on its own, and it must not become the manual. This
-mode keeps it true to the tree without letting it grow.
-
-Read [`discovery.md`](./discovery.md) first for the file, its mirror, and the guides it
-links to.
-
-## What belongs on the front door
-
-- What the thing is, in one or two sentences a stranger can act on.
-- Install, and the first command that proves the install worked.
-- The catalog: one row per capability, grouped by what the reader is trying to do.
-- Configuration that a reader must choose before the first run, and where the rest
-  lives.
-- Links onward to the guides, and the license.
-
-What does not belong: a tool's parameter table, an exhaustive options list, an internal
-architecture, or a tutorial. When a row needs three sentences of mechanism, the
-mechanism belongs in a guide and the row links to it — do not copy the guide up, and do
-not let the row become a summary of a summary.
-
-## Rows and counts belong to the tree
-
-Where the project has a catalog of capabilities, each row follows the tree:
-- Every row names something that exists and is spelled the way the code spells it: the
-  tool, the command, the flag, the file. A renamed tool with an unchanged row is a
-  broken promise to the reader who types it.
-- Every count the page states — extensions, tools, skills, themes, formats — is read
-  from the tree. A project with a guard that derives it has the number already: change
-  the tree, or the guard, never the number in the prose.
-- A capability with no row is invisible; a row with no capability is a lie. Both
-  directions, in the same pass.
-
-## Examples must run
-
-Run the quickstart as written, in a clean directory, before editing anything else on the
-page. The first command is the most expensive promise on the page: a broken one costs
-the reader the whole document. Then check the worked example — an import, a
-configuration snippet, a call — against the current surface, and prefer the shortest
-form that still runs.
-
-## The mirror, where the project has one
-
-A translated front door is the same document in another language: the same sections,
-the same table rows in the same order, the same relative links. Prose is translated;
-structure is not. A project with one language has no mirror to check, and adding one is
-not this mode's job. A row added to one and not the other is a finding, and the count on
-both sides is the tree's.
-
-## Screenshots and assets
-
-An image is a claim about a surface. Recapture it when the surface changed — and only
-then, because a stale frame is worse than no frame and a fresh frame is expensive to
-produce. Check that the alt text describes what the frame now shows, that the image is
-referenced by a relative path, and that an image whose feature was removed is deleted
-rather than left unreferenced.
-
-## Report
-
-Say which rows, counts, examples, and images moved, and which claims you could not check
-without running the product. A front door that matches the tree already is a valid
-result; say what you verified — the command you ran, the counts you derived — and stop.
-
-## In this repository
-
-- `README.md` is the front door and `README.zh-CN.md` mirrors it section for section;
-  `test/docs-parity.test.ts` holds the two to the same headings, table rows, and links,
-  and derives the catalog's counts from the tree.
-- `test/extension-load.test.ts` pins every count the pages state — extensions, tools,
-  skills, themes — against what actually loads and ships, and requires a row in both
-  entry READMEs for every packaged skill.
-- `assets/` holds the frames the pages show; `bun run screenshots` recaptures one, and a
-  frame is only recaptured when its surface changed.
-- Deep detail lives in `docs/extensions/<name>.md`, `lib/README.md`, and `docs/`; the
-  front door links there and does not restate them.
-
-The paths are named, not linked: a skill is installed into projects that do not
-contain them, so a link would point nowhere from the place it is read.