b2c-app-builder 0.221.39

package/knowledge/operations/resend-email-ops.md

@@ -0,0 +1,339 @@
+# Resend Email Operations
+
+Use this before setting up Resend for transactional email, lifecycle automations, broadcasts, waitlist/contact sync, sender-domain DNS, webhooks, inbound email, unsubscribe handling, or deliverability monitoring.
+
+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.
+
+Load [`paid-tool-routing.md`](paid-tool-routing.md) before replacing Resend account/domain features, broadcasts, automations, webhooks, inbound email, or paid deliverability needs with local email previews, logs, Gmail, Cloudflare Email Routing, or another provider.
+
+## Contents
+
+- Current Sources To Refresh
+- Required Artifact
+- Setup Process
+- Starter Template Pack
+- Verification Checklist
+
+## Current Sources To Refresh
+
+Refresh these docs before implementation because email deliverability, bulk-sender requirements, and Resend features change:
+
+- Resend docs index: `https://resend.com/docs`
+- Resend AI docs index: `https://resend.com/docs/llms.txt`
+- Next.js TypeScript quickstart: `https://resend.com/docs/send-with-nextjs`
+- Send Email API: `https://resend.com/docs/api-reference/emails`
+- Idempotency keys: `https://resend.com/docs/dashboard/emails/idempotency-keys`
+- Domains: `https://resend.com/docs/dashboard/domains/introduction`
+- Cloudflare domain setup: `https://resend.com/docs/dashboard/domains/cloudflare`
+- DMARC: `https://resend.com/docs/dashboard/domains/dmarc`
+- Region selection: `https://resend.com/docs/dashboard/domains/regions`
+- Open/click tracking: `https://resend.com/docs/dashboard/domains/tracking`
+- API keys and key handling: `https://resend.com/docs/dashboard/api-keys/introduction`, `https://resend.com/docs/knowledge-base/how-to-handle-api-keys`
+- Webhooks and verification: `https://resend.com/docs/webhooks/introduction`, `https://resend.com/docs/webhooks/verify-webhooks-requests`
+- Audiences, contacts, topics, and unsubscribe state: `https://resend.com/docs/dashboard/audiences/introduction`, `https://resend.com/docs/dashboard/audiences/contacts`, `https://resend.com/docs/dashboard/topics/introduction`
+- Broadcasts: `https://resend.com/docs/dashboard/broadcasts/introduction`
+- Automations: `https://resend.com/docs/dashboard/automations/introduction`
+- Transactional unsubscribe headers: `https://resend.com/docs/dashboard/emails/add-unsubscribe-to-transactional-emails`
+- Receiving/inbound email: `https://resend.com/docs/dashboard/receiving/introduction`, `https://resend.com/docs/dashboard/receiving/custom-domains`
+- RevenueCat customer entitlements and API docs when support emails mention granted entitlements: `https://www.revenuecat.com/docs/dashboard-and-metrics/customer-history/active-entitlements`, `https://www.revenuecat.com/docs/api-v2`
+
+## Required Artifact
+
+Create `growth/EMAIL_OPS.md` when email is more than a plain waitlist notification, or when Resend is part of the stack.
+
+Must include:
+
+- email purpose map: auth, waitlist confirmation, welcome, onboarding nudges, trial reminders, payment recovery, receipts, product updates, marketing broadcasts, support replies, admin alerts
+- sender map: from address, reply-to, domain/subdomain, purpose, owner, template, environment, and unsubscribe requirement
+- domain/DNS status: sending domain, region, SPF, DKIM, custom return path, tracking subdomain, DMARC, and verification timestamps
+- API key inventory: key name, permission, domain scope, environment variable, deploy target, rotation date, and owner
+- code paths: server-only send wrappers, template locations, idempotency-key strategy, tags/categories, logging, and retry behavior
+- webhook plan: endpoint URL, selected events, signature verification, duplicate handling via `svix-id`, storage table/log path, and alerting
+- audience plan: contacts, properties, segments, topics, broadcast policy, automation triggers, unsubscribe/preference handling
+- inbound/reply plan when used: receiving domain, MX conflict notes, webhook handler, attachment handling, support routing, and retention
+- privacy/legal notes: vendor disclosure, email content retention, tracking, unsubscribe, and data deletion behavior
+- validation log: DNS checks, test send, inbox placement/header checks, webhook replay, unsubscribe test, automation run, broadcast test, and inbound test where relevant
+
+Acceptance:
+
+- Production sends use a verified domain or subdomain, not `resend.dev`.
+- API keys are server-only and scoped to the smallest useful permission.
+- Bounces, complaints/unsubscribes, and webhooks are observable before public traffic.
+- Marketing/lifecycle messages have unsubscribe handling; transactional-only messages are classified intentionally.
+- Email behavior matches `trust/PRIVACY.md`, `trust/TERMS.md`, `analytics/ANALYTICS.md`, `product/ONBOARDING.md`, and `revenue/REVENUE_OPS.md`.
+
+## Setup Process
+
+### 1. Decide Email Architecture
+
+Classify each email:
+
+- **Transactional**: auth codes, magic links, receipts, account-access reset, account deletion confirmations, billing notices, support confirmations.
+- **Lifecycle/product**: welcome, onboarding nudges, trial reminders, abandoned onboarding, payment recovery, win-back, feature education.
+- **Marketing/broadcast**: launch updates, newsletters, promotions, product announcements.
+- **Inbound/support**: replies, forwarded attachments, support requests, human escalation.
+
+Rules:
+
+- Use Resend API/SDK for transactional product email.
+- Use Resend Automations for event-triggered lifecycle sequences when the flow is simple enough to own in Resend.
+- Use Resend Broadcasts with Contacts/Segments/Topics for marketing updates.
+- Use a support inbox/tool for human support unless Resend Inbound is explicitly chosen for routing/automation.
+
+### 2. Domain And DNS
+
+Recommended:
+
+- Use a purpose-specific sending subdomain such as `updates.example.com`, `mail.example.com`, or `notifications.example.com` instead of the root/apex domain.
+- Use separate subdomains when reputation or region needs differ, for example `updates.example.com` for marketing and `notify.example.com` for transactional.
+- Decide data region before creating domains when data residency matters.
+
+Setup:
+
+- Add the sending domain in Resend.
+- Add the required SPF and DKIM DNS records.
+- Use the Cloudflare automatic setup when available, or manually add the records exactly as Resend shows them.
+- If using a custom return path, choose a credible label and record it.
+- Add DMARC after SPF/DKIM verify. Start with `p=none` for monitoring, then move toward `quarantine` or `reject` only after all senders pass.
+- Configure open/click tracking only if the privacy policy and analytics plan cover it. Use a custom tracking subdomain if tracking is enabled.
+
+Do not point root-domain MX records at Resend Inbound unless the founder explicitly intends Resend to receive all mail for that domain. For custom inbound, prefer a subdomain to avoid breaking existing mailboxes or Cloudflare Email Routing.
+
+### 3. API Keys And Secrets
+
+Create separate keys per environment and purpose:
+
+- `development` or `staging`
+- `production-transactional`
+- `production-automation` or `production-broadcast` only if needed
+
+Rules:
+
+- Prefer `sending_access` and domain scoping for app runtime sends.
+- Use `full_access` only for admin automation that truly manages domains, contacts, webhooks, or broadcasts.
+- Store keys in server-side environment variables such as `RESEND_API_KEY`; never expose them to browser code or `NEXT_PUBLIC_*`.
+- Record where the key is stored: Vercel, Cloudflare Workers, Supabase Edge Functions, GitHub Actions secret, local `.env`, or another provider.
+- Rotate stale or unused keys. Resend keys are visible only once and do not auto-expire.
+
+### 4. TypeScript Send Path
+
+Use a server-only wrapper. Keep framework-specific route handlers thin.
+
+```ts
+import { Resend } from "resend";
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+export async function sendWelcomeEmail(input: { userId: string; email: string; firstName?: string }) {
+  return resend.emails.send(
+    {
+      from: "Example <welcome@updates.example.com>",
+      to: [input.email],
+      subject: "Welcome to Example",
+      html: `<p>Welcome${input.firstName ? `, ${input.firstName}` : ""}.</p>`,
+      text: `Welcome${input.firstName ? `, ${input.firstName}` : ""}.`,
+      tags: [{ name: "category", value: "welcome" }],
+    },
+    {
+      idempotencyKey: `welcome/${input.userId}`,
+    },
+  );
+}
+```
+
+Rules:
+
+- Include both `html` and `text` when practical.
+- Use idempotency keys for signup, receipt, account, support, and lifecycle emails that may be retried.
+- Use tags for categories such as `welcome`, `waitlist`, `trial_reminder`, `receipt`, `payment_failed`, `support`, and `admin_alert`.
+- Surface errors to logs/monitoring; do not silently swallow send failures.
+
+### 5. Templates
+
+Choose one template strategy:
+
+- React Email/TSX templates in the product repo.
+- Resend hosted Templates for Automations and non-developer editing.
+- Simple inline HTML/text only for tiny early-stage transactional messages.
+- Starter TypeScript templates from `business/growth/resend/email-templates.ts` when the app needs common support, lifecycle, billing, entitlement, waitlist, or privacy messages quickly.
+
+Every template needs:
+
+- before drafting subject, preview text, or body copy: load `knowledge/words/no-slop-writing.md` — its §7 covers push/lifecycle email subject-line limits specifically; keep the tone `11_STAR_EXPERIENCE.md`/`strategy/BRAND.md` set for this product, not generic transactional-email English
+- subject, preview text where supported, HTML, plain text, sender, reply-to, purpose, owner
+- brand fields and required email-safe design tokens derived from `DESIGN.md`: logo, app name, accent color, text colors, surface/border colors, typography, radius, spacing, max width, logo height, and footer rules
+- experience tone derived from `11_STAR_EXPERIENCE.md`, especially lifecycle copy that should feel like the product remembered the user's goal
+- mobile-safe layout and accessible links/buttons
+- unsubscribe/preference link for non-transactional messages
+- legal footer where marketing or lifecycle messaging requires it
+- test recipient and test-send record
+- tags and idempotency-key strategy for retry-prone messages
+
+### 6. Contacts, Topics, Segments, Broadcasts
+
+Use Contacts for marketing/lifecycle audience state:
+
+- create/update contacts on waitlist signup, account creation, purchase, cancellation, and preference changes
+- use custom properties for attribution source, plan, lifecycle state, country, platform, and onboarding answers only when needed
+- use Segments for internal targeting groups
+- use Topics for user-facing preferences and unsubscribe control
+- label Broadcasts with a Topic whenever possible
+
+Broadcasts and Automations can use Resend unsubscribe URLs. Transactional email does not automatically inherit contact-list unsubscribe handling, so add one-click unsubscribe headers and your own preference endpoint when sending bulk or promotional transactional-like messages.
+
+### 7. Automations
+
+Good launch automations:
+
+- `waitlist.joined` -> confirmation + referral/share reminder
+- `user.created` -> welcome + setup nudge
+- `onboarding.started` without `onboarding.completed` -> resume nudge
+- `trial.started` -> value reminder sequence
+- `trial.expiring` -> renewal reminder
+- `payment.failed` -> billing recovery
+- `subscription.cancelled` -> cancellation confirmation and optional win-back
+
+Rules:
+
+- Trigger Automations from product events that already exist in `analytics/ANALYTICS.md`.
+- Include `{{{RESEND_UNSUBSCRIBE_URL}}}` for non-transactional product and marketing messaging.
+- Monitor Automation runs for `running`, `completed`, `failed`, `cancelled`, and `skipped`.
+- Record where Resend automation state overlaps with PostHog, RevenueCat, Stripe, or your backend so users do not receive duplicate lifecycle emails.
+
+### 7a. Lifecycle Email Visual Assets
+
+Win-back, trial-reminder, and billing-recovery emails can carry Higgsfield-generated images:
+
+- **`hero_banner`** mode — wide email header art (use for top-of-email brand moment).
+- **`lifestyle_scene`** mode — product-in-context body image (use for mid-email engagement shot).
+
+Generate both via the `higgsfield-product-photoshoot` skill. See the **Seasonal restyle Refresh** and **Cheap-First Direction** recipes in `tool-recipes/visual-and-motion-production.md` for the generation workflow; use `--mode hero_banner` or `--mode lifestyle_scene` in the `higgsfield product-photoshoot create` call.
+
+Rules:
+
+- Every prompt must carry DESIGN.md brand tokens (palette, type mood, shapes, texture, banned aesthetics). DESIGN.md tokens are already pulled for email `LaunchEmailBrand.designSystem`; reuse the same token set.
+- Generated images are supporting art only. They must not substitute for truthful real UI or make product claims.
+- Confirm spend with the founder before each photoshoot run per `paid-tool-routing.md`; surface current credit balance.
+- Record every generated asset in `CONTENT_ASSETS.md` with `prompt_brief`, output path, intended email surface (`hero_banner` / `lifestyle_scene`), and approval gate.
+- Founder must approve assets before production sends. The founder approval gate in the Starter Template Pack rules applies here.
+
+### 8. Webhooks
+
+Create a production HTTPS webhook and select the events the product needs:
+
+- delivery: sent, delivered, delivery delayed, bounced, complained
+- engagement: opened/clicked only if tracking is enabled and disclosed
+- contacts/topics/unsubscribe where lifecycle messaging depends on it
+- `email.received` when using Inbound
+- domain/webhook events only for admin observability if useful
+
+TypeScript verification pattern:
+
+```ts
+import { NextRequest, NextResponse } from "next/server";
+import { Resend } from "resend";
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+export async function POST(req: NextRequest) {
+  const payload = await req.text();
+
+  try {
+    const event = resend.webhooks.verify({
+      payload,
+      headers: {
+        id: req.headers.get("svix-id") ?? "",
+        timestamp: req.headers.get("svix-timestamp") ?? "",
+        signature: req.headers.get("svix-signature") ?? "",
+      },
+      webhookSecret: process.env.RESEND_WEBHOOK_SECRET,
+    });
+
+    // Store svix-id before processing to make handling idempotent.
+    // Process event.type with created_at ordering rules if order matters.
+    return NextResponse.json({ received: true });
+  } catch {
+    return new NextResponse("Invalid webhook", { status: 400 });
+  }
+}
+```
+
+Rules:
+
+- Verify against the raw request body.
+- Store processed `svix-id` values because Resend webhooks are at-least-once and may be duplicated.
+- Do not assume event order; use `created_at` if ordering matters.
+- Return 2xx only after the event is durably accepted or safely ignored.
+- Test local webhooks with a tunnel, then deploy and replay from the Resend dashboard.
+
+### 9. Inbound Email
+
+Use Resend Inbound only when the app needs email-as-input, automated reply processing, attachment ingestion, or support routing through code.
+
+Setup:
+
+- Use a Resend-managed `*.resend.app` address for early tests, or a custom inbound subdomain for production.
+- Add the required receiving MX record.
+- Register a webhook for `email.received`.
+- Verify webhook signature and store inbound metadata.
+- Decide attachment size/type handling, PII retention, spam/abuse handling, and human escalation.
+
+If the goal is ordinary support inbox forwarding, Cloudflare Email Routing, Gmail/Workspace, or a support tool may be simpler than Resend Inbound.
+
+### 10. Compliance, Privacy, And Deliverability
+
+Before public traffic:
+
+- Update `trust/PRIVACY.md` with Resend as email processor, email categories, tracking if enabled, and unsubscribe/preference behavior.
+- Update `trust/TERMS.md` or support docs for account/billing/support email expectations where needed.
+- Add unsubscribe links to marketing/lifecycle messages and one-click unsubscribe headers where bulk-sender rules apply.
+- Suppress or stop sending to bounced, complained, deleted, or unsubscribed contacts.
+- Check headers on test emails for SPF, DKIM, and DMARC pass.
+- Monitor Resend Emails, Logs, Webhooks, Contacts, Broadcasts, Automation Runs, and Exports as needed.
+
+## Starter Template Pack
+
+Use `business/growth/resend/email-templates.ts` as the out-of-the-box pack for B2C app launches. Copy it into the product repo when Resend is selected, then adapt brand copy, links, legal footer, support SLAs, `LaunchEmailBrand.designSystem` from the project's canonical `DESIGN.md`, and lifecycle tone from `11_STAR_EXPERIENCE.md`.
+
+Included templates:
+
+- `waitlistConfirmationEmail` - confirms waitlist signup and optional referral link.
+- `supportRequestReceivedEmail` - acknowledges inbound support and sets response expectations.
+- `supportReplyEmail` - wraps human or agent-assisted support replies.
+- `entitlementGrantedEmail` - tells a user that beta/support access was granted.
+- `restorePurchasesHelpEmail` - helps users recover app-store or web purchase access.
+- `paymentFailedEmail` - sends secure billing-recovery instructions.
+- `trialExpiringEmail` - warns before trial conversion or access change.
+- `accountDeletionConfirmedEmail` - confirms privacy/account deletion completion.
+
+Rules:
+
+- Do not ship generic-looking email. `LaunchEmailBrand.designSystem` is required and must be populated from the business design system before production sends. Set `designSystem.source` to `DESIGN.md` or the project-specific design artifact used, and fill every required token group: `colors`, `typography`, `radius`, `spacing`, and `email`.
+- Use email-safe interpretations of design tokens: hex colors, web-safe or hosted font stacks, conservative radii, fixed max width, accessible contrast, and inline styles.
+- Treat the pack as starter implementation, not legal copy. Match `trust/PRIVACY.md`, `trust/TERMS.md`, subscription disclosures, and app-store billing rules before production.
+- For `entitlementGrantedEmail`, verify the RevenueCat grant in dashboard/API proof first. Do not imply that a granted entitlement changes billing, cancels a subscription, creates a paid subscription, or issues a refund.
+- For lifecycle or marketing-like messages, include preference/unsubscribe links and one-click unsubscribe headers when bulk-sender rules apply.
+- For support and account-access messages, keep replies transactional unless marketing or upsell copy is added.
+- Keep API keys and webhook secrets server-only through `SECRETS.md`; never generate sends from browser code.
+- Use Resend tags and idempotency keys for waitlist, support, billing, entitlement, privacy, and lifecycle emails that might be retried.
+
+## Verification Checklist
+
+Record each result in `growth/EMAIL_OPS.md`:
+
+- domain/subdomain verified in Resend
+- SPF and DKIM pass
+- DMARC record exists and current policy is justified
+- optional tracking subdomain verified or deliberately disabled
+- API key works in staging and production, with no browser exposure
+- test transactional email sent to Gmail/iCloud/Outlook where possible
+- idempotency retry does not duplicate a transactional email
+- webhook signature verification succeeds with raw body
+- webhook duplicate handling tested with replay
+- bounce or test failure path recorded
+- contact created/updated with expected properties
+- Topic/unsubscribe behavior tested for Broadcasts/Automations
+- Automation trigger and run status checked
+- Inbound webhook tested if receiving is enabled
+- privacy/terms/vendor inventory updated
+- subject/preview/body copy for each template passes the `no-slop-writing.md` self-check (§6) in the project's brand voice

