sloptimize 0.3.0

package/docs/USAGE.md

@@ -0,0 +1,227 @@
+# Using sloptimize day to day
+
+INTEGRATION.md is for wiring a game once. This is the manual for everyone
+AFTER that: the operator who plays, and the Claude Code sessions that read.
+Everything here was verified live against the reference deployment
+(mecharoyale) — the multi-session semantics by running the actual hook
+binary from parallel directories.
+
+## The mental model (one sentence)
+
+The game never talks to a Claude session: it posts to **its own server**,
+the server writes files into `<server cwd>/.sloptimize/`, and every Claude
+session **reads those files** — a broadcast over the filesystem, not a
+channel to anyone.
+
+```
+game tab ──POST──► game server ──writes──► .sloptimize/{profile.json, perf.jsonl, census.json}
+                                               ▲            ▲            ▲
+                                        session A      session B      session C
+                                        (reads at its next prompt, independently)
+```
+
+## A normal day
+
+1. **Start the game server with its dev switch** (reference deployment:
+   `ALLOW_DEBUG_SPAWN=1` or `SLOPTIMIZE_INGEST=1`; the standalone launcher
+   sets the latter by default). Without it the ingest endpoint does not
+   exist and every tab stays inert — by design, that is what production
+   looks like.
+2. **Open the game and just play.** The in-page runtime arms itself:
+   instantly on localhost or `?sloptimize`, otherwise by probing the ingest
+   endpoint (204 arms; the probe retries on a backoff, so a server that
+   comes up late still lights the recorder without a refresh). Your
+   confirmation is the **PERF chip** (bottom-left, dev sessions only):
+   - `◉ PERF` — armed, feed flowing.
+   - `◌ PERF DARK` — armed but the server refused/vanished; recording
+     continues, posts buffer and retry. Hover the chip for the reason.
+3. **When something feels wrong, press Ctrl+F12** (or click the chip).
+   The trailing 5 seconds freeze **at the press** — typing the note cannot
+   shift the window. Then:
+   - type one line ("huge stutter when the buildings loaded") + Enter →
+     keyframe + note land in the ledger;
+   - Esc or just closing → you were only looking; nothing is minted.
+   The debugger has three tabs (← → switch them):
+   - **Session** — this tab's incident list; every row already reached the
+     ledger when it happened.
+   - **Timeline** — the deployment's history: frame p95, draw calls and
+     hitch spikes on one time axis, build boundaries dashed, and a
+     "now vs first build" line. Hover a bucket for its numbers. A gap is
+     "nothing measured then", never zero; a caret is a spike past the
+     strip's ceiling (hover reads the real value).
+   - **Fixes** — what sloptimize + Claude Code changed and what it bought:
+     one card per recorded fix — date, commit, was → now, and the measured
+     before/after (p95, draw calls, hitches/h, worst frame) sparklined.
+4. **Go to a Claude Code session and type anything.** The evidence arrives
+   attached to that prompt. That's the whole handoff.
+
+## A new Claude Code session: zero setup
+
+Any session started in a repo with the prompt hook installed (README
+"Claude Code integration") is integrated from its first prompt. The hook
+runs `sloptimize hook-status` on every prompt-submit and prints at most 5
+lines, only when something is NEW:
+
+- `★ NEW perf keyframe (f12: <your note>) …` — a usermark, with the worst
+  frame's classification and evidence inline.
+- `⚠ budget breach (<regime>): perf.budget.… n/limit` — a budget crossed
+  an edge (said once per distinct breach signature, re-said if it clears
+  and returns).
+- `◌ feed quiet Nmin …` — the ledger went stale (>45min). Heartbeats keep
+  it fresh once a minute while a session is armed, so quiet MEANS the feed
+  is dark or the play session ended — never merely "idle".
+
+Silence means nothing new — the hook exits 0 with no output.
+
+The watcher (below) adds the live lines. Reading one:
+
+```
+sloptimize ↯ jitter unit snap 17.542 (jump [-16.25, 5.552, 3.584], expected 1.363 of travel
+  at 33.25/s in a 41ms frame) @ … → snap (17.542m off its trajectory …; motion resumed from
+  the new place) phase=play ctx=combat=yes,hull=droyd-g,squad=duo,stance=helm,view=tps
+  build=v178… fp=b5b203ba ×2 [.sloptimize]
+```
+
+`↯` is a coordinate jump: which track (the unit or the camera), how far off
+its own trajectory it landed, what constant velocity predicted for that
+frame, and the verdict — `snap` (one displacement, motion resumed),
+`oscillation` (frame-to-frame reversals), `follows-track` (the camera rode
+along with the unit; that record is the cause), `reach-change` (the camera
+boom clamped or zoomed), `long-frame-catch-up` (the stall it rode is the
+incident — silent on the watcher, listed in the ledger). `ctx=` is the
+game's situation when it happened; `fp=` is the cause's id and `×N` how
+often this ledger has seen it — `sloptimize issues --fp <id>` is its history
+and the fixes already applied.
+
+## Several sessions at once: who gets told?
+
+**All of them, once each.** Dedup state is **per working directory**
+(`.sloptimize/.hook-state.json` in the session's own cwd, keyed by watched
+dir), not global. Three sessions in three worktrees each surface the same
+new keyframe at their own next prompt, then never again.
+
+Consequences worth knowing:
+
+- **You pick the acting session by typing into it.** The game cannot
+  address a session and the F12 box cannot target one. Work the incident
+  wherever you type; the other sessions merely mention it once.
+- **Delivery is pull, not push.** A session you never prompt never hears
+  anything, no matter how many freezes land in the ledger.
+- **Same-directory sessions race.** Two sessions sharing one cwd share one
+  `.hook-state.json`; whichever prompts first consumes the "new" flag and
+  the other never sees that record. One session per directory (worktrees
+  make this automatic).
+- **Scope follows the `--dir` flags.** The reference hook watches the
+  session's own `./.sloptimize` **plus** the main deployment's directory.
+  So a worktree's private dev server is seen only by that worktree's
+  session; the shared deployment is seen by everyone.
+
+## Do I need a dedicated monitor session?
+
+**No** for the normal loop above — the hook makes every session ambient.
+
+**Yes, one, if you want unprompted reaction** (or none, if the
+`SessionStart` hook arms the watcher for you) — an agent that starts
+investigating while you keep playing and never type. Two recipes:
+
+- **`sloptimize watch` as a Monitor** (INTEGRATION.md §5): the shipped
+  watcher polls `perf.jsonl` with a byte cursor (~20s) and wakes the
+  agent with one line per new usermark, ≥100ms hitch, gpu cap-hit, coordinate jitter or
+  feed-dark edge. A `SessionStart` hook can arm it in every session
+  automatically — then nobody types anything, ever.
+- **`/loop` in one session**: e.g.
+  `/loop check <game>/.sloptimize for new keyframes or budget breaches; investigate any new incident`
+  — that session self-paces polls and works incidents autonomously.
+
+Either coexists with the ambient hook in the other sessions; dedup state
+is per directory, so the watcher consuming its own view hides nothing from
+anyone else.
+
+## The Issues tab: what keeps happening, and what was done about it
+
+Every incident carries a **footprint** — the identity of its cause (kind,
+phase, verdict, site, and the game's own situation: which machine, at the
+helm or on foot, squad size, in combat), never the time it happened. The
+debugger's **Issues** tab groups the whole ledger by footprint: one row per
+cause, `×N` occurrences, `last 3h ago`, the situation as chips. Click a row
+for its history: first and last seen, builds, worst, the last verdict, and
+every fix a session recorded against it (`sloptimize fix propose
+--footprints <id> …`). The same catalogue is `sloptimize issues` in a
+shell, and every watcher wake line ends with `fp=<id> ×N` so an agent knows
+on arrival whether it is looking at something new or the seventh time.
+
+## Reading on demand (any session, any shell)
+
+```bash
+npx sloptimize report --dir <game>/.sloptimize   # profile + incidents
+npx sloptimize check  --dir <game>/.sloptimize   # budgets → exit 0/1/4
+npx sloptimize census --dir <game>/.sloptimize   # per-entity costs
+npx sloptimize history --dir <game>/.sloptimize  # p95/calls/hitches over time, per build + fixes
+npx sloptimize doctor --dir <game>/.sloptimize   # what is wired/degraded
+```
+
+## Recording a fix (the agent's last step)
+
+Once a fix is verified — the new build is live and the ledger has evidence
+from it — the session records it:
+
+```bash
+npx sloptimize fix --dir <game>/.sloptimize \
+  --title "Launch: pipelines pre-warmed behind the reveal cover" \
+  --issue "programs +4 mid-launch, 1.4s freeze on first draw" \
+  --solution "compile the launch material set inside the hangar settle gate" \
+  --commit $(git rev-parse --short HEAD)
+```
+
+The before/after are **measured**: by default the previous build's window
+vs the latest build's (a fix ships as a build), or name them —
+`--before v1787863993876 --after v1787881270783`, or a range
+`--before 2026-08-27T20:00Z..2026-08-27T22:00Z`. The record lands in
+`fixes.jsonl`; the Fixes tab and `sloptimize history` read it back. From
+Claude Code the same verb is the MCP tool `record_fix`.
+
+Rules that keep the numbers honest (the doctrine skill enforces them):
+counters (calls/triangles/programs) compare exactly on any renderer;
+timing counts only in `regime: hardware`; an absent field means
+unmeasured, never zero; `long-script` escalates to a CPU profiler —
+sloptimize answers *which frame, which entity, which workload*, not
+*which function* (unless the attach tier's sampler is running).
+
+The armed page also exposes a console surface: `__sloptimize.mark(note)`,
+`.census()`, `.summary()`, `.feed()` (transport state), `.gpu()`
+(WebGPU-wrapper stats), `.mints()` / `.remint()` (pipeline-mint
+attribution).
+
+## When it seems dead
+
+- **Chip says DARK / hook says feed quiet**: the usual cause is the game
+  server restarted **without its dev switch** — the ingest 404s exactly
+  like production. Restore the switch; the client re-probes every 5
+  minutes and flushes what it buffered. No refresh needed.
+- **No chip at all**: the tab never armed — not localhost, no
+  `?sloptimize`, and the arm probe never got its 204. Same fix.
+- **`no census.json`**: nobody has walked the scene yet — run
+  `__sloptimize.census()` in the game tab.
+- **Ctrl+F12 does nothing**: click the chip instead (keyboard geography
+  is why it exists); failures log `[sloptimize]` lines to the console
+  rather than dying silently.
+
+## The fix loop (git only)
+
+A fix is a PROPOSAL: a `sloptimize/<slug>` branch and one entry in
+`.sloptimize/fixes.jsonl`. No forge, no API, no token — a repo with no remote
+works the same; with a remote the branch and `main` are pushed.
+
+```bash
+sloptimize fix propose --title "…" --issue "…" --solution "…"   # branch + commit + ledger entry
+sloptimize fixes                       # every proposal, status as git sees it
+sloptimize fix merge <id>              # merge commit into main (+ push); refuses a stale branch
+sloptimize fix reject <id>             # delete the branch, keep the entry
+sloptimize policy                      # automation: propose | merge
+sloptimize settings --automation merge
+```
+
+The debugger's **Fixes** tab lists proposals with Merge / Reject and a badge
+counting the ones you have not looked at; **Settings** holds the automation
+level (server-side, `.sloptimize/settings.json`). A project that is not a
+git repo is told so in both places.

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/sloptimize.mjs hook-status --dir .sloptimize 2>/dev/null || true",
+            "timeout": 10,
+            "statusMessage": "sloptimize perf check"
+          }
+        ]
+      }
+    ]
+  }
+}

