b2c-app-builder 0.221.39

package/knowledge/design/vibecoded-tells.md

@@ -0,0 +1,129 @@
+# Vibecoded Tells: The Default-Design Smell List
+
+Use this reference before you build or review a landing page, funnel page, web marketing surface, or app screen. Also load it when the vibecode audit pass (see §Audit Pass) is dispatched. It lists patterns worth inspecting in context. Their presence does not identify how an artifact was made or establish a loss of trust or conversion.
+
+This list adapts a widely shared 30-item "reasons your site looks vibecoded" checklist to this engine's doctrine. It extends the Generic-Design Tells table in [`audience-derived-identity.md`](./audience-derived-identity.md). That file explains why the defaults exist. This file gives the reviewable smell list and the audit pass that applies it.
+
+## Contents
+
+- The Rule
+- Tier 1: Trust Breakers
+- Tier 2: Visual Default Tells
+- Tier 3: Copy Tells
+- Scoring A Review
+- Mechanical Detection
+- Audit Pass
+- Gates
+
+## The Rule
+
+A visual tell is a default, not a ban. A default becomes a decision only through the derivation chain in [`audience-derived-identity.md`](./audience-derived-identity.md). Record material decisions in `DESIGN.md` using audience evidence, an explicit creative hypothesis, legibility, or platform constraints. Review the actual result against the user job; do not invent an audience fact to justify a form.
+
+Tier 1 items are different. They are honesty and completeness requirements. No derivation can earn a fake testimonial or a missing privacy policy.
+
+## Tier 1: Trust Breakers
+
+These fail a surface on a single hit. Each one has an owning artifact, so the fix is concrete.
+
+| Smell                             | Requirement                                                                                                          | Owning artifact                                                                                                               |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Fake or unattributed testimonials | Only real, sourced quotes with permission. No invented names, counts, or star ratings.                               | `product/experience/emotional-design/EMOTIONAL_DESIGN.md` social-proof card with truthfulness proof; `check:emotional-design` |
+| No terms of service               | The landing footer links a real terms page before deploy.                                                            | `trust/TERMS.md`                                                                                                              |
+| No privacy policy                 | The landing footer links a real privacy page before deploy.                                                          | `trust/PRIVACY.md`                                                                                                            |
+| No real product demo              | Show the real app UI: captures, recordings, or live embeds. Do not substitute abstract illustration for the product. | `growth/DEMO_VIDEO.md`; quality-lens rule that visuals support real app UI                                                    |
+| No skeleton or loading states     | Every async surface designs its loading, empty, error, and offline states.                                           | design-guru owned states; `DESIGN.md` screen specs                                                                            |
+
+## Tier 2: Visual Default Tells
+
+Each row prompts a contextual question and gives a possible justification. Audience evidence, a creative hypothesis, communication needs, legibility, or platform conventions can support a choice. These examples are not exclusive permission rules. Review material decisions and actual behavior; do not require an invented audience fact.
+
+| Smell                                                           | Why it reads as vibecoded                                  | Earned when                                                                                     |
+| --------------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Harsh gradients (indigo-to-purple hero, gradient headline text) | Can compete with hierarchy when used without purpose   | The palette derivation names the gradient's role and its brand hues                             |
+| Default icon packs (Lucide, Heroicons, generic thin-line sets)  | An unexamined choice may create inconsistent or ambiguous controls | Consistent, recognizable functional controls; custom identity marks where the product needs them                             |
+| Pure white background with no surface system                    | A canvas nobody decided; no depth or zoning model          | An editorial direction states white as a choice with a surface scale                            |
+| Rainbow coloring (many hues, no semantic system)                | Color without a system reads as unowned decoration         | Each hue carries a recorded semantic role                                                       |
+| Default drop shadows on every card                              | One shadow token stamped everywhere; no light model        | A stated elevation system with few, purposeful levels                                           |
+| Three feature cards in a row                                    | The tutorial demo layout                                   | The content genuinely has three parallel items and the layout derivation says so                |
+| Emoji as icons or in headings                                   | A shortcut where an icon system was owed                   | Meaning is clear, labels remain accessible, and the tone fits the task; functional use needs recognizable semantics       |
+| Liquid glass and glassmorphism                                  | Transparency can obscure content or weaken hierarchy                    | A legible, purposeful layer with acceptable performance                              |
+| Inter, Geist, or Space Grotesk with no rationale                | The corpus default standing in for a typography decision   | The face supports representative content, platform behavior, and the intended voice                               |
+| Colored left-stripe callouts                                    | Documentation-site chrome pasted onto marketing            | The stripe groups or distinguishes meaningful content without relying on color alone                                              |
+| Bento grids                                                     | The current template fashion; portable everywhere          | The content is truly modular and the derivation names why a grid beats a narrative flow         |
+| Fake terminal or code windows                                   | Generic tech garnish on a non-developer product            | The product is a developer tool showing real commands                                           |
+| Checkmark bullet walls                                          | Feature-dump formatting that replaces persuasion           | Short, verified capability lists; never as the page's main argument                             |
+| Three pricing tiers by default                                  | A pricing UI copied before the offer was designed          | Pricing state in `revenue/REVENUE_OPS.md` actually defines the tiers                            |
+| Uniform soft corner radius everywhere                           | One radius token set once and never revisited              | A radius scale tied to component meaning                                                        |
+| Purple-and-black SaaS chrome                                    | Category mismatch on most consumer products                | A recorded dark-canvas rationale, as in the Whoop case study                                    |
+| Radial orbs and blurred blob shapes                             | Decorative filler for undecided space                      | A stated compositional purpose that survives actual surface review                                        |
+| Dot-grid backgrounds                                            | Template texture with no meaning                           | The texture supports composition without competing with reading or interaction                                   |
+| Sparkle icons for AI features                                   | The generic "AI" costume                                   | The brand system derives its own marker for generated content                                   |
+| Animated scroll arrows and bouncing cues                        | Motion that begs instead of guiding                        | Motion doctrine in [`landing-motion-craft.md`](./landing-motion-craft.md) assigns the cue a job |
+| Decorative hover animations everywhere                          | Motion without hierarchy; every card wiggles               | Hover states that communicate affordance, per the motion tokens                                 |
+| Neon glow accents                                               | Loudness standing in for identity                          | The accent supports emphasis or an explicit identity hypothesis while preserving legibility                                          |
+| Basic pastel palette                                            | The soft default when nobody chose saturation              | Saturation supports the intended communication and semantic contrast, independent of category stereotypes                                       |
+
+## Tier 3: Copy Tells
+
+Two reel items are writing smells, and [`no-slop-writing.md`](../words/no-slop-writing.md) already governs them. Do not re-litigate them here; load that file for copy review.
+
+- Em-dash overuse: no-slop §5, em-dash budget.
+- "It's not X, it's Y" framing: no-slop §5, binary contrasts and negative listing.
+
+## Scoring A Review
+
+- Any Tier 1 hit fails the surface. Fix the artifact, not the wording.
+- Tier 2 patterns prompt contextual inspection. Their number does not decide acceptance. Fail a material communication, usability, identity, or truthfulness defect with evidence.
+- A Tier 2 warning can be resolved by a justified accepted choice; novelty is not required.
+- Copy tells route to the no-slop review, not this one.
+
+Review material choices against the accepted contract and actual output. Conventional controls do not each need a separate rationale row.
+
+## Mechanical Detection
+
+`check:vibecoded-tells` catches the greppable subset over landing and web-surface source. Judgment stays with the audit pass below.
+
+| Check code                        | Catches                                                                    | Severity |
+| --------------------------------- | -------------------------------------------------------------------------- | -------- |
+| `vibecode.default_icon_pack`      | Lucide or Heroicons imports in web-surface source                          | warning    |
+| `vibecode.legal_links_missing`    | A site-shaped landing with no terms or privacy link                        | error    |
+| `vibecode.emoji_in_markup`        | Emoji characters inside JSX or HTML markup                                 | warning  |
+| `vibecode.default_font`           | Inter, Geist, or Space Grotesk in tokens or CSS without a rationale marker | warning  |
+| `vibecode.indigo_purple_gradient` | Indigo-to-purple gradient utilities or hex pairs                           | warning  |
+| `vibecode.glassmorphism`          | Backdrop-blur glass panels                                                 | warning  |
+| `vibecode.decorative_blob`        | Blurred radial-gradient orb elements                                       | warning  |
+| `vibecode.sparkle_icon`           | Sparkle glyphs or sparkle icon imports                                     | warning  |
+| `vibecode.checkmark_wall`         | Three or more checkmark bullets in one file                                | warning  |
+| `vibecode.bouncing_cue`           | Bounce-animated arrows or scroll cues                                      | warning  |
+
+A warning identifies a pattern for review, not a proven defect or automatic removal order. The font rationale marker is a `font-rationale:` comment beside the font declaration, pointing at the `DESIGN.md` row.
+
+## Audit Pass
+
+The vibecode audit is a bounded subagent pass with fresh context. Kick it off:
+
+1. After a landing, funnel, or web marketing surface is first built or meaningfully restyled.
+2. Before the landing lane reaches `done`, alongside the `check:landing-funnel` gates.
+3. Inside the design-guru audit whenever `DESIGN.md` or app screens change.
+4. On demand, when a founder or maintainer asks whether a surface "looks AI-generated".
+
+Dispatch prompt:
+
+```text
+Load knowledge/design/vibecoded-tells.md and knowledge/design/audience-derived-identity.md.
+Review <surface paths> against Tier 1 and Tier 2.
+For each tell found, name the file, the tell, and whether DESIGN.md records a derivation.
+Run check:vibecoded-tells and include its output.
+Apply the scoring rule. Return the fixed handoff schema with a pass or fail verdict.
+Propose the smallest state mutation that clears each failure. Do not restyle beyond the findings.
+```
+
+The pass returns the standard handoff headings from `APP_AGENTS.md`. It proposes mutations; the orchestrator integrates them.
+
+## Gates
+
+- `check:vibecoded-tells` runs in the audit pipeline and against generated business repos via `--root`.
+- `check:emotional-design` owns the fake-social-proof trust breaker with its truthfulness proof.
+- `check:landing-funnel` owns the deploy gates a landing must pass; the terms and privacy requirement rides with it.
+- The quality lens ([`quality-lens.md`](./quality-lens.md) §Anti-Generic Checks) applies this list during Design Room review.
+- The anti-generic review in `audience-derived-identity.md` §Gates owns the contextual identity review this file supports.

