gm-copilot-cli 2.0.727 → 2.0.1063

package/skills/gm-jetbrains/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: gm-jetbrains
+description: AI-native software engineering via skill-driven orchestration on jetbrains; bootstraps plugkit for task execution and session isolation
+allowed-tools: Skill
+---
+
+# GM — jetbrains Platform
+
+AI-native software engineering orchestrated via skill chain: PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS.
+
+**Bootstrap pattern**: `bun x gm-plugkit@latest --daemon` downloads the correct platform binary, verifies SHA256, and starts the spool watcher daemon. Call once at session start; idempotent on subsequent calls. All execution routes through the file-spool: write to `.gm/exec-spool/in/<lang>/<N>.<ext>` or `in/<verb>/<N>.txt`, poll `out/<N>.json` for results.
+
+**Session-ID threading (no session-start hook)**: At skill invoke time, generate or detect SESSION_ID (env var `SESSION_ID` or `uuid()`). Pass `sessionId: "<id>"` in every rs-exec RPC body (spawn, tail, watch, etc.) and every spool-written task body. All task-scoped cleanup (deleteTask, getTask, appendOutput, killSessionTasks) requires matching sessionId. Absence is forbidden — hard reject by rs-exec handler.
+
+**Spool dispatch surface**: Write to `.gm/exec-spool/in/<lang>/<N>.<ext>` (languages: nodejs, python, bash, typescript, go, rust, c, cpp, java, deno) or `in/<verb>/<N>.txt` (verbs: codesearch, recall, memorize, wait, sleep, status, close, browser, runner, etc.). Watcher executes and streams `out/<N>.out` (stdout) + `out/<N>.err` (stderr) line-by-line, then `out/<N>.json` metadata (exitCode, durationMs, timedOut, startedAt, endedAt) at completion.
+
+**End-to-end skill chaining (skills-based platforms)**: When gm SKILL.md includes `end-to-end: true`, adapter detects signal and parses stdout for trailing JSON: `{"nextSkill": "...", "context": {...}, "phase": "..."}`. If nextSkill is non-null, invoke `Skill(skill="gm:<nextSkill>")` with context dict, repeat until null. This auto-chains 5 invocations into 1 user invocation.
+
+Every task returns complete: taskId, exitCode, durationMs, timedOut, stdout, stderr. Background tasks return immediately with task_id; continue with exec:tail, exec:watch, or exec:close.

package/skills/gm-kilo/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: gm-kilo
+description: AI-native software engineering via skill-driven orchestration on kilo; bootstraps plugkit for task execution and session isolation
+allowed-tools: Skill
+---
+
+# GM — kilo Platform
+
+AI-native software engineering orchestrated via skill chain: PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS.
+
+**Bootstrap pattern**: `bun x gm-plugkit@latest --daemon` downloads the correct platform binary, verifies SHA256, and starts the spool watcher daemon. Call once at session start; idempotent on subsequent calls. All execution routes through the file-spool: write to `.gm/exec-spool/in/<lang>/<N>.<ext>` or `in/<verb>/<N>.txt`, poll `out/<N>.json` for results.
+
+**Session-ID threading (no session-start hook)**: At skill invoke time, generate or detect SESSION_ID (env var `SESSION_ID` or `uuid()`). Pass `sessionId: "<id>"` in every rs-exec RPC body (spawn, tail, watch, etc.) and every spool-written task body. All task-scoped cleanup (deleteTask, getTask, appendOutput, killSessionTasks) requires matching sessionId. Absence is forbidden — hard reject by rs-exec handler.
+
+**Spool dispatch surface**: Write to `.gm/exec-spool/in/<lang>/<N>.<ext>` (languages: nodejs, python, bash, typescript, go, rust, c, cpp, java, deno) or `in/<verb>/<N>.txt` (verbs: codesearch, recall, memorize, wait, sleep, status, close, browser, runner, etc.). Watcher executes and streams `out/<N>.out` (stdout) + `out/<N>.err` (stderr) line-by-line, then `out/<N>.json` metadata (exitCode, durationMs, timedOut, startedAt, endedAt) at completion.
+
+**End-to-end skill chaining (skills-based platforms)**: When gm SKILL.md includes `end-to-end: true`, adapter detects signal and parses stdout for trailing JSON: `{"nextSkill": "...", "context": {...}, "phase": "..."}`. If nextSkill is non-null, invoke `Skill(skill="gm:<nextSkill>")` with context dict, repeat until null. This auto-chains 5 invocations into 1 user invocation.
+
+Every task returns complete: taskId, exitCode, durationMs, timedOut, stdout, stderr. Background tasks return immediately with task_id; continue with exec:tail, exec:watch, or exec:close.

