@albinocrabs/feynman 0.2.1 → 0.2.4

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 управляет последовательностью экспериментов, а приоритетный блок
+показывает, что лечится немедленно.

package/examples/c4-platform-diagramming.md

@@ -0,0 +1,112 @@
+# C4-Style Architecture and Request Flow
+
+## Question
+
+> Sketch a clean C4-style view for an AI documentation tool and show the
+> normal request flow. I want context, container split, component split, and a
+> clear status view for blockers.
+
+## Without feynman
+
+The tool has three users: author, reviewer, and operator. It includes a web
+client, a prompt gateway API, a rules engine, a diagram renderer, and a
+quality service that validates responses before returning them. There is
+SSO-based auth, storage for templates, and a shared observability channel.
+If the rules fail to load, the request still needs a deterministic fallback to
+text mode so the user is not blocked.
+
+## With feynman
+
+### C4 context
+
+```
+feynman-system
+├── actors
+│   ├── [Document Author]
+│   ├── [Reviewer]
+│   └── [Operator]
+├── containers
+│   ├── [Web Client]
+│   ├── [Prompt Gateway API]
+│   ├── [Rule Service]
+│   ├── [Diagram Renderer]
+│   └── [Quality Service]
+└── external systems
+    ├── [SSO]
+    ├── [Template Storage]
+    ├── [Model Provider]
+    └── [Observability]
+```
+
+### C4 container run
+
+```
+[Document Author] --> [Web Client]
+                      |
+                      v
+[Reviewer]       --> [Prompt Gateway API]
+                      |
+                      v
+                      [Auth + Rate Limit]
+                              |
+                              +-- unauthorized --> [403 / 401]
+                              |
+                              +-- authorized
+                                    |
+                                    v
+                               [Rule Service]
+                                    |
+                                    +-- rule set miss --> [Text fallback]
+                                    |
+                                    +-- rule set hit
+                                          |
+                                          v
+                                     [Diagram Renderer]
+                                          |
+                                          v
+                                       [Quality Service]
+                                          |
+                                          +-- blocked --> [Recovery Plan]
+                                          |
+                                          +-- pass --> [JSON response]
+                                          |
+                                          v
+                                  [Observability publish]
+                                          |
+                                          v
+                                   [Document Author/Reviewer]
+```
+
+### Architecture split
+
+```
+criterion      | Context (C1)        | Containers (C2)      | Components (C3)
+---------------|---------------------|----------------------|----------------------
+Main question  | Who talks to what   | Who owns boundary    | Who owns behavior
+Primary risk   | Missing actor path   | Wrong trust boundary  | Rule fallback bug
+Owner now      | Product + Ops       | Backend + Security    | Runtime rule authors
+```
+
+### Why this helps
+
+```
+┌─ Delivery readiness ────────────┐
+  context map     done
+  container flow   done
+  component split done
+  risk hotspots   identified
+└─────────────────────────────────┘
+```
+
+## Why this works
+
+Without explicit structure, the explanation is a dense paragraph. With the C4
+perspective, Feynman converts it into:
+- actor/system decomposition,
+- runtime sequence,
+- boundary+fallback behavior,
+- and explicit risk visibility.
+
+The result is understandable quickly and can be reviewed or extended as a
+single architecture baseline.
+

package/examples/context-splitting.md