package/mcp/server.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// ============================================================
+// mcp/server.mjs — the plugin's live tier (SPEC §8.1 tier 4, M-A2)
+// ============================================================
+// A dependency-free stdio MCP server (JSON-RPC 2.0, newline-delimited),
+// exposing the agent-facing verbs against the CURRENT PROJECT's
+// .sloptimize/ plus tier-0 attach. Files stay the primary interface —
+// these tools are the same reads, typed; attach_start is the one verb a
+// plain file read cannot do.
+//
+// Push: incident→wakeup stays with the session Monitor / prompt hook for
+// now — MCP notifications exist in the protocol, but a server-initiated
+// wake is not a contract this host documents; when it becomes one, the
+// watcher moves here (SPEC-attach §2, delivery edge).
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+
+const DIR = () => join(process.cwd(), '.sloptimize');
+let attachSession = null;
+
+const TOOLS = [
+  { name: 'get_report', description: 'Current profile, recent incidents (classified, clustered), and census hints from the project’s .sloptimize/ directory.',
+    inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'max incident records (default 20)' } } } },
+  { name: 'check_budgets', description: 'Check the measured profile against .sloptimize/budgets.json. Returns per-budget verdicts; "fast enough" as data.',
+    inputSchema: { type: 'object', properties: {} } },
+  { name: 'get_history', description: 'The deployment’s timeline folded from perf.jsonl: time buckets (frame p95, draw calls, hitch spikes, build), one measured window per build, and the fix ledger (fixes.jsonl) — the before/after evidence behind every recorded fix.',
+    inputSchema: { type: 'object', properties: { buckets: { type: 'number', description: 'time slices (default 24)' } } } },
+  { name: 'get_issues', description: 'The issue catalogue (SPEC §3.7): every incident type on the ledger grouped by FOOTPRINT — the identity of a cause (type, phase, verdict, site, the game’s situation), never its time — with occurrences, first/last seen, builds, worst, the last verdict, and the fixes applied to it. Read this before proposing a fix: an issue with a fix already recorded is not new.',
+    inputSchema: { type: 'object', properties: { fp: { type: 'string', description: 'one footprint id' }, from: { type: 'string', description: 'ISO lower bound' }, to: { type: 'string', description: 'ISO upper bound' }, includeAutomated: { type: 'boolean', description: 'count robots’ sessions too (default false)' }, limit: { type: 'number', description: 'max rows (default 50)' } } } },
+  { name: 'record_fix', description: 'Append a fix report to .sloptimize/fixes.jsonl: title, issue, solution, commit, the FOOTPRINTS it addresses (from get_issues — this is how the Issues tab shows which fixes were applied to an issue), and MEASURED before/after windows of the ledger (default: the previous build vs the latest build with evidence; or name a build / an <ISO>..<ISO> range). Call this after verifying a perf fix — never with numbers of your own.',
+    inputSchema: { type: 'object', properties: { title: { type: 'string' }, issue: { type: 'string' }, solution: { type: 'string' }, commit: { type: 'string' },
+      files: { type: 'array', items: { type: 'string' } }, footprints: { type: 'array', items: { type: 'string' }, description: 'footprint ids this fix addresses' },
+      before: { type: 'string' }, after: { type: 'string' } }, required: ['title'] } },
+  { name: 'attach_start', description: 'Tier-0 attach: launch a Chromium at a URL with the injected recorder + rolling profiler (zero game integration). Records land in .sloptimize/ and incidents are clustered with file:line attribution.',
+    inputSchema: { type: 'object', properties: { url: { type: 'string' }, headless: { type: 'boolean' }, port: { type: 'number' } }, required: ['url'] } },
+  { name: 'attach_stop', description: 'Stop the running attach session and report its cluster summary.',
+    inputSchema: { type: 'object', properties: {} } },
+];
+
+function readJson(name) { try { return JSON.parse(readFileSync(join(DIR(), name), 'utf8')); } catch { return null; } }
+function readJsonl(name, limit) {
+  try {
+    return readFileSync(join(DIR(), name), 'utf8').trim().split('\n').filter(Boolean)
+      .slice(-limit).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  } catch { return []; }
+}
+
+async function callTool(name, args = {}) {
+  if (name === 'get_report') {
+    return { profile: readJson('profile.json'), incidents: readJsonl('perf.jsonl', args.limit ?? 20),
+      clusters: readJson('clusters.json'), census: readJson('census.json'),
+      note: existsSync(DIR()) ? undefined : 'no .sloptimize/ in this project — run the game with the tier-1 feed, or attach_start' };
+  }
+  if (name === 'check_budgets') {
+    const profile = readJson('profile.json');
+    const budgets = readJson('budgets.json');
+    if (!profile) return { error: 'no measurement to check' };
+    if (!budgets) return { warning: 'no budgets declared (.sloptimize/budgets.json)', breached: [] };
+    const countersOnly = profile.regime !== 'hardware';
+    const read = { 'perf.budget.draw_calls': profile.render?.calls, 'perf.budget.triangles': profile.render?.triangles,
+      'perf.budget.frame_ms_p95': countersOnly ? undefined : profile.frame?.p95Ms, 'perf.budget.programs': profile.memory?.programs };
+    const results = Object.entries(budgets).map(([k, b]) => ({ budget: k, value: read[k] ?? null, limit: b,
+      verdict: read[k] === undefined ? 'unmeasured' : read[k] > b ? `over by ${(read[k] / b).toFixed(1)}x` : 'inside' }));
+    return { regime: profile.regime, results, breached: results.filter((r) => String(r.verdict).startsWith('over')).length };
+  }
+  if (name === 'get_history') {
+    const { buildHistory } = await import('../src/history.js');
+    return buildHistory(readJsonl('perf.jsonl', Infinity), { fixes: readJsonl('fixes.jsonl', Infinity), buckets: args.buckets ?? 24 });
+  }
+  if (name === 'get_issues') {
+    const { buildIssues } = await import('../src/history.js');
+    const issues = buildIssues(readJsonl('perf.jsonl', Infinity), { fixes: readJsonl('fixes.jsonl', Infinity), from: args.from, to: args.to, includeAutomated: args.includeAutomated === true });
+    const rows = args.fp ? issues.filter((i) => i.id === args.fp) : issues.slice(0, args.limit ?? 50);
+    return { footprints: issues.length, occurrences: issues.reduce((n, i) => n + i.count, 0), issues: rows };
+  }
+  if (name === 'record_fix') {
+    const { buildFix } = await import('../src/history.js');
+    const { appendFileSync, mkdirSync } = await import('node:fs');
+    const fix = buildFix(readJsonl('perf.jsonl', Infinity), args);
+    mkdirSync(DIR(), { recursive: true });
+    appendFileSync(join(DIR(), 'fixes.jsonl'), JSON.stringify(fix) + '\n');
+    return { ok: true, fix };
+  }
+  if (name === 'attach_start') {
+    if (attachSession) return { error: 'an attach session is already running — attach_stop first' };
+    const { attach } = await import('../src/attach.mjs');
+    attachSession = await attach({ launch: args.url, headless: args.headless ?? true,
+      port: args.port ?? 9222, dir: DIR(), log: () => {} });
+    return { ok: true, note: 'recording into .sloptimize/ — read with get_report; new causes cluster in clusters.json' };
+  }
+  if (name === 'attach_stop') {
+    if (!attachSession) return { error: 'no attach session running' };
+    const clusters = [...attachSession.clusters.entries()].map(([k, v]) => ({ key: k, count: v.count }));
+    await attachSession.close();
+    attachSession = null;
+    return { ok: true, clusters };
+  }
+  throw new Error(`unknown tool ${name}`);
+}
+
+// ── JSON-RPC over stdio (newline-delimited; the SDK-free minimum) ──
+const rl = createInterface({ input: process.stdin });
+const reply = (id, result, error) => {
+  process.stdout.write(JSON.stringify(error ? { jsonrpc: '2.0', id, error } : { jsonrpc: '2.0', id, result }) + '\n');
+};
+rl.on('line', (line) => {
+  let msg;
+  try { msg = JSON.parse(line); } catch { return; }
+  void (async () => {
+    try {
+      if (msg.method === 'initialize') {
+        reply(msg.id, { protocolVersion: msg.params?.protocolVersion ?? '2024-11-05',
+          capabilities: { tools: {} }, serverInfo: { name: 'sloptimize', version: '0.3.0' } });
+      } else if (msg.method === 'tools/list') {
+        reply(msg.id, { tools: TOOLS });
+      } else if (msg.method === 'tools/call') {
+        const out = await callTool(msg.params.name, msg.params.arguments);
+        reply(msg.id, { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }] });
+      } else if (msg.id !== undefined) {
+        reply(msg.id, null, { code: -32601, message: `unknown method ${msg.method}` });
+      }
+    } catch (e) {
+      if (msg.id !== undefined) reply(msg.id, null, { code: -32000, message: String(e?.message ?? e) });
+    }
+  })();
+});

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "sloptimize",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "The agent-native profiler for three.js games: an always-on flight recorder, per-entity cost attribution, and a deterministic bench — so a coding agent can measure, attribute, and verify instead of guessing.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/m0dE/sloptimize.git"
+  },
+  "homepage": "https://github.com/m0dE/sloptimize#readme",
+  "bugs": {
+    "url": "https://github.com/m0dE/sloptimize/issues"
+  },
+  "bin": {
+    "sloptimize": "bin/sloptimize.mjs"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./history": "./src/history.js",
+    "./panel": "./src/panel.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "hooks",
+    "mcp",
+    "docs",
+    ".claude-plugin",
+    ".mcp.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@slopjs/inspector": ">=0.1.0",
+    "three": ">=0.150.0"
+  },
+  "peerDependenciesMeta": {
+    "@slopjs/inspector": {
+      "optional": true
+    },
+    "three": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node --test './test/**/*.test.js'",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "three.js",
+    "profiler",
+    "performance",
+    "claude-code",
+    "ai-agent",
+    "draw-calls",
+    "benchmark",
+    "slopjs"
+  ]
+}