package/knowledge/engineering/accessibility-readiness.md

@@ -0,0 +1,24 @@
+# Accessibility Readiness
+
+## Purpose
+
+Use this guide to prove that customers can complete the common tasks of the app.
+
+## Required proof
+
+1. List the common tasks and the supported device classes.
+2. Test each task with VoiceOver or TalkBack.
+3. Test large text, contrast, reduced motion, and alternative input where the platform supports it.
+4. Record the build, device, operating system, result, defect, owner, and evidence.
+5. Reconcile the results with the App Store accessibility declarations.
+
+Static analysis does not replace common-task testing. An untested common task is a release blocker.
+
+## Output
+
+Write the results in `engineering/ACCESSIBILITY_READINESS.md`.
+
+## Sources
+
+- [Apple Accessibility Nutrition Labels](https://developer.apple.com/help/app-store-connect/manage-app-accessibility/overview-of-accessibility-nutrition-labels/)
+- [Android core app quality](https://developer.android.com/develop/adaptive-apps/quality-guidelines/core-app-quality)

package/knowledge/engineering/app-agent-roster.md

@@ -0,0 +1,120 @@
+# App-Local Agent Roster
+
+Use this when creating `AGENTS.md`, `CLAUDE.md`, `PROMPTS.md`, `engineering/ENGINEERING_PLAN.md`, builder-ready bundles, or any real app handoff that should continue after bootstrap.
+
+Load `parallel-agent-orchestration.md` and `engineering-orchestration.md` first for orchestration rules. Load `artifact-contracts.md` for accepted file names and handoff structure. Load `onboarding-conversion.md` before assigning onboarding, first-value, paywall, review, analytics, identity, or lifecycle work.
+
+## Required Output
+
+Every real B2C app build or builder-ready package should include:
+
+```text
+AGENTS.md
+CLAUDE.md
+APP_AGENTS.md
+agents/
+  orchestrator.md
+  operator-readiness.md
+  research-strategist.md
+  product-leader.md
+  design-guru.md
+  copy-specialist.md
+  marketing-guru.md
+  launch-surface-producer.md
+  mobile-engineer.md
+  backend-infrastructure-engineer.md
+  accessibility-device-qa.md
+  security-architect.md
+  engineering-leader.md
+  customer-success.md
+```
+
+Use `surfaces/workspace-template/repo-agent-entrypoints/` for the repo-root `AGENTS.md` and `CLAUDE.md`, then use `examples/workspace/business/engineering/app-agent-roster/` for `APP_AGENTS.md` and `agents/`. Install the portable `catalog.json`, `.b2c-launch/runtime.json`, and founder-owned `.b2c-launch/BUSINESS_CONTEXT.md` with them. Refresh managed prompts from the current skill version, preserve replaced prompt bytes for recovery, and never overwrite `BUSINESS_CONTEXT.md`.
+
+## Role Model
+
+The app-local roster is not a replacement for `AGENTS.md`, `product/experience/11-star-experience/11_STAR_EXPERIENCE.md`, `engineering/TECH_SPEC.md`, `DESIGN.md`, `analytics/ANALYTICS.md`, `product/ONBOARDING.md`, or `engineering/PRODUCTION_READINESS.md`. It is a lightweight routing layer for future agents. `AGENTS.md` remains the business-specific canonical guide and must explicitly tell future agents to continue using the `b2c` workflow instead of asking the founder to re-invoke it.
+
+- Orchestrator owns sequencing, source truth, founder-zero business operations, `operations/BUSINESS_ACCESS.md`, its structured ledger, reducer-mediated `state/business-state.json`, orchestration, failure cards, validators, integration, git/release coordination, and final proof.
+- Orchestrator owns Session Continuity: read `AGENTS.md`, durable state, both business/agent operations ledgers, orchestration/readiness/failure docs, and git status; do not rely on chat memory over durable state.
+- Orchestrator assumes beginner founder knowledge. It runs `operator-readiness.md` once at orient,
+  creates standing authority for routine external work, and combines missing access into one handoff.
+- Orchestrator owns the generalized onboarding `ONB-00` through `ONB-22` graph, its single-writer artifact, evidence and architecture joins, canonical IDs, Compound Engineering handoff, cutover, and target-runtime verdict.
+- Every prepared prompt has matching `catalog/roles.ts` and `catalog/operators.ts` records. A prompt that cannot be selected by the graph is a validation failure.
+- Dispatch nesting is fixed: `AGENTS.md` → `.b2c-launch/BUSINESS_CONTEXT.md` → `APP_AGENTS.md` → specialist prompt → mandatory workflow references → matching role context-pack references → matching installed skills → current tool schemas. The always-on founder-language pack is present for every role. The worker returns an exact knowledge receipt. On the scheduled headless path (`kernel/session/run.ts`) the executor verifies the receipt per file (sha256, fail-closed) before the output reconciles; on the interactive subagent path the orchestrating session checks the returned receipt against the brief's load list itself before accepting the patch — no code enforces it there, so a missing or mismatched receipt is grounds to reject the output, not a formality.
+- Research strategist owns source quality, customer language, market/category evidence, competitor evidence, and research-to-decision traceability.
+- Product leader acts as the product and UX expert for ICP, scope, core loop, onboarding evidence joins, first value, activation, effort, question usefulness, canonical journey, retention, interaction behavior, and evidence-to-product traceability.
+- Design guru acts as the visual-design expert for hierarchy, composition, design-system expression, authorized Onbo Hub and 60fps evidence packets, complete screen/control states, actual visual and interactive proofs, screenshots, icons, imagery, and motion.
+- Copy specialist owns product copy, conversion copy, brand voice, comprehension, customer language, and claim discipline.
+- Marketing guru acts as the marketing and growth expert for positioning, ASO, GEO/SEO, acquisition, lifecycle, conversion, reviews, channel learning, acquisition-message continuity, and competitor review evidence.
+- Launch surface producer builds the local landing site after design acceptance. This role also keeps public surfaces synchronized with app changes.
+- Mobile engineer owns iOS and Android architecture, implementation, performance, platform behavior, and focused mobile tests.
+- Backend and infrastructure engineer owns data, API, auth, jobs, deployment, observability, and provider integration.
+- Accessibility and device QA specialist owns assistive-technology checks, device coverage, locale and screen stress, and real-flow evidence.
+- Security architect acts as the security and release reviewer for threat analysis, platform hardening, privacy controls, onboarding data minimization, identity and redemption protection, signing, store requirements, one-time transformation security, supply-chain checks, and readiness evidence.
+- Engineering leader owns cross-stack integration review, plan coherence, onboarding state and analytics contracts, provider and policy integration, hard cutover, and unresolved frontend/backend/provider seams.
+- Customer success owns support, FAQ/help, privacy/delete/refund/restore paths, competitor complaint root-cause coding, review suppression, lifecycle recovery, review responses, and feedback triage.
+
+## Onboarding Graph Dispatch
+
+When the request creates, audits, standardizes, replaces, or materially changes onboarding, the orchestrator loads `knowledge/experience/onboarding-conversion.md` and records the nested graph in `product/ONBOARDING.md`.
+
+- Execute `ONB-00` through `ONB-22`.
+- Fan out only read-only evidence or disjoint implementation packets.
+- Join current guidance, competitor negative and positive reviews, authorized Onbo Hub flows, internal B2C doctrine, provider and policy capabilities, and 60fps motion references before architecture or screen design.
+- Keep first value rendered, first value engaged, activation, retention, monetization, review eligibility, and onboarding completion distinct.
+- Require canonical identity, journey, entitlement, analytics, experiment, review, permission, and lifecycle state.
+- Require stable screen and control IDs, exact button behavior, complete paywall and error states, actual high-fidelity designs, and an interactive prototype.
+- Earn review eligibility after meaningful value, but request through the native platform API outside first-run onboarding at a later natural success.
+- Route the accepted graph to Compound Engineering planning and implementation.
+- In replacement mode, preserve durable user value through an isolated one-time transformation, hard-cut to the new system, delete all replaced runtime and migration tooling, and run `check-onboarding-graph.ts`.
+
+The orchestrator remains the single writer for `product/ONBOARDING.md`, state, canonical IDs, pricing, provider mutations, migration and cutover decisions, and the final verdict.
+
+## Subagent Audit Pattern
+
+For non-trivial launches, select the specialists that match ready work. Run independent read-only reviews in parallel. Keep edit scopes disjoint. Give each role only the bounded source set in its prompt.
+
+- Product leader reviews `PRODUCT.md`, `product/experience/11-star-experience/11_STAR_EXPERIENCE.md`, `state/LAUNCH_TRACE.md`, `product/ONBOARDING.md`, first value, activation, effort, question usefulness, journey, and retention assumptions.
+- Marketing guru reviews `strategy/RESEARCH.md`, onboarding competitor review evidence, acquisition-message continuity, `growth/LAUNCH_NARRATIVE.md`, `store/STORE_CONSOLE.md`, `GEO_SEO.md`, `growth/PAID_UA.md`, `growth/VIRAL_GROWTH.md`, `growth/UGC_PLAYBOOK.md`, `growth/FASTLANE_OPS.md`, and attribution-channel learning.
+- Design guru reviews the authorized Onbo Hub atlas, 60fps motion register, `DESIGN.md`, `design/design-room.html`, `product/experience/11-star-experience/11-star-experience.html`, `product/onboarding.html`, actual prototype, critical screen states, screenshots, accessibility, and visual consistency.
+- Launch surface producer uses `initial-build` mode when `DESIGN.md` is accepted. Use `impact-audit` mode before each accepted app slice merges.
+- Orchestrator uses `operator-readiness.md` before build work and before an unattended resume with stale capabilities. This is a serialized provider prompt, not a specialist mutation lane.
+- Engineering leader reviews `product/ONBOARDING.md`, `engineering/TECH_SPEC.md`, `engineering/ENGINEERING_PLAN.md`, `store/APPLE_SIGNING.md`, canonical state and analytics, provider and policy contracts, cutover and deletion manifest, signing/release readiness, and test coverage.
+- Security architect reviews onboarding data and threat contracts plus `trust/SECURITY.md`, `trust/security-review.html`, `trust/secrets/SECRETS.md`, `engineering/TECH_SPEC.md`, `revenue/REVENUE_OPS.md`, `analytics/ANALYTICS.md`, `growth/EMAIL_OPS.md`, `trust/PRIVACY.md`, `store/APPLE_SIGNING.md`, `engineering/PRODUCTION_READINESS.md`, scanner/review evidence, app-integrity posture, and accepted risks.
+- Customer success reviews competitor complaint root causes, review eligibility and suppression, `trust/PRIVACY.md`, `trust/TERMS.md`, support routes, refund/restore/delete paths, lifecycle email, FAQ, and review-response readiness.
+- Engineering leader and orchestrator review `trust/secrets/SECRETS.md` for each new secret, new env vars, Doppler/provider routing, `doppler run --` command wrappers, service token/provider-integration plan, CI/deploy injection, `.env.example` names-only coverage, and public-bundle safety.
+- Orchestrator merges findings, resolves conflicts, updates source-of-truth docs, updates `operations/ORCHESTRATION.md`, commits typed state patches through the reducer to `state/business-state.json`, runs `check-onboarding-graph.ts`, and records proof or blockers in `engineering/PRODUCTION_READINESS.md`.
+
+Specialist agents should review and propose by default. They may implement only when the orchestrator assigns an isolated unit with file paths, acceptance checks, forbidden actions, and a verification method recorded in `operations/ORCHESTRATION.md`. Specialists run headless. They never ask the user or wait mid-run for approval. On missing context, they return "Risks and blockers: needs_context" with the missing item, then stop. They never mutate shared state, stage, commit, spend, change protected pricing/legal/identity fields, or decide a final release. They may apply an approved provider mutation, public artifact, store-media/metadata update, or test-build upload only in an exact assigned workflow with a matching current standing envelope, before-state, and provider read-back.
+
+Every prompt returns the same nine handoff headings. They are: Scope reviewed, Evidence, Findings, Recommendations, Files changed, Validation, Risks and blockers, Proposed state patch, and Knowledge receipt. The orchestrator accepts or rejects the proposed patch and is the only writer of shared state.
+
+## Attribution Audit Gate
+
+The product, engineering, and marketing roles must all check self-reported attribution when onboarding, signup, waitlist, or account creation exists:
+
+- visible "How did you hear about us?" screen appears after the promise/demo but within the first third of onboarding/signup when the question materially supports launch learning
+- source options use stable stored keys instead of display labels
+- `other` includes sanitized free text or a documented follow-up field
+- `attribution_source_selected` includes the stable key and technical context where available
+- PostHog person properties include `self_reported_source`
+- backend/profile storage persists the selected source when identity exists
+- anonymous attribution is reconciled after signup/login
+- tests or live smoke proof show event, person property, and backend/profile write
+
+If any item is missing, do not call attribution wired, complete, or launch-ready. If attribution does not justify delaying first value, defer it or collect it contextually rather than making it a universal fixed screen.
+
+## Acceptance
+
+- `APP_AGENTS.md` points to canonical docs and states the orchestrator is the integration owner.
+- `AGENTS.md` and `CLAUDE.md` are filled for the current business, not copied from this skill repo's maintainer docs.
+- `AGENTS.md` tells future agents to keep using `b2c`, update `state/business-state.json` only through the reducer, and run validators until a founder-only gate.
+- `AGENTS.md`, `CLAUDE.md`, `APP_AGENTS.md`, `.b2c-launch/runtime.json`, `.b2c-launch/BUSINESS_CONTEXT.md`, `catalog.json`, `operations/ORCHESTRATION.md`, and `state/business-state.json` encode the Session Continuity source set and next-action handoff.
+- The orchestrator, specialist prompts, engineering integration prompt, and customer-success prompt exist and remain short enough to be used.
+- The launch-surface prompt gives future agents exact initial-build, impact-audit, bounded-update, and approved-external-apply modes.
+- Each role has clear onboarding graph responsibilities, forbidden actions, founder-only gates, and output shape.
+- The roster gives future agents a clean way to audit and continue the app without duplicating product truth.
+- The orchestrator can prove the onboarding graph joins, actual design proof, analytics contract, provider decisions, hard cutover, and target-runtime result.
+- The orchestrator can show the founder current state through the session digest, keep orchestration decisions inspectable in `operations/ORCHESTRATION.md`, and keep known misses visible as failure cards.
+- The orchestrator can prove business identity, Doppler, account/social access, recovery/2FA ownership, and one-next-action continuity through `operations/BUSINESS_ACCESS.md`, its ledger, and `check:founder-operator`.

package/knowledge/engineering/app-quality.md

@@ -0,0 +1,19 @@
+# App Quality And Vitals
+
+## Purpose
+
+Use this guide to define and prove the mobile release-quality envelope.
+
+## Required proof
+
+Measure crashes, application-not-responding events, startup time, battery use, app size, offline behavior, and adaptive layouts. Test supported device sizes and operating-system versions. Set a release threshold and an owner for each measure. Record evidence from the build or the production provider.
+
+Keep a third-party SDK inventory. Record the SDK owner, version, permissions, data use, privacy manifest, update route, and removal route. Include the SDK inventory in software-supply-chain review.
+
+## Output
+
+Write the results in `engineering/APP_QUALITY.md`.
+
+## Source
+
+- [Android vitals](https://developer.android.com/topic/performance/vitals/index.html)

package/knowledge/engineering/backend-data-contract.md

@@ -0,0 +1,187 @@
+# Backend Data Contract
+
+Every real app build needs a backend-agnostic data contract before implementation hardens: the schema, the authorization model, the migration story, and the environment layout, written down in terms the product owns rather than terms a provider rents out. Without it, the build silently couples to whichever backend the archetype prompt defaulted to — usually Supabase — and a later founder preference for Firebase or a custom backend becomes a rewrite instead of a route change. The contract lives in `engineering/TECH_SPEC.md` under a `## Data Contract` section; this reference defines how to fill that section for each backend route and how to prove it.
+
+## Contents
+
+- When To Load
+- Backend Selection
+- Data Model
+- Authorization Model
+- Migrations And Environments
+- API Surface And Client Sync
+- Archetype Pack Adaptation
+- Proof
+- Artifact Contract
+- Founder-Only Gates
+- Anti-Patterns
+
+## When To Load
+
+Load this reference:
+
+- Before writing the data model or API sections of `engineering/TECH_SPEC.md`.
+- Before running any schema or auth prompt from an archetype pack (`social-network.md`, `ai-chat-companion.md`) — the packs assume Supabase and must be adapted first if the route differs.
+- When the founder asks for Firebase or a custom backend instead of the Supabase default, or questions the backend choice at any point.
+- Before claiming the engineering lane done; the contract and its proof are part of done status (`engineering-orchestration.md`).
+- When auditing an existing app's data layer for drift, untested authorization, or undocumented backend coupling.
+
+## Backend Selection
+
+Pick one route, record it, and never silently substitute another mid-build.
+
+- **Supabase (default route).** Postgres + Auth + Realtime + Storage. This is what the shipped archetype prompt packs target, so the schema/RLS prompts run with minimal adaptation. Choose it when the product fits relational data, the team has no contrary preference, and speed-to-working-multi-user-product matters most.
+- **Firebase.** Firestore + Auth + Cloud Functions + Storage. Choose it when the founder or team already prefers it, or when realtime-document sync (presence, collaborative state, fan-out listeners) fits the product better than relational queries. Accept the trade: no relational joins, no SQL migrations, security rules instead of RLS.
+- **Custom backend.** Node or Python service + Postgres. Choose it when the product needs server logic the BaaS models fight — heavy background processing, multi-step transactions across entities, third-party orchestration, or an authorization model too conditional for declarative rules.
+
+Record the selection in `engineering/TECH_SPEC.md` under "Backend Selection" with at least:
+
+- route: `supabase` | `firebase` | `custom`
+- reason: one or two sentences tied to the product, not to habit
+- decided by / date: founder confirmation or the default-with-no-objection note
+- what would change the decision: the named condition under which the route gets revisited
+
+Mirror the provider status in `state/business-state.json` and the decision in `strategy/TOOL_DECISIONS.md` when that file exists. A selection without a reason is the backend-by-default anti-pattern, not a decision.
+
+Switching backends after implementation starts is a **change-cascade event** ([`change-cascade.md`](../process/change-cascade.md)): re-walk the data contract, the archetype prompt adaptations, `SECRETS.md`, `trust/SECURITY.md`, and every client that touches data. Switching is also a founder-only gate — never migrate routes on inference.
+
+## Data Model
+
+Define the model in product terms first; map it to tables or collections second. The "Data Model" sub-section carries one row per entity:
+
+| Entity  | Owner | Key fields                   | Relationships | Retention                       | PII class    |
+| ------- | ----- | ---------------------------- | ------------- | ------------------------------- | ------------ |
+| profile | user  | display name, avatar path    | 1:1 auth user | hard-delete on account deletion | PII          |
+| post    | user  | body, media path, created_at | N:1 profile   | soft-delete, 30-day purge       | user content |
+
+Rules for filling it:
+
+- **Entities and ownership.** List every entity, its owning user (or system ownership), and the fields it carries. Every row/document that holds user data must name its owner column or path — authorization depends on it.
+- **Relationships.** Name each relationship and its cardinality. On Supabase/custom this becomes foreign keys; on Firebase it becomes subcollections or reference fields plus the denormalization needed to query without joins. Write the relationship down once, route-agnostically, then note the route mapping.
+- **Retention and deletion.** For each entity, decide soft-delete (tombstone + purge window) or hard-delete, and map the choice to the account-deletion requirement: when a user deletes their account, the data layer must actually erase or anonymize their data on every entity, not just hide it in the UI. Cross-check `privacy-terms.md` — the privacy policy's deletion promise and the data model's deletion path must be the same fact.
+- **PII classification.** Tag each field as PII, sensitive, or operational. This classification feeds `trust/SECURITY.md` (what needs encryption, access logging, and minimization) and the store privacy disclosures via `privacy-terms.md`.
+
+## Authorization Model
+
+Authorization is part of the contract, not an implementation detail. Write a single authorization matrix — entity by entity: who can create, read, update, delete — in the "Authorization Model" sub-section:
+
+| Entity  | Create                       | Read                                             | Update     | Delete     |
+| ------- | ---------------------------- | ------------------------------------------------ | ---------- | ---------- |
+| post    | authenticated user (as self) | any authenticated user; public if feed is public | owner only | owner only |
+| message | conversation member          | conversation members only                        | owner only | owner only |
+
+Then express the same matrix in the selected route's enforcement mechanism, and name that mechanism explicitly in the sub-section:
+
+- **Supabase:** Postgres Row Level Security policies. Every table gets RLS enabled and explicit policies; a table without RLS is publicly writable through the anon key.
+- **Firebase:** Firestore security rules. Every collection and subcollection gets match blocks with explicit allow conditions; storage buckets get their own rules.
+- **Custom:** middleware authorization. Every endpoint passes through an authz layer that checks ownership/role before the handler runs; no handler trusts the client's claim of identity.
+
+Rules for every route:
+
+- **Deny by default.** Start from "no access" and grant explicitly. Never ship permissive defaults intending to tighten later.
+- **Storage buckets are private by default.** Every storage bucket (Supabase Storage, Firebase Cloud Storage, or a custom object store) starts private with no public-read grant; serve files only through storage policies/security rules that match the authorization matrix, or through short-lived signed URLs. A bucket flipped to public — even "just for now" — is a Tier 1 legal/privacy risk (`privacy-terms.md` §7, risk 6), not a convenience; record the bucket's access mode in `engineering/TECH_SPEC.md` and `trust/SECURITY.md`.
+- **Every table/collection gets an owner, read, and write rule** derived from the matrix. If an entity has no sensible rule, the data model is wrong — fix it there.
+- **Service-role and admin keys never ship in clients.** The Supabase service-role key, Firebase Admin SDK credentials, and custom-backend admin tokens are server-only secrets routed per [`secrets-management.md`](../operations/secrets-management.md). Client builds get only publishable/anon keys, and those keys must be safe precisely because the authorization rules hold.
+- **Untested rules are a launch blocker.** Per `security-release-hardening.md`, RLS policies and security rules that have never been exercised by a test count as absent. See Proof below.
+
+## Migrations And Environments
+
+The "Migrations And Environments" sub-section must name the migration tool, the environment map, and the backup posture. Fill it as follows.
+
+- **Migration tool per route.** Supabase: `supabase` CLI migrations, committed under `supabase/migrations/`, applied in order; never mutate production schema through a dashboard without a corresponding migration file. Firebase: Firestore has no schema migrations — document a data-shape version per collection instead (a `schemaVersion` field or documented shape changelog) plus a backfill plan for shape changes. Custom: pick and name a migration tool (e.g. Prisma Migrate, Alembic, node-pg-migrate) in the contract; "raw SQL applied by hand" is not a migration story.
+- **Environment separation.** Maintain distinct dev, staging, and production backends (separate Supabase projects, Firebase projects, or database instances). Never point a dev client at production data. Record the environment map in `engineering/TECH_SPEC.md` and the per-environment secret locations in `SECRETS.md`.
+- **Secrets.** All connection strings, keys, and tokens route through Doppler (or the founder-approved alternative) per `secrets-management.md` — one config per environment, `doppler run --` wrappers in commands, no raw values in docs or proofs.
+- **Seed data and fixtures.** Ship a seed script that populates a fresh environment with enough realistic data to exercise the core loop and the authorization matrix (at least two distinct users plus anonymous). Tests and demos run against seeded environments, never production.
+- **Backup and restore posture.** Record what the route provides (Supabase point-in-time recovery tier, Firebase scheduled exports, custom `pg_dump`/managed snapshots), the retention window, and who can trigger a restore. Production restoration is a founder-only gate.
+
+## API Surface And Client Sync
+
+Define how clients reach the data, per route:
+
+- **Supabase:** PostgREST auto-API for CRUD under RLS, Postgres RPC functions for multi-step server logic, Realtime channels for live updates, Edge Functions for webhooks and third-party calls.
+- **Firebase:** direct Firestore SDK reads/writes under security rules, snapshot listeners for realtime, Cloud Functions (callable + HTTPS) for server logic and webhooks.
+- **Custom:** an explicit REST (or RPC) API with versioned routes; realtime via WebSocket or server-sent events only if the product needs it — do not build a realtime layer speculatively.
+
+Mobile-client considerations apply on every route:
+
+- **Offline and optimistic UI.** Decide per surface whether writes are optimistic with rollback, queued offline, or online-only — and record it; the 11-star core loop usually demands optimistic writes on the primary action.
+- **Token refresh on native clients.** Sessions outlive app launches; the client must refresh tokens silently and recover from refresh failure without dumping the user to login mid-action. Test the expired-token path explicitly.
+- **Pagination.** Every list the product can grow unbounded gets cursor/keyset pagination (or Firestore query cursors) from day one — never offset pagination on a feed.
+- **Webhooks.** RevenueCat and Stripe webhooks land on a server surface, never in the client: Supabase Edge Functions, Firebase Cloud Functions, or custom API routes. Verify signatures, make handlers idempotent, and reconcile entitlements per `revenue-monetization.md`; set up and prove the endpoint per `provider-state-recipes.md`.
+
+## Archetype Pack Adaptation
+
+## Data Export And Portability
+
+Define a user-data export before launch. List the included entities, file formats, media handling, request route, authentication check, delivery method, retention period, and deletion behavior. Use an open format when practical. Test one complete export and one failed or expired request. Record the owner and the recovery route. The export must match the data inventory and the privacy policy.
+
+## Archetype Pack Adaptation
+
+The shipped archetype prompt packs (`surfaces/starters/social-network`, `surfaces/starters/ai-chat-companion`) assume Supabase. When the founder selects Firebase or a custom backend, **adapt each schema/auth prompt to the selected route before running it** — do not run the Supabase prompts verbatim and patch the output later. Use this parity table when rewriting a prompt:
+
+| Supabase concept (as shipped)      | Firebase equivalent                                                                   | Custom-backend equivalent                         |
+| ---------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| Postgres tables + foreign keys     | Firestore collections/subcollections + reference fields (denormalize for query paths) | Postgres tables + foreign keys (unchanged)        |
+| Row Level Security policies        | Firestore security rules (match blocks per collection)                                | Middleware authz layer per endpoint               |
+| Supabase Auth                      | Firebase Auth                                                                         | Named auth provider/library in the contract       |
+| Realtime channels / subscriptions  | Snapshot listeners                                                                    | WebSocket/SSE layer, only if specified            |
+| Edge Functions                     | Cloud Functions                                                                       | API routes / background workers                   |
+| Storage buckets + storage policies | Cloud Storage + storage security rules                                                | Object storage (e.g. S3-compatible) + signed URLs |
+| `supabase` CLI migrations          | Data-shape versioning + backfill plan                                                 | Named migration tool                              |
+
+For each adapted prompt, keep the product content (entities, the authorization matrix, the core-loop behavior) identical and swap only the route mechanics. The adaptation happens at prompt time, not patch time: rewrite the prompt's schema/RLS/Realtime instructions through the table above, run the adapted prompt, then reconcile the output with the `## Data Contract` section as usual. Record in `state/business-state.json` that the pack was adapted and to which route, so later sessions do not re-run the Supabase originals. New archetype packs should cite this reference from their schema prompts instead of restating route mechanics.
+
+## Proof
+
+The data contract is proven, not prose. Before the engineering lane claims the data layer done:
+
+- **Authorization tests.** For each entity in the matrix, exercise at least: authenticated owner access (allowed), anonymous access (denied unless explicitly public), and other-user access (denied for owner-scoped operations). On Supabase this means RLS tests against a real database; on Firebase, security-rules tests via the rules emulator/test harness; on custom, authz middleware tests. A matrix row with no test is an open hole.
+- **Migration proof.** Apply the full migration history (or, on Firebase, instantiate the documented data shapes) against a fresh environment and confirm the result matches the contract.
+- **Seed proof.** Run the seed script against that fresh environment and confirm the core loop works against seeded data.
+
+Record the commands and evidence paths in `engineering/PRODUCTION_READINESS.md`, and the backend-provider state (docs checked, preflight, validation, fallback) in `operations/PROVIDER_PROOF.md` and `state/business-state.json` per `provider-proof.md`. Evidence means the exact command, its environment, and where the output lives — for example:
+
+```
+authorization proof: npm test -- rls.spec.ts (dev Supabase project, seeded)
+  owner read/write: pass | anon read: denied | other-user update: denied
+migration proof: supabase db reset against fresh local stack — 14 migrations applied clean
+seed proof: doppler run -- npm run seed:dev — core loop exercised as user-a and user-b
+```
+
+Never paste secret values or production data into proofs; reference secret-manager locations per `secrets-management.md`.
+
+## Artifact Contract
+
+`engineering/TECH_SPEC.md` must contain a `## Data Contract` section with these exact sub-section header strings — a deterministic validator greps for them:
+
+- "Backend Selection"
+- "Data Model"
+- "Authorization Model"
+- "Migrations And Environments"
+
+For done-status engineering, additionally:
+
+- "Backend Selection" names one route (Supabase, Firebase, or custom) with a recorded reason.
+- "Authorization Model" names its enforcement mechanism: RLS, security rules, or middleware authz.
+- The Authorization Model states the rules are tested and points at at least one artifact that exists on disk (RLS/security-rules test file, migration, or the proof doc recording the test run). A bare "RLS" in prose fails the done gate.
+
+Validator: `npm run check:backend-contract -- --root . --state state/business-state.json`. Run it before claiming the engineering lane done; a failing run leaves the lane partial with a named blocker (`artifact-contracts.md`).
+
+## Founder-Only Gates
+
+Never perform these on inference; surface them as named founder actions:
+
+- Creating backend accounts/projects or accepting billing (Supabase org/project, Firebase project + Blaze plan, hosting/database accounts for a custom backend).
+- Deleting or restoring production data, including executing account-deletion purges against production.
+- Cross-region or cross-project data moves.
+- Switching the backend route mid-build (and the change cascade that follows).
+
+## Anti-Patterns
+
+- **Backend-by-default.** Supabase chosen by inertia because the archetype prompts say so, with no recorded selection or reason. Two minutes of recorded decision now beats a route migration later.
+- **RLS written but never tested.** Policies or security rules that exist in a migration file but have never been exercised by an authenticated/anonymous/other-user test. Treat as absent; launch blocker per `security-release-hardening.md`.
+- **Public storage bucket.** A bucket or container set to public-read — directly, or through a wildcard storage policy — so any guessed or leaked URL reaches another user's file. Treat exactly like a missing RLS policy: fix before launch, never "harden later."
+- **Service-role key in the client.** Any build where the Supabase service-role key, Firebase Admin credentials, or an admin token reaches a client bundle. Rotate the key, fix the call path, route per `secrets-management.md`.
+- **Supabase prompts against a Firebase decision.** Running the archetype pack's schema/RLS prompts verbatim after the founder selected Firebase or custom, planning to "translate later". Adapt first via the parity table.
+- **Schema drift between environments.** Staging and production schemas that differ with no migration history explaining why — usually from dashboard edits. Every schema change goes through the migration tool or the data-shape changelog.
+- **Account deletion as a UI promise.** A delete-account button that signs the user out or hides their profile while rows/documents persist with no purge path. The deletion path is a data-layer contract item reconciled with `privacy-terms.md`, not a frontend feature.