b2c-app-builder 0.221.39

package/examples/workspace/business/product/ONBOARDING.md

@@ -0,0 +1,306 @@
+# Onboarding System
+
+Status: `not_started`
+
+Canonical execution record for `knowledge/experience/onboarding-conversion.md`. Record product-specific evidence, decisions, design references, implementation work, and checks here.
+
+## Execution Mode
+
+Record `greenfield`, `replacement`, `audit_only`, or founder-scoped `incremental`. Name the product surfaces, freshness date, owner, durable user value, and whether replacement requires hard cutover and only the target runtime.
+
+## Graph Run
+
+| Node     | Status      | Owner                         | Result or next action                             |
+| -------- | ----------- | ----------------------------- | ------------------------------------------------- |
+| `ONB-00` | not_started | Orchestrator                  | Record scope and mode                             |
+| `ONB-01` | not_started | Engineering and product       | Trace the current implementation                  |
+| `ONB-02` | not_started | Research                      | Lock the evidence plan                            |
+| `ONB-03` | not_started | Research and product          | Research current guidance                         |
+| `ONB-04` | not_started | Research and customer success | Code negative reviews and a positive control      |
+| `ONB-05` | not_started | Research and design           | Build the authorized Onbo Hub atlas               |
+| `ONB-06` | not_started | Product                       | Audit internal guidance                           |
+| `ONB-07` | not_started | Money, engineering, and trust | Refresh provider and policy facts                 |
+| `ONB-08` | not_started | Design                        | Research applicable motion                            |
+| `ONB-09` | not_started | Orchestrator                  | Join evidence and dispositions                    |
+| `ONB-10` | not_started | Product and data              | Define first value and activation                 |
+| `ONB-11` | not_started | Product and design            | Audit effort and questions                        |
+| `ONB-12` | not_started | Engineering and money         | Define state and identity                         |
+| `ONB-13` | not_started | Data and product              | Define analytics and experiments                  |
+| `ONB-14` | not_started | Trust and customer success    | Define reviews, permissions, lifecycle, and trust |
+| `ONB-15` | not_started | Orchestrator                  | Select the target architecture                    |
+| `ONB-16` | not_started | Product                       | Define the journey graph                          |
+| `ONB-17` | not_started | Product, words, and money     | Specify screens, controls, and paywall            |
+| `ONB-18` | not_started | Design                        | Produce actual design and prototype               |
+| `ONB-19` | not_started | Engineering and trust         | Define build, reliability, and cutover            |
+| `ONB-20` | not_started | Cross-functional reviewers    | Run the pre-mortem and QA                         |
+| `ONB-21` | not_started | Orchestrator and engineering  | Run Compound Engineering planning                 |
+| `ONB-22` | not_started | Engineering and orchestrator  | Execute, delete, test, and verify                 |
+
+## Source Map And Current-State Trace
+
+Record each surface as `owner -> source of truth -> persisted state -> API or event contract -> consumers -> failure behavior`. Trace routes, state, identity, first value, permissions, paywalls, purchase, Restore, funnels, deep links, analytics, experiments, review logic, lifecycle, errors, tests, dashboards, configuration, and removal items.
+
+## Evidence Ledger
+
+| ID        | Claim or question            | Source and date            | Class                                                                           | Finding            | Confidence           | Product implication |
+| --------- | ---------------------------- | -------------------------- | ------------------------------------------------------------------------------- | ------------------ | -------------------- | ------------------- |
+| `EVD-001` | Record the decision question | Record the original source | Rule, evidence, benchmark, observation, heuristic, hypothesis, or open question | Record the finding | High, medium, or low | Record the use      |
+
+## Competitor Review Matrix
+
+| ID        | Product, platform, and sample     | Negative theme               | Positive control        | Root-cause class                                                                                                      | Disposition                               | Test   |
+| --------- | --------------------------------- | ---------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------ |
+| `REV-001` | Record dates, versions, and count | Record the paraphrased theme | Record what users value | Onboarding, expectation, monetization, identity, lifecycle, core product, support, platform, or insufficient evidence | Address, partial, reject, or product work | Record |
+
+Report sample frequency only within the sample. Do not onboarding-wash product defects.
+
+## Onbo Hub Pattern Atlas
+
+Use authorized Onbo Hub access only. Do not scrape, bypass access controls, reuse credentials, or infer locked screens. Revenue estimates remain estimates.
+
+| ID         | App, access, and date | Screens and effort | First-value class                                           | Paywall | Review tension                        | Decision                            |
+| ---------- | --------------------- | ------------------ | ----------------------------------------------------------- | ------- | ------------------------------------- | ----------------------------------- |
+| `ONBO-001` | Record                | Record             | Promise, demo, simulated, computed, actionable, or withheld | Record  | Record negative and positive evidence | Adopt, test, reject, or investigate |
+
+## Internal Guidance Audit
+
+| ID          | Source and section                                | Recommendation  | Evidence class   | Verdict                                                    | Required change |
+| ----------- | ------------------------------------------------- | --------------- | ---------------- | ---------------------------------------------------------- | --------------- |
+| `GUIDE-001` | Record the B2C App Builder or internal B2C source | Record the rule | Record the basis | Pass, partial, fail, outdated, conflict, or not applicable | Record          |
+
+## Seven-Principle Activation Audit
+
+Audit the seven-principle heuristic: define Activation, show value before disproportionate effort, ask only useful questions, keep one dominant action per screen, use purposeful motion, show personalization proof, and end with meaningful value in a populated normal product experience. Record pass, partial, or fail with evidence, not a fake numerical score.
+
+## Provider Capability Matrix
+
+Refresh the complete relevant RevenueCat and billing surface, including SDKs, products, packages, offerings, placements, entitlements, identity, paywalls, targeting, experiments, RevenueCat Funnels, RevenueCat Web, Purchases.js, purchase links and buttons, billing engines, Redemption Links, Customer Center, webhooks, analytics, lifecycle, refunds, grace, Purchase pending, and Restore.
+
+| Capability | Support, plan, economics, and policy | Current equivalent | Decision and authority                        | Replacement or deletion |
+| ---------- | ------------------------------------ | ------------------ | --------------------------------------------- | ----------------------- |
+| Record     | Record                               | Record             | Adopt, integrate, build, omit, or investigate | Record                  |
+
+## Platform Policy Matrix
+
+| Platform and region | Technically possible | Policy permitted        | Enrollment, disclosure, fees, and reporting | Recommended behavior | Revalidation date |
+| ------------------- | -------------------- | ----------------------- | ------------------------------------------- | -------------------- | ----------------- |
+| Record              | Yes or no            | Yes, no, or conditional | Record                                      | Record               | Record            |
+
+## Motion Research
+
+Resolve applicability from studio/seed/business.json `interaction`, implemented scroll-linked hooks on an active landing, and `growth/landing/surface-contract.json` when present. Empty inventory means 60fps is not selected. A listed surface without `interaction` stays unresolved. Use the 60fps MCP with `search_shots`, `get_shot`, `get_motion_breakdown`, and `get_related_shots` only when bespoke-motion or scroll-linked is selected and that MCP is recorded ready; a fallback is not equivalent. Translate principles into original product behavior and the target framework.
+
+Do not add a Motion Research row or invent a shot ID until a surface selects bespoke-motion or scroll-linked.
+
+| ID  | Target and problem                                              | Reference              | Adopted principle | Implementation, haptic, and interruption | Reduced motion |
+| --- | --------------------------------------------------------------- | ---------------------- | ----------------- | ---------------------------------------- | -------------- |
+| —   | Leave empty until scroll-linked or bespoke-motion is selected   | Do not invent a shot ID | —                 | —                                        | —              |
+
+## Evidence Decision And Complaint Traceability
+
+| Decision ID | Evidence and complaint IDs | Decision                                   | Screen, control, architecture, or product work | Analytics | Test   | Remaining risk |
+| ----------- | -------------------------- | ------------------------------------------ | ---------------------------------------------- | --------- | ------ | -------------- |
+| `DEC-001`   | Record                     | Adopt, adapt, test, reject, or investigate | Record                                         | Record    | Record | Record         |
+
+## First Value And Activation
+
+Define First value rendered, First value engaged, Activation, habit signal, retention, monetization, review eligibility, and onboarding completion separately. First value must be real, actionable, persistent, recoverable, and visible in the populated normal product experience.
+
+| Milestone            | Semantic definition                 | Authoritative source | Event or derived metric      | Window and evidence |
+| -------------------- | ----------------------------------- | -------------------- | ---------------------------- | ------------------- |
+| First value rendered | Record the real personalized result | Record               | Record                       | Record              |
+| First value engaged  | Record the meaningful user action   | Record               | Record                       | Record              |
+| Activation           | Record the retention hypothesis     | Record               | Record the derived condition | Record              |
+
+## Effort-Before-Value Ledger
+
+| Step            | Required  | Effort class and quantity                                                  | Value already shown | Value returned | Keep, defer, infer, or delete |
+| --------------- | --------- | -------------------------------------------------------------------------- | ------------------- | -------------- | ----------------------------- |
+| Record the step | Yes or no | Passive, low, moderate, high, sensitive, permission, account, or financial | Record              | Record         | Record                        |
+
+## Question Usefulness Matrix
+
+| Question ID | Required | Downstream logic changed                             | Visible personalization proof         | Privacy and skip behavior | Decision                      |
+| ----------- | -------- | ---------------------------------------------------- | ------------------------------------- | ------------------------- | ----------------------------- |
+| `Q-001`     | Record   | Record the branch, recommendation, copy, or behavior | Record where the user sees the effect | Record                    | Keep, defer, infer, or delete |
+
+## Canonical State Model
+
+Keep identity, onboarding journey, profile completeness, activation, entitlement, Experiment assignment and exposure, review eligibility, permission and consent, and lifecycle state separate.
+
+| Machine  | State or transition | Trigger and preconditions | Authoritative owner | Persistence and event | Idempotency, retry, and recovery |
+| -------- | ------------------- | ------------------------- | ------------------- | --------------------- | -------------------------------- |
+| Identity | Record              | Record                    | Record              | Record                | Record                           |
+
+## Architecture Decision
+
+Compare native-first, hosted-funnel-first, hybrid, web-first, and any evidence-backed alternative. Select one target architecture.
+
+| Model            | First value | Conversion and retention | Identity and analytics | Policy and economics | Operations | Decision         |
+| ---------------- | ----------- | ------------------------ | ---------------------- | -------------------- | ---------- | ---------------- |
+| Record the model | Record      | Record                   | Record                 | Record               | Record     | Select or reject |
+
+## Journey Graph
+
+| Step ID        | Entry condition and job | Owner and renderer | Input and transition | Event                                | Back, skip, close, and resume | Failure and next step |
+| -------------- | ----------------------- | ------------------ | -------------------- | ------------------------------------ | ----------------------------- | --------------------- |
+| `ONB-STEP-001` | Record                  | Record             | Record               | Record the canonical event or `none` | Record                        | Record                |
+
+Mark acquisition promise, first effort, first value, engagement, account, paywall, purchase, activation, review eligibility, normal-product entry, and the interruption budget.
+
+## Commitment Funnel
+
+First-session order is welcome, then quiz or goals, then micro-commitment, then personalized insight, then hard paywall when `product.yaml` records `feature.commitment-funnel` as required. This reference workspace records that feature as required. If the feature is excluded or a non-goal, omit this table rather than inventing a quiz or hard paywall. If the instance is absent, hold. See `knowledge/experience/commitment-funnel.md`.
+
+| Step                 | Required | Skip path          | Ethics veto                                 | Event  |
+| -------------------- | -------- | ------------------ | ------------------------------------------- | ------ |
+| welcome              | Yes      | Record             | Fake scarcity veto                          | Record |
+| quiz or goals        | Yes      | Record             | Useless questions veto                      | Record |
+| micro-commitment     | Yes      | skip path required | Pledge or hold-to-confirm without skip path | Record |
+| personalized insight | Yes      | Record             | Progress animation over no computation      | Record |
+| hard paywall         | Yes      | Restore visible    | Fake download counts veto                   | Record |
+
+## Funnel Quality Metrics
+
+Trial starts alone cannot mark onboarding done. Record quality companions and route tests through RevenueCat Experiments.
+
+| Metric              | Definition | Current value | Quality bar | Experiment |
+| ------------------- | ---------- | ------------- | ----------- | ---------- |
+| onboarding complete | Record     | Record        | Record      | Record     |
+| install-to-trial    | Record     | Record        | Record      | Record     |
+| trial-to-paid       | Record     | Record        | Record      | Record     |
+| per-step drop-off   | Record     | Record        | Record      | Record     |
+| refund rate         | Record     | Record        | Record      | Record     |
+
+## Screen Inventory
+
+Every screen has one dominant action and a stable semantic ID.
+
+| Screen ID     | Purpose and evidence                 | Copy (from `product/copy/COPY_DECK.md`)                                                                                                     | Actions              | States                                                                                                                                                                | Motion         | Analytics                      | Accessibility and localization                                                | Design checks                   |
+| ------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------ | ----------------------------------------------------------------------------- | ------------------------------- |
+| `ONB-SCR-001` | Record the user job and decision IDs | `onboarding.promise.*`, `onboarding.attribution.*`, `onboarding.personalize.*`, `onboarding.plan.*`, `onboarding.push.prime.*`, `paywall.*` | Record the hierarchy | Initial, selected, disabled, loading, success, empty, error, offline, permission, subscriber, purchase, restore, returning, large text, screen reader, reduced motion | Record `MOT-*` | Record exposure and milestones | Record focus, labels, announcements, contrast, touch, RTL, and text expansion | Record the inspectable artifact |
+
+Actual high-fidelity design and an interactive prototype are required. Contract HTML is not visual design.
+
+## Control And Action Contract
+
+| Control ID    | Screen and label                        | Enable and validation | State mutation | API or provider action             | Event or `none` | Navigation and recovery                                               | Test   |
+| ------------- | --------------------------------------- | --------------------- | -------------- | ---------------------------------- | --------------- | --------------------------------------------------------------------- | ------ |
+| `ONB-CTL-001` | Record visible and accessibility labels | Record                | Record         | Record the exact idempotent action | Record          | Record loading, repeated tap, error, retry, offline, and interruption | Record |
+
+## Paywall Contract
+
+Cover trial eligible and ineligible, packages, promotions, existing subscriber, unavailable offering, offline, Purchase pending, canceled, failed, success, delayed entitlement, Restore, web handoff, and regional variants.
+
+| State  | Exact value, price, renewal, cancellation, terms, and privacy | Offering, package, product, and entitlement | CTA, close, and Restore | Provider action | Analytics authority                        | Recovery and validation |
+| ------ | ------------------------------------------------------------- | ------------------------------------------- | ----------------------- | --------------- | ------------------------------------------ | ----------------------- |
+| Record | Record                                                        | Record IDs                                  | Record                  | Record          | Provider-confirmed revenue and entitlement | Record                  |
+
+## Paywall Goal Headline
+
+The quiz writes `paywall_headline_key` when `product.yaml` records `feature.paywall-goal-headline` as required and the declared present-paywall owner can bind it. This reference workspace records that feature as excluded. Interpolate only that selected key into the paywall headline. A skip uses the fallback template. Keep templates in RevenueCat offering metadata and bind them at present time with `customVariables`. Do not invent a goal or outcome. If the feature is excluded or a non-goal, omit this bind. If the instance is absent, or no parseable `b2c.yaml` declares the present-paywall owner, hold. Packet prose cannot make that decision. See `knowledge/experience/paywall-goal-headline.md`.
+
+| Goal key       | User-facing prompt | Headline template           | Fallback when skipped       |
+| -------------- | ------------------ | --------------------------- | --------------------------- |
+| `lose_weight`  | Record             | Start losing weight today   | Record the generic fallback |
+| `build_muscle` | Record             | Start building muscle today | Record the generic fallback |
+| `skipped`      | Skip or blank      | Record the generic fallback | Yes                         |
+
+Runtime bind: Offering metadata holds the template map. `customVariables` receive `paywall_headline_key`. Sync subscriber attributes when Experiments targeting needs the key.
+
+## Review Request Contract
+
+Eligibility may be earned after value and engagement. The native request happens outside first-run onboarding. Request it at a later natural success in normal product use. Native platform API only. Forbidden: Sentiment gate, Custom rating UI, five-star ask, incentives, or selective happy-user routing. Use a remote kill switch and suppress during errors, support, purchase, Restore, cancellation, cooldown, or another interruption.
+
+Observable events: `review_eligibility_earned`, `review_request_suppressed`, `review_request_attempted`, and `review_request_returned`. Do not claim display, submission, or rating without a reliable permitted signal.
+
+## Analytics Contract
+
+Define a machine-readable schema and typed clients. Every event includes `event_id`, version, time, source, platform, journey, identity, session, correlation, acquisition, consent, privacy, and Deduplication semantics as appropriate.
+
+| Event                      | Definition and trigger           | Authoritative emitter                                                             | Properties | Identity stitching | Deduplication and retry | Privacy and QA |
+| -------------------------- | -------------------------------- | --------------------------------------------------------------------------------- | ---------- | ------------------ | ----------------------- | -------------- |
+| Record the canonical event | Record the observable occurrence | Client interaction, backend-confirmed product, or provider-confirmed monetization | Record     | Record             | Record                  | Record         |
+
+Analytics failure does not block first value.
+
+### Expected Event Sequences
+
+Record and test sequences for happy path, skip, permission denial, retry, paywall dismissal, trial, purchase, Purchase pending, Restore, existing subscriber, web redemption, returning user, and interrupted resume. Test order, Authoritative emitter, optional events, duplicates, identity stitching, Experiment exposure, and correlation.
+
+## Experimentation
+
+| Experiment | Hypothesis                   | Unit and eligibility | Assignment owner  | Exposure                   | Primary metric and guardrails                                             | Stop and cleanup                |
+| ---------- | ---------------------------- | -------------------- | ----------------- | -------------------------- | ------------------------------------------------------------------------- | ------------------------------- |
+| Record     | Record the causal hypothesis | Record               | Record one system | Emit only when experienced | Include retention, refund, support, crash, cost, accessibility, and trust | Record and delete configuration |
+
+## Permissions And Lifecycle
+
+Request protected access only after a user action with visible benefit. Record denial, limited access, retry, settings, privacy, and fallback. Use one orchestration strategy for onboarding recovery, progressive profiling, trial and post-purchase activation, habit b2c, billing recovery, dormancy, churn, win-back, and resubscription.
+
+## Failure And Recovery
+
+| Failure                                                                                                                                 | User truth and work safety | State authority | Idempotent retry | Support and observability | Test   |
+| --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | --------------- | ---------------- | ------------------------- | ------ |
+| Purchase pending, Restore, entitlement delay, network, generation, analytics, remote config, deep link, identity, or unsupported client | Record                     | Record          | Record           | Record                    | Record |
+
+Successful work is not repeated because a later step failed.
+
+## Accessibility And Localization
+
+Record VoiceOver, TalkBack, dynamic type, focus, keyboard, contrast, reduced motion, touch targets, announcements, color-independent state, RTL, text expansion, pluralization, inclusive language and imagery, localized pricing, and platform differences.
+
+## Privacy And Security
+
+Record purpose, necessity, storage, encryption, access, processors, analytics treatment, retention, deletion, export, consent, age obligations, image metadata, upload security, webhooks, deep links, redemption, identity linking, replay protection, AI-provider data use, and threat controls.
+
+## Performance And Observability
+
+Set P50, P95, and failure budgets for startup, first value, provider initialization, paywall, checkout, entitlement, analytics overhead, and handoff. Record logs, metrics, traces, dashboards, alerts, synthetic journeys, runbooks, observability ownership, and cost.
+
+## Prototype And Design Proof
+
+| Artifact                    | Path or stable link             | Journey and states               | Platforms and viewports                      | Accessibility and reduced motion | QA           |
+| --------------------------- | ------------------------------- | -------------------------------- | -------------------------------------------- | -------------------------------- | ------------ |
+| Actual high-fidelity design | Record the inspectable artifact | Record coverage                  | Record selected shipping platforms; small viewport and large text | Record                           | Pass or gaps |
+| Interactive prototype       | Record the inspectable artifact | Happy path and critical branches | Record                                       | Record                           | Pass or gaps |
+
+## Synthetic One-Star Pre-Mortem
+
+| Synthetic scenario                                                                                                                                            | Root cause | Likelihood and severity | Mitigation and change | Test   | Remaining risk |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------- | --------------------- | ------ | -------------- |
+| Record a privacy, permission, poor result, slow network, trial, subscriber, Restore, web purchase, accessibility, identity, or subscription-aversion scenario | Record     | Record                  | Record                | Record | Record         |
+
+## Compound Engineering Implementation Plan
+
+At `ONB-21`, use `ce-plan` when available. At `ONB-22`, use implementation, review, and test workflows.
+
+| Task ID        | Outcome and paths                            | Dependencies and contracts | Analytics and provider work | Tests  | Removal tasks | Acceptance |
+| -------------- | -------------------------------------------- | -------------------------- | --------------------------- | ------ | ------------- | ---------- |
+| `ONB-TASK-001` | Record the executable result and exact paths | Record                     | Record                      | Record | Record        | Record     |
+
+## Target Runtime Cutover
+
+Replacement mode uses hard cutover. Preserve durable user value through an isolated one-time transformation, rehearse and audit it, then delete the tooling.
+
+### Removal Inventory
+
+| Removal ID   | Code, data, config, provider, analytics, test, doc, dashboard, alert, or secret | Disposition                                                                        | Delete task | Verification                    |
+| ------------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------- | ------------------------------- |
+| `REMOVE-001` | Record the item                                                                 | Preserve durable data, transform once, recompute, archive legal history, or delete | Record      | Record the search or validation |
+
+Enforce a minimum supported client when old contracts are incompatible. Do not keep the old runtime as a rollback path. Roll forward on defects. Delete routes, adapters, shims, dual reads, dual writes, old state, events, flags, jobs, provider configuration, dashboards, tests, docs, secrets, and transformation tooling.
+
+## Verification
+
+- [ ] `ONB-00` through `ONB-22` are done, or the lane is not claimed done
+- [ ] Evidence, reviews, authorized Onbo Hub, internal guidance, provider, policy, seven-principle, and motion research are joined
+- [ ] First value rendered, First value engaged, Activation, retention, monetization, review eligibility, and completion are distinct
+- [ ] Effort, questions, permissions, personalization proof, and the interruption budget are justified
+- [ ] Canonical state, identity, entitlement, analytics, Experiment, review, permission, and lifecycle owners are explicit
+- [ ] Every journey, screen, control, paywall, error, and recovery state is specified and designed
+- [ ] Actual high-fidelity design, interactive prototype, accessibility, localization, privacy, security, performance, and observability checks exist
+- [ ] Typed analytics, Authoritative emitter rules, identity stitching, Deduplication, provider-confirmed outcomes, and Expected Event Sequences pass
+- [ ] Compound Engineering planning, implementation, review, tests, and provider validation pass
+- [ ] Hard cutover preserves durable user value and leaves only the target runtime and removes transformation tooling
+- [ ] `checks/validation/business/experience/check-onboarding-graph.ts` passes

