@albinocrabs/feynman 0.2.1 → 0.2.4

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -2,11 +2,58 @@
 
 All notable changes to this project are documented here.
 
-## 0.2.1 - 2026-05-07
+## 0.2.4 - 2026-05-07
 
-Changes since v0.2.0.
+Changes since v0.2.2.
+
+### Fixes
+
+- normalize hook bypass docs and lint-safe examples
+
+### CI/CD
+
+- make coverage badge commit non-blocking on protected branch
+- stabilize release note extraction by version section
+- auto-update release notes and add npm publish verification
+
+### Documentation
+
+- expand examples gallery and add activity sequence
+- update changelog for v0.2.3
+- add advanced before-after examples
 
 ### Maintenance
 
-- add open-source automation
+- v0.2.4
+- regenerate changelog for 0.2.3 updates
+- auto-merge #2
+- finalize launch docs, examples and PR auto-merge wiring
+- complete v0.2.0 milestone audit docs
+- sync plugin manifest versions for 0.2.2
+
+## 0.2.3 - 2026-05-07
+
+Changes since v0.2.2.
+
+### Fixes
+
+- normalize hook bypass docs and lint-safe examples
+
+### CI/CD
+
+- make coverage badge commit non-blocking on protected branch
+- stabilize release note extraction by version section
+- auto-update release notes and add npm publish verification
+
+### Documentation
+
+- expand examples gallery and add activity sequence
+- update changelog for v0.2.3
+- add advanced before-after examples
+
+### Maintenance
 
+- auto-merge #2
+- finalize launch docs, examples and PR auto-merge wiring
+- complete v0.2.0 milestone audit docs
+- sync plugin manifest versions for 0.2.2

package/CONTRIBUTING.md

@@ -47,6 +47,7 @@ Before opening a pull request:
 - [ ] `README.md` updated if a user-facing feature changed
 - [ ] Commit message follows the format: `type(scope): description`
       (types: `feat`, `fix`, `test`, `docs`, `refactor`, `chore`)
+- [ ] Add labels `auto-merge` and `status:ready` when the PR is fully reviewed and safe to merge automatically
 
 ---
 

package/README.md

@@ -19,6 +19,7 @@
 
 <p align="center">
   <a href="#why-feynman">Why</a> •
+  <a href="docs/object-passport.md">Passport</a> •
   <a href="#before--after">Before/After</a> •
   <a href="#install">Install</a> •
   <a href="#intensity-levels">Levels</a> •
@@ -35,7 +36,7 @@ plugin that automatically injects ASCII diagram rules into every prompt via the
 `UserPromptSubmit` hook.
 
 ```bash
-npx -y @albinocrabs/feynman@latest install --target both
+npx -y @albinocrabs/feynman@latest install --target all
 npx -y @albinocrabs/feynman@latest doctor --target codex
 ```
 
@@ -47,6 +48,15 @@ Code or Codex prompt and injects rules that turn flows into arrows,
 hierarchies into trees, comparisons into columns, and status into frames. The
 structure is visible before you have to think about it.
 
+Conceptually, feynman is inspired by prompt-compression ideas from the Caveman
+agent style: smaller prompts, clearer intent, and explicit diagram-first thinking.
+
+## Governance docs
+
+- `AGENTS.md` — project execution contract for Codex-aware tooling.
+- `CLAUDE.md` — canonical project memory, stack, and architecture constraints.
+- Global instructions are loaded from user-level runtime configuration before repo-specific overrides.
+
 ## Before / After
 
 <table>
@@ -136,10 +146,10 @@ free           | free          | $$$
 
 ## Install
 
-**Claude Code via npx:**
+**Install to Codex by default (when --target is omitted):**
 
 ```bash
-npx @albinocrabs/feynman install --target claude
+npx @albinocrabs/feynman install
 ```
 
 **Codex via npx:**
@@ -151,7 +161,7 @@ npx @albinocrabs/feynman install --target codex
 **Both clients:**
 
 ```bash
-npx @albinocrabs/feynman install --target both
+npx @albinocrabs/feynman install --target all
 ```
 
 The install command is idempotent: running it again updates the existing
@@ -167,7 +177,7 @@ Restart Claude Code or Codex. Done.
 
 **Verify:** `npx @albinocrabs/feynman doctor --target claude` or `npx @albinocrabs/feynman doctor --target codex`
 
