b2c-app-builder 0.221.39

package/knowledge/process/tool-recipes/growth-and-store-routing.md

@@ -0,0 +1,192 @@
+# Growth And Store Routing
+
+Use current tools and live data whenever possible. Treat this file as workflow, not fixed facts.
+
+Part of the [Tool Recipes](../tool-recipes.md) index. Before using any paid or account-gated tool named below, honor the **Paid Tool Decision Protocol** and **Founder-Only Gates** in that index.
+
+---
+
+## ASO Skill Routing
+
+The reviewed Eronred methods remain subordinate to the accepted research,
+product, design and copy contracts. `ios-screenshots` is not a skill path
+in the reviewed Eronred tree. Resolve a separately installed skill before attributing it
+there. Loading these methods does not select Appeeky, authorize paid queries or
+make upstream conversion statistics local evidence. Use
+[`screenshot-toolchain.md`](../../store/screenshot-toolchain.md) for the screenshot
+story and editor handoff. New upstream features require a reviewed contribution.
+
+Purpose: avoid re-creating specialist ASO work inside B2C App Builder.
+
+Use `aso-store-ops.md` as the router. Load `app-store-listing-prep.md` for Apple listing packets, pricing/privacy/growth surfaces, and `store-console-workflow.md` when the work moves into App Store Connect, Google Play Console, privacy forms, screenshots, or submission. When the runtime exposes ASO skills, delegate:
+
+- `aso-router` and `app-marketing-context` before any broad or ambiguous ASO project
+- `market-pulse`, `market-movers`, `category-positioning`, `competitor-analysis`, and `competitor-tracking` for category, chart, and competitor context
+- `keyword-research`, `metadata-optimization`, `seasonal-aso`, `localization`, and `android-aso` before title/subtitle/keywords/Play copy locks
+- `screenshot-optimization`, `ios-screenshots`, `app-icon-optimization`, `app-preview-video`, and `ab-test-store-listing` before screenshot, App Icon, App Preview, or PPO work
+- `custom-product-pages`, `in-app-events`, `app-store-featured`, and `app-clips` before Apple marketing-surface plans
+- `apple-search-ads`, `ua-campaign`, `attribution-setup`, and `web-to-app-funnel` for paid traffic, CPP routing, SKAN/MMP/deep links, and web-to-app funnels
+- `monetization-strategy`, `paywall-optimization`, and `subscription-lifecycle` for pricing, paywall, trial, churn, and subscription lifecycle work
+- `onboarding-optimization`, `retention-optimization`, and `referral-program` for activation, engagement, and viral loops that shape store claims
+- `review-management`, `rating-prompt-strategy`, `crash-analytics`, and `app-rejection-recovery` for quality loops, ratings/reviews, stability, and resubmission
+- `asc-metrics` and `app-analytics` for first-party performance and dashboards after launch
+- `app-launch`, `creator-ugc-marketing`, and `press-and-pr` for launch calendar, UGC/creator strategy, and press kit consistency
+
+Fallback:
+
+- If the ASO skills are installed but not discoverable in the current runtime, search local skill/plugin directories for the skill name and read its `SKILL.md`.
+- If the Eronred ASO skill set is relevant, refresh `https://github.com/Eronred/aso-skills` and prefer installed or vendored skill docs over memory.
+- If no ASO skill pack is installed, use [`paid-tool-routing.md`](../../operations/paid-tool-routing.md) before replacing paid ASO tooling with AppKittie, public App Store/Play Console research, manual keyword sheets, and the same outputs: context, keyword map, metadata variants, `APP_STORE_LISTING.md`, `store/STORE_CONSOLE.md`, `app-store-listing.html`, `store/store-console.html`, `SCREENSHOTS.md`, launch calendar, and post-launch monitoring loop.
+
+## Paid User Acquisition Routing
+
+Purpose: decide whether the product is ready for a small paid acquisition test before treating ad-channel ideas as a growth plan.
+
+Use `paid-user-acquisition.md` before:
+
+- paid ads, Apple Search Ads, Meta/TikTok/Google campaigns, paid creative tests, or paid-growth readiness claims
+- custom product page campaign routing or web-to-app paid traffic
+- MMP/ad-network SDK decisions, ad-account reporting, or baseline uplift plans
+- using RevenueCat LTV/cohort data to judge CPA, trial conversion, payback, or ROAS
+
+Inputs:
+
+- `PRODUCT.md`, `11_STAR_EXPERIENCE.md`, `CONTENT_ASSETS.md`, `analytics/ANALYTICS.md`, `revenue/REVENUE_OPS.md`, `APP_STORE_LISTING.md`, `state/LAUNCH_TRACE.md`, `trust/PRIVACY.md`, `trust/TERMS.md`
+- RevenueCat LTV/cohort/trial/purchase/entitlement data when available
+- App Store Connect or Play Console baseline metrics
+- ad-channel access and budget approval state
+
+Outputs:
+
+- `PAID_UA.md`
+- `growth/paid-ua-report.csv` when spend is planned or active
+- updated `analytics/ANALYTICS.md`, `revenue/REVENUE_OPS.md`, `CONTENT_ASSETS.md`, `APP_STORE_LISTING.md`, and `state/LAUNCH_TRACE.md`
+
+Rules:
+
+- Start with one channel or document the exception.
+- Do not launch campaigns, connect accounts, install privacy-affecting ad SDKs, or change budgets without founder approval.
+- Do not call installs success unless paywall reach, purchase, entitlement, revenue, and retention quality are visible.
+
+## Viral Growth Loop Routing
+
+Purpose: decide whether the product can grow through built-in sharing, referrals, invite loops, social-comment mechanics, or creator CTAs before treating content as the whole growth plan.
+
+Use `viral-growth-loops.md` before:
+
+- referral unlocks, share-to-unlock mechanics, invite systems, or referral codes
+- viral onboarding/paywall flows and closing-offer mechanics tied to sharing
+- TikTok/Reels/Shorts hooks that depend on users commenting, sharing, tagging, searching, or posting their own results
+- creator CTAs that must map to product rewards, store search, landing links, or self-reported attribution
+- calling a social channel ready from views, likes, or UGC ideas alone
+
+Inputs:
+
+- `PRODUCT.md`, `11_STAR_EXPERIENCE.md`, `product/ONBOARDING.md`, `revenue/REVENUE_OPS.md`, `analytics/ANALYTICS.md`, `state/LAUNCH_TRACE.md`, `trust/PRIVACY.md`, `trust/TERMS.md`
+- AppKittie/XPOZ/review/social evidence for category, platform, creator language, device mix, and content formats
+- real product screens or truthful prototypes that show the shareable result
+
+Outputs:
+
+- `VIRAL_GROWTH.md`
+- `growth/format-lab.csv` or `ugc/script-bank.md`
+- `growth/referral-loop-map.md` when referral/unlock mechanics are non-trivial
+- updated `growth/UGC_PLAYBOOK.md`, `growth/FASTLANE_OPS.md`, `CONTENT_ASSETS.md`, and `analytics/ANALYTICS.md` when content or automation is in scope
+
+Rules:
+
+- Treat UGC as supply and viral growth as the system that converts attention into product actions.
+- Do not force referral/share mechanics without fallback, abuse controls, and policy review.
+- Do not scale from one viral post; wait for repeatable format evidence plus downstream app, paywall, revenue, or retention signal.
+- Ask before creator payments, paid tools, public posting, social account connections, pricing changes, or legal/policy-sensitive incentives.
+
+## UGC Creator Engine Routing
+
+Purpose: decide whether creator-led organic growth is a real channel and, if so, run a Day 0 format-discovery program before scaling or feeding Fastlane.
+
+Use `ugc-creator-engine.md` before:
+
+- TikTok/Reels/Shorts founder-led organic content
+- Sideshift or other creator marketplace work
+- creator sourcing, contracts, payments, or account ownership decisions
+- UGC scripts, shot lists, creator briefs, or tracker artifacts
+- adapting creator videos into ads or Fastlane campaigns
+
+Inputs:
+
+- `PRODUCT.md`, `strategy/BRAND.md`, `DESIGN.md`, `product/ONBOARDING.md`, `LAUNCH.md`, `analytics/ANALYTICS.md`, `revenue/REVENUE_OPS.md`, `trust/PRIVACY.md`, `trust/TERMS.md`
+- AppKittie/XPOZ/review evidence for audience language and competitor creator patterns
+- real app screenshots/recordings from MobAI, Codex Desktop native iOS/XcodeBuildMCP, serve-sim, or approved fallback
+- Higgsfield visuals only as supporting assets constrained by `DESIGN.md`
+
+Outputs:
+
+- `growth/UGC_PLAYBOOK.md`
+- `ugc/creator-list.csv`
+- `ugc/creator-brief.md`
+- `ugc/script-bank.md`
+- `ugc/tracker.csv` or sheet link
+- `ugc/weekly-review.md`
+
+Rules:
+
+- Ask before spending on Sideshift, creator platforms, paid creator tools, or creator payments.
+- Do not start a mature creator program at Day 0. Start with 3-5 creators and founder-written scripts.
+- Do not schedule or post creator content without disclosure, claim review, and founder approval.
+- Treat one viral video as luck; treat 2-3 hits from one structure across creators as the earliest scale signal.
+
+## Fastlane Organic Growth Routing
+
+Purpose: set up Fastlane AI as the post-launch content engine for organic TikTok, Instagram Reels, YouTube Shorts, and any other connected destinations supported in the current workspace.
+
+Use `fastlane-growth-ops.md` after launch approval/public beta or when the user asks for `usefastlane.ai`, Fastlane setup, the Fastlane guide, developer API, Blitz campaigns, content generation, scheduling, or short-form analytics.
+
+Access:
+
+- Fastlane AI is paid/account-gated. If the app, API, workspace, or installed skill is unavailable, use `paid-tool-routing.md` before switching to a manual content calendar, local prompt set, platform-native drafts, or spreadsheet schedule.
+
+Delegate:
+
+- load the installed `usefastlane-ai` skill before API work
+- compare a user-provided Fastlane `SKILL.md` against the installed skill when the user supplies one
+- use current app/docs/API state as source truth because `developers.usefastlane.ai` can be a JavaScript shell
+- use safe reads first: preferences, angles, connections, content, posts, analytics when post IDs exist
+- build `growth/FASTLANE_OPS.md` and `fastlane/` artifacts before generating or scheduling content
+
+Inputs:
+
+- `PRODUCT.md`, `strategy/BRAND.md`, `DESIGN.md`, `LAUNCH.md`, `product/ONBOARDING.md`, `revenue/REVENUE_OPS.md`, `trust/PRIVACY.md`, `trust/TERMS.md`, and `strategy/RESEARCH.md`
+- MobAI screenshots/recordings for real app proof
+- Codex Desktop native iOS/XcodeBuildMCP or serve-sim screenshots/recordings when Apple-platform media proof is available or approved as a fallback
+- Higgsfield assets for design-system constrained hooks, mascots, backgrounds, and motion
+- `growth/UGC_PLAYBOOK.md`, `ugc/script-bank.md`, and creator/post results when a creator-led engine exists
+
+Rules:
+
+- never store or print `FASTLANE_API_KEY`
+- ask before connecting accounts, scheduling, canceling, deleting, changing profiles, or posting publicly
+- treat platform posting limits and account warmup as launch gates
+- QA every generated content item against brand, legal, store, pricing, and product truth before scheduling
+- connect content metrics back to installs, trials, purchases, attribution answers, and product analytics
+
+## GEO/SEO Skill Routing
+
+Purpose: make the public launch funnel discoverable by both traditional search and AI answer engines.
+
+Use `geo-seo.md` as the router. When the runtime exposes GEO skills from the `geo-seo-claude` workflow, delegate:
+
+- `geo` or `geo-audit` for the full GEO+SEO pass
+- `geo-technical` for crawlability, SSR/static rendering, performance, security, and indexability
+- `geo-crawlers` for AI crawler access through `robots.txt`, meta tags, and headers
+- `geo-llmstxt` for `llms.txt` generation or validation
+- `geo-schema` for JSON-LD entity markup
+- `geo-citability` for answer-style sections and citation readiness
+- `geo-content` for E-E-A-T and proof structure
+- `geo-brand-mentions` for entity/authority gaps
+- `geo-platform-optimizer` for ChatGPT, Perplexity, Gemini, Google AI Overviews, and Bing Copilot differences
+- `geo-compare` for monthly before/after tracking
+
+Fallback:
+
+- If the GEO skills are installed but not discoverable in the current runtime, search `.agents/skills`, `.claude/skills`, `.codex/skills`, and plugin caches for the relevant `SKILL.md`.
+- If no GEO skill pack is installed, still produce the minimum launch outputs: metadata, schema, `robots.txt`, `sitemap.xml`, `llms.txt`, AI-crawler access notes, citability notes, and live HTTP checks.

