b2c-app-builder 0.221.39

package/catalog/generated/firstparty/knowledge/design/consumer-craft-benchmarks.md

@@ -0,0 +1,72 @@
+# Consumer Craft Benchmarks
+
+Use this reference when a complete consumer business needs a visual standard for its mobile app, landing page, and supporting surfaces. Choose the relevant principles before producing the candidate. The examples establish a bar for judgment. They do not prescribe one style or prove commercial success.
+
+## What Was Inspected
+
+Research date: 2026-09-12. The research inspected primary-source descriptions and public product imagery for the nine examples. It viewed grug screenshots in an Apple developer interview, official Airbnb release imagery, Duolingo's art-direction examples, and official screenshots or product images for Blippo+, Metaballs, Is This Seat Taken?, Hearing Buddy, and Structured. Quabble was added from its founder nomination and current first-party product/store descriptions; image-dependent runtime judgments remain unverified because no installed-app walkthrough was performed.
+
+These were reference images, not installed-app tests. They do not establish gesture timing, haptics, accessibility behavior, frame rate, purchase reliability, or current runtime quality. Airbnb imagery represents its 2025 release. Duolingo imagery illustrates its earlier art-direction system, not its current full app. Refresh the relevant flow before using a benchmark to judge an implementation. Do not label an image observation as an interaction observation.
+
+Apple's [2026 awards page](https://developer.apple.com/design/awards/) identifies grug as Ocho's iOS app, Blippo+ as Panic's macOS experience, Metaballs as Apposite's sculpting experience, and Is This Seat Taken? as Poti Poti's puzzle game. Hearing Buddy is Lilly Seay's captioning app; Structured is unorderly's planner. These examples span different platforms and jobs. They are not interchangeable mobile templates.
+
+## Reference Principles
+
+| Reference           | Observed or source-described craft                                                                                                                                                                                                                               | Transfer to the business                                                                                                                                                                           | Do not infer or copy                                                                                                      |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Airbnb              | The inspected app image gives search clear priority, lets photography lead the content, and reserves dimensional detail for category objects. The design-system account defines components through function, required content, personality, and native behavior. | Specify recognizable product objects and reusable compositions; keep the interface coherent across discovery, decision, and action. Spend visual detail where it explains an important choice.     | Its marketplace taxonomy, specific icons, photography, or assumption that every product needs cards.                      |
+| Duolingo            | The art-direction examples use a consistent shape language and expressive characters inside learning tasks. Its product principles describe repeated design cycles and long-term user value.                                                                     | Create an asset language that belongs to the product. Connect feedback, writing, illustration, and learning or progress to one user action. Keep repairing until the agreed criteria hold.         | A mascot, streak, notification strategy, or animation automatically improves every app.                                   |
+| grug                | Sparse colored pages combine hand-drawn text, icons, and illustrations. Its creators describe building a stroke-rendering engine that also controls layout, animation, and interaction states.                                                                   | Treat the distinctive mechanism as an engineering requirement. Carry the chosen visual language into controls and edge states, not just the hero. A small product can be complete and exceptional. | Its typeface, voice, drawings, or a requirement to add accounts and cloud infrastructure when the job does not need them. |
+| Blippo+             | The inspected program guide maintains its television world through typography, channels, information layout, and screen texture. Apple describes synchronized broadcasting and carefully built world details.                                                    | Align content production, navigation, motion, and interaction with the medium. Make deliberate unusual choices coherent throughout the experience.                                                 | CRT effects or dense television controls belong in an unrelated utility app.                                              |
+| Metaballs           | The product image puts the sculpted object and manipulation space ahead of controls. The developer describes shape fusion, materials, direct manipulation, and usable exports.                                                                                   | Make the signature visual behavior part of the core job and useful output. Prototype technical feasibility before promising a physical interaction.                                                | Spatial hand gestures transfer unchanged to a phone, or a still image proves responsive manipulation.                     |
+| Is This Seat Taken? | The inspected game image uses consistent outlines, restrained colors, expressive faces, and readable in-world feedback. The team describes removing mechanics after playtests and retaining details that serve the puzzle.                                       | Use visual expression to explain state and consequence. Remove distracting systems while completing the user journey. Give secondary interactions the same care as the main action.                | The game's palette, characters, or decorative density belongs in every business.                                          |
+| Hearing Buddy       | The inspected caption screen makes readable conversation text central, with visible listening, summary, and settings controls. Its landing page describes and demonstrates the caption experience.                                                               | Build around the audience's actual access need. Use personality to support the task. Show credible product behavior in the landing page's first-value story.                                       | A marketing health claim is independently verified, or screenshots prove accessibility and speech accuracy.               |
+| Structured          | The inspected phone image represents time through a continuous timeline, duration, icons, text, and completion controls. Apple describes its emphasis on readable planning and downtime.                                                                         | Turn the product's important relationship into an understandable visual object. Combine redundant cues, calm hierarchy, and one clear next action.                                                 | A timeline is suitable for every app or color alone communicates state.                                                   |
+| Quabble            | The founder-selected reference describes a duck companion, a virtual park, daily routines, named activity objects such as Gratitude Jar, Worry Box, and Proud Dandelion, and a 15-day First Bloom journey. The official site and store listings provide product imagery and descriptions; no installed-app interaction or visual-runtime claim is made here. | Give an abstract daily practice a tangible object and a clear return rhythm. Let identity, progress, and the core task share one coherent world, while keeping the first action calm and legible. | A mascot, wellness park, gamified streak, therapeutic claim, or Quabble asset belongs in every product. A source description proves neither retention nor clinical efficacy. |
+
+Primary sources: [Airbnb design system](https://medium.com/airbnb-design/building-a-visual-language-behind-the-scenes-of-our-airbnb-design-system-224748775e4e), [Airbnb release imagery](https://news.airbnb.com/product-releases/airbnb-2025-summer-release), [Duolingo art direction](https://blog.duolingo.com/shape-language-duolingos-art-style/), [Duolingo product principles](https://blog.duolingo.com/product-principles/), [grug developer interview](https://developer.apple.com/news/?id=ux44ymcr), [Blippo+](https://blippo.plus/), [Metaballs](https://www.apposite.ai/metaballs.html), [Is This Seat Taken? developer interview](https://developer.apple.com/news/?id=z12xq8fa), [Hearing Buddy](https://hearingbuddyapp.com/), [Structured](https://structured.app/), [Quabble official site](https://quabble.app/), [Quabble App Store listing](https://apps.apple.com/us/app/quabble-daily-mental-health/id6445948886), [Quabble Google Play listing](https://play.google.com/store/apps/details?id=com.museLIVE.quabbleapp).
+
+## Turn Inspiration Into Acceptance
+
+Use the existing reference-pack librarian and frozen rubrics under `design/reference-packs/` and `design/reviews/rubrics/`. Keep the product's authored scope in `product.yaml` and design authority in `DESIGN.md`.
+
+For each important surface:
+
+1. Name the user job, product object, state transition, and intended feeling. Select the benchmark that informs that decision.
+2. Record the inspected artifact, source URL, date, observation kind, and limitations. Include visual evidence and complementary behavior or official platform guidance.
+3. State the principle to adopt, how it changes this product, and the reference-specific treatment to reject.
+4. Freeze criteria before the candidate is produced. Compare coherence, originality, craft, functionality, accessibility, motion, and identity across surfaces. Use `meets` or `exceeds` as the required floor for each criterion. Explain exactly what the words mean for the surface.
+5. Implement the distinctive assets and interaction mechanics. Shared component contracts do not imply an implemented native adapter.
+6. Review actual native and browser captures and observed interactions. Use [Design Acceptance Evidence](design-acceptance.md) to bind the review to the current implementation and rubric.
+7. Repair each failed criterion, recapture, and obtain a new independent review. A strong average cannot conceal a failed criterion or missing native screen.
+
+## Landing And Mobile Are Separate Deliverables
+
+The landing page must communicate the product promise, show credible product value, and offer the next action the business supports today. A store download, working checkout, or useful web-to-app path may be appropriate. A waitlist is not a substitute for a working acquisition path when the mandate requires a business ready to sell.
+
+Compose the landing separately for a phone and desktop. Test keyboard use, no JavaScript, reduced motion, and the actual conversion path. Use the same nouns, objects, assets, and visual rules as the mobile app without forcing identical layouts.
+
+The native app must make first value and repeat use work on every selected platform. Verify loading, empty, error, offline, permission, text-size, screen-reader, and reduced-motion behavior where applicable. Verify purchases, restoration, entitlement loss, and recovery when they are part of the accepted business. The backend and provider evidence remain owned by their engineering and revenue contracts.
+
+## Apply references to implementation
+
+Use original shared assets and a deliberate visual vocabulary across surfaces.
+Inspect actual renders to detect missing font registration, different objects,
+and generic fallbacks. Shared filenames or copied token values do not establish
+visual consistency.
+
+Exercise data recovery and focus after every state-changing interaction. Preserve
+the last good recovery point on failed writes. Surface malformed stored data
+without silently replacing it. Test input and import errors in each surface that
+supports them. Do not claim a native-only feature on a browser surface that lacks it.
+
+Use the [execution loop](design-acceptance.md#execute-the-complete-design-loop).
+The [examples area](https://github.com/Clueless-Creations/b2c-app-builder/tree/main/examples) supplies scoped implementation
+references and captures. Reproduce the relevant checks on the current candidate;
+then have an independent reviewer judge its interaction and recovery states.
+
+## One Mandate, Complete Work
+
+One shot means the builder owns the internal research, production, critique, repair, and verification loops under one founder mandate. It does not mean one model response, one unreviewed design attempt, or an excuse to ship a generic first draft. The design bar applies to the full accepted product and its supporting business surfaces.
+
+Keep scope purposeful. Remove an unnecessary feature through the product decision process; do not drop a required journey to make a test pass. A schema-valid review establishes evidence integrity. Independent inspection establishes the recorded design judgment. Provider readback establishes provider behavior. Real transactions establish revenue. None substitutes for another.

package/catalog/generated/firstparty/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/catalog/generated/firstparty/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/catalog/generated/firstparty/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.