package/skills/gm-oc/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: gm-oc
+description: AI-native software engineering via skill-driven orchestration on oc; bootstraps plugkit for task execution and session isolation
+allowed-tools: Skill
+---
+
+# GM — oc Platform
+
+AI-native software engineering orchestrated via skill chain: PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS.
+
+**Bootstrap pattern**: `bun x gm-plugkit@latest --daemon` downloads the correct platform binary, verifies SHA256, and starts the spool watcher daemon. Call once at session start; idempotent on subsequent calls. All execution routes through the file-spool: write to `.gm/exec-spool/in/<lang>/<N>.<ext>` or `in/<verb>/<N>.txt`, poll `out/<N>.json` for results.
+
+**Session-ID threading (no session-start hook)**: At skill invoke time, generate or detect SESSION_ID (env var `SESSION_ID` or `uuid()`). Pass `sessionId: "<id>"` in every rs-exec RPC body (spawn, tail, watch, etc.) and every spool-written task body. All task-scoped cleanup (deleteTask, getTask, appendOutput, killSessionTasks) requires matching sessionId. Absence is forbidden — hard reject by rs-exec handler.
+
+**Spool dispatch surface**: Write to `.gm/exec-spool/in/<lang>/<N>.<ext>` (languages: nodejs, python, bash, typescript, go, rust, c, cpp, java, deno) or `in/<verb>/<N>.txt` (verbs: codesearch, recall, memorize, wait, sleep, status, close, browser, runner, etc.). Watcher executes and streams `out/<N>.out` (stdout) + `out/<N>.err` (stderr) line-by-line, then `out/<N>.json` metadata (exitCode, durationMs, timedOut, startedAt, endedAt) at completion.
+
+**End-to-end skill chaining (skills-based platforms)**: When gm SKILL.md includes `end-to-end: true`, adapter detects signal and parses stdout for trailing JSON: `{"nextSkill": "...", "context": {...}, "phase": "..."}`. If nextSkill is non-null, invoke `Skill(skill="gm:<nextSkill>")` with context dict, repeat until null. This auto-chains 5 invocations into 1 user invocation.
+
+Every task returns complete: taskId, exitCode, durationMs, timedOut, stdout, stderr. Background tasks return immediately with task_id; continue with exec:tail, exec:watch, or exec:close.

package/skills/gm-vscode/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: gm-vscode
+description: AI-native software engineering via skill-driven orchestration on vscode; bootstraps plugkit for task execution and session isolation
+allowed-tools: Skill
+---
+
+# GM — vscode Platform
+
+AI-native software engineering orchestrated via skill chain: PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS.
+
+**Bootstrap pattern**: `bun x gm-plugkit@latest --daemon` downloads the correct platform binary, verifies SHA256, and starts the spool watcher daemon. Call once at session start; idempotent on subsequent calls. All execution routes through the file-spool: write to `.gm/exec-spool/in/<lang>/<N>.<ext>` or `in/<verb>/<N>.txt`, poll `out/<N>.json` for results.
+
+**Session-ID threading (no session-start hook)**: At skill invoke time, generate or detect SESSION_ID (env var `SESSION_ID` or `uuid()`). Pass `sessionId: "<id>"` in every rs-exec RPC body (spawn, tail, watch, etc.) and every spool-written task body. All task-scoped cleanup (deleteTask, getTask, appendOutput, killSessionTasks) requires matching sessionId. Absence is forbidden — hard reject by rs-exec handler.
+
+**Spool dispatch surface**: Write to `.gm/exec-spool/in/<lang>/<N>.<ext>` (languages: nodejs, python, bash, typescript, go, rust, c, cpp, java, deno) or `in/<verb>/<N>.txt` (verbs: codesearch, recall, memorize, wait, sleep, status, close, browser, runner, etc.). Watcher executes and streams `out/<N>.out` (stdout) + `out/<N>.err` (stderr) line-by-line, then `out/<N>.json` metadata (exitCode, durationMs, timedOut, startedAt, endedAt) at completion.
+
+**End-to-end skill chaining (skills-based platforms)**: When gm SKILL.md includes `end-to-end: true`, adapter detects signal and parses stdout for trailing JSON: `{"nextSkill": "...", "context": {...}, "phase": "..."}`. If nextSkill is non-null, invoke `Skill(skill="gm:<nextSkill>")` with context dict, repeat until null. This auto-chains 5 invocations into 1 user invocation.
+
+Every task returns complete: taskId, exitCode, durationMs, timedOut, stdout, stderr. Background tasks return immediately with task_id; continue with exec:tail, exec:watch, or exec:close.

