@albinocrabs/feynman 0.2.4 → 0.2.6

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "feynman",
-  "version": "0.2.4",
+  "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,53 @@
 
 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
+
+- add SessionStart hook priming alongside UserPromptSubmit reinforcement
+- keep full diagram rules enabled by default for Claude Code and Codex
+
+### Fixes
+
+- preserve explicit /feynman off behavior with silent hooks
+- keep feynman hooks quiet by omitting status messages
+
+### Maintenance
+
+- bump package and plugin manifest versions to 0.2.5
+- expand tests for SessionStart registration and runtime behavior
+
 ## 0.2.4 - 2026-05-07
 
 Changes since v0.2.2.

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,14 +195,25 @@ 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": [
           {
             "type": "command",
             "command": "node \"/absolute/path/to/feynman/hooks/feynman-activate.js\"",
-            "timeout": 5,
-            "statusMessage": "Injecting diagram rules..."
+            "timeout": 5
           }
         ]
       }
@@ -215,14 +228,25 @@ 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": [
           {
             "type": "command",
             "command": "FEYNMAN_HOME=\"$HOME/.codex\" node \"/absolute/path/to/feynman/hooks/feynman-activate.js\"",
-            "timeout": 5,
-            "statusMessage": "Injecting diagram rules..."
+            "timeout": 5
           }
         ]
       }