@@ -0,0 +1,77 @@
+# Context Splitting: Product Initiative to Deploy a New Onboarding Assistant
+
+## Question
+
+> We want to launch a new onboarding assistant next quarter. It touches web UI, backend,
+> legal review, and customer support. How should we split work so leadership can
+> understand risk, dependencies, and rollout order in one view?
+
+## Without feynman
+
+The initiative includes multiple teams and timelines. First we should do discovery and
+alignment between engineering, legal, and support. Then UI and backend work must start,
+because both rely on design contracts. A pilot should run with 10% of new users, then
+global rollout should happen after legal and reliability checks are complete.
+
+## With feynman
+
+Scope decomposition:
+
+```
+[Onboarding assistant]
+  ├── Product & UX
+  │     ├── onboarding copy
+  │     ├── microcopy guardrails
+  │     └── in-app hints
+  ├── Platform
+  │     ├── assistant API
+  │     ├── telemetry events
+  │     └── admin flags
+  ├── Legal & Compliance
+  │     ├── consent text
+  │     └── data retention policy
+  └── Operations
+        ├── runbook
+        ├── on-call drill
+        └── rollback script
+```
+
+Cross-team launch flow:
+
+```
+[Legal approves data flow] --> [Backend API contract ready]
+                                   |
+                                   v
+ [UX/Copy draft] --> [Integration tests] --> [10% pilot]
+                                   |               |
+                           fail --> [fix + retest]   v
+                                                  [60-day rollback check]
+                                   |
+                                   +--> [full rollout]
+```
+
+Dependency safety frame:
+
+- legal-ok: mandatory
+- telemetry path: must emit onboarding_success and onboarding_fail
+- fallback: always-on silent mode if latency > 300ms
+- rollback: kill-switch <2 minutes
+
+Priority lanes:
+
+```
+▲ high
+  legal/consent review
+  backend idempotency
+  kill-switch + rollback readiness
+▼ low
+  copy polishing
+  dashboard cosmetics
+```
+
+## Why this works
+
+The question has nested uncertainty and cross-team constraints. The tree diagram makes
+the decomposition explicit. The flow diagram shows execution order and rework loops.
+The frame and priority lanes turn soft governance requirements into checkable launch
+conditions.

package/examples/feature-planning.md

@@ -0,0 +1,107 @@
+# Feature Planning: Build Internal Search or Use Managed API
+
+## Question
+
+> We need fast text search by title/body tags. Should we build it ourselves or use
+> a managed search service? Compare the options by cost, speed, and maintenance.
+
+## Without feynman
+
+Building search internally gives us full control over ranking but requires schema
+indexing work, query tuning, and ongoing reliability engineering. A managed API
+is faster to deliver and has better relevance out of the box, but it increases
+vendor dependency and recurring cost. We can reduce risk by evaluating latency,
+cost, and maintenance for a 6-month period and then revisiting.
+
+## With feynman
+
+Decision matrix:
+
+```
+Option            | build-internal                  | managed-search-service
+------------------|--------------------------------|--------------------------
+speed-to-market   | 8-12 weeks                    | 1-2 weeks
+query latency     | 60-120ms (with cache)          | 40-80ms
+maintenance       | high (2 engineers, on-call)     | low
+vendor lock-in    | none                           | medium-high
+relevance quality | custom control, tuning effort   | high, pre-tuned
+```
+
+Decision flow:
+
+```
+[Need search by title/body now?] --> [Yes]
+                                   |
+                                   v
+                     [Need search now?] --> [Evaluate managed by default]
+                                                  |
+                                                  v
+                                       [POC in 2 weeks]
+                                                 |
+                           +-------------------- +--------------------+
+                           |                                         |
+                           v                                         v
+                   [Latency/cost ok]                              [No]
+                         |                                         |
+                         +--> [Adopt]                              +--> [Re-open internal build path]
+                               |
+                               +--> [Plan v1 migration in 1 sprint]
+```
+
+Governance priority:
+
+```
+▲ high
+  Vendor contract review (SLA, data residency)
+  Incident drill: provider outage fallback plan
+▼ low
+  UI polish in search result cards
+  Advanced synonym tuning
+```
+
+Phased rollout map:
+
+```
+[Decision]
+  |
+  v
+[POC + telemetry]
+  |
+  +-- latency/cost tests fail? --+--> [Re-scope]
+  |
+  +-- latency/cost tests pass? --> [Fallback path] --> [Adoption path]
+                                  |
+                                  +--> [Cost optimization] --> [Quarterly review]
+```
+
+Rollback frame:
+
+```
+Managed API chosen:
+- fail trigger: P95 > 2x baseline + cost ↑
+- response: cut volume 50%, enable fallback
+- rollback time: 45 min
+- owner: on-call + search guild
+```
+
+Context split before execution:
+
+```
+[Business goal]
+  ├── [Performance]
+  │     ├── latency
+  │     └── availability
+  ├── [Economics]
+  │     ├── direct cost
+  │     └── hidden support cost
+  └── [Risk]
+        ├── lock-in
+        ├── security
+        └── reversibility
+```
+
+## Why this works
+
+The plain comparison becomes explicit with columns, and the execution path becomes
+operational through a flow diagram. This helps teams decide with one view of
+trade-offs and controls.