package/skills/gm-zed/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: gm-zed
+description: AI-native software engineering via skill-driven orchestration on zed; bootstraps plugkit for task execution and session isolation
+allowed-tools: Skill
+---
+
+# GM — zed Platform
+
+AI-native software engineering orchestrated via skill chain: PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS.
+
+**Bootstrap pattern**: `bun x gm-plugkit@latest --daemon` downloads the correct platform binary, verifies SHA256, and starts the spool watcher daemon. Call once at session start; idempotent on subsequent calls. All execution routes through the file-spool: write to `.gm/exec-spool/in/<lang>/<N>.<ext>` or `in/<verb>/<N>.txt`, poll `out/<N>.json` for results.
+
+**Session-ID threading (no session-start hook)**: At skill invoke time, generate or detect SESSION_ID (env var `SESSION_ID` or `uuid()`). Pass `sessionId: "<id>"` in every rs-exec RPC body (spawn, tail, watch, etc.) and every spool-written task body. All task-scoped cleanup (deleteTask, getTask, appendOutput, killSessionTasks) requires matching sessionId. Absence is forbidden — hard reject by rs-exec handler.
+
+**Spool dispatch surface**: Write to `.gm/exec-spool/in/<lang>/<N>.<ext>` (languages: nodejs, python, bash, typescript, go, rust, c, cpp, java, deno) or `in/<verb>/<N>.txt` (verbs: codesearch, recall, memorize, wait, sleep, status, close, browser, runner, etc.). Watcher executes and streams `out/<N>.out` (stdout) + `out/<N>.err` (stderr) line-by-line, then `out/<N>.json` metadata (exitCode, durationMs, timedOut, startedAt, endedAt) at completion.
+
+**End-to-end skill chaining (skills-based platforms)**: When gm SKILL.md includes `end-to-end: true`, adapter detects signal and parses stdout for trailing JSON: `{"nextSkill": "...", "context": {...}, "phase": "..."}`. If nextSkill is non-null, invoke `Skill(skill="gm:<nextSkill>")` with context dict, repeat until null. This auto-chains 5 invocations into 1 user invocation.
+
+Every task returns complete: taskId, exitCode, durationMs, timedOut, stdout, stderr. Background tasks return immediately with task_id; continue with exec:tail, exec:watch, or exec:close.

package/skills/governance/SKILL.md

@@ -3,24 +3,25 @@ name: governance
 description: Governance reference invoked by PLAN/EXECUTE/EMIT/VERIFY. Separates route discovery (PLAN) from weak-prior handoff (EXECUTE) from earned-emission legitimacy (EMIT/VERIFY). Encodes 16-failure taxonomy, 4 state planes, ΔS/λ/ε/Coverage metrics, governance stress suite.
 ---
 
-# Governance — Route, Bridge, Legitimacy
+# Governance — Route, bridge, legitimacy
 
-Three roles, three failure surfaces:
-1. **Route discovery** — what family of fault? Owned by `planning`.
-2. **Weak-prior bridge** — plausibility ≠ authorization. Owned by `gm-execute`.
-3. **Legitimacy gate** — did this answer earn its strength? Owned by `gm-emit`/`gm-complete`.
+Three roles, three failure surfaces.
 
-## Five Refused Collapses
+1. Route discovery — what family of fault? Owned by `planning`.
+2. Weak-prior bridge — plausibility is not authorization. Owned by `gm-execute`.
+3. Legitimacy gate — did this answer earn its strength? Owned by `gm-emit` and `gm-complete`.
 
-1. Route → authorization ("plan looks good" → "code is right")
-2. Candidate → structural repair (local patch presented as architectural fix)
+## Five refused collapses
+
+1. Route → authorization ("plan looks good" treated as "code is right")
+2. Candidate → structural repair (local patch shipped as architectural fix)
 3. Hidden → public law (internal convenience shipped as contract)
-4. Cleanliness → legitimacy (compiles = evidence-supports)
+4. Cleanliness → legitimacy (compiles treated as evidence-supports)
 5. One strong route → universal closure (best answer treated as only answer)
 
