@nynb/sandpaper 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Narayan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# Sandpaper
+
+A **living project brain** for Claude Code projects. Sandpaper scaffolds a small static
+site in `brain/` — a cover, three lenses (product / engineering / project), and three
+books (log, decisions, learnings) — and teaches your agent to keep it current. After every
+substantive turn, Claude *stamps* the brain: logs the work, refreshes the digest a fresh
+session reads to rehydrate, flips plan tasks, records decisions and gotchas. The brain is
+the **eyes** (state made visible); the terminal stays the **mouth** (steering). It never
+copies your docs — every entry **links** to the canonical anchor in your spec or source.
+
+No framework, no build step, no database. Plain HTML on disk, maintained by the agent,
+readable by you.
+
+## Quick start
+
+```bash
+# in your repo (npm package coming — GitHub install for now):
+npx github:codevalley/sandpaper install-skill
+```
+
+Then, inside Claude Code:
+
+```
+/sandpaper:init      # discovers your repo, asks a few questions, fills the brain
+```
+
+And to view it:
+
+```bash
+npx github:codevalley/sandpaper open      # serves the repo + opens brain/index.html
+```
+
+(An npm package is coming as `@nynb/sandpaper`, which will shorten these to `npx @nynb/sandpaper <cmd>`.)
+
+## What you get
+
+- **`brain/`** — a multi-page static site: a **cover** (`index.html`) with a
+  machine-readable `#brain-state` digest, a one-line NOW, and derived progress;
+  **lenses** (`product/`, `engineering/`, `project/` — the plan board); **books**
+  (`log.html`, `decisions.html`, `learnings.html`). One `assets/theme.css` re-skins
+  everything.
+- **The canvas** — a whiteboard on the cover. When Claude produces an explanation worth
+  keeping, it lands there as a readable board instead of scrolling past in the terminal
+  (last 5 kept, older ones fold away).
+- **The refine toolbar** — serve the brain (or any HTML doc) locally and get an on-page
+  overlay: **Sand** (a scoped AI edit of the element you click), **Hands** (direct edit,
+  no AI), **Sling** (copies a terminal-ready instruction for bigger work). The file on
+  disk stays the single source of truth; the page live-reloads from it.
+
+## The CLI (plumbing — no AI)
+
+| command | what it does |
+|---|---|
+| `sandpaper install-skill` | install the `/sandpaper:*` commands + hooks into this repo (also scaffolds `brain/`) |
+| `sandpaper init` | scaffold `brain/` — assets, `.sandpaper/manifest.json`, a starter multi-page skeleton |
+| `sandpaper upgrade` | bring an existing brain up to date (assets · hooks · commands · canvas), preserving your `theme.css` |
+| `sandpaper rebuild` | full reset — back up the old brain to `brain.bak-<date>/`, lay down a fresh skeleton |
+| `sandpaper doctor` | health-check a setup: assets, digest, links, source meta, manifest, hooks |
+| `sandpaper open` | serve this repo's brain + open it in a browser |
+| `sandpaper <doc.html \| dir>` | serve any doc or directory with the on-page refine toolbar |
+| `sandpaper help` | usage |
+
+Serves on `127.0.0.1:4848` by default (`$SANDPAPER_PORT` or the manifest's pinned `port`
+override it; the server auto-bumps if the port is taken). `install-skill --no-hooks`
+skips hook wiring and prints the settings snippet instead.
+
+## The commands (intelligence — inside Claude Code)
+
+`/sandpaper:help` lists them all.
+
+**Maintain the brain**
+
+- `/sandpaper:stamp` — the full update after a substantive turn (log · NOW · digest · decisions · learnings · plan)
+- `/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
+- `/sandpaper:canvas` — elevate an explanation into a board on the cover's canvas
+- `/sandpaper:sync` — reconcile the brain against the code; find and flag drift
+
+**Set up & run**
+
+- `/sandpaper:init` — discover the repo, run a short wizard, generate the brain
+- `/sandpaper:open` — start the server and open the brain
+- `/sandpaper:serve` — serve the brain (or any doc) with the refine toolbar
+- `/sandpaper:theme` — re-skin from a brand colour or preset
+
+## The auto-updating brain
+
+Two hooks keep the brain current without prodding. `install-skill` wires them into
+`.claude/settings.json` (merged, deduped, your existing settings preserved); pass
+`--no-hooks` to opt out, or remove the entries later to disable.
+
+- **SessionStart** (`brain-inject.js`) — surfaces the brain's digest so a fresh `claude`
+  rehydrates from project state automatically.
+- **Stop** (`brain-stamp-check.js`) — if a turn ends with uncommitted project changes but
+  nothing changed under `brain/`, it blocks once and asks the agent to stamp.
+  Self-limiting: it never loops, and the agent can decline by stopping again.
+
+## Publishing the brain
+
+`brain/` is always publishable — point GitHub Pages, Vercel, Netlify, or Cloudflare at
+the folder as-is; there is no build step. Links out of the brain (into your source and
+specs) are written relative, and each page carries a `sandpaper:source` meta (set
+automatically from your git origin); when the brain is served *away* from its repo, an
+on-page resolver detects it and rewrites out-links to your source host at click time
+instead of 404ing. See the deploy guide that ships inside every scaffolded brain:
+[`brain/README.md`](brain/README.md).
+
+## Conventions & requirements
+
+- **Node ≥ 18**, ESM, **zero runtime dependencies** — built-ins only.
+- The document on disk is the single source of truth; the page reflects disk, never ahead of it.
+- The brain **links, never copies** — roadmap, risks, and specs stay canonical in your docs.
+- The server binds to `127.0.0.1` only.
+
+## License
+
+MIT

package/bin/brain-inject.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Sandpaper SessionStart hook — surface the brain digest so a fresh `claude` rehydrates
+// from the brain FIRST, automatically (no "read the brain" prompt needed).
+// Zero deps; prints the digest to stdout, which Claude Code adds to the session context.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+try {
+  const html = readFileSync(join(process.cwd(), 'brain', 'index.html'), 'utf8');
+  const m = html.match(/<script type="application\/json" id="brain-state">([\s\S]*?)<\/script>/);
+  if (!m) process.exit(0);
+  const d = JSON.parse(m[1]);
+  const out = [
+    `🪵 Sandpaper brain · ${d.project} · ${d.phase} · session ${d.session} · stamped ${d.updated}`,
+    `NOW — ${d.focus?.one || ''}${d.focus?.ref ? ` (${d.focus.ref})` : ''}`,
+    `Recent: ${(d.worklog || []).map((w) => w.one).join(' · ')}`,
+    (d.open && d.open.length) ? `Needs you: ${d.open.join(', ')}` : '',
+    `Canvas (board-first) — when your reply would be a substantial summary or explanation (a recap, an architecture, a comparison, a walkthrough, an analysis), the BOARD IS THE REPLY: write the elevated version as the current board in brain/index.html's <!-- BRAIN:CANVAS --> region (the .whiteboard; demote the previous to Earlier, cap 5) and leave just ONE line in the terminal — "📋 <gist> → on the canvas". Don't write it twice. Short answers and back-and-forth stay in the terminal. See the CANVAS discipline in the skill; /sandpaper:canvas forces one.`,
+    `Read brain/index.html to navigate. Stamp the brain after substantive turns (CLAUDE.md → "The project brain").`,
+  ].filter(Boolean).join('\n');
+  process.stdout.write(out + '\n');
+} catch { /* no brain / unreadable — stay silent, never break the session */ }
+process.exit(0);

package/bin/brain-stamp-check.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Sandpaper Stop hook — the brain's immune system. When a turn changed project files but DID NOT
+// touch the brain, block once and tell the agent to stamp it. Automatic; no user prodding.
+//
+// Self-limiting (never loops):
+//   1. `stop_hook_active` in the hook payload → we're already in a continuation, so allow the stop.
+//   2. The check is idempotent — once the agent stamps (brain/ changes), it no longer fires.
+//   3. The agent can override ("this turn needs no brain update") by simply stopping again.
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8') || '{}'); } catch { /* no/!json stdin */ }
+if (input.stop_hook_active) process.exit(0); // guard #1: don't re-block a continuation
+
+let changed = [];
+try {
+  changed = execFileSync('git', ['status', '--porcelain'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+    .split('\n').filter(Boolean).map((l) => l.slice(3).trim());
+} catch { process.exit(0); } // not a git repo / git missing — stay silent
+
+const isProject = (f) => /\.(js|css|html|md|json)$/.test(f) && !f.startsWith('.sandpaper') && !f.includes('node_modules');
+const proj = changed.filter(isProject);
+const brainTouched = proj.some((f) => f.startsWith('brain/'));            // guard #2: stamped → won't fire
+const nonBrain = proj.filter((f) => !f.startsWith('brain/') && f !== 'CLAUDE.md');
+
+if (nonBrain.length && !brainTouched) {
+  const reason =
+    `🪵 The brain isn't stamped. This turn changed ${nonBrain.length} project file(s) ` +
+    `(${nonBrain.slice(0, 6).join(', ')}${nonBrain.length > 6 ? ', …' : ''}) but nothing under brain/. ` +
+    `Before finishing, STAMP the brain (CLAUDE.md → "The project brain"): prepend one log row, refresh the ` +
+    `cover NOW + #brain-state digest, flip any plan-board tasks, add a decision/learning if one applies — then commit. ` +
+    `If this turn genuinely warrants no brain update, just stop again.`;
+  process.stdout.write(JSON.stringify({ decision: 'block', reason }) + '\n');
+}
+process.exit(0);

