gm-codex 2.0.726 → 2.0.788

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-codex",
-  "version": "2.0.726",
+  "version": "2.0.788",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "author": {
     "name": "AnEntrypoint",

package/README.md

@@ -8,7 +8,18 @@
 bun x gm-codex@latest
 ```
 
-This installs or upgrades the plugin into your user Codex plugins directory and keeps the package layout consistent across platforms.
+Installs the plugin to `~/.codex/plugins/gm-codex` AND wires `~/.codex/config.toml` so Codex auto-loads hooks, MCP servers, and skills on next start. No manual TOML editing required. Idempotent — re-run to upgrade.
+
+### What gets registered in `config.toml`
+
+Inside a managed block fenced by `# >>> gm-codex managed` / `# <<< gm-codex managed` sentinels:
+
+- `[features].codex_hooks = true`
+- `[[hooks.<Event>]]` blocks for `PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, `Stop` — pointing at the bundled `plugkit` and node hook scripts under the install dir
+- `[mcp_servers.<id>]` for any MCP servers declared in bundled `.mcp.json`
+- `[[skills.config]]` entries for every bundled skill folder
+
+Content outside the managed block is preserved verbatim. The installer never edits user-authored sections.
 
 ### Repository Installation (Project-Specific)
 
@@ -18,7 +29,15 @@ npm install gm-codex
 npx gm-codex-install
 ```
 
-The installer copies plugin assets into `.codex/plugins/gm-codex` in your project and is useful for local customization.
+Copies plugin assets into `<project>/.codex/plugins/gm-codex` and writes the same managed block into `<project>/.codex/config.toml` (project-trusted layer).
+
+### Uninstall
+
+```bash
+npx gm-codex-uninstall
+```
+
+Removes the plugin directory and strips the managed block from `config.toml`, leaving any user-authored content untouched.
 
 ### Manual Installation
 

package/agents/memorize.md

@@ -11,6 +11,19 @@ Writes facts to two places only: **AGENTS.md** (non-obvious technical caveats) a
 Resolve at start of every run:
 
 - **Project root** = `process.cwd()` when invoked. `AGENTS.md` is `<project root>/AGENTS.md`.
+- **Reach check** = run `gh api repos/<owner>/<repo> --jq .permissions.push` on `<project root>`'s `git remote get-url origin`. Cache the answer for the run. If the result is anything other than literal `true` (false, no remote, non-github URL, gh CLI missing, gh not authed, repo private and inaccessible), the project is **out-of-reach**.
+
+## STEP 0: SCOPE GUARD — DO NOT POLLUTE OUT-OF-REACH PROJECTS
+
+If the reach check returns out-of-reach:
+
+- **Do** ingest classified facts into rs-learn (Step 2) — rs-learn is per-user, not per-project, so private notes about a project the user is reading-but-not-owning are safe there.
+- **Do not** read or edit `<project root>/AGENTS.md` (Step 3). Skip the file entirely.
+- **Do not** run the AGENTS.md ↔ rs-learn migration audit (Step 4). The audit edits AGENTS.md.
+
+Reason: agents running in a cwd that points at a third-party repo (e.g. running Claude inside a checkout of `nousresearch/hermes-agent` while building a downstream port) must not write project-specific notes into the upstream project's AGENTS.md. That AGENTS.md belongs to the upstream maintainers. Personal porting notes belong in the user's downstream repo's AGENTS.md, or — when the work spans multiple repos and there's no clean home — in rs-learn only.
+
+When the reach check returns **in-reach**, proceed normally with all four steps below.
 
 ## STEP 1: CLASSIFY
 

package/agents/research-worker.md

@@ -0,0 +1,34 @@
+---
+name: research-worker
+description: Focused single-thread web investigator. Spawned in parallel by the research skill. Owns one question, returns one path.
+agent: true
+allowed-tools: WebFetch, WebSearch, Bash
+---
+
+# Research Worker
+
+One question. One context. One file on disk. One-line return.
+
+## Brief shape
+
+The spawning prompt names: the question, the answer shape expected, the explicit out-of-scope boundary, and the destination path `.gm/research/<slug>/<worker-id>.md`. If any of those is missing or ambiguous, treat that as the first finding — record what was unclear and stop, rather than guessing scope.
+
+## Investigation
+
+Open with a `WebSearch` broad enough to map sources, narrow enough to exclude obviously off-topic results. Pick the two or three highest-quality hits — primary docs, dated authored posts, RFCs, source repos — and `WebFetch` each. Aggregator pages, content farms, and undated listicles are last resort, flagged as such when used.
+
+Stop fetching when the question is answered to the shape requested. Extra fetches past sufficiency burn tokens the orchestrator needs for synthesis.
+
+## Output
+
+Write the findings file with: the question restated, the answer in the requested shape, every non-trivial claim followed by `[source: <url>]` and a quoted span, a `Sources` section listing every URL touched with a one-line quality note, and an `Unresolved` section naming anything the brief asked for that the search did not yield.
+
+A claim without an inline source URL is a defect; remove it before writing the file.
+
+## Return
+
+Return only: the absolute path to the findings file, and a single sentence summarising the headline answer. Never return the full findings inline — the orchestrator reads from disk.
+
+## Boundary
+
+Do not chase tangents that surface mid-investigation, however interesting. Note them in `Unresolved` so the orchestrator can decide whether to fan out a new worker. Stretching past the brief is the worker-side equivalent of the orchestrator skipping fan-out.

package/bin/plugkit.sha256

@@ -1,6 +1,6 @@
-9dbd63a59e435a3a8cb8a1b89344ecfa4b4865bdf81ec5a3aa53202645f39b01  plugkit-win32-x64.exe
-18f37964c80c20fe7adaeef4c6168b331d8d23a94ff369d9807f0847cc16c757  plugkit-win32-arm64.exe
-2cd123dd7704bd823d0c655ecb815afb155c8de2b5dafaadd475864af676a72c  plugkit-darwin-x64
-df98f857def381b366b6346b613bbd4753b62557c374b5768aee9183f52a3dd0  plugkit-darwin-arm64
-fcfdbba8a28458da1a8937670d5173f774ec6fe6bcd5b820c0bce5ae8d785660  plugkit-linux-x64
-2b6f8a8c9316f7bb1378752d61928575d4f0fcc739daab7376af66ed1b65d82f  plugkit-linux-arm64
+882cf8f24ae1755f1e503dca8b6010f3f53bf9325c0e58e059b0d9834066a151  plugkit-win32-x64.exe
+d440cd5d3e24c08325c8b7cd45b68abe3f2fcd7195f7ee25e1eaa01c610e2971  plugkit-win32-arm64.exe
+b30b0f6ad8d516283402e8f06a2ae1dae70fb4381ed9e1993751fb1baa7dff6e  plugkit-darwin-x64
+2f451f3783af406ba060f06d2ae34653f68b3731f30a0a6e269cf5f8c37372d5  plugkit-darwin-arm64
+6ea361e856a42d69e21cc2037bbe949f3e96fdf5b00412f526b1a09d08bf104f  plugkit-linux-x64
+2caa17f4c162ad8fbd2f92ca9432344449313ffc8f75983210ada7ed481cbc03  plugkit-linux-arm64

package/bin/plugkit.version

@@ -1 +1 @@
-0.1.241
+0.1.256

package/cli.js

@@ -28,6 +28,87 @@ try {
 
   filesToCopy.forEach(([src, dst]) => copyRecursive(path.join(srcDir, src), path.join(destDir, dst)));
 
+  const SENTINEL_START = '# >>> gm-codex managed (do not edit between sentinels)';
+  const SENTINEL_END = '# <<< gm-codex managed';
+  const tomlString = (s) => '"' + String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+  const expand = (cmd, root) => String(cmd).split('${CODEX_PLUGIN_ROOT}').join(root);
+  function buildHooksToml(hooksJson, root) {
+    const hooks = (hooksJson && hooksJson.hooks) || {};
+    const lines = [];
+    for (const event of Object.keys(hooks)) {
+      for (const group of (hooks[event] || [])) {
+        const matcher = group.matcher || '*';
+        const entries = group.hooks || [];
+        if (!entries.length) continue;
+        lines.push('', '[[hooks.' + event + ']]', 'matcher = ' + tomlString(matcher));
+        for (const e of entries) {
+          lines.push('', '[[hooks.' + event + '.hooks]]');
+          lines.push('type = ' + tomlString(e.type || 'command'));
+          lines.push('command = ' + tomlString(expand(e.command, root)));
+          const t = typeof e.timeout === 'number' ? Math.max(1, Math.round(e.timeout / 1000)) : 60;
+          lines.push('timeout = ' + t);
+        }
+      }
+    }
+    return lines.join('\n');
+  }
+  function buildMcpToml(mcpJson) {
+    const servers = (mcpJson && mcpJson.mcpServers) || {};
+    const lines = [];
+    for (const id of Object.keys(servers)) {
+      const s = servers[id];
+      lines.push('', '[mcp_servers.' + id + ']');
+      if (s.command) lines.push('command = ' + tomlString(s.command));
+      if (Array.isArray(s.args)) lines.push('args = [' + s.args.map(tomlString).join(', ') + ']');
+      if (s.cwd) lines.push('cwd = ' + tomlString(s.cwd));
+      if (s.url) lines.push('url = ' + tomlString(s.url));
+      if (s.env && typeof s.env === 'object') {
+        lines.push('', '[mcp_servers.' + id + '.env]');
+        for (const k of Object.keys(s.env)) lines.push(k + ' = ' + tomlString(s.env[k]));
+      }
+    }
+    return lines.join('\n');
+  }
+  function buildSkillsToml(skillsDir) {
+    if (!fs.existsSync(skillsDir)) return '';
+    const lines = [];
+    for (const ent of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+      if (!ent.isDirectory()) continue;
+      const sp = path.join(skillsDir, ent.name);
+      if (!fs.existsSync(path.join(sp, 'SKILL.md'))) continue;
+      lines.push('', '[[skills.config]]', 'path = ' + tomlString(sp), 'enabled = true');
+    }
+    return lines.join('\n');
+  }
+  function stripManagedBlock(content) {
+    if (!content) return '';
+    const i = content.indexOf(SENTINEL_START);
+    if (i === -1) return content;
+    const j = content.indexOf(SENTINEL_END, i);
+    if (j === -1) return content;
+    return (content.slice(0, i).replace(/\n*$/, '\n') + content.slice(j + SENTINEL_END.length).replace(/^\n+/, '')).replace(/\n{3,}/g, '\n\n');
+  }
+  function buildBlock(root) {
+    const hooksJson = fs.existsSync(path.join(root, 'hooks', 'hooks.json')) ? JSON.parse(fs.readFileSync(path.join(root, 'hooks', 'hooks.json'), 'utf8')) : { hooks: {} };
+    const mcpJson = fs.existsSync(path.join(root, '.mcp.json')) ? JSON.parse(fs.readFileSync(path.join(root, '.mcp.json'), 'utf8')) : { mcpServers: {} };
+    const parts = [SENTINEL_START, '', '[features]', 'codex_hooks = true', buildHooksToml(hooksJson, root), buildMcpToml(mcpJson), buildSkillsToml(path.join(root, 'skills')), '', SENTINEL_END];
+    return parts.filter(p => p !== '').join('\n').replace(/\n{3,}/g, '\n\n') + '\n';
+  }
+  function mergeCodexToml(configPath, root) {
+    const existing = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8') : '';
+    const stripped = stripManagedBlock(existing).replace(/\s+$/, '');
+    const block = buildBlock(root);
+    const next = stripped ? stripped + '\n\n' + block : block;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, next);
+  }
+  try {
+    mergeCodexToml(path.join(homeDir, '.codex', 'config.toml'), destDir);
+    console.log('✓ wired ~/.codex/config.toml (managed block)');
+  } catch (e) {
+    console.warn('Warning: failed to wire codex config.toml:', e.message);
+  }
+
   const destPath = process.platform === 'win32' ? destDir.replace(/\\/g, '/') : destDir;
   console.log(`✓ gm-codex ${isUpgrade ? 'upgraded' : 'installed'} to ${destPath}`);
   console.log('Restart Codex to activate.');

package/gm.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.726",
+  "version": "2.0.788",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "author": "AnEntrypoint",
   "license": "MIT",
@@ -23,5 +23,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "plugkitVersion": "0.1.241"
+  "plugkitVersion": "0.1.256"
 }

