docs: record redesign issue queue

- settings.ts: replaced all getCachedPython/resolvePythonExecutable calls with _resolveRuntimeCommand (ManagedRuntime)
- settings.ts: deleted _syncRuntime (superseded by ManagedRuntime.ensure)
- settings.ts: cleaned dead imports (getMemoryRuntime, isMemoryReady, isVectorReady, getCachedPython)
- main.ts: added _getPythonCommand helper using ManagedRuntime, replaced all resolvePythonExecutable calls
- dashboard.ts: added _resolvePython helper, replaced all 7 resolvePythonExecutable + 1 checkRuntimeVersion calls
- modals.ts: added _resolvePython helper to PaperForgeSetupModal, replaced getCachedPython + 3 resolvePythonExecutable calls

Build: 258.0KB | Tests: 384/384 passed | Typecheck: clean

%TEMP%test_import.py

@@ -0,0 +1 @@
+import paperforge

.agents/skills/ask-matt/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: ask-matt
+description: Ask which skill or flow fits your situation. A router over the skills in this repo.
+disable-model-invocation: true
+---
+
+# Ask Matt
+
+You don't remember every skill, so ask.
+
+A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
+
+## The main flow: idea → ship
+
+The route most work travels. You have an idea and want it built.
+
+1. **`/grill-with-docs`** — sharpen the idea by interview. Start here when you **have a codebase**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No codebase? Use `/grill-me` — see Standalone. Both run the same `/grilling` primitive; `grill-with-docs` is the one that leaves a paper trail.)
+2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (see Crossing sessions):
+   - **`/handoff`** out, then open a fresh session against that file,
+   - **`/prototype`** to answer the question with throwaway code,
+   - **`/handoff`** back what you learned, and reference it from the original idea thread.
+3. **Branch — is this a multi-session build?**
+   - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's an ordered `tickets.md` you work by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **clearing context between each one**.
+   - **No** → **`/implement`** right here, in the same context window.
+
+   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
+
+### Context hygiene
+
+Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-tickets` — so the grilling, spec, and tickets all build on the same thinking. Each `/implement` then starts fresh, working from the ticket.
+
+The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-tickets`, don't push on degraded — `/handoff` and continue in a fresh thread.
+
+## On-ramps
+
+A starting situation that generates work, then merges onto the main flow.
+
+- **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up.
+
+  Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Tickets that `/to-tickets` produced are already agent-ready, so **don't triage them**.
+
+- **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down.
+
+- **A huge, foggy effort — a greenfield project or a huge feature build, too big for one session** → **`/wayfinder`**. When the way from here to the destination isn't visible yet, it charts a **shared map** of investigation tickets on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Then it merges onto the main flow at **`/to-spec`** (or, if the effort turned out small enough, straight to **`/implement`**). Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't.
+
+## Codebase health
+
+Not feature work — upkeep.
+
+- **`/improve-codebase-architecture`** — run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces **deepening opportunities**; picking one _generates an idea_ you can take into the main flow at `/grill-with-docs`. It's the survey that finds the candidates; **`/codebase-design`** (below) is the bench you design the chosen one on.
+
+## Vocabulary underneath
+
+Two model-invoked references that run *beneath* the other skills — each the single source of truth for its vocabulary. Reach for them directly when the **words**, not the process, are the problem; or let the skills above pull them in.
+
+- **`/domain-modeling`** — sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word ("account" doing three jobs), record a hard-to-reverse decision as an ADR. It's the active discipline `/grill-with-docs` drives to keep `CONTEXT.md` a clean glossary.
+- **`/codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*: a lot of behaviour behind a small interface at a clean seam. `/tdd` and `/improve-codebase-architecture` both speak it.
+
+## Crossing sessions
+
+- **`/handoff`** — when a thread is full or you need to branch off (e.g. into a `/prototype` session), this compacts the conversation into a markdown file. You don't continue in place — you **open a new session and reference that file** to carry the context across. It's the bridge between context windows, in either direction. Use it when you want a **fresh session** but need the **current conversation preserved**.
+- **`/compact`** (built-in) — stay in the **same conversation**, letting the earlier turns be summarized. Use it at **intentional breaks between phases**, when you don't mind losing the verbatim history. Don't compact mid-phase — the agent can lose its way. `/handoff` forks; `/compact` continues.
+
+## Standalone
+
+Off the main flow entirely.
+
+- **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but for when you have **no codebase**. Stateless: it saves nothing locally, builds no `CONTEXT.md`. Reach for it to sharpen any plan or design that doesn't live in a repo.
+- **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway from day one — keep the answer, delete the code. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
+- **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
+- **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
+- **`/writing-great-skills`** — reference for writing and editing skills well.
+
+## Precondition
+
+**`/setup-matt-pocock-skills`** — run before your first engineering flow to configure the issue tracker, triage labels, and doc layout the other skills assume. Custom issue trackers also work.

.agents/skills/claude-handoff/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: claude-handoff
+description: Hand the current conversation off to a fresh background agent that picks up the work immediately.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+Write a handoff summary of the current conversation so a fresh agent can continue the work. Instead of saving it, launch a background agent seeded with the summary as its prompt: `claude --bg --name "<descriptive name>" "<handoff summary>"`. It starts in the current working directory and returns immediately; the user manages it with `claude agents`.
+
+Always pass `-n`/`--name` with a descriptive name (e.g. `--name "Fix login bug"`) — it sets the display name shown in the job list, session picker, and terminal title.
+
+Include a "suggested skills" section in the summary, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information — the summary becomes the agent's prompt.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the summary accordingly.

.agents/skills/code-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: code-review
+description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
+---
+
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards** — does the code conform to this repo's documented coding standards?
+- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
+
+Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+
+The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
+
+## Process
+
+### 1. Pin the fixed point
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
+
+Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+
+Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.
+
+### 2. Identify the spec source
+
+Look for the originating spec, in this order:
+
+1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
+2. A path the user passed as an argument.
+3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
+4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
+
+### 3. Identify the standards sources
+
+Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
+
+On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+
+- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*; match it against the diff:
+
+- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+
+### 4. Spawn both sub-agents in parallel
+
+Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
+
+**Standards sub-agent prompt** — include:
+
+- The full diff command and commit list.
+- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
+- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** — include:
+
+- The diff command and commit list.
+- The path or fetched contents of the spec.
+- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+If the spec is missing, skip the Spec sub-agent and note this in the final report.
+
+### 5. Aggregate
+
+Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
+
+End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
+- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.

.agents/skills/codebase-design/DEEPENING.md

@@ -0,0 +1,37 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
+
+Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
+- Write new tests at the deepened module's interface. The **interface is the test surface**.
+- Tests assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.

.agents/skills/codebase-design/DESIGN-IT-TWICE.md

@@ -0,0 +1,44 @@
+# Design It Twice
+
+When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
+
+Uses the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
+- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
+
+### 2. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
+- Agent 2: "Maximise flexibility — support many use cases and extension."
+- Agent 3: "Optimise for the most common caller — make the default case trivial."
+- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
+
+Include both [SKILL.md](SKILL.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+
+Each sub-agent outputs:
+
+1. Interface (types, methods, params — plus invariants, ordering, error modes)
+2. Usage example showing how callers use it
+3. What the implementation hides behind the seam
+4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
+5. Trade-offs — where leverage is high, where it's thin
+
+### 3. Present and compare
+
+Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.

.agents/skills/codebase-design/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: codebase-design
+description: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
+---
+
+# Codebase Design
+
+Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
+
+## Glossary
+
+Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+
+**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
+
+**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — they refer only to the type-level surface).
+
+**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+
+**Depth** — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
+
+**Leverage** — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests.
+
+**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Deep vs shallow
+
+**Deep module** = small interface + lots of implementation:
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid):
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing an interface, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+
+## Designing for testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them.**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects.**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
+
+## Going deeper
+
+- **Deepening a cluster given its dependencies** — see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.
+- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.

.agents/skills/decision-mapping/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: decision-mapping
+description: Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time.
+disable-model-invocation: true
+---
+
+This skill is invoked when a loose idea requires more than one agent session to turn into a plan. It creates a stateful decision map in a markdown file, and drives the user through a sequence of tickets to resolve the open questions - which may require either prototyping, research or discussion.
+
+## The Decision Map
+
+The decision map is a single compact Markdown file, one per planning effort, git-tracked alongside the project. It is the canonical artifact — the **whole map is loaded as context into every session**, so it must stay compact.
+
+Assets created during tickets should be linked to from the map, not duplicated within it.
+
+### Structure
+
+Numbered entries ("tickets"), each its own section keyed by its number:
+
+```markdown
+## #1: Relational Or Non-Relational Database?
+
+Blocked by: #<ticket-number>, #<ticket-number>
+Type: Research | Prototype | Grilling
+
+### Question
+
+<question-here>
+
+### Answer
+
+<answer-here>
+```
+
+Each ticket must be sized to one 100K token agent session.
+
+## Ticket Types
+
+There are three types of tickets:
+
+- **Research**: Reading documentation, third-party API's, or local resources like knowledge bases. Creates a markdown summary as an asset. Use this when knowledge outside the current working directory is required.
+- **Prototype**: Writing UI or logic code to test a hypothesis, or to explore a design space. Uses the /prototype skill. Creates a prototype as an asset. Use this when "how should it look" or "how should it behave" is the key question.
+- **Grilling**: Conversation with the agent. Uses the /grilling and /domain-modelling skills. Asks one question at a time. The default case.
+
+## Fog of war
+
+The map is _deliberately_ incomplete beyond the frontier. Your job is to investigate the frontier, and to resolve tickets in order to push the frontier forward. Push back the fog of war, one node at a time.
+
+At some point, the fog of war should have been pushed back far enough that the path to the finish line is clear. At that point, no more tickets will be required and the decision map can be considered 'done'.
+
+## Invocation
+
+There are two ways this skill can be invoked: **bootstrap** and **resume**.
+
+### Bootstrap
+
+User invokes with a loose idea.
+
+1. Run a /grilling + /domain-modelling session to surface the open decisions. Ask one question at a time.
+2. Write a new decision map — mostly fog, frontier identified, trivially-decidable entries resolved inline.
+3. Stop. Map-building is one session's work; do not also resolve tickets.
+
+### Resume
+
+User invokes with a path to an existing map and a ticket number.
+
+1. Load the **whole map** as context.
+2. Run a session to resolve the ticket, invoking skills as needed. If in doubt, use `/grilling` and `/domain-modelling`.
+3. Record what the session resolved in the ticket's body.
+4. Add newly-discovered tickets (with correct `blocked_by` edges).
+5. Stop.
+
+If the decisions made invalidate other parts of the map, update or delete those nodes.
+
+## Parallelism
+
+The user may choose to run tickets in parallel, so expect other agents to make changes to the map.
+
+## Skipping The Decision Map
+
+Many times, the initial grilling will result in no fog of war. No unresolved tickets. Nothing to do, except implement.
+
+In those situations, you should offer the user the chance to skip the decision map - since the decision map is only needed if multi-session decisions need to be made.
+
+If they skip it, you should recommend either implementing directly or using `/to-prd` to schedule a multi-session implementation.

.agents/skills/design-an-interface/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: design-an-interface
+description: Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".
+---
+
+# Design an Interface
+
+Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple radically different designs, then compare.
+
+## Workflow
+
+### 1. Gather Requirements
+
+Before designing, understand:
+
+- [ ] What problem does this module solve?
+- [ ] Who are the callers? (other modules, external users, tests)
+- [ ] What are the key operations?
+- [ ] Any constraints? (performance, compatibility, existing patterns)
+- [ ] What should be hidden inside vs exposed?
+
+Ask: "What does this module need to do? Who will use it?"
+
+### 2. Generate Designs (Parallel Sub-Agents)
+
+Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a **radically different** approach.
+
+```
+Prompt template for each sub-agent:
+
+Design an interface for: [module description]
+
+Requirements: [gathered requirements]
+
+Constraints for this design: [assign a different constraint to each agent]
+- Agent 1: "Minimize method count - aim for 1-3 methods max"
+- Agent 2: "Maximize flexibility - support many use cases"
+- Agent 3: "Optimize for the most common case"
+- Agent 4: "Take inspiration from [specific paradigm/library]"
+
+Output format:
+1. Interface signature (types/methods)
+2. Usage example (how caller uses it)
+3. What this design hides internally
+4. Trade-offs of this approach
+```
+
+### 3. Present Designs
+
+Show each design with:
+
+1. **Interface signature** - types, methods, params
+2. **Usage examples** - how callers actually use it in practice
+3. **What it hides** - complexity kept internal
+
+Present designs sequentially so user can absorb each approach before comparison.
+
+### 4. Compare Designs
+
+After showing all designs, compare them on:
+
+- **Interface simplicity**: fewer methods, simpler params
+- **General-purpose vs specialized**: flexibility vs focus
+- **Implementation efficiency**: does shape allow efficient internals?
+- **Depth**: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
+- **Ease of correct use** vs **ease of misuse**
+
+Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
+
+### 5. Synthesize
+
+Often the best design combines insights from multiple options. Ask:
+
+- "Which design best fits your primary use case?"
+- "Any elements from other designs worth incorporating?"
+
+## Evaluation Criteria
+
+From "A Philosophy of Software Design":
+
+**Interface simplicity**: Fewer methods, simpler params = easier to learn and use correctly.
+
+**General-purpose**: Can handle future use cases without changes. But beware over-generalization.
+
+**Implementation efficiency**: Does interface shape allow efficient implementation? Or force awkward internals?
+
+**Depth**: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
+
+## Anti-Patterns
+
+- Don't let sub-agents produce similar designs - enforce radical difference
+- Don't skip comparison - the value is in contrast
+- Don't implement - this is purely about interface shape
+- Don't evaluate based on implementation effort

.agents/skills/diagnosing-bugs/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: diagnosing-bugs
+description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
+---
+
+# Diagnosing Bugs
+
+A discipline for hard bugs. Skip phases only when explicitly justified.
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### Tighten the loop
+
+Treat the loop as a product. Once you have _a_ loop, **tighten** it:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight — a debugging superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+### Completion criterion — a tight loop that goes red
+
+Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (paste the invocation and its output), and that is:
+
+- [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_.
+- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
+- [ ] **Fast** — seconds, not minutes.
+- [ ] **Agent-runnable** — you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
+
+If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
+
+## Phase 2 — Reproduce + minimise
+
+Run the loop. Watch it go red — the bug appears.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+### Minimise
+
+Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what's load-bearing for the failure.
+
+Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
+
+Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
+
+Do not proceed until you have reproduced **and** minimised.
+
+## Phase 3 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+## Phase 6 — Cleanup + post-mortem
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
+- [ ] Regression test passes (or absence of seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
+
+**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

.agents/skills/diagnosing-bugs/scripts/hitl-loop.template.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Human-in-the-loop reproduction loop.
+# Copy this file, edit the steps below, and run it.
+# The agent runs the script; the user follows prompts in their terminal.
+#
+# Usage:
+#   bash hitl-loop.template.sh
+#
+# Two helpers:
+#   step "<instruction>"          → show instruction, wait for Enter
+#   capture VAR "<question>"      → show question, read response into VAR
+#
+# At the end, captured values are printed as KEY=VALUE for the agent to parse.
+
+set -euo pipefail
+
+step() {
+  printf '\n>>> %s\n' "$1"
+  read -r -p "    [Enter when done] " _
+}
+
+capture() {
+  local var="$1" question="$2" answer
+  printf '\n>>> %s\n' "$question"
+  read -r -p "    > " answer
+  printf -v "$var" '%s' "$answer"
+}
+
+# --- edit below ---------------------------------------------------------
+
+step "Open the app at http://localhost:3000 and sign in."
+
+capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
+
+capture ERROR_MSG "Paste the error message (or 'none'):"
+
+# --- edit above ---------------------------------------------------------
+
+printf '\n--- Captured ---\n'
+printf 'ERRORED=%s\n' "$ERRORED"
+printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

.agents/skills/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.

.agents/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,60 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

.agents/skills/domain-modeling/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: domain-modeling
+description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
+---
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design. This is the *active* discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

.agents/skills/edit-article/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: edit-article
+description: Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.
+disable-model-invocation: true
+---
+
+1. First, divide the article into sections based on its headings. Think about the main points you want to make during those sections.
+
+Consider that information is a directed acyclic graph, and that pieces of information can depend on other pieces of information. Make sure that the order of the sections and their contents respects these dependencies.
+
+Confirm the sections with the user.
+
+2. For each section:
+
+2a. Rewrite the section to improve clarity, coherence, and flow. Use maximum 240 characters per paragraph.

.agents/skills/git-guardrails-claude-code/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: git-guardrails-claude-code
+description: Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.
+---
+
+# Setup Git Guardrails
+
+Sets up a PreToolUse hook that intercepts and blocks dangerous git commands before Claude executes them.
+
+## What Gets Blocked
+
+- `git push` (all variants including `--force`)
+- `git reset --hard`
+- `git clean -f` / `git clean -fd`
+- `git branch -D`
+- `git checkout .` / `git restore .`
+
+When blocked, Claude sees a message telling it that it does not have authority to access these commands.
+
+## Steps
+
+### 1. Ask scope
+
+Ask the user: install for **this project only** (`.claude/settings.json`) or **all projects** (`~/.claude/settings.json`)?
+
+### 2. Copy the hook script
+
+The bundled script is at: [scripts/block-dangerous-git.sh](scripts/block-dangerous-git.sh)
+
+Copy it to the target location based on scope:
+
+- **Project**: `.claude/hooks/block-dangerous-git.sh`
+- **Global**: `~/.claude/hooks/block-dangerous-git.sh`
+
+Make it executable with `chmod +x`.
+
+### 3. Add hook to settings
+
+Add to the appropriate settings file:
+
+**Project** (`.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Global** (`~/.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/block-dangerous-git.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If the settings file already exists, merge the hook into existing `hooks.PreToolUse` array — don't overwrite other settings.
+
+### 4. Ask about customization
+
+Ask if user wants to add or remove any patterns from the blocked list. Edit the copied script accordingly.
+
+### 5. Verify
+
+Run a quick test:
+
+```bash
+echo '{"tool_input":{"command":"git push origin main"}}' | <path-to-script>
+```
+
+Should exit with code 2 and print a BLOCKED message to stderr.

.agents/skills/git-guardrails-claude-code/scripts/block-dangerous-git.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
+
+DANGEROUS_PATTERNS=(
+  "git push"
+  "git reset --hard"
+  "git clean -fd"
+  "git clean -f"
+  "git branch -D"
+  "git checkout \."
+  "git restore \."
+  "push --force"
+  "reset --hard"
+)
+
+for pattern in "${DANGEROUS_PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qE "$pattern"; then
+    echo "BLOCKED: '$COMMAND' matches dangerous pattern '$pattern'. The user has prevented you from doing this." >&2
+    exit 2
+  fi
+done
+
+exit 0

.agents/skills/grill-me/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-me
+description: A relentless interview to sharpen a plan or design.
+disable-model-invocation: true
+---
+
+Run a `/grilling` session.

.agents/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
+disable-model-invocation: true
+---
+
+Run a `/grilling` session, using the `/domain-modeling` skill.

.agents/skills/grilling/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases.
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
+
+If a *fact* can be found by exploring the codebase, look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
+
+Do not enact the plan until I confirm we have reached a shared understanding.

.agents/skills/handoff/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+
+Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

.agents/skills/implement/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: implement
+description: "Implement a piece of work based on a spec or set of tickets."
+disable-model-invocation: true
+---
+
+Implement the work described by the user in the spec or tickets.
+
+Use /tdd where possible, at pre-agreed seams.
+
+Run typechecking regularly, single test files regularly, and the full test suite once at the end.
+
+Once done, use /code-review to review the work.
+
+Commit your work to the current branch.

.agents/skills/improve-codebase-architecture/HTML-REPORT.md

@@ -0,0 +1,123 @@
+# HTML Report Format
+
+The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic.
+
+## Scaffold
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review — {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* small custom layer for things Tailwind doesn't cover cleanly:
+         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## Header
+
+Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates.
+
+## Candidate card
+
+The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
+
+Each candidate is one `<article>`:
+
+- **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline").
+- **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
+- **Files** — monospaced list, `font-mono text-sm`.
+- **Before / After diagram** — the centrepiece. Two columns, side by side. See patterns below.
+- **Problem** — one sentence. What hurts.
+- **Solution** — one sentence. What changes.
+- **Wins** — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
+- **ADR callout** (if applicable) — one line in an amber-tinted box.
+
+No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
+
+## Diagram patterns
+
+Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point.
+
+### Mermaid graph (the workhorse for dependencies / call flow)
+
+Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
+
+Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight.
+
+### Cross-section (good for layered shallowness)
+
+Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
+
+### Mass diagram (good for "interface as wide as implementation")
+
+Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
+
+### Call-graph collapse
+
+Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
+
+## Style guidance
+
+- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
+- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
+- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
+- Use `text-xs uppercase tracking-wider` for module labels inside diagrams — they should read as schematic, not as UI.
+- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering.
+
+## Top recommendation section
+
+One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
+
+## Tone
+
+Plain English, concise — but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
+
+**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
+
+**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
+
+**Phrasings that fit the style:**
+
+- "Order intake module is shallow — interface nearly matches the implementation."
+- "Pricing leaks across the seam."
+- "Deepen: one interface, one place to test."
+- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
+
+**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place.
+
+No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.

.agents/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: improve-codebase-architecture
+description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+disable-model-invocation: true
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+This command is _informed_ by the project's domain model and built on a shared design vocabulary:
+
+- Run the `/codebase-design` skill for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
+- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
+
+Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow** — interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates as an HTML report
+
+Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and tell them the absolute path.
+
+The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+
+For each candidate, render a card with:
+
+- **Files** — which files/modules are involved
+- **Problem** — why the current architecture is causing friction
+- **Solution** — plain English description of what would change
+- **Benefits** — explained in terms of locality and leverage, and how tests would improve
+- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening
+- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+
+End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
+
+**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+
+Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, run the `/grilling` skill to walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go:
+
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones.
+- **Want to explore alternative interfaces for the deepened module?** Run the `/codebase-design` skill and use its design-it-twice parallel sub-agent pattern.

.agents/skills/loop-me/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: loop-me
+description: Grill me about specs for the workflows I want to build, within this workspace.
+disable-model-invocation: true
+argument-hint: "A workflow to design, or nothing to go find one"
+---
+
+Run a stateful `/grilling` session whose only output is **workflow** specs. Use the grilling discipline — relentless, one question at a time, a recommended answer attached to each — aimed at the vocabulary and goal below. Create, edit, and delete specs as the grilling resolves things.
+
+## The loop lens
+
+A **loop** is a recurring pattern in the user's life: their career, their week, their morning, a single repeated activity. Picturing a life as loops within loops reveals how predictable its activities really are — which is what makes them worth **delegating**. Use the lens to find loops worth specifying, and propose ones the user hasn't noticed.
+
+A **workflow** is the spec of one loop, made real. You run a workflow on a loop — the loop is its running instantiation. Workflows live in `workflows/*.md` and are the source of truth.
+
+## Vocabulary
+
+A shared language, reached for only when a workflow calls for it — never a checklist. **Mandate nothing structural**: a workflow needs no AI, no checkpoint, and no schedule unless the grilling shows it does.
+
+- **Trigger** — what fires each run: an **event** (a new email, a new issue) or a **schedule** (every morning). Event-triggering is usually the more efficient.
+- **Checkpoint** — a human-in-the-loop point where the user is asked to verify or decide. Some workflows have none and run autonomously; some use no AI at all.
+- **Push right** — defer the checkpoint as far as it will go. Do maximal work before involving the human, so they are asked once, late, with everything prepared.
+- **Brief** — what a checkpoint presents: a tight, decision-ready summary — what was produced, why, and a link down to the asset itself — never the raw output. The user reads a brief, not a draft. Speed of review is imperative.
+
+## Definition of done
+
+A workflow spec is done when an implementer agent could build it without asking a single question. Grill until then; nothing is done while a question remains.
+
+## The workspace
+
+- `workflows/*.md` — one spec per workflow.
+- `NOTES.md` — raw notes on the user's world: the tools they use, the channels they process, and their own terminology for both. When it is empty or thin, interview them about their world before specifying anything. Sharpen fuzzy terms into canonical ones as they surface, and record them here.

.agents/skills/migrate-to-shoehorn/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: migrate-to-shoehorn
+description: Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.
+---
+
+# Migrate to Shoehorn
+
+## Why shoehorn?
+
+`shoehorn` lets you pass partial data in tests while keeping TypeScript happy. It replaces `as` assertions with type-safe alternatives.
+
+**Test code only.** Never use shoehorn in production code.
+
+Problems with `as` in tests:
+
+- Trained not to use it
+- Must manually specify target type
+- Double-as (`as unknown as Type`) for intentionally wrong data
+
+## Install
+
+```bash
+npm i @total-typescript/shoehorn
+```
+
+## Migration patterns
+
+### Large objects with few needed properties
+
+Before:
+
+```ts
+type Request = {
+  body: { id: string };
+  headers: Record<string, string>;
+  cookies: Record<string, string>;
+  // ...20 more properties
+};
+
+it("gets user by id", () => {
+  // Only care about body.id but must fake entire Request
+  getUser({
+    body: { id: "123" },
+    headers: {},
+    cookies: {},
+    // ...fake all 20 properties
+  });
+});
+```
+
+After:
+
+```ts
+import { fromPartial } from "@total-typescript/shoehorn";
+
+it("gets user by id", () => {
+  getUser(
+    fromPartial({
+      body: { id: "123" },
+    }),
+  );
+});
+```
+
+### `as Type` → `fromPartial()`
+
+Before:
+
+```ts
+getUser({ body: { id: "123" } } as Request);
+```
+
+After:
+
+```ts
+import { fromPartial } from "@total-typescript/shoehorn";
+
+getUser(fromPartial({ body: { id: "123" } }));
+```
+
+### `as unknown as Type` → `fromAny()`
+
+Before:
+
+```ts
+getUser({ body: { id: 123 } } as unknown as Request); // wrong type on purpose
+```
+
+After:
+
+```ts
+import { fromAny } from "@total-typescript/shoehorn";
+
+getUser(fromAny({ body: { id: 123 } }));
+```
+
+## When to use each
+
+| Function        | Use case                                           |
+| --------------- | -------------------------------------------------- |
+| `fromPartial()` | Pass partial data that still type-checks           |
+| `fromAny()`     | Pass intentionally wrong data (keeps autocomplete) |
+| `fromExact()`   | Force full object (swap with fromPartial later)    |
+
+## Workflow
+
+1. **Gather requirements** - ask user:
+   - What test files have `as` assertions causing problems?
+   - Are they dealing with large objects where only some properties matter?
+   - Do they need to pass intentionally wrong data for error testing?
+
+2. **Install and migrate**:
+   - [ ] Install: `npm i @total-typescript/shoehorn`
+   - [ ] Find test files with `as` assertions: `grep -r " as [A-Z]" --include="*.test.ts" --include="*.spec.ts"`
+   - [ ] Replace `as Type` with `fromPartial()`
+   - [ ] Replace `as unknown as Type` with `fromAny()`
+   - [ ] Add imports from `@total-typescript/shoehorn`
+   - [ ] Run type check to verify

.agents/skills/obsidian-vault/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: obsidian-vault
+description: Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.
+---
+
+# Obsidian Vault
+
+## Vault location
+
+`/mnt/d/Obsidian Vault/AI Research/`
+
+Mostly flat at root level.
+
+## Naming conventions
+
+- **Index notes**: aggregate related topics (e.g., `Ralph Wiggum Index.md`, `Skills Index.md`, `RAG Index.md`)
+- **Title case** for all note names
+- No folders for organization - use links and index notes instead
+
+## Linking
+
+- Use Obsidian `[[wikilinks]]` syntax: `[[Note Title]]`
+- Notes link to dependencies/related notes at the bottom
+- Index notes are just lists of `[[wikilinks]]`
+
+## Workflows
+
+### Search for notes
+
+```bash
+# Search by filename
+find "/mnt/d/Obsidian Vault/AI Research/" -name "*.md" | grep -i "keyword"
+
+# Search by content
+grep -rl "keyword" "/mnt/d/Obsidian Vault/AI Research/" --include="*.md"
+```
+
+Or use Grep/Glob tools directly on the vault path.
+
+### Create a new note
+
+1. Use **Title Case** for filename
+2. Write content as a unit of learning (per vault rules)
+3. Add `[[wikilinks]]` to related notes at the bottom
+4. If part of a numbered sequence, use the hierarchical numbering scheme
+
+### Find related notes
+
+Search for `[[Note Title]]` across the vault to find backlinks:
+
+```bash
+grep -rl "\\[\\[Note Title\\]\\]" "/mnt/d/Obsidian Vault/AI Research/"
+```
+
+### Find index notes
+
+```bash
+find "/mnt/d/Obsidian Vault/AI Research/" -name "*Index*"
+```

.agents/skills/prototype/LOGIC.md

@@ -0,0 +1,79 @@
+# Logic Prototype
+
+A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where the user wants to **press buttons and watch state change**.
+
+If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're prototyping. One paragraph, in the prototype's README or a comment at the top of the file. A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
+
+### 2. Pick the language
+
+Use whatever the host project uses. If the project has no obvious runtime (e.g. a docs repo), ask.
+
+Match the project's existing conventions for tooling — don't add a new package manager or runtime just for the prototype.
+
+### 3. Isolate the logic in a portable module
+
+Put the actual logic — the bit that's answering the question — behind a small, pure interface that could be lifted out and dropped into the real codebase later. The TUI around it is throwaway; the logic module shouldn't be.
+
+The right shape depends on the question:
+
+- **A pure reducer** — `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine** — explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no `console.log` for control flow. The TUI imports it and calls into it; nothing flows the other direction.
+
+This is what makes the prototype useful past its own lifetime. When the question's been answered, the validated reducer / machine / function set can be lifted into the real module — the TUI shell gets deleted.
+
+### 4. Build the smallest TUI that exposes the state
+
+Build it as a **lightweight TUI** — on every tick, clear the screen (`console.clear()` / `print("\033[2J\033[H")` / equivalent) and re-render the whole frame. The user should always see one stable view, not an ever-growing scrollback.
+
+Each frame has two parts, in this order:
+
+1. **Current state**, pretty-printed and diff-friendly (one field per line, or formatted JSON). Use **bold** for field names or section headers and **dim** for less important context (timestamps, IDs, derived values). Native ANSI escape codes are fine — `\x1b[1m` bold, `\x1b[2m` dim, `\x1b[0m` reset. No need to pull in a styling library unless one is already in the project.
+2. **Keyboard shortcuts**, listed at the bottom: `[a] add user  [d] delete user  [t] tick clock  [q] quit`. Bold the key, dim the description, or vice-versa — whatever reads cleanly.
+
+Behaviour:
+
+1. **Initialise state** — a single in-memory object/struct. Render the first frame on start.
+2. **Read one keystroke (or one line)** at a time, dispatch to a handler that mutates state.
+3. **Re-render** the full frame after every action — don't append, replace.
+4. **Loop until quit.**
+
+The whole frame should fit on one screen.
+
+### 5. Make it runnable in one command
+
+Add a script to the project's existing task runner (`package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`). The user should run `pnpm run <prototype-name>` or equivalent — never need to remember a path.
+
+If the host project has no task runner, just put the command at the top of the prototype's README.
+
+### 6. Hand it over
+
+Give the user the run command. They'll drive it themselves; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions added, add them. Prototypes evolve.
+
+### 7. Capture the answer
+
+When the prototype has done its job, the answer to the question is the only thing worth keeping. If the user is around, ask what it taught them. If not, leave a `NOTES.md` next to the prototype so the answer can be filled in (or filled in by you, if you've watched the session) before the prototype gets deleted.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use an in-memory store unless the question is specifically about persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the TUI together.** If the reducer / state machine references `console.log`, prompts, or terminal escape codes, it's no longer portable. Keep the TUI as a thin shell over a pure module.
+- **Don't ship the TUI shell into production.** The shell is optimised for being driven by hand from a terminal. The logic module behind it is the bit worth keeping.

.agents/skills/prototype/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: prototype
+description: Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
+---
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape.
+
+## Pick a branch
+
+Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
+- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
+
+The two branches produce very different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
+
+## Rules that apply to both
+
+1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
+2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast and then delete it.
+5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
+6. **Delete or absorb when done.** When the prototype has answered its question, either delete it or fold the validated decision into the real code — don't leave it rotting in the repo.
+
+## When done
+
+The _answer_ is the only thing worth keeping from a prototype. Capture it somewhere durable (commit message, ADR, issue, or a `NOTES.md` next to the prototype) along with the question it was answering. If the user is around, that capture is a quick conversation; if not, leave the placeholder so they (or you, on the next pass) can fill in the verdict before deleting the prototype.

.agents/skills/prototype/UI.md

@@ -0,0 +1,112 @@
+# UI Prototype
+
+Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away.
+
+If the question is about logic/state rather than what something looks like — wrong branch. Use [LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague mockups in their head.
+
+## Two sub-shapes — strongly prefer sub-shape A
+
+A UI prototype is much easier to judge when it's **butting up against the rest of the app** — real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants. Only reach for sub-shape B if the prototype genuinely has no nearby home.
+
+### Sub-shape A — adjustment to an existing page (preferred)
+
+The route already exists. Variants are rendered **on the same route**, gated by a `?variant=` URL search param. The existing data fetching, params, and auth all stay — only the rendering swaps. This is the default; pick it unless there's a specific reason not to.
+
+If the prototype is for something that doesn't yet have a page but *would naturally live inside one* (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow) — that's still sub-shape A. Mount the variants inside the host page.
+
+### Sub-shape B — a new page (last resort)
+
+Only use this when the thing being prototyped genuinely has no existing page to live inside — e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible.
+
+Create a **throwaway route** following whatever routing convention the project already uses — don't invent a new top-level structure. Name it so it's obviously a prototype (e.g. include the word `prototype` in the path or filename). Same `?variant=` pattern.
+
+Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose.
+
+In both sub-shapes the floating bottom bar is identical.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and starts being noise — cap there.
+
+Write down the plan in one line, in the prototype's location or a top-of-file comment:
+
+> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
+
+This works whether the user is here to push back or not.
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to.
+- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever).
+- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`.
+
+Variants must be **structurally different** — different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
+
+### 3. Wire them together
+
+Create a single switcher component on the route:
+
+```tsx
+// pseudo-code — adapt to the project's framework
+const variant = searchParams.get('variant') ?? 'A';
+return (
+  <>
+    {variant === 'A' && <VariantA {...data} />}
+    {variant === 'B' && <VariantB {...data} />}
+    {variant === 'C' && <VariantC {...data} />}
+    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
+  </>
+);
+```
+
+For sub-shape A (existing page): keep all the existing data fetching above the switcher; only the rendered subtree changes per variant.
+
+For sub-shape B (new page): the throwaway route under `/prototype/<name>` mounts the same switcher.
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-centre of the screen with three pieces:
+
+- **Left arrow** — cycles to the previous variant (wraps around).
+- **Variant label** — shows the current variant key and, if the variant exports a name, that name too. e.g. `B — Sidebar layout`.
+- **Right arrow** — cycles forward (wraps around).
+
+Behaviour:
+
+- Clicking an arrow updates the URL search param (use the framework's router — `router.replace` on Next, `navigate` on React Router, etc) so the variant is shareable and reload-stable.
+- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
+- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
+- Hidden in production builds — gate on `process.env.NODE_ENV !== 'production'` or an equivalent check, so a stray prototype merge can't ship the bar to users.
+
+Put the switcher in a single shared component so both sub-shapes can reuse it. Locate it wherever shared UI lives in the project.
+
+### 5. Hand it over
+
+Surface the URL (and the `?variant=` keys). The user will flip through whenever they get to it. The interesting feedback is usually **"I want the header from B with the sidebar from C"** — that's the actual design they want.
+
+### 6. Capture the answer and clean up
+
+Once a variant has won, write down which one and why (commit message, ADR, issue, or a `NOTES.md` next to the prototype if running AFK and the user hasn't responded yet). Then:
+
+- **Sub-shape A** — delete the losing variants and the switcher; fold the winner into the existing page.
+- **Sub-shape B** — promote the winning variant to a real route, delete the throwaway route and the switcher.
+
+Don't leave variant components or the switcher lying around. They rot fast and confuse the next reader.
+
+## Anti-patterns
+
+- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
+- **Sharing too much code between variants.** A shared `<Header>` is fine; a shared `<Layout>` defeats the point. Each variant should be free to throw out the layout.
+- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub — the question is "what should this look like", not "does the backend work".
+- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

.agents/skills/qa/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: qa
+description: Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, file issues conversationally, or mentions "QA session".
+---
+
+# QA Session
+
+Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and file GitHub issues that are durable, user-focused, and use the project's domain language.
+
+## For each issue the user raises
+
+### 1. Listen and lightly clarify
+
+Let the user describe the problem in their own words. Ask **at most 2-3 short clarifying questions** focused on:
+
+- What they expected vs what actually happened
+- Steps to reproduce (if not obvious)
+- Whether it's consistent or intermittent
+
+Do NOT over-interview. If the description is clear enough to file, move on.
+
+### 2. Explore the codebase in the background
+
+While talking to the user, kick off an Agent (subagent_type=Explore) in the background to understand the relevant area. The goal is NOT to find a fix — it's to:
+
+- Learn the domain language used in that area (check UBIQUITOUS_LANGUAGE.md)
+- Understand what the feature is supposed to do
+- Identify the user-facing behavior boundary
+
+This context helps you write a better issue — but the issue itself should NOT reference specific files, line numbers, or internal implementation details.
+
+### 3. Assess scope: single issue or breakdown?
+
+Before filing, decide whether this is a **single issue** or needs to be **broken down** into multiple issues.
+
+Break down when:
+
+- The fix spans multiple independent areas (e.g. "the form validation is wrong AND the success message is missing AND the redirect is broken")
+- There are clearly separable concerns that different people could work on in parallel
+- The user describes something that has multiple distinct failure modes or symptoms
+
+Keep as a single issue when:
+
+- It's one behavior that's wrong in one place
+- The symptoms are all caused by the same root behavior
+
+### 4. File the GitHub issue(s)
+
+Create issues with `gh issue create`. Do NOT ask the user to review first — just file and share URLs.
+
+Issues must be **durable** — they should still make sense after major refactors. Write from the user's perspective.
+
+#### For a single issue
+
+Use this template:
+
+```
+## What happened
+
+[Describe the actual behavior the user experienced, in plain language]
+
+## What I expected
+
+[Describe the expected behavior]
+
+## Steps to reproduce
+
+1. [Concrete, numbered steps a developer can follow]
+2. [Use domain terms from the codebase, not internal module names]
+3. [Include relevant inputs, flags, or configuration]
+
+## Additional context
+
+[Any extra observations from the user or from codebase exploration that help frame the issue — e.g. "this only happens when using the Docker layer, not the filesystem layer" — use domain language but don't cite files]
+```
+
+#### For a breakdown (multiple issues)
+
+Create issues in dependency order (blockers first) so you can reference real issue numbers.
+
+Use this template for each sub-issue:
+
+```
+## Parent issue
+
+#<parent-issue-number> (if you created a tracking issue) or "Reported during QA session"
+
+## What's wrong
+
+[Describe this specific behavior problem — just this slice, not the whole report]
+
+## What I expected
+
+[Expected behavior for this specific slice]
+
+## Steps to reproduce
+
+1. [Steps specific to THIS issue]
+
+## Blocked by
+
+- #<issue-number> (if this issue can't be fixed until another is resolved)
+
+Or "None — can start immediately" if no blockers.
+
+## Additional context
+
+[Any extra observations relevant to this slice]
+```
+
+When creating a breakdown:
+
+- **Prefer many thin issues over few thick ones** — each should be independently fixable and verifiable
+- **Mark blocking relationships honestly** — if issue B genuinely can't be tested until issue A is fixed, say so. If they're independent, mark both as "None — can start immediately"
+- **Create issues in dependency order** so you can reference real issue numbers in "Blocked by"
+- **Maximize parallelism** — the goal is that multiple people (or agents) can grab different issues simultaneously
+
+#### Rules for all issue bodies
+
+- **No file paths or line numbers** — these go stale
+- **Use the project's domain language** (check UBIQUITOUS_LANGUAGE.md if it exists)
+- **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws on line 42"
+- **Reproduction steps are mandatory** — if you can't determine them, ask the user
+- **Keep it concise** — a developer should be able to read the issue in 30 seconds
+
+After filing, print all issue URLs (with blocking relationships summarized) and ask: "Next issue, or are we done?"
+
+### 5. Continue the session
+
+Keep going until the user says they're done. Each issue is independent — don't batch them.

.agents/skills/request-refactor-plan/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: request-refactor-plan
+description: Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
+---
+
+This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.
+
+1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
+
+2. Explore the repo to verify their assertions and understand the current state of the codebase.
+
+3. Ask whether they have considered other options, and present other options to them.
+
+4. Interview the user about the implementation. Be extremely detailed and thorough.
+
+5. Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change.
+
+6. Look in the codebase to check for test coverage of this area of the codebase. If there is insufficient test coverage, ask the user what their plans for testing are.
+
+7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice to "make each refactoring step as small as possible, so that you can always see the program working."
+
+8. Create a GitHub issue with the refactor plan. Use the following template for the issue description:
+
+<refactor-plan-template>
+
+## Problem Statement
+
+The problem that the developer is facing, from the developer's perspective.
+
+## Solution
+
+The solution to the problem, from the developer's perspective.
+
+## Commits
+
+A LONG, detailed implementation plan. Write the plan in plain English, breaking down the implementation into the tiniest commits possible. Each commit should leave the codebase in a working state.
+
+## Decision Document
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this refactor.
+
+## Further Notes (optional)
+
+Any further notes about the refactor.
+
+</refactor-plan-template>

.agents/skills/research/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: research
+description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.
+---
+
+Spin up a **background agent** to do the research, so you keep working while it reads.
+
+Its job:
+
+1. Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow every claim back to the source that owns it.
+2. Write the findings to a single Markdown file, citing each claim's source.
+3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.

.agents/skills/resolving-merge-conflicts/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: resolving-merge-conflicts
+description: "Use when you need to resolve an in-progress git merge/rebase conflict."
+---
+
+1. **See the current state** of the merge/rebase. Check git history, and the conflicting files.
+
+2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets.
+
+3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`.
+
+4. Discover the project's **automated checks** and run them — typically typecheck, then tests, then format. Fix anything the merge broke.
+
+5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased.

.agents/skills/review/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: review
+description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
+---
+
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards** — does the code conform to this repo's documented coding standards?
+- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
+
+Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+
+The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
+
+## Process
+
+### 1. Pin the fixed point
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
+
+Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+
+Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.
+
+### 2. Identify the spec source
+
+Look for the originating spec, in this order:
+
+1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
+2. A path the user passed as an argument.
+3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
+4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
+
+### 3. Identify the standards sources
+
+Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
+
+### 4. Spawn both sub-agents in parallel
+
+Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
+
+**Standards sub-agent prompt** — include:
+
+- The full diff command and commit list.
+- The list of standards-source files you found in step 3.
+- The brief: "Report — per file/hunk where relevant — every place the diff violates a documented standard. Cite the standard (file + the rule). Distinguish hard violations from judgement calls. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** — include:
+
+- The diff command and commit list.
+- The path or fetched contents of the spec.
+- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+If the spec is missing, skip the Spec sub-agent and note this in the final report.
+
+### 5. Aggregate
+
+Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
+
+End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
+- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.

.agents/skills/scaffold-exercises/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: scaffold-exercises
+description: Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
+---
+
+# Scaffold Exercises
+
+Create exercise directory structures that pass `pnpm ai-hero-cli internal lint`, then commit with `git commit`.
+
+## Directory naming
+
+- **Sections**: `XX-section-name/` inside `exercises/` (e.g., `01-retrieval-skill-building`)
+- **Exercises**: `XX.YY-exercise-name/` inside a section (e.g., `01.03-retrieval-with-bm25`)
+- Section number = `XX`, exercise number = `XX.YY`
+- Names are dash-case (lowercase, hyphens)
+
+## Exercise variants
+
+Each exercise needs at least one of these subfolders:
+
+- `problem/` - student workspace with TODOs
+- `solution/` - reference implementation
+- `explainer/` - conceptual material, no TODOs
+
+When stubbing, default to `explainer/` unless the plan specifies otherwise.
+
+## Required files
+
+Each subfolder (`problem/`, `solution/`, `explainer/`) needs a `readme.md` that:
+
+- Is **not empty** (must have real content, even a single title line works)
+- Has no broken links
+
+When stubbing, create a minimal readme with a title and a description:
+
+```md
+# Exercise Title
+
+Description here
+```
+
+If the subfolder has code, it also needs a `main.ts` (>1 line). But for stubs, a readme-only exercise is fine.
+
+## Workflow
+
+1. **Parse the plan** - extract section names, exercise names, and variant types
+2. **Create directories** - `mkdir -p` for each path
+3. **Create stub readmes** - one `readme.md` per variant folder with a title
+4. **Run lint** - `pnpm ai-hero-cli internal lint` to validate
+5. **Fix any errors** - iterate until lint passes
+
+## Lint rules summary
+
+The linter (`pnpm ai-hero-cli internal lint`) checks:
+
+- Each exercise has subfolders (`problem/`, `solution/`, `explainer/`)
+- At least one of `problem/`, `explainer/`, or `explainer.1/` exists
+- `readme.md` exists and is non-empty in the primary subfolder
+- No `.gitkeep` files
+- No `speaker-notes.md` files
+- No broken links in readmes
+- No `pnpm run exercise` commands in readmes
+- `main.ts` required per subfolder unless it's readme-only
+
+## Moving/renaming exercises
+
+When renumbering or moving exercises:
+
+1. Use `git mv` (not `mv`) to rename directories - preserves git history
+2. Update the numeric prefix to maintain order
+3. Re-run lint after moves
+
+Example:
+
+```bash
+git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
+```
+
+## Example: stubbing from a plan
+
+Given a plan like:
+
+```
+Section 05: Memory Skill Building
+- 05.01 Introduction to Memory
+- 05.02 Short-term Memory (explainer + problem + solution)
+- 05.03 Long-term Memory
+```
+
+Create:
+
+```bash
+mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
+mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
+mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer
+```
+
+Then create readme stubs:
+
+```
+exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory"
+```

.agents/skills/setup-matt-pocock-skills/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: setup-matt-pocock-skills
+description: Configure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
+disable-model-invocation: true
+---
+
+# Setup Matt Pocock's Skills
+
+Scaffold the per-repo configuration that the engineering skills assume:
+
+- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box)
+- **Triage labels** — the strings used for the five canonical triage roles
+- **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
+
+This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
+
+## Process
+
+### 1. Explore
+
+Look at the current repo to understand its starting state. Read whatever exists; don't assume:
+
+- `git remote -v` and `.git/config` — is this a GitHub repo? Which one?
+- `AGENTS.md` and `CLAUDE.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either?
+- `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root
+- `docs/adr/` and any `src/*/docs/adr/` directories
+- `docs/agents/` — does this skill's prior output already exist?
+- `.scratch/` — sign that a local-markdown issue tracker convention is already in use
+
+### 2. Present findings and ask
+
+Summarise what's present and what's missing. Then walk the user through the three decisions **one at a time** — present a section, get the user's answer, then move to the next. Don't dump all three at once.
+
+Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.
+
+**Section A — Issue tracker.**
+
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, `to-spec`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+
+Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
+
+- **GitHub** — issues live in the repo's GitHub Issues (uses the `gh` CLI)
+- **GitLab** — issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI)
+- **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
+- **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
+
+If — and only if — the user picked **GitHub** or **GitLab**, ask one follow-up:
+
+> Explainer: Open-source repos often receive feature requests as pull requests, not just issues — a PR is an issue with attached code. If you turn this on, `/triage` pulls *external* PRs into the same queue and runs them through the same labels and states as issues (collaborators' in-flight PRs are left alone). Leave it off if PRs aren't a request surface for you.
+
+- **PRs as a request surface** — yes / no (default: no). Record the answer in `docs/agents/issue-tracker.md`. For local-markdown and other trackers, skip this question — there are no PRs.
+
+**Section B — Triage label vocabulary.**
+
+> Explainer: When the `triage` skill processes an incoming issue, it moves it through a state machine — needs evaluation, waiting on reporter, ready for an AFK agent to pick up, ready for a human, or won't fix. To do that, it needs to apply labels (or the equivalent in your issue tracker) that match strings *you've actually configured*. If your repo already uses different label names (e.g. `bug:triage` instead of `needs-triage`), map them here so the skill applies the right ones instead of creating duplicates.
+
+The five canonical roles:
+
+- `needs-triage` — maintainer needs to evaluate
+- `needs-info` — waiting on reporter
+- `ready-for-agent` — fully specified, AFK-ready (an agent can pick it up with no human context)
+- `ready-for-human` — needs human implementation
+- `wontfix` — will not be actioned
+
+Default: each role's string equals its name. Ask the user if they want to override any. If their issue tracker has no existing labels, the defaults are fine.
+
+**Section C — Domain docs.**
+
+> Explainer: Some skills (`improve-codebase-architecture`, `diagnosing-bugs`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.
+
+Confirm the layout:
+
+- **Single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Most repos are this.
+- **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo).
+
+### 3. Confirm and edit
+
+Show the user a draft of:
+
+- The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
+- The contents of `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md`
+
+Let them edit before writing.
+
+### 4. Write
+
+**Pick the file to edit:**
+
+- If `CLAUDE.md` exists, edit it.
+- Else if `AGENTS.md` exists, edit it.
+- If neither exists, ask the user which one to create — don't pick for them.
+
+Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa) — always edit the one that's already there.
+
+If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
+
+The block:
+
+```markdown
+## Agent skills
+
+### Issue tracker
+
+[one-line summary of where issues are tracked, plus whether external PRs are a triage surface]. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.
+```
+
+Then write the three docs files using the seed templates in this skill folder as a starting point:
+
+- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
+- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
+- [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker
+- [triage-labels.md](./triage-labels.md) — label mapping
+- [domain.md](./domain.md) — domain doc consumer rules + layout
+
+For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.
+
+### 5. Done
+
+Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.

.agents/skills/setup-matt-pocock-skills/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md

@@ -0,0 +1,45 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md

@@ -0,0 +1,46 @@
+# Issue tracker: GitLab
+
+Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `glab issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor.
+- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output.
+- **List issues**: `glab issue list -F json` with appropriate `--label` filters.
+- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes".
+- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
+- **Close**: `glab issue close <number>`. `glab issue close` does not accept a closing comment, so post the explanation first with `glab issue note <number> --message "..."`, then close.
+- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create`, `glab mr view`, `glab mr note`, etc. — the same shape as `gh pr ...` with `mr` in place of `pr` and `note`/`--message` in place of `comment`/`--body`.
+
+Infer the repo from `git remote -v` — `glab` does this automatically when run inside a clone.
+
+## Merge requests as a triage surface
+
+**MRs as a request surface: no.** _(Set to `yes` if this repo treats external merge requests as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, MRs run through the same labels and states as issues, using the `glab mr` equivalents:
+
+- **Read an MR**: `glab mr view <number> --comments` and `glab mr diff <number>` for the diff.
+- **List external MRs for triage**: `glab mr list -F json`, then keep only MRs whose author is not a project member/owner (a contributor's MR, not a maintainer's in-flight work).
+- **Comment / label / close**: `glab mr note`, `glab mr update --label`/`--unlabel`, `glab mr close`.
+
+Unlike GitHub, GitLab numbers issues and MRs separately, so `#42` is unambiguous once you know which surface the maintainer means.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitLab issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `glab issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `glab issue create --label wayfinder:map`. (On GitLab tiers with native epics, an epic may hold the map instead; a labelled issue works everywhere.)
+- **Child ticket**: an issue carrying `Part of #<map>` at the top of its description and labels `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitLab's **native blocking link** — the canonical, UI-visible representation. Add it with the `/blocked_by #<n>` quick action, posted as a note (`glab issue note <child> --message "/blocked_by #<blocker>"`). Native blocking links are a Premium/Ultimate feature; on the free tier (or where unavailable) fall back to a `Blocked by: #<n>, #<n>` line at the top of the description. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: `glab issue list -F json` scoped to the map's children, drop any with an open blocker — a native `blocked_by` link to an open issue (`glab api projects/:id/issues/:iid/links`), or an open issue in the `Blocked by` line — or an assignee; first in map order wins.
+- **Claim**: `glab issue update <n> --assignee @me` — the session's first write.
+- **Resolve**: `glab issue note <n> --message "<answer>"`, then `glab issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md

@@ -0,0 +1,30 @@
+# Issue tracker: Local Markdown
+
+Issues and PRDs for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The PRD is `.scratch/<feature-slug>/PRD.md`
+- Implementation issues are `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
+
+- **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
+- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.

.agents/skills/setup-matt-pocock-skills/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

.agents/skills/setup-pre-commit/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: setup-pre-commit
+description: Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.
+---
+
+# Setup Pre-Commit Hooks
+
+## What This Sets Up
+
+- **Husky** pre-commit hook
+- **lint-staged** running Prettier on all staged files
+- **Prettier** config (if missing)
+- **typecheck** and **test** scripts in the pre-commit hook
+
+## Steps
+
+### 1. Detect package manager
+
+Check for `package-lock.json` (npm), `pnpm-lock.yaml` (pnpm), `yarn.lock` (yarn), `bun.lockb` (bun). Use whichever is present. Default to npm if unclear.
+
+### 2. Install dependencies
+
+Install as devDependencies:
+
+```
+husky lint-staged prettier
+```
+
+### 3. Initialize Husky
+
+```bash
+npx husky init
+```
+
+This creates `.husky/` dir and adds `prepare: "husky"` to package.json.
+
+### 4. Create `.husky/pre-commit`
+
+Write this file (no shebang needed for Husky v9+):
+
+```
+npx lint-staged
+npm run typecheck
+npm run test
+```
+
+**Adapt**: Replace `npm` with detected package manager. If repo has no `typecheck` or `test` script in package.json, omit those lines and tell the user.
+
+### 5. Create `.lintstagedrc`
+
+```json
+{
+  "*": "prettier --ignore-unknown --write"
+}
+```
+
+### 6. Create `.prettierrc` (if missing)
+
+Only create if no Prettier config exists. Use these defaults:
+
+```json
+{
+  "useTabs": false,
+  "tabWidth": 2,
+  "printWidth": 80,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "semi": true,
+  "arrowParens": "always"
+}
+```
+
+### 7. Verify
+
+- [ ] `.husky/pre-commit` exists and is executable
+- [ ] `.lintstagedrc` exists
+- [ ] `prepare` script in package.json is `"husky"`
+- [ ] `prettier` config exists
+- [ ] Run `npx lint-staged` to verify it works
+
+### 8. Commit
+
+Stage all changed/created files and commit with message: `Add pre-commit hooks (husky + lint-staged + prettier)`
+
+This will run through the new pre-commit hooks — a good smoke test that everything works.
+
+## Notes
+
+- Husky v9+ doesn't need shebangs in hook files
+- `prettier --ignore-unknown` skips files Prettier can't parse (images, etc.)
+- The pre-commit runs lint-staged first (fast, staged-only), then full typecheck and tests

.agents/skills/tdd/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: tdd
+description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
+---
+
+# Test-Driven Development
+
+TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
+
+## What a good test is
+
+Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Seams — where tests go
+
+A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
+
+**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
+
+Ask: "What's the public interface, and which seams should we test?"
+
+## Anti-patterns
+
+- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
+- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
+
+## Rules of the loop
+
+- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
+- **Refactoring is not part of the loop.** It belongs to the review stage (see the `code-review` skill), not the red → green implementation cycle.

.agents/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

.agents/skills/tdd/tests.md

@@ -0,0 +1,77 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```

.agents/skills/teach/GLOSSARY-FORMAT.md

@@ -0,0 +1,35 @@
+# GLOSSARY.md Format
+
+`GLOSSARY.md` is the canonical language for this teaching workspace. All explainers, exercises, and learning records should adhere to its terminology. Building it is itself part of learning: compressing a concept into a tight definition is evidence the user understands it.
+
+## Structure
+
+```md
+# {Topic} Glossary
+
+{One or two sentence description of the topic this glossary covers.}
+
+## Terms
+
+**Hypertrophy**:
+Muscle growth driven by mechanical tension and metabolic stress over repeated training sessions.
+_Avoid_: Bulking, getting big
+
+**Progressive overload**:
+Systematically increasing the demand on a muscle over time — via load, volume, or intensity.
+_Avoid_: Pushing harder, levelling up
+
+**RPE (Rate of Perceived Exertion)**:
+A 1–10 self-rating of how hard a set felt, where 10 is failure and 8 means two reps left in the tank.
+_Avoid_: Effort score, intensity rating
+```
+
+## Rules
+
+- **Add a term only when the user understands it.** The glossary is a record of compressed knowledge, not a dictionary the user reads to learn. If the user has just been introduced to a concept, wait until they can use it correctly before promoting it here.
+- **Be opinionated.** When several words exist for the same concept, pick the best one and list the rest as aliases to avoid. This is how language compresses.
+- **Keep definitions tight.** One or two sentences. Define what the term IS, not what it does or how to do it.
+- **Use the glossary's own terms inside definitions.** Once a term is in the glossary, prefer it everywhere — including inside other definitions. This is what makes complex terms easier to grasp later.
+- **Group under subheadings** when natural clusters emerge (e.g. `## Anatomy`, `## Programming`). A flat list is fine when terms cohere.
+- **Flag ambiguities explicitly.** If a term is used loosely in the wider field, note the resolution: "In this workspace, 'set' always means a working set — warm-ups are tracked separately."
+- **Revise as understanding deepens.** A definition the user wrote in week one may be wrong by week six. Update in place; do not leave stale entries.

.agents/skills/teach/LEARNING-RECORD-FORMAT.md

@@ -0,0 +1,46 @@
+# Learning Record Format
+
+Learning records live in `./learning-records/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc. Create the directory lazily — only when the first record is written.
+
+They are the teaching equivalent of ADRs: they capture non-obvious lessons, key insights, and stated prior knowledge that will steer future sessions. They are used to calculate the zone of proximal development.
+
+## Template
+
+```md
+# {Short title of what was learned or established}
+
+{1-3 sentences: what was learned (or what prior knowledge was established), and why it matters for future sessions.}
+```
+
+That is the whole format. A learning record can be a single paragraph. The value is recording _that_ this is now known and _why_ it changes what to teach next — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most records won't need them.
+
+- **Status** frontmatter (`active | superseded by LR-NNNN`) — useful when an earlier understanding turns out to be wrong and is replaced.
+- **Evidence** — how the user demonstrated the understanding (a question answered, an exercise completed, prior experience cited). Useful when the claim might be revisited.
+- **Implications** — what this unlocks or rules out for future sessions. Worth recording when non-obvious.
+
+## Numbering
+
+Scan `./learning-records/` for the highest existing number and increment by one.
+
+## When to write a learning record
+
+Write one when any of these is true:
+
+1. **The user demonstrated genuine understanding of something non-trivial** — not just exposure, but evidence they can use the concept correctly. This sets a new floor for what to teach next.
+2. **The user disclosed prior knowledge** — "I already know X." Record it so future sessions don't re-teach it. Also record the _depth_ claimed.
+3. **A misconception was corrected** — the user previously believed something wrong and now sees why. These are high-value: they predict future stumbling blocks for related topics.
+4. **The mission shifted in response to learning** — the user discovered they cared about something different than they thought. Cross-link to [[MISSION.md]] and update it.
+
+### What does _not_ qualify
+
+- Material that was merely covered. Coverage is not learning. Wait for evidence.
+- Anything already captured tersely in [[GLOSSARY.md]] as a term definition. Don't duplicate.
+- Session-by-session activity logs. Learning records are not a journal — they are decision-grade insights.
+
+## Supersession
+
+When a later record contradicts an earlier one (the user's understanding deepened or corrected), mark the old record `Status: superseded by LR-NNNN` rather than deleting it. The history of how understanding evolved is itself useful signal.

.agents/skills/teach/MISSION-FORMAT.md

@@ -0,0 +1,31 @@
+# MISSION.md Format
+
+`MISSION.md` lives at the workspace root. It captures the _reason_ the user is learning this topic. Every teaching decision — what to teach next, which resources to surface, which exercises to design — should trace back to this document.
+
+## Template
+
+```md
+# Mission: {Topic}
+
+## Why
+{1-3 sentences. The concrete real-world goal the user is chasing. What changes in their life or work when they have this skill? Avoid abstract framings like "to understand X" — push for the underlying outcome.}
+
+## Success looks like
+- {A specific, observable thing the user will be able to do}
+- {Another specific thing}
+- {…}
+
+## Constraints
+- {Time, budget, prior commitments, learning preferences, anything that bounds the approach}
+
+## Out of scope
+- {Adjacent topics the user explicitly does not want to chase right now — protects the zone of proximal development}
+```
+
+## Rules
+
+- **One mission per workspace.** If the user wants to learn two unrelated things, that is two workspaces.
+- **Concrete over abstract.** "Run a half marathon by October" beats "get fitter." "Ship a Rust CLI to my team" beats "learn Rust."
+- **Push back on vagueness.** If the user cannot articulate why, interview them before writing anything. A bad mission is worse than no mission.
+- **Revise when reality shifts.** Missions change. When the user's goal moves, update this file — don't leave a stale mission steering future sessions.
+- **Keep it short.** If `MISSION.md` runs past a screen, it has stopped being a compass and started being a plan.

.agents/skills/teach/RESOURCES-FORMAT.md

@@ -0,0 +1,32 @@
+# RESOURCES.md Format
+
+`RESOURCES.md` is the curated set of trusted sources for this topic. Knowledge for explainers should be drawn from here, not from parametric guesses. Wisdom comes from the communities listed here.
+
+## Structure
+
+```md
+# {Topic} Resources
+
+## Knowledge
+
+- [Book: _The Science and Practice of Strength Training_ — Zatsiorsky & Kraemer](https://example.com)
+  Foundational text on programming and adaptation. Use for: anything to do with periodisation, recovery, intensity zones.
+- [Article: "How Much Should I Train?" — Greg Nuckols (Stronger By Science)](https://example.com)
+  Evidence-based review of volume landmarks. Use for: weekly set targets per muscle group.
+
+## Wisdom (Communities)
+
+- [r/weightroom](https://reddit.com/r/weightroom)
+  High-signal subreddit, moderated against bro-science. Use for: programme critique, plateau troubleshooting.
+- Local: Tuesday strength class at {gym name}
+  Use for: real-time coaching feedback on lifts.
+```
+
+## Rules
+
+- **High-trust only.** Prefer primary sources, recognised experts, peer-reviewed work, and communities with strong moderation. If a resource is marketing dressed as education, leave it out.
+- **Annotate every entry.** A bare link is useless in three months. Add one line: what it covers and when to reach for it.
+- **Group by Knowledge / Wisdom.** Mirrors the philosophy in [SKILL.md](./SKILL.md). It is fine for a resource to appear in only one group.
+- **Surface gaps explicitly.** If no good resource exists for an area the mission needs, write a `## Gaps` section listing what is missing. This drives future search.
+- **Prune ruthlessly.** A resource that turned out to be wrong, shallow, or off-mission should be removed, not buried. Better five sharp sources than thirty mediocre ones.
+- **Record community preferences.** If the user has opted out of joining communities, note it here so future sessions don't keep proposing them.

.agents/skills/teach/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: teach
+description: Teach the user a new skill or concept, within this workspace.
+disable-model-invocation: true
+argument-hint: "What would you like to learn about?"
+---
+
+The user has asked you to teach them something. This is a stateful request - they intend to learn the topic over multiple sessions.
+
+## Teaching Workspace
+
+Treat the current directory as a teaching workspace. The state of their learning is captured in this directory in several files:
+
+- `MISSION.md`: A document capturing the _reason_ the user is interested in the topic. This should be used to ground all teaching. Use the format in [MISSION-FORMAT.md](./MISSION-FORMAT.md).
+- `./reference/*.html`: A directory of reference materials. These are the compressed learnings from the lessons - cheat sheets, reference algorithms, syntax, yoga poses, glossaries. They are the raw units of learning. They should be beautiful documents which print out well, and are designed for quick reference.
+- `RESOURCES.md`: A list of resources which can be explored to ground your teaching in contextual knowledge, or to acquire knowledge and wisdom. Use the format in [RESOURCES-FORMAT.md](./RESOURCES-FORMAT.md).
+- `./learning-records/*.md`: A directory of learning records, which capture what the user has learned. These are loosely equivalent to architectural decision records in software development - they capture non-obvious lessons and key insights that may need to be revised later, or drive future sessions. These should be used to calculate the zone of proximal development. They are titled `0001-<dash-case-name>.md`, where the number increments each time. Use the format in [LEARNING-RECORD-FORMAT.md](./LEARNING-RECORD-FORMAT.md).
+- `./lessons/*.html`: A directory of lessons. A **lesson** is a single, self-contained HTML output that teaches one tightly-scoped thing tied to the mission. This is the primary unit of teaching in this workspace.
+- `./assets/*`: Reusable **components** shared across lessons. See [Assets](#assets).
+- `NOTES.md`: A scratchpad for you to jot down user preferences, or working notes.
+
+## Philosophy
+
+To learn at a deep level, the user needs three things:
+
+- **Knowledge**, captured from high-quality, high-trust resources
+- **Skills**, acquired through highly-relevant interactive lessons devised by you, based on the knowledge
+- **Wisdom**, which comes from interacting with other learners and practitioners
+
+Before the `RESOURCES.md` is well-populated, your focus should be to find high-quality resources which will help the user acquire knowledge. Never trust your parametric knowledge.
+
+Some topics may require more skills than knowledge. Learning more about theoretical physics might be more knowledge-based. For yoga, more skills-based.
+
+### Fluency vs Storage Strength
+
+You should be careful to split between two types of learning:
+
+- **Fluency strength**: in-the-moment retrieval of knowledge
+- **Storage strength**: long-term retention of knowledge
+
+Fluency can give the user an illusory sense of mastery, but storage strength is the real goal. Try to design lessons which build long-term retention by desirable difficulty:
+
+- Using retrieval practice (recall from memory)
+- Spacing (distributing practice over time)
+- Interleaving (mixing up different but related topics in practice - for skills practice only)
+
+## Lessons
+
+A lesson is the main thing you produce — the unit in which knowledge and skills reach the user. Each lesson is one self-contained HTML file, saved to `./lessons/` and titled `0001-<dash-case-name>.html` where the number increments each time.
+
+A lesson should be **beautiful** — clean, readable typography and layout — since the user will return to these later to review. Think Tufte.
+
+The lesson should be short, and completable very quickly. Learners' working memory is very small, and we need to stay within it. But each lesson should give the user a single tangible win that they can build on. It should be directly tied to the mission, and should be in the user's zone of proximal development.
+
+If possible, open the lesson file for the user by running a CLI command.
+
+Each lesson should link via HTML anchors to other lessons and reference documents.
+
+Each lesson should recommend a primary source for the user to read or watch. This should be the most high-quality, high-trust resource you found on the topic.
+
+Each lesson should contain a reminder to ask followup questions to the agent. The agent is their teacher, and can assist with anything that's unclear.
+
+## Assets
+
+Lessons are built from reusable **components**, stored in `./assets/`: stylesheets, quiz widgets, simulators, diagram helpers — anything a second lesson could reuse.
+
+Reuse is the default, not the exception. Before authoring a lesson, read `./assets/` and build from the components already there. When a lesson needs something new and reusable, write it as a component in `./assets/` and link to it — never inline code a future lesson would duplicate.
+
+A shared stylesheet is the first component every workspace earns: every lesson links it, so the lessons look like one consistent course rather than a pile of one-offs. As the workspace grows, so should the component library.
+
+## The Mission
+
+Every lesson should be tied into the mission - the reason that the user is interested in learning about the topic.
+
+If the user is unclear about the mission, or the `MISSION.md` is not populated, your first job should be to question the user on why they want to learn this.
+
+Failing to understand the mission will mean knowledge acquisition is not grounded in real-world goals. Lessons will feel too abstract. You will have no way of judging what the user should do next.
+
+Missions may change as the user develops more skills and knowledge. This is normal - make sure to update the `MISSION.md` and add a learning record to capture the change. Confirm with the user before changing the mission.
+
+## Zone Of Proximal Development
+
+Each lesson, the user should always feel as if they are being challenged 'just enough'.
+
+The user may specify an exact thing they want to learn. If they don't, figure out their zone of proximal development by:
+
+- Reading their `learning-records`
+- Figuring out the right thing to teach them based on their mission
+- Teach the most relevant thing that fits in their zone of proximal development
+
+## Knowledge
+
+Lessons should be designed around a skill the user is going to learn. The knowledge in the lesson should be only what's required to acquire that skill. You teach the knowledge first, then get the user to practice the skills via an interactive feedback loop.
+
+Knowledge should first be gathered from trusted resources. Use `RESOURCES.md` to keep track of them. Lessons should be littered with citations - links to external resources to back up any claim made. This increases the trustworthiness of the lesson.
+
+For acquiring knowledge, difficulty is the enemy. It eats working memory you need for understanding.
+
+## Skills
+
+If knowledge is all about acquisition, skills are about durability and flexibility. Make the knowledge stick.
+
+For skill acquisition, difficulty is the tool. Effortful retrieval is what builds storage strength. Skills should be taught through interactive lessons. There are several tools at your disposal:
+
+- Interactive lessons, using quizzes and light in-browser tasks
+- Lessons which guide the user through a list of real-world steps to take (for instance, yoga poses)
+
+Each of these should be based on a **feedback loop**, where the user receives feedback on their performance. This feedback loop should be as tight as possible, giving feedback immediately - and ideally automatically.
+
+For quizzes, each answer should be exactly the same number of words (and characters, if possible). Don't give the user any clues about the answer through formatting.
+
+## Acquiring Wisdom
+
+Wisdom comes from true real-world interaction - testing your skills outside the learning environment.
+
+When the user asks a question that appears to require wisdom, your default posture should be to attempt to answer - but to ultimately delegate to a **community**.
+
+A community is a place (online or offline) where the user can test their skills in the real world. This might be a forum, a subreddit, a real-world class (budget permitting) or a local interest group.
+
+You should attempt to find high-reputation communities the user can join. If the user expresses a preference that they don't want to join a community, respect it.
+
+## Reference Documents
+
+While creating lessons, you should also create reference documents. Lessons can reference these documents - they are useful for tracking raw units of knowledge useful across lessons.
+
+Lessons will rarely be revisited later - reference documents will be. They should be the compressed essence of the lesson, in a format designed for quick reference.
+
+Some learning topics lend themselves to reference:
+
+- Syntax and code snippets for programming
+- Algorithms and flowcharts for processes
+- Yoga poses and sequences for yoga
+- Exercises and routines for fitness
+- Glossaries for any topic with its own nomenclature
+
+Glossaries, in particular, are an essential reference. Once one is created, it should be adhered to in every lesson.
+
+## `NOTES.md`
+
+The user will sometimes express preferences of how they want to be taught, or things you should keep in mind. This is the place to record those preferences, so you can refer back to them when designing lessons or working with the user.

.agents/skills/to-issues/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: to-issues
+description: Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices.
+disable-model-invocation: true
+---
+
+# To Issues
+
+Break a plan into independently-grabbable issues using vertical slices (tracer bullets).
+
+The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+
+## Process
+
+### 1. Gather context
+
+Work from whatever is already in the conversation context. If the user passes an issue reference (issue number, URL, or path) as an argument, fetch it from the issue tracker and read its full body and comments.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code. Issue titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
+
+Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
+
+### 3. Draft vertical slices
+
+Break the plan into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.
+
+<vertical-slice-rules>
+
+- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests)
+- A completed slice is demoable or verifiable on its own
+- Any prefactoring should be done first
+
+</vertical-slice-rules>
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each slice, show:
+
+- **Title**: short descriptive name
+- **Blocked by**: which other slices (if any) must complete first
+- **User stories covered**: which user stories this addresses (if the source material has them)
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the dependency relationships correct?
+- Should any slices be merged or split further?
+
+Iterate until the user approves the breakdown.
+
+### 5. Publish the issues to the issue tracker
+
+For each approved slice, publish a new issue to the issue tracker. Use the issue body template below. These issues are considered ready for AFK agents, so publish them with the correct triage label unless instructed otherwise.
+
+Publish issues in dependency order (blockers first) so you can reference real issue identifiers in the "Blocked by" field.
+
+<issue-template>
+## Parent
+
+A reference to the parent issue on the issue tracker (if the source was an existing issue, otherwise omit this section).
+
+## What to build
+
+A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation.
+
+Avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it here and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Blocked by
+
+- A reference to the blocking ticket (if any)
+
+Or "None - can start immediately" if no blockers.
+
+</issue-template>
+
+Do NOT close or modify any parent issue.

.agents/skills/to-prd/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: to-prd
+description: Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
+disable-model-invocation: true
+---
+
+This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know.
+
+The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+
+## Process
+
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching.
+
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
+
+Check with the user that these seams match their expectations.
+
+3. Write the PRD using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
+
+<prd-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this PRD.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</prd-template>

.agents/skills/to-spec/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: to-spec
+description: Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
+disable-model-invocation: true
+---
+
+This skill takes the current conversation context and codebase understanding and produces a spec (you may know this document as a PRD). Do NOT interview the user — just synthesize what you already know.
+
+The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+
+## Process
+
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.
+
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
+
+Check with the user that these seams match their expectations.
+
+3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
+
+<spec-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this spec.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</spec-template>

.agents/skills/to-tickets/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: to-tickets
+description: Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker — edges as text in a local file, or native blocking links on a real tracker.
+disable-model-invocation: true
+---
+
+# To Tickets
+
+Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it.
+
+The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+
+## Process
+
+### 1. Gather context
+
+Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code. Ticket titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
+
+Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
+
+### 3. Draft vertical slices
+
+Break the work into **tracer bullet** tickets.
+
+<vertical-slice-rules>
+
+- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer
+- A completed slice is demoable or verifiable on its own
+- Each slice is sized to fit in a single fresh context window
+- Any prefactoring should be done first
+
+</vertical-slice-rules>
+
+Give each ticket its **blocking edges** — the other tickets that must complete before it can start. A ticket with no blockers can start immediately.
+
+**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there.
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each ticket, show:
+
+- **Title**: short descriptive name
+- **Blocked by**: which other tickets (if any) must complete first
+- **What it delivers**: the end-to-end behaviour this ticket makes work
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the blocking edges correct — does each ticket only depend on tickets that genuinely gate it?
+- Should any tickets be merged or split further?
+
+Iterate until the user approves the breakdown.
+
+### 5. Publish the tickets to the configured tracker
+
+Publish the approved tickets. **How** depends on the tracker `/setup-matt-pocock-skills` configured — the tickets are the same either way, only the shape of the blocking edges changes:
+
+- **Local files** → write one `tickets.md` in the repo root, all tickets in dependency order (blockers first), each with its "Blocked by" listing the titles it depends on. Use the file template below.
+- **A real issue tracker (GitHub, Linear, …)** → publish one issue per ticket in dependency order (blockers first) so each ticket's blocking edges can reference real identifiers. Use the platform's native blocking / sub-issue relationship where it has one; otherwise set each ticket's "Blocked by" to the blocking issues. Apply the `ready-for-agent` triage label unless instructed otherwise — the tickets are agent-grabbable by construction.
+
+Do NOT close or modify any parent issue.
+
+<tickets-file-template>
+
+# Tickets: <short name of the work>
+
+A one-line summary of what these tickets build. Reference the source spec if there is one.
+
+Work the **frontier**: any ticket whose blockers are all done. For a purely linear chain that means top to bottom.
+
+## <Ticket title>
+
+**What to build:** the end-to-end behaviour this ticket makes work, from the user's perspective — not a layer-by-layer implementation list.
+
+**Blocked by:** the titles of the tickets that gate this one, or "None — can start immediately".
+
+- [ ] Acceptance criterion 1
+- [ ] Acceptance criterion 2
+
+## <Ticket title>
+
+...
+
+</tickets-file-template>
+
+<issue-template>
+
+## Parent
+
+A reference to the parent issue on the tracker (if the source was an existing issue, otherwise omit this section).
+
+## What to build
+
+The end-to-end behaviour this ticket makes work, from the user's perspective — not layer-by-layer implementation.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Blocked by
+
+- A reference to each blocking ticket, or "None — can start immediately".
+
+</issue-template>
+
+In either form, avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+Work the frontier one ticket at a time with `/implement`, clearing context between tickets.
+</content>

.agents/skills/triage/AGENT-BRIEF.md

@@ -0,0 +1,207 @@
+# Writing Agent Briefs
+
+An agent brief is a structured comment posted on a GitHub issue or PR when it moves to `ready-for-agent`. It is the authoritative specification that an AFK agent will work from. The original body and discussion are context — the agent brief is the contract.
+
+The brief states **what the agent should do**, which stretches to both surfaces: for an issue, that's building the change from nothing; for a PR, it's what's left to do *to the existing diff* — finish it, close gaps, address review points. Same principles either way; the PR example below shows the difference.
+
+## Principles
+
+### Durability over precision
+
+The issue may sit in `ready-for-agent` for days or weeks. The codebase will change in the meantime. Write the brief so it stays useful even as files are renamed, moved, or refactored.
+
+- **Do** describe interfaces, types, and behavioral contracts
+- **Do** name specific types, function signatures, or config shapes that the agent should look for or modify
+- **Don't** reference file paths — they go stale
+- **Don't** reference line numbers
+- **Don't** assume the current implementation structure will remain the same
+
+### Behavioral, not procedural
+
+Describe **what** the system should do, not **how** to implement it. The agent will explore the codebase fresh and make its own implementation decisions.
+
+- **Good:** "The `SkillConfig` type should accept an optional `schedule` field of type `CronExpression`"
+- **Bad:** "Open src/types/skill.ts and add a schedule field on line 42"
+- **Good:** "When a user runs `/triage` with no arguments, they should see a summary of issues needing attention"
+- **Bad:** "Add a switch statement in the main handler function"
+
+### Complete acceptance criteria
+
+The agent needs to know when it's done. Every agent brief must have concrete, testable acceptance criteria. Each criterion should be independently verifiable.
+
+- **Good:** "Running `gh issue list --label needs-triage` returns issues that have been through initial classification"
+- **Bad:** "Triage should work correctly"
+
+### Explicit scope boundaries
+
+State what is out of scope. This prevents the agent from gold-plating or making assumptions about adjacent features.
+
+## Template
+
+```markdown
+## Agent Brief
+
+**Category:** bug / enhancement
+**Summary:** one-line description of what needs to happen
+
+**Current behavior:**
+Describe what happens now. For bugs, this is the broken behavior.
+For enhancements, this is the status quo the feature builds on.
+
+**Desired behavior:**
+Describe what should happen after the agent's work is complete.
+Be specific about edge cases and error conditions.
+
+**Key interfaces:**
+- `TypeName` — what needs to change and why
+- `functionName()` return type — what it currently returns vs what it should return
+- Config shape — any new configuration options needed
+
+**Acceptance criteria:**
+- [ ] Specific, testable criterion 1
+- [ ] Specific, testable criterion 2
+- [ ] Specific, testable criterion 3
+
+**Out of scope:**
+- Thing that should NOT be changed or addressed in this issue
+- Adjacent feature that might seem related but is separate
+```
+
+## Examples
+
+### Good agent brief (bug)
+
+```markdown
+## Agent Brief
+
+**Category:** bug
+**Summary:** Skill description truncation drops mid-word, producing broken output
+
+**Current behavior:**
+When a skill description exceeds 1024 characters, it is truncated at exactly
+1024 characters regardless of word boundaries. This produces descriptions
+that end mid-word (e.g. "Use when the user wants to confi").
+
+**Desired behavior:**
+Truncation should break at the last word boundary before 1024 characters
+and append "..." to indicate truncation.
+
+**Key interfaces:**
+- The `SkillMetadata` type's `description` field — no type change needed,
+  but the validation/processing logic that populates it needs to respect
+  word boundaries
+- Any function that reads SKILL.md frontmatter and extracts the description
+
+**Acceptance criteria:**
+- [ ] Descriptions under 1024 chars are unchanged
+- [ ] Descriptions over 1024 chars are truncated at the last word boundary
+      before 1024 chars
+- [ ] Truncated descriptions end with "..."
+- [ ] The total length including "..." does not exceed 1024 chars
+
+**Out of scope:**
+- Changing the 1024 char limit itself
+- Multi-line description support
+```
+
+### Good agent brief (enhancement)
+
+```markdown
+## Agent Brief
+
+**Category:** enhancement
+**Summary:** Add `.out-of-scope/` directory support for tracking rejected feature requests
+
+**Current behavior:**
+When a feature request is rejected, the issue is closed with a `wontfix` label
+and a comment. There is no persistent record of the decision or reasoning.
+Future similar requests require the maintainer to recall or search for the
+prior discussion.
+
+**Desired behavior:**
+Rejected feature requests should be documented in `.out-of-scope/<concept>.md`
+files that capture the decision, reasoning, and links to all issues that
+requested the feature. When triaging new issues, these files should be
+checked for matches.
+
+**Key interfaces:**
+- Markdown file format in `.out-of-scope/` — each file should have a
+  `# Concept Name` heading, a `**Decision:**` line, a `**Reason:**` line,
+  and a `**Prior requests:**` list with issue links
+- The triage workflow should read all `.out-of-scope/*.md` files early
+  and match incoming issues against them by concept similarity
+
+**Acceptance criteria:**
+- [ ] Closing a feature as wontfix creates/updates a file in `.out-of-scope/`
+- [ ] The file includes the decision, reasoning, and link to the closed issue
+- [ ] If a matching `.out-of-scope/` file already exists, the new issue is
+      appended to its "Prior requests" list rather than creating a duplicate
+- [ ] During triage, existing `.out-of-scope/` files are checked and surfaced
+      when a new issue matches a prior rejection
+
+**Out of scope:**
+- Automated matching (human confirms the match)
+- Reopening previously rejected features
+- Bug reports (only enhancement rejections go to `.out-of-scope/`)
+```
+
+### Good agent brief (PR)
+
+For a PR, "Current behavior" describes the state of the diff, and the brief asks the agent to finish or fix it rather than build from scratch.
+
+```markdown
+## Agent Brief
+
+**Category:** enhancement
+**Summary:** Finish the contributor's `--json` output flag for `triage list`
+
+**Current behavior:**
+The PR adds a `--json` flag that serializes the issue list to JSON. The happy
+path works and the diff matches the project's command structure. Two gaps
+remain: errors are still printed as human text (not JSON), and the new flag has
+no test coverage.
+
+**Desired behavior:**
+With `--json`, all output — including errors — is well-formed JSON on stdout,
+and the command's exit codes are unchanged. The existing human-readable output
+is untouched when the flag is absent.
+
+**Key interfaces:**
+- The command's error path should emit `{ "error": string }` under `--json`
+  instead of the plain-text error
+- Reuse the existing serializer the PR already added; don't introduce a second
+
+**Acceptance criteria:**
+- [ ] `triage list --json` emits valid JSON for both success and error cases
+- [ ] Exit codes match the non-JSON command
+- [ ] A test covers the `--json` success output and one error case
+- [ ] Default (non-JSON) output is byte-for-byte unchanged
+
+**Out of scope:**
+- Adding `--json` to any other command
+- Changing the JSON shape of the success payload the PR already defined
+```
+
+### Bad agent brief
+
+```markdown
+## Agent Brief
+
+**Summary:** Fix the triage bug
+
+**What to do:**
+The triage thing is broken. Look at the main file and fix it.
+The function around line 150 has the issue.
+
+**Files to change:**
+- src/triage/handler.ts (line 150)
+- src/types.ts (line 42)
+```
+
+This is bad because:
+- No category
+- Vague description ("the triage thing is broken")
+- References file paths and line numbers that will go stale
+- No acceptance criteria
+- No scope boundaries
+- No description of current vs desired behavior

.agents/skills/triage/OUT-OF-SCOPE.md

@@ -0,0 +1,105 @@
+# Out-of-Scope Knowledge Base
+
+The `.out-of-scope/` directory in a repo stores persistent records of rejected feature requests. It serves two purposes:
+
+1. **Institutional memory** — why a feature was rejected, so the reasoning isn't lost when the issue is closed
+2. **Deduplication** — when a new issue comes in that matches a prior rejection, the skill can surface the previous decision instead of re-litigating it
+
+## Directory structure
+
+```
+.out-of-scope/
+├── dark-mode.md
+├── plugin-system.md
+└── graphql-api.md
+```
+
+One file per **concept**, not per issue. Multiple issues requesting the same thing are grouped under one file.
+
+## File format
+
+The file should be written in a relaxed, readable style — more like a short design document than a database entry. Use paragraphs, code samples, and examples to make the reasoning clear and useful to someone encountering it for the first time.
+
+```markdown
+# Dark Mode
+
+This project does not support dark mode or user-facing theming.
+
+## Why this is out of scope
+
+The rendering pipeline assumes a single color palette defined in
+`ThemeConfig`. Supporting multiple themes would require:
+
+- A theme context provider wrapping the entire component tree
+- Per-component theme-aware style resolution
+- A persistence layer for user theme preferences
+
+This is a significant architectural change that doesn't align with the
+project's focus on content authoring. Theming is a concern for downstream
+consumers who embed or redistribute the output.
+
+```ts
+// The current ThemeConfig interface is not designed for runtime switching:
+interface ThemeConfig {
+  colors: ColorPalette; // single palette, resolved at build time
+  fonts: FontStack;
+}
+```
+
+## Prior requests
+
+- #42 — "Add dark mode support"
+- #87 — "Night theme for accessibility"
+- #134 — "Dark theme option"
+```
+
+### Naming the file
+
+Use a short, descriptive kebab-case name for the concept: `dark-mode.md`, `plugin-system.md`, `graphql-api.md`. The name should be recognizable enough that someone browsing the directory understands what was rejected without opening the file.
+
+### Writing the reason
+
+The reason should be substantive — not "we don't want this" but why. Good reasons reference:
+
+- Project scope or philosophy ("This project focuses on X; theming is a downstream concern")
+- Technical constraints ("Supporting this would require Y, which conflicts with our Z architecture")
+- Strategic decisions ("We chose to use A instead of B because...")
+
+The reason should be durable. Avoid referencing temporary circumstances ("we're too busy right now") — those aren't real rejections, they're deferrals.
+
+## When to check `.out-of-scope/`
+
+During triage (Step 1: Gather context), read all files in `.out-of-scope/`. When evaluating a new issue:
+
+- Check if the request matches an existing out-of-scope concept
+- Matching is by concept similarity, not keyword — "night theme" matches `dark-mode.md`
+- If there's a match, surface it to the maintainer: "This is similar to `.out-of-scope/dark-mode.md` — we rejected this before because [reason]. Do you still feel the same way?"
+
+The maintainer may:
+
+- **Confirm** — the new issue gets added to the existing file's "Prior requests" list, then closed
+- **Reconsider** — the out-of-scope file gets deleted or updated, and the issue proceeds through normal triage
+- **Disagree** — the issues are related but distinct, proceed with normal triage
+
+## When to write to `.out-of-scope/`
+
+Only when an **enhancement** (not a bug) is *rejected* as `wontfix`. This applies to enhancement PRs exactly as it does to issues — a rejected PR is recorded here so the same request doesn't return as fresh code.
+
+Do **not** write here when something is closed as `wontfix` because it's **already implemented**. That's a built feature, not a rejected one; recording it would poison the dedup checks with false rejections. Instead, the closing comment points to where the feature already lives.
+
+The flow:
+
+1. Maintainer decides a feature request is out of scope
+2. Check if a matching `.out-of-scope/` file already exists
+3. If yes: append the new issue to the "Prior requests" list
+4. If no: create a new file with the concept name, decision, reason, and first prior request
+5. Post a comment on the issue explaining the decision and mentioning the `.out-of-scope/` file
+6. Close the issue with the `wontfix` label
+
+## Updating or removing out-of-scope files
+
+If the maintainer changes their mind about a previously rejected concept:
+
+- Delete the `.out-of-scope/` file
+- The skill does not need to reopen old issues — they're historical records
+- The new issue that triggered the reconsideration proceeds through normal triage

.agents/skills/triage/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: triage
+description: Move issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.
+disable-model-invocation: true
+---
+
+# Triage
+
+Move issues on the project issue tracker through a small state machine of triage roles.
+
+If this repo treats external pull requests as a request surface (see the issue-tracker config), triage covers them too: **a PR is an issue with attached code** — same roles, same states, same machine, with a few deltas marked "for a PR" below. Resolve a bare `#42` to an issue or PR per the tracker config.
+
+Every comment or issue posted to the issue tracker during triage **must** start with this disclaimer:
+
+```
+> *This was generated by AI during triage.*
+```
+
+## Reference docs
+
+- [AGENT-BRIEF.md](AGENT-BRIEF.md) — how to write durable agent briefs
+- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — how the `.out-of-scope/` knowledge base works
+
+## Roles
+
+Two **category** roles:
+
+- `bug` — something is broken
+- `enhancement` — new feature or improvement
+
+Five **state** roles:
+
+- `needs-triage` — maintainer needs to evaluate
+- `needs-info` — waiting on reporter for more information
+- `ready-for-agent` — fully specified, ready for an AFK agent
+- `ready-for-human` — needs human implementation
+- `wontfix` — will not be actioned
+
+For a PR, the same states read against the attached code: `ready-for-agent` means a brief is attached and an agent should take the next step on the diff; `ready-for-human` means it's ready for a human to merge.
+
+Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
+
+These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run `/setup-matt-pocock-skills` if not.
+
+State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
+
+## Invocation
+
+The maintainer invokes `/triage` and describes what they want in natural language. Interpret the request and act. Examples:
+
+- "Show me anything that needs my attention"
+- "Let's look at #42" (issue or PR)
+- "Move #42 to ready-for-agent"
+- "What's ready for agents to pick up?"
+
+## Show what needs attention
+
+Query the issue tracker and present three buckets, oldest first:
+
+1. **Unlabeled** — never triaged.
+2. **`needs-triage`** — evaluation in progress.
+3. **`needs-info` with reporter activity since the last triage notes** — needs re-evaluation.
+
+When PRs are in scope, include external PRs in these buckets and tag each line `[PR]` or `[issue]`. Discovery surfaces only *external* PRs (the tracker config defines who counts as external) — a collaborator's in-flight PR is not triage work. This filter is discovery-only; an explicitly named PR is always triaged regardless of author.
+
+Show counts and a one-line summary per item. Let the maintainer pick.
+
+## Triage a specific issue or PR
+
+1. **Gather context.** Read the full issue or PR (body, comments, labels, author, dates; for a PR, the diff too). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Run two checks against the codebase: (a) **redundancy** — search for an existing implementation of the requested behavior by domain concept (not just the request's wording), and report where you looked. If found, it's an already-implemented `wontfix` (step 5). (b) **prior rejection** — read `.out-of-scope/*.md` and surface any that resembles this request.
+
+2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the request — including whether it's already implemented. Wait for direction.
+
+3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief.
+
+4. **Grill (if needed).** If the request needs fleshing out, run the `/grilling` and `/domain-modeling` skills together — grill it into shape one question at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
+
+5. **Apply the outcome:**
+   - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).
+   - `ready-for-human` — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
+   - `needs-info` — post triage notes (template below).
+   - `wontfix` — close, with the comment depending on *why*:
+     - **Already implemented** — the change already exists in the codebase. Point to where it lives; do **not** write to `.out-of-scope/` (that KB is for *rejected* requests, not built ones).
+     - **Rejected (bug)** — polite explanation, then close.
+     - **Rejected (enhancement)** — write to `.out-of-scope/`, link to it from a comment, then close ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)).
+   - `needs-triage` — apply the role. Optional comment if there's partial progress.
+
+## Quick state override
+
+If the maintainer says "move #42 to ready-for-agent", trust them and apply the role directly. Confirm what you're about to do (role changes, comment, close), then act. Skip grilling. If moving to `ready-for-agent` without a grilling session, ask whether they want to write an agent brief.
+
+## Needs-info template
+
+```markdown
+## Triage Notes
+
+**What we've established so far:**
+
+- point 1
+- point 2
+
+**What we still need from you (@reporter):**
+
+- question 1
+- question 2
+```
+
+Capture everything resolved during grilling under "established so far" so the work isn't lost. Questions must be specific and actionable, not "please provide more info".
+
+## Resuming a previous session
+
+If prior triage notes exist on the issue or PR, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.

.agents/skills/ubiquitous-language/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: ubiquitous-language
+description: Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD".
+disable-model-invocation: true
+---
+
+# Ubiquitous Language
+
+Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to a local file.
+
+## Process
+
+1. **Scan the conversation** for domain-relevant nouns, verbs, and concepts
+2. **Identify problems**:
+   - Same word used for different concepts (ambiguity)
+   - Different words used for the same concept (synonyms)
+   - Vague or overloaded terms
+3. **Propose a canonical glossary** with opinionated term choices
+4. **Write to `UBIQUITOUS_LANGUAGE.md`** in the working directory using the format below
+5. **Output a summary** inline in the conversation
+
+## Output Format
+
+Write a `UBIQUITOUS_LANGUAGE.md` file with this structure:
+
+```md
+# Ubiquitous Language
+
+## Order lifecycle
+
+| Term        | Definition                                              | Aliases to avoid      |
+| ----------- | ------------------------------------------------------- | --------------------- |
+| **Order**   | A customer's request to purchase one or more items      | Purchase, transaction |
+| **Invoice** | A request for payment sent to a customer after delivery | Bill, payment request |
+
+## People
+
+| Term         | Definition                                  | Aliases to avoid       |
+| ------------ | ------------------------------------------- | ---------------------- |
+| **Customer** | A person or organization that places orders | Client, buyer, account |
+| **User**     | An authentication identity in the system    | Login, account         |
+
+## Relationships
+
+- An **Invoice** belongs to exactly one **Customer**
+- An **Order** produces one or more **Invoices**
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed. A single **Order** can produce multiple **Invoices** if items ship in separate **Shipments**."
+> **Dev:** "So if a **Shipment** is cancelled before dispatch, no **Invoice** exists for it?"
+> **Domain expert:** "Exactly. The **Invoice** lifecycle is tied to the **Fulfillment**, not the **Order**."
+
+## Flagged ambiguities
+
+- "account" was used to mean both **Customer** and **User** — these are distinct concepts: a **Customer** places orders, while a **User** is an authentication identity that may or may not represent a **Customer**.
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously in the conversation, call it out in the "Flagged ambiguities" section with a clear recommendation.
+- **Only include terms relevant for domain experts.** Skip the names of modules or classes unless they have meaning in the domain language.
+- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include domain terms.** Skip generic programming concepts (array, function, endpoint) unless they have domain-specific meaning.
+- **Group terms into multiple tables** when natural clusters emerge (e.g. by subdomain, lifecycle, or actor). Each group gets its own heading and table. If all terms belong to a single cohesive domain, one table is fine — don't force groupings.
+- **Write an example dialogue.** A short conversation (3-5 exchanges) between a dev and a domain expert that demonstrates how the terms interact naturally. The dialogue should clarify boundaries between related concepts and show terms being used precisely.
+
+<example>
+
+## Example dialogue
+
+> **Dev:** "How do I test the **sync service** without Docker?"
+
+> **Domain expert:** "Provide the **filesystem layer** instead of the **Docker layer**. It implements the same **Sandbox service** interface but uses a local directory as the **sandbox**."
+
+> **Dev:** "So **sync-in** still creates a **bundle** and unpacks it?"
+
+> **Domain expert:** "Exactly. The **sync service** doesn't know which layer it's talking to. It calls `exec` and `copyIn` — the **filesystem layer** just runs those as local shell commands."
+
+</example>
+
+## Re-running
+
+When invoked again in the same conversation:
+
+1. Read the existing `UBIQUITOUS_LANGUAGE.md`
+2. Incorporate any new terms from subsequent discussion
+3. Update definitions if understanding has evolved
+4. Re-flag any new ambiguities
+5. Rewrite the example dialogue to incorporate new terms

.agents/skills/wayfinder/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: wayfinder
+description: Plan a huge chunk of work — more than one agent session can hold — as a shared map of investigation tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
+disable-model-invocation: true
+---
+
+A loose idea has arrived — too big for one agent session, and wrapped in fog: the way from here to the **destination** isn't visible yet. Wayfinding is about finding that way, not charging at the destination. This skill charts the way as a **shared map** on the repo's issue tracker, then works its tickets one at a time until the route is clear.
+
+The destination varies per effort, and naming it is the first act of charting — it shapes every ticket. It might be a spec to hand off and iterate on, a decision to lock before planning starts, or a change made in place like a data-structure migration. The map is domain-agnostic — engineering work, course content, whatever fits the shape.
+
+## Plan, don't do
+
+Wayfinder is **planning** by default: each ticket resolves a decision, and the map is done when the way is clear — nothing left to decide before someone goes and does the thing. The pull to just do the work is usually the signal you've reached the edge of the map and it's time to hand off. An effort can override this in its **Notes** — carrying execution into the map itself — but absent that, produce decisions, not deliverables.
+
+## Refer by name
+
+Every map and ticket is an issue, so it has a **name** — its title. In everything the human reads — narration, the map's Decisions-so-far — refer to it by that name, never by a bare id, number, or slug. A wall of `#42, #43, #44` is illegible; names read at a glance. The id and URL don't vanish — a name wraps its link — but they ride *inside* the name, never stand in for it.
+
+## The Map
+
+The map is a single issue on this repo's issue tracker, labelled `wayfinder:map` — the canonical artifact. Its tickets are child issues of the map.
+
+The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
+
+**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if not. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
+
+### The map body
+
+The whole map at low resolution, loaded once per session. Open tickets are **not** listed — they are open child issues, found by query.
+
+```markdown
+## Destination
+
+<what reaching the end of this map looks like — the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>
+
+## Notes
+
+<domain; skills every session should consult; standing preferences for this effort>
+
+## Decisions so far
+
+<!-- the index — one line per closed ticket: enough to judge relevance, then zoom the link for the detail the ticket holds -->
+
+- [<closed ticket title>](link) — <one-line gist of the answer>
+
+## Not yet specified
+
+<!-- see "Fog of war": in-scope fog you can't ticket yet; graduates as the frontier advances -->
+
+## Out of scope
+
+<!-- see "Out of scope": work ruled beyond the destination; closed, never graduates -->
+```
+
+### Tickets
+
+Each ticket is a **child issue** of the map; the tracker's issue id is its identity. Its body is the question, sized to one 100K token agent session:
+
+```markdown
+## Question
+
+<the decision or investigation this ticket resolves>
+```
+
+Each ticket carries a `wayfinder:<type>` label — one of `research`, `prototype`, `grilling`, `task` (see [Ticket Types](#ticket-types)).
+
+A session **claims** a ticket by assigning it to the dev driving the map, **first**, before any work, so concurrent sessions skip it. That assignee _is_ the claim: an open, unassigned ticket is unclaimed.
+
+Blocking uses the tracker's **native** dependency relationship — essential because it renders the frontier _visually_ in the tracker's own UI, so the human sees what's takeable without opening the map. Only a tracker that lacks native blocking falls back to a body convention. A ticket is **unblocked** when every ticket blocking it is closed; the **frontier** is the open, unblocked, unclaimed children — the edge of the known.
+
+The answer isn't part of the body — it's recorded on resolution (see [Work through the map](#work-through-the-map)). Assets created while resolving a ticket are linked from the issue, not pasted in.
+
+## Ticket Types
+
+Every ticket is either **HITL** — human in the loop, worked *with* a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
+
+- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases. Creates a markdown summary as a linked asset. Use when knowledge outside the current working directory is required.
+- **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
+- **Grilling** (HITL): Conversation via the /grilling and /domain-modeling skills, one question at a time. The default case.
+- **Task** (HITL or AFK): Manual work that must happen before a *decision* can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that *does* rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
+
+## Fog of war
+
+The map is _deliberately_ incomplete: don't chart what you can't yet see. Beyond the live tickets lies the **fog of war** — the dim view of decisions and investigations you can tell are coming but can't yet pin down, because they hang on questions still open. Resolving a ticket clears the fog ahead of it, graduating whatever's now specifiable into fresh tickets — one at a time, until the way to the destination is clear and no tickets remain.
+
+The map's **Not yet specified** section is where that dim view is written down: the suspected question, the area to revisit later. It's the undiscovered frontier _toward_ the destination — everything here is in scope, just not sharp enough to ticket. Write as loosely or as fully as the view allows; it doubles as a signpost for collaborators reading where the effort is headed.
+
+**Fog or ticket?** The test is whether you can state the question precisely now — _not_ whether you can answer it now.
+
+- **Ticket when** the question is already sharp — even if it's blocked and you can't act on it yet.
+- **Not yet specified when** you can't yet phrase it that sharply. Don't pre-slice the fog into ticket-sized pieces: it's coarser than a ticket, and one patch may graduate into several tickets, or none, once the frontier reaches it.
+
+**Not yet specified** excludes what's already decided (Decisions so far), what's already a live ticket, and what's out of scope (the next section).
+
+## Out of scope
+
+Fog only ever gathers _toward_ the destination. The destination fixes the scope, so work beyond it is **out of scope** — it isn't fog, and it doesn't belong in **Not yet specified**. It gets its own **Out of scope** section on the map: work you've consciously ruled out of _this_ effort. Scope, not sharpness, lands it here.
+
+Out-of-scope work never graduates — the frontier stops at the destination — so it returns only if the destination is redrawn, and then as a fresh effort, not a resumption.
+
+Ruling something out of scope is a scoping act, not a step on the route. When a ticket that already exists turns out to sit past the destination — mis-scoped in while charting, or exposed by a resolution — **close it** (a closed ticket is unambiguously off the frontier) and leave one line in the **Out of scope** section: the gist plus why it's out of scope, linking the closed ticket. It stays out of **Decisions so far**, which records the route actually walked — a scope boundary isn't a step on it.
+
+## Invocation
+
+Two modes. Either way, **never resolve more than one ticket per session.**
+
+### Chart the map
+
+User invokes with a loose idea.
+
+1. **Name the destination.** Run a `/grilling` and `/domain-modeling` session to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first.
+2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
+3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
+4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
+5. Stop — charting the map is one session's work; do not also resolve tickets.
+
+### Work through the map
+
+User invokes with a map (URL or number). A ticket is **optional** — without one, you pick the next decision, not the user.
+
+1. Load the **map** — the low-res view, not every ticket body.
+2. Choose the ticket. If the user named one, use it. Otherwise take the first frontier ticket in order. **Claim it**: assign it to yourself before any work.
+3. Resolve it — **zoom as needed**: fetch the full body of any related or closed ticket on demand; invoke the skills the `## Notes` block names. If in doubt, use `/grilling` and `/domain-modeling`.
+4. Record the resolution: post the answer as a **resolution comment**, **close** the issue, and **append a context pointer** to the map's Decisions-so-far.
+5. Add newly-surfaced tickets (create-then-wire); graduate any fog the answer has made specifiable, clearing each graduated patch from **Not yet specified** so it lives only as its new ticket. If the answer reveals a ticket — this one or another — sits beyond the destination, **rule it out of scope** rather than resolving it on the route. If the decision invalidates other parts of the map, update or delete those tickets.
+
+The user may run unblocked tickets in parallel, so expect other sessions to be editing the tracker concurrently.

.agents/skills/wizard/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: wizard
+description: Generate an interactive bash wizard that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening URLs, capturing values, confirming each step, and writing .env files and GitHub Actions secrets.
+disable-model-invocation: true
+---
+
+# Wizard
+
+A **wizard** is a bash script that walks a human, step by step, through a manual procedure that's tedious to do by hand and tedious to re-explain to an AI every time. It opens each URL, says exactly what to click and copy, captures the values, writes them where they belong (`.env`, GitHub secrets), confirms at every stage, and shows how much is left. It might configure third-party services, run a one-off migration, or move the project from one state to another.
+
+The delightful UX is already solved by [template.sh](template.sh) — progress with time-remaining, confirmation gates, cross-platform URL opening (including WSL), hidden secret entry, idempotent `.env` upserts, `gh secret`/`gh variable` writes, and a closing summary. **Your job is only to scope the procedure and author its stages.** The library above the `STAGES` marker is identical in every wizard; that consistency is the point — never hand-edit it.
+
+A wizard is ephemeral by default — built for one run, saved to a scratch or `scripts/` path, deleted when the job's done. Commit it only when the user wants a repeatable setup path that should live in the repo.
+
+## Process
+
+### 1. Scope the procedure
+
+Work out every manual step the human must take and every value that gets captured along the way. Read the repo first — don't ask cold:
+
+- For setup: `.env`, `.env.example`, `.env.*`, `README`, `docker-compose*`, framework config, and `.github/workflows/*` (every `secrets.*` / `vars.*` reference is a value the wizard must produce).
+- For a migration or transition: the current state, the target state, and the irreversible actions between them.
+
+Then show the user the ordered list of stages and the values each produces, and confirm — they may add, drop, or reorder.
+
+**Done when:** every stage is named in order, and for each captured value you know (a) where the human gets it, (b) where it's written (`.env`, a GitHub secret, both, or nowhere — some stages are pure actions), and (c) whether it's secret (hidden entry) or public.
+
+### 2. Map each stage's journey
+
+For each stage, write the precise path a human follows: which URL to open, what to do there, where a value is shown, which variable it fills — e.g. "Dashboard → Developers → API keys → Reveal test key → copy". Where you don't actually know the current UI or the exact command, say so and ask the user or check the docs — never invent steps that may not exist.
+
+**Done when:** every stage traces to concrete instructions a stranger could follow.
+
+### 3. Author the wizard
+
+Copy `template.sh` to the target path. Replace the example stage with one `stage` per step, in dependency order. Use the library helpers — `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `pause`/`confirm` — and set `TOTAL_STAGES` and `TOTAL_MINUTES` to honest estimates (this drives the time-remaining display).
+
+Hold the bar the template sets: open the URL before asking for its value, use `ask_secret` for anything secret, `write_env` every persisted value, `set_secret` only the values CI actually needs, and `confirm` before any irreversible action. Each `stage` clears the screen so only the current step is visible — keep a stage to one focused task so nothing the human needs scrolls away. Don't touch the library above the marker.
+
+### 4. Verify and hand off
+
+- `bash -n <script>`; run `shellcheck` if available.
+- `chmod +x <script>`.
+- Don't run it end-to-end yourself — it opens browsers and blocks on human input. Trace it statically instead: every value from step 1 is captured and lands where step 1 said, and every `set_secret` name exactly matches a `secrets.*` reference in CI.
+- Tell the user how to run it. If it's a repeatable setup path, commit it and link it from the README so the next person runs the script instead of asking an AI.

.agents/skills/wizard/template.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+#
+# A wizard — walks a human through a manual procedure step by step.
+# Generated by the /wizard skill.
+#
+# Everything above the "STAGES" marker is the wizard library: do not hand-edit
+# it. Author the per-step stages below the marker.
+
+set -euo pipefail
+
+# ──────────────────────────────────────────────────────────────────────────
+# Wizard library — delightful, consistent UX. Identical across every wizard.
+# ──────────────────────────────────────────────────────────────────────────
+
+if [[ -t 1 ]] && command -v tput >/dev/null 2>&1 && [[ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]]; then
+  BOLD=$(tput bold); DIM=$(tput dim); RESET=$(tput sgr0)
+  BLUE=$(tput setaf 4); GREEN=$(tput setaf 2); YELLOW=$(tput setaf 3); RED=$(tput setaf 1)
+else
+  BOLD=""; DIM=""; RESET=""; BLUE=""; GREEN=""; YELLOW=""; RED=""
+fi
+
+# Author sets these two at the top of the stages section.
+TOTAL_STAGES=0
+TOTAL_MINUTES=0
+
+_STAGE_INDEX=0
+_MINUTES_ELAPSED=0
+ENV_FILE="${ENV_FILE:-.env}"
+WRITTEN_ENV=()    # KEYs written to ENV_FILE this run
+WRITTEN_SECRET=() # secret NAMEs set this run
+SKIPPED=()        # things we couldn't do (e.g. gh missing)
+
+# _clear — wipe the terminal so only the current step is on screen. No-op when
+# output isn't a terminal, so piped logs stay readable.
+_clear() {
+  [[ -t 1 ]] || return 0
+  if command -v tput >/dev/null 2>&1; then tput clear; else printf '\033[2J\033[3J\033[H'; fi
+}
+
+# banner "Title" — opening frame: what this wizard does and how long it takes.
+banner() {
+  _clear
+  printf '\n%s%s  %s%s\n' "$BOLD" "$BLUE" "$1" "$RESET"
+  printf '%s  %s stages · about %s minutes%s\n\n' \
+    "$DIM" "$TOTAL_STAGES" "$TOTAL_MINUTES" "$RESET"
+  printf '%s  You drive the browser; this wizard tells you exactly what to do and\n' "$DIM"
+  printf '  captures the values you copy back. Stop any time with Ctrl-C and re-run\n'
+  printf '  later — it remembers values already saved.%s\n' "$RESET"
+  pause "Ready to start?"
+}
+
+# stage "Name" <minutes> — clear the screen, then announce a stage and show
+# progress + time remaining. Clearing keeps only the current step on screen.
+stage() {
+  _clear
+  _STAGE_INDEX=$((_STAGE_INDEX + 1))
+  local remaining=$((TOTAL_MINUTES - _MINUTES_ELAPSED))
+  (( remaining < 0 )) && remaining=0
+  _MINUTES_ELAPSED=$((_MINUTES_ELAPSED + ${2:-0}))
+  printf '\n%s%s▸ Stage %s/%s · %s%s  %s(~%s min left)%s\n' \
+    "$BOLD" "$BLUE" "$_STAGE_INDEX" "$TOTAL_STAGES" "$1" "$RESET" "$DIM" "$remaining" "$RESET"
+}
+
+# say "..." — a plain instruction line.
+say()  { printf '  %s\n' "$1"; }
+# step "..." — a numbered-feeling action the human takes in the browser.
+step() { printf '  %s•%s %s\n' "$BLUE" "$RESET" "$1"; }
+note() { printf '  %s%s%s\n' "$DIM" "$1" "$RESET"; }
+warn() { printf '  %s⚠ %s%s\n' "$YELLOW" "$1" "$RESET"; }
+
+# open_url URL — open in the human's browser, cross-platform incl. WSL.
+open_url() {
+  local url="$1"
+  printf '  %s↗ opening%s %s\n' "$GREEN" "$RESET" "$url"
+  { if   command -v wslview     >/dev/null 2>&1; then wslview "$url"
+    elif command -v explorer.exe >/dev/null 2>&1; then explorer.exe "$url"
+    elif command -v xdg-open    >/dev/null 2>&1; then xdg-open "$url"
+    elif command -v open        >/dev/null 2>&1; then open "$url"
+    else warn "couldn't open a browser — visit it manually: $url"; fi
+  } >/dev/null 2>&1 || warn "couldn't open a browser — visit it manually: $url"
+}
+
+# pause "msg" — wait for the human to confirm they've done the manual part.
+pause() {
+  printf '  %s%s%s ' "$DIM" "${1:-Press Enter to continue}" "$RESET"
+  read -r _ || true
+}
+
+# confirm "question" — y/N gate; returns success on yes.
+confirm() {
+  local reply=""
+  printf '  %s? %s [y/N] ' "$YELLOW" "$1"
+  read -r reply || true
+  [[ "$reply" =~ ^[Yy] ]]
+}
+
+# _existing KEY — current value of KEY in ENV_FILE, if any.
+_existing() {
+  [[ -f "$ENV_FILE" ]] || return 1
+  local line; line=$(grep -E "^${1}=" "$ENV_FILE" | tail -n1) || return 1
+  printf '%s' "${line#*=}"
+}
+
+# ask KEY "Prompt" — read a value into $KEY. Offers the existing .env value as
+# a default on re-runs (Enter keeps it). Visible input (non-secret).
+ask() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -r input || true
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# ask_secret KEY "Prompt" — like ask, but input is hidden.
+ask_secret() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -rs input || true
+  printf '\n'
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# write_env KEY VALUE — upsert KEY=VALUE into ENV_FILE (creates it; replaces
+# any existing line). Idempotent.
+write_env() {
+  local key="$1" value="$2" tmp
+  touch "$ENV_FILE"
+  tmp=$(mktemp)
+  grep -vE "^${key}=" "$ENV_FILE" > "$tmp" || true
+  printf '%s=%s\n' "$key" "$value" >> "$tmp"
+  mv "$tmp" "$ENV_FILE"
+  WRITTEN_ENV+=("$key")
+  printf '  %s✓ wrote%s %s → %s\n' "$GREEN" "$RESET" "$key" "$ENV_FILE"
+}
+
+# set_secret NAME VALUE — set a GitHub Actions repo secret via gh. Falls back
+# to a warning (and records it) if gh is unavailable or unauthenticated.
+set_secret() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if printf '%s' "$value" | gh secret set "$name" >/dev/null 2>&1; then
+      WRITTEN_SECRET+=("$name")
+      printf '  %s✓ set%s GitHub secret %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub secret $name (set it manually: gh secret set $name)")
+  warn "skipped GitHub secret $name — gh not ready; set it later"
+}
+
+# set_var NAME VALUE — set a GitHub Actions repo variable (non-secret).
+set_var() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if gh variable set "$name" --body "$value" >/dev/null 2>&1; then
+      printf '  %s✓ set%s GitHub variable %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub variable $name")
+  warn "skipped GitHub variable $name — gh not ready; set it later"
+}
+
+# finish — clear, then a closing summary of everything configured.
+finish() {
+  _clear
+  printf '\n%s%s  ✓ Setup complete%s\n' "$BOLD" "$GREEN" "$RESET"
+  (( ${#WRITTEN_ENV[@]} ))    && note "wrote ${#WRITTEN_ENV[@]} value(s) to $ENV_FILE: ${WRITTEN_ENV[*]}"
+  (( ${#WRITTEN_SECRET[@]} )) && note "set ${#WRITTEN_SECRET[@]} GitHub secret(s): ${WRITTEN_SECRET[*]}"
+  if (( ${#SKIPPED[@]} )); then
+    printf '\n'; warn "still to do by hand:"
+    for s in "${SKIPPED[@]}"; do note "  - $s"; done
+  fi
+  printf '\n'
+}
+
+# ──────────────────────────────────────────────────────────────────────────
+# STAGES — author this section. One stage() per step the human takes.
+# Replace the example below. Set the two totals to match the stages you write.
+# ──────────────────────────────────────────────────────────────────────────
+
+TOTAL_STAGES=1
+TOTAL_MINUTES=5
+
+banner "Stripe setup"
+
+# ── Example stage: replace with your real steps ───────────────────────────
+stage "Stripe — API keys" 5
+say "We'll grab your Stripe test keys and store them for local dev + CI."
+open_url "https://dashboard.stripe.com/test/apikeys"
+step "On the API keys page, copy the Publishable key (starts pk_test_)."
+ask STRIPE_PUBLISHABLE_KEY "Paste the publishable key:"
+step "Click 'Reveal test key' on the Secret key row, then copy it."
+ask_secret STRIPE_SECRET_KEY "Paste the secret key:"
+write_env STRIPE_PUBLISHABLE_KEY "$STRIPE_PUBLISHABLE_KEY"
+write_env STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"
+set_secret STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"   # CI needs this one
+# ──────────────────────────────────────────────────────────────────────────
+
+finish

.agents/skills/writing-beats/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: writing-beats
+description: Writing, exploit — assemble raw material into a journey of beats, grounding each term before a beat leans on it.
+disable-model-invocation: true
+---
+
+<what-to-do>
+
+The user has passed (or will pass) a markdown file of raw material. This is **exploit**: the exploring is done, the pile is fixed — commit to a path through it and mine the pile to fill each beat.
+
+If the user did not say where to save the article, ask once and remember the path.
+
+Then run a beat-by-beat journey, choose-your-own-adventure style:
+
+1. **Establish the prerequisites.** Before any beats, settle with the user what the audience already knows walking in — the concepts that are **grounded** from the start. Everything else must be grounded by a beat before a later beat can use it. See [Grounding](#grounding).
+2. Write 2–3 candidate **starting beats**, drawn from the raw material. Each is a different entry point into the article. Each may only lean on grounded concepts; note what new concepts each one grounds. Show the user the beats before writing to the article file. The user picks one. Preview what beats that pick unlocks — as if the user is seeing a little way down the path.
+3. Once the user picks a starting beat, write **only that beat** to the article file. A beat may be one sentence or several paragraphs — whatever that beat naturally is. Stop there.
+4. Re-read the article file from disk. Then offer 2–3 candidate **next beats** — different directions the journey could pivot to from where the article now stands. Each must be reachable from the current grounded set; note what each one grounds.
+5. Loop steps 3–5 until the article reaches a natural end.
+
+</what-to-do>
+
+<supporting-info>
+
+## Grounding
+
+Every **concept** has to be **grounded** before a beat can lean on it: the audience either walked in knowing it or met it in an earlier beat. A beat that reaches for an ungrounded concept loses the reader — that is the one move the journey can't make. The unit is the concept, not the word for it: a beat can lean on an idea the reader lacks even with no jargon in sight. Where a concept has a name — a **term** — grounding it means landing the idea and the term together.
+
+A concept gets grounded one of two ways:
+
+- **Prerequisite** — grounded before the first beat. The audience brings it. Fixed at the start.
+- **Introduced** — a beat establishes it, and from then on it's grounded for every later beat.
+
+So each beat does two jobs: it **requires** concepts that are already grounded, and it **grounds** new ones. Keep a running list of what's grounded so far, and update it each time a beat lands.
+
+This is what shapes the choose-your-own-adventure. A candidate beat is only reachable if everything it requires is already grounded; picking a beat that grounds concept X unlocks every beat that was waiting on X. When you offer next beats, they must all be reachable from the current grounded set — and say what each one grounds, so the user can see which paths it opens.
+
+The big lever is what you make a prerequisite versus what you ground inside the piece. Demand too much up front and you shut out readers who don't have it; ground too much inside and the early beats drown in definitions. Settle this with the user when you establish prerequisites, and revisit it whenever a tempting beat turns out to require a concept nothing has grounded yet — the fix is either a grounding beat before it, or promoting the concept to a prerequisite.
+
+## What is a beat
+
+A beat is one move in the journey. It does one thing — sets a scene, lands a point, asks a question, drops an aside, twists the angle. Then it stops, leaving the reader at a place where the next beat can pivot.
+
+A beat is sized by what it needs:
+
+- A single sentence if that's all the move is ("And then nothing happened for three weeks.").
+- A short paragraph if the move needs setup.
+- Multiple paragraphs if the beat is a self-contained vignette, argument, or example.
+
+If a "beat" needs five paragraphs and three subheadings, it's not a beat — it's two beats glued together. Split it.
+
+## Pulling from the pile
+
+Pull material from the raw pile to populate each beat. You can paraphrase, split, recombine, or quote. The pile is a quarry.
+
+## Ending the journey
+
+The article ends when the journey is complete — not when the pile is empty. Most piles will have leftover fragments that don't make it in. That is fine; that is the point of having more raw material than you need.
+
+## Writing rhythm
+
+- Append one beat at a time. Never write ahead.
+- Re-read the article file from disk before every write. Preserve user edits absolutely.
+- If the user edits a previous beat substantially, let it change what comes next.
+- If the user says "rewrite that beat" or "go back and try a different beat 3", do it — edit in place, leave the rest alone.
+
+</supporting-info>

.agents/skills/writing-fragments/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: writing-fragments
+description: Writing, explore — mine raw fragments, no structure yet.
+disable-model-invocation: true
+---
+
+<what-to-do>
+
+This is pure **explore**: widen the space of what could be written without committing to structure — committing is _exploit_, a separate skill's job. Run a grilling session that produces fragments, interviewing the user relentlessly about whatever they want to write about. Imposing phases, outlines, or article structure is out of scope here.
+
+As fragments emerge from either side of the conversation, append them to a single markdown file.
+
+If the user did not pass a path, ask once where to save the document, then remember it for the rest of the session.
+
+Capture fragments from the very first thing the user says, including the initial prompt.
+
+On first write, put a single H1 at the top with a working title (it can change later) and nothing else — no metadata, no TOC, no date.
+
+</what-to-do>
+
+<supporting-info>
+
+## What is a fragment
+
+A fragment is any piece of text that might survive into the final article. It must be _readable by the author_ — the author can tell what it means — but it does not need to define its terms or be comprehensible to a cold reader. The bar is "is this a piece of good writing?", not "is this a self-contained argument?"
+
+Fragments are deliberately heterogeneous. Examples of what could be a fragment:
+
+- A sharp sentence you'd want to deploy somewhere but don't yet know where.
+- A claim with a one-line justification.
+- A vignette: a thing that happened, a code snippet, a scenario, an analogy.
+- A half-thought: "something about how X feels like Y, work this out later."
+- A quote, a piece of dialogue, an overheard line.
+- A list of related observations that hang together by feel.
+- A complaint, a confession, a punchline.
+- A **leading word** — a compact metaphor or coinage the whole piece can hang on (one term that names the idea, the way _tracer bullets_ or _fog of war_ names a whole pattern).
+
+Of these, the leading word is the most valuable fragment to land. It is load-bearing: name the right one in explore and it shapes the structure, the transitions, and the title later — paying dividends through the entire exploit phase. When the conversation circles a recurring idea, push to coin a word for it.
+
+The novelist's diary is the model: years of unstructured noticings that later get mined for raw material. Fragments are noticings.
+
+## File format
+
+```markdown
+# Working title
+
+A first fragment lives here.
+
+It can be multiple paragraphs. It can include lists, code, quotes — whatever
+shape the fragment naturally takes.
+
+---
+
+A second fragment.
+
+---
+
+> A quoted line that the user wants to keep around.
+
+A reaction to it.
+
+---
+
+- A cluster of related observations
+- That hang together by feel
+- And want to be near each other
+```
+
+Fragments are separated by a horizontal rule (`\n---\n`). No headings inside the body. No tags. No order beyond the order they were added.
+
+## Writing rhythm
+
+Append silently. Don't ask permission for each fragment. Mention what you added in passing ("adding that"), but don't interrupt the conversation with save dialogs.
+
+Before every write: re-read the file from disk. The user may have edited, reordered, or deleted fragments between turns — preserve their changes. Never overwrite the file; only append (or, if the user asks, edit a specific fragment in place).
+
+The user can say "cut the last one", "rewrite that one sharper", "merge those two" at any time. Treat those as first-class instructions.
+
+</supporting-info>

.agents/skills/writing-great-skills/GLOSSARY.md

@@ -0,0 +1,201 @@
+# Glossary — Building Great Skills
+
+The domain model for what makes a skill great. A skill exists to wrangle determinism out of a stochastic system; the root virtue is **Predictability**, and every term below is a lever on it. This is the disclosed reference for [`writing-great-skills`](SKILL.md).
+
+The terms are grouped by axis: **Invocation** (how a skill is reached), **Information Hierarchy** (how its content is arranged), **Steering** (how the agent's runtime behaviour is shaped), and **Pruning** (how it is kept lean). Each **failure mode** lives beside the lever that cures it, tagged _failure mode_.
+
+**Bold terms** in any definition are themselves defined in this glossary; find them by their heading.
+
+## Predictability
+
+The degree to which a skill makes the agent behave the same _way_ on every run — the same process, not the same output (a brainstorming skill should _predictably_ diverge; its tokens vary, its behaviour doesn't). The root virtue every other term serves — cost and maintainability are symptoms of it, not rivals.
+
+_Avoid_: consistency, reliability, robustness, output-determinism
+
+## Invocation
+
+How a skill is reached — and the two loads you pay for the choice.
+
+### Model-Invoked
+
+A skill that keeps its **description** field, so the agent can see it and fire it autonomously — and the human can still type its name, so model-invocation always _includes_ user reach. There is no model-only state: a description only ever _adds_ agent discovery, never removes the human's. Pays a permanent **context load** on every turn in exchange for that discoverability. Reachable by other skills, because the description that makes it agent-discoverable makes it invocable. A model-invoked skill whose content is all **reference** is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Pick model-invocation only when the agent must reach the skill on its own; if it never fires except by hand, drop the description and pay no context load.
+
+_Avoid_: ability, tool, capability
+
+### User-Invoked
+
+A skill with its **description** stripped — invisible to the agent and reachable only by the human typing its name (user-_only_, where **model-invoked** is user-_and-agent_). Trades agent-discoverability for zero **context load**. Because it has no description, nothing but the human can reach it: no other skill can fire it.
+
+_Avoid_: procedure, workflow, command
+
+### Description
+
+The skill's machine-readable trigger, and the one **context pointer** a **model-invoked** skill is forced to keep loaded at all times. Its mere presence _is_ the invocation axis: keep it and the skill is model-invoked (and reachable by other skills); delete it and the skill is **user-invoked**, reachable only by the human. The source of a model-invoked skill's **context load**.
+
+_Avoid_: frontmatter, summary
+
+### Context Pointer
+
+A reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. The **description** is the top-level context pointer (context window → skill); pointers to disclosed files are the same object one level down. Its wording, not the target, decides _when_ the agent reaches — and _how reliably_. A must-have target behind a weakly worded pointer is a variance bug: fix the wording first, and inline the material only if sharpening fails.
+
+_Avoid_: link, reference, import
+
+### Context Load
+
+The cost a **model-invoked** skill imposes on the agent's context window — its **description**, always loaded, spending both tokens and attention. What **user-invoked** skills escape by having no description, and the brake on splitting into more model-invoked skills.
+
+_Avoid_: token cost, context bloat
+
+### Cognitive Load
+
+The cost a **user-invoked** skill imposes on the human — what they must hold in their head: which skills exist and when to reach for each (the human is the index). What **model-invocation** removes by being agent-discoverable, and the brake on splitting into more user-invoked skills. Not a cost to minimise: it is the price of human agency, the reason some skills stay user-invoked. Spend it where human judgement matters; remove it where it does not.
+
+_Avoid_: human index, burden, overhead
+
+### Router Skill
+
+A **user-invoked** skill whose job is to point at your other user-invoked skills — naming each and when to reach for it — so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no **description**, so nothing but the human can reach them. The cure for **cognitive load** when user-invoked skills multiply.
+
+_Avoid_: dispatcher, menu, registry, index, router procedure
+
+### Granularity
+
+How finely you divide skills. Finer division spends one of the two loads: more **model-invoked** skills spend **context load** (more descriptions crowding the window and competing for attention); more **user-invoked** skills spend **cognitive load** (more for the human to remember and reach for). Two cuts guide the division. By **invocation**, split off a model-invoked skill where you have a distinct **leading word** to trigger it — a trigger word you actually use in your prompts. By **sequence**, split a run of **steps** where a step's **post-completion steps** need hiding, since isolating it in its own context clears what follows. Beware the reverse: merging sequences exposes each step's post-completion steps to what follows, inviting premature completion.
+
+_Avoid_: chunking, modularity
+
+## Information Hierarchy
+
+How a skill's content is arranged, and how far down the ladder each piece sits.
+
+### Information Hierarchy
+
+A skill's content ranked by how immediately the agent needs it — a single ladder, produced by two cuts: in-file or behind a pointer, and step or reference. The rungs:
+
+- **Steps** — in-file, primary
+- **Reference**, in-file — secondary
+- **Reference**, disclosed — behind a **context pointer**
+
+A skill with no **steps** uses just the bottom two rungs — often a legitimately flat peer-set (e.g. every rule of a review on one rung), which is a fine arrangement, not a smell. The hierarchy is independent of invocation: a skill can be model- or user-invoked whether it is all steps, all reference, or both. When a skill has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one. Keep the top of the ladder legible; push down it whatever you can.
+
+_Avoid_: structure, organization, layout
+
+### Steps
+
+The ordered actions the agent performs — when a skill has them, the primary tier of its content, and the part that earns its place in SKILL.md. Not every skill has steps: a skill can be all steps (`tdd`), all **reference** (a review), or both, independent of invocation. Every step ends on a **completion criterion**, clear or vague.
+
+_Avoid_: workflow, instructions, choreography
+
+### Reference
+
+Material the agent refers to on demand — definitions, facts, parameters, examples, conditional instructions. When a skill has **steps** it is secondary to them; when a skill has none it is the entire content; or it lives outside any skill entirely — see **External Reference**. Reached via **context pointers**, and the prime candidate for **progressive disclosure**.
+
+_Avoid_: supporting material, docs, background
+
+### External Reference
+
+**Reference** that lives outside the skill system — a plain file, no **description**, no **steps**, not invocable — that any skill can point at. The home for shared reference that needn't fire on its own, and the only shared home two **user-invoked** skills can use, since neither has a description and so neither can fire the other.
+
+_Avoid_: doc, resource, knowledge base
+
+### Progressive Disclosure
+
+Moving **reference** down the ladder — out of SKILL.md and behind a **context pointer** — so the top stays legible. Not primarily a token optimisation; it is how the **information hierarchy** is protected. Licensed by **branching**: disclose what only some branches need, inline what every path needs, and if a pointer fires unreliably on must-have material, sharpen its wording, and pull it back inline only if that fails.
+
+_Avoid_: lazy loading, chunking
+
+### Co-location
+
+Keeping the material an agent needs at once in one place — a concept's definition, rules, and caveats under a single heading, not scattered across the file — so reading one part brings its neighbours with it. The within-file companion to the **Information Hierarchy**: the hierarchy ranks _how far down_ a piece sits; co-location decides _what sits beside it_ once there. There is no formula for the right format of a body of **reference**; the test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not. Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many.
+
+_Avoid_: grouping, clustering, cohesion
+
+### Sprawl
+
+_Failure mode._ A skill that is simply too long — too many lines in SKILL.md — independent of whether they are stale or repeated. Even an all-live, all-unique skill can sprawl. It costs readability (the agent wades through more before it can act, and attention thins across the excess), maintainability (every extra line is one more to keep **relevant**), and tokens. The cure is the **information hierarchy**: push **reference** down behind **context pointers**, and split by **branch** or sequence so each path carries only what it needs. Distinct from **sediment** (length from stale accumulation) and **duplication** (length from repeated meaning) — sprawl is length itself, whatever its cause.
+
+_Avoid_: bloat, length, size, verbosity
+
+## Steering
+
+The levers that shape the agent's runtime behaviour toward **Predictability**.
+
+### Branch
+
+A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it. A skill with many steps may carry many branches; a linear one has none.
+
+_Avoid_: path, case, fork
+
+### Leading Word
+
+A compact concept — also called a _Leitwort_ — already living in the model's pretraining, that the agent thinks with while running the skill. It encodes a behavioural principle in the fewest possible tokens by invoking priors the model already holds (e.g. _lesson_, _proximal zone of development_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition across the skill and anchors a whole region of behaviour. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free. Reach for an existing word first.
+
+A leading word serves **predictability** twice. In the body it anchors **execution** — the agent reaches for the same behaviour every time the concept appears, and inside flat reference it focuses attention on a class of thing to look for, recruiting the right checks each run. In the **description** it anchors **invocation** — and not only within the skill: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the skill and fires it more reliably. Word a description with the leading words you actually use when you want the skill.
+
+_Avoid_: keyword, term, motif
+
+### Completion Criterion
+
+The condition that tells the agent a unit of work is done — the target it judges against. Two properties make it a lever, not just a quality. Its **clarity** (can the agent tell done from not-done?) resists **premature completion** — a vague bound ("understanding reached") lets the agent declare done and slip to the next step; this axis needs _steps_ to bite, since premature completion is a between-steps failure. Its **demand** (how much it requires) sets **legwork** — "every modified model accounted for" forces thorough work where "produce a change list" does not — and this axis is _not_ step-bound: it can bind a body of flat reference too, which is how a skill with no steps still carries an exhaustiveness bar ("every rule applied"). The strongest criteria are both checkable and exhaustive.
+
+_Avoid_: done condition, exit condition, stopping rule
+
+### Legwork
+
+The work an agent does behind the scenes within a single step — reading files, exploring the codebase, making changes, digging up what it needs rather than offloading to the user. It lives below the step structure: never written as its own step, latent in the wording, controlled by the agent rather than the skill. The within-step counterpart to **post-completion steps**' across-step pull. Raised by a **leading word** (_comprehensive_, _thorough_) or a **completion criterion** that demands the work be exhaustive — including the demand axis applied to flat reference, which is what drives a skill of flat reference to cover all its rungs. Goes thin either when that demand is missing or when **premature completion** cuts the step short.
+
+_Avoid_: scope, effort, diligence, coverage
+
+### Post-Completion Steps
+
+The **steps** that follow the current step. Visible, they pull the agent forward into **premature completion** — the more it sees, the stronger the tug; the defence is to hide them by splitting the sequence of steps into two.
+
+_Avoid_: horizon, fog of war, lookahead
+
+### Premature Completion
+
+_Failure mode._ Ending the current step before it is genuinely done, because the agent's attention slips to being done rather than to the work. A between-steps failure: it needs **steps** to occur — a skill with no steps that quits early isn't premature completion but thin **legwork** under an unmet demand. A tug-of-war between two forces: visible **post-completion steps** (the pull forward) and the **completion criterion**'s clarity (the resistance — a sharp, checkable bar holds; a vague one gives way). Fuzziness is the necessary condition: a sharp bound resists the pull no matter how many later steps are visible, so a step that never rushes needs no defending. Two levers hold a step that does, but reach for them in order: **sharpen the bound first** — it is local and cheap. Only when the criterion is irreducibly fuzzy _and_ you actually observe the rush do you **hide the later steps** — and hiding only works across a real context boundary (a user-invoked hand-off or a subagent dispatch; an inline model-invoked call leaves the later steps in context and clears nothing). One cause of thin legwork, but distinct from it: legwork can be thin even when a step runs to full completion.
+
+_Avoid_: premature closure, the rush, rushing, shortcutting
+
+### Negation
+
+_Failure mode._ Steering by prohibition — telling the agent what _not_ to do — which drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; _never write verbose comments_, and verbosity is the pattern the agent has just read. The negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Its **leading word** is the _elephant_: whatever a prohibition names into the frame. Cure: prompt the **positive** — describe the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail on a behaviour you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do.
+
+_Avoid_: ironic rebound, don't-prompting, the pink elephant
+
+## Pruning
+
+Keeping a skill lean — each remedy paired with the failure it cures.
+
+### Single Source of Truth
+
+The desired state where each meaning lives in exactly one authoritative place, so a change to the skill's behaviour is a change in one place. **Duplication** is its violation.
+
+_Avoid_: home, canonical location
+
+### Duplication
+
+_Failure mode._ The same meaning given more than one **single source of truth**. It costs maintenance (change one place, you must change the others), costs tokens, and inflates prominence — repeating a meaning weights it on the ladder past its real rank. The accidental inverse of a **leading word**, which raises attention on purpose by repeating a token, never the meaning.
+
+_Avoid_: repetition, redundancy
+
+### Relevance
+
+Whether a line still bears on what the skill does — the lens for what to keep. A line loses relevance either by never bearing on the task (mere exposition, or a **branch** that should be disclosed) or by going stale: drifting out of date as the behaviour or world it describes changes. Shorter skills are easier to keep relevant, because each line is cheaper to check. Distinct from **no-op**: relevance asks whether a line bears on the task, not whether it changes behaviour.
+
+_Avoid_: load-bearing, staleness, freshness
+
+### Sediment
+
+_Failure mode._ Layers of old content that settle in a skill and are never cleared, because adding feels safe and removing feels risky — so stale and irrelevant lines accumulate and you must core down through them to find what is still live. The default fate of any skill without a pruning discipline; the slow erosion of **relevance**, as opposed to **duplication**'s repeated meaning.
+
+_Avoid_: accretion, bloat, cruft, rot
+
+### No-Op
+
+_Failure mode._ An instruction that changes nothing because the model already does it by default — you pay load to tell the agent what it would do anyway. The test: does a line change behaviour versus the default? A line can be perfectly **relevant** and still be a no-op. The same priors that make a **leading word** free make a no-op worthless.
+
+A leading word is a _technique_; No-Op is a _verdict_ on a line — and they cross. A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique. So the No-Op test — does it change behaviour versus the default? — is also how you grade whether a leading word is earning its repetitions. This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate.
+
+_Avoid_: redundant instruction, restating the obvious, belaboring

.agents/skills/writing-great-skills/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: writing-great-skills
+description: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.
+disable-model-invocation: true
+---
+
+A skill exists to wrangle determinism out of a stochastic system. **Predictability** — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it.
+
+**Bold terms** are defined in [`GLOSSARY.md`](GLOSSARY.md); look them up there for the full meaning.
+
+## Invocation
+
+Two choices, trading different costs:
+
+- A **model-invoked** skill keeps a **description**, so the agent can fire it autonomously _and_ other skills can reach it (you can still type its name too). It contributes to **context load** — the description sits in the window every turn. Mechanics: omit `disable-model-invocation`, and write a model-facing description with rich trigger phrasing ("Use when the user wants…, mentions…").
+- A **user-invoked** skill strips the description from the agent's reach: only you, typing its name, can invoke it — and no other skill can. Zero context load, but it spends **cognitive load**: _you_ are the index that must remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` becomes human-facing — a one-line summary, trigger lists stripped.
+
+Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
+
+When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each.
+
+## Writing the description
+
+A model-invoked **description** does two jobs — state what the skill is, and list the **branches** that should trigger it. Every word increases **context load**, so a description earns even harder pruning than the body:
+
+- **Front-load the skill's leading word** — the description is where it does its invocation work.
+- **One trigger per branch.** Synonyms that rename a single branch are **duplication** — "build features using TDD … asks for test-first development" is one branch written twice. Collapse them; keep only genuinely distinct branches.
+- **Cut identity that's already in the body.** Keep the description to triggers, plus any "when another skill needs…" reach clause.
+
+## Information hierarchy
+
+A skill is built from two content types — **steps** and **reference** — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:
+
+1. **In-skill step** — an ordered action in `SKILL.md`, the primary tier: what the agent does, in order. Each step ends on a **completion criterion**, the condition that tells the agent the work is done. Make it _checkable_ (can the agent tell done from not-done?) and, where it matters, _exhaustive_ ("every modified model accounted for", not "produce a change list") — a vague criterion invites **premature completion**.
+2. **In-skill reference** — a definition, rule, or fact in `SKILL.md`, consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell. _This skill is all reference._
+3. **External reference** — reference pushed out of `SKILL.md` into a separate file, reached by a **context pointer**, loaded only when the pointer fires. (Spans _disclosed_ reference — a sibling file like `GLOSSARY.md`, still part of the skill — through fully **external reference** that lives outside the skill system and any skill can point at.)
+
+A demanding completion criterion drives thorough **legwork** — the digging the agent does within the work — whether the skill has steps or not, since "every rule applied" binds flat reference just as "every step done" binds a sequence.
+
+Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
+
+**Progressive disclosure** is the move down the ladder — out of `SKILL.md` into a linked file — so the top stays legible. Mechanics: a linked `.md` file in the skill folder, named for what it holds (this skill discloses its full definitions to `GLOSSARY.md`). Some skills are used in more than one way, and each distinct way is a **branch** — different runs taking different paths through the skill. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. A **context pointer**'s _wording_, not its target, decides when and how reliably the agent reaches the material.
+
+Where the ladder decides _how far down_ a piece sits, **co-location** decides _what sits beside it_ once there: keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it.
+
+## When to split
+
+**Granularity** is how finely you divide skills, and each cut spends one of the two loads, so split only when the cut earns it. Two cuts:
+
+- **By invocation** — split off a **model-invoked** skill when you have a distinct **leading word** that should trigger it on its own, or another skill must reach it. You pay **context load** for the new always-loaded **description**, so that independent reach has to be worth it.
+- **By sequence** — split a run of **steps** when the steps still ahead (a step's **post-completion steps**) tempt the agent to rush the one in front of it (**premature completion**). Keeping them out of view encourages the agent to do more **legwork** on the current task.
+
+## Pruning
+
+Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit.
+
+Check every line for **relevance**: does it still bear on what the skill does?
+
+Then hunt **no-ops** sentence by sentence, not just line by line: run the no-op test on each sentence in isolation, and when one fails, delete the whole sentence rather than trim words from it. Be aggressive — most prose that fails should go, not be rewritten.
+
+## Leading words
+
+A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the skill (e.g. _lesson_, _fog of war_, _tracer bullets_). Repeated throughout the text (though not necessarily - a strong leading word might only be needed once), it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds.
+
+It serves predictability twice. In the body it anchors _execution_: the agent reaches for the same behaviour every time the word appears. In the description it anchors _invocation_: when the same word lives in your prompts, docs, and code, the agent links that shared language to the skill and fires it more reliably.
+
+Hunt for opportunities to refactor skills to use leading words. A triad spelled out at three sites (**duplication**), a description spending a sentence to gesture at one idea — each is a passage begging to **collapse** into a single token. Examples include:
+
+- "fast, deterministic, low-overhead" -> _tight_ — one quality restated across a phase — into a single pretrained word (a _tight_ loop).
+- "a loop you believe in" -> _red_ — converts a fuzzy gate into a binary observable state (the loop goes _red_ on the bug, or it doesn't).
+
+You win twice over: fewer tokens, _and_ a sharper hook for the agent to hang its thinking on. Assume every skill is carrying restatements that leading words retire — go find them.
+
+## Failure modes
+
+Use these to diagnose issues the user may be having with the skill.
+
+- **Premature completion** — ending a step before it's genuinely done, attention slipping to _being done_. Defence, in order: sharpen the completion criterion first (cheap, local); only if it is irreducibly fuzzy _and_ you observe the rush, hide the post-completion steps by splitting (the sequence cut).
+- **Duplication** — the same meaning in more than one place. Costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank.
+- **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without a pruning discipline.
+- **Sprawl** — a skill simply too long, even when every line is live and unique. Hurts readability and maintainability and wastes tokens. The cure is the ladder: disclose **reference** behind pointers, and split by **branch** or sequence so each path carries only what it needs.
+- **No-op** — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (_be thorough_ when the agent is already thorough-ish) is a no-op; the fix is a stronger word (_relentless_), not a different technique.
+- **Negation** — steering by prohibition backfires: _don't think of an elephant_ names the elephant and makes it more available, not less. Prompt the **positive** — state the target behaviour so the banned one is never spoken; keep a prohibition only as a hard guardrail you can't phrase positively, and even then pair it with what to do instead.

.agents/skills/writing-shape/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: writing-shape
+description: Writing, exploit — shape raw material into an article, paragraph by paragraph.
+disable-model-invocation: true
+---
+
+<what-to-do>
+
+The user has passed (or will pass) a markdown file of raw material. Treat it as the input pile — anything from a tidy list of fragments to a wall of unstructured prose to a transcript. The format does not matter. Read it end-to-end before doing anything else.
+
+Then run a shaping session that produces a separate article document. This is **exploit**: the exploring is done, the pile is fixed — commit to a structure and mine the pile to fill it. Do not edit the raw material file — it is read-only to this skill.
+
+If the user did not say where to save the article, ask once and remember the path.
+
+</what-to-do>
+
+<supporting-info>
+
+## The loop
+
+1. **Read the pile.** Read the input file in full. Form a sense of what's in it.
+2. **Establish the prerequisites.** Settle with the user what the reader knows walking in — the concepts that are **grounded** from the start. Everything else must be grounded by a block before a later block can lean on it. See [Grounding](#grounding).
+3. **Draft 2–3 candidate openings.** Each opening should imply a different thesis or angle for the article. Show all of them. Force the user to pick or compose a hybrid. The chosen opening defines what the rest of the article must do.
+4. **Grow paragraph by paragraph.** After the opening lands, ask "given this opening, what does the reader need to hear next?" Pull material from the pile to answer. The next block may only lean on grounded concepts, and grounds new ones as it lands. Argue about the form the next block takes — a paragraph, a list, a table, a callout, a quote, a code block. Each format choice should be deliberate and defensible.
+5. **Append to the article file as you go.** Don't batch. Write each agreed paragraph or block immediately so the user can see the article taking shape.
+6. **Loop step 4 until the article is done.** The user decides when it's done.
+
+## Grounding
+
+Every **concept** has to be **grounded** before a block can lean on it: the reader either walked in knowing it or met it in an earlier block. A block that reaches for an ungrounded concept loses the reader. The unit is the concept, not the word for it — a block can lean on an idea the reader lacks even with no jargon in sight. Where a concept has a name — a **term** — grounding it means landing the idea and the term together.
+
+A concept gets grounded one of two ways:
+
+- **Prerequisite** — grounded before the opening. The reader brings it. Fixed at the start.
+- **Introduced** — a block establishes it, and from then on it's grounded for the rest of the article.
+
+Keep a running list of what's grounded. When you ask "what does the reader need to hear next?", an ungrounded concept the next move needs is itself the answer: ground it first — here or in an earlier block — or you can't make the move. This is the gap-naming of [Pulling from the pile](#pulling-from-the-pile) one level up: there the pile is missing material; here the article is missing a foundation.
+
+The lever is what you make a prerequisite versus what you ground inside the article. Demand too much up front and you shut readers out; ground too much inside and the opening drowns in definitions. Settle it with the user when you establish prerequisites.
+
+## Conversational feel
+
+This is a grilling session inverted. In ideation, the question was "what are you actually noticing?" Here it's "what is this article actually arguing, and in what order does the reader need to hear it?" Push back. Refuse to let weak transitions slide. If a paragraph doesn't earn its place, cut it.
+
+Specific moves to keep using:
+
+- "What does this paragraph do for the reader that the previous one didn't?"
+- "If I cut this, what breaks?"
+- "Is this prose, or should it be a list? Why prose?"
+- "This sentence is doing two jobs — split it or pick one."
+- "The opening promised X. We've drifted to Y. Either re-thread it or change the opening."
+
+## Pulling from the pile
+
+Treat the raw material as a quarry, not a script. Pull a fragment, rework it to fit the surrounding paragraph, and place it. A fragment may be split across multiple paragraphs, merged with another, or paraphrased. The pile's job is to be mined; the article's job is to read as one voice.
+
+If the pile lacks something the article needs, name the gap explicitly: "We need an example here and the pile doesn't have one — give me one now or we cut this section."
+
+## Format arguments to actually have
+
+When choosing how to render a block, weigh these tradeoffs out loud with the user, not silently:
+
+- **Prose vs. list.** Prose carries argument; lists carry parallel items. If items aren't truly parallel, prose is better. If they are, a list is faster to scan.
+- **Inline vs. callout.** Tips, warnings, and asides go in callouts (`> [!TIP]`, `> [!NOTE]`) — but only if they'd genuinely derail the main argument inline. Otherwise leave them inline.
+- **Table vs. repeated structure.** If the same shape repeats 3+ times with the same fields, a table. Otherwise prose with bold leads.
+- **Quote vs. paraphrase.** Quote when the original wording is the point. Paraphrase when only the idea matters.
+- **Code block vs. inline code.** Multi-line, runnable, or illustrative → block. Single token or identifier → inline.
+
+## Writing rhythm
+
+Append to the article file as each block is agreed. Re-read the file from disk before every write — the user may have edited between turns. Never overwrite blindly. If the user wants a paragraph rewritten, edit that specific paragraph in place; leave the rest alone.
+
+## Out of scope
+
+- Mining for new fragments that aren't in the pile (handle gaps as in "Pulling from the pile").
+- Editing the raw material file.
+- Publishing, formatting for a specific platform, or adding frontmatter the user didn't ask for.
+
+</supporting-info>

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## Summary
+<!-- Briefly describe what this PR does -->
+
+## Checklist
+- [ ] Fork synced with upstream master (`git merge upstream/master`)
+- [ ] `ruff check && ruff format` passes
+- [ ] `pytest tests/ --ignore=tests/sandbox -x` passes
+- [ ] Plugin changes: `npx vitest run` in `paperforge/plugin/` passes
+- [ ] No secrets, API keys, or `.env` files committed

.github/workflows/ci-chaos.yml

@@ -0,0 +1,37 @@
+name: Chaos Tests (L6)
+
+on:
+  schedule:
+    # Weekly: Sunday 06:00 UTC
+    - cron: "0 6 * * 0"
+  workflow_dispatch:
+    # Manual trigger from GitHub UI
+
+jobs:
+  chaos-tests:
+    name: Chaos / Destructive Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package with test dependencies
+        run: |
+          pip install -e ".[test]"
+          pip install pytest pytest-timeout responses PyYAML
+
+      - name: Run chaos tests
+        run: |
+          python -m pytest tests/chaos/ -m chaos -v --tb=long --timeout=120 \
+            --junit-xml=chaos-results.xml
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: chaos-test-results
+          path: chaos-results.xml

.github/workflows/ci.yml

@@ -0,0 +1,108 @@
+# CI — Simplified Pipeline
+# Runs on push/PR to master. All tests run (no -x early exit).
+
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+    paths-ignore:
+      - "**.md"
+      - "docs/**"
+  pull_request:
+    branches: [main, master]
+
+env:
+  PYTHONIOENCODING: utf-8
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # L0 — Version consistency check
+  # ---------------------------------------------------------------------------
+  version-check:
+    name: L0 — Version Sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install package
+        run: pip install -e .
+      - name: Check version consistency
+        run: python scripts/check_version_sync.py
+
+  # ---------------------------------------------------------------------------
+  # L1 — Unit tests (3 OS x 1 Python)
+  # ---------------------------------------------------------------------------
+  unit-tests:
+    name: L1 — Unit Tests (${{ matrix.os }}, py3.11)
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install package with test deps
+        run: pip install -e ".[test]"
+      - name: Run unit tests
+        shell: bash
+        run: |
+          python -m pytest tests/unit/ \
+            -v --tb=short --timeout=60
+
+  # ---------------------------------------------------------------------------
+  # L3 — Plugin tests (Vitest)
+  # ---------------------------------------------------------------------------
+  plugin-tests:
+    name: L3 — Plugin Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+          cache-dependency-path: paperforge/plugin/package-lock.json
+      - run: npm ci
+        working-directory: paperforge/plugin
+      - run: npx vitest run --reporter=verbose
+        working-directory: paperforge/plugin
+
+  # ---------------------------------------------------------------------------
+  # L4 — E2E + Audit
+  # ---------------------------------------------------------------------------
+  e2e-tests:
+    name: L4 — E2E + Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install package with test deps
+        run: pip install -e ".[test]"
+      - name: Run E2E tests
+        run: python -m pytest tests/e2e/ -m e2e -v --tb=short --timeout=120
+      - name: Run audit tests
+        run: python -m pytest tests/audit/ -m audit -v --tb=short --timeout=120
+
+  # ---------------------------------------------------------------------------
+  # Merge gate
+  # ---------------------------------------------------------------------------
+  alls-green:
+    name: All Checks Passed
+    if: always()
+    needs:
+      - unit-tests
+      - plugin-tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: re-actors/alls-green@v1.2.2
+        with:
+          allowed-skips: version-check
+          jobs: ${{ toJSON(needs) }}

.github/workflows/publish.yml

@@ -0,0 +1,55 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+      - '[0-9]*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+          cache-dependency-path: paperforge/plugin/package-lock.json
+
+      - name: Build Python package
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Build plugin bundle
+        working-directory: paperforge/plugin
+        run: |
+          npm ci
+          npm run build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+          skip-existing: true
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release view "${{ github.ref_name }}" > /dev/null 2>&1 && gh release delete "${{ github.ref_name }}" --yes || true
+          gh release create "${{ github.ref_name }}" \
+            --title "${{ github.ref_name }}" \
+            --generate-notes \
+            paperforge/plugin/main.js \
+            paperforge/plugin/styles.css \
+            paperforge/plugin/manifest.json \
+            paperforge/plugin/versions.json

.github/workflows/release.yml

@@ -0,0 +1,47 @@
+# Auto-release Obsidian plugin on tag push
+# Triggered by tags like v1.4.18. Runs plugin tests, then creates a GitHub Release
+# with the 4 required Obsidian plugin files.
+
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+      - '[0-9]*'
+
+jobs:
+  release:
+    name: Release Plugin
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+          cache-dependency-path: paperforge/plugin/package-lock.json
+
+      - name: Run plugin tests
+        working-directory: paperforge/plugin
+        run: |
+          npm ci
+          npx vitest run --reporter=verbose
+
+      - name: Build plugin bundle
+        working-directory: paperforge/plugin
+        run: npm run build
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ github.ref_name }}
+          generate_release_notes: true
+          files: |
+            paperforge/plugin/main.js
+            paperforge/plugin/styles.css
+            paperforge/plugin/manifest.json
+            paperforge/plugin/versions.json

.gitignore

@@ -20,9 +20,12 @@ build/
 config.json
 
 # Data (user-specific)
+Bases/
 05_Bases/
+System/
 99_System/
 00_Inbox/
+Resources/
 03_Resources/
 
 # Test sandbox (wizard output)
@@ -31,3 +34,27 @@ tests/sandbox/00_TestVault/
 # OS
 .DS_Store
 Thumbs.db
+.worktrees/
+
+.vite/
+paperforge/plugin/node_modules/
+
+# Temp files
+.opencode/tmp/
+.ai-bridge/
+
+# Audit per-paper artifacts (keep root-level summary files)
+audit/*/
+!audit/*.json
+!audit/*.md
+
+# Temp / generated files
+.git-rewrite/
+.tmp/
+local-*.md
+loss_*.md
+audit/tmp_pdf/
+audit/media_asset_samples/
+
+# OpenCode MCP binaries
+.opencode/mcp/

.husky/pre-commit

@@ -0,0 +1 @@
+cd paperforge/plugin && npx lint-staged && npm run typecheck && npm run test

.omp/AGENTS.md

@@ -0,0 +1,34 @@
+# PaperForge — Project Record Management
+
+Project state is split across three layers with distinct roles:
+
+- **Narrative ledger** (`PROJECT-MANAGEMENT.md`) — full history, updated every session end
+- **Active queue** (`project/current/ocr-v2-active-queue.md`) — next-work priorities, updated at milestones
+- **Archive** (`project/archive/`) — superseded files from `current/`, moved not deleted
+
+## Update Rules
+
+### PROJECT-MANAGEMENT.md — Every Session End
+
+Update before final commit. Touches:
+- Executive summary (§0) — one-line current state + next action
+- Current status (§2) — test counts, component state, fix table
+- Remaining issues (§3) — resolved out, new ones in
+- Active queue checkpoint (§4) — next steps
+- Decision log (§6) — one line per decision with rationale
+- Session timeline (§8) — compressed one-line record
+
+### project/current/ — Milestones Only
+
+`ocr-v2-active-queue.md` updates after major fix series or priority shifts. Never mid-session.
+Other `ocr-v2-*.md` files: update only when architecture or evidence changes.
+
+### project/archive/ — Move, Don't Delete
+
+When a current file no longer reflects active truth: prepend archive header (date + reason + replacement), move to `project/archive/`, remove from `current/`.
+
+## Format Conventions
+
+- **Timeline entry** (§8): `| YYYY-MM-DD | Short title | Key results — what was done, what was found | §N.M |`
+- **Decision log** (§6): `| YYYY-MM-DD | Decision title | Rationale — why, not what |`
+- **Fix table** (§2.3): `| # | Paper + symptom | Root cause | Fix approach | Commit |`

.omp/RULES.md

@@ -0,0 +1,11 @@
+# Matt Workflow Guardrails
+
+- Ask Matt owns the engineering lifecycle: route with `/ask-matt`, implement one agent-ready issue with `/implement`, then run `/review`. Do not introduce a second orchestration workflow.
+- One implementation session handles one issue in one authoritative worktree. Start a fresh session before changing issues; use `/handoff` only when context must cross sessions.
+- Before editing, pin the issue, parent PRD, issue `updated_at`, base SHA, worktree root, scope, acceptance criteria, and verification commands. If the issue changes, stop and refresh this contract.
+- Use one writer. Parallel `task` batches may contain only read-only `scout`, `reviewer`, or `librarian` agents. Never let parallel agents edit shared files or the same worktree.
+- Never copy implementation files between the main checkout and a worktree. All reads, writes, tests, reviews, and commits for an issue use its authoritative worktree.
+- Follow Matt `/tdd` at pre-agreed seams. Run focused checks while implementing and the issue-specific final gate once after the last mutation; UI work also needs a real-browser smoke test.
+- Review exactly once on Matt's two axes. Consolidate findings into one repair pass and one re-review. If an important defect remains, return to the acceptance contract or split the issue; do not create repeated Final/Definitive review loops.
+- Commit, merge, push, create/merge a PR, or close an issue only after verification succeeds after the last mutation. Update `PROJECT-MANAGEMENT.md` and the active queue according to project rules before closeout.
+- The removed Superpowers workflows are not part of this project. Do not reinstall, invoke, emulate, or delegate through them.

.omp/WATCHDOG.md

@@ -0,0 +1,59 @@
+# Advisor policy — sparse, risk-focused review
+
+Your job is not to optimize, polish, or co-design.
+Your job is to prevent expensive mistakes.
+
+Default to silence.
+
+Only speak when one of these is true:
+
+1. The agent is about to do something dangerous, irreversible, or likely to damage user work, data, or repo state.
+2. The agent is making a design decision that is clearly brittle, unstable, or likely to cause incorrect behavior, hidden coupling, or expensive rework.
+3. The agent is operating on a false assumption that will likely invalidate the current line of work.
+4. The agent is about to miss a hard constraint that materially changes correctness.
+
+Priorities:
+- Dangerous actions
+- Data loss or destructive operations
+- Broken or fragile architecture
+- Incorrect assumptions with high downstream cost
+- Real correctness risks
+
+De-prioritize or ignore:
+- Style suggestions
+- Naming improvements
+- Small refactors
+- "Could be cleaner" comments
+- Alternative designs unless the current one is materially risky
+- Minor optimizations
+- General best-practice commentary
+
+Severity policy:
+- Use `blocker` only for clear stop-now situations.
+- Use `concern` only for high-confidence, high-cost risks.
+- Avoid `nit` unless the note prevents future confusion at near-zero token cost.
+- When in doubt, do not advise.
+
+Token discipline:
+- Prefer no message over a low-value message.
+- Never restate what the agent already knows.
+- Never give a suggestion unless the expected benefit clearly exceeds the token cost.
+- Keep advice extremely short, concrete, and decision-oriented.
+
+Design review stance:
+- Allow local freedom when the design is reasonable.
+- Intervene only when the design is not robust enough for likely real use.
+- Do not push ideal architecture over adequate architecture unless the current path is likely to fail.
+
+One-message rule:
+- If multiple issues exist, report only the highest-severity, highest-leverage one.
+- Do not stack minor concerns.
+
+Additional strictness:
+- Treat absence of advice as the normal outcome.
+- Do not emit advice for speculative risks.
+- Do not emit advice for possible-improvement comments.
+- Only intervene when the risk is concrete enough that a careful reviewer would be surprised if nothing were said.
+
+Reminder:
+Silence is success. Speak only when the agent is likely to make a costly mistake.

.omp/config.yml

@@ -0,0 +1,10 @@
+memory:
+  backend: mnemopi
+mnemopi:
+  scoping: per-project
+
+advisor:
+  enabled: true
+  subagents: false
+  syncBacklog: off
+  immuneTurns: 8

.omp/hooks/pre/matt-guard.test.ts

@@ -0,0 +1,90 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import register from "./matt-guard";
+
+type Handler = (
+  event: Record<string, unknown>,
+  context?: { cwd: string },
+) => unknown | Promise<unknown>;
+
+const root = path.resolve(import.meta.dir, "../../..");
+
+function handlers() {
+  const registered: Record<string, Handler> = {};
+  register({
+    on: (event: string, handler: Handler) => {
+      registered[event] = handler;
+    },
+  } as unknown as Parameters<typeof register>[0]);
+  return registered;
+}
+
+function foreignWorktree(): string | undefined {
+  const current = path.normalize(root).toLowerCase();
+  return execFileSync("git", ["worktree", "list", "--porcelain"], {
+    cwd: root,
+    encoding: "utf8",
+  })
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith("worktree "))
+    .map((line) => path.normalize(line.slice("worktree ".length)))
+    .find((worktree) => worktree.toLowerCase() !== current);
+}
+
+describe("Matt workflow guard", () => {
+  test("allows parallel read-only agents and blocks a writer", async () => {
+    const hook = handlers();
+    const context = { cwd: root };
+
+    expect(
+      await hook.tool_call(
+        {
+          toolName: "task",
+          input: { tasks: [{ agent: "reviewer" }, { agent: "scout" }] },
+        },
+        context,
+      ),
+    ).toBeUndefined();
+    expect(
+      await hook.tool_call(
+        {
+          toolName: "task",
+          input: { tasks: [{ agent: "reviewer" }, {}] },
+        },
+        context,
+      ),
+    ).toMatchObject({ block: true });
+  });
+
+  test("requires verification after the latest mutation", async () => {
+    const hook = handlers();
+    const context = { cwd: root };
+    const commit = { toolName: "bash", input: { command: "git commit --dry-run" } };
+
+    expect(await hook.tool_call(commit, context)).toMatchObject({ block: true });
+    await hook.tool_result({
+      toolName: "bash",
+      input: { command: "npm test" },
+      isError: false,
+      details: { exitCode: 0 },
+    });
+    expect(await hook.tool_call(commit, context)).toBeUndefined();
+
+    await hook.tool_call({ toolName: "edit", input: "mutation" }, context);
+    expect(await hook.tool_call(commit, context)).toMatchObject({ block: true });
+  });
+
+  test.skipIf(!foreignWorktree())("blocks writes into another linked worktree", async () => {
+    const hook = handlers();
+    const target = path.join(foreignWorktree()!, "CONTEXT.md");
+
+    expect(
+      await hook.tool_call(
+        { toolName: "write", input: { path: target } },
+        { cwd: root },
+      ),
+    ).toMatchObject({ block: true });
+  });
+});

.omp/hooks/pre/matt-guard.ts

@@ -0,0 +1,211 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+const READ_ONLY_AGENTS: Record<string, true> = {
+  scout: true,
+  reviewer: true,
+  librarian: true,
+};
+const RELEASE_COMMAND =
+  /\bgit(?:\.exe)?\b[^\r\n;&|]*\b(?:commit|merge|push)\b|\bgh(?:\.exe)?\s+(?:issue\s+close|pr\s+(?:create|merge))\b/i;
+const VERIFICATION_COMMAND =
+  /\b(?:pytest|unittest|vitest|jest|ruff|mypy|pyright|tsc)\b|\b(?:npm|pnpm|yarn|bun)\s+(?:test|run\s+(?:test|typecheck|build|lint))\b|\bcargo\s+(?:test|check)\b|\bgo\s+test\b|\bdotnet\s+test\b/i;
+const URI = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+interface GuardState {
+  verifiedAfterMutation: boolean;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function json(value: unknown): Record<string, unknown> {
+  try {
+    return record(JSON.parse(String(value ?? "")));
+  } catch {
+    return {};
+  }
+}
+
+function runGit(cwd: string, args: string[]): string {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function normalized(value: string): string {
+  const resolved = path.resolve(value);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function isWithin(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function crossesWorktrees(candidate: string, cwd: string): boolean {
+  if (!candidate || URI.test(candidate)) return false;
+
+  const current = runGit(cwd, ["rev-parse", "--show-toplevel"]);
+  if (!current) return false;
+
+  const target = normalized(path.resolve(cwd, candidate));
+  const currentRoot = normalized(current);
+  const worktrees = runGit(cwd, ["worktree", "list", "--porcelain"])
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith("worktree "))
+    .map((line) => normalized(line.slice("worktree ".length)));
+  return worktrees.some(
+    (root) => root !== currentRoot && isWithin(root, target),
+  );
+}
+
+function pathsFromCall(toolName: string, input: unknown): string[] {
+  const fields = record(input);
+
+  if (toolName === "edit") {
+    const patch = typeof input === "string" ? input : String(fields.input ?? "");
+    return [...patch.matchAll(/^\[([^#\r\n]+)#[0-9A-F]{4}\]$/gm)].map(
+      (match) => match[1],
+    );
+  }
+
+  if (toolName === "ast_edit") {
+    return Array.isArray(fields.paths) ? fields.paths.map(String) : [];
+  }
+
+  if (toolName === "lsp") {
+    return typeof fields.file === "string" ? [fields.file] : [];
+  }
+
+  if (toolName !== "write") return [];
+  const target = String(fields.path ?? "");
+  if (target === "xd://ast_edit") {
+    const payload = json(fields.content);
+    return Array.isArray(payload.paths) ? payload.paths.map(String) : [];
+  }
+  if (target === "xd://lsp") {
+    const payload = json(fields.content);
+    return typeof payload.file === "string" ? [payload.file] : [];
+  }
+  return URI.test(target) ? [] : [target];
+}
+
+function tasksFromCall(input: unknown): Record<string, unknown>[] {
+  const tasks = record(input).tasks;
+  return Array.isArray(tasks) ? tasks.map(record) : [];
+}
+
+function hasWriterTask(input: unknown): boolean {
+  return tasksFromCall(input).some(
+    (task) => READ_ONLY_AGENTS[String(task.agent ?? "")] !== true,
+  );
+}
+
+function isMutatingCall(toolName: string, input: unknown): boolean {
+  if (toolName === "edit" || toolName === "ast_edit") return true;
+  if (toolName === "task") return hasWriterTask(input);
+  if (toolName === "lsp") {
+    const fields = record(input);
+    return (
+      fields.action === "rename" ||
+      fields.action === "rename_file" ||
+      (fields.action === "code_actions" && fields.apply === true)
+    );
+  }
+  if (toolName !== "write") return false;
+
+  const fields = record(input);
+  const target = String(fields.path ?? "");
+  if (!URI.test(target)) return true;
+  if (target === "xd://ast_edit") return true;
+  if (target !== "xd://lsp") return false;
+
+  const payload = json(fields.content);
+  return (
+    payload.action === "rename" ||
+    payload.action === "rename_file" ||
+    (payload.action === "code_actions" && payload.apply === true)
+  );
+}
+
+function releaseAction(toolName: string, input: unknown): boolean {
+  const fields = record(input);
+  if (toolName === "bash") return RELEASE_COMMAND.test(String(fields.command ?? ""));
+  if (toolName === "github") {
+    return ["pr_create", "pr_push"].includes(String(fields.op ?? ""));
+  }
+  if (toolName !== "write" || fields.path !== "xd://github") return false;
+  return ["pr_create", "pr_push"].includes(String(json(fields.content).op ?? ""));
+}
+
+function successfulVerification(event: Record<string, unknown>): boolean {
+  if (event.toolName !== "bash" || event.isError === true) return false;
+  const input = record(event.input);
+  if (!VERIFICATION_COMMAND.test(String(input.command ?? ""))) return false;
+
+  const details = record(event.details);
+  const exitCode = details.exitCode ?? details.exit_code ?? details.code;
+  if (typeof exitCode === "number") return exitCode === 0;
+
+  const content = Array.isArray(event.content) ? event.content : [];
+  const text = content.map((chunk) => String(record(chunk).text ?? "")).join("\n");
+  return !/command exited with code\s+[1-9]\d*/i.test(text);
+}
+
+export default function mattGuard(pi: ExtensionAPI): void {
+  const state: GuardState = { verifiedAfterMutation: false };
+
+  pi.on("tool_call", async (event, ctx) => {
+    const toolName = String(event.toolName);
+    const input = event.input;
+
+    if (toolName === "task") {
+      const tasks = tasksFromCall(input);
+      if (tasks.length > 1 && hasWriterTask(input)) {
+        return {
+          block: true,
+          reason:
+            "Matt guard: parallel task batches may contain only scout, reviewer, or librarian agents. Use one writer.",
+        };
+      }
+    }
+
+    const crossWorktree = pathsFromCall(toolName, input).find((candidate) =>
+      crossesWorktrees(candidate, ctx.cwd),
+    );
+    if (crossWorktree) {
+      return {
+        block: true,
+        reason: `Matt guard: refusing write into another Git worktree: ${crossWorktree}`,
+      };
+    }
+
+    if (releaseAction(toolName, input) && !state.verifiedAfterMutation) {
+      return {
+        block: true,
+        reason:
+          "Matt guard: run the issue-specific verification gate after the last mutation before commit, merge, push, PR creation, or issue close.",
+      };
+    }
+
+    if (isMutatingCall(toolName, input)) state.verifiedAfterMutation = false;
+  });
+
+  pi.on("tool_result", async (event) => {
+    if (successfulVerification(event as unknown as Record<string, unknown>)) {
+      state.verifiedAfterMutation = true;
+    }
+  });
+}

.opencode/opencode.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "skills": {
+    "paths": [
+      ".opencode/skills",
+      "C:/Users/Lin/ponytail/skills"
+    ]
+  }
+}

.opencode/skills/paperforge-development/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: paperforge-development
+description: Use when doing PaperForge engineering or internal OCR truth-audit work. Triggered by: "OCR审计" "审OCR" "审计OCR" "审一下" "审计这篇" "block review" "ocr truth audit" "annotated pages" "看下角色对不对" "块角色" "visual audit" "对照一下图片" "校对block".
+---
+
+# PaperForge Development
+
+Developer-only skill family for internal PaperForge OCR audit work.
+
+Use this when the task is to inspect OCR truth, classify failures, and write audit evidence without changing the runtime PaperForge skill graph.
+
+## Route
+
+- OCR truth audit: `workflows/ocr-truth-audit.md`
+
+## Scripts
+
+- `scripts/ocr_truth_audit.py` — artifact generator (annotated pages, summaries, findings)
+- `scripts/audit_helpers.py` — structured data maps for vision agents (figure, frontmatter, reference, body)
+- `scripts/verify_review_coverage.py` — coverage verification
+- `scripts/diff_audit.py` — diff audit between truth and pipeline
+
+## Invariant
+
+- Truth first.
+- Do not start by authoring expectations.
+- Establish block-level truth from page visuals and artifacts before comparing pipeline behavior.
+
+## Agent Dispatch Rules (CRITICAL — read before any audit task)
+
+The #1 source of audit errors is using the wrong tool for the question.
+Follow these rules unconditionally:
+
+### When to dispatch `vision` subagent (MUST):
+
+The workflow in `workflows/ocr-truth-audit.md` Step 6 tells you the exact commands.
+Summary:
+
+| Audit domain | Data recipe | Vision template |
+|-------------|-------------|----------------|
+| Figures | `audit_helpers.py --recipe figure_map` | atoms/ocr-vision-audit-templates.md — Template 1 |
+| Frontmatter | `audit_helpers.py --recipe frontmatter_map` | Template 2 |
+| References | `audit_helpers.py --recipe reference_map` | Template 3 |
+| Body text | `audit_helpers.py --recipe body_text_map` | Template 4 |
+
+**Procedure:** (1) Run the recipe → get JSON. (2) Read the template. (3) Paste JSON into template. (4) Dispatch as `vision` subagent prompt.
+
+### Forbidden agent patterns:
+
+- `general` subagent claiming to "see" an annotated page. **Only `vision` can view images.**
+- Concluding figure matching from `figure_table_ownership_summary.json` alone. **Must cross-check with source `figure_inventory.json` AND visual truth.**
+- Reporting `reference_intrusion_candidates` as errors without checking block roles.**noise blocks in `reference_zone` are expected.**
+- "The block has 0 candidates so figure is on another page" without scanning `page_{N-1}_index.json` and `page_{N+1}_index.json`.
+
+### Finding trust boundaries (CRITICAL):
+
+The auto-generated findings in `audit_report.json` contain substantial noise.
+**Only these [CODE] checks are reliable — all others need [VISION]:**
+
+| Finding category | Trust? | Why |
+|-----------------|--------|-----|
+| `role_mismatch` (from diff_audit.py) | ✅ [CODE] | Direct string comparison, 100% |
+| `zone_mismatch` (from block_review.jsonl) | ✅ [CODE] | Direct string comparison, 100% |
+| `render_mapping_error` — non-noise blocks | ✅ [CODE] | Substring match, exclude noise |
+| `unmatched_asset_count > 0` | ✅ [CODE] | deterministic count from inventory |
+| `coverage_check status` | ✅ [CODE] | direct comparison |
+| `reference_span_audit status` | ✅ [CODE] | deterministic |
+| `same_page_boundary_error` | ❌ NEVER | Page-level heuristic, no actionable info |
+| `reference_span_error` (audit_report.json) | ⚠️ Partially | Span may be too wide; need vision to verify boundary |
+| `object_ownership_error` (audit_report.json) | ❌ NEVER | Misses unmatched assets entirely |
+| `render_mapping_error` — noise blocks | ❌ NEVER | noise should not be in fulltext |
+| `image_quality`, `font`, `color`, `typography` | ❌ [VISION] only | No metadata available |
+
+### Per-role audit strategies:
+
+Full methodology for each of the 28 canonical roles is in `atoms/ocr-role-audit-strategies.md`.
+Each role is classified into one of 4 tiers:
+
+| Tier | Method | Roles |
+|------|--------|-------|
+| A | Vision-required | `figure_asset`, `media_asset`, `figure_caption`, `figure_caption_candidate`, `table_caption`, `table_asset`, `table_html`, `structured_insert` |
+| B | Data-primary, vision-confirm | `body_paragraph`, `section_heading`, `subsection_heading`, `reference_item`, `reference_heading`, `backmatter_heading`, `backmatter_body` |
+| C | Data-sufficient | `paper_title`, `authors`, `affiliation`, `abstract_heading`, `abstract_body`, `keywords`, `frontmatter_support`, `frontmatter_noise`, `footnote` |
+| D | Structural-only | `tail_candidate_body`, `backmatter_boundary_*`, `ocr_raw_error`, `unknown_structural`, `page_header`, `page_footer`, `noise` |
+
+### Deep per-role + quality audit:
+
+**`atoms/ocr-vision-audit-master.md`** extends all 4 templates with:
+- Per-role analysis covering role/zone/reference AND quality (typography, image, table)
+- Cross-reference pathways linking all audit data sources for any block_id
+- Chart-type routing to `paperforge/skills/paperforge/atoms/chart-reading/*.md`
+- Full-page typography sweep (font consistency, alignment, orphans/widows, heading hierarchy)
+- Output format for block_review.jsonl with optional `quality_checks` and `page_typography` fields
+
+After the 4 recipe-driven vision passes in Step 6, run the master atom:
+```bash
+# Read the master atom before dispatching per-role vision
+cat .opencode/skills/paperforge-development/atoms/ocr-vision-audit-master.md
+```
+It contains the per-role data-cross-ref + quality-check methodology. Paste the relevant section into each vision subagent prompt depending on which role set the agent is reviewing.

.opencode/skills/paperforge-development/atoms/ocr-audit-report-schema.md

@@ -0,0 +1,131 @@
+# OCR Audit Report Schema
+
+Truth-first invariant:
+
+- Do not start by authoring expectations.
+- Determine truth from page visuals and artifacts first.
+- Use reports to record truth and mismatches, not to normalize incorrect output.
+
+External vault invariant:
+
+- The OCR source root is outside the repo.
+- The audit helper must not assume a repo-local literature vault.
+- The caller must provide `--source-root` or set `PAPERFORGE_OCR_ROOT`.
+
+## Required Output Files
+
+Write outputs under `audit/<paper_key>/`.
+
+Concrete example:
+
+ - `audit/CAQNW9Q2/audit_report.md`
+ - `audit/CAQNW9Q2/audit_report.json`
+ - `audit/CAQNW9Q2/audit_scope.json`
+ - `audit/CAQNW9Q2/block_review.jsonl`
+ - `audit/CAQNW9Q2/coverage_check.json`
+ - `audit/CAQNW9Q2/block_coverage_summary.json`
+ - `audit/CAQNW9Q2/page_risk_summary.json`
+ - `audit/CAQNW9Q2/reference_intrusion_candidates.json`
+ - `audit/CAQNW9Q2/figure_table_ownership_summary.json`
+ - `audit/CAQNW9Q2/fulltext_block_mapping_summary.json`
+ - `audit/CAQNW9Q2/reference_span_audit.json`
+ - `audit/CAQNW9Q2/annotated_pages/page_*_overview.png` — all-block overview with short numeric labels
+ - `audit/CAQNW9Q2/annotated_pages/page_*_index.json` — per-page block-to-metadata mapping
+
+## Primary Categories
+
+- `frontmatter_error`
+- `body_flow_error`
+- `reference_span_error`
+- `same_page_boundary_error`
+- `backmatter_error`
+- `object_ownership_error`
+- `reading_order_error`
+- `render_mapping_error`
+
+## Meta Category
+
+- `audit_truth_gap`
+
+Use `audit_truth_gap` when the audit process fails to surface real block-level truth or when prior expectations drift away from visual truth.
+
+## Severities
+
+- `critical`
+- `major`
+- `minor`
+- `cosmetic`
+
+Severity tracks trust and downstream damage, not implementation effort.
+
+## audit_report.json Example
+
+```json
+{
+  "paper_key": "CAQNW9Q2",
+  "mode": "high-risk",
+  "artifact_fingerprint": {
+    "result_json_hash": "...",
+    "structured_blocks_hash": "...",
+    "fulltext_hash": "...",
+    "document_structure_hash": "..."
+  },
+  "reviewed_pages": [1, 7, 8],
+  "reviewed_blocks": ["p1:b3", "p7:b12"],
+  "findings": [
+    {
+      "category": "reference_span_error",
+      "severity": "critical",
+      "block_ids": ["p7:b12"],
+      "truth": "block belongs outside reference span",
+      "pipeline_behavior": "rendered inside accepted references",
+      "root_cause_hypothesis": "same-page boundary inference overreach",
+      "evidence": {
+        "annotated_page": "annotated_pages/page_007.png",
+        "artifact": "structure/document_structure.json"
+      }
+    }
+  ]
+}
+```
+
+## reference_span_audit.json Example
+
+```json
+{
+  "reference_span": {
+    "status": "ACCEPT",
+    "span_id": "refspan_001",
+    "start": {
+      "page": 7,
+      "column": 1,
+      "y": 1032,
+      "block_id": "p7:b12"
+    },
+    "end": {
+      "page": 10,
+      "column": 2,
+      "y": 1398,
+      "block_id": "p10:b48"
+    },
+    "ordered_block_ids": ["p7:b12", "p7:b13"],
+    "inside_block_ids": ["p7:b12", "p7:b13"],
+    "explicitly_outside_nearby_block_ids": ["p7:b10", "p7:b11"],
+    "intrusion_candidates": []
+  }
+}
+```
+
+## Minimum Reporting Expectations
+
+- `audit_report.md` summarizes reviewed scope, freshness status, findings, and repair vs residual recommendations.
+- `audit_report.json` is the machine-readable source of findings.
+- `audit_scope.json` defines which pages and blocks must be reviewed for the chosen mode.
+- `block_review.jsonl` is the agent-written visual truth review log.
+- `coverage_check.json` is written by `verify_review_coverage.py` and must fail when mandatory reviews are missing.
+- `block_coverage_summary.json` tracks which blocks were reviewed and their review state.
+- `page_risk_summary.json` records page scores and reasons.
+- `reference_intrusion_candidates.json` records candidate reference contamination.
+- `figure_table_ownership_summary.json` records caption/asset/object mismatches.
+- `fulltext_block_mapping_summary.json` records source-to-render placement checks.
+- `reference_span_audit.json` records accepted reference span boundaries and intrusion checks.

.opencode/skills/paperforge-development/atoms/ocr-canonical-roles.md

@@ -0,0 +1,87 @@
+# OCR Canonical Roles
+
+`truth_role` in `block_review.jsonl` MUST be one of these canonical pipeline roles.
+Do not invent new role names — use only the set below. Non-canonical names
+will be normalized by `diff_audit.py` but relying on that is a workflow violation.
+
+## Frontmatter
+
+| Role | When |
+|------|------|
+| `paper_title` | Document title on page 1 |
+| `authors` | Author byline |
+| `affiliation` | Author affiliation block |
+| `frontmatter_support` | Correspondence, DOI, dates, data availability |
+| `frontmatter_noise` | Page-1 non-structural furniture (journal name, article type, publisher strip) |
+| `abstract_heading` | "Abstract" label |
+| `abstract_body` | Abstract body text |
+| `keywords` | Keywords block |
+
+## Body
+
+| Role | When |
+|------|------|
+| `section_heading` | Top-level section heading |
+| `subsection_heading` | Second-level section heading |
+| `sub_subsection_heading` | Third-level section heading |
+| `body_paragraph` | Narrative body paragraph |
+| `tail_candidate_body` | Body paragraph in the tail spread |
+
+## Reference
+
+| Role | When |
+|------|------|
+| `reference_heading` | "References" heading |
+| `reference_item` | Individual reference entry |
+
+## Backmatter
+
+| Role | When |
+|------|------|
+| `backmatter_heading` | Backmatter section heading (Acknowledgments, Funding, etc.) |
+| `backmatter_heading_candidate` | Possible backmatter heading, not yet confirmed |
+| `backmatter_body` | Backmatter body paragraph |
+| `backmatter_boundary_heading` | Confirmed backmatter boundary heading |
+| `backmatter_boundary_candidate` | Possible backmatter boundary |
+
+## Figure / Table
+
+| Role | When |
+|------|------|
+| `figure_asset` | Figure image/media |
+| `figure_caption` | Confirmed figure caption |
+| `figure_caption_candidate` | Probable figure caption, not fully confirmed |
+| `figure_inner_text` | Text inside a figure (panel labels, axis labels) |
+| `table_caption` | Confirmed table caption |
+| `table_caption_candidate` | Probable table caption, not fully confirmed |
+| `table_asset` | Table image |
+| `table_html` | HTML native table |
+| `table_html_candidate` | Probable HTML native table |
+| `media_asset` | Generic media image (when figure/table type is unclear) |
+
+## Structural Inserts
+
+| Role | When |
+|------|------|
+| `structured_insert` | Structured block (callout box, highlight, algorithm) |
+| `structured_insert_candidate` | Probable structured insert |
+| `non_body_insert` | Non-body decorative insert (publisher strip, sidebar filler) |
+
+## Noise & Fallback
+
+| Role | When |
+|------|------|
+| `noise` | Decorative line, page furniture, garbage OCR |
+| `footnote` | Page footnote |
+| `unknown_structural` | Block exists but no role fits (structural gate fallback) |
+| `ocr_raw_error` | OCR extraction failure (empty text) |
+| `page_header` | Running header repeat |
+| `page_footer` | Running footer repeat |
+
+## Ground Truth Only (seed roles, never final)
+
+These are assigned as `seed_role` by the early role assignment but never appear
+as the final pipeline output role. When auditing, use the final role above
+even if the seed role seems more intuitive:
+
+- `figure_title` (raw OCR label, not a final role)

.opencode/skills/paperforge-development/atoms/ocr-page-risk-scoring.md

@@ -0,0 +1,56 @@
+# OCR Page Risk Scoring
+
+Use this only for `high-risk` mode page selection.
+
+Truth-first note:
+
+- The score prioritizes likely inspection value.
+- It does not author expected truth.
+- Final judgment still comes from visual review plus artifact grounding.
+
+## Fixed Additive Formula
+
+```text
+page_risk_score =
+  +5 if page == 1
+  +5 if contains reference_heading
+  +4 if contains both body_paragraph and reference_item
+  +4 if contains tail/body/ref mixed evidence
+  +4 if figure/table asset count >= 2
+  +3 if caption count != asset count
+  +3 if reader/object coverage gap exists
+  +2 if verify-required HOLD count >= threshold
+  +2 if unknown_structural count >= threshold
+```
+
+## Risk Reason Hints
+
+Suggested reason labels:
+
+- `frontmatter_page`
+- `reference_heading_present`
+- `mixed_body_reference`
+- `same_page_boundary`
+- `multi_asset_page`
+- `caption_asset_mismatch`
+- `reader_object_gap`
+- `hold_threshold`
+- `unknown_structural_threshold`
+
+## Example Output Shape
+
+```json
+{
+  "page": 7,
+  "risk_score": 14,
+  "risk_reasons": [
+    "mixed_body_reference",
+    "reference_heading_present",
+    "same_page_boundary"
+  ],
+  "recommended_audit_targets": [
+    "reference_span",
+    "reading_order"
+  ]
+}
+```

.opencode/skills/paperforge-development/atoms/ocr-role-audit-strategies.md

@@ -0,0 +1,77 @@
+# OCR Per-Role Audit Strategies
+
+> **Use this as a quick reference** for deciding how to inspect any role.
+> For actual audit work, use `scripts/audit_helpers.py` recipes + `ocr-vision-audit-templates.md`.
+> Do NOT write custom Python for per-role checks — it's already built.
+
+## Tier Classification
+
+| Tier | Method | When |
+|------|--------|------|
+| A | **Vision-required** | Must dispatch `vision` subagent. Data alone insufficient. |
+| B | **Data-primary, vision-confirm** | Read data first. Dispatch vision only when data flags an issue. |
+| C | **Data-sufficient** | JSON analysis is enough. Vision only for ordering/layout ambiguity. |
+| D | **Structural-only** | Read from block trace / document structure. No vision needed. |
+
+## Role → Tier Mapping
+
+### Tier A — Vision-Required
+
+| Role | Why vision is needed |
+|------|---------------------|
+| `figure_asset` | Is the box covering an actual image? Are sub-panels merged? |
+| `media_asset` | Is this a figure, a table, or a phantom block? |
+| `figure_caption` | Is it a real caption, sub-panel label, or body mention? Where is its image? |
+| `figure_caption_candidate` | Should it be confirmed or demoted? |
+| `figure_inner_text` | Is it inside a figure (panel label) or separate text? |
+| `table_caption` | Same as figure_caption. Cross-page? |
+| `table_caption_candidate` | Should it be confirmed? |
+| `table_asset` | Is this actually a table image? |
+| `table_html` | Is the HTML table rendering correctly? |
+| `structured_insert` | Is this a callout box or mislabeled body text? |
+| `structured_insert_candidate` | Should it be confirmed? |
+| `non_body_insert` | What is this element visually? |
+
+### Tier B — Data-Primary, Vision-Confirm
+
+| Role | Data check | When to add vision |
+|------|-----------|-------------------|
+| `body_paragraph` | zone=body_zone? text non-empty? | zone wrong, text empty, or two-column ambiguity |
+| `section_heading` | numbering depth, heading absorption (two levels in one block) | verify visually if absorption detected |
+| `subsection_heading` | same as section_heading | same |
+| `sub_subsection_heading` | same | same |
+| `reference_heading` | in reference_zone? before first reference_item? | transition page boundary |
+| `reference_item` | in reference_zone? correct numbering pattern? | real intrusions or numbering gaps |
+| `backmatter_heading` | after last reference? in backmatter_zone? | if inside reference_zone |
+| `backmatter_body` | same | same |
+
+### Tier C — Data-Sufficient
+
+`paper_title`, `authors`, `affiliation`, `frontmatter_support`, `frontmatter_noise`,
+`abstract_heading`, `abstract_body`, `keywords`, `footnote`
+
+These are on page 1 (or page N for footnotes) at known positions with known patterns.
+Read `page_001_index.json`. Vision only for ordering ambiguity or badge mislabel suspicion.
+
+### Tier D — Structural-Only
+
+`tail_candidate_body`, `backmatter_boundary_candidate`, `backmatter_boundary_heading`,
+`ocr_raw_error`, `unknown_structural`, `page_header`, `page_footer`, `noise`
+
+Read from `blocks.structured.jsonl` (text, span_metadata, _ocr_raw_status) or
+`document_structure.json` (tail order, boundaries). No vision needed.
+
+## Common Failure Patterns (quick reference)
+
+| Pattern | Signal in data | Confirmation |
+|---------|---------------|-------------|
+| Sub-panels not merged | N asset blocks, 1 fig with < N assets | Vision: are they panels of same figure? |
+| Caption sandwiched between figs | close_asset_tie with above+below | Vision: which figure owns the caption? |
+| Cross-page caption | no_asset_match, prev/next page has orphan assets | Vision: is image on adjacent page? |
+| Sub-panel heading as caption | figure_caption with text like "Musculoskeletal conditions..." | Vision: is this a panel heading? |
+| Truncated legend as standalone | "Fig. 6" only, long caption below | Vision: composite figure with shared caption? |
+| Table mislabeled as figure | media_asset with raw_label=table | Vision: is this a table or figure? |
+| Body text as noise | noise with text_preview > 30 chars, not at page edge | Vision: is this body text? |
+| Heading absorption | section_heading text has "2. ... 2.1. ..." | Vision: two heading levels merged? |
+| Badge as authors | authors text = "HIGHLIGHTED PAPER" | Vision: is it a badge or authors? |
+| Reference zone intrusion | body_paragraph in reference_zone | Vision: verify boundary |

.opencode/skills/paperforge-development/atoms/ocr-vision-audit-master.md

@@ -0,0 +1,286 @@
+# OCR Vision Audit Master — CODE vs VISION 严格分离
+
+> **原则：** 每个检查标注来源。
+> `[CODE]` = 从 JSON 文件或 PDF 元数据精确提取，无需视觉判断。
+> `[VISION]` = 必须看 `page_NNN.png`，代码没有所需数据。
+>
+> 字体属性（family、size、weight、color、italic）在 `blocks.structured.jsonl` 的
+> `span_metadata` / `span_signature` 中，代码可直接提取。不要用 vision 做字体检查。
+
+---
+
+## 0. 数据源权限
+
+| 文件 | `[CODE]` 可读 | `[VISION]` 需要 |
+|------|-------------|----------------|
+| `page_NNN.png` | ❌ | ✅ |
+| `page_NNN_index.json` | ✅ role, zone, bbox, text | — |
+| `block_coverage_summary.json` | ✅ role, raw_label, zone, bbox | — |
+| `blocks.structured.jsonl` (OCR 源) | ✅ **span_metadata (font/color/size), span_signature, style_family** | — |
+| `block_review.jsonl` | ✅ truth_role, truth_zone, truth_reference_membership | — |
+| `figure_table_ownership_summary.json` | ✅ matched/ambiguous/unmatched 计数 | ⚠️ 验证匹配正确性 |
+| `fulltext_block_mapping_summary.json` | ✅ found_in_fulltext（排除 noise 后） | — |
+| `reference_span_audit.json` | ✅ inside/outside | ⚠️ 边界验证 |
+| `coverage_check.json` | ✅ 100% 可靠 | — |
+
+---
+
+## 1. `[CODE]` 自动化可信任检查
+
+以下从 JSON 数据直接提取，**不看图片**，结果决定性的。
+
+### 1.1 Role 一致性 — block_review.jsonl + diff_audit.py
+
+```yaml
+输入: block_review.jsonl 的 truth_role vs _current_role
+     changed_blocks_after_fallback.json
+方法: 字符串直接比较
+信任度: 100%
+输出: 每个 role mismatch 的 {block_id, pipeline_role, truth_role}
+```
+
+### 1.2 Zone 一致性 — block_review.jsonl
+
+```yaml
+输入: block_review.jsonl 的 truth_zone vs _current_zone
+方法: 字符串直接比较
+信任度: 100%
+```
+
+### 1.3 渲染完整性 — fulltext_block_mapping_summary.json
+
+```yaml
+输入: fulltext_block_mapping_summary.json
+      found_in_fulltext=false 且 role ∉ {noise, figure_inner_text, frontmatter_noise}
+方法: 前80字符子在渲染全文中的存在性检查
+信任度: 高（排除 noise 后），注意子串匹配微小误报可能
+输出: 真正在 fulltext 中丢失的 body_paragraph / reference_item / backmatter_body 等
+```
+
+### 1.4 图/表未匹配资产 — figure_table_ownership_summary.json
+
+```yaml
+输入: figures.unmatched_asset_count, tables.unmatched_asset_count
+方法: 直接计数
+信任度: 100%
+输出: 有未匹配资产的 paper，未匹配数量
+注意: 不判断为什么。vision 看具体原因。
+```
+
+### 1.5 覆盖完整性 — coverage_check.json
+
+```yaml
+输入: coverage_check.json 的 status, missing_block_ids
+信任度: 100%
+```
+
+### 1.6 字体一致性 — blocks.structured.jsonl
+
+从每个 block 的 `span_signature` 和 `span_metadata` 提取：
+
+```yaml
+输入: blocks.structured.jsonl 中所有 text block 的 span_signature
+     (font_family_norm, font_size_bucket, bold, italic)
+方法: 按 role 分组，检查组内一致性
+信任度: PDF 直接提取，100% 精确
+```
+
+**具体检查项：**
+
+```
+A. 同一 role 内 font_family_norm 一致吗？
+   - body_paragraph 应该全是同一字体（如 MyriadPro-Light）
+   - 如果某个 body_paragraph 的 font_family 与其他不同 → 混用字体
+
+B. 同一 role 内 font_size_bucket 一致吗？
+   - 所有 body_paragraph 的 font_size_bucket 应相同
+   - 差异 > 1pt → 字号不一致
+
+C. 标题层次递减正确吗？
+   - 按 page 分组，比较 section_heading / subsection_heading 的 font_size
+   - H1 > H2 > H3 在字体大小上应有明显递减
+
+D. 同一 block 内混用字体吗？
+   - span_metadata 有多个 entries 且 font 不同 → 可能是加粗/斜体标记混入
+   - 检查是否合理（如关键词加粗）还是问题（同一字体错误嵌入）
+
+E. 加粗/斜体使用一致吗？
+   - 所有 section_heading 的 bold=true？
+   - 所有 body_paragraph 的 bold=false？
+```
+
+### 1.7 排版布局 — blocks.structured.jsonl + bbox
+
+从每个 block 的 `bbox` 坐标提取：
+
+```yaml
+输入: blocks.structured.jsonl 的 bbox [x0, y0, x1, y1]
+     page_width, page_height
+```
+
+**具体检查项：**
+
+```
+A. 对齐方式检测：
+   每页取 body_paragraph 的 x0, x1 坐标：
+   - 如果所有 x0 相同 → 左对齐 (ragged right)
+   - 如果所有 x1 相同且 x0 不同 → 右对齐
+   - 如果 x0 和 x1 都跨block一致 → 居中对齐?
+   - 如果 x0 都相同但 x1 不同（各行不同长度）+ x1 抵边 → 两端对齐(justified)
+   - 跨页一致吗？
+
+B. 列检测：
+   每页对 body_paragraph 的 x-center 做聚类：
+   - 1个聚类 → 单栏
+   - 2个聚类 → 双栏（和 expected 一致？）
+   - 聚类中心 x-center 分布均匀？
+
+C. 页边距一致性：
+   每页 body_paragraph 的 min(x0) 应大致相同（左页边距）
+   每页 body_paragraph 的 max(x1) 应大致相同（右页边距）
+   跨页比较左/右边距是否一致
+
+D. 行间距检测：
+   同一列相邻 body_paragraph 的 y0 差值减去前一个 block 的高度
+   = 段间距
+   跨 block 段间距一致吗？
+
+E. 孤行/孤段检测：
+   如果一页上某个 body_paragraph 的 height < 正常行高的1.5倍
+   且它在页面顶部或底部 → orphan 或 widow
+```
+
+### 1.8 引用区间完整性 — reference_span_audit.json
+
+```yaml
+输入: reference_span_audit.json 的 status, inside_block_ids
+方法: status == "HOLD" → 区间未通过验证
+      inside_block_ids 中 role ≠ reference_item/heading → 可能 intrusion
+信任度: 状态可靠，intrusion 需要 vision 确认
+```
+
+---
+
+## 2. `[VISION]` 必须看图片
+
+以下检查代码**没有所需元数据**，必须看 `page_NNN.png`。
+
+### 2.1 图/表视觉验证
+
+```
+- 子面板覆盖：一个 figure 的 asset 列表覆盖了所有视觉上的子面板吗？
+- 子面板合并：2x2 的 grid 被合并为 1 个 figure 还是 4 个独立的？
+- caption 位置：在图上方/下方？跨页？
+- caption 语义：文字描述的内容与图上数据一致吗？（代码读不了图内容）
+- 表布局：HTML 表渲染正确？图片表完整无裁剪？
+- 角色误标：media_asset 实际上是 table？figure_caption 实际上是 section_heading？
+```
+
+### 2.2 图像质量
+
+```
+- 分辨率：模糊/锯齿/像素化？
+- 仪器截屏：显微镜软件、流式细胞仪输出？
+- 对比度：前景/背景区分足够？
+```
+
+### 2.3 颜色可达性（仅限图片中的颜色）
+
+```
+- 图片本身的配色（热图、荧光图等）
+- 是否只依赖红/绿区分条件？
+- 注意：文本颜色在 span_metadata.color 中，用代码检查
+```
+
+### 2.4 统计完整性（图中数据 vs caption 描述）
+
+```
+- 图中显示的误差棒/显著性标记与 caption 描述一致？
+- N 值标注了吗？
+- p 值标注与图例对应？
+- 热图 colorbar 标注完整？
+```
+
+### 2.5 Chart 类型识别 + 深度分析
+
+```
+识别 chart 类型 → 路由到 paperforge/skills/paperforge/atoms/chart-reading/{TYPE}.md
+然后用对应指南做深度检查。
+```
+
+### 2.6 引用区间边界验证
+
+```
+- 参考页第一页：body 在 "References" 前结束了吗？
+- 过渡页：body 和 ref 没有交错？
+- reference_zone 外的 reference_item 是否真的是引用条目？
+- intrusion candidate 是真的还是 span 边界误标？
+```
+
+---
+
+## 3. 不可信自动化结果（不用）
+
+以下数据不作为 finding，只做导航：
+
+| 数据 | 问题 | 替代用法 |
+|------|------|---------|
+| `same_page_boundary_error` (audit_report.json) | 纯页面角色计数，正常布局也被标 | vision 优先审这些页 |
+| `object_ownership_error` (audit_report.json) | 只报 ambiguous/unresolved，漏了大批量 unmatched_assets | 改为读 unmatched_asset_count |
+| noise block 的 render_mapping_error | noise 不该在 fulltext 中 | 排除 noise 后看 |
+| vision 做字体/颜色检查 | 不准，PDF 元数据更精确 | 用 blocks.structured.jsonl |
+
+---
+
+## 4. 输出格式
+
+```jsonl
+{
+  "block_id": "p3:12",
+  "page": 3,
+  "review_status": "reviewed",
+  "truth_role": "figure_asset",
+  "truth_zone": "display_zone",
+  "truth_reference_membership": "outside",
+  "evidence": {"annotated_page": "annotated_pages/page_003.png", "method": "visual+bbox"},
+  "short_reason": "Fig. 2A MRI image — role and zone correct",
+  "vision_checks": {
+    "subpanels_merged": "A (2 of 2 panels matched)",
+    "image_quality": "OK",
+    "chart_type": null
+  }
+}
+```
+
+`vision_checks` 可选，只记录 vision 实际检查的维度，未检查的用 `null`。
+
+---
+
+## 5. 工作流程
+
+```
+1. 跑 [CODE]
+   diff_audit.py → role/zone mismatch 列表
+   fulltext_block_mapping → 真实渲染丢失（排除 noise）
+   figure_table_ownership → unmatched_asset_count
+   coverage_check → 缺失 block
+   blocks.structured.jsonl → 字体一致性、排版异常
+
+2. 决定 vision 目标
+   优先:
+     - code 发现的 role mismatch block
+     - unmatched_asset > 0 的 figure
+     - body/reference 在 fulltext 丢失的 block
+     - 参考页第一页
+     - figure-heavy 页
+     - coverage FAIL 的 page
+
+3. 逐 block vision [VISION]
+   对选中 block:
+     看 annotated page → 确认角色/区域
+     如果是 figure → 子面板、质量、chart 路由
+
+4. 输出
+   block_review.jsonl 只写 vision 确认过的 block
+   不编造未看内容
+```

.opencode/skills/paperforge-development/atoms/ocr-vision-audit-templates.md

@@ -0,0 +1,251 @@
+# OCR Vision Audit Templates
+
+> **Purpose:** Structured prompts for vision agents. Each template pairs with a `--recipe` from `audit_helpers.py`.
+> The agent workflow: (1) run `audit_helpers.py --recipe figure_map` to get JSON → (2) read this template → (3) dispatch vision with data + template → (4) vision reports findings.
+>
+> **After running these 4 templates**, read `ocr-vision-audit-master.md` for the deep quality pass:
+> per-role cross-reference pathways, typography checks, chart-type routing to `paperforge/skills/paperforge/atoms/chart-reading/*.md`, figure/table quality checks.
+
+---
+
+## Template 1: Figure Verification
+
+**Data source:** `audit_helpers.py --recipe figure_map --key {KEY}`
+
+**Vision agent prompt (replace {KEY}, {DATA_JSON}, {PAGE_LIST}):**
+
+```
+You are auditing figure matching for paper {KEY}. Below is a structured summary
+of every figure the pipeline detected — matched, ambiguous, and unresolved.
+
+FIGURE DATA:
+{DATA_JSON}
+
+Annotated pages are at:
+  audit/{KEY}/annotated_pages/page_NNN.png  (color-coded block rectangles)
+  audit/{KEY}/annotated_pages/page_NNN_index.json  (maps label numbers to block IDs)
+
+For EACH figure in the data, look at the corresponding annotated page(s) and answer:
+
+### For every figure:
+
+1. VISUAL CONFIRMATION: Find the colored rectangle(s) for this figure on the annotated page.
+   - The label numbers on the PNG correspond to `block_id` in the data.
+   - The index JSON maps label_number → block_id, role, bbox.
+   - TRACE: Find the caption block first (its label number), then find each asset block.
+
+2. ASSET COVERAGE: Does the set of colored boxes cover ALL visible sub-panels of this figure?
+   - Count how many sub-panels the figure has (from the colored boxes on the page).
+   - Compare with `assets` list in the data. Are any sub-panels MISSING? Are any EXTRA?
+   - If data says N assets but visually you see M sub-panels: report the discrepancy.
+
+3. CAPTION CORRECTNESS: Is the caption text (shown in the data) visually the correct caption for this figure?
+   - Is the caption block positioned correctly relative to the figure (below, above, or side-by-side)?
+   - Does the caption text match what you see on the page?
+   - Is it a REAL caption (description of the figure), not a section heading or body text?
+
+4. SUB-PANEL MERGING: Are sub-panels of the SAME figure correctly grouped?
+   - If the page has a 2x2 grid of images with ONE shared caption, they should be ONE figure.
+   - If the data shows them as separate figures: that's a merge failure.
+   - If the data shows them as one figure with N assets: check that N matches visual sub-panels.
+
+5. CROSS-PAGE CHECK: If a figure's caption is on a different page than its assets:
+   - Is this correct (caption on page N+1, image on page N)? Or is it a mismatch?
+   - Look at both pages to confirm.
+
+6. ROLE MISLABELS:
+   - Is any `figure_caption` block actually a section heading? (e.g., "Figure 3. In vitro evaluation..." at the top of a new section)
+   - Is any `figure_asset` / `media_asset` block actually a table?
+   - Is any `figure_caption` actually just a sub-panel label ("Fig. 6" only, no description)?
+
+### For each figure, report:
+
+```
+Fig {N} — page {P} — status: {OK / PROBLEM}
+  Issue: {specific problem description}
+  Evidence: {what you see on the annotated page that supports this}
+```
+
+### After checking all figures, provide a summary:
+
+```
+Total figures: {N}
+OK: {M}
+Problems found: {K}
+
+Problem details:
+  Fig X: [one-line issue]
+  ...
+```
+
+### Common patterns to watch for:
+
+- **Truncated label as standalone figure:** "Fig. 6" with no description text, next to a long caption block below → these should be ONE figure with the long text as caption.
+- **Multi-panel grid as separate figures:** 4 images in a 2x2 grid, each with "Fig. N" label, one shared caption below → should be ONE composite figure.
+- **Caption between two figures:** "Fig. 2" caption sandwiched between Fig 2 image above and Fig 3 image below → caption belongs to the image ABOVE.
+- **Empty/phantom blocks in figure area:** A colored box with no visible content inside → the block detection created a ghost.
+    - **Cross-page orphan:** Caption on page N, image on page N-1 → normal for preproofs.
+```
+
+---
+
+## Template 2: Frontmatter Verification
+
+**Data source:** `audit_helpers.py --recipe frontmatter_map --key {KEY}`
+
+**Vision agent prompt:**
+
+```
+You are auditing page 1 (frontmatter) for paper {KEY}.
+
+FRONTMATTER DATA:
+{DATA_JSON}
+
+Annotated page: audit/{KEY}/annotated_pages/page_001.png
+
+The data lists every block on page 1, top-to-bottom, with its pipeline-assigned role.
+Your job: verify each block's role against what you VISUALLY see on the page.
+
+### For each block, answer:
+
+1. ROLE CHECK: Is the assigned role correct?
+   - paper_title: should be the LARGEST text near the top, centered or left-aligned.
+   - authors: multiple names, usually below the title, smaller font.
+   - affiliation: institutional addresses, below authors.
+   - abstract_heading / abstract_body: "Abstract" label + paragraph text.
+   - frontmatter_noise: journal name, article type badge, publisher strip — small text at page edges.
+   - frontmatter_support: correspondence, DOI, dates.
+
+2. BADGE CHECK: Is there a "HIGHLIGHTED PAPER" or "RESEARCH ARTICLE" badge?
+   - If the data labels it as authors → WRONG.
+   - If the data labels it as noise → correct.
+
+3. MISSING ROLES: Are any expected roles missing?
+   - If data says `missing_expected: ["paper_title"]` → check if the title is absorbed into another block.
+   - If data says `missing_expected: ["abstract_heading"]` → check if the abstract exists but is labeled as body_paragraph.
+
+4. ORDERING: The blocks in the data are sorted top-to-bottom. Is this order visually correct?
+   - Expected: title → authors → affiliation → (badges/noise mixed in) → abstract → keywords → body text.
+   - If the order looks wrong visually, report the correct order.
+
+### Report format:
+
+```
+Page 1 — {paper_title}
+  Roles OK: {list of correct roles}
+  Roles WRONG:
+    p1:{block_id}: labeled as {role}, should be {correct_role}
+  Missing: {list}
+  Badge issue: {yes/no + detail}
+```
+```
+
+---
+
+## Template 3: Reference Verification
+
+**Data source:** `audit_helpers.py --recipe reference_map --key {KEY}`
+
+**Vision agent prompt:**
+
+```
+You are auditing reference completeness for paper {KEY}.
+
+REFERENCE DATA:
+{DATA_JSON}
+
+Annotated pages are at audit/{KEY}/annotated_pages/. Focus on:
+  - The first reference page (where references begin)
+  - The last reference page (where references end)
+  - Any "transition_pages" listed in the data
+
+### Check these specific things:
+
+1. REFERENCE BOUNDARY: On the first reference page, is there a clean boundary between body text and references?
+   - Look for the "References" heading (colored as reference_heading).
+   - Body text (green) should STOP before this heading.
+   - If body paragraphs appear AFTER the "References" heading → intrusion.
+
+2. INTRUSIONS: The data lists "real_intrusions" — body_paragraph or backmatter blocks inside the reference zone.
+   - If empty: no intrusions detected.
+   - If not empty: look at the specific pages listed. Are these REALLY inside the reference zone?
+   - Note: noise blocks (gray) between reference items are NORMAL (page numbers, headers).
+
+3. ZONE GAPS: The data lists references not in `reference_zone`.
+   - Look at the listed pages. Are these reference items that should be in reference_zone?
+   - If ALL refs on a page are in the wrong zone: the zone assignment failed for that page.
+
+4. TRANSITION PAGES: Pages where body and references co-exist.
+   - Look at the page: is the visual boundary clean?
+   - Is there body text that should have ended before the references?
+
+5. REFERENCE NUMBERING: The data lists missing or duplicate reference numbers.
+   - This is a data-derived check. No visual verification needed.
+   - Missing numbers may indicate references absorbed into body text → check visually if the missing references appear as body paragraphs.
+
+### Report format:
+
+```
+References — {total_references} total
+  Span: {start} → {end}
+  Boundary clean: {yes/no}
+  Real intrusions: {count or "none"}
+  Zone issues: {count or "none"}
+  Numbering gaps: {list or "none"}
+
+  Visual findings:
+    [page-specific observations]
+```
+```
+
+---
+
+## Template 4: Body Text Verification
+
+**Data source:** `audit_helpers.py --recipe body_text_map --key {KEY}`
+
+**Vision agent prompt:**
+
+```
+You are auditing body text cleanliness for paper {KEY}.
+
+BODY TEXT DATA:
+{DATA_JSON}
+
+The data lists, per page, every body_paragraph, noise, unknown_structural, and
+other content block with their bboxes, zones, and text previews.
+
+Annotated pages at audit/{KEY}/annotated_pages/page_NNN.png
+
+### For pages flagged in the data:
+
+1. NOISE IN CONTENT AREA: Blocks with `flag: text_in_content_area` or `flag: empty_in_content_area`.
+   - Look at the specific page. Is the noise block actually sitting in body text?
+   - Is it page furniture (page number, header) that happens to have non-edge coordinates?
+   - Is it a phantom (empty box with no visible content)?
+
+2. BODY TEXT WITH EMPTY TEXT: Body_paragraph blocks with `flag: empty_text_*`.
+   - Look at the bbox on the annotated page. Is there visible text at this position?
+   - If yes: OCR missed the text → PDF backfill needed.
+   - If no: the block is a phantom that should be removed.
+
+3. LARGE GAPS between body paragraphs (gap_px > 100).
+   - Look at what's in the gap (listed in `blocks_in_gap`).
+   - Is there supposed to be a figure, heading, or table here?
+   - Is it a two-column layout where the gap is the right-column text?
+
+4. TWO-COLUMN SUSPICION: If a page has body paragraphs with widely different x-centers.
+   - Look at the page layout. Is it genuinely two-column?
+   - Do the left and right columns each have coherent reading order?
+
+### Report format:
+
+```
+Body text — {page_count} pages checked
+  Pages with noise in content: {list}
+  Pages with empty body text: {list}
+  Pages with large gaps: {list}
+
+  Per-page findings:
+    Page {N}: [specific observations]
+```

.opencode/skills/paperforge-development/scripts/README.md

@@ -0,0 +1,5 @@
+# Scripts
+
+- `ocr_truth_audit.py` stages OCR audit artifacts and writes deterministic helper summaries under `audit/<paper_key>/`.
+- It requires an explicit external OCR root via `--source-root` or `PAPERFORGE_OCR_ROOT`.
+- It is developer-only and separate from `scripts/dev/` so the repo-local `paperforge-development` skill can evolve without touching the PaperForge product workflow.

.opencode/skills/paperforge-development/scripts/diff_audit.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Differential audit: compare existing block_review.jsonl truth against current pipeline output.
+
+Identifies blocks where pipeline role/zone now matches or still differs from human truth.
+Marks resolved entries and flags blocks needing re-audit. Updates block_review.jsonl in-place.
+
+Usage:
+    python diff_audit.py <KEY> --source-root D:/path/to/ocr [--audit-root D:/path/to/audit]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[5]))
+from paperforge.worker.ocr_artifacts import artifact_paths_for_root
+
+# Canonical role map: alias → pipeline output role name.
+_CANONICAL_ROLE = {
+    "media_asset": "figure_asset",
+    "structural_noise": "noise",
+    "author_list": "authors",
+    "running_header": "noise",
+    "page_marker": "noise",
+    "frontmatter_metadata": "frontmatter_noise",
+    "separator": "noise",
+}
+
+
+def _canonical(role: str) -> str:
+    return _CANONICAL_ROLE.get(role, role)
+
+
+def _load_jsonl(path: Path) -> list[dict]:
+    if not path.exists():
+        return []
+    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+
+
+def _write_jsonl(path: Path, rows: list[dict]) -> None:
+    with path.open("w", encoding="utf-8") as f:
+        for row in rows:
+            f.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Diff audit: compare truth roles with current pipeline")
+    ap.add_argument("key")
+    ap.add_argument("--source-root", dest="source_root", required=True)
+    ap.add_argument("--audit-root", dest="audit_root", default=None)
+    args = ap.parse_args()
+
+    source_root = Path(args.source_root)
+    audit_root = Path(args.audit_root) if args.audit_root else Path("audit")
+    paper_audit = audit_root / args.key
+    review_path = paper_audit / "block_review.jsonl"
+    changed_path = paper_audit / "changed_blocks_after_fallback.json"
+
+    reviews = _load_jsonl(review_path)
+    if not reviews:
+        print(f"No block_review.jsonl at {review_path} — nothing to diff.")
+        return
+
+    artifacts = artifact_paths_for_root(source_root, args.key)
+    if not artifacts.blocks_structured.exists():
+        print(f"ERROR: No structured blocks at {artifacts.blocks_structured}")
+        sys.exit(1)
+
+    structured = _load_jsonl(artifacts.blocks_structured)
+
+    # Index structured by key
+    struct_by_key: dict[str, dict] = {}
+    for block in structured:
+        page = block.get("page", 0)
+        bid = block.get("block_id")
+        if page is None or bid is None:
+            continue
+        key = f"p{page}:{bid}"
+        struct_by_key[key] = block
+
+    matches_truth = 0
+    needs_reaudit = 0
+    changed_items: list[dict] = []
+
+    for review in reviews:
+        bid = review.get("block_id", "")
+        truth_role = review.get("truth_role", "")
+        truth_zone = review.get("truth_zone", "")
+        current = struct_by_key.get(bid)
+        if not current:
+            continue
+
+        pipe_role = current.get("role", "")
+        pipe_zone = current.get("zone", "")
+        pipe_text_len = len(str(current.get("text", "")).strip())
+
+        role_match = _canonical(pipe_role) == _canonical(truth_role)
+        zone_match = not truth_zone or pipe_zone == truth_zone
+
+        if role_match:
+            review["_pipeline_verified"] = True
+            review["_current_role"] = pipe_role
+            matches_truth += 1
+        else:
+            review["_needs_reaudit"] = True
+            review["_current_role"] = pipe_role
+            review["_current_zone"] = pipe_zone
+            needs_reaudit += 1
+
+        changed_items.append({
+            "block_id": bid,
+            "truth_role": truth_role,
+            "pipe_role": pipe_role,
+            "pipe_zone": pipe_zone,
+            "pipe_text_len": pipe_text_len,
+            "role_match": role_match,
+            "zone_match": zone_match,
+        })
+
+    # Write summary
+    summary = {
+        "paper": args.key,
+        "total_reviewed": len(reviews),
+        "pipeline_verified": matches_truth,
+        "need_reaudit": needs_reaudit,
+        "changed_blocks": changed_items,
+    }
+    changed_path.write_text(json.dumps(summary, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+    # Normalize truth_role to canonical form in place, so future diffs
+    # match even without the alias map.
+    for review in reviews:
+        raw = str(review.get("truth_role") or "")
+        canonical = _canonical(raw)
+        if canonical != raw:
+            review["truth_role"] = canonical
+
+    # Write back updated block_review.jsonl
+    _write_jsonl(review_path, reviews)
+
+    print(f"Paper: {args.key}")
+    print(f"  Total reviewed: {len(reviews)}")
+    print(f"  Pipeline verified (role matches truth): {matches_truth}")
+    print(f"  Need re-audit (role still wrong): {needs_reaudit}")
+    print(f"Written: {changed_path}")
+    print(f"Updated: {review_path}")
+
+
+if __name__ == "__main__":
+    main()

.opencode/skills/paperforge-development/scripts/verify_review_coverage.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+
+REQUIRED_FIELDS = [
+    "block_id",
+    "page",
+    "review_status",
+    "truth_role",
+    "truth_zone",
+    "truth_reference_membership",
+]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Verify OCR truth-review coverage against audit_scope.json")
+    parser.add_argument("audit_dir", help="Path like audit/CAQNW9Q2")
+    return parser
+
+
+def _load_json(path: Path) -> dict:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _load_jsonl(path: Path) -> list[dict]:
+    rows: list[dict] = []
+    if not path.exists():
+        return rows
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        rows.append(json.loads(line))
+    return rows
+
+
+def _write_json(path: Path, payload: dict) -> None:
+    path.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def verify(audit_dir: Path) -> tuple[int, dict]:
+    scope_path = audit_dir / "audit_scope.json"
+    review_path = audit_dir / "block_review.jsonl"
+    if not scope_path.exists():
+        raise SystemExit(f"Missing audit scope: {scope_path}")
+    if not review_path.exists():
+        raise SystemExit(f"Missing block review file: {review_path}")
+
+    scope = _load_json(scope_path)
+    reviews = _load_jsonl(review_path)
+    required = {str(item): True for item in scope.get("required_block_ids", [])}
+    reviewed_valid: dict[str, dict] = {}
+    invalid_rows: list[dict] = []
+    page_counts: dict[int, int] = {}
+
+    for row in reviews:
+        block_id = str(row.get("block_id", "")).strip()
+        if not block_id:
+            invalid_rows.append({"block_id": None, "reason": "missing_block_id", "row": row})
+            continue
+        missing_fields = [field for field in REQUIRED_FIELDS if row.get(field) in (None, "")]
+        if row.get("review_status") != "reviewed":
+            missing_fields.append("review_status=reviewed")
+        evidence = row.get("evidence") or {}
+        if not isinstance(evidence, dict) or not evidence.get("annotated_page"):
+            missing_fields.append("evidence.annotated_page")
+        if missing_fields:
+            invalid_rows.append({"block_id": block_id, "reason": "missing_fields", "fields": missing_fields})
+            continue
+        reviewed_valid[block_id] = row
+        page = int(row.get("page", 0) or 0)
+        if page > 0:
+            page_counts[page] = page_counts.get(page, 0) + 1
+
+    missing_block_ids = sorted([block_id for block_id in required if block_id not in reviewed_valid])
+    missing_pages = []
+    for page_row in scope.get("selected_page_requirements", []):
+        page = int(page_row.get("page", 0) or 0)
+        if page_row.get("must_review_page") and page_counts.get(page, 0) == 0:
+            missing_pages.append(page)
+
+    status = "PASS"
+    if invalid_rows or missing_block_ids or missing_pages:
+        status = "FAIL"
+
+    coverage_ratio = (len(required) - len(missing_block_ids)) / len(required) if required else 1.0
+    report = {
+        "paper_key": audit_dir.name,
+        "mode": scope.get("mode"),
+        "required_block_ids": sorted(required.keys()),
+        "reviewed_block_ids": sorted(reviewed_valid.keys()),
+        "missing_block_ids": missing_block_ids,
+        "missing_pages": missing_pages,
+        "invalid_rows": invalid_rows,
+        "coverage_ratio": coverage_ratio,
+        "status": status,
+    }
+    return (0 if status == "PASS" else 1), report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    audit_dir = Path(args.audit_dir)
+    if not audit_dir.exists():
+        raise SystemExit(f"Audit dir not found: {audit_dir}")
+    code, report = verify(audit_dir)
+    _write_json(audit_dir / "coverage_check.json", report)
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.opencode/skills/paperforge-development/workflows/ocr-truth-audit.md

@@ -0,0 +1,210 @@
+# OCR Truth Audit
+
+Inputs:
+
+- explicit `paper_key`, or current paper from active context
+- `mode: strict | high-risk`
+
+## Pre-flight Checklist
+
+- [ ] Confirm this is developer/internal OCR audit work.
+- [ ] Resolve one target paper.
+- [ ] Confirm mode: `strict` or `high-risk`.
+- [ ] Do not start by writing expectations or fixtures.
+- [ ] Use visual and artifact truth first.
+- [ ] Know the report contract in `../atoms/ocr-audit-report-schema.md`.
+- [ ] Know the page ranking contract in `../atoms/ocr-page-risk-scoring.md`.
+- [ ] Know the canonical role list in `../atoms/ocr-canonical-roles.md` — `truth_role` MUST be from that list.
+
+## Workflow
+
+1. Resolve the paper.
+   Accept an explicit `paper_key`; otherwise use the current paper in context.
+
+   Also resolve the OCR root explicitly. The literature/OCR vault is outside the repo. Pass it with `--source-root` or set `PAPERFORGE_OCR_ROOT`.
+
+2. Refresh or check required artifacts.
+   Run `../scripts/ocr_truth_audit.py` with `--refresh-artifacts` when you need a fresh rebuild. Confirm availability of `block_trace`, `annotated_pages`, structured block artifacts, rendered `fulltext`, document-structure artifacts, and relevant figure/table artifacts.
+
+3. Verify artifact freshness before auditing.
+   Check that the paper PDF and derived artifacts belong to the same rebuild generation. At minimum compare fingerprints for `result_json`, raw/structured blocks, document structure, figure/table inventories, reader object outputs, and `fulltext`.
+
+4. Stop on stale artifacts.
+   If the required artifacts are out of sync, stop with `AUDIT_BLOCKED: stale artifacts` and record which artifacts mismatch.
+
+5. Generate helper summaries.
+   Materialize helper outputs under `audit/<paper_key>/` via `../scripts/ocr_truth_audit.py`, but treat them as accelerators only, not truth.
+
+6. Inspect truth from evidence.
+
+   The audit is split into **five phases**. Phase 6a-6d use the 4 recipes + 4 templates.
+   Phase **6e** is the deep quality pass using the master atom.
+   Work through them in this order.
+   Each domain has a **data map** (run the recipe) and a **vision template** (read the atom).
+
+   **6a. Figure verification (most error-prone — do this first).**
+   ```bash
+   python .opencode/skills/paperforge-development/scripts/audit_helpers.py --recipe figure_map --key {KEY}
+   ```
+   This prints a JSON listing every figure: caption page/text, asset blocks with bboxes,
+   match status, candidates, panel labels, cross-page flags.
+   Then read `../atoms/ocr-vision-audit-templates.md` → "Template 1: Figure Verification".
+   Dispatch a `vision` subagent with the figure_map JSON + that prompt template.
+   The vision agent checks: asset coverage, caption correctness, sub-panel merging,
+   cross-page pairing, role mislabels. Reports discrepancies between pipeline data and
+   visual truth.
+
+   **6b. Frontmatter verification.**
+   ```bash
+   python .opencode/skills/paperforge-development/scripts/audit_helpers.py --recipe frontmatter_map --key {KEY}
+   ```
+   Then read `../atoms/ocr-vision-audit-templates.md` → "Template 2: Frontmatter Verification".
+   Dispatch `vision` subagent with the frontmatter JSON + template.
+   Checks: role correctness on page 1, badge mislabel, missing roles, ordering.
+
+   **6c. Reference verification.**
+   ```bash
+   python .opencode/skills/paperforge-development/scripts/audit_helpers.py --recipe reference_map --key {KEY}
+   ```
+   Then read `../atoms/ocr-vision-audit-templates.md` → "Template 3: Reference Verification".
+   Dispatch `vision` subagent with the reference JSON + template.
+   Checks: reference boundary, real intrusions, zone gaps, transition pages.
+
+   **6d. Body text verification (only flagged pages need vision).**
+   ```bash
+   python .opencode/skills/paperforge-development/scripts/audit_helpers.py --recipe body_text_map --key {KEY}
+   ```
+   Then read `../atoms/ocr-vision-audit-templates.md` → "Template 4: Body Text Verification".
+   Most pages pass on data alone. Dispatch `vision` only for pages with
+   flagged gaps, noise-in-content, or empty body text blocks.
+
+   **6e. Deep quality + typography audit (new — extends all 4 domains).**
+   After the 4 recipe-driven vision passes, read `../atoms/ocr-vision-audit-master.md`.
+   This atom provides per-role cross-reference pathways, typography checks,
+   figure/table quality checks, chart-type routing to the chart-reading atoms,
+   and full-page layout audit.
+   
+   For each block that passed the recipe check, dispatch an additional vision pass
+   if the block is Tier A (figure/table/structured) or if the page has typography flags.
+   The master atom tells you which data files to cross-reference and what to look for.
+   
+   **Color reference for annotated pages:** Each role has a distinct color:
+   - dark blue: `paper_title` `authors` `affiliation` `frontmatter_*`
+   - purple: `abstract_heading` `abstract_body`
+   - orange/red: `section_heading` `subsection_heading` `sub_subsection_heading`
+   - green: `body_paragraph`
+   - red: `reference_heading` `reference_item`
+   - purple-brown: `backmatter_*`
+   - amber/gold: `figure_asset` `media_asset` `figure_caption*` `table_caption*` `figure_inner_text`
+   - teal: `structured_insert*` `non_body_insert`
+   - gray: `noise` `footnote` `unknown_structural`
+
+   The annotated pages show what the pipeline decided. Your job is to judge whether
+   that matches visual truth. The companion index (`page_*_index.json`) maps label
+   numbers to block IDs for cross-reference.
+
+7. Write audit outputs.
+   Produce the required reports and summaries using `../scripts/ocr_truth_audit.py` plus the schema in `../atoms/ocr-audit-report-schema.md`.
+
+8. Perform visual block review.
+   After prep outputs are written, inspect the selected pages and write `audit/<paper_key>/block_review.jsonl`. Every reviewed block must be grounded in page visuals plus bbox/artifact evidence.
+
+   **`truth_role` MUST be one of the canonical roles in `../atoms/ocr-canonical-roles.md`.**
+   Do not invent role names. The list includes `paper_title`, `authors`, `abstract_body`, `section_heading`, `body_paragraph`, `reference_item`, `backmatter_body`, `figure_caption`, `table_caption`, `noise`, and all other final pipeline roles.
+   Using old names (e.g. `media_asset` for `figure_asset`, `author_list` for `authors`, `structural_noise` for `noise`) is a workflow violation — `diff_audit.py` normalizes them, but the audit should be correct from the start.
+
+   Each line must include `block_id`, `page`, `review_status`, `truth_role`, `truth_zone`, `truth_reference_membership`, and `evidence` with `annotated_page` and `method`. Example:
+
+   ```json
+   {"block_id":"p5:9","page":5,"review_status":"reviewed","truth_role":"body_paragraph","truth_zone":"body_zone","truth_reference_membership":"outside","evidence":{"annotated_page":"annotated_pages/page_005.png","method":"visual+bbox"},"short_reason":"Conclusion body before references, not backmatter."}
+   ```
+
+   Use the page index to find a block's current role/zone before judging. Color category helps orient: red blocks are reference candidates, purple are backmatter candidates, etc.
+
+   For deep quality checks, see `../atoms/ocr-vision-audit-master.md` section 3 (chart quality),
+   section 4 (page typography), and section 2 (per-role analysis with quality dimensions).
+
+8.5. Record quality findings in block_review.jsonl.
+   Extend each block_review.jsonl entry with optional fields `quality_checks` and `page_typography`
+   as described in `../atoms/ocr-vision-audit-master.md` section 5. Use `null` for unchecked dimensions.
+
+9. Verify review coverage.
+   Run `../scripts/verify_review_coverage.py` against the paper audit directory. If required blocks are missing for the chosen mode, the audit is incomplete.
+
+## Script Entry Point
+
+Use:
+
+```bash
+python .opencode/skills/paperforge-development/scripts/ocr_truth_audit.py CAQNW9Q2 --source-root D:/YOUR/VAULT/System/PaperForge/ocr --mode high-risk --refresh-artifacts
+```
+
+For strict mode:
+
+```bash
+python .opencode/skills/paperforge-development/scripts/ocr_truth_audit.py DWQQK2YB --source-root D:/YOUR/VAULT/System/PaperForge/ocr --mode strict --refresh-artifacts
+```
+
+Coverage verification:
+
+```bash
+python .opencode/skills/paperforge-development/scripts/verify_review_coverage.py audit/DWQQK2YB
+```
+
+10. Classify findings.
+   Classify every real error into the frozen taxonomy. Use `audit_truth_gap` only when the audit layer itself misses or distorts block-level truth.
+
+11. Recommend disposition.
+   For each finding, recommend `repair` when it reflects a pipeline defect worth fixing now, or `residual` when it is real but intentionally deferred or outside the current close-out boundary.
+
+## Strict Mode
+
+Strict mode is full-coverage and block-oriented.
+
+- Every block gets a review state.
+- Every reviewed block records truth for role, zone, order, object membership, and reference membership.
+- Check role correctness against page context.
+- Check zone correctness against actual placement.
+- Check reading order and fulltext insertion point.
+- Check figure/table ownership where applicable.
+- Check reference membership and same-page boundary behavior where applicable.
+- Do not infer truth from current rendered output as the first step.
+
+Minimum review questions per block:
+
+- What is the true role?
+- What is the true zone?
+- What blocks should come before and after it?
+- Does it belong to a figure or table object?
+- Is it inside or outside the accepted reference span?
+
+## High-Risk Mode
+
+High-risk mode is rapid audit for trust-sensitive layout classes.
+
+- Rank pages with the additive score in `../atoms/ocr-page-risk-scoring.md`.
+- Prioritize frontmatter pages.
+- Prioritize first-reference and mixed reference pages.
+- Prioritize same-page body/reference/tail mixes.
+- Prioritize post-reference backmatter pages.
+- Prioritize figure-dense and table-dense pages.
+- Prioritize figure/table ownership and caption-matching failures.
+
+Recommended focus targets:
+
+- `frontmatter`
+- `reference_span`
+- `same_page_boundary`
+- `backmatter`
+- `object_ownership`
+- `reading_order`
+
+## Truth Rules
+
+Always follow this order:
+
+1. Determine block-level truth from page visuals and artifacts.
+2. Record the truth.
+3. Compare pipeline behavior against that truth.
+
+Never reverse the order by rewriting expected truth to fit current OCR output.

.planning/2026-07-10-retrieval-recovery-plan.md

@@ -0,0 +1,24 @@
+# Retrieval Recovery — Phase 1: Unified Contract
+
+> **For agentic workers:** Use TDD. Write failing test, watch it fail, implement minimal fix, verify green.
+
+**Goal:** Restore retrieval correctness by unifying the Python result envelope and fixing the plugin parser/spawn contracts.
+
+**Architecture:** Approach A — Python CLI is sole retrieval owner. Plugin spawns CLI per query, parses one unified PFResult envelope. sql.js deleted.
+
+**Tech Stack:** Python 3.14 (D:/L/OB/Literature-hub/.venv/Scripts/python.exe), TypeScript/esbuild Obsidian plugin, sqlite-vec 0.1.9, FTS5.
+
+## Global Constraints
+
+- Source Corpus (papers, OCR, blocks, metadata, annotations) MUST NOT be modified.
+- Retrieval Artifacts (FTS indexes, vec0 tables, companion meta) are disposable.
+- Python executable: `D:/L/OB/Literature-hub/.venv/Scripts/python.exe`
+- Vault: `D:/L/OB/Literature-hub`
+- Repository worktree: `D:/L/Med/Research/99_System/LiteraturePipeline/github-release/.worktrees/retrieval-recovery`
+- Test vault for disposable tests: `tests/fixtures/vault`
+- All CLI calls use `--vault` flag pointing to the test vault, never the live vault in tests.
+- Contract tests must parse real CLI JSON output, not mock it.
+- Existing 89 tests must keep passing.
+- Commit after every task with Conventional Commits style (repo convention: `feat:`, `fix:`, `chore:`).
+
+---

.planning/BRANCH-REVIEW.md

@@ -0,0 +1,84 @@
+---
+phase: branch-review-v1.6-ai-ready-asset-foundation
+reviewed: 2026-05-07T00:00:00Z
+depth: deep
+files_reviewed: 11
+files_reviewed_list:
+  - paperforge/worker/sync.py
+  - paperforge/worker/asset_index.py
+  - paperforge/worker/asset_state.py
+  - paperforge/worker/ocr.py
+  - paperforge/commands/context.py
+  - paperforge/worker/discussion.py
+  - paperforge/worker/repair.py
+  - paperforge/worker/status.py
+  - paperforge/setup_wizard.py
+  - paperforge/plugin/main.js
+  - pyproject.toml
+findings:
+  critical: 3
+  warning: 4
+  info: 0
+  total: 7
+status: issues_found
+---
+
+# Branch Review Report
+
+## Critical Issues
+
+### CR-01: First upgrade sync can delete legacy flat notes before preserving deep-reading content
+
+**File:** `paperforge/worker/sync.py:1547-1549,1649-1652,1719-1729`  
+**Issue:** `migrate_to_workspace()` refuses to migrate when no canonical index exists, but `run_index_refresh()` still proceeds to `build_index()` and later deletes matching flat notes once workspace folders exist. For a user upgrading from `master` with only legacy flat notes, the workspace note is rebuilt from scratch and the original flat note can then be deleted, dropping any existing `## 🔍 精读` content and other legacy note body content.
+
+**Fix:** Make migration scan legacy flat notes directly instead of depending on an existing index, and do not delete flat notes until deep-reading/body preservation has been verified in the workspace files.
+
+### CR-02: Legacy library-record workflow flags are dropped on upgrade
+
+**File:** `paperforge/worker/sync.py:652-677,735-737`; `paperforge/worker/asset_index.py:307-308`  
+**Issue:** The branch stops reading `do_ocr` / `analyze` from legacy `library-records` and `run_selection_sync()` explicitly skips any migration of those controls. `_build_entry()` now derives both flags only from formal notes or OCR meta. On upgrade from `master`, queued OCR/deep-reading selections stored only in library records are silently reset, breaking pending user workflows.
+
+**Fix:** Add an explicit one-time migration that imports `do_ocr`, `analyze`, and related state from legacy library-record files into formal-note frontmatter before the first rebuild, then keep the old files until migration succeeds.
+
+### CR-03: Canonical index can declare papers AI-ready even when required workspace assets do not exist
+
+**File:** `paperforge/worker/asset_index.py:334-338,357-364`; `paperforge/worker/asset_state.py:39-48,100-114`  
+**Issue:** `_build_entry()` always fills `paper_root`, `main_note_path`, `fulltext_path`, `deep_reading_path`, and `ai_path` as strings whether or not those files exist. `compute_lifecycle()` and `compute_health()` treat non-empty strings as sufficient, so entries can be marked `ai_context_ready` / `healthy` while `deep-reading.md` or `fulltext.md` is missing. That breaks the contract of the new canonical asset index and can feed dead paths to `paperforge context`, the dashboard, and downstream agents.
+
+**Fix:** Derive readiness from filesystem existence, not path-string presence. For example, require `Path(vault, fulltext_path).exists()` / `Path(vault, deep_reading_path).exists()` before returning `ai_context_ready` or `asset_health=healthy`.
+
+## Warnings
+
+### WR-01: Setup wizard accepts unsupported Python versions
+
+**File:** `paperforge/setup_wizard.py:137-146`; `pyproject.toml:10`; `paperforge/plugin/main.js:17-20`  
+**Issue:** The setup wizard passes Python `>=3.8` and the plugin UI advertises `3.9+`, but the package metadata requires `>=3.10`. Fresh installs can therefore be reported as valid by setup while later install/runtime steps fail on unsupported interpreters.
+
+**Fix:** Align every setup check and UI string to `>=3.10`.
+
+### WR-02: Discussion recorder can commit partial state on malformed Q&A payloads
+
+**File:** `paperforge/worker/discussion.py:185-189,314-333`  
+**Issue:** `record_session()` appends to `discussion.json` before rendering `discussion.md`, and `_build_md_session()` blindly indexes `qa['question']` / `qa['answer']`. A malformed QA item can therefore persist JSON, fail Markdown generation, and return an error after only half of the append completed.
+
+**Fix:** Validate each QA pair before any write, or build both JSON and Markdown payloads completely in memory before replacing either file.
+
+### WR-03: “Copy Collection Context” exports the whole vault, not the visible collection
+
+**File:** `paperforge/plugin/main.js:209-216,1319-1322`  
+**Issue:** The UI promises “all visible papers,” but `_runAction()` hardcodes `--all` for `needsFilter`. In collection mode this copies every indexed paper to the clipboard, which is both incorrect behavior and an avoidable prompt-scope leak.
+
+**Fix:** Pass the active collection/domain filter to `paperforge context` instead of defaulting to `--all`.
+
+### WR-04: Repair writes the canonical index through the non-atomic helper
+
+**File:** `paperforge/worker/repair.py:290-305,331-346`; `paperforge/worker/_utils.py:69-71`  
+**Issue:** `repair --fix` mutates `formal-library.json` using `write_json()` instead of the lock-protected atomic writer introduced in `asset_index.py`. Concurrent `sync`/`ocr`/dashboard reads can observe torn or stale index state.
+
+**Fix:** Route every canonical-index write through `asset_index.atomic_write_index()` (or rebuild via `refresh_index_entry()` / `build_index()` only).
+
+---
+
+_Reviewer: gsd-code-reviewer_  
+_Depth: deep_

.planning/MILESTONES.md

@@ -1,5 +1,76 @@
 # Milestones: PaperForge Lite Release Hardening
 
+## v1.8 AI Discussion & Deep-Reading Dashboard (Shipped: 2026-05-07)
+
+**Phases completed:** 6 phases (31-36)
+
+**Key accomplishments:**
+
+- Version display restored, "AI Ready" lifecycle stage removed from dashboard (Phase 31)
+- Deep-reading mode detection: `_resolveModeForFile()` prioritises deep-reading.md → zotero_key → global (Phase 32)
+- Deep-reading dashboard rendering: status card + Pass 1 extraction + AI Q&A collapsible history (Phase 33)
+- "Jump to Deep Reading" button on per-paper dashboard card (Phase 34)
+- AI discussion recorder: `discussion.py` writes atomic discussion.md + discussion.json into workspace ai/ (Phase 35)
+- Full E2E integration verification with CJK encoding and vault.read API (Phase 36)
+
+---
+
+## v1.9 Frontmatter Rationalization & Library-Record Deprecation (Shipped: 2026-05-07)
+
+**Phases completed:** 5 phases, 28 requirements (all verified)
+**Tests:** 188 passing
+
+**Key accomplishments:**
+
+- Slimmed formal note frontmatter from 28 to 16 fields: identity (title/year/journal/first_author/zotero_key/domain/doi/pmid/collection_path/impact_factor/abstract/tags) + workflow (has_pdf/do_ocr/analyze/ocr_status/deep_reading_status) + pdf_path
+- Created `paper_meta.py` — per-workspace JSON for internal pipeline state (OCR jobs, health, maturity, version)
+- Removed `library_record_markdown()` and all library-record generation from sync — new users never see library-records
+- Unconditional workspace creation — new papers get workspace directories on first sync (no flat fallback)
+- Fulltext bridge from OCR output to workspace; discussion.py reads from canonical index
+- Base views restored to workflow-gate filters (has_pdf/do_ocr/analyze/ocr_status → do_ocr=true, analyze=true+ocr_status=done) pointing to Literature/
+- Version badge fixed to read paperforge_version from canonical index envelope
+- Doctor detects stale library-records directory and workspace integrity issues
+
+---
+
+## v1.7 Context-Aware Dashboard (Shipped: 2026-05-04)
+
+**Phases completed:** 4 phases, 6 plans, 14 tasks
+
+**Key accomplishments:**
+
+- Pure CSS dashboard components for the PaperForge plugin -- loading skeleton, metric card, lifecycle stepper, health matrix, maturity gauge, and bar chart -- all themed via Obsidian CSS variables
+- 5 new DOM render methods on PaperForgeStatusView: loading skeleton utilities, enhanced metric cards, 6-stage lifecycle stepper, 2x2 health matrix, 6-segment maturity gauge, and lifecycle-proportional bar chart -- all using createEl() DOM API with CSS classes from Plan 27-01
+- Index loading utilities (_loadIndex, _getCachedIndex, _findEntry, _filterByDomain) on PaperForgeStatusView + CSS Sections 13-14 for mode-aware dashboard content area and header context
+- Mode-aware dashboard routing with _detectAndSwitch, _switchMode, debounced event subscriptions, mode header rendering, and lifecycle cleanup in PaperForgeStatusView
+- Full per-paper dashboard rendering pipeline: lifecycle stepper, health matrix, maturity gauge, next-step recommendation card, contextual actions, and paper metadata header
+- Domain-level aggregated dashboard: metric cards (papers/fulltext-ready/deep-read), lifecycle bar chart, and health overview grid with healthy/unhealthy counts for PDF/OCR/Note/Asset dimensions
+
+---
+
+## v1.6 AI-Ready Literature Asset Foundation (Shipped: 2026-05-04)
+
+**Phases completed:** 6 phases, 15 plans, 40 tasks
+
+**Key accomplishments:**
+
+- schema_version marker, top-level-to-vault_config migration engine, and auto-trigger in sync command
+- Refactored Obsidian plugin to read path configuration from `paperforge.json` (vault_config block), eliminating the second runtime truth problem where plugin DEFAULT_SETTINGS had wrong defaults (System/Resources/Notes/Index_Cards/Base instead of Python's 99_System/03_Resources/Literature/LiteratureControl/05_Bases).
+- Setup wizard writes canonical vault_config-only paperforge.json with schema_version, doctor detects stale legacy config with migration guidance, and load_vault_config supports optional config source tracing for CONF-03 runtime inspection.
+- Extracted index generation from sync.py into asset_index.py with versioned envelope format, atomic writes (tempfile + os.replace + filelock), and 14 passing tests
+- Legacy bare-list auto-migration, incremental refresh by Zotero key, workspace path fields in every index entry, and --rebuild-index CLI flag for the canonical asset index
+- Wire incremental index refresh into OCR, deep-reading, and repair workers; document sync.py default convention; add integration tests
+- Four pure derivation functions (lifecycle, health, maturity, next-step) consuming canonical index entry dicts with full test coverage via TDD
+- All four compute functions from asset_state.py wired into _build_entry() — every canonical index entry now carries embedded lifecycle, health, maturity, and next_step fields derived from source artifacts
+- status --json reads lifecycle/health/maturity from canonical index; doctor shows Index Health section with per-dimension health counts and brownfield detection
+- Plugin dashboard reads formal-library.json directly via readFileSync instead of spawning Python CLI, with doctor and repair as one-click Quick Action buttons
+- Base views lifecycle column migration and repair source-first rebuild with build_index() call
+- Flat literature notes copied into per-paper workspace directories with ## 🔍 精读 extraction and ai/ directory creation, wired into run_index_refresh() for first-sync migration, with workspace-aware _build_entry() writing and backward-compatible flat fallback
+- paperforge context CLI command that reads the canonical index and outputs JSON context entries with provenance traces and AI readiness explanations
+- Plugin "Copy Context" and "Copy Collection Context" Quick Actions with zotero_key resolution from active note frontmatter, clipboard copy with JSON validation
+
+---
+
 **Project:** PaperForge Lite — Local Obsidian + Zotero literature workflow for medical researchers
 
 ---
@@ -201,3 +272,18 @@
 
 ---
 *Milestone v1.3 completed: 2026-04-24*
+
+---
+
+## v1.10 Dependency Cleanup (Shipped: 2026-05-07)
+
+**Phases completed:** 4 phases (42-45), 29 requirements
+
+**Key accomplishments:**
+
+- OCR/status workers read `do_ocr`/`analyze` from formal note frontmatter (same pattern as `get_analyze_queue()`) — core workflow unbroken for post-v1.9 papers
+- `load_control_actions()` rewritten to scan Literature/; `auto_analyze_after_ocr` writes to formal notes
+- Repair worker re-anchored: three-way divergence scan compares formal note frontmatter vs canonical index vs meta.json
+- 14 hardcoded old directory defaults (`99_System`, `03_Resources`, `05_Bases`) updated to clean names across asset_index/sync/repair/setup_wizard/validate_setup/.gitignore/CLI
+- 9 documentation files updated (AGENTS.md, 5 skill files, 3 docs) — zero remaining library-records references
+- 473 tests pass, 0 regressions

.planning/PROJECT.md

@@ -1,12 +1,94 @@
-# PaperForge Lite Release Hardening
+# PaperForge
 
 ## What This Is
 
-PaperForge Lite is a polished local Obsidian + Zotero literature workflow for medical researchers. It takes a new user from registration/configuration through Better BibTeX export, Obsidian Base queue control, PaddleOCR processing, formal literature note generation, and `/pf-deep` deep reading. The UX is smooth, code is clean, and failures are diagnosed clearly.
+PaperForge is a local-first Obsidian + Zotero literature asset manager. It turns Zotero exports, PDFs, OCR fulltext, figures, notes, and AI outputs into a structured, traceable, reusable research library. v1.9 consolidated the fragmented tracking layers (library-records + formal notes) into a single per-workspace structure with slim frontmatter and paper-meta.json for internal state. v1.10 fixed cross-cutting dependency drift. v1.11 resolved all v1.9 ripple effects (index paths, library-records cleanup, TUI removal, module hardening, repair blind spots).
 
-v1.4 focuses on eliminating accumulated technical debt (~1,610 lines of code duplication, ad-hoc logging) and smoothing the user-facing workflow friction points identified in a comprehensive codebase audit.
+## Current Milestone: v2.0 Testing Infrastructure — 6-Layer Quality Gates
 
-## Completed Milestone: v1.3 Path Normalization & Architecture Hardening
+**Goal:** Establish a multi-layer testing infrastructure that covers version consistency, Python units, CLI contracts, plugin-backend integration, temp vault E2E workflows, user journey contracts, and destructive scenarios — with CI matrix, golden datasets, and snapshot testing.
+
+**Target features:**
+- Level 0: Version/build consistency checking (check_version_sync.py)
+- Level 1: Python unit tests (config, BBT parser, PDF resolver, OCR state machine, etc.)
+- Level 2: CLI contract tests (--json schema stability)
+- Level 3: Plugin-backend integration tests (plugin runtime helpers)
+- Level 4: Temp vault E2E tests (automatic vault creation, mock OCR, full workflow)
+- Level 5: User journey tests (UX Contract doc + journey scripts)
+- Level 6: Destructive/abnormal scenario tests (chaos matrix)
+- Fixtures: Golden dataset (zotero/ JSON fixtures, PDF fixtures, expected snapshots)
+- CI: GitHub Actions matrix (win/mac/linux, py3.10-3.12, node 20)
+
+## Completed Milestone: v1.10 Dependency Cleanup
+
+**Status:** COMPLETE (2026-05-07)
+
+**Delivered:**
+- OCR/status/repair workers read workflow state from formal note frontmatter — no library-records dependency
+- 14 hardcoded old directory defaults updated to clean names
+- 9 documentation files updated for v1.9 structure
+- 473 tests pass, 0 regressions
+
+## Completed Milestone: v1.11 Merge Gate — v1.9 Ripple Remediation
+
+**Status:** COMPLETE (2026-05-07)
+**Archive:** `.planning/milestones/v1.11-ROADMAP.md`
+
+**Delivered:**
+- Index path resolution: 5 workspace fields use config-resolved `literature_dir` (not hardcoded `"Literature/"`); env var typo fixed; legacy config migration
+- Library-records deprecation cleanup: zero residual traces in production code, documentation, and user-facing labels
+- Textual TUI removal: broken TUI classes removed; `paperforge setup` prints headless redirect; 3 docs updated
+- Module hardening: discussion.py (file locking, markdown escaping, UTC timestamps), main.js (API key via env, createEl(), async I/O), asset_state.py (next_step ordering, null JSON outputs), repair.py (all 6 divergence types detected)
+- Repair blind spots: condition 4 divergence detection, --fix mode coverage, silent exception logging, dead code removal
+
+## Completed Milestone: v1.9 Frontmatter Rationalization & Library-Record Deprecation
+
+**Status:** COMPLETE (2026-05-07)
+**Archive:** `.planning/milestones/v1.9-ROADMAP.md`
+
+**Delivered:**
+- Slimmed formal note frontmatter (28 → 16 fields); per-workspace paper-meta.json for internal state
+- Library-record generation removed; sync no longer creates library-records
+- Unconditional workspace creation on first sync; flat-to-workspace migration with fulltext bridge
+- Base views restored to workflow-gate filters (has_pdf/do_ocr/analyze/ocr_status), pointing to Literature/
+- Version badge fixed; lifecycle keys aligned; doctor workspace integrity + stale library-records checks
+- 188 tests passing, 0 failures
+
+## In Progress: v1.8 AI Discussion & Deep-Reading Dashboard (paused)
+
+**Goal:** Capture AI-paper discussions into structured ai/ records and extend the per-paper dashboard with deep-reading content and AI interaction history.
+
+**Status:** Phases 31-35 partial — 2/6 phases complete. Paused to prioritize v1.9 structural foundation before surfacing more dashboard features.
+
+## Completed Milestone: v1.7 Context-Aware Dashboard
+
+**Status:** COMPLETE (2026-05-04)
+
+**Delivered:**
+- Pure CSS dashboard components (metric cards, lifecycle stepper, health matrix, maturity gauge, bar chart)
+- Mode-aware dashboard routing with auto-detect and debounced switching
+- Full per-paper dashboard: lifecycle stepper, health matrix, maturity gauge, next-step recommendations
+- Collection dashboard: domain-level metric cards, lifecycle bar chart, health grid aggregation
+- Global dashboard with enhanced library overview
+
+## Completed Milestone: v1.6 AI-Ready Literature Asset Foundation
+
+## Completed Milestone: v1.4 Code Health & UX Hardening
+
+**Status:** COMPLETE (2026-04-27)
+**Archive:** `.planning/milestones/v1.4.md`
+
+**Delivered:**
+- Structured logging module (`paperforge/logging_config.py`) with dual-output (stdout + stderr)
+- Shared utilities module (`paperforge/worker/_utils.py`) eliminating ~1,610 lines of duplication
+- Merged deep-reading queue implementations (3 → 1)
+- OCR retry/backoff/rate-limiting
+- Dead code elimination + pre-commit hooks (ruff)
+- `auto_analyze_after_ocr` workflow option
+- E2E integration tests + setup_wizard unit tests (317 passed, 2 skipped)
+- CONTRIBUTING.md, CHANGELOG.md
+
+### v1.3 Path Normalization & Architecture Hardening
 
 **Status:** COMPLETE (2026-04-24)
 **Archive:** `.planning/milestones/v1.3.md`
@@ -22,31 +104,22 @@ v1.4 focuses on eliminating accumulated technical debt (~1,610 lines of code dup
 
 ---
 
-## Current Milestone: v1.4 Code Health & UX Hardening
+## Completed Milestone: v1.5 Obsidian Plugin Setup Integration
 
-**Goal:** Eliminate all code duplication, add formal observability, and streamline the end-to-end user workflow.
+**Status:** COMPLETE (2026-04-29)
 
-**Target features (User-facing):**
-- Simplify OCR → deep-reading workflow (reduce manual frontmatter-editing steps)
-- Add progress indicators for long-running operations (large-file OCR)
-- Improve error visibility on OCR failure (structured log output)
-- Unify Agent/CLI naming mental model (audit `/pf-*` vs `paperforge *` boundaries)
-- Fix README rendering artifacts (legacy code snippet on line 102)
-
-**Target features (Maintainer-facing):**
-- Extract `worker/_utils.py` shared module (eliminate ~1,610 lines of duplicated code)
-- Replace `print()` with level-based structured `logging` module
-- Merge duplicate deep-reading queue scanning implementations
-- Add retry/backoff/rate-limiting for OCR worker
-- Clean up dead code and unused imports across all 7 workers
-- Add pre-commit hook with consistency audit
-- Add `CONTRIBUTING.md`, `CHANGELOG.md`
-- Add E2E integration tests + setup_wizard tests
-- Cross-reference chart-reading guides in agent prompt
+**Delivered:**
+- Plugin settings tab exposing all setup_wizard.py fields (vault path, system/resource/lit/ctrl/agent dirs, PaddleOCR API token, Zotero junction) — Phase 20
+- Settings fields persist via Obsidian `loadData/saveData` API with debounced 500ms save — Phase 20
+- One-click "Install" button running full setup via `python -m paperforge setup --headless` with explicit args — Phase 21
+- Client-side field validation with Chinese error messages before subprocess spawn — Phase 21
+- Subprocess orchestration with button disable/enable lifecycle, stdout step-parsing, and color-coded status area — Phase 21
+- Friendly Chinese error mapping (5 patterns) — no raw traceback exposure — Phase 21
+- Existing sidebar and command palette completely untouched — strictly additive
 
 ## Core Value
 
-A new user can install PaperForge, configure their own vault paths and PaddleOCR credentials, then run the full literature pipeline with copy-pasteable commands that diagnose failures clearly.
+Researchers always know what papers they have, what state those papers are in, and whether each paper is reliably usable by AI with traceable fulltext, figures, notes, and source links.
 
 ## Requirements
 
@@ -74,14 +147,83 @@ A new user can install PaperForge, configure their own vault paths and PaddleOCR
 - ✓ Pipeline module boundary cleanup (`pipeline/` → `paperforge/worker/` as 7 modules) — Phase 12
 - ✓ Skill scripts integration (`skills/` → `paperforge/skills/`) — Phase 12
 - ✓ Test dead zone elimination (203 passed, 0 failed) — Phase 12
-- [ ] Consistency audit CI integration (pre-commit / GitHub Action) — deferred to future
+
+### v1.4 Completed (2026-04-27)
+
+- ✓ Structured logging (`paperforge/logging_config.py`, `PAPERFORGE_LOG_LEVEL`) — Phase 13
+- ✓ Shared utilities extraction (`_utils.py`, ~1,610 lines deduplicated) — Phase 14
+- ✓ Deep-reading queue merge (3 implementations → 1) — Phase 15
+- ✓ OCR retry/backoff/rate-limiting + progress bar — Phase 16
+- ✓ Dead code elimination + pre-commit hooks (ruff) — Phase 17
+- ✓ CONTRIBUTING.md, CHANGELOG.md — Phase 18
+- ✓ E2E integration tests + setup_wizard tests (317 passed, 2 skipped) — Phase 19
+- ✓ `auto_analyze_after_ocr` workflow option — Phase 18
+- [ ] Consistency audit CI integration (GitHub Action) — deferred to future
+
+### Validated (v1.5)
+
+- ✓ **SETUP-01**: Plugin settings tab renders all setup_wizard.py fields (vault path, system/resource/lit/ctrl/agent dirs, PaddleOCR API token, Zotero junction) — Phase 20
+- ✓ **SETUP-02**: Settings fields persist to plugin data (Obsidian `settings` API), survive reload — Phase 20
+- ✓ **SETUP-03**: One-click "Install" button triggers full setup pipeline — write paperforge.json, create directories, env check, agent configs — Phase 21
+- ✓ **SETUP-04**: Each setup step produces polished, human-readable output via Obsidian notices/UI (never raw terminal text) — Phase 21
+- ✓ **SETUP-05**: Install button validates all fields before execution, shows specific field-level errors in friendly language — Phase 21
+- ✓ **SETUP-06**: Existing sidebar and command palette actions continue working unchanged alongside new settings tab — Phase 21
+
+### Validated (v1.11)
+
+- ✓ **REMED-01**: Index workspace path fields use config-resolved literature_dir (not hardcoded "Literature/")
+- ✓ **REMED-02**: All library-records residual traces removed — dead code, stale docstrings, wrong scan dirs, misleading labels
+- ✓ **REMED-03**: Setup wizard TUI removed; headless-only redirect with clean message
+- ✓ **REMED-04**: Discussion recorder hardened: file locking, markdown escaping, UTC timezone, QA key validation
+- ✓ **REMED-05**: Plugin hardened: API key via env not CLI args, innerHTML replaced with createEl, sync I/O→async
+- ✓ **REMED-06**: Asset state/repair logic fixed: next_step ordering, null JSON outputs, repair divergence blind spots
+- ✓ **REMED-07**: 5 command files updated to reflect v1.9 workflow (no library-records references)
+
+### Validated (v1.10)
+
+- ✓ OCR worker reads `do_ocr` from formal note frontmatter (same `get_analyze_queue()` logic as analyze), not from deprecated library-records.
+- ✓ Status worker reads `do_ocr`/path counts from formal notes + canonical index, not from library-records.
+- ✓ Repair worker three-way divergence scan and path error detection re-anchored to formal notes + canonical index.
+- ✓ `load_control_actions()` rewritten to scan formal note frontmatter; orphan cleanup targets Literature/.
+- ✓ 14 hardcoded old defaults (`99_System`/`03_Resources`/`05_Bases`) updated in production code to match `DEFAULT_CONFIG`.
+- ✓ 5 skill files (pf-sync/pf-ocr/pf-status/pf-paper/pf-deep) updated to reflect library-records deprecation.
+- ✓ AGENTS.md, docs/setup-guide.md, docs/ARCHITECTURE.md, docs/COMMANDS.md updated.
+- ✓ setup_wizard function signatures and cli.py help text updated to clean directory names.
+- ✓ `.gitignore` patterns updated for new clean directory defaults.
+- ✓ All tests pass after changes (473 passed, 0 regressions).
+
+### Validated (v1.9)
+
+- ✓ Library-records directory eliminated: sync no longer creates `<control_dir>/library-records/`; new users never see it.
+- ✓ Upgrading users get lossless library-record → formal note frontmatter migration on first sync (via `_build_entry()` defaults + paper_meta.py).
+- ✓ Base views fixed: removed ghost lifecycle/maturity_level/next_step; restored has_pdf/do_ocr/analyze/ocr_status; folder filter points to Literature/.
+- ✓ Formal note frontmatter slimmed to identity fields + workflow flags + pdf_path; redundant fields removed.
+- ✓ Per-workspace paper-meta.json stores OCR backend data, derived state details, and debug fields.
+- ✓ Workspace folder construction: new papers create workspace on first sync (no flat-first-then-migrate); fulltext.md bridged from OCR output.
+- ✓ Path construction unified: discussion.py reads workspace paths from canonical index instead of reconstructing independently.
+- ✓ Plugin dashboard: version badge reads paperforge_version from index envelope; lifecycle keys aligned; CSS components verified.
+
+### Validated (v1.8)
+
+- ✓ AI discussion recorder: `/pf-paper` and agent chats produce `discussion.md` + `discussion.json` in workspace `ai/`.
+- ✓ Deep-reading dashboard mode with status bar, Pass 1 summary, and AI Q&A history.
+- ✓ "Jump to Deep Reading" button on per-paper dashboard card.
+- ✓ Bug fix: removed meaningless "ai" row from plugin UI.
+- ✓ Bug fix: restored version number display in plugin.
 
 ### Out of Scope
 
 - Replacing Zotero or Better BibTeX — the project is built around them.
 - Automatically triggering deep-reading agents from workers — the Lite architecture intentionally keeps worker automation and agent reasoning separate.
 - Cloud-hosted multi-user service — this project targets local single-user vault workflows.
-- Full OCR provider abstraction in v1.2 — deferred to v1.3+ (PaddleOCR path/env consistency was the v1.2 priority).
+- Full OCR provider abstraction — deferred (PaddleOCR path/env consistency is the priority).
+- Discipline-specific extraction products (PICO tables, mechanism tables, parameter tables) as core built-ins — PaperForge should provide a framework, not hardcoded scholarly schemas.
+- Replacing Zotero, Better BibTeX, or Obsidian Bases — the system is built around those primitives.
+- Automatically turning every prompt into a fixed UI button — prompt-specific workflows stay optional templates, not core product logic.
+- Cloud multi-user collaboration or hosted sync — this milestone remains local-first and single-user.
+- Plugin auto-update — deferred to when listed on Obsidian Community Plugins.
+- Plugin published to Obsidian Community Plugins — deferred until after v1.5 stabilizes the settings experience.
+- v1.8 dashboard features (deep-reading mode, Jump to Deep Reading, AI discussion recorder) — paused, not cancelled; will resume after v1.9 cleans the structural foundation.
 
 ## Context
 
@@ -110,7 +252,27 @@ The v1.1 milestone was completed after a manual sandbox audit from `tests/sandbo
 
 **v1.3 focus:** Fix real-world Zotero path handling (absolute Windows paths in BBT JSON → Vault-relative wikilinks), clean up module architecture (`pipeline/` and `skills/` integration), eliminate test dead zones, establish CI-ready consistency audit.
 
-**v1.4 focus:** A comprehensive codebase audit (2026-04-25) revealed 1,610 lines of duplicated code across 7 worker modules, ad-hoc `print()`-based logging, duplicate deep-reading queue implementations, and user-facing UX friction. v1.4 will extract a shared utilities module, add structured logging, merge duplicate implementations, add pre-commit hooks, and streamline the OCR→deep-reading workflow.
+**v1.4 shipped (2026-04-27):**
+- Structured logging with `PAPERFORGE_LOG_LEVEL` env var
+- `_utils.py` shared module (read_json, write_json, yaml operations, slugify, journal_db)
+- Single deep-reading queue implementation
+- OCR retry/backoff/rate-limiting with progress bar
+- Pre-commit hooks (ruff check --fix + ruff format)
+- CONTRIBUTING.md, CHANGELOG.md
+- 317 tests passing, 2 skipped, 0 failures
+
+**v1.5 shipped (2026-04-29):** Settings tab with all 8 wizard fields, debounced persistence, one-click "安装配置" button, client-side field validation with Chinese errors, subprocess orchestration via `python -m paperforge setup --headless`, step-by-step Chinese progress notices, and color-coded status area. Plugin becomes single download artifact — no terminal required for new user setup.
+
+**v1.6 focus:** Consolidate the next layer of product evolution into one milestone instead of splitting it across several small releases. The emphasis is not on more one-off extraction buttons, but on durable asset state, asset health, maturity-guided workflow progression, and AI-ready context packaging.
+
+**v1.9 focus:** The feature branch (milestone/v1.6-ai-ready-asset-foundation) accumulated 117 commits of v1.6-v1.8 work. Before merging to master, structural cleanup is needed: library-records (a v1.0 tracking layer) must be deprecated in favor of formal note frontmatter; Base views regressed in v1.7 (lost workflow flags, gained unwritten ghost fields); frontmatter grew to 47 unique fields across two note types. This milestone fixes the foundation so incremental PRs can land cleanly on master.
+
+Key gaps identified on feature branch:
+- Base views declare lifecycle/maturity_level/next_step but NO .md writer exists for these fields — columns permanently empty
+- Base views lost has_pdf/do_ocr/analyze/ocr_status — users cannot batch-toggle workflow from Obsidian
+- _build_entry() declares fulltext_path in workspace but no code copies OCR output there — broken link
+- New papers go flat-first-then-migrate — should create workspace directly
+- discussion.py builds ai/ path independently instead of reading from canonical index
 
 ## Constraints
 
@@ -121,6 +283,8 @@ The v1.1 milestone was completed after a manual sandbox audit from `tests/sandbo
 - **Credential safety:** API keys belong in `.env` or user environment variables and must not be committed.
 - **Agent independence:** Users should not need an agent to inspect `paperforge.json` just to build a worker command.
 - **Sandbox realism:** `tests/sandbox` must remain safe, deterministic, and representative of a GitHub user trying the project locally.
+- **Thin-shell plugin:** Obsidian plugin UI must not become a second implementation of lifecycle or health logic already owned by Python workers.
+- **Traceability:** AI-facing outputs must remain traceable back to original PDFs, OCR outputs, and notes.
 
 ## Key Decisions
 
@@ -136,7 +300,33 @@ The v1.1 milestone was completed after a manual sandbox audit from `tests/sandbo
 | Aggressive migration (no aliases) | Clean break reduces maintenance burden; migration guide handles transition | ✓ Implemented v1.2 |
 | Command modules in `paperforge/commands/` | Shared logic between CLI and Agent layers reduces duplication | ✓ Implemented v1.2 |
 | Package rename to `paperforge` | Naming consistency with CLI brand | ✓ Implemented v1.2 |
-| Extract shared worker utilities to `_utils.py` | ~1,610 lines of duplicate utility code exist across 7 worker modules; single source of truth reduces maintenance burden | — Pending |
+| Extract shared worker utilities to `_utils.py` | ~1,610 lines of duplicate utility code exist across 7 worker modules; single source of truth reduces maintenance burden | ✓ Implemented v1.4 |
+| Settings tab in Obsidian plugin as setup entry point | Eliminates terminal requirement for new users; plugin becomes single download artifact. CLI/Agent unchanged — plugin is a new UI surface | ✓ Implemented v1.5 |
+| Reposition PaperForge around literature assets, not one-off prompts | Long-term user value comes from clean, traceable, AI-ready libraries rather than hardcoded extraction buttons | — Active for v1.6 |
+| Keep plugin as thin shell over CLI and canonical index | Avoids duplicated business logic and configuration drift between JS and Python layers | — Active for v1.6 |
+| Deprecate library-records in favor of formal notes | Two tracking layers (library-records + formal notes) create divergence, double the frontmatter surface, and confuse users. Formal notes already carry most metadata; adding workflow flags makes them self-sufficient. | ✓ Integrated |
+| Separate Base views (workflow batch ops) from Dashboard (derived state viz) | lifecycle/maturity/next_step already have rich visualization in the Obsidian plugin dashboard; duplicating them in Base views as empty columns adds noise. Base views focus on user-actionable workflow gates. | ✓ Implemented |
+| Per-workspace paper-meta.json for internal state | Frontmatter is the user-facing surface; internal pipeline data (OCR jobs, health details, debug fields) belongs in a machine-readable JSON file. Keeps formal notes clean while preserving all state for tools. | ✓ Implemented |
+| Unconditional workspace creation on first sync | Flat-note fallback created confusion and required separate migration step. Always creating workspace dirs simplifies the architecture and eliminates the flat-first-then-migrate path. | ✓ Implemented |
+
+## Research Lock
+
+Research has been frozen at milestone boundaries to avoid redundant re-research.  
+
+**v1.6 (Literature Asset Foundation)** — product direction and architecture are settled:
+- Asset lifecycle, canonical index, thin-shell plugin, paper workspace direction, ai/ in workspace, Python-owned health/maturity rules.  
+- No re-research needed unless architecture or product direction changes materially.  
+
+**v1.7 (LLMWiki Concept Network)** — direction settled:
+- Cross-paper synthesis layer, concept/mechanism network, source-traceable, human-reviewable.  
+- No re-research on "whether to build a wiki" or "first use case."  
+
+**v1.9 (Frontmatter Rationalization)** — no new research needed:
+- All pieces already exist on the feature branch: workspace migration, derived state, canonical index, Base generation, frontmatter writing.
+- This milestone is structural cleanup — rewire, remove, and fix existing code, not invent new capabilities.
+- Skip research for this milestone.
+
+See: `.planning/research/MILESTONE-RESEARCH-LOCK.md` for the full lock definition.
 
 ## Evolution
 
@@ -155,4 +345,5 @@ This document evolves at phase transitions and milestone boundaries.
 3. Audit Out of Scope.
 4. Update Context with current state.
 
----\n*Last updated: 2026-04-25 — Milestone v1.4 started (code health & UX hardening)*
+---
+*Last updated: 2026-05-08 after milestone v2.0 initiation*

.planning/REQUIREMENTS.md

@@ -1,155 +1,139 @@
-# Requirements: PaperForge Lite
+# Requirements: PaperForge v2.0
 
-> **Defined:** 2026-04-25
-> **Core Value:** A new user can install PaperForge, configure their own vault paths and PaddleOCR credentials, then run the full literature pipeline with copy-pasteable commands that diagnose failures clearly.
+**Defined:** 2026-05-08
+**Core Value:** Researchers always know what papers they have, what state those papers are in, and whether each paper is reliably usable by AI with traceable fulltext, figures, notes, and source links.
 
----
+## v1 Requirements
 
-## v1.3 Requirements (Validated)
+Requirements for this release. Each maps to roadmap phases.
 
-All 19 v1.3 requirements shipped and validated. See `.planning/milestones/v1.3.md` and `MILESTONES.md` for completion details.
+### Version Consistency (VC)
 
----
+- [ ] **VC-01**: Version sync checker script validates Python `__version__`, plugin manifest.json, versions.json, CHANGELOG — all 6+ declarations are consistent before any test runs
+- [ ] **VC-02**: CI version gate runs version check on every push
 
-## v1.4 Requirements
+### Python Unit Tests (UNIT)
 
-### Code Health (CH)
+- [ ] **UNIT-01**: Config tests cover reading, env var override, defaults, legacy migration, all path fields
+- [ ] **UNIT-02**: BBT parser tests cover all JSON variants — valid, empty, malformed, missing citationKey, missing title, missing DOI, empty attachments, storage: paths, absolute Windows paths, bare relative paths, CJK content, multiple PDFs, zero PDFs
+- [ ] **UNIT-03**: PDF resolver tests cover Zotero data dir unset/wrong, storage path missing, CJK filenames, filenames with parentheses, OneDrive paths, moved PDFs, multi-attachment main/supplementary identification
+- [ ] **UNIT-04**: OCR state machine tests cover pending → processing → done → failed transitions, retry/backoff, progress, auto_analyze_after_ocr, error recovery
+- [ ] **UNIT-05**: Note generation tests cover frontmatter field correctness, template rendering, field migration, CJK-safe output
+- [ ] **UNIT-06**: Base generation tests cover .base file structure, workflow-gate filters, config-aware paths, CJK-safe output
+- [ ] **UNIT-07**: Index generation tests cover canonical index format, versioned envelope, atomic writes, incremental refresh, rebuild
+- [ ] **UNIT-08**: Template checker tests cover asset state derivation (lifecycle/health/maturity/next_step), edge cases, null/incomplete inputs
 
-**Goal:** Eliminate all code duplication and dead code across the 7 worker modules.
+### CLI Contract Tests (CLI)
 
-- [ ] **CH-01**: Create `paperforge/worker/_utils.py` as a pure leaf module (zero imports from sibling workers) containing all duplicated utility functions: `read_json`, `write_json`, `read_jsonl`, `write_jsonl`, `yaml_quote`, `yaml_block`, `yaml_list`, `slugify_filename`, `_extract_year`, `load_journal_db`, `lookup_impact_factor`, `_STANDARD_VIEW_NAMES`, and the `_JOURNAL_DB` cache.
-- [ ] **CH-02**: Update all 7 worker modules (`sync.py`, `ocr.py`, `deep_reading.py`, `repair.py`, `status.py`, `update.py`, `base_views.py`) to import shared functions from `paperforge.worker._utils` instead of defining local copies. Approximately 1,610 lines of duplication removed.
-- [x] **CH-03**: Merge the two duplicate deep-reading queue scanning implementations — consolidate `worker/deep_reading.py::run_deep_reading()` (scanner logic) and `skills/ld_deep.py::scan_deep_reading_queue()` into a single `scan_library_records()` function in `_utils.py`. Both original call sites import the shared function with no behavioral change.
-- [ ] **CH-04**: Remove dead code: (a) `UPDATE_*` constants from `status.py` lines 620-625 (duplicated in `update.py`), (b) unused imports from each worker module (`csv`, `hashlib`, `shutil`, `subprocess`, `zipfile`, `ElementTree`, `fitz`, `PIL` where not used), (c) unnecessary delegation wrappers (`load_vault_config` / `pipeline_paths`) that merely call `paperforge.config` equivalents — direct `config.*` imports replace these.
-- [ ] **CH-05**: All 205 existing tests continue to pass after shared utility extraction. No regression in CLI dispatch, OCR state machine, path normalization, repair, or base view generation.
+- [ ] **CLI-01**: All 7 CLI commands (status, sync, ocr, doctor, repair, context, setup) return stable `--json` schema
+- [ ] **CLI-02**: Error responses use standard JSON format with `ok`, `error_code`, `message`, `details`, `suggestions` fields
+- [ ] **CLI-03**: pytest-snapshot integration with shape-specific assertions (not whole-file) for CLI output contracts
 
-### Observability (OBS)
+### Plugin-Backend Integration (PLUG)
 
-**Goal:** Replace ad-hoc `print()` calls with a structured, configurable logging system.
+- [ ] **PLUG-01**: Plugin runtime helpers testable via Vitest — resolvePythonExecutable, getPluginVersion, checkRuntimeVersion
+- [ ] **PLUG-02**: Error classification covers all error patterns (Python missing, import failed, version mismatch, pip install failure, timeout)
+- [ ] **PLUG-03**: Command dispatch tests cover buildRuntimeInstallCommand, parseRuntimeStatus, subprocess orchestration
 
-- [x] **OBS-01**: Create `paperforge/logging_config.py` that configures a `logging.Logger` hierarchy using stdlib `logging`. Log level controllable via `PAPERFORGE_LOG_LEVEL` environment variable (accepts `DEBUG`/`INFO`/`WARNING`/`ERROR` string names). All workers and CLI commands use `logger = logging.getLogger(__name__)`.
-- [x] **OBS-02**: Implement dual-output strategy: `print()` preserved for user-facing formatted output on stdout; `logging` used for diagnostic/trace/error output to stderr. Existing piped commands and Agent scripts that parse stdout continue to work unmodified.
-- [x] **OBS-03**: Add `--verbose`/`-v` flag to `paperforge sync`, `paperforge ocr`, and `paperforge deep-reading` that enables `DEBUG` log level. All existing commands accept the flag.
-- [ ] **OBS-04**: Add `tqdm`-based progress bars to OCR upload (per-PDF) and batch polling loops. Progress output goes to stderr. Auto-detects non-TTY mode (CI, pipe) — silently falls back to no progress output when stdout is not an interactive terminal. A `--no-progress` flag suppresses output explicitly.
-- [ ] **OBS-05**: Make OCR error messages actionable: on failure/timeout/blocked, the error includes the specific HTTP status code or exception type, the library-record name for context, and a suggestion (e.g., "Run `paperforge ocr --diagnose` to test API connectivity" or "Run `paperforge repair --fix` to recover state"). Error pattern follows `ocr_diagnostics.classify_error()` format.
+### Temp Vault E2E (E2E)
 
-### Reliability (REL)
+- [ ] **E2E-01**: Temp vault creation fixture produces disposable Vault with config, directories, mock Zotero data
+- [ ] **E2E-02**: Full sync workflow test — BBT JSON → formal notes → canonical index → Base views
+- [ ] **E2E-03**: Full OCR workflow with mock PaddleOCR backend via HTTP interception (responses library)
+- [ ] **E2E-04**: status/doctor/repair commands run correctly in temp vault with known state
+- [ ] **E2E-05**: Multi-domain sync test verifies multiple collections sync correctly and independently
 
-**Goal:** Make the OCR pipeline resilient to transient network failures.
+### User Journey Tests (JNY)
 
-- [ ] **REL-01**: Add `tenacity`-based retry decorator to PaddleOCR API calls (upload and poll functions) with exponential backoff (1s → 2s → 4s → 8s → max 30s), jitter, and selective exception retry (`requests.ConnectionError`, `requests.Timeout`, `HTTPError` with status 429/503). Configurable via `PAPERFORGE_RETRY_MAX` and `PAPERFORGE_RETRY_BACKOFF` environment variables.
-- [ ] **REL-02**: Extend OCR `meta.json` schema with `retry_count` (int, default 0), `last_error` (str | null), `last_attempt_at` (ISO-8601 str | null). These fields are written atomically after each attempt and read during polling to inform retry decisions.
-- [ ] **REL-03**: Prevent zombie OCR state: on worker restart, all `processing` jobs older than configurable threshold (default: 30 minutes) are reset to `pending` with `retry_count` incremented. Blocked jobs (`blocked` terminal state) are never retried unless user manually resets `do_ocr`.
-- [ ] **REL-04**: The `paperforge ocr` command gracefully handles partial failures: a single upload failure does not abort the entire batch. Failed items are logged, their state updated, and processing continues with remaining items.
+- [x] **JNY-01**: UX Contract document (docs/ux-contract.md) with verifiable rules for installation, sync, OCR, and dashboard
+- [x] **JNY-02**: New user onboarding journey test — install → sync → OCR → analyze → deep-read
+- [x] **JNY-03**: Daily workflow journey test — existing user adds paper, syncs, OCRs, reads
 
-### Developer Experience (DX)
+### Chaos / Destructive Tests (CHAOS)
 
-**Goal:** Establish standard open-source project infrastructure for maintainers and contributors.
+- [x] **CHAOS-01**: Corrupted input tests — malformed JSON, corrupt PDF, broken meta.json, missing frontmatter fields
+- [x] **CHAOS-02**: Network failure tests — OCR API timeout, HTTP 401, 500, DNS unreachable
+- [x] **CHAOS-03**: Filesystem error tests — permission denied, locked files, missing directories, path too long
+- [x] **CHAOS-04**: CHAOS_MATRIX.md documents all destructive scenarios with triggers, expected behavior, and safety contracts
 
-- [ ] **DX-01**: Create `.pre-commit-config.yaml` with hooks: `ruff` (lint + format), `check-yaml`, `check-toml`, `end-of-file-fixer`, `trailing-whitespace`, and a custom `consistency-audit` hook that runs `scripts/consistency_audit.py` and blocks commits if duplicate utility functions are detected in any worker module.
-- [ ] **DX-02**: Add `[tool.ruff]` section to `pyproject.toml` targeting Python 3.10+, enabling rules `E`, `F`, `I`, `UP`, `B`, `SIM`. Run `ruff check --fix` and `ruff format` across the entire codebase as part of the pre-commit activation phase.
-- [x] **DX-03**: Create `CHANGELOG.md` following the Keep a Changelog format with sections for each version (v1.0 through v1.4). Include the changelog URL in `paperforge.json` update metadata.
-- [x] **DX-04**: Create `CONTRIBUTING.md` documenting: development setup (`pip install -e ".[test]"`), pre-commit hook installation, test execution workflow, architecture overview, and code conventions (no new print() calls, import shared utilities from `_utils.py`, REQ-ID linking in commit messages).
+### Fixtures / Golden Datasets (FIX)
 
-### Testing (TEST)
+- [ ] **FIX-01**: Zotero JSON fixtures — 8+ variants covering valid, empty, malformed, missing keys, CJK content, multi-attachment, absolute/storage/bare paths
+- [ ] **FIX-02**: PDF fixture samples — minimal valid PDFs including CJK filenames and special characters
+- [ ] **FIX-03**: Mock OCR response fixtures — realistic PaddleOCR API responses for submit, poll, result, error, timeout
+- [ ] **FIX-04**: Expected output snapshots — formal note, Base file, canonical index expected outputs for golden dataset inputs
+- [ ] **FIX-05**: MANIFEST.json tracks all fixtures with `used_by`, `generated`, `desc` metadata
 
-**Goal:** Close testing gaps identified in the codebase audit.
+### CI Infrastructure (CI)
 
-- [ ] **TEST-01**: Add E2E integration tests in `tests/test_e2e_pipeline.py` covering the full Zotero JSON → selection-sync → index-refresh → OCR queue → formal notes pipeline using the sandbox fixture vault. Tests validate frontmatter completeness, wikilink correctness, and state transitions.
-- [ ] **TEST-02**: Add setup wizard tests in `tests/test_setup_wizard.py` validating: agent platform detection, vault path resolution, environment checks, and configuration file generation. Tests use the Textual testing harness if available or validate standalone functions independently.
-- [ ] **TEST-03**: All existing 205 tests continue to pass with zero failures. No test regression from shared utility extraction, logging changes, or dead code removal. Minimum bar: 205+ tests passing, 0 failures, 0 errors.
-- [ ] **TEST-04**: Add dedicated unit tests for `paperforge/worker/_utils.py` functions: `test_utils_json.py` (read/write JSON + JSONL), `test_utils_yaml.py` (yaml_quote/yaml_block/yaml_list), `test_utils_slugify.py` (slugify_filename, _extract_year), `test_utils_journal.py` (load_journal_db, lookup_impact_factor).
-
-### User Experience (UX)
-
-**Goal:** Smooth user-facing friction points identified in the codebase audit.
-
-- [x] **UX-01**: Add workflow streamlining options to `paperforge.json`: `auto_analyze_after_ocr` (bool, default `false`) — when enabled, after OCR completes for a paper, the library-record's `analyze` flag is automatically set to `true`. This is opt-in to preserve the two-layer Worker/Agent separation and user agency.
-- [x] **UX-02**: Fix README.md rendering artifact: remove the orphaned legacy code snippet lines (`python <resolved_worker_script> --vault . ocr`, `python <resolved_worker_script> --vault . status`) at lines 102-104 that appear outside any code fence. Audit all user-facing docs (AGENTS.md, docs/*.md, command/*.md) for similar rendering issues.
-- [x] **UX-03**: Generate a chart-reading guide cross-reference index (`chart-reading/INDEX.md`) that maps the 19 chart types to their reading guides, ordered by commonness in biomedical literature. The agent prompt (`prompt_deep_subagent.md`) references this index so AI agents can discover and cite relevant guides during Pass 2 figure-by-figure analysis.
-- [x] **UX-04**: Audit the command naming boundary: ensure all user-facing documentation consistently maps `/pf-*` Agent commands to `paperforge *` CLI commands. Add a quick-reference table showing "What to type where" in AGENTS.md section 1.
-
-### Documentation (DOCS)
-
-**Goal:** Document the v1.4 changes for existing users and future maintainers.
-
-- [x] **DOCS-01**: Create `docs/MIGRATION-v1.4.md` following the established v1.2 migration document pattern. Document behavioral changes (dual-output logging, retry behavior, opt-in workflow streamlining), environment variable additions (`PAPERFORGE_LOG_LEVEL`, `PAPERFORGE_RETRY_MAX`, `PAPERFORGE_RETRY_BACKOFF`), and new developer workflow requirements (pre-commit hooks, ruff).
-- [x] **DOCS-02**: Update `AGENTS.md` to reflect: new `--verbose` flag on CLI commands, new `paperforge.json` workflow options, new environment variables page, and the chart-reading INDEX.md cross-reference.
-- [x] **DOCS-03**: Add ADR-012 (Shared Utilities Extraction) and ADR-013 (Dual-Output Logging Strategy) to `docs/ARCHITECTURE.md`, documenting the `_utils.py` leaf-module constraint and the print/logging boundary decision.
-- [x] **DOCS-04**: Update `ROADMAP.md` to reflect v1.4 phase structure and mark all requirements as mapped after roadmap creation.
-
----
-
-## v1.5 Requirements (Deferred)
-
-Deferred from v1.4 scope to keep the milestone focused and manageable.
-
-### Workflow
-
-- **WF-01**: One-click `paperforge process` command — triggers sync + OCR + auto-analyze in a single command. Deferred: requires research on optimal default behavior vs opt-out model.
-- **WF-02**: Obsidian Base bulk-action integration — inline "Run OCR" / "Start Deep Reading" buttons in Base views. Deferred: requires Obsidian plugin architecture research.
-
-### Testing
-
-- **TEST-V2-01**: Performance benchmarks for OCR processing (large PDF timing). Deferred: need baseline measurements first.
-- **TEST-V2-02**: Cross-platform CI (Windows + macOS + Linux) via GitHub Actions. Deferred: pre-commit hooks are the priority for v1.4.
-
----
+- [ ] **CI-01**: PR check workflow (ci-pr-checks.yml) — L0 + L1 on push, <2 minute target
+- [ ] **CI-02**: Full CI gate (ci.yml) — L0 through L4 on merge to main
+- [ ] **CI-03**: Plasma matrix — 3 OS (win/mac/linux) × 3 Python (3.10/3.11/3.12) for L1; narrower for higher layers
+- [ ] **CI-04**: Node 20 CI runner for plugin Vitest tests
+- [x] **CI-05**: Scheduled chaos workflow (ci-chaos.yml) — L6 weekly + manual trigger
 
 ## Out of Scope
 
+Explicitly excluded. Documented to prevent scope creep.
+
 | Feature | Reason |
 |---------|--------|
-| Auto-triggering deep-reading from workers | Lite architecture keeps Worker and Agent layers separate (ADR-002) |
-| Cloud-hosted multi-user service | Local-first scope |
-| Replacing Zotero or Better BibTeX | Core dependency |
-| OCR provider abstraction (beyond PaddleOCR) | Requires API research, deferred to v1.5+ |
-| TypeScript Obsidian plugin architecture | Major new stack, needs dedicated milestone |
-| Real-time Zotero sync (daemon) | Conflicts with Lite two-layer design |
-
----
+| Real Obsidian E2E in CI | Requires running Obsidian process; 3+ min per test, flaky. Use obsidian-test-mocks for unit tests |
+| Load/performance testing | PaperForge is a local single-user tool; no performance requirements |
+| Cross-browser testing | Plugin runs inside Obsidian's Electron (Chromium only) — not applicable |
+| Full parallel 3×3×6 matrix | 54 CI jobs per PR for minimal added confidence. Plasma matrix is sufficient |
+| Automated visual regression | Screenshot-based plugin UI tests are fragile and high-maintenance |
+| Coverage percentage gates | Would incentivize superficial testing. Use targeted coverage instead |
+| Property-based testing (Hypothesis) | High complexity, low value for this project's domain |
 
 ## Traceability
 
 | Requirement | Phase | Status |
 |-------------|-------|--------|
-| CH-01 | Phase 14 | Pending |
-| CH-02 | Phase 14 | Pending |
-| CH-03 | Phase 15 | Complete |
-| CH-04 | Phase 17 | Pending |
-| CH-05 | Phase 14 | Pending |
-| OBS-01 | Phase 13 | Complete |
-| OBS-02 | Phase 13 | Complete |
-| OBS-03 | Phase 13 | Complete |
-| OBS-04 | Phase 16 | Pending |
-| OBS-05 | Phase 17 | Pending |
-| REL-01 | Phase 16 | Pending |
-| REL-02 | Phase 16 | Pending |
-| REL-03 | Phase 16 | Pending |
-| REL-04 | Phase 16 | Pending |
-| DX-01 | Phase 17 | Pending |
-| DX-02 | Phase 17 | Pending |
-| DX-03 | Phase 18 | Complete |
-| DX-04 | Phase 18 | Complete |
-| TEST-01 | Phase 19 | Pending |
-| TEST-02 | Phase 19 | Pending |
-| TEST-03 | Phase 14 | Pending |
-| TEST-04 | Phase 19 | Pending |
-| UX-01 | Phase 18 | Complete |
-| UX-02 | Phase 18 | Complete |
-| UX-03 | Phase 18 | Complete |
-| UX-04 | Phase 18 | Complete |
-| DOCS-01 | Phase 18 | Complete |
-| DOCS-02 | Phase 18 | Complete |
-| DOCS-03 | Phase 18 | Complete |
-| DOCS-04 | Phase 18 | Complete |
+| VC-01 | Phase 51 | Pending |
+| VC-02 | Phase 51 | Pending |
+| UNIT-01 | Phase 51 | Pending |
+| UNIT-02 | Phase 51 | Pending |
+| UNIT-03 | Phase 51 | Pending |
+| UNIT-04 | Phase 51 | Pending |
+| UNIT-05 | Phase 51 | Pending |
+| UNIT-06 | Phase 51 | Pending |
+| UNIT-07 | Phase 51 | Pending |
+| UNIT-08 | Phase 51 | Pending |
+| CLI-01 | Phase 52 | Pending |
+| CLI-02 | Phase 52 | Pending |
+| CLI-03 | Phase 52 | Pending |
+| PLUG-01 | Phase 53 | Pending |
+| PLUG-02 | Phase 53 | Pending |
+| PLUG-03 | Phase 53 | Pending |
+| E2E-01 | Phase 53 | Pending |
+| E2E-02 | Phase 53 | Pending |
+| E2E-03 | Phase 53 | Pending |
+| E2E-04 | Phase 53 | Pending |
+| E2E-05 | Phase 53 | Pending |
+| JNY-01 | Phase 54 | Complete |
+| JNY-02 | Phase 54 | Complete |
+| JNY-03 | Phase 54 | Complete |
+| CHAOS-01 | Phase 54 | Complete |
+| CHAOS-02 | Phase 54 | Complete |
+| CHAOS-03 | Phase 54 | Complete |
+| CHAOS-04 | Phase 54 | Complete |
+| FIX-01 | Phase 52 | Pending |
+| FIX-02 | Phase 52 | Pending |
+| FIX-03 | Phase 52 | Pending |
+| FIX-04 | Phase 52 | Pending |
+| FIX-05 | Phase 52 | Pending |
+| CI-01 | Phase 51 | Pending |
+| CI-02 | Phase 55 | Pending |
+| CI-03 | Phase 55 | Pending |
+| CI-04 | Phase 53 | Pending |
+| CI-05 | Phase 54 | Complete |
 
 **Coverage:**
-- v1.4 requirements: 30 total
-- Mapped to phases: 30 (100%)
-- Unmapped: 0
+- v2.0 requirements: 38 total
+- Mapped to phases: 38
+- Unmapped: 0 ✓
 
 ---
-
-*Requirements defined: 2026-04-25*
-*Last updated: 2026-04-26 — traceability populated with v1.4 phase mappings (30/30 requirements, 100% coverage)*
+*Requirements defined: 2026-05-08*
+*Last updated: 2026-05-08 after initial definition*

.planning/ROADMAP.md

@@ -1,142 +1,115 @@
-# Roadmap: PaperForge Lite v1.4 — Code Health & UX Hardening
+# Roadmap: PaperForge v2.1 — Contract-Driven Architecture & Engineering Hardening
 
-**Milestone:** v1.4
-**Goal:** Eliminate all code duplication (~1,610 lines), add structured observability, automate code-health guardrails, and smooth user-facing workflow friction.
-**Started:** 2026-04-25
-**Phase numbering:** Continues from v1.3 Phase 12 → v1.4 starts at Phase 13
+## Overview
 
----
+v2.1 transforms PaperForge from feature-stacked monoliths into a contract-driven system. Each phase builds on the last: quick consistency fixes unblock the work (Phase 56), stable JSON contracts define the machine-readable API surface (Phase 57), sync.py decomposes into testable adapters and a service layer (Phase 58), the state machine formalizes with enums and a field registry (Phase 59), and setup_wizard modularizes into focused classes with per-step JSON output (Phase 60). Every requirement maps to exactly one phase.
 
 ## Phases
 
-- [x] **Phase 13: Logging Foundation** — Structured logging, `--verbose` flag, zero behavioral change to user-facing output
-- [x] **Phase 14: Shared Utilities Extraction** — Extract `_utils.py` leaf module, eliminate ~1,610 lines of duplication across 7 workers
-- [x] **Phase 15: Deep-Reading Queue Merge** — Single canonical `scan_library_records()` for both CLI and Agent consumers
-- [x] **Phase 16: Retry + Progress Bars** — Resilient OCR with exponential backoff and user-visible progress indication
-- [x] **Phase 17: Dead Code Removal + Pre-Commit** — Clean codebase validated by automated git hooks
-- [x] **Phase 18: Documentation + CHANGELOG + UX Polish** — Complete user/maintainer docs, README fix, command naming audit (2 plans)
-- [x] **Phase 19: Testing** — E2E pipeline tests, setup wizard tests, `_utils.py` unit tests
-
----
+- [ ] **Phase 56: Stop the Bleeding** — Quick consistency fixes: version sync, PyYAML, README/install unification, plugin version pinning
+- [ ] **Phase 57: Contract Layer** — PFResult/PFError dataclasses, ErrorCode enum, CLI --json contracts (status/doctor/sync/ocr/dashboard) [Planned, 4 plans]
+- [ ] **Phase 58: Service Extraction** — Decompose sync.py into adapters (bbt/zotero_paths/obsidian_frontmatter) and SyncService
+- [ ] **Phase 59: State Machine & Field Registry** — PdfStatus/OcrStatus/Lifecycle enums, ALLOWED_TRANSITIONS, field_registry.yaml, doctor field checks
+- [ ] **Phase 60: Setup Modularization** — SetupPlan/Checker/RuntimeInstaller/VaultInitializer/AgentInstaller/ConfigWriter classes, setup --headless --json
 
 ## Phase Details
 
-### Phase 13: Logging Foundation
-**Goal**: Structured, level-based logging infrastructure with zero behavioral change to user-facing output — sets the stage for all subsequent observability work.
-**Depends on**: Nothing (first phase of v1.4)
-**Requirements**: OBS-01, OBS-02, OBS-03
+### Phase 56: Stop the Bleeding
+**Goal**: Quick consistency fixes that unblock all subsequent phases — version declarations synchronized, dependency declarations resolved, install documentation unified, and plugin runtime version pinned.
+**Depends on**: Nothing (v2.0 complete)
+**Requirements**: BLEED-01, BLEED-02, BLEED-03, BLEED-04
 **Success Criteria** (what must be TRUE):
-  1. All worker modules use `logging.getLogger(__name__)` instead of bare `print()` for diagnostic/trace/error output
-  2. `--verbose`/`-v` flag on `paperforge sync`, `paperforge ocr`, and `paperforge deep-reading` enables DEBUG-level output on stderr
-  3. User-facing status messages continue to appear on stdout unchanged — piped commands (`paperforge status | grep ocr`) remain unbroken
-  4. `PAPERFORGE_LOG_LEVEL` environment variable (accepting `DEBUG`/`INFO`/`WARNING`/`ERROR`) controls default log level
-  5. `paperforge/logging_config.py` exists as the single `configure_logging(verbose)` call point; no scattered `basicConfig()` calls
+  1. `scripts/check_version_sync.py` passes as a CI gate — all 6+ version declarations (__init__.py, manifest.json, versions.json, pyproject.toml, plugin manifest, docs) return consistent
+  2. PyYAML dependency is resolved — either added to pyproject.toml as explicit dependency, or the yaml module existence check is removed from `paperforge doctor` (single source of truth — no "optional dependency" ambiguity)
+  3. README, INSTALLATION, and setup-guide present a single unified primary install path — no conflicting recommendations across the three documents
+  4. Plugin runtime `pip install paperforge` pins to the plugin manifest version — no version drift possible between the Obsidian plugin and the Python package
+**Plans**: 2 plans
+
+Plans:
+- [ ] 056-01-PLAN.md — Version sync CI gate script + PyYAML doctor hardening (BLEED-01, BLEED-02)
+- [ ] 056-02-PLAN.md — Install doc unification + plugin version pinning (BLEED-03, BLEED-04)
+
+### Phase 57: Contract Layer
+**Goal**: Stable JSON contracts (PFResult/PFError dataclasses, ErrorCode enum) that CLI commands produce and the plugin consumes — defining the machine-readable API surface consumed by SYNC, STAT, and SETP phases.
+**Depends on**: Phase 56
+**Requirements**: CTRT-01, CTRT-02, CTRT-03, CTRT-04, CTRT-05, CTRT-06, CTRT-07, CTRT-08
+**Success Criteria** (what must be TRUE):
+  1. `PFResult` and `PFError` dataclasses are defined in `paperforge/core/result.py` with `to_json()` serialization that survives round-trip (serialize → deserialize → equal)
+  2. All error codes are centralized in `ErrorCode` enum in `paperforge/core/errors.py` — no scattered string-based error codes remain in any production module
+  3. `paperforge status --json`, `doctor --json`, `sync --json`, and `ocr --diagnose --json` all return PFResult-format output with consistent `{ok, command, version, data, error}` shape
+  4. `paperforge dashboard --json` returns a stable UI contract with stats (papers, pdf_health, ocr_health, domain_counts) and actionable permissions (can_sync, can_ocr, can_copy_context)
+  5. Plugin reads dashboard data via `paperforge dashboard --json` CLI contract; fallback to direct `formal-library.json` reading remains available during the transition period (removed after 2 release cycles of stable PFResult)
+**Plans**: 4 plans
+**UI hint**: yes
+
+Plans:
+- [ ] 057-01-PLAN.md — Core contract types: ErrorCode enum + PFResult/PFError dataclasses + round-trip tests (CTRT-01, CTRT-02)
+- [ ] 057-02-PLAN.md — Status & doctor --json PFResult wrapping + contract tests (CTRT-03, CTRT-04)
+- [ ] 057-03-PLAN.md — Sync & ocr --diagnose --json PFResult wrapping + contract tests (CTRT-05, CTRT-06)
+- [ ] 057-04-PLAN.md — Dashboard command + plugin contract integration + contract tests (CTRT-07, CTRT-08)
+
+### Phase 58: Service Extraction
+**Goal**: Monolithic sync.py decomposed into focused adapters and a SyncService class — each module independently testable with its own unit tests, sync.py reduced to a thin CLI dispatch layer.
+**Depends on**: Phase 57
+**Requirements**: SYNC-01, SYNC-02, SYNC-03, SYNC-04, SYNC-05
+**Success Criteria** (what must be TRUE):
+  1. `paperforge/adapters/bbt.py` contains all BBT JSON parsing functions (`load_export_rows`, `_normalize_attachment_path`, `_identify_main_pdf`, `extract_authors`, `resolve_item_collection_paths`) — importable and testable in isolation from sync.py
+  2. `paperforge/adapters/zotero_paths.py` contains all path resolution functions (`obsidian_wikilink_for_pdf`, `absolutize_vault_path`, `obsidian_wikilink_for_path`) — no path resolution logic remains in sync.py
+  3. `paperforge/adapters/obsidian_frontmatter.py` contains frontmatter read/write/update operations using YAML parser (replacing regex-based parsing where possible) — importable and testable in isolation
+  4. `paperforge/services/sync_service.py` exists as a `SyncService` class that wraps the decomposed adapter modules; `worker/sync.py` becomes a thin dispatch layer with no business logic beyond orchestration
+  5. All extracted modules have passing unit tests covering BBT JSON variants, path formats (storage:/, absolute Windows, CJK filenames, spaces), and frontmatter edge cases — existing sync behavior preserved (no regressions)
+**Plans**: 4 plans (3 waves)
+
+Plans:
+- [ ] 058-01-PLAN.md — adapters/zotero_paths.py + unit tests (SYNC-02, SYNC-05) [Wave 1]
+- [ ] 058-02-PLAN.md — adapters/bbt.py + unit tests (SYNC-01, SYNC-05) [Wave 2]
+- [ ] 058-03-PLAN.md — adapters/obsidian_frontmatter.py + unit tests (SYNC-03, SYNC-05) [Wave 2]
+- [ ] 058-04-PLAN.md — services/sync_service.py + thin sync.py + full regression (SYNC-04, SYNC-05) [Wave 3]
+
+### Phase 59: State Machine & Field Registry
+**Goal**: Formalized state machine with explicit enums and allowed transitions, plus a field registry that `paperforge doctor` can validate against — making state changes predictable and field drift detectable.
+**Depends on**: Phase 57
+**Requirements**: STAT-01, STAT-02, STAT-03, STAT-04, STAT-05
+**Success Criteria** (what must be TRUE):
+  1. `PdfStatus`, `OcrStatus`, and `Lifecycle` enums are defined in `paperforge/core/state.py` with explicit string values — every existing state string in the codebase maps to an enum member
+  2. `ALLOWED_TRANSITIONS` table defines legal state migrations; workers validate transitions before writing state changes — illegal transitions are rejected with clear, actionable error messages
+  3. `paperforge/schema/field_registry.yaml` defines every field in the system (formal note frontmatter, index entries, paper-meta.json) with public/required/type/owner/description metadata — complete coverage of all field-carrying structures
+  4. `paperforge doctor` checks field completeness against the registry — missing required fields produce actionable warnings with migration suggestions; unknown/invalid fields produce warnings to flag drift
+  5. Edge case: fields present in data but absent from registry trigger a "drift detected" diagnostic; fields in registry but absent from data trigger "missing required field" with severity levels
 **Plans**: 3 plans (2 waves)
 
 Plans:
-- [x] 13-01-PLAN.md — Logging Core: logging_config.py + global --verbose flag
-- [x] 13-02-PLAN.md — Module Loggers: logger instances + diagnostic print migration
-- [x] 13-03-PLAN.md — Verbose Wiring: verbose params + command dispatch passthrough
+- [ ] 059-01-PLAN.md — State machine enums + transitions + lifecycle update (STAT-01, STAT-02) [Wave 1]
+- [ ] 059-02-PLAN.md — Field registry YAML + loader (STAT-03) [Wave 1]
+- [ ] 059-03-PLAN.md — Doctor field completeness checks + drift detection (STAT-04, STAT-05) [Wave 2]
 
----
-
-### Phase 14: Shared Utilities Extraction
-**Goal**: Eliminate ~1,610 lines of copy-pasted utility code by creating `paperforge/worker/_utils.py` as a pure leaf module — THE critical path all subsequent code-health work depends on.
-**Depends on**: Phase 13 (logging infrastructure available for diagnostic output)
-**Requirements**: CH-01, CH-02, CH-05, TEST-03
+### Phase 60: Setup Modularization
+**Goal**: Monolithic setup_wizard.py decomposed into six focused classes with explicit dependencies — enabling `paperforge setup --headless --json` to return per-step status that the Obsidian plugin can render as progress.
+**Depends on**: Phase 57
+**Requirements**: SETP-01, SETP-02, SETP-03, SETP-04, SETP-05, SETP-06, SETP-07
 **Success Criteria** (what must be TRUE):
-  1. `paperforge/worker/_utils.py` exists containing all shared utility functions: `read_json`, `write_json`, `read_jsonl`, `write_jsonl`, `yaml_quote`, `yaml_block`, `yaml_list`, `slugify_filename`, `_extract_year`, `load_journal_db`, `lookup_impact_factor`, `_STANDARD_VIEW_NAMES`, and the `_JOURNAL_DB` cache
-  2. All 7 worker modules (`sync.py`, `ocr.py`, `deep_reading.py`, `repair.py`, `status.py`, `update.py`, `base_views.py`) import shared functions from `paperforge.worker._utils` — no local copy of any utility function remains
-  3. No circular imports: `_utils.py` imports only from stdlib and `paperforge.config` — never from any sibling worker module
-  4. All 205 existing tests pass with zero failures after extraction (verified by `pytest tests/ -x`)
-  5. Re-exports with `# Re-exported from _utils.py for backward compatibility` comments preserved in original modules where callers may still reference them
-**Plans**: 2 plans (1 wave)
+  1. `SetupPlan`, `SetupChecker`, `RuntimeInstaller`, `VaultInitializer`, `AgentInstaller`, and `ConfigWriter` classes each exist with a single responsibility and explicit interface — no class exceeds its boundary
+  2. `paperforge setup --headless --json` returns per-step status — each step has independent `{ok, error, message}` fields; the plugin UI can render step-by-step progress from the JSON output
+  3. `ConfigWriter` writes `paperforge.json` atomically using tempfile + os.replace — no partial or corrupted config files possible on crash or interrupt
+  4. `RuntimeInstaller` handles `pip install` with explicit version pinning (from plugin manifest), progress output via callback, and classified errors using the ErrorCode enum from Phase 57
+  5. `SetupChecker` validates all preconditions (Python executable, pip availability, dependency health) before any installation step begins — failures produce classified, user-readable diagnostics
+**Plans**: 4 plans (2 waves)
 
 Plans:
-- [x] 18-01-PLAN.md — Core Config & Foundation Docs (auto_analyze_after_ocr, CHANGELOG, CONTRIBUTING)
-- [x] 18-02-PLAN.md — Migration, Architecture & Doc Polish (MIGRATION, ADRs, AGENTS, INDEX, README)
-
----
-
-### Phase 19: Testing
-**Goal**: Validate the entire v1.4 codebase with expanded test coverage — E2E pipeline tests, setup wizard tests, and dedicated `_utils.py` unit tests.
-**Depends on**: All previous phases (tests validate the final v1.4 state)
-**Requirements**: TEST-01, TEST-02, TEST-04
-**Success Criteria** (what must be TRUE):
-  1. E2E integration tests pass covering full Zotero JSON → selection-sync → index-refresh → OCR queue → formal notes pipeline using the sandbox fixture vault
-  2. Setup wizard tests pass validating agent platform detection, vault path resolution, environment checks, and configuration file generation
-  3. Dedicated unit tests for `_utils.py` cover JSON I/O, YAML helpers, slugify, and journal DB functions — `test_utils_json.py`, `test_utils_yaml.py`, `test_utils_slugify.py`, `test_utils_journal.py`
-  4. All 205 existing tests continue to pass with zero failures — minimum bar: 205+ tests passing, 0 failures, 0 errors
-**Plans**: 3 plans (1 wave)
-
-Plans:
-- [ ] 19-01-PLAN.md — _utils.py unit tests (JSON I/O, YAML helpers, slugify, journal DB)
-- [ ] 19-02-PLAN.md — E2E pipeline integration tests (selection-sync → index-refresh → OCR queue → formal notes)
-- [ ] 19-03-PLAN.md — Setup wizard tests (Agent configs, EnvChecker, path resolution)
-
----
+- [ ] 060-01-PLAN.md — SetupStepResult type + SetupChecker + ConfigWriter (SETP-02, SETP-06) [Wave 1]
+- [ ] 060-02-PLAN.md — VaultInitializer + RuntimeInstaller (SETP-03, SETP-04) [Wave 1]
+- [ ] 060-03-PLAN.md — AgentInstaller (SETP-05) [Wave 1]
+- [ ] 060-04-PLAN.md — SetupPlan orchestrator + CLI integration + backward-compat shim (SETP-01, SETP-07) [Wave 2]
+**UI hint**: yes
 
 ## Progress
 
-**Execution Order:** Phases 13-14-15-16 are strictly sequential (hard dependency chain). Phase 18 can overlap partially with Phases 14-17. Phase 19 must be last.
+**Execution Order:** 56 → 57 → 58 → 59 → 60
 
-| Phase | Milestone | Plans Complete | Status | Completed |
-|-------|-----------|----------------|--------|-----------|
-| 13. Logging Foundation | v1.4 | 3/3 | Complete    | 2026-04-27 |
-| 14. Shared Utils Extraction | v1.4 | 0/0 | Not started | — |
-| 15. Queue Merge | v1.4 | 1/1 | Complete   | 2026-04-27 |
-| 16. Retry + Progress | v1.4 | 2/2 | Complete | 2026-04-27 |
-| 17. Dead Code + Pre-Commit | v1.4 | 1/1 | Complete | 2026-04-27 |
-| 18. Docs + CHANGELOG + UX | v1.4 | 2/2 | Complete   | 2026-04-27 |
-| 19. Testing | v1.4 | 0/3 | Not started | — |
-
-### Historical Milestones
-
-<details>
-<summary>✅ v1.0 MVP (Phases 1-5) — SHIPPED 2026-04-23</summary>
-
-- Phase 1: Config And Command Foundation (3/3 plans)
-- Phase 2: PaddleOCR And PDF Path Hardening (2/2 plans)
-- Phase 3: Config-Aware Obsidian Bases (2/2 plans)
-- Phase 4: End-To-End Onboarding And Validation (2/2 plans)
-- Phase 5: Release Verification (2/2 plans)
-
-_Archived: `.planning/milestones/v1.0.md`_
-
-</details>
-
-<details>
-<summary>✅ v1.1 Sandbox Onboarding (Phases 6-8) — SHIPPED 2026-04-24</summary>
-
-- Phase 6: Setup, CLI, And Diagnostics Consistency (3/3 plans)
-- Phase 7: Zotero PDF, Metadata, And State Repair (2/2 plans)
-- Phase 8: Deep Helper Deployment And Sandbox Regression Gate (2/2 plans)
-
-_Archived: `.planning/milestones/v1.1.md`_
-
-</details>
-
-<details>
-<summary>✅ v1.2 Systematization & Cohesion (Phases 9-10) — SHIPPED 2026-04-24</summary>
-
-- Phase 9: Command Unification & CLI Simplification (2/2 plans)
-- Phase 10: Documentation & Cohesion (2/2 plans)
-
-_Archived: `.planning/milestones/v1.2-ROADMAP.md`_
-
-</details>
-
-<details>
-<summary>✅ v1.3 Path Normalization & Architecture Hardening (Phases 11-12) — SHIPPED 2026-04-24</summary>
-
-- Phase 11: Zotero Path Normalization (1/1 plan)
-- Phase 12: Architecture Cleanup (1/1 plan)
-
-_Archived: `.planning/milestones/v1.3.md`_
-
-</details>
-
----
-
-*Roadmap created: 2026-04-26 — Milestone v1.4 Code Health & UX Hardening*
-*Phase numbering continues from v1.3 Phase 12*
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 56. Stop the Bleeding | 0/2 | Ready to execute | — |
+| 57. Contract Layer | 0/TBD | Not started | — |
+| 58. Service Extraction | 0/4 | Planned | — |
+| 59. State Machine & Field Registry | 0/3 | Planned | — |
+| 60. Setup Modularization | 0/4 | Planned | — |

.planning/STATE.md

@@ -1,104 +1,50 @@
----
-gsd_state_version: 1.0
-milestone: v1.4
-milestone_name: milestone
-status: In progress
-stopped_at: Phase 19 execution complete
-last_updated: "2026-04-27T10:52:33.704Z"
-progress:
-  total_phases: 3
-  completed_phases: 2
-  total_plans: 6
-  completed_plans: 6
----
-
-# State: PaperForge Lite Release Hardening
+# Project State
 
 ## Project Reference
 
-See: `.planning/PROJECT.md` (updated 2026-04-25)
+See: .planning/PROJECT.md (updated 2026-05-08)
 
-**Core value:** A new user can install PaperForge, configure their own vault paths and PaddleOCR credentials, then run the full literature pipeline with copy-pasteable commands that diagnose failures clearly.
-
-**Current focus:** Phase 13 — logging-foundation
+**Core value:** Researchers always know what papers they have, what state those papers are in, and whether each paper is reliably usable by AI with traceable fulltext, figures, notes, and source links.
+**Current focus:** Phase 56 — Stop the Bleeding
 
 ## Current Position
 
-Phase: 19
-Plans: 19-01 ready to execute, 19-02 ready to execute, 19-03 ready to execute
+Phase: 57 of 60 (Contract Layer)
+Plan: 0 of 4 in current phase
+Status: Ready to execute
+Last activity: 2026-05-09 — Phase 57 plans created (4 plans, 12 tasks, 2 waves)
+
+Progress: [░░░░░░░░░░░░░░░░░░░░] 0%
 
 ## Performance Metrics
 
 **Velocity:**
+- Total plans completed: 0
+- Average duration: — min
+- Total execution time: 0.0 hours
 
-- Total phases completed (cumulative): 14
-- v1.4 phases: 2/7 complete
+**By Phase:**
 
-**By Milestone:**
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| — | — | — | — |
 
-| Milestone | Phases | Status |
-|-----------|--------|--------|
-| v1.0 MVP | 1-5 | Shipped 2026-04-23 |
-| v1.1 Sandbox | 6-8 | Shipped 2026-04-24 |
-| v1.2 Systematization | 9-10 | Shipped 2026-04-24 |
-| v1.3 Architecture | 11-12 | Shipped 2026-04-24 |
-| v1.4 Code Health | 13-19 | In progress |
+**Recent Trend:**
+- No plans executed yet.
 
 *Updated after each plan completion*
-| Phase 13-logging-foundation P01 | 18min | 2 tasks | 2 files |
-| Phase 13-logging-foundation P02 | 12min | 2 tasks | 12 files |
-| Phase 13-logging-foundation P03 | 8min | 2 tasks | 6 files |
-| Phase 15-deep-reading-queue-merge P01 | 4min | 2 tasks | 3 files |
-| Phase 15-deep-reading-queue-merge P01 | 4min | 2 tasks | 3 files |
-| Phase 17-dead-code-precommit P01 | 25min | 2 tasks | 11 files |
-| Phase 18-documentation-ux-polish P01 | 12min | 3 tasks | 4 files |
-| Phase 18-documentation-ux-polish P01 | 12min | 3 tasks | 4 files |
-| Phase 18-documentation-ux-polish P02 | 18min | 3 tasks | 6 files |
 
 ## Accumulated Context
 
-### v1.4 Critical Path
+### Decisions
 
-- **Phase 13:** Logging Foundation (enables all observability work)
-- **Phase 14:** Shared Utils Extraction (critical path — all code-health work depends on `_utils.py`)
-- **Phases 13-14-15-16:** Strictly sequential (hard dependency chain)
-- **Phase 18:** Can partially overlap with Phases 14-17
-- **Phase 19:** Must be last (validates final state)
+Decisions are logged in PROJECT.md Key Decisions table.
+Recent decisions affecting current work:
 
-### v1.4 Key Decisions (from research)
-
-- **Dual-output logging:** `print()` stays for user-facing stdout; `logging` for diagnostic stderr — NOT a wholesale replacement
-- **`_utils.py` leaf module:** Must never import from `paperforge.worker.*` or `paperforge.commands.*` — circular import firebreak
-- **Re-exports preserved:** Moved functions get `# Re-exported from _utils.py` comments in original modules for backward compatibility
-- **No new user-facing features:** v1.4 is pure infrastructure hardening — `auto_analyze_after_ocr` is the only opt-in workflow option
-
-### v1.4 Environment Variables (new)
-
-- `PAPERFORGE_LOG_LEVEL` — `DEBUG`/`INFO`/`WARNING`/`ERROR`
-- `PAPERFORGE_RETRY_MAX` — max retry attempts
-- `PAPERFORGE_RETRY_BACKOFF` — backoff multiplier
-
-### Phase 11 Decisions (Locked)
-
-- D-01 through D-08: Documented in ADR-011
-- `storage:` prefix as unified internal representation for Zotero storage paths
-- Hybrid main PDF selection (title → size → shortest title)
-- Forward slashes exclusively in wikilinks (`Path.as_posix()`)
-- `path_error` frontmatter field for explicit error tracking
-
-### Phase 17 Decisions (Locked)
-
-- `from paperforge.config import load_vault_config, paperforge_paths` replaces all per-module delegation wrappers
-- Pre-commit hooks configured but NOT auto-installed (DX-04 deferred to Phase 18)
-- `ruff check --fix` + `ruff format` are sufficient for automated code cleanup
-- `E501` (line-too-long) and pre-existing simplifications suppressed via `per-file-ignores` — not a blocker for code quality
-
-### Phase 12 Decisions (Locked)
-
-- Migrated 4041-line `literature_pipeline.py` into 7 focused modules under `paperforge/worker/`
-- Function-level imports used to break circular dependencies between sync.py and ocr.py
-- Module-reference imports (`_sync.run_selection_sync`) used in ocr.py for test patch compatibility
-- Old `pipeline/` and `skills/` directories removed after confirming zero import references
+- [v2.1]: Incremental extraction from sync.py — adapters first, then SyncService, keeping sync.py as thin shell. No full rewrite.
+- [v2.1]: Dual JSON output during contract transition — old format + new PFResult side-by-side until 2 release cycles of stability.
+- [v2.1]: Plugin keeps fallback to direct index reading during PFResult transition — removed after 2 stable release cycles.
+- [v2.1]: Tests must not be modified to pass if code is broken — tests verify contracts, not implementation convenience.
 
 ### Pending Todos
 
@@ -106,15 +52,10 @@ None yet.
 
 ### Blockers/Concerns
 
-- **Circular import risk in Phase 14:** `_utils.py` must be pure leaf module — verify with `pytest --collect-only` after each worker migration
-- **Windows TTY detection (Phase 16):** `sys.stdout.reconfigure(encoding='utf-8')` may not work on all PowerShell configs — test on actual Windows 10/11
-- **Backward compatibility:** Users relying on `from paperforge.worker.sync import read_json` — mitigation: re-exports with deprecation comments
-- **Pre-commit hooks not installed:** CONTRIBUTING.md documents `pre-commit install` (DX-04 docs complete). Hooks must be manually installed by each developer.
+None yet.
 
 ## Session Continuity
 
-Last session: 2026-04-27T10:52:33.701Z
-Stopped at: Phase 19 execution complete
-Resume file: .planning/phases/19-testing/19-03-SUMMARY.md
-
----\n*Initialized: 2026-04-23*\n*Last updated: 2026-04-26 (v1.4 roadmap created — Phase 13 ready to plan)*
+Last session: 2026-05-09
+Stopped at: Roadmap created — files written (ROADMAP.md, STATE.md, REQUIREMENTS.md traceability)
+Resume file: None