package/knowledge/operations/secrets-management.md

@@ -0,0 +1,215 @@
+# Secrets Management
+
+Use this before adding API keys, tokens, OAuth credentials, webhook signing secrets, service-account files, store credentials, CI/deploy environment variables, `.env` files, or secret-bearing provider setup. Load `provider-state-recipes.md` when the secret belongs to a third-party service setup.
+
+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.
+
+During broad business setup, load `founder-zero-operator.md` first. Explain Doppler in plain language, ask for only the login/approval step the founder must perform, then let the agent inventory projects/configs, route secret names, run safe proof, and continue. Doppler manages automation secrets; interactive browser passwords/passkeys stay with platform delegation, the founder's password manager, or a founder-authenticated session.
+
+Default to Doppler when the founder has not selected another secret manager. Load [`paid-tool-routing.md`](paid-tool-routing.md) before replacing Doppler or another paid/account-gated secret manager with Apple Keychain, platform secrets, local `.env`, or manual exports.
+
+## Contents
+
+- Live Documentation Gate
+- Required Artifacts
+- Secret Discovery Loop
+- Classification
+- Doppler Workflow
+- Alternatives And Fallbacks
+- Production Readiness Gates
+- Common Failure Modes
+
+## Live Documentation Gate
+
+Refresh current provider docs before installing, configuring, writing commands, creating service tokens, wiring CI/deploy injection, or calling a Doppler setup complete. Prefer Doppler's official docs and `https://docs.doppler.com/llms.txt` over local examples, memory, old transcripts, or prior agent output.
+
+Required Doppler sources:
+
+- Doppler CLI install: `https://docs.doppler.com/docs/install-cli`
+- Doppler CLI guide: `https://docs.doppler.com/docs/cli`
+- Doppler secrets setup guide: `https://docs.doppler.com/docs/secrets-setup-guide`
+- Doppler service tokens: `https://docs.doppler.com/docs/service-tokens`
+- Doppler AI docs index: `https://docs.doppler.com/llms.txt`
+- Target deploy provider docs for secrets: Cloudflare, Vercel, Netlify, Supabase, GitHub Actions, EAS, Xcode Cloud, Firebase, or app-store provider docs as applicable
+
+Record in `SECRETS.md`:
+
+- docs checked date
+- docs URLs used
+- observed install route and CLI version, when available
+- project/config mapping source
+- command differences between live docs, local CLI help, this skill, or old project docs
+- live-environment auth model: service token, provider integration, OIDC, or platform-native secret store
+
+Also record the matching provider state in `state/business-state.json`: docs checked date, required secret names, access route in use (`access_route`), preflight, validation command/proof, fallback limitation, and blocked founder actions.
+
+If current official docs or CLI help cannot be reached, mark setup as `blocked: docs refresh needed` or `provisional: docs unavailable`. Do not invent install, login, service-token, or deploy commands from memory.
+
+## Required Artifacts
+
+Create or update `SECRETS.md` whenever any service in the launch needs a secret or environment variable.
+
+`SECRETS.md` must include:
+
+- selected secret provider: Doppler by default, or founder-approved alternative
+- provider docs basis: docs checked date, official URLs, install route, and observed CLI version when available
+- secret inventory: variable name, service, class, environment, runtime surface, public/server-only status, owner, rotation note, and status
+- Doppler project/config map or alternate provider location for each environment
+- command map: local dev, tests, build, deploy, migrations, webhook replay, store/CLI automation, and support scripts
+- CI/deploy map: where staging and production secrets are injected
+- new-secret routing log: what introduced the secret, where it was stored, which docs/tests were updated, and who owns it
+- blocked founder actions: secrets or account steps the agent cannot complete
+- proof notes: secret-manager location and command evidence, never raw values
+- corresponding `state/business-state.json` provider status for every material provider
+
+Recommended repo files:
+
+- `SECRETS.md`: committed, names and locations only
+- `doppler.yaml`: committed only when it contains non-secret project/config/path hints
+- `.env.example`: committed names only, no values
+- `.env`, `.env.local`, `.env.*.local`, service-account JSON, `.p8`, `.p12`, `.mobileprovision`, raw keys, tokens, and downloaded credential files: ignored or stored outside git
+
+Use `business/trust/secrets/` as a starting point when available.
+
+## Secret Discovery Loop
+
+When a new secret appears during research, setup, or implementation:
+
+1. Stop and classify it before writing code around it.
+2. Add the name to `SECRETS.md` with service, class, environment, runtime surface, owner, and status.
+3. Route it to Doppler or the founder-approved provider before running commands that require it.
+4. Update `.env.example` with the name only when the repo needs a local schema.
+5. Update `AGENTS.md`, `engineering/TECH_SPEC.md`, `engineering/ENGINEERING_PLAN.md`, provider ops docs, and `engineering/PRODUCTION_READINESS.md` if behavior or verification changes.
+6. Update `state/business-state.json`.
+7. Run or record a secret scan before handoff.
+
+Do not leave new secrets as ad hoc shell exports, pasted chat values, committed `.env` values, screenshots, raw logs, or untracked setup steps.
+
+## Classification
+
+Use these classes in `SECRETS.md`:
+
+- `public_client_config`: documented public tokens or IDs safe for client bundles, such as publishable analytics/project tokens when vendor docs say so
+- `server_secret`: API keys, database URLs, admin tokens, private provider keys, and service-role credentials
+- `webhook_signing_secret`: Resend, Stripe, RevenueCat, PostHog, GitHub, or store notification signing secrets
+- `store_credential`: App Store Connect keys, Play service-account JSON, ASC issuer/key IDs, private `.p8` files, signing material, provisioning credentials
+- `oauth_or_refresh_token`: OAuth refresh tokens, social account tokens, connected account sessions
+- `ci_deploy_secret`: deploy tokens, CI service tokens, cloud account tokens, `DOPPLER_TOKEN`
+- `runtime_user_secret`: app user tokens that belong in platform secure storage such as Apple Keychain or Android Keystore
+- `local_operator_secret`: local-only CLI credentials or personal tokens used by the founder/operator
+
+Public does not mean harmless. If a token can write, mutate, impersonate, bill, send email, read private data, or access admin APIs, it is server-only.
+
+## Doppler Config Preflight And Shell Patterns
+
+**Config name preflight (never guess):** Before constructing any `doppler run --project <name> --config <config>` command, resolve the actual config name. Config names are project-specific and do not follow a universal convention — "prod" and "prd" are both common and the wrong one causes a hard error. Resolve in this priority order:
+
+1. Read the project's `SECRETS.md` config map — it is the canonical record.
+2. Read `store/STORE_CONSOLE.md` if it contains Doppler snippets; those snippets are written from a working session.
+3. Run `doppler configs --project <name>` to list all real config names in the project.
+   Never construct a `doppler run` command with a config name sourced from memory, a different project's docs, or a prior session transcript. Record the resolved config name in `SECRETS.md` if it is missing.
+
+**Doppler preflight check:** Run `doppler me` to confirm the local CLI is authenticated and the expected account is active before any secrets work. A missing or wrong account is a silent failure that produces confusing auth errors downstream.
+
+**Env file extraction — never `source`:** Do not run `source` or `.` on `.env` files that contain prose comments, export-less assignments, or multi-line values (such as `.p8` or PEM keys). Shell attempts to execute each line as a command, so a comment line or a value with spaces causes "command not found" errors and may execute unintended commands. Use awk for single-value extraction:
+
+```bash
+VAR=$(awk -F= '/^KEY_NAME=/{print $2}' /path/to/file.env)
+```
+
+For multiline values such as a `.p8` private key, never extract the raw value into a shell variable or print it. Read the file path directly or route through Doppler. Document the extraction command in `SECRETS.md`; do not commit awk/grep extraction snippets that print raw credential values in `store/STORE_CONSOLE.md` or any committed markdown.
+
+**JS template literals inside `doppler run -- bash -lc`:** When a command passed to `doppler run -- bash -lc '...'` contains JavaScript template literals (`${...}`, `` `...` ``), the outer bash shell expands the `${...}` before Doppler injects secrets, causing "bad substitution" or silent empty-string substitution. Use one of these patterns instead:
+
+- Use a single-quoted heredoc to pass a Node script (`doppler run -- node --input-type=module <<'NODE' ... NODE`). Single-quoting the heredoc delimiter prevents bash expansion; Doppler injects environment variables and Node sees them as `process.env.*`.
+- Rewrite the JS template literals as string concatenation before passing to bash.
+- Write the script to a temp file and invoke it: `doppler run -- node /tmp/script.mjs`.
+  Do not nest multi-line JavaScript containing template literals inside a double-quoted or unquoted bash heredoc passed to `doppler run`.
+
+## Doppler Workflow
+
+Local development:
+
+- Refresh the Live Documentation Gate before installation or setup.
+- Verify install with the current official command, usually `doppler --version`, and record the observed version or missing-binary status.
+- If missing and the founder selected Doppler, install from current official docs or ask if global install is not appropriate.
+- Authenticate locally with `doppler login`; this is a founder/operator action when browser login or account access is required.
+- Run `doppler me` to confirm the active account before secrets work.
+- Run `doppler setup` at the repo root or configured app folder. Use `doppler.yaml` only for non-secret project/config/path hints.
+- Before constructing `doppler run --project X --config Y`, verify the config name from `SECRETS.md`, `store/STORE_CONSOLE.md`, or `doppler configs --project X`. Never guess the config name.
+- Run commands as `doppler run -- <command>`, for example `doppler run -- pnpm dev`, `doppler run -- npm test`, or `doppler run -- wrangler deploy`.
+- Use `doppler run --watch -- <command>` only when the plan supports it and the current Doppler plan/docs allow it.
+- For one-off command strings that reference variables, escape variables or use single quotes so the shell does not expand before Doppler injects values.
+- When the command contains JavaScript template literals, use a single-quoted Node heredoc (`doppler run -- node --input-type=module <<'NODE' ... NODE`) instead of passing JS through `bash -lc`.
+
+Secret visibility (masked vs restricted):
+
+- Set automation-consumed secrets with the **default `masked`** visibility (plain `doppler secrets set SECRET_NAME`, no `--visibility` flag).
+- Do **not** use `--visibility restricted` for secrets that automation reads: restricted secrets are invisible to CLI injection (`doppler run --`) and produce errors like "The current authentication does not have access to restricted secrets," forcing every secret to be re-created. Reserve `restricted` for dashboard-/API-only secrets that never need CLI injection.
+- Any config consumed by `wrangler deploy`, Expo, CI, or another `doppler run --` consumer must use `masked`.
+
+wrangler.toml / committed config (never plaintext credentials):
+
+- `wrangler.toml`/`wrangler.json` `[vars]` (and `next.config.js`/`app.json` env blocks) must not contain real credential values (Supabase URL/keys, API keys). Route them through `wrangler secret put` or Doppler-injected env vars and keep `[vars]` for non-secret config only. `check:secrets` scans `.toml`/config files for credential-shaped values; a hit is the `wrangler-toml-credentials-committed` failure card. Audit git history if a credential was ever committed.
+
+Setting and reading:
+
+- Prefer setting secrets through the Doppler dashboard or `doppler secrets set SECRET_NAME` without exposing values in command history or logs.
+- Do not run `doppler secrets get SECRET_NAME --plain` unless absolutely necessary; never paste or print the result into docs, chats, commits, screenshots, or logs.
+- If a secret value is needed and unavailable, mark a founder action instead of inventing a placeholder that may ship.
+
+CI and production:
+
+- Refresh the Doppler service-token docs and target deploy-provider secret docs before writing production instructions.
+- Use Doppler service tokens, provider integrations, or OIDC identities for non-local environments.
+- Service tokens should be read-only where possible and scoped to one project/config.
+- Store `DOPPLER_TOKEN` only in the CI/deploy provider secret store or runtime secret store.
+- Do not use personal tokens or local CLI tokens in live environments.
+- If a service token is rotated, update the provider secret and rerun the verification command.
+
+## Alternatives And Fallbacks
+
+Allowed alternatives after founder confirmation:
+
+- Apple Keychain, Android Keystore, or secure storage for runtime user tokens on device
+- macOS Keychain for local operator-only CLI credentials
+- GitHub Actions secrets, Cloudflare secrets, Vercel/Netlify/Supabase/Firebase secrets, Xcode Cloud secrets, or platform-native secret stores for deploy/runtime
+- `.env.local` or manual shell exports only as a temporary local fallback, recorded as lower confidence in `SECRETS.md` and never committed
+
+Do not treat Apple Keychain as a replacement for server-side secret management. It is appropriate for local machine credentials or app runtime user secrets, not for committed app configuration or cloud production secrets.
+
+## Claude Code Sandbox And Local Secret Files
+
+A `permissions.deny` rule on the Read tool blocks only the Read tool. It does not stop a Bash subprocess from reading the same file. Route `.env`, `.p8`, and service-account files through `sandbox.credentials.files` instead. Give each path as an absolute path, never a glob. Pair that setting with a `PreToolUse` hook on Bash that blocks readers such as `cat`, `head`, `grep`, `base64`, and `cp`. Leave `source .env` alone, so normal local development still works. Record the chosen deny mechanism in `SECRETS.md`.
+
+## Production Readiness Gates
+
+Before beta, store submission, or production launch:
+
+- `SECRETS.md` exists and every secret-bearing service is represented.
+- No raw secret values appear in git, docs, screenshots, logs, or proof artifacts.
+- `.gitignore` blocks local env files and credential artifacts.
+- Local commands that require secrets are documented with `doppler run --` or the approved provider command.
+- CI/deploy/runtime environments have secrets injected from Doppler or an approved provider.
+- Production uses service tokens/provider integrations/OIDC, not personal CLI tokens.
+- Frontend bundles expose only documented public client config.
+- Release/staging builds prove mocks are disabled and secrets are not bundled.
+- Rotation/revocation notes exist for live keys, webhook secrets, social/Fastlane keys, store credentials, and deploy tokens.
+- `state/business-state.json` shows provider status and required secret names without exposing values.
+
+## Common Failure Modes
+
+Flag these aggressively:
+
+- a new `process.env`, `import.meta.env`, `DartDefine`, `xcconfig`, `Info.plist`, GitHub Actions secret, Cloudflare secret, or mobile build setting appears without a `SECRETS.md` update
+- `.env.example` contains real-looking values instead of names or safe placeholders
+- production setup uses a Doppler personal/CLI token instead of a service token, provider integration, or OIDC
+- `doppler secrets get --plain` output is printed into logs or proof
+- a public `NEXT_PUBLIC_`, `PUBLIC_`, `EXPO_PUBLIC_`, or mobile plist value contains a server secret
+- service-account JSON, `.p8`, `.p12`, provisioning files, SSH keys, or OAuth refresh tokens are committed
+- CI/deploy works only from a developer shell because the agent forgot launch-time environment differs from interactive shell
+- `state/business-state.json` says provider setup is done even though `SECRETS.md`, CI injection, or command wrappers are missing
+- `doppler run --config` uses a guessed config name (such as "prod" instead of "prd") without reading `SECRETS.md` or running `doppler configs` first
+- `source` or `.` is used on a `.env` or credential file containing prose, multiline values, or non-POSIX assignment syntax
+- a committed markdown file (`store/STORE_CONSOLE.md` or similar) contains an awk/grep/shell snippet that extracts and prints a raw credential value from a `.env` or `.p8` file
+- JavaScript template literals are nested inside a double-quoted bash heredoc passed to `doppler run -- bash -lc`, causing silent bash expansion before Doppler injection