@albinocrabs/feynman 0.2.2 → 0.2.5

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/
@@ -153,7 +156,7 @@ All runtime state lives in two files under the selected client root:
   state.intensity = <value>
   .feynman-active content updated
 
-[npx @albinocrabs/feynman uninstall --target claude|codex|both]
+[npx @albinocrabs/feynman uninstall --target claude|codex|both|all|*]
   hook removed from target hook config
   .feynman-active deleted
   state.json preserved (user data)
@@ -171,20 +174,27 @@ 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
+   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
+   ├── examples   → list and render built-in ASCII examples
+   ├── help       → this help/usage block
+   ├── bootstrap  → exports examples + manifests + skill into local package folder
+   └── version    → prints package.json version
 ```
 
+`/feynman on|off|start|stop|lite|full|ultra` are handled by the skill contract
+in `skills/feynman/SKILL.md` and share aliases:
+`start` == `on`, `stop` == `off`.
+
 Targets:
 
 ```
 claude → ~/.claude/settings.json + ~/.claude/.feynman/
 codex  → ~/.codex/hooks.json     + ~/.codex/.feynman/
-both   → runs claude and codex installers idempotently
+both, all, * → runs claude and codex installers/uninstallers idempotently
 ```
 
 **File:** `bin/feynman.js`

package/docs/launch.md

@@ -9,7 +9,7 @@ become columns, priorities become scales, and status summaries become frames.
 ## One-liner
 
 ```bash
-npx -y @albinocrabs/feynman@latest install --target both
+npx -y @albinocrabs/feynman@latest install --target all
 ```
 
 ## Short Description
@@ -30,9 +30,10 @@ without asking every time.
 ## Demo Script
 
 ```bash
-npx -y @albinocrabs/feynman@latest install --target both
+npx -y @albinocrabs/feynman@latest install --target '*'
 npx -y @albinocrabs/feynman@latest doctor --target claude
 npx -y @albinocrabs/feynman@latest doctor --target codex
