@albinocrabs/feynman 0.2.0 → 0.2.1

package/docs/visual-patterns.md

@@ -0,0 +1,253 @@
+# Visual Patterns: Research Foundation
+
+How feynman's rules derive from visual communication research.
+
+---
+
+## Core Principle
+
+A diagram should reduce the cognitive work required to extract information.
+When prose describes a structure, the reader must reconstruct that structure
+mentally. A diagram presents the structure directly.
+
+feynman operationalizes this principle in eight lint rules (L01-L08) that
+enforce correctness of the most common ASCII diagram patterns.
+
+---
+
+## Tufte: Data-Ink Ratio
+
+**Source:** Edward R. Tufte, *The Visual Display of Quantitative Information*, 2nd ed.
+Graphics Press, 2001.
+
+Tufte's central rule: maximize the ratio of data ink to total ink. Remove
+everything that does not carry information.
+
+```
+data-ink ratio = (ink carrying data) / (total ink in graphic)
+
+high ratio  -->  dense, clear
+low ratio   -->  cluttered, noisy
+```
+
+**Small multiples** (Tufte, *Envisioning Information*, 1990) — repeat the same
+graphic structure across multiple instances to enable comparison. The same
+visual encoding applied consistently lets the eye detect differences without
+re-learning the encoding.
+
+### How feynman embodies Tufte
+
+**L08 frame width discipline** directly enforces data-ink ratio in ASCII frames.
+Every row in a frame block must have the same display width. Ragged right
+edges add visual noise without information.
+
+Valid (consistent width — passes L08):
+
+```
+┌─ Status ──────┐
+│  item-a  ok   │
+│  item-b  wait │
+└───────────────┘
+```
+
+Invalid (ragged right edge — fails L08):
+
+```text
+┌─ Status ─────┐
+│  item-a done │
+│  item-b in progress│
+└────────┘
+```
+
+**L01 box closure** enforces structural completeness. An unclosed box is
+decoration without information — the visual boundary promises containment
+but does not deliver it.
+
+---
+
+## Few: Pre-Attentive Attributes
+
+**Source:** Stephen Few, *Show Me the Numbers*, 2nd ed. Analytics Press, 2012.
+Stephen Few, *Now You See It*. Analytics Press, 2009.
+
+Pre-attentive processing happens in under 250 ms, before conscious attention.
+Attributes processed pre-attentively include: position, length, size, color,
+orientation, shape, and enclosure.
+
+For ASCII diagrams, the relevant pre-attentive attributes are:
+
+```
+attribute    | ASCII representation        | activates
+-------------|-----------------------------|--------------------------
+position     | indentation, left-alignment | hierarchy, sequence
+enclosure    | frame blocks                | grouping
+shape        | [box] vs tree vs lines      | diagram type
+orientation  | --> (horizontal) vs |       | flow direction
+```
+
+Few's dashboard principle: a viewer should be able to identify the most
+important item within 5 seconds. In a code review response, `▲` and `▼`
+markers make the highest and lowest priority items instantly findable.
+
+### How feynman embodies Few
+
+**L06 priority scale** enforces that `▲` and `▼` always appear together.
+A scale with only one end is not a scale — it lacks the reference point
+that makes the pre-attentive contrast useful.
+
+Valid (both ends — passes L06):
+
+```
+▲ high
+  critical-bug
+  security-patch
+▼ low
+  cosmetic-fix
+```
+
+Invalid (one end only — fails L06):
+
+```text
+▲ high
+  critical-bug
+  security-patch
+```
+
+Without `▼ low`, the reader cannot determine whether "security-patch" is at
+the top, middle, or bottom of the full severity range.
+
+**L05 flow integrity** enforces that boxes in sequence have arrows between them.
+The pre-attentive attribute of position implies connection only when supported
+by an explicit visual link. Two boxes next to each other with no arrow are
+ambiguous — parallel? sequential? unrelated?
+
+---
+
+## Bertin: Visual Variables
+
+**Source:** Jacques Bertin, *Semiology of Graphics*, trans. William J. Berg.
+University of Wisconsin Press, 1983 (orig. 1967).
+
+Bertin identified seven visual variables: position, size, value (lightness),
+texture, color, orientation, and shape. Each variable has different
+*retinal properties* — they vary in whether they communicate order, quantity,
+or mere difference.
+
+For monochrome ASCII (no color, no size variation), the available variables are:
+
+```
+variable     | ASCII encoding                  | retinal property
+-------------|─────────────────────────────────|------------------
+position     | column, indentation level        | order, quantity
+orientation  | --> (horizontal) | (vertical)    | difference
+shape        | frame vs [box] vs tree vs scale  | difference
+texture      | - vs space vs | fill             | difference
+```
+
+Bertin's key insight: variables must be used consistently within a graphic.
+Inconsistent use of a variable adds noise without information.
+
+### How feynman embodies Bertin
+
+**L02 tree chars** enforces consistent use of the shape variable.
+In ASCII trees, `├──` signals "more siblings follow" and `└──` signals
+"last sibling." Using `├──` for the last child violates Bertin's consistency
+requirement — the shape variable now carries conflicting information.
+
+Valid (correct last-child marker — passes L02):
+
+```
+root
+├── child-a
+├── child-b
+└── child-c
+```
+
+Invalid (wrong last-child marker — fails L02):
+
+```text
+root
+├── child-a
+├── child-b
+├── child-c
+```
+
+**L03 arrow style** enforces consistency of the shape variable for directional
+links. `-->`, `─→`, and `──>` all encode "directed connection," but mixing
+them within a single diagram adds visual noise. The reader must expend
+attention verifying that mixed styles are equivalent rather than distinct.
+
+Valid (consistent style — passes L03):
+
+```
+[A] --> [B] --> [C] --> [D]
+```
+
+Invalid (mixed styles — fails L03):
+
+```text
+[A] --> [B] --> [C] --> [D]
+```
+
+Note: the invalid example above only becomes invalid when `→` appears alongside
+`-->` in the same diagram block.
+
+**L04 column widths** enforces consistent position encoding in tables.
+Misaligned column separators break the visual grid — the position variable
+now encodes nothing, forcing the reader to count pipes instead of reading
+structure.
+
+---
+
+## Knaflic: Annotation and Focus
+
+**Source:** Cole Nussbaumer Knaflic, *Storytelling with Data*. Wiley, 2015.
+
+Knaflic emphasizes that every visual element should serve a purpose, and that
+annotation should guide attention to what matters. Unlabeled structures leave
+the reader to infer the author's intent.
+
+**L07 no mermaid/ASCII mix** enforces a single visual vocabulary per document.
+Mixing Mermaid syntax and ASCII diagrams forces the reader to context-switch
+between two encoding systems. It also signals that the response was assembled
+without a deliberate visual strategy.
+
+---
+
+## Principle-to-Rule Mapping
+
+```
+principle                     | rule | what it enforces
+------------------------------|------|---------------------------------------------
+Tufte: data-ink ratio         | L08  | frame rows same width (no wasted ink)
+Tufte: structural completeness| L01  | every box-open has a matching box-close
+Few: pre-attentive scale      | L06  | both scale ends (▲ and ▼) always present
+Few: position implies sequence| L05  | boxes in sequence require explicit arrows
+Bertin: shape consistency     | L02  | last tree child uses └── not ├──
+Bertin: shape consistency     | L03  | one arrow style per diagram
+Bertin: position encoding     | L04  | table column counts consistent across rows
+Knaflic: single vocabulary    | L07  | no mermaid + ASCII mix in same document
+```
+
+---
+
+## Bibliography
+
+- Tufte, Edward R. *The Visual Display of Quantitative Information*, 2nd ed.
+  Cheshire, CT: Graphics Press, 2001.
+
+- Tufte, Edward R. *Envisioning Information*. Cheshire, CT: Graphics Press,
+  1990.
+
+- Few, Stephen. *Show Me the Numbers: Designing Tables and Graphs to Enlighten*,
+  2nd ed. Burlingame, CA: Analytics Press, 2012.
+
+- Few, Stephen. *Now You See It: Simple Visualization Techniques for Quantitative
+  Analysis*. Burlingame, CA: Analytics Press, 2009.
+
+- Bertin, Jacques. *Semiology of Graphics: Diagrams, Networks, Maps*. Trans.
+  William J. Berg. Madison, WI: University of Wisconsin Press, 1983.
+  (Original: *Semiologie graphique*, Gauthier-Villars, 1967.)
+
+- Nussbaumer Knaflic, Cole. *Storytelling with Data: A Data Visualization
+  Guide for Business Professionals*. Hoboken, NJ: Wiley, 2015.