package/skills/install/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: install
+description: Use when asked to install, integrate, or wire sloptimize into a game project — performs the tier-1 integration (in-page runtime, ingest sink, budgets, Claude hooks) and verifies the feed live before claiming success.
+---
+
+# Installing sloptimize into a game
+
+You are wiring the always-on tier (tier 1) into a real game repo. The
+reference deployment's mistakes are encoded below as MUST rules — do not
+rediscover them. `docs/INTEGRATION.md` in the sloptimize package is the
+narrative version; `docs/USAGE.md` is what the result behaves like.
+
+**The definition of done is a measured round-trip, not written code.** Do
+not report success until step 7 shows your test keyframe in
+`sloptimize report`.
+
+## 1. Locate the package and the game's shape
+
+- Find sloptimize: `node_modules/sloptimize` (npm) or a sibling checkout.
+- Identify: the render loop's stats site (wherever `renderer.info` is
+  already read), the dev-server topology (vite? own server? esbuild?), and
+  the dev-only switch the project already uses for debug endpoints.
+
+## 2. The in-page runtime
+
+Create a dev module (reference: mecharoyale's `dev/sloptimize-runtime.ts`)
+that:
+
+- `createRecorder({ budgetFrameMs: <the game's frame budget> })`.
+- **MUST give the recorder its own rAF clock** — a game-loop-fed clock is
+  blind to boot/menu/loading, exactly the windows that freeze. The game
+  loop only *enriches* counters; treat counters staler than ~250ms as
+  zeros.
+- `frameMs` MUST bound `insideRenderMs` (rAF-to-rAF delta, wall time
+  inside render).
+- Feed `paused: true` while the tab is hidden or unfocused (and for the
+  first frame after refocus) — throttled-tab gaps must never classify as
+  hitches.
+- Bind a keyframe chord (Ctrl+F12 recommended) AND a small clickable chip:
+  capture the trailing 5s FIRST, then open the package's debugger
+  (`createPanel` — Current Session · Issues · Optimizations · Settings + the
+  note box) and post the keyframe only if a note comes back. The incident
+  rows you hand it carry `fp` (the footprint id) and, for rows that are not
+  milliseconds, `label`/`glyph`.
+- Stamp `build`, `phase`, `automated` (navigator.webdriver), `ctx` and
+  `footprint` (`footprintOf(record)`) on every posted record — the writer
+  names the cause; every reader agrees without re-deriving.
+
+### 2b. The jitter detector (the second incident type)
+
+Read `docs/JITTER-AND-FOOTPRINTS.md` §1–2, then:
+
+- `createMotionMonitor({ unit, longFrameMs: <the sim's dt clamp, ms>,
+  tracks: { unit: { floor }, camera: { floor, reach: 'boom', follows: 'unit' } } })`.
+  `longFrameMs` MUST be the game's real clamp, found in its loop — never a
+  guess; the floor is the smallest pop a player can see in the game's units.
+- Feed once per RENDERED frame, after the render (transient shakes must not
+  be sampled): the `unit` track is the point the view is arranged around
+  (the pivot — rotation-invariant), NEVER the raw camera; the `camera` track
+  is the eye, HELD on any frame that consumed look/zoom input, with `reach`
+  = its distance to the pivot.
+- Hold both tracks while paused/unfocused and in phases without a
+  continuous view (boot, a cinematic that cuts). Derive a view-configuration
+  key (pivot publisher · camera mode · spectate target) and `cut()` when it
+  changes — never enumerate call sites.
+- Drain beside the recorder into the same post.
+
+### 2c. The situation and footprints
+
+Read `docs/JITTER-AND-FOOTPRINTS.md` §3–4, then:
+
+- Write a `context()` returning ≤6 LOW-CARDINALITY facets of the player's
+  situation (the reference: stance, hull, squad, view, combat) — categories,
+  never positions or counters. Refresh `canonicalContext(context())` once a
+  second; pass the string as `ctx` to `frame()`, `usermark()` and every
+  motion `sample()`.
+- At post, for every record: `r.ctx ??= ctx; const fp = footprintOf(r); if (fp) r.footprint = fp;`.
+- Post a `{type:'heartbeat', medianFrameMs, p95Ms, calls, triangles,
+  programs}` ledger line once a minute while armed — the counters are the
+  Timeline's draw-call history.
+
+## 3. Activation — MUST NOT gate on hostname
+
+Probe the ingest endpoint at boot: 204 arms, anything else stays inert,
+and the probe retries on a backoff (5s/30s/2min, then 5min). A dev preview
+behind a proxy looks like production to a hostname test; only the server
+knows what it is.
+
+## 4. The sink
+
+- Vite host: the vite plugin surface (when present), else the same
+  endpoint as below in the dev server.
+- Any other host: one dev-only `POST /api/sloptimize/ingest` accepting
+  `{kind: 'profile'|'records'|'census', payload}` → writes
+  `.sloptimize/profile.json`, appends `perf.jsonl`, writes `census.json`.
+  Refuse with a plain 404 when the dev switch is off — identical to an
+  unknown route. Beside it, one dev-gated `GET /api/sloptimize/ledger` →
+  `{perf, fixes}` (the ~2MB tail of `perf.jsonl` + all of `fixes.jsonl`,
+  raw JSONL) for the debugger's history tabs. Prefer arming by topology (the presence of
+  `.sloptimize/budgets.json` in the server cwd) with env overrides, over
+  a bare env flag someone must remember.
+- **MUST NOT die silently**: once armed, a refused or failed post flips
+  the feed DARK — buffer (bounded, count drops), retry on the backoff,
+  and SHOW the state on the chip. The first deployment lost an hour of
+  real freezes to "first 404 disables posting".
+
+## 5. Budgets and gitignore
+
+- Write `.sloptimize/budgets.json` with the game's real limits, e.g.
+  `{"perf.budget.frame_ms_p95": 16.7, "perf.budget.draw_calls": 400}`.
+- Gitignore `.sloptimize/*` **except** `budgets.json`.
+
+## 6. The Claude Code session surface
+
+- If installed as a plugin, the prompt hook ships already. Otherwise add
+  the `UserPromptSubmit` hook to the game's `.claude/settings.json`:
+  `npx sloptimize hook-status --dir .sloptimize` (add a second `--dir`
+  for a shared deployment directory if one exists).
+- Copy the doctrine skill into `.claude/skills/sloptimize/` when not
+  running as a plugin.
+
+## 7. Verify — the gate
+
+1. Start the game server in its dev topology; open the game.
+2. Confirm the chip reads armed (`◉`), or `__sloptimize.feed()` says ok.
+3. Fire a synthetic keyframe: `__sloptimize.mark('install-test')` in the
+   console (or the chord).
+4. Run `npx sloptimize report --dir <game>/.sloptimize` and confirm the
+   `install-test` usermark is in it — with a `footprint` and a `ctx` on the
+   ledger line.
+5. Run `npx sloptimize check` and report the budget verdict.
+6. Jitter: `__sloptimize.motion()` (or your equivalent) shows both tracks
+   sampling with `held` counting up on look input; force one jump of the
+   unit (move the body/hull by a metre in one frame from the console) and
+   confirm a `jitter` record with `kind: 'snap'` and the right `units` lands
+   — and that a camera flick, a mode flip and a respawn land NOTHING.
+7. `npx sloptimize issues --dir <game>/.sloptimize` lists the footprints
+   seen so far, the `install-test` keyframe among them.
+
+Only after 4 succeeds may you tell the user the install is complete —
+report what was wired, the verify evidence, and the one daily obligation
+that remains (start the server in its dev topology; everything else is
+automatic).

