npm - gm-hermes - Versions diffs - 2.0.515 - Mend

gm-hermes 2.0.515

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/AGENTS.md +11 -0
package/LICENSE +21 -0
package/README.md +21 -0
package/cli.js +37 -0
package/hermes-skill.json +9 -0
package/index.html +54 -0
package/package.json +33 -0
package/skills/software-development/browser/SKILL.md +202 -0
package/skills/software-development/code-search/SKILL.md +69 -0
package/skills/software-development/create-lang-plugin/SKILL.md +183 -0
package/skills/software-development/gm/SKILL.md +28 -0
package/skills/software-development/gm-complete/SKILL.md +185 -0
package/skills/software-development/gm-emit/SKILL.md +126 -0
package/skills/software-development/gm-execute/SKILL.md +159 -0
package/skills/software-development/pages/SKILL.md +258 -0
package/skills/software-development/planning/SKILL.md +177 -0
package/skills/software-development/ssh/SKILL.md +89 -0
package/skills/software-development/update-docs/SKILL.md +113 -0

package/skills/software-development/pages/SKILL.md ADDED Viewed

@@ -0,0 +1,258 @@
+---
+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
+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.**
+## 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 |
+## Directory 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
+```
+## index.html — Buildless Entry
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{SITE_TITLE}}</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/rippleui@1.12.1/dist/css/styles.css">
+  <script type="importmap">
+  {
+    "imports": {
+      "webjsx": "https://cdn.jsdelivr.net/npm/webjsx@0.0.42/dist/index.js",
+      "webjsx/jsx-runtime": "https://cdn.jsdelivr.net/npm/webjsx@0.0.42/dist/jsx-runtime.js"
+    }
+  }
+  </script>
+  <script type="module" src="./app.js"></script>
+</head>
+<body class="bg-backgroundPrimary text-content1 min-h-screen">
+  <div id="root"></div>
+</body>
+</html>
+```
+## app.js — webjsx App Pattern
+```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));
+}
+function App(s) {
+  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)
+    ),
+    h('main', {}, ...s.page.sections.map(Section))
+  );
+}
+function Section(section) {
+  return h('section', { class: 'card mb-4 p-6' },
+    h('h2', { class: 'text-2xl font-bold mb-2' }, section.title),
+    h('p', { class: 'text-content2' }, section.body)
+  );
+}
+async function main() {
+  state.page = await loadData('./data/index.json');
+  render();
+}
+main();
+```
+## flatspace.config.js
+```js
+module.exports = {
+  input: './content',
+  output: './docs/data',
+  collections: {
+    pages: { dir: 'pages', format: 'markdown' },
+    posts: { dir: 'posts', format: 'markdown', sortBy: 'date', order: 'desc' },
+    data: { dir: 'data', format: 'json' }
+  }
+};
+```
+## GH Actions Workflow — pages.yml
+```yaml
+name: Deploy GitHub Pages
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Build content with flatspace
+        run: npx flatspace
+      - name: Commit built data
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          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/
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
+## Scaffolding Steps
+When user says "set up pages" or "create GH pages site":
+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:
+| Component | Class |
+|-----------|-------|
+| Button | `btn btn-primary`, `btn btn-secondary`, `btn btn-ghost` |
+| Card | `card p-4` |
+| Input | `input input-primary` |
+| Navbar | `navbar` + `navbar-brand` |
+| Badge | `badge badge-primary` |
+| Alert | `alert alert-success`, `alert alert-error` |
+| 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.
+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.
+**applyDiff signature**: `applyDiff(domNode, vnodeOrArray)` — never pass a string, always pass a vnode from `h()`.
+**State updates**: mutate `state`, call `render()` — no reactive system, explicit re-render on every change.
+## Content Format (flatspace input)
+Markdown with YAML frontmatter:
+```markdown
+---
+title: Home
+sections:
+  - title: Welcome
+    body: Hello world
+---
+# Home
+Full markdown body here.
+```
+flatspace outputs `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.
+**docs/data/ must be in .gitignore** but `docs/index.html` and `docs/app.js` must NOT be ignored — they are the committed source files.
+**flatspace npx cold start**: first CI run downloads flatspace — takes ~10s extra. Subsequent runs use cache if `actions/setup-node` cache is configured.
+**importmap browser support**: all modern browsers support importmap. No IE, no Safari < 16.4. For GH Pages this is fine.
+**webjsx CDN version**: pin to explicit version in importmap (e.g. `@0.0.42`) — avoid `@latest` to prevent silent breakage on upstream updates.