-When in doubt: preserve ambiguity. Lawful downgrade beats forced closure.
+When in doubt, preserve ambiguity. Lawful downgrade beats forced closure.
 
-## 7 Route Families
+## 7 route families
 
 | Family | What breaks | Repair |
 |---|---|---|
@@ -32,7 +33,7 @@ When in doubt: preserve ambiguity. Lawful downgrade beats forced closure.
 | boundary | Interfaces, contracts, seams | Re-assert contract from one source |
 | representation | Data shape, schema, type | Make illegal states unrepresentable |
 
-## 16 Failure Modes
+## 16 failure modes
 
 | # | Name | Family |
 |---|---|---|
@@ -53,7 +54,7 @@ When in doubt: preserve ambiguity. Lawful downgrade beats forced closure.
 | 15 | Deployment deadlock | execution |
 | 16 | Pre-deploy collapse | execution |
 
-## 4 State Planes
+## 4 state planes
 
 | Plane | Owner | States | Implication |
 |---|---|---|---|
@@ -62,18 +63,18 @@ When in doubt: preserve ambiguity. Lawful downgrade beats forced closure.
 | repair_legality | gm-emit | unverified → local_candidate → structural | Local cannot ship as structural |
 | hidden_decision_posture | gm-complete | open → down_weighted → closed | Close only after CI green |
 
-## Quality Metrics
+## Quality metrics
 
 - **ΔS** — witnessed output equals expected. ΔS≠0 = still open.
-- **λ≥2** — two independent paths agree. λ=1 = still unknown.
+- **λ ≥ 2** — two independent paths agree. λ=1 = still unknown.
 - **ε** — adjacent invariants hold (types, tests, neighboring callers).
-- **Coverage≥0.70** — enough corpus inspected to rule out contradicting evidence.
+- **Coverage ≥ 0.70** — enough corpus inspected to rule out contradicting evidence.
 
-All four must pass before mutable flips UNKNOWN→KNOWN.
+All four pass before a mutable flips UNKNOWN → KNOWN.
 
-## Stress Suite (8 Cases)
+## Stress suite
 
-Run before declaring COMPLETE:
+Run before declaring COMPLETE.
 
 | # | Case | Failure if flunked |
 |---|---|---|
@@ -86,11 +87,11 @@ Run before declaring COMPLETE:
 | A1 | Authenticity eval partial signals | Surface appearance beats evidence |
 | D1 | Deploy-gate under CI flake | Treats noise as green |
 
-Legal: illegal_commitment=0, evidence_boundary_violation=0, lawful_downgrade=available in all 8, outlier_visibility=preserved.
+Legal: `illegal_commitment=0`, `evidence_boundary_violation=0`, `lawful_downgrade=available` in all 8, `outlier_visibility=preserved`.
 
-## Phase Application
+## Phase application
 
 - **planning** — tag every `.prd` item with route family + failure-mode IDs
-- **gm-execute** — weak prior only; witnessed probe required before authorization
+- **gm-execute** — weak prior only; witnessed probe before authorization
 - **gm-emit** — legitimacy gate; unearned specificity → lawful downgrade
-- **gm-complete** — stress-suite pass; close posture only CI green
+- **gm-complete** — stress-suite pass; close posture only when CI is green

package/skills/pages/SKILL.md

@@ -3,41 +3,37 @@ name: pages
 description: Scaffold and maintain a GitHub Pages site. Buildless in browser (webjsx + rippleui via CDN), flatspace for content aggregation built during GH Actions. Use when user wants to create or update a GH Pages site.
 ---
 
-# Pages — GitHub Pages Site Scaffolder
+# Pages — GitHub Pages site scaffolder
 
-Scaffold a complete GH Pages site: **no local build step**, content managed via flatspace flat-file CMS, UI via webjsx + rippleui CDN, GH Actions builds and deploys.
-
-**Follow full gm skill chain: planning → gm-execute → gm-emit → gm-complete → update-docs.**
+Scaffold a complete GH Pages site with no local build step. Content via flatspace flat-file CMS, UI via webjsx + rippleui CDN, GH Actions builds and deploys. Follow the full chain: `planning → gm-execute → gm-emit → gm-complete → update-docs`.
 
 ## Stack
 
 | Layer | Tool | How |