package/examples/workspace/business/product/README.md

@@ -0,0 +1,8 @@
+# Product
+
+Owns the product contract in root `PRODUCT.md`, plus detailed onboarding, copy,
+behavioral experience, and customer-facing acceptance evidence.
+
+`PRODUCT.md` is the authored product authority and index. `ONBOARDING.md` holds
+the detailed journey and interaction contract. Research, design, runtime state,
+and provider records remain in their own source files.

package/examples/workspace/business/product/copy/COPY_BRIEF.md

@@ -0,0 +1,64 @@
+# Copy Brief
+
+Status: template — fill every section from this product's evidence, then set the status to `authored` with the date.
+
+The brief is the product's message in one place: the promise, the proof, and the voice. Every conversion surface (landing, store listing, paywall, lifecycle email, onboarding value-reveal) writes from here so the user meets one product, not five. The full string surface lives in `product/copy/COPY_DECK.md`, which inherits this voice. Craft rules live in `knowledge/words/conversion-copy.md`.
+
+## Value proposition
+
+_Replace this line with this product's content — the gate fails a brief that still carries it._
+
+One sentence. The promise the whole product makes, traced to `strategy/RESEARCH.md` or `11_STAR_EXPERIENCE.md` evidence — name the source line.
+
+## Message hierarchy
+
+_Replace this line with this product's content — the gate fails a brief that still carries it._
+
+- Primary promise: the one outcome the user buys.
+- Supporting benefits (2-3): each with its proof (a review quote, a metric, a demo moment).
+
+## Voice and tone
+
+_Replace this line with this product's content — the gate fails a brief that still carries it._
+
+- Reading level and person: second person, plain words, short sentences.
+- Case system: pick sentence case or title case once, record it here, hold it everywhere (`product/copy/COPY_DECK.md` repeats the choice).
+- Words we own: the product's coined terms, with one line on what each means.
+- Words we never use: jargon, internal vocabulary, and any term from the banned lists in `knowledge/words/conversion-copy.md`.
+
+## Voice benchmarks
+
+_Replace this line with this product's content — the gate fails a brief that still carries it._
+
+2-3 live consumer apps adjacent to this category whose current voice this product borrows from, and one anti-benchmark it must not sound like. Ground each borrowed attribute in words on their surfaces today, and date the teardown — `knowledge/words/consumer-copy-benchmarks.md` carries the method and starting cohorts.
+
+| App | Borrow or reject | Attribute, grounded in their current copy | Checked |
+| --- | --- | --- | --- |
+| | borrow | | |
+| | reject | | |
+
+## Voice-of-customer phrase bank
+
+_Replace this line with this product's content — the gate fails a brief that still carries it._
+
+Verbatim phrases from reviews, interviews, and support threads — the problem in their words, the outcome in their words, the objection in their words. Headlines and CTAs get written from this bank, not from taste.
+
+| Their words | Where it came from | Cluster |
+| --- | --- | --- |
+| | | problem / outcome / objection |
+
+## Per-surface copy blocks
+
+_Replace this line with this product's content — the gate fails a brief that still carries it._
+
+The locked promise as it appears on each conversion surface, with the variant under test marked. Landing hero, store title/subtitle/first description lines, paywall headline, onboarding value-reveal, key email subjects.
+
+## Claims ledger
+
+_Replace this line with this product's content — the gate fails a brief that still carries it._
+
+Every quantified, comparative, health, or earnings claim, with its substantiation or a note that it was removed. A claim with no ledger row does not ship.
+
+| Claim | Where it appears | Substantiation |
+| --- | --- | --- |
+| | | |