package/hooks/hooks.spec.json

@@ -0,0 +1,73 @@
+{
+  "schemaVersion": 1,
+  "description": "Hook spec for gm Codex extension",
+  "envVar": "CODEX_PLUGIN_ROOT",
+  "plugkitInvoker": "node",
+  "events": [
+    {
+      "eventKey": "PreToolUse",
+      "commands": [
+        {
+          "kind": "plugkit",
+          "subcommand": "pre-tool-use",
+          "timeout": 3600
+        },
+        {
+          "kind": "js",
+          "file": "pre-tool-use-hook.js",
+          "timeout": 2000
+        }
+      ]
+    },
+    {
+      "eventKey": "PostToolUse",
+      "commands": [
+        {
+          "kind": "js",
+          "file": "post-tool-use-hook.js",
+          "timeout": 3000
+        }
+      ]
+    },
+    {
+      "eventKey": "SessionStart",
+      "commands": [
+        {
+          "kind": "plugkit",
+          "subcommand": "session-start",
+          "timeout": 180000
+        }
+      ]
+    },
+    {
+      "eventKey": "UserPromptSubmit",
+      "commands": [
+        {
+          "kind": "plugkit",
+          "subcommand": "prompt-submit",
+          "timeout": 60000
+        },
+        {
+          "kind": "js",
+          "file": "prompt-submit-hook.js",
+          "timeout": 3000
+        }
+      ]
+    },
+    {
+      "eventKey": "Stop",
+      "commands": [
+        {
+          "kind": "plugkit",
+          "subcommand": "stop",
+          "timeout": 15000
+        },
+        {
+          "kind": "plugkit",
+          "subcommand": "stop-git",
+          "timeout": 210000
+        }
+      ]
+    }
+  ]
+}