-|-------|------|-----|
+|---|---|---|
 | UI rendering | [webjsx](https://webjsx.org) | ES module via importmap, `applyDiff` for DOM updates |
 | Styling | [rippleui](https://ripple-ui.com) | CDN `<link>` — Tailwind-based component classes |
 | Content CMS | [flatspace](https://npmjs.com/package/flatspace) | Aggregates `content/` → `docs/data/*.json` at build time |
 | Build | GH Actions | `npx flatspace` runs in CI, commits output to `docs/` |
-| Hosting | GitHub Pages | Source: `docs/` branch, or GH Actions deploy |
+| Hosting | GitHub Pages | Source set to "GitHub Actions" |
 
-## Directory Layout
+## Layout
 
 ```
 <project>/
-  content/              # Source content (markdown, json, yaml)
-    pages/              # Static pages (index.md, about.md, ...)
-    posts/              # Blog posts or articles
-    data/               # Structured data files
-  docs/                 # GH Pages root (gitignored build output except index.html)
-    index.html          # Entry point — committed, never regenerated
-    app.js              # Main webjsx app — committed
-    data/               # flatspace output — gitignored, built by CI
-  .github/
-    workflows/
-      pages.yml         # Build + deploy workflow
-  flatspace.config.js   # flatspace aggregation config
+  content/
+    pages/
+    posts/
+    data/
+  docs/
+    index.html       # committed, never regenerated
+    app.js           # committed
+    data/            # flatspace output, gitignored
+  .github/workflows/pages.yml
+  flatspace.config.js
 ```
 
-## index.html — Buildless Entry
+## index.html
 
 ```html
 <!DOCTYPE html>
@@ -63,28 +59,19 @@ Scaffold a complete GH Pages site: **no local build step**, content managed via
 </html>
 ```
 
-## app.js — webjsx App Pattern
+## app.js
 
 ```js
 import { applyDiff } from 'webjsx';
 
 const h = (tag, props, ...children) => ({ tag, props: props || {}, children });
-
 const state = { page: null, data: {} };
 
-async function loadData(path) {
-  const res = await fetch(path);
-  return res.json();
-}
-
-function render() {
-  applyDiff(document.getElementById('root'), App(state));
-}
+async function loadData(path) { return (await fetch(path)).json(); }
+function render() { applyDiff(document.getElementById('root'), App(state)); }
 
 function App(s) {
-  if (!s.page) return h('div', { class: 'flex justify-center p-8' },
-    h('span', { class: 'spinner' })
-  );
+  if (!s.page) return h('div', { class: 'flex justify-center p-8' }, h('span', { class: 'spinner' }));
   return h('div', { class: 'max-w-4xl mx-auto p-4' },
     h('nav', { class: 'navbar bg-backgroundSecondary mb-6' },
       h('span', { class: 'navbar-brand text-xl font-bold' }, s.page.title)
@@ -100,11 +87,7 @@ function Section(section) {
   );
 }
 
-async function main() {
-  state.page = await loadData('./data/index.json');
-  render();
-}
-
+async function main() { state.page = await loadData('./data/index.json'); render(); }
 main();
 ```
 
@@ -122,11 +105,10 @@ module.exports = {
 };
 ```
 
-## GH Actions Workflow — pages.yml
+## pages.yml
 
 ```yaml
 name: Deploy GitHub Pages
-
 on:
   push:
     branches: [main]
@@ -142,14 +124,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-
       - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
+        with: { node-version: '20' }
       - name: Build content with flatspace
         run: npx flatspace
-
       - name: Commit built data
         run: |
           git config user.name "github-actions[bot]"
@@ -157,11 +135,8 @@ jobs:
           git add docs/data/
           git diff --staged --quiet || git commit -m "chore: build content [skip ci]"
           git push
-
-      - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: docs/
+      - uses: actions/upload-pages-artifact@v3
+        with: { path: docs/ }
 
   deploy:
     needs: build
@@ -174,26 +149,14 @@ jobs:
         uses: actions/deploy-pages@v4
 ```
 
-## Scaffolding Steps
+## Scaffold sequence
 
-When user says "set up pages" or "create GH pages site":
+Read existing `docs/` and `content/` if present — never clobber existing content. Create the directory structure. Write `docs/index.html`, `docs/app.js`, `flatspace.config.js`, `.github/workflows/pages.yml`, `content/pages/index.md` with minimal frontmatter (`title`, `sections` array). Add `docs/data/` to `.gitignore`. Verify GH Pages setting is "GitHub Actions" in repo Settings — remind the user if you can't verify.
 
-1. **Read** existing `docs/` and `content/` if present — never clobber existing content
-2. **Create** directory structure above
-3. **Write** `docs/index.html` with correct site title
-4. **Write** `docs/app.js` with webjsx app skeleton
-5. **Write** `flatspace.config.js`
-6. **Write** `.github/workflows/pages.yml`
-7. **Write** `content/pages/index.md` with minimal frontmatter (`title`, `sections` array)
-8. **Add** `docs/data/` to `.gitignore` (built by CI, not committed by humans)
-9. **Verify** GH Pages setting is "GitHub Actions" in repo Settings — remind user if can't verify
-
-## rippleui Component Classes Quick Reference
-
-Use these directly in JSX className strings — no config needed:
+## rippleui classes
 
 | Component | Class |
-|-----------|-------|
+|---|---|
 | Button | `btn btn-primary`, `btn btn-secondary`, `btn btn-ghost` |
 | Card | `card p-4` |
 | Input | `input input-primary` |
@@ -203,30 +166,18 @@ Use these directly in JSX className strings — no config needed:
 | Spinner | `spinner` |
 | Divider | `divider` |
 
-Background: `bg-backgroundPrimary`, `bg-backgroundSecondary`. Text: `text-content1`, `text-content2`.
-
-**CSS variable warning**: rippleui color vars (e.g. `--gray-2`) are raw space-separated RGB tuples — not valid CSS colors. Never use them in `rgb()` directly from JS. Use the component classes instead.
-
-## webjsx Patterns
-
-**No JSX transpile needed** — use `h()` factory or import from CDN with importmap and write JSX in `.jsx` files served directly (Chrome supports importmap natively).
-
-For `.js` files without transpile, use the `h` factory pattern shown above.
+Background `bg-backgroundPrimary`, `bg-backgroundSecondary`. Text `text-content1`, `text-content2`. rippleui CSS color vars (e.g. `--gray-2`) are raw space-separated RGB tuples — invalid in `rgb()` directly. Use the component classes instead.
 
-For `.jsx` with native importmap (no build):
-```js
-/** @jsxImportSource webjsx */
-import { applyDiff } from 'webjsx';
-```
-Only works if server sets correct MIME type for `.jsx` — GH Pages does not. Use `.js` + `h()` factory.
+## webjsx
 
-**applyDiff signature**: `applyDiff(domNode, vnodeOrArray)` — never pass a string, always pass a vnode from `h()`.
+No JSX transpile needed. Use the `h()` factory in `.js` files served directly. `.jsx` with native importmap requires the server to set the correct MIME type, which GH Pages does not — stay in `.js` + `h()`.
 
-**State updates**: mutate `state`, call `render()` — no reactive system, explicit re-render on every change.
+`applyDiff(domNode, vnodeOrArray)` — never pass a string. State updates mutate `state` and call `render()`; no reactive system.
 
-## Content Format (flatspace input)
+## Content format
 
 Markdown with YAML frontmatter:
+
 ```markdown
 ---
 title: Home
@@ -240,19 +191,18 @@ sections:
 Full markdown body here.
 ```
 
-flatspace outputs `docs/data/pages/index.json`:
+Output `docs/data/pages/index.json`:
+
 ```json
 { "title": "Home", "sections": [...], "body": "<p>Full markdown body here.</p>", "slug": "index" }
 ```
 
-## Known Gotchas
-
-**GH Pages must be set to "GitHub Actions"** in Settings → Pages. "Deploy from branch" ignores the deploy-pages action entirely.
+## Gotchas
 
-**docs/data/ must be in .gitignore** but `docs/index.html` and `docs/app.js` must NOT be ignored — they are the committed source files.
+GH Pages must be set to "GitHub Actions" in Settings → Pages. "Deploy from branch" ignores the deploy-pages action.
 
-**flatspace npx cold start**: first CI run downloads flatspace — takes ~10s extra. Subsequent runs use cache if `actions/setup-node` cache is configured.
+`docs/data/` is gitignored; `docs/index.html` and `docs/app.js` are not — they are the committed source files.
 
-**importmap browser support**: all modern browsers support importmap. No IE, no Safari < 16.4. For GH Pages this is fine.
+`npx flatspace` cold-start is ~10s on first CI run; subsequent runs use the `actions/setup-node` cache.
 
-**webjsx CDN version**: pin to explicit version in importmap (e.g. `@0.0.42`) — avoid `@latest` to prevent silent breakage on upstream updates.
+Pin the webjsx CDN version in importmap (e.g. `@0.0.42`) — `@latest` breaks silently on upstream updates.