b2c-app-builder 0.221.39

package/knowledge/design/design-acceptance.md

@@ -0,0 +1,199 @@
+# Design Acceptance Evidence
+
+Use this contract when accepting the complete mobile and landing design. The existing grader remains advisory by default. This strict check validates the completeness and integrity of an independent review. It does not compute beauty, authenticate a human identity, run an app, or grant release authority. It does require the report reviewer session to equal the engine-issued owner of the exact current audit attempt.
+
+The session runtime must establish the producer and independent reviewer identities. The reviewer must open the actual captures and execute or inspect the recorded interactions before writing observations. Distinct strings in a JSON file alone are not proof of an independent session.
+
+## Owners
+
+- `product.yaml` owns accepted product scope. Its `meta.status` must be `accepted`.
+- `DESIGN.md` owns an `acceptance` map in its existing YAML frontmatter. Explain it in the Design Acceptance section. It declares detailed design contracts, surface coverage, implementation paths, state applicability, locales, interactions, and the frozen rubric path.
+- `studio/seed/business.json` owns the existing screen and funnel inventory. Every required native screen needs coverage on every selected platform. Landing and other web surfaces need mobile and desktop coverage. Required rows must be `ready`; blocked and draft rows remain incomplete.
+- Existing files under `design/reviews/rubrics/` own frozen criteria. A Markdown rubric uses a `designRubric` map in YAML frontmatter. A JSON rubric may store the same map directly. Do not create a second rubric elsewhere.
+- Native producers own capture, interaction, and receipt files under their selected `proof/ios-simulator/`, `proof/ios-device/`, `proof/android-emulator/`, or `proof/android-device/` lane. The landing producer owns browser evidence, response bytes, manifests, and launch receipts under `growth/landing/proof/`. Audit-owned `design/reviews/` paths cannot supply producer evidence.
+- `design/proofs/design-acceptance.json` is the audit index. Its capture and interaction rows contain only an evidence ID, a hashed receipt pointer, and engine provenance for the accepted producer attempt. It does not copy producer facts or become a second state store.
+- `design/reviews/IMPLEMENTATION_REVIEW.md` owns reviewer prose. It must contain exactly one `Acceptance report SHA-256: <64 lowercase hex>` line bound to the current bytes of `design/proofs/design-acceptance.json`.
+- The current `workflow.design.implementation-craft-audit` attempt owns both files above. Their run-state bindings must name that attempt and its engine-issued owner session. An invented reviewer label, an older audit attempt, or an audit file changed after production fails closed.
+
+The exact typed shapes and schemas are exported from `checks/validation/business/design/design-acceptance.ts`. Schema version 1 rejects unknown fields and verdicts.
+
+## Authored Coverage
+
+The `acceptance` map has `schemaVersion: 1`, `status: accepted`, `designContractPaths`, `surfaces`, and `exclusions`. `designContractPaths` lists every detailed contract under `design/screens/` and `design/flows/` that the `DESIGN.md` body links. The list may be empty when the global contract is sufficient. A linked contract omitted from the list, or a listed contract without a body link, fails coverage. Every listed file is hashed as both an authored input and part of the candidate fingerprint, so changing a detailed screen or flow invalidates acceptance.
+
+Each surface declares:
+
+| Field                 | Meaning                                                                                                                                                                                                                                       |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                  | Unique review target, such as `home-ios` or `landing-mobile`.                                                                                                                                                                                 |
+| `surfaceId`           | Existing studio screen or funnel ID.                                                                                                                                                                                                          |
+| `kind`                | `native`, `landing`, or `web`.                                                                                                                                                                                                                |
+| `platform`            | A selected native platform from studio, or `web`. A stack name never proves an untested device platform.                                                                                                                                      |
+| `viewport`            | `native`, `mobile`, or `desktop`. Browser mobile is at most 600 CSS pixels wide; desktop is at least 900. Add intermediate layouts as further product-specific tests when needed.                                                             |
+| `routePath`           | Exact browser URL path, such as `/` or `/landing/`. It is required for landing and web surfaces and forbidden for native surfaces.                                                                                                            |
+| `productScreenIds`    | Accepted `class.screen` instance IDs represented by this target. All accepted product screen instances require a mapping.                                                                                                                     |
+| `implementationPaths` | Explicit source files or directories whose changes invalidate the candidate. Include actual surface code, shared tokens/assets, relevant dependencies, and the entrypoint used to build. Do not include caches or the evidence report itself. |
+| `rubricPath`          | Frozen rubric in `design/reviews/rubrics/`.                                                                                                                                                                                                   |
+| `locales`             | Every locale this target must support.                                                                                                                                                                                                        |
+| `states`              | States requiring a runtime capture for every locale.                                                                                                                                                                                          |
+| `stateExclusions`     | Unique `{state, reason}` entries for non-applicable loading, empty, error, offline, or permission-denied states. State the product reason. A required state cannot be excluded, and a state cannot be excluded twice.                         |
+| `interactions`        | `{id, action, expected}` for the complete task and recovery/accessibility scenarios. The report cannot remove them.                                                                                                                           |
+
+All surfaces require `default` and `reduced-motion`. Native requires `large-text` and `screen-reader`. Web requires `no-js` and `keyboard`. Each surface must cover or explain the non-applicability of `loading`, `empty`, `error`, `offline`, and `permission-denied`. These are minimum coverage rules, not the full product specification.
+
+A surface exclusion has `surfaceId` and a substantive product reason. It is valid only when the existing studio row is already `not_needed`. Changing the report cannot remove accepted scope. A complete consumer business still needs actual native and landing surfaces.
+
+## Frozen Calibration
+
+The rubric has `schemaVersion: 2`, `id`, `frozenAt`, `references`, and `criteria`. Freeze it before producing the candidate. Version 1 rubrics require a reviewed source-resolution update and fresh acceptance, not an automatic schema-stamp rewrite.
+
+Each reference has an `id`, HTTPS `url`, `{path, sha256}` artifact, `kind` (`visual`, `interaction`, or `documentation`), and a concrete `observation`. A visual reference must include an inspected PNG or JPEG image. Include at least one visual reference and one complementary interaction or documentation reference. Preserve the source date and inspection limitations inside the referenced pack.
+
+Each selected reference also has `resolution`: `status`, `observedAt`, `provider`, and `sourceId`,
+with `validUntil` and `substitutesFor` when applicable. Only `resolved` or `retained_snapshot` can
+support a lock. The observation must not postdate the frozen rubric. Explicit expiry must not
+have passed at review. A retained, hashed capture can remain useful when its old signed URL
+expires; it is not a claim that a remote catalog is currently reachable.
+
+Record failed source attempts in the reference pack, not as accepted calibration evidence.
+Choose only declared alternatives that cover the required visual, interaction or documentation
+kind. Documentation cannot replace motion evidence. `check:design-md` validates these source
+requirements at an accepted/locked scope; `check:design-acceptance` uses the same validator.
+Neither check grants access to another provider or spending authority.
+
+Each criterion has an `id`, `facet`, product-specific `condition`, `minimum` (`meets` or `exceeds`), and `referenceIds`. Cover all seven facets: `coherence`, `originality`, `craft`, `functionality`, `accessibility`, `motion`, and `cross_surface_identity`. Use separate criteria when one facet has several independent requirements. These are ordinal judgments against explicit conditions, not an objective numerical beauty score.
+
+Do not weaken a frozen floor after seeing a failed candidate. A legitimate product or rubric revision changes the input hash and requires fresh production, capture, and review.
+
+## Evidence Report
+
+The report records source hashes for `product.yaml`, `DESIGN.md`, `studio/seed/business.json`, and every declared `designContractPaths` entry. It records the candidate source inventory hash, production time and producer `{id, sessionId}`, exact native and browser runtimes, independent reviewer `{id, sessionId}`, review time, `verdict: pass`, surface reviews, and findings. `reviewer.sessionId` comes from the immutable execution identity in the current audit brief and must match the latest implementation-craft audit attempt owner. The review time must fall inside that attempt. A surface capture or interaction row is only `{id, receipt, producer}`. `receipt` is the current path and SHA-256 of the producer receipt. `producer` names its workflow ID, attempt ID, and engine-owned accepted output fingerprint.
+
+The helper `designCandidateFingerprint(root, scope)` hashes every detailed design contract and every regular implementation file under the authored implementation paths, in stable path order. Added implementation files also change the fingerprint. Producer evidence roots are excluded when they sit beneath an implementation directory, so capturing a candidate does not change that candidate. The helper `designArtifact(root, relativePath)` returns the current `{path, sha256}` for an evidence file. These helpers describe files; they do not create a review or invent evidence.
+
+### Producer-bound capture and interaction receipts
+
+A capture receipt is a strict `design-capture` object. An interaction receipt is a strict `design-interaction` object. Both record `schemaVersion`, `surfaceId`, `evidenceId`, the evidence artifact path and byte SHA-256, the exact candidate hash, observed timestamp, named tool and version, producer session ID, source, and platform. The capture receipt also records state, locale, pixel dimensions, logical viewport, scale, and settings. The interaction receipt also records the authored interaction ID, locale, cited capture IDs, passing result, and concrete observation.
+
+A native receipt records `runtimeId` and a device object with stable ID, model identifier, OS version, and OS build. The validator joins that identity to the current installed runtime and its platform receipt. A browser receipt records `runtimeId`, `browserContextId`, browser name and version, and OS identity. An interaction can cite only captures from the same registered runtime and browser context.
+
+The validator reads `run/run-state.json` for every evidence reference. It derives the producer node from the declared workflow, requires the current latest attempt to be succeeded, and requires the receipt session to equal that attempt owner. The native producer must have exactly one accepted current-attempt binding at `proof`; the landing producer must have exactly one at `growth/landing`. The validator recomputes that binding from workspace bytes and derives its one-output fingerprint instead of trusting the report's label. Both the receipt and its evidence artifact must remain beneath the binding and their platform-specific producer lane. A receipt written or changed by the audit after producer acceptance makes the binding stale. The implementation audit workflow can never be the receipt producer.
+
+This engine join is required even when the receipt JSON looks valid. A shell-capable audit worker can write JSON and refresh report prose. It cannot turn those bytes into accepted producer output by editing the report. Re-run the owning native or landing producer when capture or interaction evidence changes.
+
+### Exact browser runtime identity
+
+Every report has a `browserRuntimes` registry. Each entry has a unique ID. It records the candidate hash, current source and build fingerprints, served origin and document URL, browser name and version, context ID, OS identity, launch and navigation transcript hashes, and one matching receipt.
+
+The landing producer authors `growth/landing/browser-proof.json` before proof. It names one runtime ID, the browser acceptance surface IDs, their exact source roots, the current candidate SHA-256, every built resource and its served URL path, the entrypoint, served origin and URL, and the Chrome channel. Run `b2c browser-proof --workspace . --session-id <authorization.executionIdentity>` while the local server is available. The command refuses stale candidate config, source roots that differ from the selected acceptance surfaces, build paths outside those roots, a route that differs from `routePath`, an insecure remote origin, a redirect to another page, or served response bytes that differ from the current build.
+
+The command creates a fresh Chrome process and browser context. It writes an immutable attempt directory under `growth/landing/proof/browser-runtimes/` and atomically selects its receipt through `growth/landing/proof/browser-proof.json` only after the whole bundle succeeds. `check:browser-runtime-proof` recomputes the config, candidate, source, build, response, and transcript bindings. It also requires the supplied `--session-id` and proof timeline to match the current engine-issued landing producer attempt. An old session cannot be copied into a new accepted landing binding.
+
+The landing producer writes a strict `browser-runtime-launch` receipt under `growth/landing/proof/`. Its `source.root` must be the canonical business workspace. Its sorted `source.roots` must equal the authored `implementationPaths` for every browser surface that cites this runtime. The validator recomputes that source fingerprint from current workspace bytes. A label cannot bind an old build to changed landing source.
+
+The receipt points to a strict build manifest. That manifest binds the source fingerprint, one entrypoint, and every build file used by the page. Each file must remain under an authored implementation path and keep its recorded SHA-256. The validator derives the build fingerprint from the canonical manifest. The report and launch receipt must name that same fingerprint.
+
+The receipt also points to a resource manifest. It records the exact origin, document URL, context ID, resource URLs, build paths, and retained response bytes. Every response must match its current build file. The served document must match the build entrypoint. The manifest must cover the build exactly. Remote origins require HTTPS. Explicit `localhost`, `127.0.0.1`, and `[::1]` origins may use HTTP for local proof.
+
+The launch and navigation transcripts are distinct hashed artifacts. The timeline starts after candidate production. It launches the isolated browser context, completes navigation with a 2xx or 3xx status, and finishes before review. The final navigation URL must equal the served URL. Its pathname must equal each citing surface's authored `routePath`.
+
+Each browser surface review declares its exact `runtimeIds`. Every browser capture and interaction receipt cites one registered runtime and its exact context ID. Its browser, OS, producer session, and timestamp must match the launch receipt. Captures and interactions happen after navigation. An interaction can cite only captures from that same runtime and context. This join prevents an old tab or unrelated route from being relabeled with the current candidate hash.
+
+### Exact native runtime identity
+
+Every report has a `nativeRuntimes` registry. Each entry records a unique `id`, `platform` (`ios` or `android`), platform-specific `target`, candidate hash, source fingerprint, stable device identity, operating-system identity where required, and the path and hash of one matching receipt. The validator recomputes the receipt source fingerprint inside the current business workspace. An old receipt cannot be relabeled as a changed candidate.
+
+An iOS simulator entry uses `platform: ios` and `target: simulator`. It records bundle ID, build number, executable SHA-256, whole-bundle content SHA-256, source fingerprint, and simulator ID. It consumes the structured rung-2 artifact from the native iOS Route Ladder. The receipt must show one passing build, build verification, install, installed-byte readback, and terminated-process launch in that order. Its `installedBuild` must match every runtime identity field. This route can prove ordinary simulator captures and interactions. It cannot prove VoiceOver behavior on a physical iPhone.
+
+An iOS physical-device entry uses `platform: ios` and `target: physical-device`. It consumes a `physical-ios-install` receipt from the trusted physical-device run and also records `deviceModelIdentifier`, `osVersion`, and `osBuild`. The receipt binds the candidate and built app to the exact installation input through its bundle ID, build number, executable hash, bundle-content hash, app path, and source fingerprint. It then records installed app bundle/build readback from the same stable physical iPhone, followed by launch. The receipt device ID, iPhone model identifier, OS version, and OS build must match the runtime. Build, install, device-readback, and launch transcripts each require a distinct hashed artifact.
+
+An Android runtime uses `platform: android` and `target: emulator` or `physical-device`. It records package name, integer `versionCode`, the built package format and SHA-256, the exact installation APK SHA-256, source fingerprint, device ID and model identifier, API level, OS version, and OS build. An `android-emulator-install` receipt binds an emulator under `proof/android-emulator/`; a `physical-android-install` receipt binds a physical Android device under `proof/android-device/`. Both receipts must record build, install, installed-app package/version readback, and launch on the same device in order. The receipt `source.root` must be the current business workspace. Its deduplicated `source.roots` must equal the Android native surface `implementationPaths` exactly; a convenient unchanged subset cannot stand in for the current app. A built APK is also the installation APK. A built AAB is not directly installable: its receipt must bind the AAB, a derived install APK, and a separate hashed conversion transcript; installation must use that derived APK. Build, conversion when required, install, device-readback, and launch evidence paths must be distinct.
+
+The built-in `b2c proof` MobAI route produces bounded device-action evidence. It uses `apkanalyzer` to reject an APK whose manifest package or version differs from the requested install, then installs, reads back, launches, and captures on one pinned target. It does not prove source-to-APK build linkage and therefore cannot produce the strict receipt above. Strict Android acceptance requires a named machine-produced build/install receipt adapter that supplies the complete identity chain. The audit worker must consume that receipt and must never reconstruct or hand-author it from MobAI output. When no such adapter is connected, record `android.strict_receipt_adapter_required` as the blocker and keep acceptance incomplete.
+
+Every native receipt timeline starts after candidate production and finishes before review. A build log, a screenshot, or an already-installed app cannot replace a platform receipt.
+
+Each native surface review declares the exact set in `runtimeIds`. Every native producer receipt supplies its own `runtimeId`. This lets ordinary states cite an installed simulator or emulator while VoiceOver or TalkBack evidence cites a physical device in the same surface review. Every native receipt must use the platform receipt's device identity after install and launch. An interaction can cite only captures from its own receipt-verified runtime.
+
+`screenReader: true` requires a `physical-device` runtime. Its interaction must cite that same physical runtime. An iOS simulator cannot prove VoiceOver, and an Android emulator cannot prove TalkBack, by setting a Boolean or changing a label. Unused receipts, unknown runtime IDs, and receipt identities that do not match the current candidate fail acceptance.
+
+Each surface review records:
+
+- The exact frozen rubric path and hash.
+- Capture references with a globally unique `id`, exact receipt path and hash, and accepted producer reference. The producer receipt owns state, locale, artifact path and hash, capture time, candidate and runtime identity, tool, device or browser identity, dimensions, viewport, scale, and settings. Use actual PNG or JPEG runtime captures, not a Design Room render, generated mockup, or marketing composition. Record at least 240 pixels per image side.
+- Interaction references with a globally unique evidence `id`, exact receipt path and hash, and accepted producer reference. The producer receipt owns the authored interaction ID, locale, execution time, candidate and runtime identity, tool, device or browser identity, artifact, capture IDs, result, and observed behavior. Accessibility and reduced-motion states require interaction evidence, not only screenshots.
+- One judgment for every frozen criterion, with `id`, exact `verdict` (`fails`, `meets`, or `exceeds`), a concrete `observation`, and `evidenceIds`. Functionality, accessibility, and motion need interaction evidence.
+
+Ordinary criteria may cite evidence only from their own surface. A `cross_surface_identity` criterion is the deliberate exception: it must cite its own current capture plus globally unique captures from at least one native surface and one landing surface. This makes the comparison executable without letting a strong landing screenshot stand in for a weak native criterion.
+
+Capture and interaction times must follow candidate production and precede review. The review cannot be future-dated. File hashes must still match. No open finding can accompany acceptance. Keep unresolved findings and failed judgments in the repair workflow until the producer has corrected them and a fresh review passes.
+
+## Check And Repair
+
+```bash
+npx tsx checks/validation/business/design/check-design-acceptance.ts --root /path/to/business
+npx tsx tooling/grade-design-surface.ts --root /path/to/business --acceptance-report design/proofs/design-acceptance.json
+```
+
+The explicit acceptance mode exits nonzero for missing or stale evidence, self-review, an invented or old audit identity, missing platform or state coverage, unknown criteria, unmet floors, and unresolved findings. `design_acceptance.report_coverage` identifies audit structure, current-attempt output binding, duplicate indexes, and Markdown-to-JSON binding repairs. `design_acceptance.surface_coverage` identifies omitted required product surfaces or absent current producer evidence. It does not change the grader's ordinary advisory behavior. Use the exported `validateDesignAcceptance(root)` function from the full-business closeout gate.
+
+After a valid product or craft rejection, return observations to the responsible producer through the existing graph. Invalidate affected downstream work, repair the candidate, recapture, and run an independent review. A missing, changed, symlinked, malformed, stale, or misbound audit artifact retries only the audit within its bounded cap because it has not established a product defect. Preserve the full mandate. Ordinary repairs do not require another founder prompt. Protected actions and the founder's shipment decision retain their existing authority boundary.
+
+## Execute The Complete Design Loop
+
+Executed product reviews expose failures that a polished default screenshot cannot reveal. Use this
+sequence with the actual product, through the existing producer and review workflows:
+
+1. Reconcile the authored scope with the implemented surface. A landing with local
+   editing, persistence, and import has real empty and error states. Do not exclude
+   them as if it were static marketing. Freeze the rubric and source inventory.
+2. Run the platform proof route for every selected native platform. For iOS simulator
+   evidence, build the target, install that exact new binary, read the installed bytes
+   back, terminate any running process, and launch the verified install. For Android,
+   bind package name and `versionCode`, install the built APK or an APK derived from the
+   recorded AAB, read the installed package/version from the same emulator or device,
+   and launch it. A derived APK needs its own hash and AAB-to-APK conversion evidence.
+   For VoiceOver or TalkBack, run the matching physical-device route and record model,
+   device ID, API level where applicable, and exact OS version/build. Carry each receipt
+   identity into `nativeRuntimes`.
+   Link each native capture and interaction to the runtime that produced it. A successful
+   build followed by an older installed app does not exercise the candidate. Serve the
+   current web sources and shared assets for the browser review.
+3. Execute the complete task and its recovery path. Inject failed writes at both
+   primary and backup boundaries in an isolated test store. Check visible state,
+   entered fields, undo state, the saved primary, and the previous good backup.
+   A failed primary write must not silently replace the recovery point. Preserve
+   malformed stored bytes; ordinary edits must not overwrite them before an
+   explicit safe recovery. Validate imports before replacement.
+4. Exercise keyboard and assistive-technology paths after state changes. A rerender
+   can remove the focused control even when its replacement looks identical.
+   Check focus after a state change, undo, editor save/cancel, and item removal. Return
+   focus to a surviving meaningful control and confirm the next action works.
+5. Capture the resulting native and browser states and compare them together.
+   Include shared original geometry, fonts, and platform adapters in the candidate
+   fingerprint. Verify the actual rendered font and objects, not just matching
+   token names. Record distinct accessibility settings and observed interactions.
+   When offline is identical to default, record disconnected execution with that
+   default capture and an explicit applicability explanation instead of duplicate
+   pixels. A screenshot or schema check cannot prove a gesture or recovery path.
+6. Have an independent reviewer grade every frozen criterion using those artifacts.
+   Return concrete findings to the responsible producer, repair, rebuild/reinstall,
+   recapture affected work, and review the current candidate again. Keep missing
+   evidence and unresolved findings visible until the acceptance contract is met.
+
+## Runnable examples
+
+The [examples area](https://github.com/Clueless-Creations/b2c-app-builder/tree/main/examples) links runnable sources, real captures,
+and their verification limits. Reproduce the relevant interaction and recovery
+checks for the selected business. Example acceptance never transfers to a new
+candidate.
+
+## Limits
+
+Regular-file checks, confined paths, image parsing, digests, engine-owned producer bindings, receipt identity, runtime links, and chronology prevent common invalid evidence. They cannot establish that a named tool or reviewer is truthful if the trusted execution boundary itself is compromised. Installed-build readback on iOS and installed-package/version readback on Android, physical-device tool transcripts, actual runtime inspection, and the independent session must supply that trust. Do not describe a passing synthetic fixture as an award-quality app or a profitable business.
+
+## Foundation resource invalidation
+
+The existing candidate fingerprint includes local typography resources and their notice files from DESIGN.md foundation, plus version-2 content-asset manifest inputs (including the supported root manifest fallback), kit assets, reference records, lineage, and claim-source records. These dependencies remain bound even if an author omits their directory from implementationPaths. Missing or out-of-workspace dependencies refuse fingerprinting. Parse-only dependency discovery bounds DESIGN metadata to 1 MiB and manifest metadata to 4 MiB before the existing source inventory checks resource bytes. Current bytes, not an unchanged declared digest, determine candidate identity.
+
+The asset gate separately checks declared hashes and brief compatibility. Font metadata and notice presence are not font-loading or license-coverage proof. Review actual rendered text and incorporated-resource output evidence. A focused repair can narrow review work but cannot preserve a stale global acceptance.

package/knowledge/design/design-evidence-stack.md

@@ -0,0 +1,130 @@
+# Design Evidence Stack
+
+Use this reference before you plan, create, revise, audit, or implement a user-facing surface. It routes a design question to the right evidence source. It does not require a tour of every source.
+
+This reference routes evidence gathering. Root `DESIGN.md` is the authored design authority. Record a design decision there in the words the decision needs. The old `Reference Evidence` table remains retired. Complete design acceptance uses the existing reference packs and frozen rubrics through [design-acceptance.md](design-acceptance.md); its strict check validates current capture, interaction, criterion, and scope evidence.
+
+## Core Rule
+
+Classify the decision before you search. Decide which sources fit the decision and why. Say when a source does not apply.
+
+Use at least one relevant source for a new or materially changed user-facing surface. A small token-preserving correction can skip live research.
+
+Use at least two sources for a high-impact or high-risk surface. These surfaces include onboarding, a paywall, the core loop, an AI trust surface, and the first frames of a store listing. Use one source for behavior or structure and one source for craft or validation.
+
+Apply the B2C App Builder Craft Lens to every substantive design decision. It is internal design doctrine. It does not replace audience, behavior, trust, component, or experiment evidence.
+
+For native mobile work, also apply [mobile-flow-craft.md](mobile-flow-craft.md). Research complete comparable journeys when the decision is flow-level. A gallery of disconnected screenshots cannot establish navigation grammar, interruption behavior, or one-way-door semantics.
+
+## B2C App Builder Craft Lens
+
+Before you converge on a solution:
+
+1. Explore at least three meaningfully different concepts. Do not create three cosmetic variants of one idea.
+2. Give objects physical presence. Define their layers, anchors, overlap, separation, tilt, collision behavior, shadows, and settle. Motion must carry convincing weight instead of arbitrary floating.
+3. Make motion explain structure. Hover, press, drag, scroll, transition, and reveal behavior must clarify a relationship, state change, hierarchy, or content boundary.
+4. Recompose mobile. Do not shrink a desktop composition. Choose a mobile hierarchy, focus model, stack, disclosure sequence, gesture model, and safe-area behavior.
+5. Make each medium feel native. An article must support reading. A walkthrough must support guided action. A video must support time, playback, captions, and progress. Do not reduce a real medium to a decorative thumbnail.
+6. Use restraint. Preserve quiet space around important content and interaction. Density, decoration, and simultaneous motion must not flatten the hierarchy.
+7. Make microinteractions precise and responsive. Define immediate feedback, interruption, completion, and subtle spring behavior. Do not use slow fades as the default response to every state change.
+8. Define the quality facets that matter for the surface. Examples include clarity, hierarchy, density, responsiveness, feedback, accessibility, trust, and emotional tone.
+9. Separate structure, interaction, content, visual expression, and motion before you recombine them. Tune one variable at a time and compare it with the prior state.
+10. Remove anything that does not improve the user job or a named quality facet. Compare the result with the current industry standard. State where it meets, exceeds, or deliberately breaks that standard.
+
+## Flow-first research discipline
+
+When the question concerns onboarding, paywalls, authentication, checkout, core loops, permissions, recovery, or another journey:
+
+1. Name the exact question before opening a catalog.
+2. Study the complete relevant flow for each selected product, not a cherry-picked hero screen.
+3. Compare several relevant products when authorized evidence exists. Record the common spine and meaningful divergence.
+4. Treat commercial success or ranking as context, not proof that a particular screen caused the outcome.
+5. Stop at saturation: when another comparable flow no longer changes the working spec, record that and move on.
+6. Preserve observations and stable source IDs in the reference pack. Expiring provider media is not durable evidence unless a permitted inspected capture is retained and hashed.
+
+This method is adapted in part from Appllama's MIT-licensed research skill. It is provider-neutral. Do not harvest a provider library or turn a task-scoped research method into dataset extraction.
+
+## Source Router
+
+| Source                       | Use it for                                                                                                             | Evidence to capture                                                                                                 | Boundary                                                                                                                                                 |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Appllama`                   | Native mobile screen, complete-flow, and component research when the customer has authorized access                    | Question, selected apps/flows, stable source IDs, inspected screens/interactions, convergence, divergence, local decision | Optional provider. Use its upstream `appllama-usage` skill when connected. Do not copy its proprietary corpus, bulk extract it, or treat revenue rank as causal proof. |
+| `60fps.design`               | Motion, transitions, gestures, loading, success, and the magical moment                                                | Two to four relevant examples; the trigger, timing, state change, interruption, and reduced-motion result           | Transfer mechanics only. Do not copy brand, assets, copy, exact layout, or generated code without adapting it to the product and token system.           |
+| `catalogue.projectsbyif.com` | AI decisions, automation, trust, consent, sign-in, permissions, sensitive data, user control, and takeover or recovery | The pattern, its advantages, its limitations, and the reason for adoption or rejection                              | Prefer agency and clear limits. Keep attribution when an adapted artifact requires it.                                                                   |
+| `abtest.design`              | Conversion, onboarding, paywall, checkout, engagement, retention, monetization awareness, and referral hypotheses      | The tested change, audience and context, metric, cited source, counter-metric, and a local validation plan          | Treat a result as a hypothesis seed. It is not transferable causal proof. Do not repeat a number or claim if its primary or cited source is unavailable. |
+| `Design Spells`              | Delight, personality, micro-interactions, empty states, success states, transitions, and small moments of surprise     | The emotional principle, interaction mechanic, and why it fits this audience                                        | Inspiration only. Do not copy a branded asset, exact composition, or exact interaction sequence.                                                         |
+| `UXSnaps`                    | Journey teardown, information hierarchy, onboarding, dashboards, content discovery, and flow critique                  | The observed pattern, claimed rationale, applicability gap, and local evidence that is still needed                 | Treat the breakdown as critique, not authority or causal proof.                                                                                          |
+| `UI Playbook`                | Standard component selection and specification                                                                         | Function, states, focus and keyboard behavior, accessibility semantics, collision behavior, and responsive behavior | Use it as a specification seed. Confirm implementation details in current official platform or WAI-ARIA guidance.                                        |
+
+When the Appllama MCP is connected and authorized for the acting member, load the upstream `appllama-usage` skill rather than duplicating its tool map here. The B2C workflow owns the research question, scope, adoption decision, and evidence contract. Appllama owns its provider-specific search syntax, pagination, credits, media behavior, and catalog semantics. If it is unavailable, choose a declared compatible source lane; do not imply Appllama was inspected.
+
+When the 60fps MCP is connected, use `60fps_search_shots`, `60fps_get_shot`, `60fps_get_motion_breakdown`, and `60fps_get_related_shots`. When bespoke-motion or scroll-linked is selected and that MCP is not connected, hold. Distilled recipes in `motion-craft-benchmarks.md` are not the disconnected procedure for a selected 60fps register and are not equivalent proof.
+
+## Task Routing
+
+| Design task                                                 | Suggested source lanes                                                                          |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Native mobile flow grammar or category convention           | Appllama when authorized; otherwise an approved mobile reference source plus official platform guidance |
+| Motion or gesture                                           | 60fps.design; add UI Playbook when a standard component owns the interaction                    |
+| AI, consent, authentication, permissions, or sensitive data | IF Design Patterns Catalogue; add UI Playbook for the component contract                        |
+| Onboarding, paywall, checkout, retention, or referral       | Appllama when authorized for complete-flow structure, plus abtest.design/UXSnaps for hypotheses; add 60fps.design only when motion affects comprehension or feedback |
+| Core journey or information hierarchy                       | Appllama when authorized or UXSnaps; add UI Playbook for each standard component that needs a full state contract |
+| Brand delight, success, empty state, or a magical moment    | Design Spells plus 60fps.design when the idea moves                                             |
+| Standard control, overlay, input, or notification           | UI Playbook; add IF when the control changes trust, consent, or user agency                     |
+
+The task decides the sources. Taste does not decide the sources.
+
+The B2C App Builder Craft Lens applies across every design decision. It does not count as a behavior or structure source in the two-source rule.
+
+## Evidence Pass
+
+1. Define the user job, surface, decision, and risk.
+2. Decide which sources fit the decision. Say why a source does not apply.
+3. Open only the sources you need. Apply the untrusted-content rules in `knowledge/operations/frontier-agent-operations.md`.
+4. Collect two to four useful observations. For flow research, observations may summarize a complete comparable journey rather than four arbitrary frames. Do not save a screenshot without analysis.
+5. Adopt or reject each principle. Map an adopted principle to an exact state path, semantic token, surface, component, or flow semantic.
+6. Define the test, metric, counter-metric, accessibility result, and fallback that apply.
+7. Mutate state. Update `DESIGN.md`. Validate, version, and render through the Design Room loop.
+8. For implemented native flows, carry the accepted semantics into runtime interaction evidence through `design-acceptance.md`; the reference pack alone is not completion.
+
+For a complete-business mandate, use [consumer-craft-benchmarks.md](consumer-craft-benchmarks.md) to calibrate the relevant native and landing surfaces. Record whether you actually viewed an image, observed an interaction, or read a description. Freeze the per-surface criteria before production. Keep the complete product scope through independent review and repair; a Design Room rendering alone cannot establish native or browser quality.
+
+If an optional inspiration source is unavailable, distilled doctrine or official platform guidance may support a provisional design decision. They do not satisfy mandatory visual or interaction evidence. Resolve a declared, coverage-compatible alternative before locking the affected design. Do not invent source observations or silently substitute providers.
+
+Source use is not acceptance. Audience research, product constraints, accessibility, trust, and local validation can reject a popular pattern.
+
+## Working Check
+
+- You can name the sources you used and the sources you skipped.
+- Substantive design work applies the B2C App Builder Craft Lens.
+- Flow-level work names the research question and studies journeys rather than isolated frames.
+- An adopted principle has an adaptation, a state path or flow semantic, and a validation method.
+- A high-impact or high-risk surface uses two complementary sources.
+- A cited experiment or commercial rank is context/hypothesis evidence unless local evidence proves more.
+- No decision copies source branding, assets, copy, or an exact layout.
+- `DESIGN.md`, structured state, tokens, version, and render agree.
+- Implemented native flows are not called design-complete without the applicable runtime evidence.
+
+## Resolution and compatible alternatives
+
+Freeze source provenance with each reference in the existing per-surface rubric. Rubric schema
+version 2 records `resolution.status`, `observedAt`, `provider` and `sourceId`, plus `validUntil`
+when the evidence has a declared expiry. Use `retained_snapshot` for a permitted inspected capture
+whose bytes are retained and hashed. A signed URL expiring after a valid capture does not erase
+that capture; conversely, an expired catalog response is not a successful observation.
+
+Select alternatives in the order declared for the task's evidence requirement. For a static
+onboarding-layout question, an authorized Appllama or Refero source can be followed by an authorized AppKittie
+screen source when it supplies the required scope. A motion requirement needs an observed
+interaction or recording, such as a suitable authorized 60fps shot. An internal procedure can
+explain how to search, but cannot stand in for either of those observations.
+
+Record an actual alternative with `substitutesFor` and its own resolved evidence. A declared
+alternative does not grant connection or spending authority. Missing access must remain a named
+hold. Do not silently switch an explicitly bound provider. If no permitted alternative covers the
+requirement, leave the design lock unresolved and continue independent work.
+
+`check:design-md` checks source resolution when DESIGN.md declares accepted scope. Final design
+acceptance uses the same check. A provisional design document may exist before references resolve,
+but cannot be presented as a passing accepted direction. Refresh older frozen rubrics explicitly;
+do not invent their observation dates or claim that a source was inspected.

package/knowledge/design/design-room.md

@@ -0,0 +1,83 @@
+# Design Room
+
+Use the Design Room to review an app design. It is one generated, read-only page. It is not a design editor, state store, component library, or revision system.
+
+## Authority
+
+Root `DESIGN.md` is the authored global design system and routing index. It owns the shared experience direction, visual rules, token definitions, component policy, accessibility rules, and implementation constraints.
+
+`studio/seed/business.json` holds structured screen and flow routes. It makes relationships visible to the renderer and validators. It does not replace the authored contract.
+
+Use detailed files only when they improve the work:
+
+```text
+design/flows/<flow-id>.md              detailed journey or flow plan
+design/screens/<screen-id>.md          screen purpose, states, copy, events, and proof
+design/components/<component-id>.md    app-specific component contract
+design/platforms/<stack>.json          selected native adapter map
+```
+
+Link every detailed file from `DESIGN.md`. Do not create a second global design document.
+
+## Product Design Loop
+
+Use the same sequence a consumer product team uses:
+
+1. Define the brief, target user, problem, and success measure.
+2. Map the journey and information architecture.
+3. Plan the critical flows.
+4. Specify screens, states, copy, events, and accessibility behavior.
+5. Reuse a component contract or record a real component gap.
+6. Prototype the key path and edge states.
+7. Critique the work and record the accepted direction.
+8. Implement the selected native adapter.
+9. Verify behavior on the target platform.
+
+Keep the current decision in authored files. Use Git commits, branches, tags, and diffs for revision history.
+
+## Component Routing
+
+Reusable contracts live under `<skill-root>/ui-library/components/`. `<skill-root>/ui-library/component-index.json` routes tools to them. A contract defines purpose, states, requirements, accessibility behavior, token references, and maturity. It does not prescribe SwiftUI, React Native, Flutter, or another framework.
+
+Reference adapter manifests live under `<skill-root>/ui-library/adapters/`. An app can refine a contract in `design/components/<component-id>.md`. Record the selected native mapping in `design/platforms/<stack>.json`. The stack is a free-form slug. Examples include `swiftui`, `expo`, `react-native`, and `flutter`.
+
+The selected adapter must point to real implementation code. Verified or stable claims also need proof. If no adapter exists, report the component as not implemented on that stack. Do not create empty adapter entries to imply parity.
+
+## Review Page
+
+Run the renderer after an authored design or structured route changes:
+
+```bash
+npm run validate:design-state -- --root /path/to/app
+npm run check:design-md -- --root /path/to/app
+npm run render:design-room -- --root /path/to/app
+npm run check:design-room -- --root /path/to/app
+```
+
+The generated page is `design/design-room.html`. It presents:
+
+- the product brief and visual direction
+- flow and screen routes
+- screen states and proof links
+- component maturity and selected adapter coverage
+- token samples and accessibility constraints
+- open decisions, gaps, and review status
+
+The page must identify the source revision or content hash. It must not contain editable state or its own version log.
+
+## Scrollytelling
+
+For a scroll-led landing or in-app story, load [`editorial-scrollytelling.md`](./editorial-scrollytelling.md). Add the story order, stable scene IDs, sources, responsive states, reduced-motion fallback, and viewport proof to the relevant screen plan. The Design Room shows the plan and proof; it does not become the runtime.
+
+## Review Gate
+
+A design is ready for review when:
+
+- `DESIGN.md` states the current direction and links every detailed plan.
+- Structured flow and screen routes match those links.
+- Each critical screen covers default, loading, empty, error, offline, and permission states when applicable.
+- Each component names its maturity and real adapter coverage.
+- The selected stack has no implied implementation.
+- Accessibility, reduced motion, copy, events, and proof paths are explicit.
+- `design/design-room.html` is fresh and read-only.
+- The complete design change is recorded in Git.