package/install.js

@@ -50,6 +50,88 @@ function install() {
   try { fs.copyFileSync(path.join(sourceDir, 'README.md'), path.join(codexDir, 'README.md')); } catch {}
   try { fs.copyFileSync(path.join(sourceDir, 'CLAUDE.md'), path.join(codexDir, 'CLAUDE.md')); } catch {}
   try { fs.copyFileSync(path.join(sourceDir, 'AGENTS.md'), path.join(codexDir, 'AGENTS.md')); } catch {}
+
+  const SENTINEL_START = '# >>> gm-codex managed (do not edit between sentinels)';
+  const SENTINEL_END = '# <<< gm-codex managed';
+  const tomlString = (s) => '"' + String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+  const expand = (cmd, root) => String(cmd).split('${CODEX_PLUGIN_ROOT}').join(root);
+  function buildHooksToml(hooksJson, root) {
+    const hooks = (hooksJson && hooksJson.hooks) || {};
+    const lines = [];
+    for (const event of Object.keys(hooks)) {
+      for (const group of (hooks[event] || [])) {
+        const matcher = group.matcher || '*';
+        const entries = group.hooks || [];
+        if (!entries.length) continue;
+        lines.push('', '[[hooks.' + event + ']]', 'matcher = ' + tomlString(matcher));
+        for (const e of entries) {
+          lines.push('', '[[hooks.' + event + '.hooks]]');
+          lines.push('type = ' + tomlString(e.type || 'command'));
+          lines.push('command = ' + tomlString(expand(e.command, root)));
+          const t = typeof e.timeout === 'number' ? Math.max(1, Math.round(e.timeout / 1000)) : 60;
+          lines.push('timeout = ' + t);
+        }
+      }
+    }
+    return lines.join('\n');
+  }
+  function buildMcpToml(mcpJson) {
+    const servers = (mcpJson && mcpJson.mcpServers) || {};
+    const lines = [];
+    for (const id of Object.keys(servers)) {
+      const s = servers[id];
+      lines.push('', '[mcp_servers.' + id + ']');
+      if (s.command) lines.push('command = ' + tomlString(s.command));
+      if (Array.isArray(s.args)) lines.push('args = [' + s.args.map(tomlString).join(', ') + ']');
+      if (s.cwd) lines.push('cwd = ' + tomlString(s.cwd));
+      if (s.url) lines.push('url = ' + tomlString(s.url));
+      if (s.env && typeof s.env === 'object') {
+        lines.push('', '[mcp_servers.' + id + '.env]');
+        for (const k of Object.keys(s.env)) lines.push(k + ' = ' + tomlString(s.env[k]));
+      }
+    }
+    return lines.join('\n');
+  }
+  function buildSkillsToml(skillsDir) {
+    if (!fs.existsSync(skillsDir)) return '';
+    const lines = [];
+    for (const ent of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+      if (!ent.isDirectory()) continue;
+      const sp = path.join(skillsDir, ent.name);
+      if (!fs.existsSync(path.join(sp, 'SKILL.md'))) continue;
+      lines.push('', '[[skills.config]]', 'path = ' + tomlString(sp), 'enabled = true');
+    }
+    return lines.join('\n');
+  }
+  function stripManagedBlock(content) {
+    if (!content) return '';
+    const i = content.indexOf(SENTINEL_START);
+    if (i === -1) return content;
+    const j = content.indexOf(SENTINEL_END, i);
+    if (j === -1) return content;
+    return (content.slice(0, i).replace(/\n*$/, '\n') + content.slice(j + SENTINEL_END.length).replace(/^\n+/, '')).replace(/\n{3,}/g, '\n\n');
+  }
+  function buildBlock(root) {
+    const hooksJson = fs.existsSync(path.join(root, 'hooks', 'hooks.json')) ? JSON.parse(fs.readFileSync(path.join(root, 'hooks', 'hooks.json'), 'utf8')) : { hooks: {} };
+    const mcpJson = fs.existsSync(path.join(root, '.mcp.json')) ? JSON.parse(fs.readFileSync(path.join(root, '.mcp.json'), 'utf8')) : { mcpServers: {} };
+    const parts = [SENTINEL_START, '', '[features]', 'codex_hooks = true', buildHooksToml(hooksJson, root), buildMcpToml(mcpJson), buildSkillsToml(path.join(root, 'skills')), '', SENTINEL_END];
+    return parts.filter(p => p !== '').join('\n').replace(/\n{3,}/g, '\n\n') + '\n';
+  }
+  function mergeCodexToml(configPath, root) {
+    const existing = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8') : '';
+    const stripped = stripManagedBlock(existing).replace(/\s+$/, '');
+    const block = buildBlock(root);
+    const next = stripped ? stripped + '\n\n' + block : block;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, next);
+  }
+  try {
+    mergeCodexToml(path.join(projectRoot, '.codex', 'config.toml'), codexDir);
+    console.log('✓ wired ~/.codex/config.toml (managed block)');
+  } catch (e) {
+    console.warn('Warning: failed to wire codex config.toml:', e.message);
+  }
+
 }
 
 install();

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "gm-codex",
-  "version": "2.0.726",
+  "version": "2.0.788",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "author": "AnEntrypoint",
   "license": "MIT",
   "main": "plugin.json",
   "bin": {
     "gm-codex": "./cli.js",
-    "gm-codex-install": "./install.js"
+    "gm-codex-install": "./install.js",
+    "gm-codex-uninstall": "./uninstall.js"
   },
   "repository": {
     "type": "git",
@@ -41,7 +42,8 @@
     "plugin.json",
     "gm.json",
     "cli.js",
-    "install.js"
+    "install.js",
+    "uninstall.js"
   ],
   "keywords": [
     "codex",
@@ -51,4 +53,4 @@
     "automation",
     "gm"
   ]