package/knowledge/process/tool-recipes/research-intelligence.md

@@ -0,0 +1,258 @@
+# Research And Market Intelligence
+
+Use current tools and live data whenever possible. Treat this file as workflow, not fixed facts.
+
+Part of the [Tool Recipes](../tool-recipes.md) index. Before using any paid or account-gated tool named below, honor the **Paid Tool Decision Protocol** and **Founder-Only Gates** in that index.
+
+---
+
+## AppKittie App-Store Intelligence
+
+Purpose: choose the market/category by revenue and downloads, then position inside or against it. Also use AppKittie to monitor competitors, ads, creators, screenshots, keywords, reviews, and post-launch deltas.
+
+Access:
+
+- AppKittie is a paid/account-gated intelligence path. If unavailable in the runtime, use [`paid-tool-routing.md`](../../operations/paid-tool-routing.md) before substituting public store research.
+
+Run:
+
+- `search_apps` across 3-5 plausible categories or query clusters
+- top revenue apps, top download apps, trending apps, and fastest growth apps by downloads/revenue/reviews
+- filtered searches for apps with Meta ads, Apple Search Ads, creator partnerships, websites, or contact emails
+- `get_app_detail` for the top 5-10 competitors, including screenshots, IAPs, developer/site/socials, historical downloads/revenue/reviews/ratings, ads, and creator partnerships
+- `get_app_reviews` for 50-300 recent reviews across the most relevant competitors, depending on credit budget
+- `batch_keyword_difficulty` for the candidate name, subtitle, category terms, competitor alternatives, and long-tail pains; use `get_keyword_difficulty` for final deep dives
+- `get_supported_countries` before non-US keyword research
+
+Record:
+
+- monthly downloads and revenue estimates
+- lifetime downloads/revenue where available
+- rating and review count
+- update recency
+- pricing and trial structure
+- in-app purchase tiers
+- app age and growth rate
+- ad presence and creative pattern
+- screenshots and app-store positioning
+- user complaints and feature requests
+- Meta/ASA ad presence and creative patterns
+- creator/influencer partnership signals
+- contact emails, websites, and social links for partnership/press/ads research
+- keyword popularity, difficulty, traffic, and top-ranking apps by country
+
+Decision rule:
+
+- The storefront category is where users already search and spend.
+- The product identity can be a contrarian wedge against that category.
+- If a phrase has no search volume, keep it as brand/category creation, not the only acquisition path.
+- AppKittie data is directional unless first-party; cite it as estimates and pair it with reviews/social evidence.
+
+## Social-Language Research
+
+Purpose: find the words users already use for the pain.
+
+Sources:
+
+- Reddit subreddits around the job-to-be-done and competitor categories
+- TikTok hashtags and creator formats
+- X/Twitter keyword clusters
+- YouTube/creator comments when the concept is creator-led
+
+Preferred local tool:
+
+- Use XPOZ for Reddit, TikTok, X/Twitter, and Instagram social/market-language research when available.
+- Prefer the installed XPOZ MCP/CLI. If only a local CLI exists, resolve its path before use instead of assuming it is on `PATH`.
+- Put global flags before the platform: `xpoz-cli --output json tiktok search_posts ...`
+- Check auth first: `xpoz-cli --output pretty auth status`
+- Useful platforms/methods: `reddit search_posts`, `reddit search_comments`, `reddit get_subreddit_with_posts`, `tiktok search_posts`, `tiktok search_users`, `tiktok get_posts_by_user`, `twitter search_posts`, `twitter count_posts`, `instagram search_posts`, `instagram get_posts_by_user`.
+- For a scored recency brief across those platforms, see Last30days Recency Research below. last30days is not the XPOZ free fallback.
+
+Access:
+
+- XPOZ is a paid/account-gated research path. If auth is missing or the CLI is unavailable, ask before using public search, platform-native browser search, reviews, or founder-provided screenshots as the fallback.
+
+Queries:
+
+- problem phrases from the source spec
+- competitor names plus "quit", "alternative", "too much", "expensive", "worth it"
+- category verbs, not just nouns
+- aspirational phrases and "I wish..." phrases
+- trend containers such as "Sunday reset", "weekly review", "AI coach", "habit tracker", adapted to the current product
+
+Record:
+
+- verbatim language
+- emotional register
+- repeated failure modes
+- screenshots/posts worth citing
+- social formats that can become ads or organic content
+
+Rules:
+
+- Do not overfit to one viral post.
+- Separate broad cultural trend from app-store search behavior.
+- Keep sensitive or copyrighted material summarized unless the source allows direct quotation.
+- Prefer creator handles, subreddits, compact hashtags, and competitor names over broad generic phrases; broad XPOZ queries are often noisy.
+- Record query, platform, date, result URL/post ID/creator handle where possible, and how the evidence changed positioning or copy.
+
+## Last30days Recency Research
+
+Purpose: collect what people are saying about a topic, person, product, or comparison inside a dated recency window (default last 30 days), ranked by engagement rather than search-engine rank.
+
+This method adapts selected procedures from the MIT-licensed `mvanhorn/last30days-skill` host skill. It does not copy that skill, vendor its Python engine, or add a B2C App Builder capability, provider, or recipe. Host installation stays founder-approved and outside the business workspace.
+
+When to use:
+
+- Recent community consensus, objections, comparisons, and "what moved this month" questions
+- Person, company, or product recency before a competitive brief
+- Discovery of currently discussed topics when the host skill is already installed
+
+When not to use:
+
+- App-store economics, downloads, revenue estimates, or keyword difficulty (AppKittie)
+- Targeted per-platform social-language queries XPOZ already covers
+- Competitor page, pricing, policy, or funnel extraction (Firecrawl)
+- As a silent substitute for XPOZ, AppKittie, or Firecrawl
+- As a generic "last 30 days of X" web-search essay when the engine did not run
+
+Access:
+
+- The host skill name is `last30days`. Citing this method does not require installing it.
+- Reddit, Hacker News, Polymarket, and GitHub can return evidence without keys when the engine is present.
+- X, TikTok, Instagram, YouTube transcripts, and similar sources need host binaries or keys. Treat those as founder-gated secrets or spend. Do not run the upstream setup wizard, browser-cookie capture, CLI auto-install, or publish path from a business session.
+- The engine needs Python 3.12 or newer on the host. Missing Python is a host blocker, not a reason to improvise an equivalent brief.
+- Do not also add the Claude Code marketplace plugin when `npx skills add` already installed the skill. The two installs duplicate.
+
+Run, when the skill is already installed:
+
+- Load the installed `last30days` skill and follow its engine. Do not invent a parallel research prompt.
+- Resolve people, repositories, and communities before a keyword sweep.
+- Record source coverage honestly. A failed, unconfigured, rate-limited, or skipped source is not proof that the platform was quiet.
+- In a registered planning workspace, checkpoint through `research-lookup` and `research-record` before and after the authorized dispatch.
+
+Record:
+
+- topic, recency window, run date, and installed skill version when known
+- sources that returned evidence versus sources that failed or were skipped
+- engagement-backed quotes with URLs, post IDs, or equivalent resolvable references
+- what the brief changed in positioning, copy, or the spec
+
+Rules:
+
+- Engine output is an observation, not accepted product truth and not permission to ship a claim.
+- Partial coverage stays partial. Do not fill gaps with unsourced narrative.
+- Keep the upstream output contract (badges, engine footers, host formatting laws) inside the host skill. B2C App Builder still requires dated, resolvable sources in `strategy/RESEARCH.md`.
+- Do not copy `SKILL.md` into the business or into this repository.
+
+## Firecrawl Web Intelligence
+
+Purpose: inspect public web surfaces that AppKittie and XPOZ do not cover well: competitor landing pages, pricing pages, docs, help centers, policy pages, blog/SEO content, feature pages, and funnel claims.
+
+Use Firecrawl MCP/API when available:
+
+- `firecrawl_search` for broad web discovery with scraped result content
+- `firecrawl_map` to discover URLs on a competitor/domain and find pricing, terms, support, blog, FAQ, or docs pages
+- `firecrawl_scrape` for a single page when the URL is known
+- `firecrawl_crawl` for multi-page competitor/site audits
+- `firecrawl_extract` for structured fields such as pricing, plans, claims, CTAs, features, testimonials, integrations, and policy commitments
+- batch scrape when comparing several competitors or policy pages
+
+Fallback:
+
+- Firecrawl is a paid/account-gated crawler. If unavailable or blocked, use `paid-tool-routing.md` before switching to ordinary web search, `curl`, browser snapshots, `sitemap.xml`, `robots.txt`, or manual page notes.
+
+Record:
+
+- source URL, crawl date, page type, extracted facts, claims copied into product/marketing, and claims rejected as unsupported
+- competitor pricing and plan names
+- funnel steps and CTAs
+- support/privacy/contact/deletion pages
+- SEO/GEO content patterns: FAQ, schema, blog topics, `llms.txt`, sitemap, and robots behavior
+
+Rules:
+
+- Respect robots, login walls, paywalls, and terms. Do not bypass access controls.
+- Use Firecrawl for public web evidence, not for App Store intelligence where AppKittie/ASO tools are stronger.
+- Do not rely on Firecrawl metadata extraction alone for schema/security checks; verify important items directly on the live page when launching.
+
+## Refero UX Pattern Research
+
+Purpose: ground web and mobile UX decisions in shipped product screens, styles, and flows before building app screens, onboarding, paywalls, web funnels, settings, support, and legal/account flows.
+
+Current docs basis to refresh at runtime:
+
+- docs index: `https://doc.refero.design/llms.txt`
+- MCP server URL: `https://api.refero.design/mcp`
+- Getting Started, Tools, Data Model, Examples, and Refero Skill pages
+
+Access:
+
+- Refero is a paid/account-gated design research path. Current docs say Refero Pro is required for MCP use and auth can be OAuth or an Authorization Bearer token.
+- If Refero is not available in the runtime, load `paid-tool-routing.md` and ask before using the bundled baseline pattern pack, public inspiration galleries, Page Flows/UI Sources-style public references, app-store screenshots, or founder-provided examples.
+
+Use the current MCP tool names:
+
+- `refero_search_styles` for visual direction, typography, surfaces, spacing, and design-system inspiration.
+- `refero_get_style` for full design guidance after choosing style candidates.
+- `refero_search_screens` with `platform: "web"` or `platform: "ios"` for concrete UI patterns, components, copy hierarchy, and state handling.
+- `refero_get_screen` for detailed screen metadata.
+- `refero_get_similar_screens` to expand from one strong reference.
+- `refero_get_screen_image` only when metadata is not enough and visual inspection is required.
+- `refero_search_flows` with `platform: "web"` or `platform: "ios"` for onboarding, signup, checkout, cancellation, upgrade, account deletion, password reset, permissions, and settings changes.
+- `refero_get_flow` for full journey logic, step goals, actions, system responses, and related queries.
+- Current Refero docs list `web` and `ios` for screen/flow platform filters. For Android launches, use Refero iOS/mobile findings only as journey evidence, then adapt to Android-native controls, permissions, billing, and device screenshots before marking Android UX ready.
+
+Research packet:
+
+- 3-5 styles for the brand/design direction, with one primary and 1-2 secondary influences.
+- 5-10 screens for each critical surface family: onboarding, paywall, pricing, restore, settings/account, support/privacy, empty/error/offline, referral/share, search/filter.
+- 2-4 flows for each critical journey: onboarding, purchase/upgrade, cancellation/retention, restore purchases, account deletion, password reset or login recovery, and permission requests when applicable.
+- A `UX_PATTERNS.md` source ledger with query, platform, selected records, observed pattern, adopted decision, rejected decisions, and caveats.
+- A `ux-patterns.html` or `design/design-room.html` section rendering pattern inventory, flow maps, state matrix, and bug traps.
+
+Rules:
+
+- Use Refero as research ingredients, not a template library to copy.
+- Preserve the onboarding conversion playbook unless the user explicitly approves a named experiment.
+- Do not commit paid Refero screenshots unless licensing/permission is clear; summarize metadata and link source records instead.
+- Pair Refero findings with product trace rows, analytics events, accessibility checks, and implementation state matrices.
+- Record free fallback approval and limitations in `strategy/TOOL_DECISIONS.md` when Refero is unavailable.
+
+## Name And Keyword Collision
+
+Check:
+
+- App Store search and exact title collisions
+- high-revenue apps/games using the term
+- generic utility apps that own the keyword
+- domain availability
+- trademark obvious conflicts
+- social handle availability when relevant
+- pronunciation and "did you do your ___?" usability
+
+Decision rule:
+
+- A beautiful name that is invisible in App Store search can still win if the brand has another acquisition path, but the launch dossier must compensate.
+- Do not lock a name until ASO collision and domain options are known.
+
+## Planning checkpoints and restart
+
+In a registered planning workspace, use `b2c research-lookup --workspace ID --query QUERY.json --max-age SECONDS --json`
+before collecting the same provider observation. The query names the provider version, connection reference,
+operation and non-secret semantic parameters. Read the exact public input schema; do not store credentials.
+
+Use `b2c research-record --workspace ID --revision REVISION --observation OBSERVATION.json --json`
+to save a pending query before its authorized external dispatch. Immediately checkpoint the actual result
+as observed, failed or uncertain. An observed record needs a timestamp and resolvable source references.
+Keep useful evidence and sampling limitations in the bounded summary and linked workspace artifacts.
+The record is a source observation, not accepted proof or a permission grant.
+
+On restart, inspect the saved research-query summaries in business status/plan. Reuse a matching current
+observation, explicitly refresh an expired one, and reconcile pending or uncertain provider requests
+before replay. Recording a local pending intent does not prove the external call occurred; readback
+or an explicit reconciliation is necessary when the process stopped between those steps. Do not infer
+that a changed query string represents a new research need. Search the existing source ledger first.
+
+This checkpoint route is for planning before runtime initialization. Once initialized, existing executor
+attempts and receipts remain the execution owner. Do not create a competing run-state file.