@@ -232,6 +256,41 @@ For Codex, add the same shape to `~/.codex/hooks.json` and set
 ```
 </details>
 
+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 |
@@ -276,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:
@@ -481,24 +560,51 @@ from day one.
 
 ## How it works
 
-The `UserPromptSubmit` hook fires on every Claude Code or Codex prompt. The
-hook reads the target-local state file (`~/.claude/.feynman/state.json` or
-`~/.codex/.feynman/state.json`), extracts the rules for the active intensity
-level, and injects them as `additionalContext` — invisible to you, visible to
-the model on every message.
+The `SessionStart` hook primes fresh Claude Code or Codex sessions with the
+active rules, and the `UserPromptSubmit` hook reinforces them on every prompt.
+Both hooks read the target-local state file
+(`~/.claude/.feynman/state.json` or `~/.codex/.feynman/state.json`), extract
+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

@@ -29,6 +29,7 @@ const HOME = os.homedir();
 
 // Hook script lives relative to this file
 const HOOK_PATH = path.resolve(__dirname, '..', 'hooks', 'feynman-activate.js');
+const SESSION_HOOK_PATH = path.resolve(__dirname, '..', 'hooks', 'feynman-session-start.js');
 const RULES_PATH = path.resolve(__dirname, '..', 'rules', 'feynman-activate.md');
 
 const DEFAULT_STATE = { enabled: true, intensity: 'full', injections: 0 };
@@ -108,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
@@ -425,11 +426,11 @@ Claude creates:
   ~/.claude/.feynman-active        — presence flag
 
 Codex creates:
-  ~/.codex/hooks.json              — UserPromptSubmit hook registration
+  ~/.codex/hooks.json              — SessionStart + UserPromptSubmit hook registration
   ~/.codex/.feynman/state.json     — feynman state (enabled, intensity, injections)
   ~/.codex/.feynman-active         — presence flag
 
-Idempotent by default: skips if feynman-activate.js entry already exists.
+Idempotent by default: skips if feynman hook entries already exist.
 `;
 
 const UNINSTALL_HELP = `${c.bold('feynman uninstall')} — remove feynman hook
@@ -451,11 +452,11 @@ ${c.bold('Usage:')}
 
 Checks:
   1. target hook config present
-  2. UserPromptSubmit hook references feynman-activate.js
-  3. Hook script file exists and is readable
+  2. SessionStart and UserPromptSubmit hooks reference feynman scripts
+  3. Hook script files exist and are readable
   4. Rules file exists and is non-empty
   5. state.json valid JSON with enabled field
-  6. .feynman-active flag present
+  6. .feynman-active flag matches enabled state
   7. (INFO) lint hook registered (optional)
 
 Exit code: always 0 (advisory only).
@@ -506,24 +507,61 @@ 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) {
-  return ((settings.hooks && settings.hooks.UserPromptSubmit) || []).some(g =>
+  const promptHook = ((settings.hooks && settings.hooks.UserPromptSubmit) || []).some(g =>
     g.hooks && g.hooks.some(h => h.command && h.command.includes('feynman-activate.js'))
   );
+  const sessionHook = ((settings.hooks && settings.hooks.SessionStart) || []).some(g =>
+    g.hooks && g.hooks.some(h => h.command && h.command.includes('feynman-session-start.js'))
+  );
+  return promptHook && sessionHook;
 }
 
-function removeFeynmanHooks(settings) {
-  if (!settings.hooks || !Array.isArray(settings.hooks.UserPromptSubmit)) return settings;
-  settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(g =>
-    !(g.hooks && g.hooks.some(h =>
-      h.command && (
-        h.command.includes('feynman-activate.js') ||
-        h.command.includes('feynman-lint.js')
-      )
-    ))
+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))
+    )
   );
-  if (settings.hooks.UserPromptSubmit.length === 0) {
-    delete settings.hooks.UserPromptSubmit;
+}
+
+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]
+      .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];
+    }
   }
   if (Object.keys(settings.hooks).length === 0) {
     delete settings.hooks;
@@ -534,10 +572,21 @@ function removeFeynmanHooks(settings) {
 function bootstrapState(target) {
   const cfg = targetConfig(target);
   fs.mkdirSync(cfg.feynmanDir, { recursive: true });
+  let state = DEFAULT_STATE;
   if (!fs.existsSync(cfg.statePath)) {
     fs.writeFileSync(cfg.statePath, JSON.stringify(DEFAULT_STATE, null, 2) + '\n');
+  } else {
+    try {
+      state = { ...DEFAULT_STATE, ...JSON.parse(fs.readFileSync(cfg.statePath, 'utf8')) };
+    } catch (_) {
+      fs.writeFileSync(cfg.statePath, JSON.stringify(DEFAULT_STATE, null, 2) + '\n');
+    }
+  }
+  if (state.enabled) {
+    fs.writeFileSync(cfg.flagPath, state.intensity || DEFAULT_STATE.intensity);
+  } else if (fs.existsSync(cfg.flagPath)) {
+    fs.unlinkSync(cfg.flagPath);
   }
-  fs.writeFileSync(cfg.flagPath, DEFAULT_STATE.intensity);
 }
 
 function installClaudeCommand() {
@@ -561,6 +610,7 @@ function installOne(target, opts) {
   // Read or create settings
   const cfg = readSettings(target);
   cfg.hooks = cfg.hooks || {};
+  cfg.hooks.SessionStart = cfg.hooks.SessionStart || [];
   cfg.hooks.UserPromptSubmit = cfg.hooks.UserPromptSubmit || [];
 
   // Idempotency check
@@ -572,20 +622,36 @@ function installOne(target, opts) {
     return { target, already: true };
   }
 
-  // If force + already, remove old entry first
+  // If force or partial legacy install, remove old feynman entries first.
   if (already && force) {
     removeFeynmanHooks(cfg);
     cfg.hooks = cfg.hooks || {};
+    cfg.hooks.SessionStart = cfg.hooks.SessionStart || [];
+    cfg.hooks.UserPromptSubmit = cfg.hooks.UserPromptSubmit || [];
+  } else if (!already) {
+    removeFeynmanHooks(cfg);
+    cfg.hooks = cfg.hooks || {};
+    cfg.hooks.SessionStart = cfg.hooks.SessionStart || [];
     cfg.hooks.UserPromptSubmit = cfg.hooks.UserPromptSubmit || [];
   }
 
-  // Append hook entry
+  // Append hook entries
+  const sessionEntry = {
+    hooks: [{
+      type: 'command',
+      command: hookCommandFor(target).replace(HOOK_PATH, SESSION_HOOK_PATH),
+      timeout: 5,
+    }]
+  };
+  if (target === 'codex') {
+    sessionEntry.matcher = 'startup|resume';
+  }
+  cfg.hooks.SessionStart.push(sessionEntry);
   cfg.hooks.UserPromptSubmit.push({
     hooks: [{
       type: 'command',
       command: hookCommandFor(target),
       timeout: 5,
-      statusMessage: 'Injecting diagram rules...',
     }]
   });
 
@@ -623,7 +689,7 @@ function cmdInstall(opts) {
   }
   console.log('└──────────────────────────────────────────────────────────────┘');
   console.log('');
-  console.log('Restart Claude Code or Codex to activate feynman.');
+  console.log('Restart Claude Code or Codex to activate feynman full mode.');
 
   process.exit(0);
 }
@@ -638,7 +704,7 @@ function uninstallOne(target) {
   }
 
   const cfg = readSettings(target);
-  const hadHook = hasFeynmanHook(cfg);
+  const hadHook = hasAnyFeynmanHook(cfg);
   removeFeynmanHooks(cfg);
   writeSettings(target, cfg);
 
@@ -684,40 +750,54 @@ function cmdDoctor(opts = {}) {
   const settingsExists = fs.existsSync(tc.settingsPath);
   check(`${tc.settingsPath.replace(HOME, '~')} present`, settingsExists);
 
-  // 2. UserPromptSubmit hook references feynman-activate.js
+  // 2. SessionStart and UserPromptSubmit hooks reference feynman scripts
+  let sessionHookRegistered = false;
   let hookRegistered = false;
+  let sessionHookAbsPath = null;
   let hookAbsPath = null;
   if (settingsExists) {
     const cfg = readSettings(target);
+    const sessionEntries = (cfg.hooks && cfg.hooks.SessionStart) || [];
+    const feynmanSessionEntry = sessionEntries.find(g =>
+      g.hooks && g.hooks.some(h => h.command && h.command.includes('feynman-session-start.js'))
+    );
+    sessionHookRegistered = !!feynmanSessionEntry;
+    if (feynmanSessionEntry) {
+      const hookCmd = feynmanSessionEntry.hooks.find(h => h.command && h.command.includes('feynman-session-start.js')).command;
+      sessionHookAbsPath = extractHookScriptPath(hookCmd, 'feynman-session-start.js');
+    }
+
     const entries = (cfg.hooks && cfg.hooks.UserPromptSubmit) || [];
     const feynmanEntry = entries.find(g =>
       g.hooks && g.hooks.some(h => h.command && h.command.includes('feynman-activate.js'))
     );
     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);
   check('hook registered (feynman-activate.js in UserPromptSubmit)', hookRegistered);
 
-  // 3. Hook script file exists + readable
+  // 3. Hook script files exist + readable
+  let sessionHookFileOk = false;
+  if (sessionHookAbsPath) {
+    try {
+      fs.accessSync(sessionHookAbsPath, fs.constants.R_OK);
+      sessionHookFileOk = true;
+    } catch (_) {}
+  }
+  check('session hook script file exists and is readable', sessionHookFileOk);
+
   let hookFileOk = false;
   if (hookAbsPath) {
     try {
       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('hook script file exists and is readable', hookFileOk);
+  check('prompt hook script file exists and is readable', hookFileOk);
 
   // 4. Rules file exists + non-empty
   let rulesOk = false;
@@ -729,15 +809,20 @@ function cmdDoctor(opts = {}) {
 
   // 5. state.json valid JSON + has enabled field
   let stateOk = false;
+  let stateEnabled = false;
   try {
     const state = JSON.parse(fs.readFileSync(tc.statePath, 'utf8'));
     stateOk = 'enabled' in state;
+    stateEnabled = state.enabled === true;
   } catch (_) {}
   check('state.json valid (has enabled field)', stateOk);
 
-  // 6. .feynman-active flag present
+  // 6. .feynman-active flag matches state
   const flagPresent = fs.existsSync(tc.flagPath);
-  check('.feynman-active flag present', flagPresent);
+  check(
+    stateEnabled ? '.feynman-active flag present when enabled' : '.feynman-active flag absent when disabled',
+    stateEnabled ? flagPresent : !flagPresent
+  );
 
   // 7. (INFO) lint hook registered
   let lintHookRegistered = false;

package/docs/architecture.md

@@ -6,16 +6,18 @@ Three independent layers: hook lifecycle, lint pipeline, and state schema.
 
 ## Layer 1: Hook Lifecycle
 
-The `UserPromptSubmit` hook fires before every Claude Code or Codex prompt.
-feynman intercepts the event, reads the active rules, and injects them as
-`additionalContext`.
+The `SessionStart` hook primes fresh Claude Code or Codex sessions with the
+active rules. The `UserPromptSubmit` hook fires before every prompt and
+reinforces the same rules as `additionalContext`.
 
 ```
 ~/.claude/settings.json       ~/.codex/hooks.json
          │