-}
+}

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.726",
+  "version": "2.0.788",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "author": {
     "name": "AnEntrypoint",

package/skills/gm/SKILL.md

@@ -41,36 +41,59 @@ Multiple facts → parallel Agent calls in ONE message. End-of-turn: scan for un
 
 ## AUTONOMY — HARD RULE
 
-Default = autonomous execution. Emit PRD, run it to completion, push. Do NOT ask the user mid-task.
+A written PRD is the user's authorization. Once it exists, EXECUTE owns the work to COMPLETE. Resolve every doubt that arises during execution by witnessed probe, by recall, or by re-reading the PRD — never by asking the user. Any question whose answer the agent could obtain itself is a question the agent owes itself, not the user.
 
-Forbidden patterns:
-- "Should I continue with X?" / "Want me to do Y next?" / "Want me to also Z?"
-- "This is a lot — should I do A first and confirm?" / "Two options: A or B, which?"
-- Pre-confirmation before multi-file edits when scope is already clear
-- Stopping after partial completion to summarize and await direction
+**FINISH ALL REMAINING STEPS — HARD RULE**: when a request enumerates or implies multiple work items ("all", "any", "everything", "the rest", "remaining"), or after a covering family is constructed under MAXIMAL COVER, the agent finishes every witnessable item in the same turn. Stopping after one item to ask "which next?" is forbidden — the answer is *all of them*, in one chain, until `.gm/prd.yml` is empty and git is clean and pushed. Mid-chain "should I…", "want me to…", "which would you like…" prompts are forced closure; replace them with the next skill invocation.
 
-Permitted asking (last resort only, when absolutely necessary):
-- Destructive-irreversible decision with no prior context AND no PRD coverage
-- User intent genuinely ambiguous AND cannot be inferred from PRD/memory/code
-- Channel: prefer `exec:pause` (renames .gm/prd.yml → .gm/prd.paused.yml; question lives in header). In-conversation asking is last-resort only.
+Asking is permitted only as a last resort, when the next action is destructive-irreversible AND the PRD does not cover it, OR when user intent is genuinely irrecoverable from PRD, memory, code, AND the public web. The channel is structured: `exec:pause` (renames `.gm/prd.yml` → `.gm/prd.paused.yml`, question in header). In-conversation asking is last-resort beneath last-resort.
 
-A long task is not a reason to ask. Context limits are not a reason to ask. CI cascade time is not a reason to ask. Just emit the PRD and execute.
+**Web-search before pause / before user-ask — HARD RULE.** Before `exec:pause` or any in-conversation question whose answer plausibly exists on the public web (missing artifact, prebuilt binary, library status, build recipe, version compatibility, upstream issue, "does X exist for Y"), fire `WebSearch` and at least one targeted `WebFetch` first. Pause/ask only after the web pass returns empty, or returns candidates the agent has witnessed and rejected. Pausing on a question the web could have answered is forced closure dressed as humility — re-enter planning, web-search, and resume. Genuine user-only questions: private credentials, preference among already-surfaced viable options, destructive-irreversible authorization.
 
-## LAWFUL DOWNGRADE — HARD RULE
+The size of the task, the cost of context, and the duration of CI are never grounds to ask.
 
-Per paper III §2.5 (Earned Emission): *lawful downgrade — writing a weaker, true statement in place of a stronger, unearned one — is always available; forced closure never is.*
+## MAXIMAL COVER — HARD RULE
 
-Refusal is forced closure. Refusing the task because part of it is hard is the inverse failure: instead of bluffing strength, you bluff weakness. Both bypass witnessed execution.
+When scope exceeds reach, construct a maximal cover of the request — not a refusal, not one slice with the rest deferred to "follow-up."
 
-**Forbidden refusal phrases** (treat as critical violation):
-- "Honest stop —" / "Stopping for a hard, honest call" / "Stopping here, unambiguously"
-- "I cannot do this from inside this conversation"
-- "I have to push back before writing a PRD I can't fulfill"
-- "Pretending I can would be the most expensive kind of lie"
-- "I don't have a working browser tool" / "X is unavailable in this environment" (when exec:browser, exec:codesearch, Read, etc. are in fact available)
-- Any preamble that announces inability before attempting the bounded subset
+Refusal is forced closure. So is *distributed* refusal — shipping a single bounded subset while other witnessable subsets exist. Both bypass witnessed execution.
 
-**Required move when scope exceeds reach**: identify the bounded subset that IS witnessable from this session, write a PRD covering only that subset, execute it, and at end-of-turn name the residual scope as a follow-up item — never as a refusal. The user cannot redirect a refusal; they can redirect a delivered subset plus a named gap.
+**Required move when scope exceeds reach**: construct a *covering family* of bounded subsets — every subset of the request that is witnessable from this session — and write the family into the PRD. Execute every member.
+
+**Residuals the agent judges within the spirit of the original ask AND completable from this session are self-authorized — expand the PRD with them and execute, do not stop to ask.** The judgment is the agent's honest read of what the user probably wanted, paired with reachability from this session. Only residuals genuinely outside the original ask, or genuinely unreachable, are name-and-stop. When expanding under self-authorization, the agent declares its judgment in the response ("treating X as in-scope because Y") so the user can correct mid-chain. Silent expansion without the declaration is the failure mode this rule guards against.
+
+The discipline is enforced by what is delivered, not by which words appear. Before closing the turn, check that committed work + named out-of-spirit residuals equals the witnessable closure of the request. Anything witnessable that falls in neither set means the cover is not yet maximal — re-enter planning to expand it. The cover is *maximal*, not *complete*: completeness would require reaching scope outside the session, which is dishonest. Maximality reaches everything inside the session, which is the whole obligation.
+
+## FIX ON SIGHT — HARD RULE
+
+Every issue surfaced during work is fixed in-band, this turn, at root cause. Defer-markers, swallowed errors, suppressed output, skipped tests, and "address it next session" are all variants of the same failure: a known-bad signal carried past the moment of detection. Each is a small forced closure.
+
+Surface → diagnose → fix at root cause → re-witness → continue. If the fix uncovers a new unknown, regress to `planning`. If the fix is itself genuinely out-of-scope-irreversible, the residual goes into `.gm/prd.yml` *before* moving on — narration is not a substitute for an item.
+
+A skill chain that ships while ignoring a known-bad signal is forced closure (see MAXIMAL COVER).
+
+## BROWSER WITNESS — HARD RULE
+
+Editing code that runs in a browser requires a live `exec:browser` witness in the same turn as the edit. The witness does not defer to a later phase; later phases re-witness on top, they do not replace this one.
+
+Protocol on every client edit:
+1. Boot the real surface — server up, page reachable, HTTP 200 witnessed.
+2. `exec:browser` → navigate → poll for the global the change affects.
+3. `page.evaluate` asserting the specific invariant the change establishes. Capture the witnessed numbers in the response.
+4. Variance from expectation → fix at root cause, re-witness (FIX ON SIGHT). Never advance on unwitnessed client behavior.
+
+Pure-prose edits to static documents with no JS/canvas/DOM behavior change are exempt; tag the exemption explicitly with the reason so the skip is auditable. Silent skip on actual behavior change is forced closure.
+
+This rule fires in EXECUTE (witness on edit), EMIT (post-emit verify), and VERIFY (final gate). All three.
+
+## NOTHING FAKE — HARD RULE
+
+What ships runs against real services, real data, real binaries. Stubs, mocks, placeholder returns, fixture-only paths, "TODO: implement", `return null /* fake */`, hardcoded sample responses, and demo-mode fallbacks are forbidden in source the user will run. They produce green checks that survive into production and lie about what works.
+
+Scaffolding and shims are permitted when they call through to real behavior — an empty file laid down before its body, a thin adapter wrapping an upstream API, a build target that compiles but is wired to nothing yet *and is the only callsite of itself*. The test is whether the artifact, executed, would do the thing it claims. If it would not, it is a stub.
+
+Before writing a shim or adapter, the agent asks whether an existing library or tool already provides the same surface. Maintaining a local reimplementation of something an upstream package solves is its own failure mode — the shim drifts, ages, and accumulates the bugs the upstream already fixed. If a published package fits, the shim becomes one line of import.
+
+Stub detection is by behavior, not by keyword: code paths that always succeed, always return the same value regardless of input, or short-circuit a real call to satisfy a type signature, are stubs. Comments asserting realness do not make code real. The witnessing rule that closes a mutable also closes this one — until real input has produced real output through the new code, it is provisional, and shipping provisional code as done is forced closure.
 
 ## EXECUTION ORDER
 

package/skills/gm-complete/SKILL.md

@@ -59,7 +59,9 @@ Required protocol:
 
 Long-running probes: split into navigate-call → `exec:wait N` → probe-call to stay under the per-call budget. Do not stack multi-second `setTimeout` inside one `exec:browser` invocation.
 
-Exempt only when: change is server-only with zero browser-facing surface, OR repository has no browser surface at all (pure CLI/library). Tag the exemption in the response with the reason; do not silently skip.
+Exempt only when: change is server-only with zero browser-facing surface, OR repository has no browser surface at all (pure CLI/library). Exemption requires explicit tag in the response: `BROWSER EXEMPT: <reason — must reference diff paths showing zero browser-facing surface>`. Silent skip = forced-closure failure. Default posture is NOT exempt — burden is on the agent to prove exemption with diff evidence, not to assume it.
+
+**Pre-flight check before declaring complete**: run `git diff --name-only origin/main..HEAD` and grep for `client/|docs/|\.html$|\.glsl$|\.frag$|\.vert$`. Any hit AND no `exec:browser` block in this session = mandatory regression to `gm-execute` to witness the change live. No exceptions for "small CSS tweak" or "obvious string change".
 
 ## INTEGRATION TEST GATE
 
@@ -89,6 +91,10 @@ Stop hook watches all GitHub Actions runs for the pushed HEAD. Do not call `gh r
 - Failure → Stop blocks with run names+IDs → investigate with `gh run view <id> --log-failed`, fix, push, hook re-watches
 - Deadline 180s (override `GM_CI_WATCH_SECS`) → slow jobs get "still in progress" approve
 
+## FIX ON SIGHT — HARD RULE
+
+Any issue surfaced during verify (test.js failure, browser-validation mismatch, CI red, git-status dirt, hygiene-sweep finding, stress-suite flunk, observability gap) is fixed in-band before declaring complete. Never paper over, never `.skip`, never ship-and-followup, never silence stderr/CI signals. Failure routes to the owning phase: broken output → `gm-emit` | wrong logic → `gm-execute` | new unknown → `planning`. Never declare COMPLETE while a known-bad signal is live.
+
 ## HYGIENE SWEEP
 
 Before declaring complete:

package/skills/gm-emit/SKILL.md

@@ -67,6 +67,10 @@ console.log(await fn(realInput));
 - All facts resolved this phase memorized via background Agent(memorize)
 - CHANGELOG.md updated; TODO.md cleared/deleted
 
+## FIX ON SIGHT — HARD RULE
+
+Pre-emit run, post-emit run, or legitimacy gate surfaces ANY issue (failing assertion, stderr, type/lint error, unexpected variance, broken import, runtime throw) → fix at root cause this turn, re-run pre-emit AND post-emit, advance only when all gates pass simultaneously. Never write-and-promise-fix-later, never `try/catch`-to-hide, never `.skip`, never silence with redirection. Known variance → fix and re-verify (self-loop). Unknown variance → regress to `planning`.
+
 ## CODE EXECUTION
 
 `exec:<lang>` only. File writes via exec:nodejs + require('fs'). Never Bash(node/npm/npx/bun).

package/skills/gm-execute/SKILL.md

@@ -118,6 +118,22 @@ Triggers: exec output answers prior unknown | CI log reveals root cause | code r
 
 N facts → N parallel Agent calls in ONE message. End-of-turn self-check mandatory.
 
+## FIX ON SIGHT — HARD RULE
+
+Issue surfaced mid-execution (failing test, exec stderr, broken import, runtime exception, lint/type error, deprecation warning, unexpected output) is fixed THIS turn, at root cause, in-band. Never `// TODO`, never `try/catch`-to-swallow, never `2>/dev/null`, never `.skip`, never "out of scope" inside the same file. Re-witness after fix. New unknown surfaced by the fix → regress to `planning`. Genuine out-of-scope → write a `.gm/prd.yml` item before continuing.
+
+## BROWSER WITNESS — HARD RULE
+
+Editing browser-facing code (under `client/`, `docs/`, `*.html`, shaders, page-bundle imports, served JS/CSS, gh-pages assets, anything imported by a browser entry, anything visible in DOM/canvas/WebGL) → live `exec:browser` witness in THIS phase, same turn as the edit. Not deferred to EMIT, not deferred to VERIFY — those layers re-witness on top, they don't replace this one.
+
+Protocol on every client edit:
+1. Boot server / open page → HTTP 200 witnessed
+2. `exec:browser` → `page.goto(url)` → poll the affected global (`window.__app.<system>`, `window.__debug.<module>`)
+3. `page.evaluate` asserting the specific invariant the change establishes — capture numbers
+4. Variance → fix at root cause, re-witness (FIX ON SIGHT). Never advance to EMIT on unwitnessed client behavior.
+
+Forbidden: `node test.js` green as a substitute | screenshot without evaluate | "I'll check it in VERIFY" then skipping | committing a client diff without an `exec:browser` block this turn. Exempt only for server-only / no-browser repos; tag the exemption explicitly.
+
 ## CONSTRAINTS
 
 **Never**: Bash(node/npm/npx/bun) | fake data | mocks | scattered tests | fallbacks | Grep/Glob/Find/Explore | sequential independent items | respond mid-phase | edit before witnessing | duplicate code | if/else where dispatch suffices | one-liners that obscure | reinvent native/library

package/skills/planning/SKILL.md

@@ -43,23 +43,55 @@ Runs until: .gm/prd.yml empty AND git clean AND all pushes confirmed AND CI gree
 
 ## AUTONOMY — HARD RULE
 
-PRD written → execute to COMPLETE without asking the user. No "should I continue", no "want me to do X next", no offering to split work.
+PRD written → execute to COMPLETE without asking the user. Doubts that arise during execution are resolved by witnessed probe, by recall, or by re-reading the PRD — never by asking. Any question whose answer is reachable from the agent's tools belongs to the agent, not the user.
 
-Asking permitted only as last resort: destructive-irreversible with no PRD coverage, OR user intent unrecoverable from PRD/memory/code. Channel: `exec:pause` (renames prd.yml → prd.paused.yml; question in header). In-conversation asking last-resort.
+Asking is last-resort: destructive-irreversible without PRD coverage, OR user intent irrecoverable from PRD/memory/code/web. Channel: `exec:pause` (renames `prd.yml` → `prd.paused.yml`; question in header). In-conversation asking is last-resort beneath last-resort.
 
-**Cannot stop while**: .gm/prd.yml has items | git uncommitted | git unpushed.
+**WEB-SEARCH BEFORE PAUSE — HARD RULE.** Before `exec:pause` for any blocking question whose answer could plausibly exist on the public web — missing artifact, unknown library/API, prebuilt binary, version compatibility, build recipe, upstream status — fire `WebSearch` and at least one `WebFetch` first. Only after the web pass returns empty (or returns options the agent then witnesses and rejects) is `exec:pause` legitimate. Pausing on a question the web could have answered is forced closure dressed up as humility — fix on sight by re-entering planning, web-searching, and resuming. The only questions that genuinely require user-ask are ones the public web cannot answer: private credentials, intent/preference between viable options the agent has *already surfaced*, destructive-irreversible authorization.
 
-## LAWFUL DOWNGRADE — HARD RULE
+**Cannot stop while**: `.gm/prd.yml` has items | git uncommitted | git unpushed.
 
-Per paper III §2.5: lawful downgrade is always available; forced closure (refusal) is never available. Refusing the task because part is out of reach is the inverse of bluffing — both bypass witnessed execution.
+## MAXIMAL COVER — HARD RULE
 
-Forbidden: "honest stop", "stopping for a hard call", "I cannot do this from inside this conversation", "pretending I can would be a lie", any preamble that announces inability before attempting the bounded subset.
+When scope exceeds reach, expand the cover. Don't refuse. Don't ship one slice with the rest abandoned as "follow-up" — that's distributed refusal: the same failure dressed up as triage.
 
-Required: identify the witnessable bounded subset, PRD-write it, execute it. Residual scope = follow-up item, never refusal.
+**Required move when scope exceeds reach**: construct a *covering family* — every bounded subset of the request that is witnessable from this session — and write the family into the PRD as separate items, with the dependency graph explicit so independent members parallelize. Execute every member.
 
-## SKIP PLANNING (DEFAULT for small work)
+**Residuals the agent judges within the spirit of the original ask AND completable from this session are self-authorized — expand the PRD with them and execute, do not stop to ask.** The judgment is the agent's honest read of what the user probably wanted, paired with reachability from this session. Only residuals genuinely outside the original ask, or genuinely unreachable from this session, are name-and-stop. When expanding under self-authorization, the agent declares its judgment in the response ("treating X as in-scope because Y") so the user can correct mid-chain. Silent expansion without the declaration is the failure mode this rule guards against.
 
-Skip if ANY: single-file single-concern edit | trivially bounded <5min | surgical user instructions | bug fix with identified root cause | zero unknowns. Heavy ceremony only for multi-file architectural work.
+Enforcement is on what is delivered, not on which words appear. Before closing the turn, check that committed work + named out-of-spirit residuals = witnessable closure of the request. Gap = cover not yet maximal → re-enter PLAN to expand.
+
+## FIX ON SIGHT — HARD RULE
+
+Every issue surfaced during planning, execution, or verification is fixed in-band, the same session, at root cause. A known-bad signal carried past the moment of detection — by deferral, suppression, silencing, skipping, or "next time" narration — is a small forced closure.
+
+Surface → diagnose → fix → re-witness → continue. New unknown surfaced by the fix → regress here. Genuinely out-of-scope-irreversible → the residual goes into `.gm/prd.yml` *before* moving on; narration is not a substitute for an item.
+
+## BROWSER WITNESS — HARD RULE
+
+A `.prd` item that touches browser-facing code is not plan-complete unless its acceptance criteria include a live `exec:browser` witness with a `page.evaluate` assertion against the specific invariant the change establishes. "Manual verification", "test.js passes", and "browser test optional" are all unwitnessed and therefore unacceptable.
+
+The trigger is functional, not a path-list: any change whose effect is observable in the DOM, canvas, WebGL surface, network frames captured by the page, or any global the page exposes, requires the browser witness. Pure-prose edits to static documents with no behavior change are exempt; the exemption is tagged on the item with the reason.
+
+Propagation: EXECUTE witnesses on edit, EMIT re-witnesses post-write, VERIFY runs the final gate. The plan must encode the rule so all three layers fire.
+
+## NOTHING FAKE — HARD RULE
+
+Plan items resolve when real input flows through real code into real output. Stubs, mocks, placeholder returns, fixture-only branches, "TODO: implement", and demo-mode short-circuits do not count as resolution — they are mutables wearing closed-status disguise.
+
+Acceptance criteria must witness behavior, not the existence of a function with the right name. "X is implemented" is not acceptance; "X called with real Y produces real Z" is. The agent that satisfies the criterion via a stub has built something that will lie when production calls it.
+
+Scaffolding and shims are permitted only when the shim *delegates* to real behavior — wraps an upstream API, calls a real subprocess, hits a real disk. Before adding a shim, the plan asks whether a published library or tool already provides that surface; maintaining a local reimplementation of an upstream solution is its own failure mode and the shim line should usually become an import line.
+
+The fake-detection test is behavioral: would the code, executed against the inputs it claims to accept, produce the outputs it claims to produce? If the answer requires "after we fill in the body" or "once X is wired up", the plan item is open, not done.
+
+## ORIENT — HARD RULE
+
+Open every plan with a parallel pack of `exec:recall` and `exec:codesearch` against the request's nouns. Hits land as `weak_prior`; misses confirm the unknown is fresh. The pack runs in one message — never serially. The agent that skips orient pays the same cost in fresh probes a turn later, plus the price of disagreeing with its own prior witness.
+
+## PRD — HARD RULE
+
+`./.gm/prd.yml` is the authorization. It is written before EXECUTE fires for any task that touches more than one line in one file. The cost of writing it equals the cost of skipping it; what the file buys is durable trace, resumability, and the cover-maximality check.
 
 ## PLAN PHASE — MUTABLE DISCOVERY
 
@@ -82,7 +114,7 @@ Client: `window.__debug` live registry; modules register on mount.
 
 `console.log` ≠ observability. Discovery of gap → add .prd item immediately, never deferred.
 
-**No parallel test runners or smoke pages.** Per paper II §5.4, `window.__debug` is THE registry. Creating dedicated `docs/smoke.js` / `docs/smoke-network.js` / `docs/test.html` / `*-playground.html` files is a parallel observability surface that fights the discipline — register surfaces in `window.__debug` instead. The single `test.js` at project root (see SINGLE INTEGRATION TEST POLICY) is the only out-of-page test asset.
+**No parallel observability surfaces.** `window.__debug` is THE in-page registry; `test.js` at project root is the sole out-of-page test asset. Any new file whose purpose is to exercise, smoke-test, demo, or sandbox in-page behavior outside that registry fights the discipline — extend the registry instead.
 
 ## .PRD FORMAT
 
@@ -124,6 +156,12 @@ Not parallelizable → invoke `gm-execute` directly.
 
 `exec:<lang>` only via Bash. File I/O via exec:nodejs + fs. Git directly in Bash. Never Bash(node/npm/npx/bun).
 
+File paths in `exec:nodejs` are platform-literal — node's `fs` does not auto-resolve POSIX shortcuts like `/tmp`. Use `os.tmpdir()` and `path.join` for portable temp paths; reserve `/tmp/...` for `exec:bash` heredocs where the shell rewrites the prefix.
+
+Every `exec:<lang>` and `exec:bash` call should pass `--timeout-ms <ms>` (mandatory at the rs-exec RPC layer; the CLI emits a transitional warning when omitted). On timeout, partial streamed output is preserved and the runner emits `[exec timed out after Nms; partial output above]` — treat the marker as authoritative truncation and re-issue with a higher budget rather than retrying blindly.
+
+**Utility-verb syntax**: `exec:wait`, `exec:sleep`, `exec:status`, `exec:close`, `exec:pause`, `exec:type`, `exec:runner`, `exec:kill-port`, `exec:recall`, `exec:memorize`, `exec:forget` all take their argument on the **next line** (heredoc body), never inline. `exec:status\n<task_id>` polls one task; bare `exec:status` lists all. `exec:sleep\n<task_id>` blocks until the task produces output or completes. `exec:close\n<task_id>` terminates and removes a task. Inline forms (`exec:status <id>`) are denied by the hook.
+
 `exec:codesearch` only — Glob/Grep/Find/Explore hook-blocked. Start 2 words → change/add one per pass → minimum 4 attempts before concluding absent.
 
 Pack runs: Promise.allSettled for parallel. Each idea own try/catch. Under 12s per call.
@@ -136,9 +174,23 @@ No comments. No scattered test files. 200-line limit per file. Fail loud. No dup
 
 ## SINGLE INTEGRATION TEST POLICY
 
-One `test.js` at project root. 200-line max. No `.test.js` / `.spec.js` / `__tests__/` / fixtures / mocks. Plain assertions, real data, real system. `gm-complete` runs it. Failure = regression to EXECUTE.
+One `test.js` at project root. **200-line hard cap.** No fixtures, mocks, or scattered test files under any naming convention. Plain assertions, real data, real system. `gm-complete` runs it. Failure = regression to EXECUTE.
+
+Any second test runner — under any name, in any directory — is a smuggled parallel surface and fights the discipline. If a behavior needs to be exercised in-page, register it in `window.__debug` and assert via `test.js`.
+
+**Purpose: maximum surface coverage in 200 lines.** test.js is a budget, not a target. Every line should witness a load-bearing behavior; redundant assertions are dead weight. Subsystems get *one* group each — combined groups (e.g. `profiles+observability+auth+context+cron+batch`) are the norm, not the exception. As thoth grew from 17 → 21 → 14 named groups while the surface tripled, the win came from collapsing per-subsystem groups into multi-subsystem ones.
+
+**Use overlap to exclude.** When subsystem A's test exercises B as a side effect, B does not need its own group — drop the redundant assertion. Examples that have proven out:
+- The agent-machine tool-loop test exercises bash dispatch → no separate bash test needed beyond a smoke-call inside the tools+toolsets group.
+- The dashboard test asserts the API surface AND that the registry has ≥N tools → covers tool registration coverage.
+- The plugins+memory group exercises observability metrics + achievements → no need for a separate plugins-extra group.
+- The gateway test exercising one platform plus a platform-stub-shape loop covers all 18 adapters in one group.
+
+**Adding a new subsystem:** first try to fold its assertion into the closest existing group. Only create a new group when the subsystem's failure mode is genuinely orthogonal (e.g. compressor's iterative-update behavior is not exercised by any other group). Test surface should grow linearly with subsystem count, not multiplicatively, and the line budget is the forcing function.
+
+**Pattern that works:** name combined groups by joining their subsystems with `+`, e.g. `home+config+skin`, `mcp+swe+distributions+account+credpool`, `env+pi+cli+tui+setup+website`. Future readers see the coverage at a glance. A group title with 4–6 components is healthy; a group with 1 component should be questioned.
 