package/examples/algorithm-explain.md

@@ -0,0 +1,70 @@
+# Algorithm: Token-Bucket Rate Limiter
+
+## Question
+
+> Explain how a token-bucket rate limiter works. Walk through the state
+> machine and the per-request decision logic.
+
+## Without feynman
+
+A token bucket holds up to N tokens. Tokens are added at a fixed rate (the
+refill rate). When a request arrives, one token is consumed. If the bucket
+is empty the request is rejected. Over time the bucket refills up to its
+capacity. Bursts are handled because a full bucket allows N requests
+immediately; sustained overload is prevented because refill is bounded.
+
+## With feynman
+
+State machine:
+
+```
+[bucket: N tokens]
+        |
+        +-- tick (every 1/rate seconds)
+        |          |
+        |          v
+        |   [add 1 token, cap at N]
+        |
+        +-- request arrives
+               |
+               v
+        [check bucket]
+               |
+        empty -+- has token
+        |             |
+        v             v
+  [reject 429]     [tokens--]
+                      |
+                      v
+               [allow request]
+```
+
+Per-request decision flow:
+
+```
+[request] --> [read bucket state] --> [tokens > 0?]
+                                            |
+                                   yes -----+------ no
+                                   |               |
+                                   v               v
+                            [tokens--]      [reject 429]
+                            [allow]         [retry-after]
+```
+
+Key properties:
+
+```
+property         | value
+-----------------|----------------------------------
+burst capacity   | N tokens (full bucket)
+sustained rate   | refill rate (tokens/second)
+penalty          | token consumed even on error
+state storage    | counter + last_refill timestamp
+```
+
+## Why this works
+
+An algorithm with internal states and per-step decisions maps to feynman's
+flow-diagram rule. The state diagram shows the two concurrent processes
+(tick refill and request consume); the flow diagram shows per-request
+branching; the table captures the rate-limit contract in comparable columns.