-         │  hooks.UserPromptSubmit fires on every prompt
+         ├─ hooks.SessionStart primes new sessions
+         │
+         └─ hooks.UserPromptSubmit reinforces every prompt
          ▼
-hooks/feynman-activate.js
+hooks/feynman-session-start.js + hooks/feynman-activate.js
          │
          ├─ [0] FEYNMAN_HOME selects client state root
          │        unset              → ~/.claude (backward compatible)
@@ -25,9 +27,10 @@ hooks/feynman-activate.js
          ├─ [1] validate session_id (path-traversal guard)
          │
          ├─ [2] $FEYNMAN_HOME/.feynman-active  ← flag file
-         │        absent + no state.json   → bootstrap first run
-         │        absent + state.json      → exit 0 (user disabled)
-         │        present                  → continue
+         │        absent + no state.json      → bootstrap first run
+         │        absent + state.enabled=true → recreate flag
+         │        absent + state.enabled=false → exit 0 (user disabled)
+         │        present                     → continue
          │
          ├─ [3] $FEYNMAN_HOME/.feynman/state.json
          │        enabled: false           → exit 0
@@ -121,7 +124,7 @@ All runtime state lives in two files under the selected client root:
 ~/.claude/ or ~/.codex/
 ├── .feynman-active          ← presence flag
 │     present  = feynman active