-**Also forbidden**: `docs/smoke.js`, `docs/smoke-*.js`, `*-smoke.html`, `docs/test.html`, `docs/demo.html`, `*-playground.html`. These are smuggled second test runners. If a surface needs to be exercised in-page, register it in `window.__debug` and assert via `test.js`.
+**Hygiene at edit time:** every change to test.js prefers compaction over expansion. If `wc -l test.js > 200`, the discipline is *not* "split" — it's "merge groups + drop redundancy" until it fits. If the budget is genuinely insufficient for the load-bearing surface, the right move is to question whether the assertion is load-bearing, not to lift the cap.
 
 ## RESPONSE POLICY
 

package/skills/research/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: research
+description: Web research via parallel subagent fan-out. Use when a question needs the live web, spans multiple sources, requires comparison across vendors/papers/repos, or would saturate a single context window. Skip for one-page lookups answerable by a single WebFetch.
+allowed-tools: Task, WebFetch, WebSearch
+---
+
+# Research
+
+Lead orchestrates. Workers fetch. Findings converge. The lead never reads pages — workers do.
+
+## Shape of the work
+
+Breadth first, depth on demand. Open with a wide sweep that maps the terrain; commit deep dives only where the sweep surfaces something load-bearing. A narrow opening misses the alternative the user actually needed.
+
+Effort matches stakes. A single fact warrants one short fetch. A vendor comparison warrants a handful of workers, each owning one vendor. A landscape survey warrants ten or more, each owning one axis. Spending a fan-out on a fact wastes tokens; spending a fact-fetch on a landscape under-delivers.
+
+Workers run in parallel. Independent questions launch in one message, never serialized. Serial fan-out is the default failure mode — guard against it explicitly.
+
+## Worker contract
+
+Each worker receives: the precise question it owns, the shape of the answer (bullets, table row, prose paragraph), the boundary of what it must not pursue, and the destination path under `.gm/research/<slug>/<worker-id>.md` for its findings. Vague briefs produce vague returns; the lead's job is to make the brief unambiguous before spawning.
+
+Workers write structured findings to disk and return only a path plus a one-line summary. The lead reads paths it cares about; the rest stay on disk. Returning full prose through the agent boundary burns context that the synthesis pass needs.
+
+## Citations
+
+A claim without a source URL is a hallucination waiting to be quoted. Workers attach the URL and the quoted span beside every non-trivial assertion. The lead refuses to lift a claim into the final answer if its citation field is empty.
+
+## Source quality
+
+Content farms and SEO-optimised listicles outrank primary sources on most queries. Prefer vendor docs, RFCs, primary repos, dated blog posts from named authors, and academic preprints over aggregator pages. When two sources disagree, the older primary usually beats the newer aggregator.
+
+## Convergence
+
+Synthesis happens once, after all workers return. Mid-flight summarisation truncates findings the next worker would have built on. The lead holds the question, the workers' paths, and the synthesis prompt; everything else lives on disk.
+
+If a worker's return reveals a new axis the original plan missed, expand the fan-out — do not stretch an existing worker past its brief.
+
+## When not to fan out
+
+One question, one page, one fetch. A single `WebFetch` answers it. The fan-out machinery has overhead; spending it on a lookup is the same mistake as skipping it on a survey.
+
+## Handoff
+
+Final answer cites every load-bearing claim, names the workers' output paths for audit, and surfaces disagreements between sources rather than averaging them away.