+feynman bootstrap --out ./feynman-package
 ```
 
 Prompt:
@@ -65,3 +66,10 @@ limited writes   | production-ready | persistence opt
 ```bash
 npx -y @albinocrabs/feynman@latest version
 ```
+
+For the full release playbook, see: [docs/release.md](release.md)
+
+## Detailed Release Docs
+
+- [docs/release.md](release.md): full end-to-end release procedure, release notes
+  contract, workflow behavior, and post-release verification.

package/docs/object-passport.md

@@ -0,0 +1,91 @@
+# Feynman Product Passport
+
+## 1) Миссия и область применения
+
+`feynman` — plugin для Claude Code и Codex, который injects ASCII-правила диаграмм в каждый prompt на слое `UserPromptSubmit`.
+
+Главная задача: ускорить расшифровку структуры и снизить когнитивную нагрузку в ответах с потоками, иерархией, сравнением и статусами.
+
+Не делает:
+- бизнес-логику приложения,
+- редизайн ответа API/фронтенда,
+- сетевые вызовы или фоновое хранение текстовых логов.
+
+## 2) Артефакты проекта
+
+| Слой | Артефакт | Назначение |
+|---|---|---|
+| Hook | `hooks/feynman-activate.js` | Чтение состояния и инъекция `additionalContext` |
+| Rules | `rules/feynman-activate.md` | Набор правил `lite/full/ultra` |
+| CLI | `bin/feynman.js` | `install/uninstall/doctor/lint/examples/bootstrap/version/help` |
+| Lint | `bin/feynman-lint.js`, `lib/lint/*` | Проверка корректности ASCII-диаграмм |
+| Skill | `skills/feynman/SKILL.md` | Slash-команды управления режимом |
+| Package | `.claude-plugin/`, `.codex-plugin/`, `hooks.json` | Доставка плагина |
+
+## 3) Runtime state
+
+`~/.claude/.feynman/` или `~/.codex/.feynman/`:
+
+- `state.json` — `enabled`, `intensity`, `injections`.
+- `.feynman-active` — флаг включения.
+
+Семантика:
+- флаг есть: инъекция может выполняться (если `enabled: true`);
+- флага нет + state есть: отключено пользователем;
+- оба файла отсутствуют: bootstrap первого запуска.
+
+## 4) Управление состоянием (slash)
+
+- `/feynman on` / `/feynman start` — включить инъекцию;
+- `/feynman off` / `/feynman stop` — выключить инъекцию;
+- `/feynman lite|full|ultra` — переключить интенсивность;
+- `/feynman` / `/feynman status` — статус без изменений.
+
+## 5) CLI контракт
+
+| Команда | Что делает |
+|---|---|
+| `feynman install` | Регистрирует hook в `settings.json`/`hooks.json` |
+| `feynman uninstall` | Удаляет hook, оставляя state |
+| `feynman doctor` | Диагностический health-check |
+| `feynman lint` | Проверяет Markdown на правила L01-L08 |
+| `feynman examples` | Печатает примеры ответов |
+| `feynman bootstrap` | Экспортирует артефакты в локальную папку |
+| `feynman version` | Версия пакета |
+| `feynman help` | Текущая справка CLI |
+
+## 6) Качество диаграмм
+
+Источник правил:
+- `rules/feynman-activate.md` (источник истины для `lite/full/ultra`)
+
+Обновление правил требует синхронизации:
+- `hooks/feynman-activate.js` + `bin/feynman.js` + `skills/feynman/SKILL.md`
+- плюс smoke/pattern-тесты `tests/cli.test.js`.
+
+## 7) Технико-операционные ограничения
+
+- Zero deps, CommonJS.
+- Node >= 18.
+- No network at runtime для hook execution (внешние пути не используются).
+- Bootstrap включает runtime files для дисконнекта: `hooks/feynman-activate.js`, `bin/feynman.js`, `package.json` и ассеты.
+
+## 8) Проверки и сопровождение
+
+Обязательные для релиза:
+- `feynman bootstrap --out ... --force`
+- `feynman lint --json README.md` (рекурентно по docs),
+- CI matrix (`Node 18/20` на `ubuntu`/`macos`).
+
+## 9) Известный рынок и позиционирование
+
+В рынке есть аналоги по prompt-управлению (кнопки в IDE/CLI/prompt-команды), но у `feynman` уникально сочетание:
+- автоматическая ASCII-семантика на hooks,
+- отдельный lint для качества диаграмм,
+- zero-dep runtime.
+
+## 10) Связь
+
+- [Architecture](./architecture.md)
+- [Launch](./launch.md)
+- [RTK Playbook](../RTK.md)

package/docs/release.md

@@ -0,0 +1,162 @@
+# Release Documentation
+
+This document defines the full release process for `@albinocrabs/feynman`, including changelog usage, release notes generation, publishing, and verification.
+
+## 1) Scope and ownership
+
+- Release versioning is package-driven (`package.json` `version`).
+- GitHub release tags use `v${version}` format.
+- Changelog is the canonical source for release notes.
+- CI/release workflows live in `.github/workflows/ci.yml` and `.github/workflows/release.yml`.
+
+## 2) Pre-release checks
+
+1. Verify repo cleanliness and branch context.
+2. Ensure `main` is clean and CI checks are green.
+3. Confirm `package.json` version is the intended next version.
+4. Confirm matching plugin manifest versions if changed.
+
+Recommended commands:
+
+```bash
+git status --short --branch
+git log --oneline -5 --decorate
+npm run ci
+```
+
+## 3) Changelog-first release notes (required)
+
+### What to update
+
+- Edit top of `CHANGELOG.md` before tagging.
+- Use this section format:
+
+```md
+## 0.2.3 - 2026-05-07
+
+Changes since v0.2.2.
+
+### Added
+- ...
+
+### Changed
+- ...
+
+### Fixed
+- ...
+
+### Maintenance
+- ...
+```
+
+### What goes into release notes
+
+- `GitHub Release body` is generated from the section matching the new version in `CHANGELOG.md`.
+- If no section exists or it is empty, workflow auto-falls back to:
+  - `## <version>`
+  - `Changes since <previousTag>.`
+  - `- Release published from package.json version <version>.`
+
+### Key rule
+
+The workflow ignores changelog command output at publish time; it extracts directly from the repository changelog section for the version.
+
+## 4) Version and release flow
+
+### Step-by-step sequence
+
+1. Update files for release:
+   - `package.json` version bump.
+   - top `CHANGELOG.md` section for that version.
+2. Run release checks:
+   - `npm run ci`
+3. Commit and push to `main`.
+4. Create and publish GitHub release tag `v<version>`:
+   - Via UI or CLI.
+5. GitHub release workflow executes automatically:
+   - validates repository and package checks,
+   - extracts changelog notes,
+   - uploads tarball artifact,
+   - updates/creates release body,
+   - publishes to npm (if not already published),
+   - verifies npm propagation.
+
+Manual local command examples:
+
+```bash
+git add package.json CHANGELOG.md
+git commit -m "chore: release v0.2.3"
+git push origin main
+
+gh release create v0.2.3 --generate-notes --target main
+```
+
+If you need a full dry run without publish, use workflow dispatch:
+
+```bash
+gh workflow run release.yml -f dry_run=true
+```
+
+## 5) What each workflow step does
+
+- Checkout with full history + tags (`fetch-depth: 0`, `fetch-tags: true`).
+- Resolve metadata from `package.json`:
+  - `package_name`
+  - `package_version`
+  - `tag`
+  - previous tag for fallback context.
+- Parse `CHANGELOG.md` for matching `## <version>` section.
+- Build and test release artifact (`npm run ci` + `npm run build`).
+- Upload `dist/*.tgz` artifact.
+- Update release notes on GitHub release.
+- Publish to npm using `NPM_TOKEN` (skipped if version already exists).
+- Verify publication via repeated `npm view` checks.
+
+## 6) Post-release verification
+
+Run in order:
+
+1. Git state and alignment:
+
+```bash
+git rev-parse --short HEAD
+git rev-parse --short origin/main
+```
+
+2. Release artifact validation:
+
+```bash
+gh release view v0.2.3 --json name,tagName,isDraft,isPrerelease,url -q '.name+"\\n"+.tagName+"\\n"+.isDraft+"\\n"+.isPrerelease+"\\n"+.url'
+gh release view v0.2.3 --json body -q .body
+```
+
+3. NPM publication:
+
+```bash
+npm view @albinocrabs/feynman@0.2.3 version
+npm view @albinocrabs/feynman dist-tags
+```
+
+4. Smoke test from clean env:
+
+```bash
+node -e "console.log('ok')" # placeholder for your install checks
+npx -y @albinocrabs/feynman@latest version
+``
+
+## 7) Troubleshooting
+
+- **Release notes still show CI/CD text**
+  - Ensure tag points to commit containing the new `CHANGELOG.md` section.
+  - Ensure section header exactly matches `## <version>`.
+- **Publish failed**
+  - confirm `NPM_TOKEN` is set in repo secrets,
+  - verify package name in `package.json`.
+- **Release not auto-updated**
+  - run on `release` event only or manual dispatch with `dry_run=false`.
+
+## 8) Required docs references
+
+- [Release process (short)](../README.md) – README overview.
+- [CI workflow](./launch.md#release-checklist).
+- [Release workflow](../.github/workflows/release.yml).

package/examples/activity-sequence.md

@@ -0,0 +1,105 @@
+# Action Sequencing: Checkout Incident During Peak
+
+## Question
+
+> Checkout error rate jumps during peak and latency is now above SLO. We need a
+> concrete action sequence for recovery, including who does what, when to rollback,
+> and when to stop doing damage-control.
+
+## Without feynman
+
+The team usually starts by checking dashboards, then opens an emergency channel,
+then asks backend and DB teams to investigate. If they find a single failing
+dependency they rollback that change; otherwise they add read-through cache and
+throttle traffic. Communication goes out if the user impact is material.
+
+## With feynman
+
+Operational sequence:
+
+```
+[Alert: checkout error spike] --> [On-call acknowledges in 60s]
+                                   |
+                                   +--> [Is impact external?]
+                                               |
+                                               +-- yes --> [Start Incident Commander]
+                                               |
+                                               +-- no  --> [Fast path mitigation only]
+                                                                   |
+                                                                   v
+[Notify org channel] --> [Freeze non-critical deploys] --> [Triage by layer]
+                                                          |
+                                                          v
+                                               [Cache/DB/API/Infra]
+                                                          |
+                                              [Need rollback?]
+                                                      |
+                                                       +-- yes --> [Rollback scoped deploy]
+                                                       |
+                                                       +-- no  --> [Apply temporary safeguard]
+                                                           |
+                                                           v
+                                               [Stabilize + reduce blast radius]
+                                                          |
+                                                          v
+                                                  [Declare recovery ETA]
+                                                          |
+                                                          +-- success --> [Post-incident audit]
+                                                          |
+                                                          +-- degraded --> [Resume changes]
+```
+
+State board (what changed inside the incident):
+
+```
+┌─ Incident Action Board ───────────────────────┐
+│ triage              : done                    │
+│ command setup       : done                    │
+│ mitigation active   : in-flight               │
+│ rollback            : ready                   │
+│ customer comms      : live                    │
+│ root-cause evidence : collecting              │
+└───────────────────────────────────────────────┘
+```
+
+Critical path decomposition:
+
+```
+[Containment]
+  ├── [Enable queue throttle]
+  ├── [Route reads to replica]
+  └── [Turn on circuit breaker]
+[Recovery]
+  ├── [Collect flamegraphs]
+  ├── [Compare with healthy minute]
+  └── [Prepare rollback diff]
+[Verification]
+  ├── [Canary checks]
+  ├── [Synthetic transaction replay]
+  └── [SLO probe]
+```
+
+Priority ladder during incident:
+
+```
+▲ high
+  data integrity checks
+  user-visible checkout path
+▼ low
+  dashboard chart style changes
+  PR comments cleanup
+```
+
+Runbook gate table:
+
+```
+check                | owner          | threshold      | action
+--------------------|----------------|----------------|-------------------------
+P95 latency         | SRE            | <= 700ms       | continue with mitigation
+error budget burn    | SRE            | <= 3%/15m      | escalate communications
+db retry pressure    | Backend lead    | <= 2x baseline | rotate to fallback path
+cache hit rate       | Platform lead   | >= 78%         | stop throttling traffic
+```
+
+This template forces action ordering, makes ownership explicit, and keeps the
+team from drifting between investigation and mitigation under stress.

package/examples/api-flow.md

@@ -44,12 +44,41 @@ error response is sent.
                           [200 OK + token]
 ```
 
-Seven stages, two branch points. Every failure path exits early — success
-continues to the next stage.
+### Timing lens: what can degrade and where
+
+```
+[Client]
+   |
+   v
+[CORS] --> [Parser] --> [Validation] --> [Controller] --> [AuthService]
+                                   |                   |
+                                   |                   +--> [401]
+                                   |
+                                   +--> [429/503]
+                                   +--> [400]
+
+[AuthService] --> [UserRepository] --> [bcrypt.compare]
+                                   |
+                                   +-- mismatch --> [401]
+                                   |
+                                   +-- hit --> [JWT sign] --> [200]
+```
+
+Error-path table:
+
+```
+stage              | symptom      | response | recovery
+-------------------|--------------|----------|-------------------
+validation failed   | 400          | reject   | fix request payload
+user not found      | 401          | reject   | prompt signup/help
+credentials mismatch| 401          | reject   | suggest retry/reset
+dependency timeout  | 503/504      | fail     | retry/backoff
+success            | 200          | token    | cache token metadata
+```
 
 ## Why this works
 
 The request lifecycle is a sequential flow with conditional branches, which
-activates feynman's flow diagram rules. Boxes (`[…]`) mark processing stages;
+activates feynman's flow-diagram rules. Boxes (`[…]`) mark processing stages;
 arrows (`-->`) mark data flow; branch splits show the conditional paths at
 validation and credential-check points.

package/examples/bug-isolation.md

@@ -0,0 +1,89 @@
+# Bug Isolation: Intermittent 500s in Checkout
+
+## Question
+
+> Checkout API starts returning 500s at random intervals under normal load. How do we
+> isolate root cause without a full-service shutdown?
+
+## Without feynman
+
+Start by checking logs, then look at DB and cache metrics, then inspect release notes,
+and finally reproduce with synthetic traffic around the failure window. If needed, roll
+back gradually while validating with a canary cohort.
+
+## With feynman
+
+Hypothesis tree:
+
+```
+intermittent 500s
+├── app code
+│   ├── null dereference
+│   └── unhandled exception
+├── data layer
+│   ├── deadlock / lock timeout
+│   ├── stale row locks
+│   └── missing index
+├── infrastructure
+│   ├── DB connection pool exhaustion
+│   └── Redis timeout
+└── operational
+    ├── rollout wave overlap
+    └── scheduled jobs interference
+```
+
+Isolation flow:
+
+```
+[Symptom observed] --> [Scope blast radius]
+                          |
+               +----------+----------+
+               |                     |
+               v                     v
+      [Single endpoint only]    [All endpoints]
+              |                     |
+          yes/no                yes/no
+              |                     |
+              v                     v
+     [Replay payload]         [Re-check infra]
+              |                     |
+               v                     v
+   [Exception trace matches]
+   [Connection errors]
+              yes/no
+              |                |
+              v                v
+        [fix app]       [next hypothesis]
+              |                |
+              v                v
+       [fix infra]    [rollback segment]
+```
+
+Impact priority:
+
+```
+▲ high
+  user checkout failure
+  payment status integrity
+  canary regression safety
+▼ low
+  low-frequency telemetry noise
+  non-critical UI latency
+```
+
+Validation decision table:
+
+```
+check             | command                        | expected
+------------------|--------------------------------|-------------------------
+error correlation  | logs + correlation ids         | grouped by checkout_id
+db pressure       | pool saturation metrics        | stable for 15m
+cache health      | hit rate and timeout count     | no timeout spike
+deployment diff   | feature flags + release notes  | no new high-risk delta
+```
+
+## Why this works
+
+Схема строит диагностику от гипотез к действиям: дерево сокращает пространство
+поиска, flow управляет последовательностью экспериментов, а приоритетный блок
+показывает, что лечится немедленно.