package/examples/api-flow.md

@@ -0,0 +1,55 @@
+# API Flow: POST /api/login Request Lifecycle
+
+## Question
+
+> Walk me through exactly what happens when a client sends POST /api/login.
+> Include middleware, validation, and the response path.
+
+## Without feynman
+
+When a login request arrives the framework runs the CORS middleware first,
+then body-parser parses the JSON payload. The validation layer checks that
+email and password fields are present and well-formed. The controller calls
+the auth service, which queries the database. If credentials match, a session
+token is issued and returned. If anything fails along the way an appropriate
+error response is sent.
+
+## With feynman
+
+```
+[Client] --> [CORS middleware] --> [body-parser] --> [Validation]
+                                                          |
+                                                   pass --+-- fail
+                                                   |           |
+                                                   v           v
+                                            [Controller]     [400 Bad Request]
+                                                   |
+                                                   v
+                                            [AuthService]
+                                                   |
+                                                   v
+                                            [UserRepository]
+                                                   |
+                                         found ----+---- not found
+                                         |                   |
+                                         v                   v
+                                  bcrypt.compare       [401 Unauthorized]
+                                         |
+                                 match --+-- mismatch
+                                 |               |
+                                 v               v
+                          [issue JWT]     [401 Unauthorized]
+                                 |
+                                 v
+                          [200 OK + token]
+```
+
+Seven stages, two branch points. Every failure path exits early — success
+continues to the next stage.
+
+## Why this works
+
+The request lifecycle is a sequential flow with conditional branches, which
+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/architecture-review.md