package/skills/update-docs/SKILL.md

@@ -52,6 +52,10 @@ git commit -m "docs: update documentation to reflect session changes"
 git push -u origin HEAD
 ```
 
+## FIX ON SIGHT — HARD RULE
+
+Doc-write surfaces a stale claim, broken link, missing file referenced, or contradiction with disk → fix at root cause this turn (update doc to match disk, or fix code if disc is wrong). Never leave a known-false claim in docs. Push surfaces a CI failure → fix and re-push, do not declare complete.
+
 ## Fidelity Rules
 
 Every claim verifiable against disk: phase names match frontmatter, platform names match `platforms/`, file paths exist, constraint counts accurate. Unverifiable section → remove, don't speculate.

package/uninstall.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const homeDir = process.env.HOME || process.env.USERPROFILE || os.homedir();
+const pluginDir = path.join(homeDir, '.codex', 'plugins', 'gm-codex');
+const configPath = path.join(homeDir, '.codex', 'config.toml');
+const SENTINEL_START = '# >>> gm-codex managed (do not edit between sentinels)';
+const SENTINEL_END = '# <<< gm-codex managed';
+
+function stripManagedBlock(content) {
+  if (!content) return '';
+  const i = content.indexOf(SENTINEL_START);
+  if (i === -1) return content;
+  const j = content.indexOf(SENTINEL_END, i);
+  if (j === -1) return content;
+  return (content.slice(0, i).replace(/\n*$/, '\n') + content.slice(j + SENTINEL_END.length).replace(/^\n+/, '')).replace(/\n{3,}/g, '\n\n');
+}
+
+try {
+  if (fs.existsSync(pluginDir)) {
+    fs.rmSync(pluginDir, { recursive: true, force: true });
+    console.log('✓ removed ' + pluginDir);
+  }
+  if (fs.existsSync(configPath)) {
+    const before = fs.readFileSync(configPath, 'utf8');
+    const after = stripManagedBlock(before);
+    if (after !== before) {
+      if (after.trim() === '') {
+        fs.unlinkSync(configPath);
+        console.log('✓ removed empty ' + configPath);
+      } else {
+        fs.writeFileSync(configPath, after);
+        console.log('✓ stripped managed block from ' + configPath);
+      }
+    }
+  }
+  console.log('gm-codex uninstalled.');
+} catch (e) {
+  console.error('Uninstall failed:', e.message);
+  process.exit(1);
+}

package/.github/workflows/publish-npm.yml

@@ -1,44 +0,0 @@
-name: Publish to npm
-
-on:
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Publish to npm
-        run: |
-          PACKAGE=$(jq -r '.name' package.json)
-          VERSION=$(jq -r '.version' package.json)
-          echo "Package: $PACKAGE@$VERSION"
-
-          # Skip if this exact version is already on npm
-          PUBLISHED=$(npm view "$PACKAGE@$VERSION" version 2>/dev/null || echo "")
-          if [ "$PUBLISHED" = "$VERSION" ]; then
-            echo "✅ $PACKAGE@$VERSION already published - skipping"
-            exit 0
-          fi
-
-          echo "Publishing $PACKAGE@$VERSION..."
-          npm publish --access public 2>&1 | tee /tmp/npm-out.log; EXIT=${PIPESTATUS[0]}
-          if [ "$EXIT" != "0" ]; then
-            if grep -q "cannot publish over\|previously published" /tmp/npm-out.log; then
-              echo "⚠️  Version already published, skipping"
-            else
-              exit "$EXIT"
-            fi
-          fi
-          echo "✅ Published $PACKAGE@$VERSION"
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}