@albinocrabs/feynman 0.2.5 → 0.2.6

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "feynman",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Auto-inject ASCII diagram rules into Codex and Claude Code prompts.",
   "author": {
     "name": "apolenkov",

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this project are documented here.
 
+## 0.2.6 - 2026-05-08
+
+Changes since v0.2.5.
+
+### Features
+
+- harden feynman runtime checks
+- add roadmap phase uat risk patterns
+- add sdlc output patterns to feynman
+- add terminal-safe feynman rendering rules
+
+### Fixes
+
+- clarify terminal table rendering rules
+- harden feynman hook lifecycle
+
+### Documentation
+
+- restore GSD validation coverage
+
+### Tests
+
+- cover codex app-server hook visibility
+- cover ci threshold branches
+
+### Maintenance
+
+- use global gsd defaults
+- remove gsd model bindings from repo config
+
 ## 0.2.5 - 2026-05-08
 
 ### Features

package/README.md

@@ -22,7 +22,10 @@
   <a href="docs/object-passport.md">Passport</a> •
   <a href="#before--after">Before/After</a> •
   <a href="#install">Install</a> •
+  <a href="#verify-the-install">Verify</a> •
   <a href="#intensity-levels">Levels</a> •
+  <a href="#security-notes">Security</a> •
+  <a href="#token-budget-and-output-size">Tokens</a> •
   <a href="#lint">Lint</a> •
   <a href="#examples">Examples</a> •
   <a href="docs/launch.md">Launch</a> •
@@ -32,8 +35,8 @@
 ---
 
 A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and Codex
-plugin that automatically injects ASCII diagram rules into every prompt via the
-`UserPromptSubmit` hook.
+plugin that automatically injects ASCII diagram rules through `SessionStart`
+and `UserPromptSubmit` hooks.
 
 ```bash
 npx -y @albinocrabs/feynman@latest install --target all
@@ -173,16 +176,15 @@ feynman hook instead of adding duplicates.
 git clone https://github.com/apolenkov/feynman && bash feynman/install.sh
 ```
 
-Restart Claude Code or Codex. Done.
-
-**Verify:** `npx @albinocrabs/feynman doctor --target claude` or `npx @albinocrabs/feynman doctor --target codex`
+Restart Claude Code or Codex after install so a fresh `SessionStart` hook can
+prime the session.
 
 **Uninstall:** `npx @albinocrabs/feynman uninstall --target claude|codex|both|all|*`
 
 **Plugin manifests:** this repo also ships `.claude-plugin/plugin.json`,
-`hooks/hooks.json`, `.codex-plugin/plugin.json`, and `hooks.json` so plugin
-marketplaces can discover feynman. The npx installer remains the production
-fallback because both clients still support direct user hook registration.
+`hooks/hooks.json`, `.codex-plugin/plugin.json`, and `hooks.json` for direct
+client integrations. The npx installer remains the production fallback because
+both clients still support direct user hook registration.
 
 <details>
 <summary>Manual install</summary>
@@ -193,6 +195,18 @@ Add to `~/.claude/settings.json` — use the absolute path, not `~/`
 ```json
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"/absolute/path/to/feynman/hooks/feynman-session-start.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [
@@ -214,6 +228,18 @@ For Codex, add the same shape to `~/.codex/hooks.json` and set
 ```json
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FEYNMAN_HOME=\"$HOME/.codex\" node \"/absolute/path/to/feynman/hooks/feynman-session-start.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [
@@ -234,6 +260,37 @@ After install, feynman starts in `full` mode by default. Disable or change it
 explicitly with `/feynman off`, `/feynman lite`, `/feynman full`, or
 `/feynman ultra`.
 
+## Verify the install
+
+Run `doctor` after installing or after manually editing hooks:
+
+```bash
+npx @albinocrabs/feynman doctor --target codex
+npx @albinocrabs/feynman doctor --target claude
+npx @albinocrabs/feynman doctor --target all
+```
+
+A healthy target reports both hook events and both hook script files as `OK`:
+
+```text
+[OK] hook registered (feynman-session-start.js in SessionStart)
+[OK] hook registered (feynman-activate.js in UserPromptSubmit)
+[OK] session hook script file exists and is readable
+[OK] prompt hook script file exists and is readable
+Status: OK
+```
+
+For Codex, runtime state should live under `~/.codex`:
+
+```bash
+cat ~/.codex/.feynman/state.json
+test -f ~/.codex/.feynman-active
+```
+
+For Claude Code, use `~/.claude` instead of `~/.codex`. `doctor` fails if a
+registered hook command cannot be parsed to a real hook script, which catches
+stale or broken manual installs.
+
 ## Intensity Levels
 
 | Level | What draws | Use when |
@@ -278,6 +335,26 @@ This bypasses `~/.codex/hooks.json` hook execution entirely.
 Regular `/feynman off` and `/feynman on` continue to use normal profile state
 files (`~/.codex/.feynman-active`, `~/.codex/.feynman/state.json`).
 
+## Security notes
+
+feynman hooks are local prompt-context hooks. They do not require network
+access, do not read repository files, and do not read credentials. The active
+mode is stored only in the client-local state path:
+
+```text
+~/.claude/.feynman/state.json
+~/.codex/.feynman/state.json
+```
+
+The hook runtime treats invalid state as disabled for that turn, removes the
+activation flag, and stays silent. That prevents a corrupted state file from
+silently forcing diagram rules into future prompts.
+
+`uninstall` removes only feynman hook commands and preserves unrelated hooks in
+the same hook group. `doctor` validates that registered commands point to real
+hook scripts, so broken manual commands are visible before a session depends on
+them.
+
 ## CLI examples
 
 Quickly discover and view repository prompt templates:
@@ -492,15 +569,42 @@ the rules for the active intensity level, and inject them into model context.
 ```
 [your prompt]
       +
-[feynman rules]    ← injected by hook, ~2KB
+[feynman rules]    injected by hook
       │
       ▼
-  [Claude]
+ [Claude Code]
+      or
+   [Codex]
       │
       ▼
 [structured response with ASCII diagrams]
 ```
 
+## Token budget and output size
+
+feynman always adds some input context when it is enabled, because the active
+diagram rules are injected into the client prompt context. It does not add
+visible output by itself; output changes only when the assistant uses the
+rules.
+
+Current rule payload sizes are approximately:
+
+| Mode | Bytes | Approx tokens | Use when |
+| ---- | ----- | ------------- | -------- |
+| `lite` | 1307 | 317 | minimal flows and trees |
+| `full` | 2180 | 532 | default diagram coverage |
+| `ultra` | 1390 | 337 | force diagrams more often |
+
+The token count is a rough `chars / 4` estimate, not a billing counter. The
+actual number depends on the runtime tokenizer and surrounding hook envelope.
+
+The plugin can reduce output size when a diagram replaces repeated prose,
+especially for flows, status summaries, hierarchies, and comparisons. It can
+increase output for short answers where a diagram would be unnecessary, so the
+rules explicitly suppress diagrams for one- or two-sentence direct answers.
+Use `/feynman lite` for lower overhead or `/feynman off` when token budget is
+more important than visual structure.
+
 ## Release process
 
 Every push runs tests on Node 18 and 20 across Ubuntu and macOS. The release

package/SECURITY.md

@@ -39,4 +39,4 @@ Before publishing a new npm version:
 - GitHub release tag must match `package.json` version with a `v` prefix.
 - GitHub Actions secret `NPM_TOKEN` must be present for first publish of a new version.
 - npm provenance is enabled in the release workflow.
-- Registry smoke verification must pass after publish (`npm view`, install from npm, `feynman doctor --target both`).
+- Registry smoke verification must pass after publish (`npm view`, install from npm, `feynman doctor --target all`).

package/bin/feynman.js

@@ -109,7 +109,7 @@ ${c.bold('Options:')}
 ${c.bold('Examples:')}
   npx @albinocrabs/feynman install
   npx @albinocrabs/feynman install --target codex
-  npx @albinocrabs/feynman install --target both
+  npx @albinocrabs/feynman install --target all
   npx @albinocrabs/feynman install --target all
   npx @albinocrabs/feynman doctor
   feynman lint response.md
@@ -507,6 +507,14 @@ function writeSettings(target, settings) {
   fs.writeFileSync(cfg.settingsPath, JSON.stringify(settings, null, 2) + '\n');
 }
 
+function isFeynmanHookCommand(command) {
+  return typeof command === 'string' && (
+    command.includes('feynman-session-start.js') ||
+    command.includes('feynman-activate.js') ||
+    command.includes('feynman-lint.js')
+  );
+}
+
 function hasFeynmanHook(settings) {
   const promptHook = ((settings.hooks && settings.hooks.UserPromptSubmit) || []).some(g =>
     g.hooks && g.hooks.some(h => h.command && h.command.includes('feynman-activate.js'))
@@ -517,19 +525,40 @@ function hasFeynmanHook(settings) {
   return promptHook && sessionHook;
 }
 
+function hasAnyFeynmanHook(settings) {
+  if (!settings.hooks) return false;
+  return ['SessionStart', 'UserPromptSubmit', 'Stop'].some(eventName =>
+    ((settings.hooks && settings.hooks[eventName]) || []).some(g =>
+      g.hooks && g.hooks.some(h => isFeynmanHookCommand(h.command))
+    )
+  );
+}
+
+function extractHookScriptPath(command, scriptName) {
+  if (typeof command !== 'string') return null;
+  const escaped = scriptName.replace(/\./g, '\\.');
+  const quotedPattern = new RegExp("[\"']([^\"']*" + escaped + ")[\"']");
+  const quoted = command.match(quotedPattern);
+  if (quoted) return quoted[1];
+
+  const unquotedPattern = new RegExp("(?:^|\\s)(/[^\\s\"';&|<>]*" + escaped + ")(?=$|\\s)");
+  const unquoted = command.match(unquotedPattern);
+  return unquoted ? unquoted[1] : null;
+}
+
 function removeFeynmanHooks(settings) {
   if (!settings.hooks) return settings;
   for (const eventName of ['SessionStart', 'UserPromptSubmit', 'Stop']) {
     if (!Array.isArray(settings.hooks[eventName])) continue;
-    settings.hooks[eventName] = settings.hooks[eventName].filter(g =>
-      !(g.hooks && g.hooks.some(h =>
-        h.command && (
-          h.command.includes('feynman-session-start.js') ||
-          h.command.includes('feynman-activate.js') ||
-          h.command.includes('feynman-lint.js')
-        )
-      ))
-    );
+    settings.hooks[eventName] = settings.hooks[eventName]
+      .map(g => {
+        if (!Array.isArray(g.hooks)) return g;
+        return {
+          ...g,
+          hooks: g.hooks.filter(h => !isFeynmanHookCommand(h.command)),
+        };
+      })
+      .filter(g => !Array.isArray(g.hooks) || g.hooks.length > 0);
     if (settings.hooks[eventName].length === 0) {
       delete settings.hooks[eventName];
     }
@@ -675,7 +704,7 @@ function uninstallOne(target) {
   }
 
   const cfg = readSettings(target);
-  const hadHook = hasFeynmanHook(cfg);
+  const hadHook = hasAnyFeynmanHook(cfg);
   removeFeynmanHooks(cfg);
   writeSettings(target, cfg);
 
@@ -735,8 +764,7 @@ function cmdDoctor(opts = {}) {
     sessionHookRegistered = !!feynmanSessionEntry;
     if (feynmanSessionEntry) {
       const hookCmd = feynmanSessionEntry.hooks.find(h => h.command && h.command.includes('feynman-session-start.js')).command;
-      const match = hookCmd.match(/"([^"]+feynman-session-start\.js)"/);
-      if (match) sessionHookAbsPath = match[1];
+      sessionHookAbsPath = extractHookScriptPath(hookCmd, 'feynman-session-start.js');
     }
 
     const entries = (cfg.hooks && cfg.hooks.UserPromptSubmit) || [];
@@ -745,10 +773,8 @@ function cmdDoctor(opts = {}) {
     );
     hookRegistered = !!feynmanEntry;
     if (feynmanEntry) {
-      // Extract the path from command: node "/abs/path/to/feynman-activate.js"
       const hookCmd = feynmanEntry.hooks.find(h => h.command && h.command.includes('feynman-activate.js')).command;
-      const match = hookCmd.match(/"([^"]+feynman-activate\.js)"/);
-      if (match) hookAbsPath = match[1];
+      hookAbsPath = extractHookScriptPath(hookCmd, 'feynman-activate.js');
     }
   }
   check('hook registered (feynman-session-start.js in SessionStart)', sessionHookRegistered);
@@ -761,11 +787,6 @@ function cmdDoctor(opts = {}) {
       fs.accessSync(sessionHookAbsPath, fs.constants.R_OK);
       sessionHookFileOk = true;
     } catch (_) {}
-  } else if (sessionHookRegistered) {
-    try {
-      fs.accessSync(SESSION_HOOK_PATH, fs.constants.R_OK);
-      sessionHookFileOk = true;
-    } catch (_) {}
   }
   check('session hook script file exists and is readable', sessionHookFileOk);
 
@@ -775,12 +796,6 @@ function cmdDoctor(opts = {}) {
       fs.accessSync(hookAbsPath, fs.constants.R_OK);
       hookFileOk = true;
     } catch (_) {}
-  } else if (hookRegistered) {
-    // Hook registered but path extraction failed — check default location
-    try {
-      fs.accessSync(HOOK_PATH, fs.constants.R_OK);
-      hookFileOk = true;
-    } catch (_) {}
   }
   check('prompt hook script file exists and is readable', hookFileOk);
 

package/hooks/feynman-session-start.js

@@ -17,14 +17,6 @@ const RULES_PATH  = path.join(__dirname, '..', 'rules', 'feynman-activate.md');
 const DEFAULT_STATE = { enabled: true, intensity: 'full', injections: 0 };
 const VALID_INTENSITIES = ['lite', 'full', 'ultra'];
 
-function readState() {
-  try {
-    return { ...DEFAULT_STATE, ...JSON.parse(fs.readFileSync(STATE_PATH, 'utf8')) };
-  } catch (_) {
-    return { ...DEFAULT_STATE };
-  }
-}
-
 function writeState(state) {
   fs.mkdirSync(FEYNMAN_DIR, { recursive: true });
   fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
@@ -53,9 +45,16 @@ process.stdin.on('end', () => {
 
     const stateExists = fs.existsSync(STATE_PATH);
     const flagExists = fs.existsSync(FLAG_PATH);
-    const state = readState();
+    let state = { ...DEFAULT_STATE };
 
-    if (!stateExists) {
+    if (stateExists) {
+      try {
+        state = { ...DEFAULT_STATE, ...JSON.parse(fs.readFileSync(STATE_PATH, 'utf8')) };
+      } catch (_) {
+        try { fs.unlinkSync(FLAG_PATH); } catch (_) {}
+        process.exit(0);
+      }
+    } else {
       writeState(state);
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@albinocrabs/feynman",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Claude Code and Codex plugin that auto-injects ASCII diagram rules into every AI request via UserPromptSubmit hook",
   "license": "MIT",
   "author": "apolenkov",

package/rules/feynman-activate.md

@@ -111,6 +111,168 @@ Syntax:
   item-3
 ```
 
+### Terminal-safe rendering
+
+Tables are allowed when they stay readable in terminal chat. Wide Markdown
+tables are a rendering defect: convert them into a cleaner terminal layout
+instead of letting columns wrap unpredictably.
+
+Choose the layout by readability:
+
+```text
+short matrix -> Markdown table is OK
+status maps  -> ASCII frame blocks
+long rows    -> key-value bullets
+hierarchy    -> ASCII tree
+sequence     -> arrow flow
+comparison   -> max 3 columns, max 10 words per cell
+```
+
+Frame discipline:
+
+```text
++---- Status ----+
+| item-a | done  |
+| item-b | risk  |
++----------------+
+```
+
+- Keep frame rows visually aligned.
+- Keep diagram lines under about 88 columns when possible.
+- If a row becomes long, split it into bullets or grouped frames instead of
+  widening the table.
+- Optimize for human scanning: aligned labels, short cells, stable columns,
+  and no wrapped table rows.
+- Use plain ASCII frames with `+`, `-`, and `|` when terminal compatibility
+  matters.
+
+### SDLC output patterns
+
+For engineering status, retrospectives, handoffs, reviews, and release notes,
+choose a human-scannable shape before writing prose. Prefer compact blocks with
+explicit evidence over long narrative.
+
+Use these shapes:
+
+```text
+status       -> frame with state, branch, commit, checks, blocker
+retro        -> DONE / WORKED / FRAGILE / LEFT
+handoff      -> NOW / NEXT / FILES / COMMANDS / RISK
+review       -> FINDINGS first, then QUESTIONS, then SUMMARY
+incident     -> IMPACT / CAUSE / FIX / PREVENTION
+release      -> CHANGED / VERIFIED / RISK / ROLLBACK
+decision     -> CONTEXT / OPTIONS / CHOICE / CONSEQUENCE
+verification -> command -> result -> evidence -> gap
+roadmap      -> NOW / NEXT / LATER / BLOCKED
+phase        -> GOAL / SCOPE / PLAN / VERIFY / EXIT
+UAT          -> SCENARIO / EXPECTED / ACTUAL / RESULT
+risk register -> RISK / IMPACT / MITIGATION / OWNER
+```
+
+Status block pattern:
+
+```text
++---- Status ----+
+| repo    | name  |
+| branch  | main  |
+| commit  | abc12 |
+| checks  | PASS  |
+| blocker | none  |
++----------------+
+```
+
+Retro pattern:
+
+```text
+DONE:
+- landed change with evidence
+
+WORKED:
+- useful command or decision
+
+FRAGILE:
+- risk or assumption
+
+LEFT:
+- next executable action
+```
+
+Roadmap pattern:
+
+```text
+NOW:
+- current milestone or active phase
+
+NEXT:
+- next executable phase
+
+LATER:
+- deferred work
+
+BLOCKED:
+- dependency or decision needed
+```
+
+Phase pattern:
+
+```text
+GOAL:
+- promised outcome
+
+SCOPE:
+- included / excluded boundaries
+
+PLAN:
+- implementation path
+
+VERIFY:
+- command, test, or review evidence
+
+EXIT:
+- condition for done
+```
+
+UAT pattern:
+
+```text
+SCENARIO:
+- user action or workflow
+
+EXPECTED:
+- expected behavior
+
+ACTUAL:
+- observed behavior
+
+RESULT:
+- PASS / FAIL / BLOCKED
+```
+
+Risk register pattern:
+
+```text
+▲ high
+RISK:
+- what can go wrong
+IMPACT:
+- why it matters
+MITIGATION:
+- concrete control
+OWNER:
+- agent / human / system
+▼ low
+```
+
+Rules:
+
+- Put the answer first, evidence second, next action last.
+- Never bury blockers in prose; give them their own label.
+- For status and retro, avoid wide tables even when Markdown would be valid.
+- Prefer `PASS`, `FAIL`, `BLOCKED`, `not run`, and exact command names.
+- If verification was not run, say `not run` and name the command.
+- For Russian chat, keep prose Russian and keep commands, paths, config keys,
+  commits, and status labels in English.
+
 ### When no diagram appears
 
 Responses that are any of the following contain no diagram:
@@ -154,13 +316,74 @@ detail    | detail
 
 **Comparisons** — Same as full mode. Includes side-by-side ASCII columns.
 
-**Status summaries** — Same as full mode. Uses ┌─ frame blocks.
+**Status summaries** — Same as full mode. Uses ASCII `+---` frame blocks.
 
 **Priority orderings** — Same as full mode. Uses ▲▼ scale.
 
+### Terminal-safe rendering
+
+Tables are allowed when they are compact and readable. Wide Markdown tables are
+a rendering defect in terminal chat. Prefer ASCII frames, key-value bullets,
+trees, and short columns for long content. Keep diagram lines under about 88
+columns when possible. If content is long, split it into bullets or grouped
+frames instead of widening the visual block.
+
+### SDLC output patterns
+
+All full-mode SDLC patterns apply. In ultra mode, use them aggressively for any
+engineering status, retrospective, review, release, handoff, decision, or
+verification answer. The default shape is:
+
+```text
+[state] --> [evidence] --> [risk] --> [next]
+```
+
+For retrospectives, prefer:
+
+```text
+DONE / WORKED / FRAGILE / LEFT
+```
+
+For status answers, prefer:
+
+```text
++---- Status ----+
+| item    | state |
+| checks  | PASS  |
+| blocker | none  |
++----------------+
+```
+
 ### When no diagram appears
 
 The only response that contains no diagram is a single sentence of pure prose with no enumerable items, no steps, no comparisons, and no structure of any kind.
 
 All other responses — including those with two or more items, any named concept with sub-parts, any sequence of actions, any set of options — include an ASCII diagram.
 <!-- /ultra -->
+
+### Russian terminal chat visual guardrail
+
+For Russian terminal chat, avoid using ASCII frames as two-column tables when
+values contain long Cyrillic or mixed Cyrillic/Latin text. Visual alignment can
+look broken even when character counts are correct.
+
+Prefer bullets for long Russian status facts:
+
+Итог:
+- Что сделали: dtp-retro стал русским по умолчанию.
+- История: текущая session ищется автоматически.
+- Форма: сначала смысл, потом proof/details.
+- Статус: правки есть, commit ещё не сделан.
+
+Avoid frame rows like this for long Russian text:
+
+| что сделали | длинная русская строка ... |
+| история     | длинная смешанная строка ... |
+
+Rule:
+
+- frame with short values -> OK
+- long Russian value -> bullets
+- sequence -> arrows
+- comparison -> max 3 short columns
+- status with long text -> label bullets, not frame rows

package/skills/feynman/SKILL.md

@@ -26,11 +26,21 @@ Parse `$ARGUMENTS`:
 ```bash
 node -e "
 const fs = require('fs'), os = require('os'), path = require('path');
-const stateFile = path.join(os.homedir(), '.claude', '.feynman', 'state.json');
-const flagFile  = path.join(os.homedir(), '.claude', '.feynman-active');
+function clientHome() {
+  if (process.env.FEYNMAN_HOME) return process.env.FEYNMAN_HOME;
+  if (process.env.FEYNMAN_TARGET === 'codex') return path.join(os.homedir(), '.codex');
+  if (process.env.FEYNMAN_TARGET === 'claude') return path.join(os.homedir(), '.claude');
+  if (process.env.CODEX_HOME) return process.env.CODEX_HOME;
+  if (process.env.CODEX_THREAD_ID || process.env.CODEX_SANDBOX) return path.join(os.homedir(), '.codex');
+  if (process.env.CLAUDE_CONFIG_DIR) return process.env.CLAUDE_CONFIG_DIR;
+  return path.join(os.homedir(), '.claude');
+}
+const root = clientHome();
+const stateFile = path.join(root, '.feynman', 'state.json');
+const flagFile  = path.join(root, '.feynman-active');
 let st = {enabled: true, intensity: 'full', injections: 0};
 try { st = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch(e) {}
-console.log('enabled:', st.enabled, '| intensity:', st.intensity, '| injections:', (st.injections ?? st.count ?? 0), '| flag:', fs.existsSync(flagFile));
+console.log('target:', path.basename(root), '| enabled:', st.enabled, '| intensity:', st.intensity, '| injections:', (st.injections ?? st.count ?? 0), '| flag:', fs.existsSync(flagFile));
 "
 ```
 
@@ -39,18 +49,29 @@ console.log('enabled:', st.enabled, '| intensity:', st.intensity, '| injections:
 ```bash
 node -e "
 const fs = require('fs'), os = require('os'), path = require('path');
-const stateFile = path.join(os.homedir(), '.claude', '.feynman', 'state.json');
-const flagFile  = path.join(os.homedir(), '.claude', '.feynman-active');
+function clientHome() {
+  if (process.env.FEYNMAN_HOME) return process.env.FEYNMAN_HOME;
+  if (process.env.FEYNMAN_TARGET === 'codex') return path.join(os.homedir(), '.codex');
+  if (process.env.FEYNMAN_TARGET === 'claude') return path.join(os.homedir(), '.claude');
+  if (process.env.CODEX_HOME) return process.env.CODEX_HOME;
+  if (process.env.CODEX_THREAD_ID || process.env.CODEX_SANDBOX) return path.join(os.homedir(), '.codex');
+  if (process.env.CLAUDE_CONFIG_DIR) return process.env.CLAUDE_CONFIG_DIR;
+  return path.join(os.homedir(), '.claude');
+}
+const root = clientHome();
+const stateFile = path.join(root, '.feynman', 'state.json');
+const flagFile  = path.join(root, '.feynman-active');
 const arg = (process.argv[1] || '').trim().toLowerCase();
 const normalized = arg === 'start' ? 'on' : arg === 'stop' ? 'off' : arg;
 let st = {enabled: false, intensity: 'full', injections: 0};
 try { st = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch(e) {}
-if (normalized === 'on')  { st.enabled = true;  fs.writeFileSync(flagFile, st.intensity); }
+function writeFlag(value) { fs.mkdirSync(root, {recursive: true}); fs.writeFileSync(flagFile, value || 'full'); }
+if (normalized === 'on')  { st.enabled = true;  writeFlag(st.intensity); }
 if (normalized === 'off') { st.enabled = false; try { fs.unlinkSync(flagFile); } catch(e) {} }
-if (['lite','full','ultra'].includes(normalized)) { st.intensity = normalized; st.enabled = true; fs.writeFileSync(flagFile, normalized); }
+if (['lite','full','ultra'].includes(normalized)) { st.intensity = normalized; st.enabled = true; writeFlag(normalized); }
 fs.mkdirSync(path.dirname(stateFile), {recursive: true});
 fs.writeFileSync(stateFile, JSON.stringify(st, null, 2));
-console.log(JSON.stringify(st));
+console.log(JSON.stringify({target: path.basename(root), ...st}));
 " "$ARGUMENTS"
 ```