- CLAUDE.md Key Conventions: 'App bootstrap' rule rewritten as 'Three
binding modes per feature' — describes USE_DEV_SEED + NODE_ENV
resolution order and the new ./di/bind-dev-seed export.
- AGENTS.md (root): exports list now mentions ./ui + ./di/bind-dev-seed;
Per-feature public-API surface table gains a row; Apps section shows
the bindAll() dispatcher with three-rule logic.
- docs/architecture/vertical-feature-spec.md §6: file shape now
includes bind-dev-seed.ts, bind-dev-seed.test.ts, __seeds__/dev.ts;
package.json exports list updated to include ./di/bind-dev-seed.
- docs/architecture/data-flow-explainer.html: anatomy tree gains
__seeds__/ row; LAYERS.di description updated with new binders +
cross-link to di-explainer.html; new LAYERS.seeds entry; public-
surface card expanded to six subpaths.
- docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md
§7: new 'Post-Plan-9: dev-seed binders' entry summarizing the rollout
(commits, per-feature additions, app wiring, tests, turbo, docs).
- bind-production.test.ts: dispatcher tests use vi.stubEnv (typesafe
way to test process.env in TypeScript 5+ with @types/node read-only
process.env types). 4 dispatcher tests + 2 bindAllProduction tests
= 7 tests total.
User pushback: 'I already need mock data for dev and for testing at
runtime' — i.e., the dual role of the mock is obvious, not surprising.
Earlier framing was condescending.
Reframe around 'runtime reach':
- Section blurb leads with 'three artifacts at different distances
from runtime'
- Three-roles card intro: same neighborhood, different reach. Mock is
reached by runtime; contract + factory only by tests.
- 'The mock has two jobs' → 'The mock is reached from two directions
— both legitimate, neither is the test version'.
- Contract framing now leads with its real purpose: it tests the mock
alongside the real impl so you can trust the mock as a runtime
artifact.
User asked: 'arent mocks also related to testing?' — yes, but the mock
plays two roles where the contract and factory play one each. §04 now
opens with that framing.
What's new:
- Section title bumped to 'Mocks, contracts & factories'
- New three-roles diagram at the top of §04 visualizing the chain:
IArticlesRepository → MockArticlesRepository + ArticlesRepository
→ articlesRepositoryContract → articleFactory
- Two ordered lists explaining the mock's dual job (DI default binding
+ direct test fake) and the contract/factory's single test-only roles
- Three new expandable code examples:
· the mock as DI binding (real BlogModule code)
· the mock as direct test fake (use-case test, no container)
· the contract running against both impls (proof-of-parity)
- New CSS for .three-roles-diagram, .role-* boxes, .role-arrow with
vertical connector lines, .role-jobs lists with counter-leading
decimal numbering
The existing Contracts and Factories cards stay in place below — they
provide the deeper detail on each individual artifact.
Single-file HTML at docs/architecture/data-flow-explainer.html.
Self-contained — Google Fonts (Fraunces + JetBrains Mono) is the only
external resource; all interactivity is vanilla JS, all diagrams are
inline SVG/CSS.
Five sections:
01. Feature anatomy — clickable folder tree, layer detail card swaps
to explain entities / application / infrastructure / interface-
adapters / di / integrations / ui / __factories__ / __contracts__
/ public surface.
02. Request flow — step-through pipeline (12 stages, including the
success/error fork) with prev/next/play and a feature picker
(auth, blog, marketing-pages, navigation, media). Each feature
swaps real code snippets, the procedures.ts error map, and the
use-case/controller pattern.
03. Dependency injection — interactive DI canvas with default/prod
toggle so the user sees the same symbol resolving to mock vs
real Payload-backed impl. Real module.ts and bind-production.ts
code blocks below.
04. Contracts and factories — expandable sections with the actual
defineContractSuite + defineFactory code from packages/blog.
05. Verdict — short answer (yes), tradeoffs, badge row.
Editorial aesthetic: cream paper, deep ink, oxblood accent, Fraunces
display + JetBrains Mono code. Subtle paper noise + ruled-line bg.
No CDN scripts beyond fonts.