@@ -0,0 +1,50 @@
+# Architecture Review: Auth Service Topology
+
+## Question
+
+> How does our auth service connect to the user database and rate limiter?
+> Walk me through the request path.
+
+## Without feynman
+
+The auth service receives incoming requests and first checks the rate limiter
+to see if the caller has exceeded their quota. If not, it queries the user
+database to validate credentials. On success it issues a JWT and logs the
+event. If the rate limiter trips, the request is rejected before the database
+is ever touched.
+
+## With feynman
+
+```
+[POST /auth/token]
+        |
+        v
+[Rate Limiter: Redis, 100 req/60s per IP]
+        |
+  over limit --> 429 Too Many Requests
+        |
+  within limit
+        |
+        v
+[Auth Service: validate credentials]
+        |
+        v
+[UserDB: SELECT hash WHERE email = ?]
+        |
+        v
+[bcrypt.compare(password, hash)]
+        |
+  match --> issue JWT (RS256, 15 min TTL) --> 200 OK
+        |
+  no match --> 401 Unauthorized
+```
+
+Three components, one path. Rate limiter sits in front — database never sees
+throttled traffic.
+
+## Why this works
+
+The response describes a hierarchy of sequential components with decision
+branches, activating feynman's flow-integrity and frame-block rules. The flow
+diagram shows each processing stage as a box with arrows marking the request
+path and branch outcomes.

package/examples/code-review.md

@@ -0,0 +1,55 @@
+# Code Review: PR with Mixed-Severity Issues
+
+## Question
+
+> Review this PR. It has a SQL injection vulnerability in the login handler,
+> a missing null check that could cause crashes, and a variable name that
+> doesn't follow conventions. How should I prioritize the fixes?
+
+## Without feynman
+
+The SQL injection is the most critical issue because it's a security
+vulnerability that could expose user data. The missing null check is serious
+because it causes crashes in production but doesn't expose data. The naming
+convention issue is low severity — it's cosmetic and only affects readability.
+Fix security first, stability second, style last.
+
+## With feynman
+
+Priority order:
+
+```
+▲ high
+  SQL injection (login handler, line 47)
+  — user input concatenated into query string
+  — fix: parameterized query or ORM method
+
+  null check missing (user.profile access, line 83)
+  — crashes when user has no profile row
+  — fix: optional chaining or guard clause
+
+▼ low
+  variable name: usr_Obj → user (line 31)
+  — convention: camelCase, descriptive noun
+  — fix: rename + search-replace in file
+```
+
+Issue comparison:
+
+```
+issue             | severity | risk           | fix effort
+──────────────────|──────────|────────────────|────────────
+SQL injection     | critical | data breach    | 15 min
+null crash        | high     | prod outage    | 5 min
+naming convention | low      | readability    | 2 min
+```
+
+Fix sequence: null check (5 min, unblock prod) → SQL injection (15 min,
+close security hole) → rename (2 min, cleanup). Total: ~22 min.
+
+## Why this works
+
+Issues ordered by severity map to feynman's priority-scale rule (▲▼ markers).
+A multi-criteria comparison of the same issues across dimensions (risk, effort)
+activates the comparison-column rule. Both diagrams together give a complete
+picture — one for prioritization, one for planning.

package/examples/db-schema.md

