@albinocrabs/feynman 0.2.0 → 0.2.1

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## 0.2.1 - 2026-05-07
+
+Changes since v0.2.0.
+
+### Maintenance
+
+- add open-source automation
+

package/CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# Contributing to feynman
+
+Contributions welcome. This guide covers setup, what to work on, and
+how to get a PR merged.
+
+---
+
+## Quick Start
+
+```bash
+git clone https://github.com/apolenkov/feynman
+cd feynman
+npm install
+npm test
+```
+
+Tests use Node's built-in `node:test` runner — no external test framework
+needed.
+
+Lint the codebase: `node bin/feynman-lint.js README.md docs/*.md examples/*.md`
+
+---
+
+## What Makes a Good First PR
+
+These are well-scoped and require no architectural decisions:
+
+- **Add a lint-rule test case** — add a row to `tests/lint-cases.json` for
+  an edge case that's currently untested.
+- **Improve an example** — add or improve a file in `examples/` following
+  the schema in `docs/architecture.md` and `06-CONTEXT.md`.
+- **Expand `feynman doctor`** — add a new health check to `bin/feynman.js`
+  `cmdDoctor()`.
+- **Fix a typo or improve prose** — in `README.md`, `docs/`, or `CONTRIBUTING.md`.
+- **Add a rule to `rules/feynman-activate.md`** — follow the rules-authoring
+  guidelines below.
+
+---
+
+## PR Checklist
+
+Before opening a pull request:
+
+- [ ] `npm test` passes (all existing tests green)
+- [ ] New behavior has a test in `tests/` covering the change
+- [ ] No new lint warnings: `node bin/feynman-lint.js <changed files>`
+- [ ] `README.md` updated if a user-facing feature changed
+- [ ] Commit message follows the format: `type(scope): description`
+      (types: `feat`, `fix`, `test`, `docs`, `refactor`, `chore`)
+
+---
+
+## Rules Authoring Guidelines
+
+The hook injects `rules/feynman-activate.md` into every Claude prompt.
+The rules must be declarative facts, not commands.
+
+**Good (declarative):**
+> "A response describing a sequence of steps includes an ASCII flow diagram."
+
+**Bad (imperative):**
+> "Always draw a flow diagram when you see steps."
+
+Imperative phrasing triggers Claude's prompt-injection defense
+([bug #17804](https://github.com/anthropics/claude-code/issues/17804)) and
+may be filtered or reinterpreted.
+
+Each intensity variant must stay under 8,000 characters. Measure with:
+
+```bash
+node -e "
+const f = require('fs').readFileSync('rules/feynman-activate.md', 'utf8');
+['lite','full','ultra'].forEach(v => {
+  const s = f.indexOf('<!-- ' + v + ' -->');
+  const e = f.indexOf('<!-- /' + v + ' -->', s);
+  console.log(v, f.slice(s, e + ('<!-- /' + v + ' -->').length).length, 'chars');
+});
+"
+```
+
+---
+
+## Issue Triage
+
+**Labels:**
+
+| label            | when to use                                      |
+|------------------|--------------------------------------------------|
+| `bug`            | something works differently than documented      |
+| `feature`        | new capability request                           |
+| `docs`           | documentation gap or error                       |
+| `good-first-issue` | well-scoped, no architecture decisions needed  |
+
+**Expected response time:** best-effort, typically within a week for bugs.
+Feature requests may be deferred to a milestone.
+
+---
+
+## Governance
+
+- Single maintainer: [apolenkov](https://github.com/apolenkov)
+- License: MIT — see `LICENSE`
+- Public roadmap: `.planning/ROADMAP.md` (check before proposing big features)
+- No DCO or CLA sign-off required — low barrier to contribution is intentional
+
+---
+
+## Testing
+
+```bash
+npm test              # run all tests
+npm test -- --grep L01  # filter by test name pattern
+```
+
+Coverage report: `npm run coverage` (writes to `coverage/`)
+
+Tests are in `tests/` using `node:test` and `node:assert`. Lint golden
+cases are in `tests/lint-cases.json`.
+
+---
+
+## Architecture
+
+See [`docs/architecture.md`](docs/architecture.md) for the hook lifecycle,
+lint pipeline, and state schema before making changes to `hooks/`,
+`lib/lint/`, or `bin/`.

package/README.md

@@ -24,6 +24,7 @@
   <a href="#intensity-levels">Levels</a> •
   <a href="#lint">Lint</a> •
   <a href="#examples">Examples</a> •
+  <a href="docs/launch.md">Launch</a> •
   <a href="CONTRIBUTING.md">Contributing</a>
 </p>
 
@@ -33,7 +34,10 @@ 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.
 
-<!-- TODO: GIF after v0.3.0 visual capture -->
+```bash
+npx -y @albinocrabs/feynman@latest install --target both
+npx -y @albinocrabs/feynman@latest doctor --target codex
+```
 
 ## Why feynman
 
@@ -262,10 +266,11 @@ Domain-specific examples showing feynman in practice:
 
 ## How it works
 
-The `UserPromptSubmit` hook fires on every Claude prompt. The hook reads
-`~/.claude/.feynman/state.json`, extracts the rules for the active intensity
+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
-Claude on every message.
+the model on every message.
 
 ```
 [your prompt]
@@ -279,6 +284,19 @@ Claude on every message.
 [structured response with ASCII diagrams]
 ```
 
+## Release process
+
+Every push runs tests on Node 18 and 20 across Ubuntu and macOS. The release
+lane also lints public docs, smoke-tests the packed npm tarball, builds a
+`dist/*.tgz` artifact, and can publish to npm from a GitHub Release when
+`NPM_TOKEN` is configured.
+
+```bash
+npm run ci
+npm run changelog
+npm run build
+```
+
 State is stored at `~/.claude/.feynman/state.json`. First run bootstraps
 automatically. See [docs/architecture.md](docs/architecture.md) for internals.
 

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are shipped for the latest published npm version.
+
+## Reporting a Vulnerability
+
+Please report security issues privately by opening a GitHub security advisory:
+
+https://github.com/apolenkov/feynman/security/advisories/new
+
+Do not file public issues for vulnerabilities. Include:
+
+- affected version
+- reproduction steps
+- expected impact
+- suggested fix, if known
+
+We aim to acknowledge reports within 72 hours.
+
+## Scope
+
+feynman is a local hook package. The main security-sensitive surfaces are:
+
+- hook command registration in `~/.claude/settings.json`
+- hook command registration in `~/.codex/hooks.json`
+- file reads from the installed package directory
+- state files under `~/.claude/.feynman/` and `~/.codex/.feynman/`
+
+The package has zero runtime npm dependencies.

package/bin/feynman.js

@@ -98,10 +98,10 @@ ${c.bold('Options:')}
   --force      (install) Re-register even if already installed
 
 ${c.bold('Examples:')}
-  npx feynman install
-  npx feynman install --target codex
-  npx feynman install --target both
-  npx feynman doctor
+  npx @albinocrabs/feynman install
+  npx @albinocrabs/feynman install --target codex
+  npx @albinocrabs/feynman install --target both
+  npx @albinocrabs/feynman doctor
   feynman lint response.md
   feynman uninstall
 `;
@@ -351,7 +351,7 @@ function cmdUninstall(opts) {
   if (results.every(r => r.missing || !r.hadHook)) {
     console.log(`feynman: no hook found for ${labels} — nothing to uninstall.`);
   } else {
-    console.log(`feynman disabled for ${labels}. State preserved. Re-enable: npx feynman install --target ${opts.target}`);
+    console.log(`feynman disabled for ${labels}. State preserved. Re-enable: npx @albinocrabs/feynman install --target ${opts.target}`);
   }
   process.exit(0);
 }

package/docs/architecture.md

@@ -0,0 +1,190 @@
+# feynman Architecture
+
+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`.
+
+```
+~/.claude/settings.json       ~/.codex/hooks.json
+         │
+         │  hooks.UserPromptSubmit fires on every prompt
+         ▼
+hooks/feynman-activate.js
+         │
+         ├─ [0] FEYNMAN_HOME selects client state root
+         │        unset              → ~/.claude (backward compatible)
+         │        ~/.claude          → Claude Code install
+         │        ~/.codex           → Codex install
+         │
+         ├─ [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
+         │
+         ├─ [3] $FEYNMAN_HOME/.feynman/state.json
+         │        enabled: false           → exit 0
+         │        corrupt JSON             → exit 0 (fail safe)
+         │
+         ├─ [4] rules/feynman-activate.md
+         │        extract section for state.intensity
+         │        (lite | full | ultra)
+         │
+         ├─ [5] state.injections++  (write back)
+         │
+         └─ [6] stdout: JSON additionalContext → injected into prompt
+                  {hookSpecificOutput: {hookEventName: 'UserPromptSubmit',
+                                        additionalContext: <rules text>}}
+```
+
+**Key constraints:**
+
+- Output must be JSON with no trailing newline — plain stdout triggers
+  Claude Code's red error banner (bug #13912).
+- Paths use `os.homedir()`, never tilde literals (bug #8810).
+- Production install writes user hook config directly:
+  `~/.claude/settings.json` for Claude Code and `~/.codex/hooks.json` for
+  Codex. Plugin manifests are shipped for discoverability, but direct hook
+  registration remains the reliable fallback.
+- Flag file checked before state file to detect intentional disabling
+  vs. first run (bug #35713).
+
+**File:** `hooks/feynman-activate.js`
+
+---
+
+## Layer 2: Lint Pipeline
+
+The lint pipeline validates ASCII diagram correctness in markdown files.
+It runs as a CLI tool and as an optional `Stop` hook.
+
+```
+<file.md> or stdin
+         │
+         ▼
+lib/lint/parser.js
+         │  parseMarkdown(text) → ASTNode[]
+         │  each node: {type, content, startLine, endLine}
+         │  types: fenced_code, ascii_art (freestanding)
+         │
+         ▼
+lib/lint/rules.js
+         │  runs each rule against each AST node:
+         │
+         ├─ L01_box_closure(ast)
+         ├─ L02_tree_chars(ast)
+         ├─ L03_arrow_style(ast)
+         ├─ L04_column_widths(ast)
+         ├─ L05_flow_integrity(ast)
+         ├─ L06_priority_scale(ast)
+         ├─ L07_no_mermaid_mix(ast, fullText)
+         └─ L08_frame_width(ast)
+         │
+         │  each rule returns Issue[]:
+         │  {rule, severity, line, column, message, suggestion?}
+         │
+         ▼
+reporter (inline in CLI + Stop hook)
+         │
+         ├─ bin/feynman-lint.js   ← standalone CLI
+         │     feynman lint <file>
+         │     exit 0: no errors
+         │     exit 1: errors found
+         │     exit 2: usage error
+         │     --json: machine-readable output
+         │     --strict: warnings treated as errors
+         │
+         └─ hooks/feynman-lint.js ← Stop hook (optional)
+               fires after Claude's response
+               if issues found: injects correction context
+               into next UserPromptSubmit cycle
+```
+
+**File:** `lib/lint/parser.js`, `lib/lint/rules.js`, `bin/feynman-lint.js`,
+`hooks/feynman-lint.js`
+
+---
+
+## Layer 3: State Schema
+
+All runtime state lives in two files under the selected client root:
+`~/.claude/` for Claude Code, `~/.codex/` for Codex.
+
+```
+~/.claude/ or ~/.codex/
+├── .feynman-active          ← presence flag
+│     present  = feynman active
+│     absent   = user disabled (state.json preserved)
+│     content  = current intensity string (informational)
+│
+└── .feynman/
+    └── state.json           ← runtime state
+          {
+            "enabled":    boolean,   // true = inject rules on each prompt
+            "intensity":  string,    // "lite" | "full" | "ultra"
+            "injections": number     // cumulative hook fire count
+          }
+```
+
+**State transitions:**
+
+```
+[first run]
+  both files absent → bootstrap
+  writes state.json {enabled:true, intensity:'full', injections:0}
+  writes .feynman-active with intensity string
+
+[/feynman off]
+  state.enabled = false
+  .feynman-active deleted
+
+[/feynman on]
+  state.enabled = true
+  .feynman-active created
+
+[/feynman lite | full | ultra]
+  state.intensity = <value>
+  .feynman-active content updated
+
+[npx @albinocrabs/feynman uninstall --target claude|codex|both]
+  hook removed from target hook config
+  .feynman-active deleted
+  state.json preserved (user data)
+```
+
+**Schema is frozen** — field names are used by `hooks/feynman-activate.js`,
+`bin/feynman.js`, and `skills/feynman/SKILL.md`. Any rename requires
+coordinated update across all three files.
+
+**File:** read/written by `hooks/feynman-activate.js` and `bin/feynman.js`;
+managed by skill commands in `skills/feynman/SKILL.md`.
+
+---
+
+## CLI Subcommand Map
+
+```
+bin/feynman.js
+├── install    → writes target hook config + state.json + flag
+├── uninstall  → removes target hook entries + flag (keeps state)
+├── doctor     → checks target health criteria, prints frame
+├── lint       → delegates to bin/feynman-lint.js
+└── version    → prints package.json version
+```
+
+Targets:
+
+```
+claude → ~/.claude/settings.json + ~/.claude/.feynman/
+codex  → ~/.codex/hooks.json     + ~/.codex/.feynman/
+both   → runs claude and codex installers idempotently
+```
+
+**File:** `bin/feynman.js`

package/docs/launch.md

@@ -0,0 +1,67 @@
+# Launch Notes
+
+## Positioning
+
+feynman is a Claude Code and Codex plugin that makes structured answers
+visible by default. Flows become arrows, hierarchies become trees, comparisons
+become columns, priorities become scales, and status summaries become frames.
+
+## One-liner
+
+```bash
+npx -y @albinocrabs/feynman@latest install --target both
+```
+
+## Short Description
+
+feynman automatically injects ASCII diagram rules into Claude Code and Codex
+prompts, so structured answers render as readable terminal-native diagrams
+without asking every time.
+
+## Benefits
+
+- No runtime dependencies
+- Works with Claude Code and Codex
+- Installs with `npx`
+- Keeps state local under `~/.claude` or `~/.codex`
+- Ships a diagram linter for public docs and generated responses
+- Uses plain ASCII/Unicode text, not external renderers
+
+## Demo Script
+
+```bash
+npx -y @albinocrabs/feynman@latest install --target both
+npx -y @albinocrabs/feynman@latest doctor --target claude
+npx -y @albinocrabs/feynman@latest doctor --target codex
+```
+
+Prompt:
+
+```text
+Compare SQLite, Postgres, and Redis for a local-first prototype.
+```
+
+Expected shape:
+
+```text
+SQLite           | Postgres         | Redis
+-----------------|------------------|----------------
+single-file      | server database  | memory-first
+easy local setup | richer SQL       | fast cache
+limited writes   | production-ready | persistence opt
+```
+
+## Release Checklist
+
+- `npm run ci`
+- GitHub Actions CI green
+- `npm run changelog`
+- `npm run build`
+- `npm publish --dry-run --access public`
+- GitHub Release created from changelog notes
+- npm package visible at `@albinocrabs/feynman@latest`
+- Smoke test from clean directory:
+
+```bash
+npx -y @albinocrabs/feynman@latest version
+```