package/examples/workspace/business/product/copy/COPY_DECK.md

@@ -0,0 +1,84 @@
+# Copy Deck
+
+Status: template — every copy cell below is example voice from Fernpath, a fictional daily-walks app. Author this product's own words cell by cell, then set the status to `authored` with the date. `check:app-copy` fails a deck that ships example or unfilled cells.
+
+The deck is the single source for every string a user reads in the app. Builders type what a row says; a screen with no row stops the build until the row is authored. Voice comes from `product/copy/COPY_BRIEF.md` and `strategy/BRAND.md`; craft rules and surface formulas live in `knowledge/words/conversion-copy.md`; which locales ship comes from `LOCALIZATION_MARKET_RESEARCH.md`.
+
+Keys are the app's localization keys — the same name flows from this deck into the string resources unchanged where the format allows dots (String Catalogs, i18next); for ARB + `gen-l10n` and Android `strings.xml`, dots become underscores (the mechanical transform recorded in `engineering/TECH_SPEC.md`). Locale tier: `1` ships translated at launch, `2` ships source language, `3` deferred.
+
+Case system (from `product/copy/COPY_BRIEF.md`): sentence case everywhere except proper nouns.
+
+## Allowed terms
+
+None yet. Add a product-owned word here (with a one-line reason) only when `check:app-copy` would otherwise read it as internal vocabulary.
+
+## Onboarding
+
+Rows mirror the `product/ONBOARDING.md` screen sequence — one row per string, including buttons.
+
+| Key                             | Screen / moment           | Copy (source language)                                         | Voice notes                | Locale tier |
+| ------------------------------- | ------------------------- | -------------------------------------------------------------- | -------------------------- | ----------- |
+| onboarding.promise.headline     | Promise screen            | A ten-minute walk, every day                                   | outcome, user's words      | 1           |
+| onboarding.promise.body         | Promise screen            | Fernpath turns your daily walk into a streak you can see grow. | one idea                   | 1           |
+| onboarding.promise.cta          | Promise screen            | Get started                                                    | verb-first                 | 1           |
+| onboarding.attribution.question | Attribution screen        | How did you hear about us?                                     | keep short, honest         | 1           |
+| onboarding.attribution.other    | Attribution screen        | Somewhere else                                                 | plain option label         | 1           |
+| onboarding.personalize.question | Personalization screen    | When do you like to walk?                                      | one question per screen    | 1           |
+| onboarding.personalize.cta      | Personalization screen    | Continue                                                       | neutral step               | 1           |
+| onboarding.plan.loading         | Plan generation           | putting your week together                                     | lowercase narration        | 1           |
+| onboarding.plan.headline        | First value / plan reveal | Your first week, mapped                                        | the aha moment             | 1           |
+| onboarding.plan.cta             | First value / plan reveal | Start my week                                                  | possessive, forward        | 1           |
+| onboarding.push.prime.headline  | Push permission prime     | Keep your streak safe                                          | benefit before the dialog  | 1           |
+| onboarding.push.prime.body      | Push permission prime     | A nudge at your walking time, nothing else.                    | name exactly what they get | 1           |
+| onboarding.push.prime.accept    | Push permission prime     | Turn on reminders                                              | states the consequence     | 1           |
+| onboarding.push.prime.decline   | Push permission prime     | Not now                                                        | neutral, no shame          | 1           |
+
+## Paywall
+
+| Key                | Screen / moment | Copy (source language)            | Voice notes               | Locale tier |
+| ------------------ | --------------- | --------------------------------- | ------------------------- | ----------- |
+| paywall.headline   | Paywall         | Walk further with Fernpath Trails | restate the felt value    | 1           |
+| paywall.plan.name  | Plan card       | Trails                            | identity noun, not "Pro"  | 1           |
+| paywall.trial.line | Plan card       | Try one week for free             | spelled out, low pressure | 1           |
+| paywall.cta        | Paywall         | Start free week                   | value-named verb          | 1           |
+| paywall.restore    | Paywall footer  | Restore purchase                  | plain, always visible     | 1           |
+| paywall.decline    | Paywall footer  | Not now                           | neutral exit              | 1           |
+
+## Core loop
+
+| Key                 | Screen / moment | Copy (source language) | Voice notes                          | Locale tier |
+| ------------------- | --------------- | ---------------------- | ------------------------------------ | ----------- |
+| today.checkin.cta   | Today screen    | Log today's walk       | the one action                       | 1           |
+| today.done.headline | After check-in  | That's day {count}     | ICU interpolation, celebrate briefly | 1           |
+| today.done.cta      | After check-in  | See my streak          | forward-pointing                     | 1           |
+
+## Empty states
+
+| Key                    | Screen / moment       | Copy (source language)            | Voice notes           | Locale tier |
+| ---------------------- | --------------------- | --------------------------------- | --------------------- | ----------- |
+| history.empty.headline | History, no walks yet | Nothing here yet.                 | name it               | 1           |
+| history.empty.body     | History, no walks yet | Your first walk starts the story. | reframe it            | 1           |
+| history.empty.cta      | History, no walks yet | Log a walk                        | point at the next tap | 1           |
+
+## Errors
+
+| Key                 | Screen / moment        | Copy (source language)                                        | Voice notes                 | Locale tier |
+| ------------------- | ---------------------- | ------------------------------------------------------------- | --------------------------- | ----------- |
+| errors.offline.body | Any save while offline | Couldn't save — you're offline. We'll retry when you're back. | what happened + what's next | 1           |
+| errors.generic.body | Unexpected failure     | Something went wrong on our side. Try again in a moment.      | own it, no codes            | 1           |
+
+## Settings and dialogs
+
+| Key                      | Screen / moment     | Copy (source language) | Voice notes               | Locale tier |
+| ------------------------ | ------------------- | ---------------------- | ------------------------- | ----------- |
+| settings.reminders.label | Settings            | Walking reminders      | noun the user recognizes  | 1           |
+| dialogs.delete.title     | Delete confirmation | Delete this walk?      | consequence in the title  | 1           |
+| dialogs.delete.confirm   | Delete confirmation | Delete walk            | consequence on the button | 1           |
+| dialogs.delete.cancel    | Delete confirmation | Keep it                | neutral, human            | 1           |
+
+## Handoff checks
+
+- Every screen the build plan names has its rows here before the build starts.
+- Keys ship into the string resources via the mechanism and key transform `engineering/TECH_SPEC.md` records (unchanged where dots are allowed; dots→underscores for ARB and `strings.xml`).
+- Read each surface aloud once; rewrite anything that sounds like a system explaining itself.
+- `npm run check:app-copy -- --root <app> --state state/business-state.json` passes (a relative state path joins the root).