package/skills/sloptimize/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: sloptimize
+description: Use when investigating or fixing rendering performance in a three.js game instrumented with sloptimize — reading .sloptimize/ evidence, classifying hitches, attributing cost, and verifying fixes by measurement.
+---
+
+# The sloptimize loop
+
+**Never claim a performance fix without a measured before/after.** A fix
+without one is a hypothesis.
+
+The playbook, in order:
+1. `sloptimize report --dir <game>/.sloptimize` — the current profile,
+   recorded hitches (each classified WITH evidence), usermarks (the human's
+   Ctrl+F11 "it felt wrong here" captures), and census hints.
+2. Classify before touching code: shader-compile / texture-upload /
+   spawn-burst / long-render / long-script / gc-or-upload-by-elimination.
+   The record's `evidence` string says why the guess exists.
+3. `sloptimize census` — per-entity meshes/triangles/materials/shadow
+   casters, plus the closed hint vocabulary (instancing-candidate,
+   material-dedup-candidate, oversized-texture, undisposed-suspect).
+4. ONE change at a time.
+5. Verify: counters (draw calls, triangles, programs) compare EXACTLY on any
+   renderer, including software rasterizers. Timing numbers only count in
+   `regime: hardware`; never quote a timing from a `software` regime.
+6. `sloptimize check` against `.sloptimize/budgets.json` — "fast enough" is
+   an exit code, and distance-to-budget is part of every verdict you report.
+7. Record the fix once the new build has ledger evidence:
+   `sloptimize fix --title "…" --issue "…" --solution "…" --commit <sha>`
+   (MCP: `record_fix`). The before/after are measured windows of the
+   ledger — previous build vs new build by default — never numbers you
+   type. `sloptimize history` and the debugger's Fixes tab show it; that is
+   how the human sees what the loop bought.
+
+The fix loop (git only): a verified fix is PROPOSED, never pushed to main —
+`sloptimize fix propose --title "…" --issue "…" --solution "…"` turns the
+working tree (or the current branch) into a `sloptimize/<slug>` branch plus
+a ledger entry the debugger's Fixes tab lists with merge/reject. Read
+`sloptimize policy` first: `propose` means stop there; `merge` means
+`sloptimize fix merge <id>` yourself once the tests are green. A repo
+without git says so — nothing to do until `git init`.
+
+↯ jitter records (SPEC §3.6) are the OTHER incident: the unit or the camera
+landed off its own trajectory — a `snap` (one displacement, motion resumed
+from the new place) or an `oscillation` (frame-to-frame reversals: a
+fixed-step sim drawn without interpolation, or two writers on one
+transform). This is a correctness incident, not a timing one — census and
+counters will not explain it. Read the record: `track`, `jump` per axis (a
+vertical-only jump is a step or a ground snap; horizontal is a correction
+or a teleport), `speed`, `dtMs`, `coincident`, `reach`. `reach-change` =
+the camera's boom clamped or zoomed; `follows-track` = the camera was a
+passenger — work the unit's record; `long-frame-catch-up` = the stall it
+rode is the incident (already woke as a hitch). Find the writer of that
+transform in that phase and fix the discontinuity at its source. Verify
+with `sloptimize history` (jitters/h before → after) and a played session
+— never by raising the floor.
+
+Every wake line ends with the record's FOOTPRINT — `fp=<id> ×N` (SPEC §3.7):
+the identity of the cause (kind · phase · verdict · site · the game's
+situation: hull, stance, squad, combat), and how many times this ledger has
+seen it. ×1 is new; ×40 is the same issue again — read
+`sloptimize issues --fp <id>` FIRST: its history, and every fix already
+applied to it (do not re-propose one). When you record a fix, name the
+footprints it addresses: `sloptimize fix propose --footprints <id>,<id> …`
+— that is how the Issues tab and the catalogue show "which fixes were
+applied", and how the before/after says whether yours landed.
+
+Push channel: if a `sloptimize watch` Monitor is armed in this session,
+its lines (★ usermark / ⚡ hitch / ⏳ gpu / ◌ feed quiet) arrive as
+notifications; each one starts this playbook unprompted at step 1.
+
+Trust rules: census estimates are estimates (the field names say so); an
+absent field means unmeasured, never zero; `long-script` hitches escalate to
+a CPU profiler (Chrome DevTools), per-draw GL state to Spector — sloptimize
+answers WHICH entity, WHICH frame, WHICH workload, only.