package/bin/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Sandpaper CLI. Subcommands are the "plumbing" (no AI); a bare path falls through to `serve`.
+//   sandpaper install-skill | init | doctor | open | help | <doc.html|dir>
+import { resolve, dirname, join } from 'node:path';
+import { existsSync, statSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { execFile } from 'node:child_process';
+import { startServer } from '../src/server.js';
+import { installSkill, scaffold, doctor, upgrade, rebuild } from '../src/setup.js';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const [cmd, ...rest] = process.argv.slice(2);
+
+// Starting port: $SANDPAPER_PORT wins, else the repo's pinned .sandpaper/manifest.json "port",
+// else 4848. The server auto-bumps from here if it's taken, so multiple repos never collide.
+const startPort = () => {
+  if (process.env.SANDPAPER_PORT) return Number(process.env.SANDPAPER_PORT);
+  try { const m = JSON.parse(readFileSync(join(process.cwd(), '.sandpaper', 'manifest.json'), 'utf8')); if (m.port) return Number(m.port); } catch {}
+  return 4848;
+};
+const port = startPort();
+
+const usage = () => console.log(`
+  🪵  sandpaper — a living project brain
+
+  sandpaper install-skill      install the /sandpaper commands + hooks into this repo
+  sandpaper init               scaffold brain/ (assets + manifest + a starter cover)
+  sandpaper upgrade            bring an existing brain up to date (assets · hooks · commands · canvas)
+  sandpaper rebuild            full reset — back up the old brain + lay down a fresh skeleton
+  sandpaper doctor             health-check a Sandpaper setup
+  sandpaper open               serve this repo's brain + open it in a browser
+  sandpaper <doc.html | dir>   serve with the on-page refine toolbar
+  sandpaper help               this
+
+  Fresh repo? → sandpaper install-skill, then /sandpaper:init in Claude Code.
+`);
+
+const serve = async (target, openBrowser) => {
+  const isDir = statSync(target).isDirectory();
+  const url = await startServer(target, port, { brain: isDir });
+  console.log(`\n  🪵  Sandpaper\n  ↳ ${isDir ? 'serving' : 'editing'}  ${target}\n  ↳ open     ${url}\n`);
+  if (openBrowser) {
+    const u = isDir && existsSync(join(target, 'brain', 'index.html')) ? url + 'brain/index.html' : url;
+    const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    execFile(opener, [u], () => {}); // best-effort; ignore failures
+  }
+};
+
+(async () => {
+  try {
+    if (!cmd || cmd === 'help' || cmd === '-h' || cmd === '--help') return usage();
+    if (cmd === 'install-skill') return installSkill(process.cwd(), PKG, { noHooks: rest.includes('--no-hooks') });
+    if (cmd === 'init') return scaffold(process.cwd(), PKG);
+    if (cmd === 'upgrade' || cmd === 'update') return upgrade(process.cwd(), PKG);
+    if (cmd === 'rebuild' || cmd === 'reset') return rebuild(process.cwd(), PKG);
+    if (cmd === 'doctor') return doctor(process.cwd());
+    if (cmd === 'open') return serve(process.cwd(), true);
+    const target = resolve(process.cwd(), cmd);
+    if (!existsSync(target)) { console.error(`\n  sandpaper: unknown command or path: ${cmd}`); usage(); process.exit(1); }
+    return serve(target, false);
+  } catch (e) { console.error('  sandpaper:', e.message); process.exit(1); }
+})();

package/brain/README.md

@@ -0,0 +1,99 @@
+# Deploying the brain
+
+## What this folder is
+
+This folder is Sandpaper's own living brain: a small static site the terminal agent stamps
+after each substantive turn (see `../CLAUDE.md` → "The project brain").
+
+- `index.html` — the cover: NOW, the canvas (boards), digest, recent log, browse.
+- `log.html` — append-only work log (the heartbeat).
+- `decisions.html` — decisions + open questions (the why).
+- `map.html` — components, architecture (linked), glossary.
+- `learnings.html` — gotchas & verdicts.
+- `product/` · `engineering/` · `project/` — the lenses; `wiki/` — the settled prose docs.
+
+Styled by `assets/theme.css` + `assets/brain.css`, with a little vanilla JS in
+`assets/brain.js`. No framework, no build step, no server-side anything. It is
+**always publishable**: point any static host at this folder as-is and it works.
+
+One design choice shapes everything below: the brain **links, never copies**. Canonical
+truth lives in the parent repo — the spec docs (`../sandpaper.html`, `../engg-spec.html`),
+source files, `package.json` — and the brain references them with relative paths (`../…`)
+so they resolve on disk and whenever the whole repo is served.
+
+## Two deploy shapes
+
+### 1. Whole-repo deploy (recommended for public repos)
+
+Serve the repo root and visit `/brain/`. Every out-of-brain link resolves: spec HTML docs
+render with working `#anchors`, source files are viewable. GitHub Pages serving the repo
+root does this perfectly.
+
+### 2. Brain-only deploy (site root = this folder)
+
+The relative `../` refs can't resolve — there's nothing above the root. The built-in
+resolver in `assets/brain.js` handles it. Each page's head carries:
+
+```html
+<meta name="sandpaper:source" content="https://github.com/codevalley/sandpaper/blob/HEAD/" data-pkg="sandpaper" />
+```
+
+On load, the page probes `../package.json` and checks its `name` against `data-pkg`.
+If the probe fails (or the name doesn't match), the page knows it is detached, and
+out-links open the source-host copy instead (rewritten at click time). Source and meta
+files render fine on GitHub's blob view; spec **HTML** docs land on blob *source* view —
+unrendered. Use the whole-repo shape if you want rendered specs. With no meta configured,
+out-links dim with a tooltip instead of 404ing.
+
+The meta is written automatically by `npx sandpaper init` / `upgrade` from the git origin
+(or `package.json` → `"repository"`). `npx sandpaper doctor` verifies it is present and
+consistent across pages.
+
+## Deployed brains are read-only
+
+The refine toolbar (Sand / Hands / Sling) is injected only by the local `sandpaper`
+server — a deployed brain has no toolbar and can't be edited from the page. By design:
+the public copy is for reading.
+
+## Recipes
+
+**GitHub Pages (simplest)** — Settings → Pages → Source: *Deploy from a branch*, branch
+`main`, folder `/ (root)`. That's the whole-repo shape — visit
+`https://<owner>.github.io/<repo>/brain/`. For the brain-only shape, use Source:
+*GitHub Actions* with this workflow:
+
+```yaml
+name: Deploy brain
+on: { push: { branches: [main] } }
+permissions: { contents: read, pages: write, id-token: write }
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: { name: github-pages, url: "${{ steps.deployment.outputs.page_url }}" }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/upload-pages-artifact@v3
+        with: { path: brain }          # 'path: .' switches to the whole-repo shape
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+**Vercel** — New Project → import the repo. Root Directory = repo root (or `brain/` for
+brain-only), Framework Preset = *Other*, no build command, Output Directory = `./`.
+
+**Netlify** — New site from Git. No build command. Publish directory: `brain` (or the
+repo root).
+
+**Cloudflare Pages** — Connect the repo. No build command. Build output directory:
+`brain` (or `/`).
+
+## Privacy
+
+Deploying the whole repo publishes **all** of its files, not just the brain. Brain-only
+publishes just this folder — but its out-links point at the source host, which must be
+public for them to work. Either way, assume everything the brain links to is visible.
+Don't deploy a brain whose repo isn't ready to be read.
+
+Remember what the brain *is*: distilled internal state. The canvas boards are derived
+from working conversations, and the log/decisions/learnings record real reasoning —
+read them with publishing eyes before pointing a host at this folder.