-│     absent   = user disabled (state.json preserved)
+│     absent   = user disabled only when state.enabled=false
 │     content  = current intensity string (informational)
 │
 └── .feynman/

package/hooks/feynman-activate.js

@@ -31,18 +31,25 @@ process.stdin.on('end', () => {
     if (sessionId && /[/\\]|\.\./.test(sessionId)) process.exit(0);
 
     // Step 2: flag file + first-run bootstrap (D-05, D-07, bug #35713)
-    // True first run: neither flag nor state exists → bootstrap both, then fall through
-    // Intentionally disabled: flag absent but state exists → exit 0 (user ran /feynman off)
+    // True first run: neither flag nor state exists -> bootstrap default full mode.
+    // Intentionally disabled: flag absent + state.enabled=false -> exit 0.
     const flagExists  = fs.existsSync(FLAG_PATH);
     const stateExists = fs.existsSync(STATE_PATH);
     if (!flagExists) {
       if (!stateExists) {
-        // First install — bootstrap everything and activate
+        // First install: bootstrap and activate full mode.
         fs.mkdirSync(FEYNMAN_DIR, { recursive: true });
         fs.writeFileSync(STATE_PATH, JSON.stringify(DEFAULT_STATE, null, 2));
         fs.writeFileSync(FLAG_PATH, DEFAULT_STATE.intensity);
       } else {
-        process.exit(0); // disabled intentionally by user
+        let existingState;
+        try {
+          existingState = { ...DEFAULT_STATE, ...JSON.parse(fs.readFileSync(STATE_PATH, 'utf8')) };
+        } catch (_) {
+          process.exit(0);
+        }
+        if (!existingState.enabled) process.exit(0);
+        fs.writeFileSync(FLAG_PATH, existingState.intensity || DEFAULT_STATE.intensity);
       }
     }
 

package/hooks/feynman-session-start.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// feynman — SessionStart hook — injects active diagram rules at session start.
+// UserPromptSubmit still reinforces rules every turn; this primes fresh sessions.
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const HOME        = os.homedir();
+const CLIENT_HOME = process.env.FEYNMAN_HOME || path.join(HOME, '.claude');
+const FEYNMAN_DIR = path.join(CLIENT_HOME, '.feynman');
+const STATE_PATH  = path.join(FEYNMAN_DIR, 'state.json');
+const FLAG_PATH   = path.join(CLIENT_HOME, '.feynman-active');
+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 writeState(state) {
+  fs.mkdirSync(FEYNMAN_DIR, { recursive: true });
+  fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
+}
+
+function readRules(intensity) {
+  const rulesContent = fs.readFileSync(RULES_PATH, 'utf8');
+  const selected = VALID_INTENSITIES.includes(intensity) ? intensity : 'full';
+  const openMarker  = '<!-- ' + selected + ' -->';
+  const closeMarker = '<!-- /' + selected + ' -->';
+  const i1 = rulesContent.indexOf(openMarker);
+  const i2 = rulesContent.indexOf(closeMarker, i1);
+  if (i1 === -1 || i2 === -1) return '';
+  return rulesContent.slice(i1 + openMarker.length, i2).trim();
+}
+
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    if (input.trim()) {
+      const data = JSON.parse(input);
+      const sessionId = data.session_id || '';
+      if (sessionId && /[/\\]|\.\./.test(sessionId)) process.exit(0);
+    }
+
+    const stateExists = fs.existsSync(STATE_PATH);
+    const flagExists = fs.existsSync(FLAG_PATH);
+    let state = { ...DEFAULT_STATE };
+
+    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);
+    }
+
+    if (!state.enabled) {
+      try { fs.unlinkSync(FLAG_PATH); } catch (_) {}
+      process.exit(0);
+    }
+
+    if (!flagExists) {
+      fs.writeFileSync(FLAG_PATH, state.intensity || DEFAULT_STATE.intensity);
+    }
+
+    const rulesText = readRules(state.intensity);
+    if (!rulesText) process.exit(0);
+
+    // SessionStart accepts plain stdout as context, matching caveman's hook shape.
+    process.stdout.write(rulesText);
+  } catch (_) {
+    process.exit(0);
+  }
+});