@@ -0,0 +1,48 @@
+# Database Schema: E-commerce Entity Model
+
+## Question
+
+> Show me the relationships between users, orders, and products.
+> Which tables are involved and how do they connect?
+
+## Without feynman
+
+Users can place multiple orders. Each order contains one or more line items,
+and each line item references a product. The users table has a primary key
+that the orders table references via user_id. The order_items junction table
+connects orders to products with a quantity field. Products belong to
+categories via a category_id foreign key.
+
+## With feynman
+
+```
+users                    orders                   products
+─────────────────────    ─────────────────────    ─────────────────────
+id (PK)                  id (PK)                  id (PK)
+email (unique)           user_id (FK → users)     name
+password_hash            created_at               price
+created_at               status                   stock_count
+                         total_amount             category_id (FK)
+```
+
+Entity relationships:
+
+```
+users
+└── orders (user_id → users.id)
+    └── order_items (order_id → orders.id)
+        └── products (product_id → products.id)
+
+categories
+└── products (category_id → categories.id)
+```
+
+One user → many orders → many order_items → one product per item. Categories
+are a separate hierarchy connected only to products.
+
+## Why this works
+
+A database schema is a hierarchy of related entities — feynman's tree-diagram
+and comparison-column rules both activate. Side-by-side columns show each
+table's fields at a glance; the tree shows foreign-key relationships across
+three levels.

package/examples/deploy-pipeline.md

@@ -0,0 +1,58 @@
+# Deploy Pipeline: Monorepo CI/CD
+
+## Question
+
+> Draw the CI/CD pipeline for our monorepo. We run lint, test, and build in
+> parallel, then deploy to staging, run smoke tests, and promote to production.
+
+## Without feynman
+
+The pipeline starts with lint, unit tests, and the build running in parallel.
+Once all three pass the deploy job sends the artifact to staging. After that
+the smoke test suite runs against staging. If smoke tests pass, a manual
+approval gate is required before the production deployment goes out. If smoke
+tests fail, the pipeline stops and alerts on-call.
+
+## With feynman
+
+```
+[push / PR] --> [trigger CI]
+                      |
+          .-----------+-----------.
+          |           |           |
+          v           v           v
+       [Lint]      [Test]      [Build]
+          |           |           |
+          '-----------+-----------'
+                      |  all pass
+                      v
+              [Deploy --> Staging]
+                      |
+                      v
+              [Smoke Tests]
+                      |
+              pass ---+--- fail
+              |               |
+              v               v
+       [Manual Approval]     [Stop + Alert]
+              |
+              v
+       [Deploy --> Production]
+              |
+              v
+       [Rollout health check]
+              |
+          ok -+- degraded
+              |         |
+              v         v
+          [Done]     [Auto-rollback]
+```
+
+Three parallel jobs gate everything downstream. Production only reachable
+after staging smoke tests and human approval.
+
+## Why this works
+
+A pipeline with parallel stages and conditional branches is feynman's
+canonical flow-with-branch pattern. The parallel fork and join shows
+concurrent jobs; sequential arrows show the rest of the path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@albinocrabs/feynman",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Claude Code and Codex plugin that auto-injects ASCII diagram rules into every AI request via UserPromptSubmit hook",
   "license": "MIT",
   "author": "apolenkov",
@@ -38,16 +38,26 @@
     "skills/",
     "hooks.json",
     ".codex-plugin/",
+    "docs/",
+    "examples/",
     "install.sh",
     "uninstall.sh",
     "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "scripts": {
     "test": "node --test tests/*.test.js",
     "coverage": "c8 --reporter=text --reporter=lcov node --test tests/*.test.js",
-    "ci": "npm run coverage",
-    "lint": "node bin/feynman-lint.js"
+    "lint": "node bin/feynman-lint.js",
+    "test:docs": "node scripts/check-docs.js",
+    "test:release": "node scripts/release-smoke.js",
+    "build": "node scripts/build-package.js",
+    "changelog": "node scripts/generate-changelog.js",
+    "ci": "npm run coverage && npm run test:docs && npm run test:release && npm run build",
+    "prepublishOnly": "npm run ci"
   },
   "devDependencies": {
     "c8": "^10"