package/knowledge/process/tool-recipes/revenue-email-analytics.md

@@ -0,0 +1,101 @@
+# Revenue, Email, And Analytics Routing
+
+Use current tools and live data whenever possible. Treat this file as workflow, not fixed facts.
+
+Part of the [Tool Recipes](../tool-recipes.md) index. Before using any paid or account-gated tool named below, honor the **Paid Tool Decision Protocol** and **Founder-Only Gates** in that index.
+
+---
+
+## Revenue And Monetization Routing
+
+Purpose: set up purchase infrastructure without confusing payment success with app entitlement access.
+
+Use `revenue-monetization.md` as the router. Delegate to local skills when available:
+
+- `setup-revenuecat` for initial RevenueCat project, `premium` entitlement, and default offering scaffold.
+- `stripe-best-practices` before Stripe Checkout, Payment Links, Billing, Customer Portal, webhooks, or tax decisions.
+- ASO `monetization-strategy`, `subscription-lifecycle`, and `retention-optimization` for pricing, paywall timing, churn, and lifecycle loops.
+- `setup-posthog` once the product repo exists and purchase/subscription events need validation.
+- `setup-supabase` if the funnel or backend needs accounts, waitlist, referrals, or subscription projection storage.
+- `resend-email-ops.md` before subscription lifecycle emails, payment recovery, receipts, trial reminders, or billing-support notifications.
+
+Rules:
+
+- RevenueCat should be the entitlement source of truth for B2C mobile subscriptions unless the project explicitly chooses a different architecture.
+- Stripe may process web payments, but web payment success must be mapped into RevenueCat entitlement or backend access before launch-ready.
+- App Store/Google Play product setup, web billing, pricing, taxes, subscription terms, and live checkout are founder-only gates.
+- Use sandbox/Test Store first; do not publish production purchase links or live prices until validation passes and the founder approves.
+- RevenueCat, Stripe, tax, and store-account features can be paid/account-gated. Use [`paid-tool-routing.md`](../../operations/paid-tool-routing.md) before replacing provider setup with local mocks or free-tier planning, and never call mocks live entitlement proof.
+
+### Recipe: RevenueCat Economics Pull
+
+Purpose: get the revenue numbers out of the dashboard and into decisions on a fixed cadence — the offering/entitlement probe (`probe:revenuecat`) proves the plumbing works, this recipe reads what flows through it. Run it before every kill-or-scale checkpoint (`post-launch-operations.md` §9) and each Weekly Ops Review growth step once spend is active.
+
+1. Refresh the current RevenueCat charts/metrics docs from the §1 sources in `revenuecat-and-store-products.md` before relying on chart names or API shapes — dashboards and endpoints move; record the docs basis and checked date with the numbers.
+2. Pull four numbers for the trailing window: MRR, realized LTV per paying customer, download-to-paid (initial) conversion, and churn split voluntary vs. involuntary by platform (the `billing-health-and-reactivation.md` §2 events make the split readable in PostHog when RevenueCat's own view is too coarse).
+3. Land them in the `revenue/REVENUE_OPS.md` Economics Snapshot row for the date, with the source named per row.
+4. Route the consequences, not just the numbers: LTV and payback feed the `growth/PAID_UA.md` blended report and its Decision Thresholds; the cancellation-reason mix feeds the Pricing Decision revisit (`paywall-pricing-and-experiments.md` §3 step 5); the whole row feeds the kill-or-scale evidence pack.
+5. Numbers that would change a founder-gated decision (price, spend, kill/scale) get surfaced in the reply per the narration contract — never only written to the file.
+
+## Resend Email Routing
+
+Purpose: set up outbound, lifecycle, broadcast, and optional inbound email without damaging domain reputation or creating compliance gaps.
+
+Use `resend-email-ops.md` before:
+
+- Resend domain creation or DNS changes
+- transactional email send wrappers
+- waitlist confirmations, welcome messages, trial reminders, payment recovery, receipts, support confirmations, or admin alerts
+- Contacts, Topics, Segments, Broadcasts, or Automations
+- unsubscribe/preference handling
+- Resend webhooks, inbound receiving, or attachment processing
+
+Rules:
+
+- Prefer a verified sending subdomain over the root domain.
+- Keep Resend API keys server-side only; never use `NEXT_PUBLIC_` or browser bundles.
+- Prefer sending-access/domain-scoped keys for runtime senders.
+- Use idempotency keys for retryable transactional sends.
+- Verify webhooks with the raw request body and store `svix-id` to handle duplicates.
+- Add unsubscribe/preference handling for lifecycle and marketing email.
+- Treat inbound MX changes as founder-gated when they could affect existing mailboxes or Cloudflare Email Routing.
+- Resend account/domain features can be paid/account-gated. Use `paid-tool-routing.md` before replacing Resend with local email previews, logs, Gmail, Cloudflare Email Routing, or another provider.
+
+## PostHog Analytics And Attribution Routing
+
+Purpose: make analytics, attribution, and launch learning visible before implementation and then validate the first real events once a repo exists.
+
+Use `analytics-attribution.md` before:
+
+- PostHog setup or SDK installation
+- event catalogs, funnels, dashboards, or PostHog project decisions
+- landing/waitlist/referral analytics
+- onboarding attribution questions
+- paywall, trial, closing-offer, or RevenueCat/Stripe event naming
+- feature flags, experiments, session replay, surveys, or data pipelines
+- Fastlane/social campaign UTM conventions
+- builder prompts that ask another agent to implement events
+
+Delegate:
+
+- `setup-posthog` only after the product repo exists and can receive an event scaffold.
+- `setup-posthog` handles initial project/setup validation; B2C App Builder owns the upfront `analytics/ANALYTICS.md` and `analytics/analytics-plan.html`.
+- Use current PostHog docs or Context7/web docs for stack-specific SDK details because PostHog SDK options, defaults, and product docs change.
+
+Default stack:
+
+- PostHog primary for product analytics, web analytics, feature flags, funnels, session replay when explicitly enabled, surveys, and experiments.
+- RevenueCat as subscription entitlement truth and subscription event source.
+- Stripe as web payment truth when direct checkout exists.
+- GA4/ad-network tooling only when paid ads, Google attribution, or platform reporting require it.
+- Sentry for errors/crashes, not product analytics.
+
+Rules:
+
+- Create `analytics/ANALYTICS.md` and a founder-visible `analytics/analytics-plan.html` before implementation.
+- Track waitlist, referral, pricing-section, app-store CTA, onboarding steps, attribution answer, demo video, personalized plan, review prompt eligibility/request, paywall view/dismissal, closing offer, activation, subscription lifecycle, restore, refund, email lifecycle, and Fastlane campaign events when relevant.
+- Combine technical attribution with self-reported attribution; UTMs alone miss word-of-mouth, creator, AI-search, and social discovery.
+- Use one analytics wrapper per surface; do not scatter vendor SDK calls throughout app code.
+- Validate at least one real event in the dashboard before saying analytics is live.
+- Do not enable replay, surveys, ad identifiers, or sensitive event properties without privacy/store-disclosure mapping.
+- PostHog paid/account features can affect replay, surveys, experiments, retention, and data pipelines. Use `paid-tool-routing.md` before replacing them with static plans or local event logs.

package/knowledge/process/tool-recipes/secrets-and-environment.md

@@ -0,0 +1,35 @@
+# Secrets And Environment Routing
+
+Use current tools and live data whenever possible. Treat this file as workflow, not fixed facts.
+
+Part of the [Tool Recipes](../tool-recipes.md) index. Before using any paid or account-gated tool named below, honor the **Paid Tool Decision Protocol** and **Founder-Only Gates** in that index.
+
+---
+
+## Doppler And Secret Routing
+
+Load [`secrets-management.md`](../../operations/secrets-management.md) before adding or using secrets. Default to Doppler unless the founder selected another provider.
+
+Refresh current Doppler official docs and `https://docs.doppler.com/llms.txt` before installation, setup, service-token, or CI/live-environment instructions. Record docs checked date, docs URLs, observed CLI version/install route, and any docs-vs-local mismatch in `SECRETS.md`.
+
+Local check:
+
+```bash
+doppler --version
+doppler setup
+doppler run -- npm test
+```
+
+Rules:
+
+- `doppler login` and account/project access are founder/operator actions when authentication is required.
+- Run `doppler me` before secrets work to confirm the active account.
+- **Config name preflight:** Before any `doppler run --project X --config Y` command, read the config name from `SECRETS.md` or run `doppler configs --project X`. Never guess from memory (e.g. "prod" vs "prd" differ by project and both are valid naming conventions).
+- Use `doppler run -- <command>` for local commands that need secrets.
+- Use Doppler service tokens, provider integrations, OIDC, or platform-native secrets for CI/live environments.
+- Do not print `doppler secrets get --plain` output.
+- **Env file extraction:** Never `source` a `.env`, `.p8`, or credential file. Use `awk -F= '/^KEY=/{print $2}' file` for single values. Do not commit awk/shell extraction snippets that print raw credential values to committed docs.
+- **JS inside doppler run:** When the command contains JavaScript template literals (`${...}`), pass the script via a single-quoted heredoc (`doppler run -- node --input-type=module <<'NODE' ... NODE`) so bash does not expand template syntax before Doppler injects secrets.
+- Update `SECRETS.md` whenever a new secret, `process.env`, webhook signing secret, provider key, service-account file, app-store credential, mobile build setting, or CI/deploy secret appears.
+- Commit `.env.example` names only; never commit `.env`, private keys, service-account JSON, signing files, OAuth refresh tokens, or raw provider keys.
+- **Session guard:** ship a `.claude/settings.json` `permissions.deny` block in every app repo. Deny Read, Edit, and Write access to `.env`, `.env.local`, `.env.*.local`, `secrets/**`, `*.pem`, `*.key`, `*.p8`, and `credentials*`. Treat this as one defense-in-depth layer, not a full guarantee. Keep the Doppler and no-print rules above as the primary control.