@nynb/sandpaper 0.1.0

package/skill/sandpaper/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: sandpaper
+description: >-
+  Use when working in a repo that has (or should have) a Sandpaper "project brain" — a
+  brain/ folder of static HTML that is a living service-manual mirroring the project's
+  state. Invoke to STAMP the brain after substantive turns (log the work, refresh the
+  digest, flip plan tasks, record decisions/learnings), to scaffold a new brain, to serve
+  it, or to re-skin it. Keeps the brain current and link-never-copy.
+---
+
+# Sandpaper — the living project brain
+
+Sandpaper turns a project's state into a navigable, always-current web **service manual**
+(`brain/`) that the agent maintains. A fresh `claude` reads the brain to rehydrate; after
+each substantive turn the agent **stamps** it. The brain is the **eyes** (state made
+visible); steering stays in the terminal (the **mouth**).
+
+## Layout
+- `brain/index.html` — the cover/portal: a `#brain-state` JSON **digest** (read first), the
+  **NOW** line, derived progress, **needs-you**, **latest**.
+- Lenses: `product/`, `engineering/`, `project/` (the **plan board**) — the prose home per lens.
+- Books: `log.html` (work log), `decisions.html` (ledger), `learnings.html` (gotchas), `wiki/`.
+- `assets/theme.css` — one file re-skins everything; `assets/brain.js` derives all numbers.
+
+## Grammar
+Every durable fact is an `.entry` carrying `data-cid` (mirrored to `id`), `data-kind`,
+`data-status`, `data-date`, at least one `data-ref` into a canonical anchor, and an optional
+`data-lens`. **Link, never copy** — point at the canonical doc; don't restate it (the wiki is
+the one prose exception). Every block carries `data-cid`; an agent must never strip cids.
+
+## STAMP — after every substantive turn (not optional)
+Templated, never free-form. Regenerate whole regions; never prose-edit inside one.
+1. **LOG** — prepend exactly one row to the top of `log.html` (verb-led, ≤12 words, ends in a
+   link). Never edit a prior row.
+2. **NOW** — overwrite the cover's `<!-- BRAIN:NOW -->…` region with one present-tense
+   sentence (≤120 chars) + a link to what you touched. Replace, never append.
+3. **DIGEST** — overwrite `#brain-state` so `focus`, the newest worklog line, and `open` match.
+4. **DECISIONS** — if a call was made/resolved: append a status-typed entry, or flip ONE
+   `data-status`. A reversal is a NEW entry with `data-rel="supersedes:<id>"` — never rewrite.
+5. **LEARNINGS** — if a gotcha bit, append one callout.
+6. **PLAN** — flip the relevant task's `data-status`; progress **derives** (never type a number).
+7. **CANVAS** — board-first (see below): if the turn's reply is a substantive summary or explanation,
+   it should already BE the current board on the whiteboard — demote the previous current into
+   *Earlier*, cap at 5, leave a `📋 … → on the canvas` pointer. (Pure-conversation turns don't stamp,
+   but board-first still applies to their replies.)
+
+## CANVAS — board-first: substantial replies go on the cover, not the scrollback
+The cover hosts a **canvas** (the `<!-- BRAIN:CANVAS -->` region of `index.html`): a **whiteboard** —
+a white `.whiteboard` container whose content scrolls inside it. The newest board sits full and live
+in the whiteboard; older ones fold into a collapsed *Earlier* stack below it (normal page flow).
+
+**Board-first is the default.** When your reply would be a substantial summary or explanation — the
+recap of a turn, an architecture, a comparison, a walkthrough, an analysis — the **board IS the reply**:
+write the elevated version as the current board and leave the terminal ONE line (`📋 <gist> → on the
+canvas`). Don't write it twice. Short answers, confirmations, and the back-and-forth stay in the
+terminal. The terminal **steers**; the canvas **shows**. No hook enforces this — boarding a *judgment*
+can't be enforced the way "you changed code, go stamp" can; the pointer is the tripwire (no pointer
+means nothing was boarded).
+
+- **A board** is freeform, self-contained, theme-skinned rich HTML (SVG/CSS diagrams, tables, code,
+  side-by-sides — the things that die in a terminal). NOT the `.entry` grammar — boards are working
+  output; lavish is fine.
+- **To add one:** the new board becomes the CURRENT one — replace the `<article class="board board--live"
+  data-cid="board-NNNN" …>…</article>` inside `.whiteboard`. Move the previously-current board to the
+  TOP of the `.canvas-earlier` list (below the whiteboard) as a collapsed `<details class="board board--past">
+  <summary class="board-row"><span class="board-row-dot"></span><span class="board-row-when">MM-DD · NNN</span><span
+  class="board-row-title">…</span><span class="board-row-chev">›</span></summary>…body + foot…</details>`.
+  Cap the stack at **5 total** — drop the oldest `<details>`. Update the `canvas-count` and the
+  `Earlier · N` label. Then in the terminal: `📋 <gist> → on the canvas`.
+- **When NOT to:** short answers, direct edits, confirmations, lookups — those stay in the terminal.
+  Don't over-produce; a board is for something worth a second screen.
+- **Canvas → brain.** Boards are the *working* layer; the brain (wiki/decisions/learnings) is the
+  *settled* layer. Promote a board only when it proves durable — via the STAMP — and never write
+  live explanations straight into the wiki. `/sandpaper:canvas <topic>` forces a board on demand.
+
+## Plan model
+`phase → initiative → task → session`. Initiatives carry `data-phase`; tasks carry
+`data-initiative`/`data-status`/`data-session`. `brain.js` sums task status into the
+initiative, phase, and overall bars. The only operations: FLIP a task's status, APPEND a
+task/initiative, STAMP a session. Never reuse a cid; re-scope = append + flip the old one.
+
+## Auto-update — the brain stays current without prodding
+Two Claude Code hooks (scripts in `bin/`):
+- **SessionStart → `bin/brain-inject.js`** — surfaces the digest so a fresh session
+  rehydrates from the brain automatically.
+- **Stop → `bin/brain-stamp-check.js`** — if a turn changed project files but didn't touch
+  `brain/`, it **blocks once** with a reminder to STAMP. Self-limiting: it honors
+  `stop_hook_active` (never loops), is idempotent (stops firing once `brain/` is touched), and
+  the agent can override by simply stopping again.
+
+Enable by merging into `.claude/settings.json` (project) or `~/.claude/settings.json` (user):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node bin/brain-inject.js", "timeout": 10 }] }],
+    "Stop":         [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node bin/brain-stamp-check.js", "timeout": 20 }] }]
+  }
+}
+```
+
+Remove either entry to disable. This is the difference between the brain being a discipline
+you might forget and a system that cannot silently drift.
+
+## Commands
+`/help` (this list) · `/init` (harvest → interview → generate a brain) · `/stamp` (the 6-step
+stamp) · `/canvas` (elevate an explanation into a board on the cover) · `/plan` · `/decide` ·
+`/learn` · `/log` · `/sync` (reconcile + heal drift) ·
+`/open` (serve + open the brain in a browser) · `/serve` (on-page refine toolbar) · `/theme`
+(re-skin from a brand hex). Run `/sandpaper:help` for the full grouped list.
+
+## Serve / refine in place
+`npx sandpaper <dir>` serves the brain with an on-page toolbar — **Sand** (scoped AI edit),
+**✎ Hands** (direct edit, no AI), **❯ Sling** (hand a terminal-ready instruction over).

package/skill/sandpaper/commands/canvas.md

@@ -0,0 +1,31 @@
+---
+description: Elevate an explanation into a rich board on the cover's canvas (not the terminal)
+---
+
+Write the current (or named) summary/explanation as a **board** on the cover's canvas — the
+`<!-- BRAIN:CANVAS -->` region of `brain/index.html`, a white `.whiteboard` container — instead of
+leaving it in the terminal. The terminal steers; the canvas shows.
+
+A board is freeform, self-contained, **theme-skinned** rich HTML: lead with the point, then make it
+*visual* where that helps — a CSS/SVG diagram, a comparison table, code, a side-by-side. It is NOT
+the `.entry` grammar (boards are working output; lavish is fine), but it must use the project's
+theme classes so it matches the rest of the surface.
+
+The canvas is a **whiteboard, not a notebook**: the newest board is the CURRENT one (full + live);
+older boards fold into a collapsed *Earlier* stack, capped at five.
+
+Steps:
+1. The new board becomes the CURRENT one — replace the `<article class="board board--live"
+   data-cid="board-NNNN" data-kind="board" data-date="YYYY-MM-DD" data-ref="<source>">` inside
+   `.whiteboard`, with a `.board-head` (dot · title · `MM-DD · board NNN`), a rich `.board-body`, and a
+   `.board-foot`.
+2. Move the previously-current board to the TOP of the `.canvas-earlier` list (below the whiteboard) as
+   a collapsed `<details class="board board--past"><summary class="board-row">…dot · `MM-DD · NNN` · title · ›…</summary>…body + foot…</details>`.
+   Remove any `.canvas-empty` placeholder.
+3. Cap the stack at **5 boards total** — drop the oldest `<details>`. Update the `canvas-count` and
+   the `Earlier · N` label.
+4. In the terminal, leave one line: `📋 <gist> → on the canvas`.
+
+Keep boards for things worth a second screen (architecture, comparisons, walkthroughs, analyses);
+short answers stay in the terminal. Durable boards are **promoted** into the brain later via the
+STAMP — the canvas never writes straight into the wiki or decisions.

package/skill/sandpaper/commands/decide.md

@@ -0,0 +1,16 @@
+---
+description: Record a decision (or open/resolve a question) in the brain ledger
+argument-hint: "<the decision, and why>"
+---
+
+Append a decision to `brain/decisions.html`: $ARGUMENTS.
+
+Use the grammar: `<article class="entry entry--decision" data-kind="decision" data-status="accepted"
+data-date data-ref data-lens id="d-…" data-cid="d-…">` with **Decision / Because / Instead-of**
+fields and a link to the canonical anchor. Next monotonic `D-NNN`.
+
+- To **resolve** a question, flip its `data-status`.
+- To **reverse** a prior call, add a NEW entry with `data-rel="supersedes:<id>"` — never rewrite
+  the old one.
+
+Then LOG it (`/sandpaper:log`) and bump the cover's `<b data-count="decision">` count.

package/skill/sandpaper/commands/help.md

@@ -0,0 +1,25 @@
+---
+description: List the Sandpaper commands and what each one does
+---
+
+Show the user the Sandpaper command set, grouped like this, then offer to run one:
+
+**Maintain the brain**
+- `/sandpaper:stamp` — stamp the brain after a substantive turn (the 6-step update)
+- `/sandpaper:log` — add one work-log row (the heartbeat)
+- `/sandpaper:plan` — add or flip a task / initiative on the plan board
+- `/sandpaper:decide` — record a decision, or open/resolve a question
+- `/sandpaper:learn` — record a gotcha or verdict learning
+- `/sandpaper:canvas` — elevate an explanation into a board on the cover's canvas
+- `/sandpaper:sync` — reconcile the brain against the code; find + heal drift
+
+**Set up & run**
+- `/sandpaper:init` — scaffold a new brain for this repo (harvest → interview → generate)
+- `/sandpaper:open` — start the server and open the brain in your browser
+- `/sandpaper:serve` — serve the brain (or any doc) with the on-page refine toolbar
+- `/sandpaper:theme` — re-skin the whole brain from one brand colour
+- `/sandpaper:help` — this list
+
+Then note: the brain also auto-maintains via two hooks — **SessionStart** rehydrates from the
+digest, **Stop** nudges you to stamp if a turn changed code but not the brain
+(`skill/sandpaper/SKILL.md` → Auto-update). Keep it concise; don't dump file contents.

package/skill/sandpaper/commands/init.md

@@ -0,0 +1,113 @@
+---
+description: Scaffold a living Sandpaper brain for this repo — discover widely, run a wizard, generate
+---
+
+Build a living project brain (`brain/`) for this repo. Five movements: **INTRODUCE**, **DISCOVER**
+(scan widely), **WIZARD** (interactive — fill the gaps + shape the brain), **GENERATE**, **WELCOME**.
+
+## 0. INTRODUCE — a premium, human welcome (then a go-ahead gate)
+Make the first impression feel crafted, not chatty. **Open with the banner, printed verbatim in a code block:**
+
+```
+  ░█▀▀░█▀█░█▀█░█▀▄░█▀█░█▀█░█▀█░█▀▀░█▀▄
+  ░▀▀█░█▀█░█░█░█░█░█▀▀░█▀█░█▀▀░█▀▀░█▀▄
+  ░▀▀▀░▀░▀░▀░▀░▀▀░░▀░░░▀░▀░▀░░░▀▀▀░▀░▀
+        refine on the page
+```
+
+Then a **short, warm, plain-language** intro — no jargon, no wall of text. In ~3 lines the owner
+actually cares about:
+- **What you'll get** — a living "brain" for this repo: a small local website that shows what the
+  project is, its plan, the decisions, and its history — and stays current as you work. Your project,
+  made legible at a glance.
+- **What happens now** — I skim the repo, ask you a few quick questions, then build it.
+- **You're in control** — stop me anytime; it's all local files, nothing leaves your machine.
+
+Keep it human and brief — a welcome, not a manual.
+
+Then **gate on a go-ahead with the AskUserQuestion tool** (never plain prose — it breaks the flow and
+forces typing). Do a quick, cheap size read first (count source files, list top dirs — don't read
+everything). **Be honest about time:** building a real brain is a lot of writing, so even a SMALL repo
+is roughly **15–30 minutes** and a fair chunk of tokens; bigger repos take longer — never lowball it.
+Ask: header "Build it?", question e.g. *"~N source files. Building the brain runs ~15–30 min and uses
+a fair few tokens — a one-time setup. Go?"*, options **Build it** · **Scope it down (just code)** ·
+**Not now**. Begin DISCOVER only once they pick; honor a scoped choice.
+
+## 1. DISCOVER — cast a wide net; classify by content, not filename
+Projects are organised every which way, so don't assume fixed paths. Glob broadly
+(`**/*.md`, `docs/**`, `spec/**`, `rfc*/**`, `adr/**`, `design/**`), read what you find, and group it:
+
+- **Code** — the manifest (`package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` / …), entry
+  points, the source layout + module graph, tests, the build/CI config.
+- **Specs & design** — `SPEC*.md`, RFCs, ADRs (`docs/adr/`, `decisions/`), `ARCHITECTURE.md`,
+  design docs, anything spec-shaped by its contents.
+- **Work history & plans** — `CHANGELOG.md`, `TODO.md`, `ROADMAP.md`, `NOTES`, the `git log`, and
+  any issue/PR references in commit messages.
+- **Meta** — `README`, `CONTRIBUTING`, a `docs/` site, the `LICENSE`.
+- **External pointers** — links in the README/docs to a Notion / wiki / Figma / issue tracker. You
+  can't read those; note them and raise them in the wizard.
+
+From all of it infer: the project's name + what it is, its components + their status, the recent
+work, the apparent roadmap, and any decisions/gotchas already written down somewhere.
+
+## 2. WIZARD — interactive; never guess what you can ask
+Show the owner a short summary of what you found, **grouped** (code · specs · logs · docs ·
+external links). Then run a brief wizard — **use the AskUserQuestion tool for the shaping choices**
+(lenses, books, theme, phases), not a wall of prose; ask in small batches:
+
+**a. Fill discovery gaps.** "Did I miss anything? Where's your spec / design / roadmap if I didn't
+find it? Any external docs (Notion / wiki / Figma) I should fold in by hand?" Let them point you at
+artifacts the scan missed — and paste/summarise anything you can't reach.
+
+**b. Shape the brain** — confirm what *this* project's brain should hold (don't impose the full
+template):
+- Which **lenses** matter — product, engineering, project (the plan board), a subset, or a custom one?
+- Which **books** — decisions, learnings, a glossary, a stats page? (default: decisions + learnings + log)
+- The current **focus**, near-term **goals**, and any **open decisions/risks** you couldn't infer.
+- A **theme** — a brand colour to skin it (else the warm default)?
+- Do they think in **phases / milestones / rungs**? (to seed the plan board's grouping)
+- A **port** — if they run Sandpaper for several repos at once, suggest pinning a distinct
+  `port` in `.sandpaper/manifest.json` (default 4848; the server auto-bumps if it's taken).
+
+Keep it to ~5–8 questions total; infer everything else.
+
+## 3. GENERATE — seeded with REAL content, shaped by the answers
+The design-system assets are **already in `brain/assets/`** (`theme.css` + `brain.css` + `brain.js`) —
+`install-skill` scaffolded them from the Sandpaper package, along with a starter `brain/index.html`.
+**Use them as-is.** Do NOT regenerate the assets, and **NEVER read, copy, or take templates / a
+reference brain from any other directory or sibling project on disk** — that's someone else's repo,
+not the Sandpaper package, and it won't exist on a distributed install. If `brain/assets/` is somehow
+missing, stop and run `npx sandpaper init` (or ask the owner for the package path) — never go hunting.
+
+**The multi-page skeleton is already on disk** — `install-skill` scaffolded the cover (`index.html`),
+three lens pages (`product/index.html`, `engineering/index.html`, `project/index.html`), and three
+books (`log.html`, `decisions.html`, `learnings.html`), each with the shared shell nav wired to
+relative paths. **FILL these existing pages** (replace the `<!-- FILL: … -->` stubs with real content).
+The brain is a **MULTI-PAGE site**: every lens and book is a SEPARATE `.html` file the shell nav links
+to by relative path — **never collapse it into one page, and never turn the nav into in-page
+`#anchors`.** Use the `.entry` grammar (`data-cid`→`id`, `data-kind`, `data-status`, `data-date`,
+≥1 `data-ref`, optional `data-lens`). **Link, never copy** — `data-ref` points at the real artifacts you
+discovered (a spec's heading anchor if it has one, else the source file / README section). Generate
+ONLY the lenses + books the owner chose; dim any deferred chrome so nothing dangles. Seed the plan
+board from the discovered state (shipped = `done`; gaps between the code and the README/spec = the
+honest backlog), the log from the git history, and the decisions/learnings books from anything
+already written down. **Keep the scaffolded canvas** on the cover as-is — the `<!-- BRAIN:CANVAS -->`
+region with its plain-language empty state; don't rewrite that copy into jargon (it fills with boards
+as you work). Stamp the first log row, verify the `#brain-state` JSON parses and links resolve.
+
+## 4. WELCOME — a tight close, then OPEN it (the money shot)
+Don't spread this into blabber. A short, confident close, then the payoff:
+- **One line of what got built** — e.g. *"Your brain is live: a cover, 3 lenses, and 4 books, all
+  seeded from the real repo."*
+- **One line on using it** — refine on the page with **Sand** (say a change) · **✎ Hands** (edit
+  directly) · **❯ Sling** (hand a job to the terminal); it also stays current on its own as you work.
+
+Then **OPEN it yourself — the payoff must not be left to chance.** Serve the brain + open the browser
+by running the `open` command **in the background** (so it keeps serving without blocking the turn):
+read the `pkg` in `.sandpaper/manifest.json` and run `node <pkg>/bin/cli.js open` in the background
+(or `sandpaper open` if it's on PATH). It opens their browser on the brain and greets them with the
+one-time tour. Actually do it — don't just suggest it; if it genuinely can't run, hand them the one
+exact command.
+
+Keep the whole close under ~8 lines. `/sandpaper:help` lists every command. If you didn't commit
+(e.g. a branch rule you discovered), offer that as the very last line.

package/skill/sandpaper/commands/learn.md

@@ -0,0 +1,11 @@
+---
+description: Record a gotcha or verdict learning in the brain
+argument-hint: "<what bit you, and the takeaway>"
+---
+
+Append one callout to `brain/learnings.html`: $ARGUMENTS.
+
+`<aside class="entry entry--learning callout gotcha|verdict" data-kind="learning"
+data-status="active" data-date data-area data-tags id="l-…" data-cid="l-…">` — a **bold one-line
+claim**, the why in a sentence, and a back-link to where it bit. `gotcha` = something that broke;
+`verdict` = a settled judgement. Then LOG it (`/sandpaper:log`).

package/skill/sandpaper/commands/log.md

@@ -0,0 +1,9 @@
+---
+description: Add a work-log row to the brain (the heartbeat)
+argument-hint: "<what you did, ≤12 words>"
+---
+
+Prepend one `<li>` row to the top of `brain/log.html` AND the cover's `<!-- BRAIN:LOG -->` feed:
+$ARGUMENTS. Next monotonic `w-NNNN` cid; verb-led, ≤12 words, ends in a link to a canonical anchor.
+Never edit a prior row. Refresh the cover NOW + `#brain-state` digest so the newest worklog line
+matches.

package/skill/sandpaper/commands/open.md

@@ -0,0 +1,15 @@
+---
+description: Start the Sandpaper server and open the brain in your browser
+---
+
+Open the project's brain dashboard:
+
+1. Check whether a server is already on port 4848 (`lsof -ti :4848`). If not, start one in the
+   background from the repo root: `node bin/cli.js .` (serving the repo so the brain's `spec ↗` /
+   `engg ↗` links resolve), or `node bin/cli.js brain/` for the brain alone.
+2. Open the cover in the default browser — `open http://127.0.0.1:4848/brain/index.html` on macOS
+   (`xdg-open` on Linux, `start` on Windows).
+3. Tell the user the URL. Every page carries the on-page toolbar — **Sand** (scoped AI edit),
+   **✎ Hands** (direct edit, no AI), **❯ Sling** (copy a terminal-ready instruction).
+
+The file on disk stays the single source of truth; the page always reflects disk.

package/skill/sandpaper/commands/plan.md

@@ -0,0 +1,16 @@
+---
+description: Add or update a task/initiative on the Sandpaper plan board
+argument-hint: "flip t-NNNN done | add \"<task>\" to <initiative> | new initiative \"<name>\" in phase <0|1>"
+---
+
+Update `brain/project/index.html` per: $ARGUMENTS.
+
+- **FLIP a task** = change ONE `data-status` (todo→doing→done|blocked). On `done`, set
+  `data-session` and prepend a log row.
+- **ADD a task** = next monotonic `t-NNNN` under the right `data-initiative`, status `todo`.
+- **ADD an initiative** = a new `.entry--initiative` with `data-phase`, `data-lens="project"`, and
+  an empty `data-rollup` / `data-progress` (brain.js fills them).
+
+Never reuse a cid; re-scoping = append a new task + flip the old one to done/blocked. Never type a
+progress number — `brain.js` derives every bar from task status. Then run the rest of the STAMP if
+the turn was substantive (`/sandpaper:stamp`).

package/skill/sandpaper/commands/serve.md

@@ -0,0 +1,8 @@
+---
+description: Serve the brain (or any Sandpaper doc) with the on-page refine toolbar
+---
+
+Run `node bin/cli.js brain/` (or `node bin/cli.js <doc.html>`) in the background — it serves on
+http://127.0.0.1:4848 with the on-page toolbar: **Sand** (scoped AI edit), **✎ Hands** (direct
+edit, no AI), **❯ Sling** (copy a terminal-ready instruction). Tell the owner the URL and that the
+file on disk stays the single source of truth.

package/skill/sandpaper/commands/stamp.md

@@ -0,0 +1,25 @@
+---
+description: Stamp the Sandpaper brain after a substantive turn (the 6-step update)
+argument-hint: "[optional one-line summary of the turn]"
+---
+
+Update the project brain in `brain/` to reflect the work just done $ARGUMENTS. Follow the STAMP
+contract exactly (`skill/sandpaper/SKILL.md` → STAMP / the project's CLAUDE.md). Do every step
+that applies, regenerating WHOLE regions — never prose-edit inside one:
+
+1. **LOG** — prepend exactly one `<li>` row to the top of `brain/log.html` AND the cover's
+   `<!-- BRAIN:LOG -->` feed. Verb-led, ≤12 words, ends in a link to a canonical anchor. Use the
+   next monotonic `w-NNNN` cid. Never edit a prior row.
+2. **NOW** — overwrite the cover's `<!-- BRAIN:NOW -->…` region with one present-tense sentence
+   (≤120 chars) + a link to what you touched. Replace, never append.
+3. **DIGEST** — overwrite `#brain-state` so `focus`, the newest worklog line, and `open` match.
+4. **DECISIONS** — if a call was made or a question opened/resolved, append a status-typed
+   `.entry` to `brain/decisions.html` (or flip ONE `data-status`). A reversal is a NEW entry with
+   `data-rel="supersedes:<id>"` — never rewrite the old one.
+5. **LEARNINGS** — if a gotcha bit, append one callout to `brain/learnings.html`.
+6. **PLAN** — flip the relevant task's `data-status` in `brain/project/index.html`. Progress is
+   DERIVED — never type a number. Append a task/initiative if the work was new.
+
+Keep it link-never-copy and respect the `.entry` grammar (data-cid→id, data-kind, data-status,
+data-date, ≥1 data-ref, optional data-lens). Then verify `#brain-state` still parses and the new
+links resolve, and commit.

package/skill/sandpaper/commands/sync.md

@@ -0,0 +1,17 @@
+---
+description: Reconcile the brain against the code — find and flag drift
+---
+
+Audit the brain against reality and report drift (the brain's periodic checkup):
+
+1. Read `#brain-state`, the plan board, and the component map.
+2. Check each claim against the code — the `git log`, the file structure, the actual source.
+   Flag: stale facts, components whose status changed, decisions overtaken by events, plan tasks
+   that are actually done/blocked, counts that no longer match, and any `data-ref` whose anchor no
+   longer exists (a dangling link).
+3. Present the drift as a concise list.
+4. With the owner's OK, fix it via the STAMP ops — flip statuses, append entries, **supersede**
+   stale decisions (a new entry with `data-rel="supersedes:<id>"`). Never silently rewrite history.
+
+This is the manual companion to the Stop hook: the hook prevents NEW drift; `/sync` heals existing
+drift.

package/skill/sandpaper/commands/theme.md

@@ -0,0 +1,12 @@
+---
+description: Re-skin the Sandpaper brain from a brand colour or preset
+argument-hint: "<a brand hex like #2E6F95, or \"preset: <name>\">"
+---
+
+Re-skin by editing ONLY `brain/assets/theme.css` (the single token file): $ARGUMENTS.
+
+Derive a coherent palette from the brand hex — a paper/ink base plus an accent and supporting
+hues (a green, an amber, a red) — keeping contrast and legibility (WCAG AA for text). Touch no
+other file: every brain surface reads its colour from `theme.css`, so one edit re-skins the whole
+manual. If the owner also wants the injected toolbar reskinned, keep its `#sp-panel` `--sp-*`
+mirror in `public/toolbar.css` in sync (it's deliberately host-independent).