-**Uninstall:** `npx @albinocrabs/feynman uninstall --target claude|codex|both`
+**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
@@ -253,16 +263,221 @@ npx @albinocrabs/feynman lint response.md
 
 See [docs/lint-rules.md](docs/lint-rules.md) for the full L01-L08 reference.
 
+### Quick hard-disable / re-enable (testing and emergency)
+
+For temporary global disable in Codex (for smoke tests or troubleshooting), use:
+
+```bash
+touch ~/.codex/.feynman-disable-global    # hard OFF
+rm ~/.codex/.feynman-disable-global       # hard ON
+```
+
+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`).
+
+## CLI examples
+
+Quickly discover and view repository prompt templates:
+
+```bash
+feynman examples
+feynman examples --name feature-planning
+feynman examples --name incident-response
+feynman examples --random
+```
+
+Export a ready-to-distribute local package (examples, rules, plugins, and skill):
+
+```bash
+feynman bootstrap
+feynman bootstrap --out ./feynman-package
+feynman bootstrap --out ./feynman-package --force
+```
+
+This is useful for disconnected/air-gapped installs where you want to copy one
+folder with all `Feynman` assets instead of depending on `npm`.
+
+Slash command aliases (inside Claude/Codex):
+
+```text
+/feynman on | off
+/feynman start | stop
+/feynman lite | full | ultra
+/feynman status
+```
+
 ## Examples
 
-Domain-specific examples showing feynman in practice:
+Run a concrete example in the needed style:
+
+```bash
+feynman examples --name <example-name>
+```
+
+> Tip: all examples are ready-to-run templates in `examples/*.md`, can be copied into prompts or docs, and rendered as a compact ASCII layout with `feynman examples --name ...`.
+
+```text
+[Flow]  [Architecture]   [API]        [Decisions]
+  |          |            |              |
+  v          v            v              v
+ [Action]  [System]    [Lifecycle]   [Reasoning]
+    ↓          ↓            ↓              ↓
+ [Outcome] [Design]     [Change]      [Choice]
+```
+
+## Visual example gallery
+
+### Flow and actioning
+
+#### Incident-ready action playbooks
+
+- [Activity sequence](examples/activity-sequence.md) — incident action plans with rollback gates  
+  ```
+  [Incident] --> [Triage] --> [Contain] --> [Mitigate] --> [Review]
+                                   | no         |
+                                   v            |
+                                [Rollback] <----+ 
+  ```
+- [Incident response](examples/incident-response.md) — triage and containment sequence  
+  ```
+  [Detect] --> [Classify] --> [Isolate] --> [Communicate]
+                                  |
+                                  +--> [Recover]
+  ```
+- [Bug isolation](examples/bug-isolation.md) — stateful diagnostic flow with priorities  
+  ```
+  ▲ high
+    high-likelihood
+  ▼ low
+    narrow scope
+    documentation
+  ```
+- [Release readiness](examples/release-readiness.md) — staged launch gates and recovery triggers  
+  ```
+  [Build] --> [QA] --> [Dark launch] --> [General] 
+                       | no             | yes
+                       v                v
+                 [Rollback]        [Monitor]
+  ```
+
+### Architecture and design
+
+- [Architecture review](examples/architecture-review.md) — auth system decomposition  
+  ```
+  Auth
+  ├── Service
+  │   ├── Redis rate limits
+  │   └── Postgres users
+  └── Observability
+      └── Events
+  ```
+- [C4 platform design](examples/c4-platform-diagramming.md) — context → container → component  
+  ```
+  [User] --> [Web] --> [API] --> [DB]
+  ```
+- [Context splitting](examples/context-splitting.md) — decomposing complex initiatives  
+  ```
+  Initiative
+  ├── Domain A
+  ├── Domain B
+  └── Domain C
+  ```
+- [Database schema](examples/db-schema.md) — entity model as structured tree  
+  ```
+  Report
+  ├── Metadata
+  ├── Sections
+  └── History
+  ```
+
+### API and migration
+
+- [API flow](examples/api-flow.md) — request lifecycle with branch diagnostics  
+  ```
+  [Client] --> [Auth] --> [Service] --> [DB]
+                        | yes          |
+                        +-->[Cache] ---+
+  ```
+- [Deploy pipeline](examples/deploy-pipeline.md) — CI/CD action chain  
+  ```
+  [Source] --> [Build] --> [Test] --> [Canary] --> [Scale]
+              |             |
+              v             +--> [Rollback]
+  ```
+- [Service migration](examples/service-migration.md) — cutover with risk controls  
+  ```
+  [Old service] --> [Dual write] --> [Read compare] --> [Cut over]
+                                        | mismatch
+                                        v
+                                  [Stop migration]
+  ```
+
+### Decisions and methods
+
+- [Feature planning](examples/feature-planning.md) — decision matrix + phased rollout  
+  ```
+  [Need] --> [Plan] --> [Run experiment] --> [Scale]
+             |        |
+             +--> [Kill-switch]
+  ```
+- [Algorithm walkthrough](examples/algorithm-explain.md) — rate-limiter logic as explainable sequence  
+  ```
+  [Need decision?] --> [Compute score] --> [Allow / Deny]
+  ```
+- [Code review](examples/code-review.md) — issue prioritization and evidence matrix  
+  ```
+  ▲ must-fix       [security]
+    ▲ medium       [performance]
+      ▼ low        [docs]
+  ```
+
+### One-command pack test
+
+```bash
+feynman examples --name activity-sequence && \
+feynman examples --name incident-response && \
+feynman examples --name c4-platform-diagramming
+```
 
-- [Architecture review](examples/architecture-review.md) — auth service topology
-- [API flow](examples/api-flow.md) — POST /api/login request lifecycle
-- [Database schema](examples/db-schema.md) — e-commerce entity model
-- [Algorithm walkthrough](examples/algorithm-explain.md) — token-bucket rate limiter
-- [Deploy pipeline](examples/deploy-pipeline.md) — monorepo CI/CD
-- [Code review](examples/code-review.md) — priority + comparison diagrams
+## Visual gallery (before → after)
+
+If you want to quickly see how diagram-first responses evolve, this is the core pattern:
+
+Without feynman:
+
+`We need to choose between shipping fast with a managed API, keeping control in-house, or a hybrid path while managing risk and cost.`
+
+With feynman:
+
+```
+[Is SLA strict?] --> [Yes] --> [Prefer managed service]
+                 |             |               |
+                 |             v               v
+                 |      [Contract + vendor risk] --> [Is rollback cheap?]
+                 |                                   |
+                 v                                   +--> [Yes] --> [Adopt + guardrails]
+        [Can we build fast?]                            +--> [No]  --> [Hybrid path]
+                 |
+      no ------ +------- yes
+       |                |
+       v                v
+ [Build in house]   [Run controlled managed pilot]
+```
+
+Same brief question, different clarity level.
+
+```
+criterion      | build in-house | managed API | hybrid
+---------------|----------------|-------------|----------------
+launch speed   | slow           | fast        | medium
+vendor lock-in | low            | high        | medium
+compliance     | high control   | partner SLA | custom controls
+cost           | low initial    | medium      | medium-high
+```
+
+Use this gallery style if you want `feynman` examples to look “production-clean”
+from day one.
 
 ## How it works
 
@@ -289,7 +504,10 @@ the model on every message.
 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.
+`NPM_TOKEN` is configured. If the token is absent and the package version is
+already published, the workflow updates release notes and exits successfully;
+for a new publish, it fails with a clear message so token-less publication
+cannot silently pass.
 
 ```bash
 npm run ci
@@ -297,6 +515,24 @@ npm run changelog
 npm run build
 ```
 
+### GitHub release path
+
+1. Tag and release from GitHub (or run workflow_dispatch with `dry_run=false`).
+2. Ensure repository secret `NPM_TOKEN` is set (only needed for first publish
+   of a new version).
+3. Keep version/tag aligned: release tag must equal `package.json` with `v`
+   prefix (enforced by workflow).
+4. Create release notes generated from `CHANGELOG.md` and verify package
+   availability after publish.
+5. Mark PRs for auto-merge with labels `auto-merge` and `status:ready` and
+   keep required review approvals in place.
+
+Set or rotate `NPM_TOKEN` with:
+
+```bash
+gh secret set NPM_TOKEN -r apolenkov/feynman
+```
+
 State is stored at `~/.claude/.feynman/state.json`. First run bootstraps
 automatically. See [docs/architecture.md](docs/architecture.md) for internals.
 

package/SECURITY.md

@@ -29,3 +29,14 @@ feynman is a local hook package. The main security-sensitive surfaces are:
 - state files under `~/.claude/.feynman/` and `~/.codex/.feynman/`
 
 The package has zero runtime npm dependencies.
+
+## Release Security Checklist
+
+Before publishing a new npm version:
+
+- CI required checks must pass on Node 18 and 20 across Ubuntu and macOS.
+- `npm run audit` must pass at `moderate` severity or higher.
+- 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`).