package/hooks/hooks.json

@@ -1,14 +1,24 @@
 {
   "description": "Inject feynman ASCII diagram rules before each Claude Code prompt.",
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FEYNMAN_HOME=\"$HOME/.claude\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/feynman-session-start.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [
           {
             "type": "command",
             "command": "FEYNMAN_HOME=\"$HOME/.claude\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/feynman-activate.js\"",
-            "timeout": 5,
-            "statusMessage": "Injecting diagram rules..."
+            "timeout": 5
           }
         ]
       }

package/hooks.json

@@ -1,13 +1,24 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PLUGIN_ROOT=\"${PLUGIN_ROOT:-$CLAUDE_PLUGIN_ROOT}\"; FEYNMAN_HOME=\"$HOME/.codex\" node \"$PLUGIN_ROOT/hooks/feynman-session-start.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [
           {
             "type": "command",
             "command": "PLUGIN_ROOT=\"${PLUGIN_ROOT:-$CLAUDE_PLUGIN_ROOT}\"; FEYNMAN_HOME=\"$HOME/.codex\" node \"$PLUGIN_ROOT/hooks/feynman-activate.js\"",
-            "timeout": 5,
-            "statusMessage": "Injecting diagram rules..."
+            "timeout": 5
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@albinocrabs/feynman",
-  "version": "0.2.4",
+  "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');
-let st = {enabled: false, intensity: 'full', injections: 0};
+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: true, intensity: 'full', injections: 0};
+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"
 ```