b2c-app-builder 0.221.39

package/knowledge/data/analytics-attribution.md

@@ -0,0 +1,317 @@
+# Analytics And Attribution Planning
+
+For the selected provider's official setup and skill procedures, use [PostHog agent tooling](./posthog-agent-tooling.md).
+The provider procedure does not replace this contract or grant authority.
+
+Use this before PostHog setup, event catalogs, attribution, dashboards, campaign links, onboarding questions, paywall experiments, referral loops, web funnels, paid UA, Fastlane campaigns, or builder prompts that mention analytics.
+
+Before marking this lane done, load [`provider-proof.md`](../process/provider-proof.md): provider-backed readiness needs live proof or a recorded founder-only decision in `operations/PROVIDER_PROOF.md`, never setup prose alone.
+
+The goal is to give the founder a visible measurement plan before launch work hardens. Do not bolt analytics on after the landing page, onboarding, paywall, or store CTAs are already built.
+
+Load `paid-user-acquisition.md` before paid ads, Apple Search Ads, Meta/TikTok/Google campaigns, paid creative tests, ad-network SDK choices, MMP decisions, or paid spend-readiness claims.
+
+Load [`paid-tool-routing.md`](../operations/paid-tool-routing.md) before replacing PostHog paid/account features, GA4/ad-network tooling, MMP tooling, RevenueCat experiments, ad-network account data, or Fastlane campaign analytics with a free/manual plan. Local event logs are not proof that analytics is live.
+
+## Contents
+
+- 1. Refresh Current PostHog Sources
+- 2. Required Artifacts
+- 3. Upfront Planning Workflow
+- 4. Identity Model
+- 5. Attribution Model
+- 6. Event Catalog
+- 7. Dashboards And Insights
+- 8. Experiments, Flags, Replays, And Surveys
+- 9. Privacy And Governance
+- 10. Implementation And QA
+- 11. Runtime Research Prompt
+
+## 1. Refresh Current PostHog Sources
+
+At runtime, refresh the current docs before locking implementation details. Prefer PostHog docs and official SDK docs over memory.
+
+Minimum PostHog doc map:
+
+- Product analytics overview: `https://posthog.com/docs/product-analytics`
+- Product analytics installation: `https://posthog.com/docs/product-analytics/installation`
+- Capturing events: `https://posthog.com/docs/product-analytics/capture-events`
+- Complete event tracking guide: `https://posthog.com/tutorials/event-tracking-guide`
+- Events: `https://posthog.com/docs/data/events`
+- Persons: `https://posthog.com/docs/data/persons`
+- Anonymous vs identified events: `https://posthog.com/docs/data/anonymous-vs-identified-events`
+- Web analytics: `https://posthog.com/docs/web-analytics`
+- Performance marketing and UTMs: `https://posthog.com/tutorials/performance-marketing`
+- iOS SDK: `https://posthog.com/docs/libraries/ios`
+- Android SDK: `https://posthog.com/docs/libraries/android`
+- React Native SDK: `https://posthog.com/docs/libraries/react-native`
+- Flutter SDK: `https://posthog.com/docs/libraries/flutter`
+- Feature flags: `https://posthog.com/docs/feature-flags`
+- Experiments: `https://posthog.com/docs/experiments`
+- Session replay: `https://posthog.com/docs/session-replay`
+- Session replay privacy: `https://posthog.com/docs/session-replay/privacy`
+- Surveys: `https://posthog.com/docs/surveys`
+- Data pipelines/CDP: `https://posthog.com/docs/cdp`
+
+Also refresh:
+
+- RevenueCat docs for subscription events, customer IDs, webhooks, experiments, Web Purchase Links, Web Funnels, and redemption links.
+- RevenueCat growth guidance and `paid-user-acquisition.md` when paid UA needs LTV, cohort, CPA, blended-report, or baseline-uplift planning.
+- Stripe docs when web checkout, Customer Portal, or Stripe Billing is in scope.
+- Apple App Analytics, Apple Search Ads, App Store privacy, and SKAdNetwork/AdAttributionKit docs when iOS paid acquisition is in scope.
+- Google Play Console analytics, Play Install Referrer, Data safety, and Google Ads/GA4 docs when Android paid acquisition is in scope.
+- Resend docs when email lifecycle, broadcasts, or webhooks are in scope.
+- Fastlane docs/API when social content campaigns need UTM/campaign measurement.
+
+## 2. Required Artifacts
+
+Create `analytics/ANALYTICS.md` before implementation or builder handoff.
+
+Update `state/business-state.json` before calling analytics ready:
+
+- lane status and evidence paths for `analytics_attribution`
+- provider state for PostHog, RevenueCat, Stripe, Resend, Sentry, or ad/MMP tools when relevant
+- current-doc basis for fast-moving analytics/provider setup
+- attribution contract booleans, stable keys, event name, person properties, backend persistence, anonymous reconciliation, and verification status
+- active failure cards for missing analytics, attribution, privacy, replay/survey, or dashboard proof
+
+`analytics/ANALYTICS.md`'s required sections are defined once, canonically, in [`artifact-contracts.md`](../process/artifact-contracts.md) `analytics/ANALYTICS.md` — load that section rather than a second checklist here; a second copy is how the two lists drift on exactly the details that matter (event grouping, the identity-map fields).
+
+Create `analytics/analytics-plan.html` or an analytics section in `design/design-room.html` early:
+
+- show the acquisition-to-revenue journey as a visual map
+- include copyable event tables grouped by surface
+- render funnel cards for acquisition, onboarding, paywall, activation, retention, referral, email, and post-launch social
+- show an attribution matrix with UTM/source/deep-link/self-report examples
+- show dashboard wireframes or screenshot placeholders
+- mark founder-only decisions and blocked credentials
+- use `DESIGN.md` tokens when available; otherwise label it as provisional
+
+After analytics status changes, report what is planned, connected, and still unverified.
+
+## 3. Upfront Planning Workflow
+
+1. Inventory surfaces before writing events: landing, app install/open, onboarding, paywall, subscription, web checkout, paid UA, referral/share, email, support, privacy/deletion, store CTAs, Fastlane/social campaigns, backend jobs, and admin tools.
+2. Define the decision the founder must see upfront: what users are doing, where they came from, where they drop, what converts, what retains, what produces revenue, and which channel is worth repeating.
+3. Choose the minimum analytics stack. Default to PostHog primary, RevenueCat for subscription truth, Stripe for web payment truth, Sentry for errors, and GA4/ad-network tooling only when paid ads or Google attribution require it.
+4. Decide PostHog region and project grouping before setup. PostHog recommends grouping multiple customer-facing products such as marketing site, mobile app, and web app in one project when the goal is cross-surface journey analysis.
+5. Write the identity and attribution model before event names. Do not let each surface invent its own user ID or source fields.
+6. Draft the event catalog and dashboards, then map each event to the exact screen, server endpoint, webhook, provider callback, or email lifecycle hook that emits it.
+7. Add privacy and store-disclosure notes while planning, not after implementation.
+8. Render `analytics/analytics-plan.html` so the founder can inspect the tracking plan and understand launch learning before the build starts.
+
+## 4. Identity Model
+
+Default identity stance:
+
+- Start anonymous on marketing pages and pre-auth app usage.
+- Call `identify` as soon as a stable logged-in user ID exists.
+- Use the same internal user ID across app, backend, RevenueCat, Stripe, support, and email where possible.
+- Keep PostHog person profiles to `identified_only` unless the current docs and product privacy posture justify another mode.
+- Call reset/logout behavior on shared devices so events do not bleed between users.
+- Treat email as a property, not the primary distinct ID, unless the product has no better stable ID.
+
+Map these IDs explicitly:
+
+- `anonymous_distinct_id`
+- `user_id` or auth UID
+- `posthog_distinct_id`
+- `revenuecat_app_user_id`
+- `stripe_customer_id`
+- `resend_contact_id` or email hash
+- `referral_code`
+- `device_platform`, `app_version`, `build_number`, `locale`, `country`, `storefront`
+- optional: `installation_id`, `push_token_id`, `family_or_team_id`, `group_id`
+
+For iOS extensions, widgets, app clips, or Android instant/deep-link flows, document whether the SDK can share identity across targets or whether the first event may be anonymous.
+
+## 5. Attribution Model
+
+Use both technical and self-reported attribution. Neither is enough alone.
+
+Technical attribution:
+
+- UTMs: `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`
+- Click IDs: `gclid`, `fbclid`, `msclkid`
+- Referrer and landing URL
+- Initial and latest source/campaign properties
+- Deep link route and campaign payload
+- App Store / Google Play source where available
+- Referral code, invite code, creator code, vanity URL, QR code, or coupon code
+- Fastlane/social post ID and content angle where links are generated
+
+Self-reported attribution:
+
+- Ask "How did you hear about us?" in onboarding or signup while memory is fresh.
+- Include options for friend/referral, TikTok, Instagram, YouTube, X/Twitter, Reddit, search, App Store/Google Play search, creator/influencer, newsletter/email, article/blog, podcast, ad, and other/free text.
+- Store a stable stored key as a first-touch user property and event property on `attribution_source_selected`.
+- Keep source keys stable; display labels may change through aliases, but stored keys must not.
+- Persist the source to the backend profile, account, waitlist, or Supabase profile record when identity exists.
+- Reconcile anonymous attribution into the identified PostHog person and backend profile after signup/login.
+
+Self-reported attribution data contract:
+
+- Stored keys: use a typed enum or equivalent constants such as `friend`, `tiktok`, `instagram_reels`, `youtube`, `x_twitter`, `reddit_search`, `app_store_search`, `play_store_search`, `creator`, `podcast`, `ai_search`, `ad`, and `other`.
+- Event: emit `attribution_source_selected` with `source_key`, `source_label`, `other_text_present`, `flow_id`, `step_id`, `initial_utm_source`, `initial_utm_medium`, `initial_utm_campaign`, `initial_referrer`, `referral_code`, `creator_code`, and deep-link/store context when available.
+- PostHog person properties: set `self_reported_source`, `self_reported_source_label`, `self_reported_source_other_text_present`, and `self_reported_source_captured_at`. Store raw `self_reported_source_other` only when privacy docs allow it.
+- Backend/profile fields: persist `self_reported_source`, `self_reported_source_label`, `self_reported_source_other`, `self_reported_source_captured_at`, and `self_reported_source_context` or the product's named equivalents.
+- Verification: prove event delivery, person-property update, backend/profile write, and anonymous-to-identified stitching. Do not call attribution wired if it only updates local state or emits a one-off event.
+- State: set `state/business-state.json` attribution contract fields to true only after each corresponding implementation/proof exists.
+
+Campaign convention:
+
+- `utm_source`: platform or partner, e.g. `tiktok`, `instagram`, `youtube`, `reddit`, `apple_search_ads`, `creator_<handle>`
+- `utm_medium`: `organic_social`, `paid_social`, `search`, `email`, `referral`, `creator`, `store`, `qr`, `fastlane`
+- `utm_campaign`: launch, product, market, and date, e.g. `launch_v1_2026_06`
+- `utm_content`: hook, creative, post ID, screenshot concept, or Fastlane angle
+- `utm_term`: search keyword or ASA/ad keyword when applicable
+
+Store and mobile caveats:
+
+- Do not promise perfect attribution from app install to purchase. App-store privacy rules, browser handoffs, SKAdNetwork/AdAttributionKit, Play Install Referrer, tracking blockers, and user behavior create gaps.
+- Adopting an ad-network SDK to close that gap changes privacy disclosures and ATT posture — load [`privacy-terms.md`](../trust/privacy-terms.md) and [`store-console-workflow.md`](../store/store-console-workflow.md) before enabling one, not after.
+- Use self-reported attribution to catch word-of-mouth, creator, social, and AI-search discovery that UTMs miss.
+- Preserve campaign context from landing page to store CTA, deep link, waitlist, web checkout, and email where the platform allows it.
+
+## 6. Event Catalog
+
+Rules:
+
+- Use snake_case event names in this skill, even though PostHog examples often show object-verb names with spaces.
+- Emotion Card events: when the Emotional Experience System is in scope (see [`emotional-design-system.md`](../experience/emotional-design-system.md) and [`emotional-experience-measurement.md`](../experience/emotional-experience-measurement.md)), register the system-level envelope events `emotion_card_fired`, `emotion_card_completed`, `emotion_card_abandoned`, and `emotion_card_opt_out`, plus the per-card events (`commitment_made`, `variable_reward_revealed`, `perceived_effort_started`/`perceived_effort_completed`, `intent_mirror_shown`/`intent_mirror_continued`). Every card applied in `EMOTIONAL_DESIGN.md` must name one of these here before implementation, and the HIGH-risk counter-metrics feed a "Dark-Pattern Watch" insight (rage-tap abandons, opt-outs, sub-500ms dismissals, cancels within 24h of a card fire).
+- Keep event names stable; change display labels in dashboards, not emitted names.
+- Every event must have: owner, surface, trigger, required properties, optional properties, privacy note, QA method, dashboard usage.
+- Prefer semantic events for key decisions and allow autocapture/web analytics for exploratory web behavior.
+- Server-side events should cover purchase/webhook/account truth; client-side events should cover UI behavior and timing.
+
+Minimum B2C launch events:
+
+- Acquisition: `landing_page_viewed`, `pricing_section_viewed`, `app_store_cta_clicked`, `waitlist_joined`, `referral_link_created`, `referral_link_opened`, `referral_invite_started`, `referral_invite_completed`, `referral_unlock_earned`, `share_started`, `share_completed`, `web_checkout_started`
+- Attribution: `campaign_context_received`, `deeplink_opened`, `attribution_source_selected`, `creator_code_applied`
+- App: `app_opened`, `signup_started`, `signup_completed`, `login_completed`, `permission_prompt_viewed`, `permission_granted`
+- Onboarding: `onboarding_started`, `onboarding_step_viewed`, `onboarding_answer_selected`, `demo_video_viewed`, `personalized_plan_viewed`, `onboarding_completed`
+- Review: `review_prompt_eligible`, `review_prompt_requested`, `review_prompt_continued`
+- Paywall/revenue: `paywall_viewed`, `paywall_dismissed`, `closing_offer_viewed`, `closing_offer_selected`, `trial_started`, `purchase_started`, `purchase_completed`, `purchase_failed`, `entitlement_active`, `restore_started`, `restore_succeeded`, `subscription_cancelled`, `refund_detected`
+- Activation/retention: `activation_task_started`, `activation_task_completed`, `core_action_completed`, `share_started`, `share_completed`, `notification_opened`, `return_session_started`
+- Email/lifecycle: `email_subscribed`, `email_sent`, `email_delivered`, `email_clicked`, `email_unsubscribed`, `lifecycle_message_triggered`
+- Support/privacy: `support_contact_clicked`, `data_deletion_requested`, `privacy_choice_updated`
+- Post-launch social: `viral_format_signal_detected`, `fastlane_content_generated`, `fastlane_content_approved`, `fastlane_content_scheduled`, `social_campaign_click_received`
+
+Core properties:
+
+- `platform`, `device_type`, `app_version`, `build_number`, `environment`, `locale`, `country`, `storefront`
+- `surface`, `screen_id`, `step_id`, `flow_id`, `variant_id`, `feature_flag_key`, `experiment_key`
+- `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `gclid`, `fbclid`, `msclkid`, `referrer`, `landing_url`
+- `initial_utm_source`, `initial_utm_medium`, `initial_utm_campaign`, `initial_referrer`
+- `self_reported_source`, `self_reported_source_label`, `self_reported_source_other_text_present`, `referral_code`, `creator_code`, `fastlane_post_id`, `content_angle`
+- `offering_id`, `package_id`, `product_id`, `price_id`, `currency`, `trial_state`, `is_intro_offer`, `entitlement_id`
+- `error_code`, `error_state`, `network_state`, `privacy_consent_state`
+
+## 7. Dashboards And Insights
+
+Create launch dashboards before public traffic:
+
+- Founder launch control room: visitors, waitlist joins, store clicks, app opens, onboarding starts/completions, paywall views, purchases, revenue, activation, errors.
+- Attribution dashboard: first/latest UTM, referrer, self-reported source, creator/referral codes, store CTA by channel, Fastlane post/angle performance.
+- Onboarding funnel: app opened -> onboarding started -> each key step -> attribution answered -> plan/demo viewed -> paywall viewed -> purchase/trial/activation.
+- Revenue dashboard: paywall conversion, trial starts, Day 0 cancellations, purchase failures, restore success, entitlement active, refund/dispute signals.
+- Retention dashboard: D1/D3/D7 returns, core action retention, lifecycle chart, new/returning/resurrected/dormant users.
+- Quality dashboard: errors/crashes from Sentry/store reports, support clicks, session replay volume, rage/friction signals where available.
+- Email lifecycle dashboard: waitlist confirmations, welcome, onboarding resume, trial reminders, payment recovery, unsubscribes, clicks.
+
+Each dashboard definition should state:
+
+- exact events and filters
+- date range
+- breakdowns
+- conversion window
+- success threshold or "watch only"
+- owner
+- what action to take when it moves
+
+## 8. Experiments, Flags, Replays, And Surveys
+
+Plan experiments before build:
+
+- onboarding order and question count
+- mascot/demo video presence
+- attribution question wording/options
+- paywall timing, package mix, trial length, closing offer, and annual highlight
+- landing headline, CTA, proof block, pricing block, referral prompt
+- email lifecycle timing and subject lines
+
+Use PostHog feature flags for safe rollouts, remote config, cohort targeting, and experiment assignment when the current docs and SDK support the target stack. Use RevenueCat experiments for paywall/offering tests when RevenueCat controls the paywall surface.
+
+Session replay:
+
+- Enable only with documented privacy controls, masking, sampling, and consent posture.
+- Use replay to inspect failed funnels, onboarding confusion, paywall dismissals, support issues, and first-session activation.
+- Do not record sensitive screens unless masking and policy coverage are verified.
+
+Surveys:
+
+- Use self-reported attribution early.
+- Use PMF/NPS/CSAT or cancellation surveys only after enough usage context exists.
+- Target surveys with cohorts or events so they do not interrupt the first value moment.
+
+## 9. Privacy And Governance
+
+Analytics planning must update `trust/PRIVACY.md`, `LEGAL_REVIEW.md`, and store console answers.
+
+Document:
+
+- analytics vendor, host/region, SDKs, and whether data is linked to identity
+- event categories collected
+- UTM/referrer/click IDs and self-reported attribution
+- session replay, heatmaps, surveys, feature flags, and experiments
+- retention/deletion behavior and user opt-out path
+- whether advertising IDs, device identifiers, precise location, contacts, photos, health data, or sensitive content are collected
+- whether events are sent to destinations, data warehouse, webhooks, Slack, CRM, email tools, or ad platforms
+
+Rules:
+
+- Do not capture raw user content, prompts, photos, messages, or health/sensitive data in analytics properties unless the product requires it and legal/privacy docs cover it.
+- Prefer IDs, counts, categories, and derived states over raw content.
+- Keep service keys server-side. PostHog project tokens are public/write-only only when the current docs say that is acceptable for the SDK surface.
+- Explicitly document opt-out or consent behavior for web and app if the market or data type requires it.
+
+## 10. Implementation And QA
+
+Implementation rules:
+
+- Use one analytics wrapper/module per surface.
+- Capture client UI events in the client and source-of-truth events on the server/provider webhook.
+- Initialize SDKs early enough for first events, but after consent/opt-out gates where required.
+- Keep environment separation: development, staging/test, production.
+- Do not emit test data into production unless labeled with `environment=test` and cleaned or filtered.
+- Add typed constants or generated event helpers when the repo supports TypeScript, Swift, Kotlin, Dart, or React Native typing.
+
+QA checklist:
+
+- PostHog project reachable, correct host/region, and correct project token.
+- At least one real event appears in PostHog activity or equivalent live view.
+- `app_opened` or first app event fires on real device/simulator.
+- Web pageview and waitlist/store CTA events fire from the production or preview URL.
+- UTM/referrer/click ID properties persist from landing to conversion where possible.
+- Self-reported attribution uses stable source keys, not display labels.
+- Self-reported attribution event and person properties appear after onboarding/signup.
+- Self-reported attribution persists to backend/profile storage when identity exists.
+- `other` attribution captures sanitized free text or a documented follow-up value when selected.
+- `identify` links anonymous and known user journey after signup/login.
+- Logout/reset behavior prevents identity bleed.
+- RevenueCat/Stripe/webhook events reconcile with entitlement events.
+- Feature flag/experiment exposure events fire once per intended exposure.
+- Session replay and surveys respect masking, sampling, and consent settings.
+- Privacy/terms/store data disclosures match the actual SDK/event behavior.
+- `npm run check:attribution -- --root .` or the installed-skill equivalent passes when onboarding/signup/waitlist attribution exists.
+- `state/business-state.json` reflects analytics provider state, proof, and blockers.
+
+## 11. Runtime Research Prompt
+
+Before writing `analytics/ANALYTICS.md`, run a current-doc pass like:
+
+```text
+Research current PostHog docs for this app's stack and produce an analytics/attribution plan before launch. Cover product analytics installation, event capture, web analytics, mobile SDK setup, anonymous vs identified events, persons/properties, UTM/referrer/click ID attribution, feature flags, experiments, session replay privacy, surveys, and data pipelines. Map each doc finding to this app's landing, onboarding, paywall, subscription, email, referral, store CTA, and Fastlane/social campaigns. Output analytics/ANALYTICS.md plus analytics/analytics-plan.html with funnels, event catalog, identity model, attribution model, dashboards, privacy notes, and QA gates.
+```
+
+If the product repo already exists and is ready, use the installed `setup-posthog` skill for initial project setup and first-event validation after the plan is approved. If the repo does not exist, stop at the plan, event catalog, and builder prompts.

package/knowledge/data/posthog-agent-tooling.md

@@ -0,0 +1,101 @@
+# PostHog agent tooling in a consumer business
+
+Use this only for a selected PostHog integration or audit. This guide adapts the
+MIT wizard README and uses official product documentation for identity and privacy.
+It does not bundle context-mill skill text or install an upstream agent.
+
+## Contents
+
+- Prepare the integration contract
+- Decide whether to use the wizard
+- Reuse selected upstream procedures
+- Implement first-session measurement
+- Verify delivery and isolation
+
+## Prepare the integration contract
+
+Before implementing screens, resolve the app, environment, PostHog project/region,
+authentication model and consent policy. Use `analytics/ANALYTICS.md`, the accepted
+onboarding contracts and `operations/metric-contracts.json` as the existing owners.
+An upstream wizard can propose events; it cannot replace that event dictionary,
+change the meaning of activation, or make itself the owner of authentication.
+
+Separate SDK setup, instrumentation, analytics reads, replay, feature flags,
+experiments, warehouse connections and source-map uploads. Supporting one does not
+authorize all the others. Keep server credentials out of client bundles and logs.
+
+## Decide whether to use the wizard
+
+PostHog's wizard describes source-file processing through its LLM gateway and
+Anthropic, default telemetry, organization AI opt-in and a secret scanner. Treat
+these as declared behaviors to verify, not a guarantee that disclosure cannot occur.
+
+Before an authorized run, preview the exact app root, files available to the agent,
+remote recipients, project/region, dependency edits and generated configuration.
+Review the source-upload permission separately from telemetry. `--no-telemetry`
+does not disable source upload required by the AI integration flow. Do not run the
+wizard in the builder repository when the intended target is a consumer app.
+
+Prefer integration using our existing worker and reviewed platform guidance when
+external AI processing is not authorized. Do not disable a scanner or bypass an
+organization's AI opt-in to finish setup. Running a command called an audit may
+still execute an agent, disclose source, or offer writes; its name is not a grant.
+
+## Reuse selected upstream procedures
+
+The reviewed wizard describes integration, `audit events`, `audit identify`,
+`audit feature-flags`, and `audit session-replay` as focused jobs. Choose only the
+job in scope and preserve builder review and evidence gates. Runtime command menus
+may be fetched from context-mill, independently of the installed wizard version.
+Pin or record the selected bundle and verify its compatibility before use.
+
+Context-mill is tracked separately because its inspected revision has no root
+license. Its skill files, examples and generated bundles are not redistributed or
+adapted here. Recheck rights and dependencies for a selected bundle before adoption;
+the wizard's MIT license does not license that other repository. Its examples are
+not production authentication or ready-made consumer businesses.
+
+Do not auto-enable self-driving jobs, replay, warehouse ingestion, source-map upload
+or Stripe revenue integration merely because the wizard offers them. A revenue
+analytics example for Stripe is not proof of a RevenueCat integration. Billing and
+analytics identities must use the explicitly agreed mapping, not guessed joins.
+
+## Implement first-session measurement
+
+Apply [onboarding foundations](../experience/onboarding-foundations.md) from the
+first prototype. Restore the app's privacy and identity state before collection.
+Identify using the verified opaque app user ID under the approved policy. Reset
+analytics identity on logout as the selected SDK requires and test account switching.
+Backend event identity must agree with the authenticated subject; a client-provided
+analytics ID is not a backend authentication credential.
+
+Keep first open, first value, onboarding completion and paid conversion distinct.
+Use the declared event/property allowlist, deduplication and emitters. Never send
+tokens, passwords, unrestricted form content, or unreviewed personal attributes.
+Do not infer a successful purchase from a paywall close event.
+
+Retain first-touch/last-touch attribution only within its declared persistence and
+consent rules. Test direct and deferred links and anonymous-to-identified joins.
+Missing campaign data stays unknown. Consent denial does not justify fingerprinting
+or reconstructing an identity. SDK opt-out, cookieless collection, replay and
+server-side events have separate behaviors: verify the chosen mode against the
+accepted policy rather than assuming one client flag blocks every data route.
+
+Official behavior references:
+https://posthog.com/docs/product-analytics/identify
+https://posthog.com/docs/privacy/data-collection
+
+## Verify delivery and isolation
+
+Run the synthetic first-session, consent denial/revocation, auth failure/cancel,
+logout/account switch, retry/offline and collector-outage scenarios from the
+onboarding contract. Verify actual collector readback for allowed events, and
+absence from the relevant client and server routes when the policy requires it.
+
+Test duplicate SDK initialization and events, stale source maps, incorrect project
+or region, replay masking and sensitive properties. Keep first value usable during
+analytics outages. An SDK dependency, dashboard screenshot, local print statement
+or wizard success message alone does not prove event delivery or identity isolation.
+
+The builder retains product decisions and independent acceptance. Provider source
+updates remain reviewed contributions, not permission to repin an existing business.

package/knowledge/design/audience-derived-identity.md

@@ -0,0 +1,55 @@
+# Audience-Derived Identity: From Brief To Design Decisions
+
+Use this reference when creating or materially revising `DESIGN.md`, and when reviewing a direction. The required discipline is to explain, compare, implement and inspect consequential choices. No palette, font class, metaphor, layout or motion style is universally required.
+
+## Communication Brief
+
+Record the audience, situation, user task, intended takeaway and next action in `DESIGN.md` under Audience And Identity. Link relevant `strategy/RESEARCH.md` evidence. Distinguish observed facts from assumptions and creative hypotheses. Research does not prove that a particular typeface produces an emotion.
+
+For each material decision, name its reason: audience evidence, task clarity, accessibility, platform convention, product identity, or an explicit creative hypothesis. Record the uncertainty and how the actual result will be judged. Pleasure, familiarity and restraint are legitimate purposes. A small correction needs a bounded rationale, not a new research workshop.
+
+## The Derivation Chain
+
+1. Read the accepted promise and audience context. Separate the product identity from features and campaigns. Establish the communication problem before styling.
+2. Inspect relevant references and ordinary product-world material. Name each reference's permitted influence and forbidden transfers. Palette, typography, composition and behavior are separate dimensions.
+3. Compare meaningful alternatives when establishing a direction. Vary the organizing idea, information priorities, type relationships or imagery role; changing colors alone is not a new concept. Preserve familiar controls when they help the task.
+4. Select the direction against the brief. Record rejected alternatives and the concrete reason. A physical metaphor, conceptual substitution, editorial density, or purposeful imbalance is available when it helps; a direct quiet interface is equally eligible.
+5. Explain the system through actual content and states. Define alignment, grouping, reading order, emphasis, rhythm, text measure and image relationships. Test mobile composition separately from desktop.
+6. Keep stable identity decisions and permitted variation in the Anchor Brand Kit inside `DESIGN.md`. Apply it to core work, recovery, settings, offers and marketing; a hero alone cannot demonstrate the system.
+7. Inspect representative unbranded outputs. Ask which choices serve this audience and which are inherited defaults. Compare same-category audiences as well as unrelated products. Shared navigation or accessible controls are not failures of originality.
+
+## Composition Review
+
+Check what the viewer notices first, reads next, understands and can act on. The focal image need not be the first readable message. Proximity must group related information; an aligned layout can still imply the wrong relationship. A grid supports this work, but a fixed column count cannot decide it.
+
+Compare a conventional composition with an exception only when the exception has a useful role. Overlap, counterpoint, unusual scale and negative space may connect ideas. Reject them when they hide qualifications, confuse choice mapping or break text expansion. Pricing, consent and recovery must not depend on solving a visual puzzle.
+
+## Generic-Design Diagnostics
+
+A familiar treatment prompts a question; it is not a mechanical taste failure. A gradient, system font, uniform radius, icon library, card row or dark canvas may be appropriate. Review whether it serves the current task, preserves clarity and belongs to the chosen identity. Do not infer the absence of thought from a style's name or count two familiar patterns as an automatic failure.
+
+Name the actual defect: interchangeable message, unrelated grouping, unexplained decorative emphasis, identity drift, weak contrast, inaccessible control, or repetitive composition across different briefs. The repair must address that defect. Replacing a gradient with another fashionable treatment is not sufficient.
+
+## Category Conventions
+
+Treat category codes as hypotheses to inspect, not audience facts. A novice running companion and an advanced club-analysis app may share controls while differing in information density, language and emotional pace. A household utility may benefit from familiar typography and calm order. A regional food publication may need expressive editorial relationships. None requires a prescribed palette.
+
+Record which conventions help users, which need changing and why. Anti-references are useful when a specific confusion or unwanted association exists; inventing three enemies is not a requirement. Do not force difference at the expense of usability.
+
+## Selectable Creative Methods
+
+Use conceptual substitution when combining familiar meanings makes the product's message clearer. State the intended reading and compare a direct treatment. Use predictive empathy as an explicit hypothesis about the user's next concern; check comprehension separately from reported reassurance. A moment of curiosity does not prove later recall.
+
+For premium positioning, distinguish genuine exclusivity, audience identification and storytelling. Exclusivity may concern craftsmanship or meaningful belonging; it is not permission to invent scarcity. Research the segment, maintain a coherent direction across variants, then measure relevant behavior with an exposure window and denominator. A campaign narrative or brand anecdote cannot prove revenue causality. Utility and accessibility can outweigh status signaling.
+
+Treat typography as a working language: compare weights, widths, scale, measure and type/image counterpoint with actual product text. See `design-visual-system.md` for roles and resources. Personal creative practice may inspire bounded exploration; biography, work hours, popularity and artistic distortion are not requirements or factual evidence.
+
+## Critique And Transfer
+
+Give an independent reviewer the accepted brief and actual candidate before the producer's explanation. Ask for a diagnosis and concrete repair, including a valid purposeful exception. Separate brief misunderstanding, weak concept, composition, typography, implementation and unsupported claims. Then compare the author's reasoning with the review; neither prose nor confidence proves correctness.
+
+Source lessons are hypotheses until tested in the present work. Described demonstrations, career claims, historical anecdotes and popularity are not evidence of conversion, memory or superiority. A useful method should help identify a consequential defect on a new brief, not merely repeat its vocabulary.
+
+## Gates
+
+`check:design-room` checks the authored section, evidence references and placeholder state. It cannot establish originality, emotional response or effective composition. Token and schema checks establish their declared facts. Independent inspection and representative task evidence establish whether the actual direction works. Keep failures open until an inspected repair resolves them.

package/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.