package/skills/software-development/planning/SKILL.md ADDED Viewed

@@ -0,0 +1,177 @@
+---
+name: planning
+description: State machine orchestrator. Mutable discovery, PRD construction, and full PLAN→EXECUTE→EMIT→VERIFY→COMPLETE lifecycle. Invoke at session start and on any new unknown.
+allowed-tools: Write
+---
+# Planning — State Machine Orchestrator
+Root of all work. Runs `PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS → COMPLETE`.
+**Entry**: prompt-submit hook → `gm` agent → invoke `planning` skill (here). Also re-entered any time a new unknown surfaces in any phase.
+## STATE MACHINE
+**FORWARD**: PLAN complete → `gm-execute` | EXECUTE complete → `gm-emit` | EMIT complete → `gm-complete` | VERIFY .prd remains → `gm-execute` | VERIFY .prd empty+pushed → `update-docs`
+**REGRESSIONS**: new unknown at any state → re-invoke `planning` | EXECUTE unresolvable 2 passes → `planning` | EMIT logic error → `gm-execute` | EMIT new unknown → `planning` | VERIFY broken output → `gm-emit` | VERIFY logic wrong → `gm-execute` | VERIFY new unknown → `planning`
+**Runs until**: .gm/prd.yml empty AND git clean AND all pushes confirmed AND CI green.
+## ENFORCEMENT — COMPLETE EVERY TASK END-TO-END
+**Cannot respond or stop while**:
+- .gm/prd.yml exists and has items
+- git has uncommitted changes
+- git has unpushed commits
+The skill chain MUST be followed completely end-to-end without exception. Partial execution = violation. After every phase: read .prd, check git, invoke next skill.
+## PLAN PHASE — MUTABLE DISCOVERY
+Planning = exhaustive fault-surface enumeration. For every aspect of the task:
+- What do I not know? → mutable (UNKNOWN)
+- What could go wrong? → edge case item with failure mode
+- What depends on what? → blocking/blockedBy mapped explicitly
+- What assumptions am I making? → each = unwitnessed hypothesis = mutable until execution proves it
+**Fault surfaces**: file existence | API shape | data format | dependency versions | runtime behavior | environment differences | error conditions | concurrency hazards | integration seams | backwards compatibility | rollback paths | deployment steps | CI/CD correctness
+**MANDATORY CODEBASE SCAN**: For every planned item, add `existingImpl=UNKNOWN`. Resolve via exec:codesearch. Existing code serving same concern → consolidation task, not addition. `exec:codesearch` indexes PDFs page-by-page alongside source — spec PDFs, papers, vendor manuals, and RFCs are searchable as code. When planning against a protocol, hardware, or compliance requirement, search the PDF corpus the same way you search source: two words, iterate. A constraint the PRD is missing because it only lives in a PDF is a fault surface — enumerate doc PDFs as scan targets during mutable discovery.
+**EXIT PLAN**: zero new unknowns in last pass AND all .prd items have explicit acceptance criteria AND all dependencies mapped → launch subagents or invoke `gm-execute`.
+**SELF-LOOP**: new items discovered → add to .prd → plan again.
+**Skip planning entirely** (this is the DEFAULT for small work) if ANY of these apply:
+- Single-file, single-concern edit
+- Task is trivially bounded and under ~5 minutes
+- User gave explicit surgical instructions ("change X to Y")
+- Bug fix where root cause is already identified
+- Zero unknowns / no mutables to resolve
+Heavy ceremony (PRD + parallel subagents) is for multi-file architectural work or genuinely unknown fault surfaces. Writing a 7-item PRD for a 3-line change is waste. Err toward skipping — if a new unknown surfaces mid-work, THAT is when you regress to planning, not preemptively.
+**Contrast examples:**
+- "Fix the hold-detect logic at apcKey25.cpp:163" → SKIP planning. Read, edit, done.
+- "Add drift correction and watchdog and observability across the USB audio path" → DO plan. Multi-file, multiple unknowns.
+## OBSERVABILITY ENUMERATION — MANDATORY EVERY PASS
+During every planning pass, enumerate every possible aspect of the app's runtime observability that can be improved. The goal is permanent structures — not ad-hoc logs — that make any future debugging session start from a complete, live picture of system state.
+**Server-side permanent structures**: Every internal subsystem — state machine, queue, cache, connection pool, active task map, process registry, RPC handler, hook dispatcher — must expose a named, queryable inspection endpoint (e.g. `/debug/<subsystem>`). State must be readable, filterable, and ideally modifiable without restart. Profiling hooks on every hot path. Structured logs with subsystem tag, severity, and timestamp — filterable at runtime by subsystem, not just log level. Any internal state that requires a restart to inspect is an observability gap.
+**Client-side permanent structures**: `window.__debug` must be a live, structured registry — not a dump. Every component's state, every active request, every event queue, every WebSocket connection, every rendered prop, every error boundary — all addressable by key, all queryable without refreshing. New modules register themselves into `window.__debug` on mount and deregister on unmount. Any execution path not traceable via `window.__debug` is an observability gap.
+**Permanent vs ad-hoc**: `console.log` = ad-hoc = not observability. A structured logger with subsystem routing = permanent. `window.__debug.myModule.state` = permanent. `window.__debug = { ...window.__debug, tmp: x }` = ad-hoc = not acceptable. Permanent structures survive deploys and accumulate diagnostic value across sessions.
+**Mandate**: on discovery of any observability gap → immediately add a .prd item. Observability improvements are highest-priority — never deferred. The agent must be able to see specifically anything it wants and nothing else — no guessing, no blind spots.
+## .PRD FORMAT
+Path: `./.gm/prd.yml`. YAML via `exec:nodejs` (use `fs.writeFileSync`). Ensure `.gm/` dir exists before writing. Delete when empty — never leave empty file. Delete `.gm/` dir when completely empty.
+```yaml
+- id: kebab-id
+  subject: Imperative verb phrase
+  status: pending
+  description: Precise criterion
+  effort: small|medium|large
+  category: feature|bug|refactor|infra
+  blocking: []
+  blockedBy: []
+  acceptance:
+    - binary criterion
+  edge_cases:
+    - failure mode
+```
+Status: `pending` → `in_progress` → `completed` (remove completed items). Effort: small <15min | medium <45min | large >1h.
+## PARALLEL SUBAGENT LAUNCH
+After .prd written, launch ≤3 parallel `gm:gm` subagents for all independent items simultaneously. Never sequential.
+`Agent(subagent_type="gm:gm", prompt="Work on .prd item: <id>. .prd path: <path>. Item: <full YAML>.")`
+After each wave: read .prd, find newly unblocked items, launch next wave. Exception: browser tasks serialize.
+When parallelism not applicable: invoke `gm-execute` skill directly.
+## MUTABLE DISCIPLINE
+Each mutable: name | expected | current | resolution method. Resolve by witnessed execution only. Zero variance = resolved. Unresolved after 2 passes = new unknown = re-invoke `planning`. Mutables live in conversation only.
+## CODE EXECUTION
+`exec:<lang>` only. Bash body: `exec:<lang>\n<code>`
+`exec:nodejs` | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:c` | `exec:cpp` | `exec:java` | `exec:deno` | `exec:cmd`
+File I/O: exec:nodejs + require('fs'). Git only in Bash directly. `Bash(node/npm/npx/bun)` = violation.
+Pack runs: `Promise.allSettled` for parallel ops. Each idea its own try/catch. Under 12s per call.
+Background: `exec:sleep <id>` | `exec:status <id>` | `exec:close <id>`. Runner: `exec:runner start|stop|status`.
+## CODEBASE EXPLORATION
+`exec:codesearch` only. Glob/Grep/Read/Explore/WebSearch = hook-blocked. Start 2 words → change one word → add third → minimum 4 attempts before concluding absent.
+## BROWSER AUTOMATION
+Invoke `browser` skill. Escalation: (1) `exec:browser <js>` → (2) browser skill → (3) navigate/click → (4) screenshot last resort. Browser tasks serialize — one Chrome instance per project.
+## SKILL REGISTRY
+`gm-execute` → `gm-emit` → `gm-complete` → `update-docs` | `browser` | `memorize` (sub-agent, background only)
+`memorize`: `Agent(subagent_type='memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<what>')`
+## MANDATORY DEV WORKFLOW
+No comments. No scattered test files. 200-line limit — split before continuing. Fail loud. No duplication. Scan before every edit. Duplicate concern = regress to PLAN. Errors throw with context — no `|| default`, no `catch { return null }`. `window.__debug` exposes all client state. AGENTS.md via memorize only. CHANGELOG.md: append per commit.
+**Minimal code / maximal DX process**: Before writing any logic, run this process in order — stop at the first step that resolves the need:
+1. **Native first** — does the language or runtime already do this? Use it exactly as designed.
+2. **Library second** — does an existing dependency already solve this pattern? Use its API directly.
+3. **Structure third** — can the problem be encoded as data (map, table, pipeline) so the structure enforces correctness and eliminates branching entirely?
+4. **Write last** — only author new logic when the above three are exhausted. New logic = new surface area = new bugs.
+When structure eliminates a whole class of wrong states — name that pattern explicitly. Dispatch tables replacing switch chains, pipelines replacing loop-with-accumulator, maps replacing if/else forests — these are not just style preferences, they are correctness properties. Code that cannot be wrong because of how it is shaped is the goal. Readable top-to-bottom without mental simulation = done right. Requires decoding = not done.
+## SINGLE INTEGRATION TEST POLICY
+Every project maintains exactly one `test.js` at project root. 200-line max. No other test files anywhere — no `.test.js`, `.spec.js`, `__tests__/`, `fixtures/`, `mocks/`. Delete all scattered tests on discovery and consolidate coverage into `test.js`.
+**test.js replaces all unit tests.** It tests the real system end-to-end with real data. No mocks, no stubs, no test frameworks. Plain node assertions or process exit codes.
+**Creation**: if `test.js` does not exist, create it during EXECUTE phase covering all testable surface of current work.
+**Maintenance**: every code change that adds or modifies behavior must update `test.js` to cover it. Every bug fix must add a regression case that would have caught the bug.
+**Structure**: group by subsystem, each subsystem gets a section. When approaching 200 lines, compress older stable tests into tighter assertions to make room for new coverage.
+**Execution**: `gm-complete` runs `test.js` before allowing completion. Failure = regression to EXECUTE.
+## RESPONSE POLICY
+Terse like smart caveman. Technical substance stays. Fluff dies. Default: **full**. Switch: `/caveman lite|full|ultra`.
+Drop: articles, filler, pleasantries, hedging. Fragments OK. Short synonyms. Technical terms exact. Code unchanged. Pattern: `[thing] [action] [reason]. [next step].`
+Levels: **lite** = no filler, full sentences | **full** = drop articles, fragments OK | **ultra** = abbreviate all, arrows for causality | **wenyan-full** = 文言文, 80-90% compression | **wenyan-ultra** = max classical terse.
+Auto-Clarity: drop caveman for security warnings, irreversible confirmations, ambiguous sequences. Resume after. Code/commits/PRs write normal. "stop caveman" / "normal mode": revert.
+## CONSTRAINTS
+**Tier 0**: no_crash, no_exit, ground_truth_only, real_execution, fail_loud
+**Tier 1**: max_file_lines=200, hot_reloadable, checkpoint_state
+**Tier 2**: no_duplication, no_hardcoded_values, modularity
+**Tier 3**: no_comments, convention_over_code
+**Never**: `Bash(node/npm/npx/bun)` | skip planning | partial execution | stop while .gm/prd.yml has items | stop while git dirty | sequential independent items | screenshot before JS exhausted | fallback/demo modes | silently swallow errors | duplicate concern | leave comments | create scattered test files (only root test.js) | write if/else chains where a map or pipeline suffices | write one-liners that require decoding | branch on enumerated cases when a dispatch table exists
+**Always**: invoke named skill at every state transition | regress to planning on any new unknown | witnessed execution only | scan codebase before edits | enumerate every possible observability improvement every planning pass | follow skill chain completely end-to-end on every task without exception | prefer dispatch tables over switch/if chains | prefer pipelines over loop-with-accumulator | make wrong states structurally impossible | name patterns when structure eliminates a whole class of bugs

package/skills/software-development/ssh/SKILL.md ADDED Viewed

@@ -0,0 +1,89 @@
+---
+name: ssh
+description: Run shell commands on remote SSH hosts via exec:ssh. Reads targets from ~/.claude/ssh-targets.json. Use for deploying, monitoring, or controlling remote machines.
+---
+# exec:ssh — Remote SSH Execution
+**Use gm subagents for all independent work items. Invoke all skills in the chain: planning → gm-execute → gm-emit → gm-complete → update-docs.**
+Runs shell commands on a remote host over SSH. No shell open, no manual connection — just write the command.
+## Setup
+Create `~/.claude/ssh-targets.json`:
+```json
+{
+  "default": {
+    "host": "192.168.1.10",
+    "port": 22,
+    "username": "pi",
+    "password": "yourpassword"
+  },
+  "prod": {
+    "host": "10.0.0.1",
+    "username": "ubuntu",
+    "keyPath": "/home/user/.ssh/id_rsa"
+  }
+}
+```
+Fields: `host` (required), `port` (default 22), `username` (required), `password` OR `keyPath` + optional `passphrase`.
+## Usage
+```
+exec:ssh
+<shell command>
+```
+Target a named host with `@name` on the first line:
+```
+exec:ssh
+@prod
+sudo systemctl restart myapp
+```
+Multi-line scripts work:
+```
+exec:ssh
+cd /var/log && tail -20 syslog
+```
+## Process Persistence
+SSH sessions kill child processes on close. To keep a process running after the command returns:
+```
+exec:ssh
+sudo systemctl reset-failed myunit 2>/dev/null; systemd-run --unit=myunit bash -c 'your-long-running-command'
+```
+Always call `systemctl reset-failed <unit>` before reusing a unit name, or use a unique timestamped name:
+```
+exec:ssh
+systemd-run --unit=job-$(date +%s) bash -c 'nohup myprogram &'
+```
+Fallback if systemd unavailable:
+```
+exec:ssh
+setsid nohup bash -c 'myprogram > /tmp/out.log 2>&1' &
+```
+## Dependency
+Requires `ssh2` npm package. Install in `~/.claude/gm-tools`:
+```
+exec:bash
+cd ~/.claude/gm-tools && npm install ssh2
+```
+The plugin searches: `~/.claude/gm-tools/node_modules/ssh2`, `~/.claude/plugins/node_modules/ssh2`, then global.

package/skills/software-development/update-docs/SKILL.md ADDED Viewed

@@ -0,0 +1,113 @@
+---
+name: update-docs
+description: UPDATE-DOCS phase. Refresh README.md, AGENTS.md, and docs/index.html to reflect changes made this session. Commits and pushes doc updates. Terminal phase — declares COMPLETE.
+---
+# GM UPDATE-DOCS — Documentation Refresh
+You are in the **UPDATE-DOCS** phase. Feature work is verified and pushed. Refresh all documentation to match the actual codebase state right now.
+**GRAPH POSITION**: `PLAN → EXECUTE → EMIT → VERIFY → [UPDATE-DOCS] → COMPLETE`
+- **Entry**: Feature work verified, committed, and pushed. Entered from `gm-complete`.
+## TRANSITIONS
+**FORWARD**: All docs updated, committed, and pushed → COMPLETE (session ends)
+**BACKWARD**:
+- Diff reveals unknown architecture change → invoke `planning` skill, restart chain
+- Doc write fails post-emit verify → fix and re-verify before advancing
+## EXECUTION SEQUENCE
+**Step 1 — Understand what changed**:
+```
+exec:bash
+git log -5 --oneline
+git diff HEAD~1 --stat
+```
+Witness which files changed. Identify doc-sensitive changes: new skills, new states in the state machine, new platforms, modified architecture, new constraints, renamed files.
+**Step 2 — Read current docs**:
+```
+exec:nodejs
+const fs = require('fs');
+['README.md', 'AGENTS.md', 'docs/index.html',
+ 'gm-starter/agents/gm.md'].forEach(f => {
+  try { console.log(`=== ${f} ===\n` + fs.readFileSync(f, 'utf8')); }
+  catch(e) { console.log(`MISSING: ${f}`); }
+});
+```
+Identify every section that no longer matches the actual codebase state.
+**Step 3 — Write updated docs**:
+Write only sections that changed. Do not rewrite unchanged content. Rules per file:
+**README.md**: platform count matches adapters in `platforms/`, skill tree diagram matches current state machine, quick start commands work.
+**AGENTS.md**: Launch memorize sub-agent in background with session learnings. Do not inline-edit AGENTS.md — the memorize agent handles extraction, deduplication, and writing. Use: `Agent(subagent_type='memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<session learnings>')`
+**docs/index.html**: `PHASES` array matches current skill state machine phases. Platform lists match `platforms/` directory. State machine diagram updated if new phases added.
+**gm-starter/agents/gm.md**: Skill chain on the `gm skill →` line updated if new skills were added.
+```
+exec:nodejs
+const fs = require('fs');
+fs.writeFileSync('/abs/path/file.md', updatedContent);
+```
+**Step 4 — Verify from disk**:
+```
+exec:nodejs
+const fs = require('fs');
+const content = fs.readFileSync('/abs/path/file.md', 'utf8');
+console.log(content.includes('expectedString'), content.length);
+```
+Witness each written file from disk. Any variance from expected content → fix and re-verify.
+**Step 5 — Commit and push**:
+```
+exec:bash
+git add README.md docs/index.html gm-starter/agents/gm.md
+git diff --cached --stat
+```
+Witness staged files. Then commit and push:
+```
+exec:bash
+git commit -m "docs: update documentation to reflect session changes"
+git push -u origin HEAD
+```
+Witness push confirmation. Zero variance = COMPLETE.
+## DOC FIDELITY RULES
+Every claim in docs must be verifiable against disk right now:
+- State machine phase names must match skill file `name:` frontmatter
+- Platform names must match adapter class names in `platforms/`
+- File paths must exist on disk
+- Constraint counts must match actual constraints
+If a doc section cannot be verified against disk: remove it, do not speculate.
+## CONSTRAINTS
+**Never**: skip diff analysis | write docs from memory alone | push without verifying from disk | add comments to doc content | claim done without witnessed push output
+**Always**: witness git diff first | read current file before overwriting | verify each file from disk after write | push doc changes | confirm with witnessed push output
+---
+**→ COMPLETE**: Docs committed and pushed → session ends.
+**↩ SNAKE to PLAN**: New unknown about codebase state → invoke `planning` skill.