b2c-app-builder 0.221.39

package/knowledge/research/distribution-first-niche.md

@@ -0,0 +1,70 @@
+# Distribution-First Niche
+
+Use this before Phase 2 design or build work.
+Name a paying audience and one reachable channel first.
+Code does not create distribution.
+
+Purchases validate the niche.
+Compliments, likes, and waitlist-only interest do not.
+
+## Contents
+
+- 1. Pre-Build Gate
+- 2. Press Pack
+- 3. Influencer Pack
+- 4. Outputs
+- 5. Common Failure Modes
+
+## 1. Pre-Build Gate
+
+Record a Distribution-First Niche table in `strategy/RESEARCH.md`.
+
+The table must name:
+
+- who already pays for this job
+- one named channel the founder can reach
+- the paid event that counts as validation
+
+A named channel is a community, creator list, search cluster, or partner list.
+"Social media", "online", "ads", and "organic" are not named channels.
+
+`check:research` reads this table when the research lane is done.
+Distribution Proof still records reach evidence.
+This table records that the audience already pays and that purchases, not compliments, count.
+
+## 2. Press Pack
+
+Keep press work as a short checklist.
+Do not build a second outreach system.
+
+- shortlist two or three outlets that already cover this job
+- write one email that leads with the transformation demo
+- offer TestFlight as the launch artifact, not a feature tour
+
+Load `launch-narrative-cadence.md` for public posting rules.
+The founder approves every outbound email.
+
+## 3. Influencer Pack
+
+Load `influencer-sponsorship-engine.md` for native-fit filters, view-guarantee deals, and disclosure.
+Load `ugc-creator-engine.md` for hired posts on accounts the program controls.
+
+Do not start creator spend from this file.
+This file only requires that purchases, not compliments, validate a fit.
+
+Native-fit means the creator already speaks to people who pay for this job.
+A view guarantee is a deal term in the influencer engine.
+It is not a reason to skip the paying-audience row here.
+
+## 4. Outputs
+
+- `strategy/RESEARCH.md` Distribution-First Niche table
+- press shortlist and one-email draft, founder-gated
+- influencer prospects only after the niche table passes
+
+## 5. Common Failure Modes
+
+- Build starts with no paying audience
+- Channel recorded as "social media"
+- Waitlist compliments used as validation
+- Press or influencer spend before the niche table exists

package/knowledge/research/distribution-offer-signal.md

@@ -0,0 +1,190 @@
+# Distribution, Offer, And Signal Validation
+
+Use this reference before the founder records a Go, Pivot, or Kill decision.
+It adds distribution and offer evidence to the pre-build decision.
+
+## 1. Required Outcome
+
+Research must answer five questions before design or build work starts:
+
+1. Which people have the problem?
+2. Where do these people seek a solution?
+3. Which native message or format can reach them?
+4. Does a measurable offer response exist?
+5. How will the business keep an owned relationship after discovery?
+
+Category revenue proves that money exists in a market.
+It does not prove that this business can reach the market.
+
+### Strict Evidence Markdown
+
+Validator-backed evidence sections use a narrow Markdown dialect. Each section has one exact rendered H2 and one simple pipe table. Validators resolve required columns by name. Approved column-zero backtick and tilde fences may hold hidden examples. Outside those fences, every nonblank line indented four or more columns invalidates the evidence document. HTML comment opener tokens, raw HTML block syntax, non-column-zero fences, and container-relative raw HTML also invalidate it. Write checkable records as top-level Markdown.
+
+## 2. Distribution Proof
+
+Record distribution proof in `strategy/RESEARCH.md`.
+Use evidence from a current source ledger row.
+Give that row a stable source or trace ID in its URL/source-ID or Artifact/trace cell.
+The Distribution Proof evidence cell must resolve to that ledger ID or to a `current` or `dated` Signal ID.
+Do not use an unverified, rejected, or superseded signal as distribution proof.
+
+The proof must identify:
+
+- one audience segment
+- one exact discovery location
+- one native content or outreach format
+- one route to an owned relationship
+- one measured signal from that route
+
+An exact location is a named search result, community, creator audience, keyword cluster, newsletter, ad placement, or partner channel.
+"Social media" is not an exact location.
+
+An owned relationship is an email subscriber, account, push permission, or direct community membership.
+Do not require email when another durable route fits the product better.
+
+## 3. Signal Corpus
+
+Write `strategy/SIGNAL_CORPUS.md` before every pre-build verdict when reusable source material exists. Source material can include posts, transcripts, reviews, interviews, support records, and prior launch material. When no reusable source exists, keep the artifact. Record a project-specific `Status: not applicable —` reason. The reason must explain why no reusable source material exists. Do not invent evidence. Do not use `none`, `n/a`, `not applicable`, `unknown`, `no reason`, literal `authored reason` text, or an angle-bracket instruction.
+
+Record every source in Corpus Inputs before you cite it.
+Give each input a stable `INPUT-` ID, a real date range, an owner or creator, a collection route, a permission or public basis, and collection limits.
+Every Source ID in Signal Records must resolve to a declared input.
+
+Keep one signal record for one claim.
+Each record must include:
+
+- a stable signal ID
+- a signal type
+- the claim or exact phrase
+- one or more source IDs
+- an observation date
+- an applicability statement
+- a confidence value
+- a lifecycle status
+- a trace pointer
+
+Use these lifecycle values:
+
+- `current`: the evidence supports current use
+- `dated`: the record can still inform work, but time can change it
+- `superseded`: a later record replaces it
+- `rejected`: the evidence does not support use
+- `unverified`: the record needs more evidence
+
+A superseded record must point to its replacement.
+Do not delete a material contradiction.
+Record the contradiction and the selected current position.
+Unverified, rejected, and superseded records can remain in the corpus.
+Only `current` and `dated` records can support Distribution Proof or Derived Outputs.
+
+Markdown is the authoritative record.
+Indexes, search data, charts, and embeddings are rebuildable outputs.
+
+## 4. Traffic-Backed Offer Test
+
+Write `strategy/OFFER_TEST.md` before the founder records the verdict.
+Use the smallest truthful offer surface that can measure response.
+Replace every starter field with one project-specific value.
+A menu of possible audiences, locations, formats, relationship routes, responses, or stop rules is guidance, not a completed test contract.
+The Owned relationship field must name one durable route.
+An absent route does not complete the contract.
+
+The test can use:
+
+- a plain landing page
+- an existing store page
+- a direct-outreach offer
+- a partner or creator placement
+- a community post with a measurable call to action
+
+The test must record exposure and response.
+Exposure can be impressions, qualified visits, or qualified direct contacts.
+Response can be sign-ups, deposits, purchases, booked calls, or another named action.
+
+Do not treat compliments, likes, or general survey interest as an offer response.
+
+Public deployment, account connection, and spend need the applicable founder authority.
+Research can prepare the test without that authority.
+
+If the founder declines or cannot run the test, record a waiver.
+The waiver must include the founder, date, reason, and residual risk.
+Silence is not a waiver.
+
+## 5. Decision Use
+
+Add `Distribution proof` and `Offer test` columns to the Go, Pivot, Or Kill table.
+The founder decides the verdict after these columns contain evidence.
+
+A zero-conversion test does not force an automatic Kill decision.
+It is evidence for the founder to judge.
+The test can expose a bad audience, channel, message, offer, or product promise.
+
+## 6. Owned-Relationship Metrics
+
+When the project continues, track these metrics by discovery channel:
+
+- discovery exposure to owned contact
+- owned contact to activation
+- owned contact to paid conversion
+- revenue per owned contact
+- share of acquisition from the largest external platform
+
+Raw reach is a diagnostic value.
+It is not a business outcome.
+
+## 7. Content Intelligence
+
+Store reusable content observations as structured records.
+Each record should include the source, account baseline, audience fit, hook, structure, emotion, format, sales intent, and downstream result.
+
+Normalize performance against the source account's usual result.
+Do not rank content by raw views alone.
+
+Extract patterns.
+Do not copy another creator's words, identity, assets, or exact composition.
+
+## 8. Manual Proof Before Automation
+
+Run each value-producing process manually before you automate it.
+Record the manual input, output, result, cost, and failure mode.
+
+This rule does not apply to necessary security, compliance, backup, or monitoring controls.
+
+Begin each automation decision with `automate` or `keep manual`. Use `automate` only when that process's row passed and its manual evidence shows that repetition has value.
+
+## 9. Optional Persona-Balanced Test Planning
+
+When a beta test is in scope, a mixed group can help plan complementary perspectives:
+
+- a target novice
+- a target experienced user
+- a user who represents a device or accessibility risk
+- a domain, product, or usability reviewer
+
+Use the worksheet only when it helps the project plan recruitment or interpret feedback.
+It is optional planning guidance, not app-quality completion evidence.
+It does not replace measured quality results or change fresh-context acceptance of the whole app-quality artifact.
+Do not use one tester group as a fixed quota for every product, and do not treat a filled worksheet as proof that the app passed quality review.
+
+## 10. Prohibited Transfers
+
+Do not transfer deceptive or unsafe tactics from source material.
+Prohibited tactics include:
+
+- hidden fees
+- fake scarcity or social proof
+- undisclosed engagement manipulation
+- platform-rule circumvention
+- safety-filter evasion
+- close copying of successful content or ads
+
+Treat strong universal claims as hypotheses.
+Test them against this business's evidence.
+
+## 11. Source Limits
+
+EP's Signal Knowledgebase is a primary example of corpus compression and portable publishing.
+It also contains personal claims, dated tool choices, and aggressive growth tactics.
+
+Use its information architecture and testable business hypotheses.
+Do not treat its business claims as verified facts.

package/knowledge/research/go-pivot-or-kill.md

@@ -0,0 +1,120 @@
+# Go, Pivot, Or Kill: The Pre-Build Research Verdict
+
+The launch machinery will polish and ship whatever idea it is given — it has no opinion on
+whether the idea is worth building. This is the one evidence-gated exit ramp before Phase 2
+spends design, build, and store effort: the agent assembles the evidence, the founder decides
+whether the category and the wedge earn a build. `check:research` enforces the shape of this
+decision in `strategy/RESEARCH.md`; this file is the judgment behind that shape, not a second
+copy of it.
+
+## Contents
+
+- 1. The Category Revenue Reality Bar
+- 2. The Go, Pivot, Or Kill Table Contract
+- 3. The Verdict Is Founder-Only
+- 4. What Kill And Pivot Mean
+- 5. When The Verdict Is Mandatory
+
+## 1. The Category Revenue Reality Bar
+
+Before the spec hardens, ask the question a good idea and a good business both answer
+differently: **is this market big enough to be worth building in at all?** Pull top-competitor
+revenue estimates (AppKittie, sorted by revenue) and judge them against a stated bar.
+
+Default bar: the top 10 apps in the target category gross at least **$5M/year combined**, with
+at least **two independent apps each clearing $1M/year**. A category whose leaders gross too
+little cannot become a real business however well the launch executes — no amount of good
+onboarding, ASO, or paid UA fixes a market that is not there. Adjust the bar with the founder
+for a deliberate niche play, and record why the adjustment is legitimate rather than a way to
+pass a category that would otherwise fail.
+
+`check:research` reads the `## Category Revenue Reality` section's table, not the phrase in
+prose, and requires:
+
+- at least one competitor row with a real dollar estimate in the revenue column AND a dated
+  (`YYYY-MM-DD`), non-placeholder source in the source column — collecting the AppKittie data
+  is not the gate, the sourced number judged against the bar is
+- a "stated bar" line carrying an actual number, not a blank or placeholder
+- an explicit `pass or fail:` judgment line against that bar
+
+A pass verdict over no stated threshold, or a table with rows but no judgment line, is data
+collection wearing a gate's clothes.
+
+## 2. The Go, Pivot, Or Kill Table Contract
+
+The verdict itself lives in a `## Go, Pivot, Or Kill` table with these required named columns.
+The starter uses this canonical order, but projects may reorder the named columns or add
+project-specific columns:
+
+| Date | Category revenue reality | Wedge | Demand signal | Distribution proof | Offer test | Verdict (Go / Pivot / Kill) | Decided by |
+| ---- | ------------------------ | ----- | ------------- | ------------------ | ---------- | --------------------------- | ---------- |
+
+The five evidence columns are named on purpose: **category revenue reality**, **wedge**,
+**demand signal**, **distribution proof**, and **offer test** are the inputs a real verdict is
+judged from. A table renamed to Notes/Opinion/Summary carries cells, not the required inputs,
+and `check:research` rejects it. The validator resolves the required fields by normalized name,
+not by physical position or by a table shaped roughly like a decision.
+
+Row-level requirements once the lane is done:
+
+- **date and verdict must parse.** The date is ISO (`YYYY-MM-DD`); the verdict cell starts with
+  `go`, `pivot`, or `kill`. A row with a mistyped date or an unparseable verdict is reported as
+  malformed, never silently dropped — dropping it would fall back to an older verdict the
+  founder already superseded.
+- **the latest date wins ties.** If two rows share the newest date, the later row in the table
+  is the one that counts.
+- **evidence cells must be substantive.** Each of the five named evidence cells on the latest
+  row must be non-empty and free of placeholder text (`unverified`, `tbd`, `todo`, `to be
+filled`, `pending`, `placeholder`). A verdict decided over "unverified" is a mood, not a
+  decision — fill category revenue, wedge, demand, distribution, and offer evidence before
+  recording it.
+
+## 3. The Verdict Is Founder-Only
+
+`"Decided by"` names the founder — by role (`founder`, `owner`) or by the name recorded in
+`project.owner` — **never an agent or automation identity**. `check:research` explicitly rejects
+`agent`, `codex`, `claude`, `gpt`, `assistant`, `bot`, `automation`, `autopilot`, and `ai` as
+decision-makers in this column. This is the one gate in the whole engine designed to stop the
+agent from clearing itself: an agent recording Go for itself is the exact bypass the checkpoint
+exists to prevent, however confident the evidence looks.
+
+The verdict and its date must also be mirrored into `state/business-state.json`
+(`lanes.research.go_pivot_kill_decision` / `lanes.research.go_pivot_kill_decided_at`), and the
+mirror must match the latest table row exactly — a stale or forward-dated mirror is what
+downstream lanes and the portfolio pipeline would act on instead of the real decision.
+
+## 4. What Kill And Pivot Mean
+
+A Kill or a Pivot at this checkpoint is the process working, not failing — it costs a research
+document instead of a shipped app nobody wanted.
+
+- **Kill** winds the idea down before any design or build spend. The research lane is not
+  done, and stays not done: `check:research` refuses a `done` status while the latest verdict
+  is anything other than `go`.
+- **Pivot** re-enters Phase 1 with the wedge changed — new positioning, a different core loop,
+  or a narrower niche — and the Category Revenue Reality and Go/Pivot/Kill sections get a fresh
+  row once the changed wedge has been evaluated. The old verdict does not carry forward onto a
+  materially different idea.
+- **Go** is the only verdict that lets the research lane close `done`. Record the follow-up
+  verdict once the founder actually decides to build — a lane cannot be `done` on the strength
+  of the evidence alone.
+
+## 5. When The Verdict Is Mandatory
+
+This checkpoint does not wait politely for the research lane to claim `done` before it starts
+enforcing. `check:research` requires a real verdict the moment any of the following is true:
+
+- `lanes.research.status` is `done`, or
+- `project.phase` is `phase_2` or later, or
+- any downstream lane — `experience`, `product`, `design`, `content_assets`, or
+  `engineering` — is already `partial` or `done`.
+
+The `research-backed-spec` workflow uses `check:research-workflow-output`. This strict wrapper
+also requires complete research, signal-corpus, and offer-test outputs when that workflow claims
+its work. It does not change the pre-claim behavior of the public `check:research` command.
+
+That last condition is the one that matters most in practice: design and build effort spent
+before the founder's verdict is exactly the cost this checkpoint exists to prevent, whatever the
+recorded project phase says. Deferring or marking the research lane `not_needed` does not route
+around this — from `phase_2` onward, or the moment downstream work goes active, the verdict is
+mandatory even for a lane the state file claims is deferred.

package/knowledge/research/localization-market-research.md

@@ -0,0 +1,145 @@
+# Localization Market Research First
+
+Use this **before** localizing any surface — App Store/Google Play metadata, keywords, screenshots, App Previews, custom product pages, paywall/offers, landing pages, lifecycle email, or ads. Localization is a **market-selection decision made from search-demand evidence**, not a translation task you run "to be safe."
+
+This is the research-first inversion of the common indie pattern (translate into N languages, then hope for downloads). The skill's posture is the opposite: **research demand, prioritize markets, then localize only what clears the bar, then measure**. Produce `LOCALIZATION_MARKET_RESEARCH.md` (and `localization-market-research.html`) in the research phase so the priority tiers exist before metadata, screenshots, or paywall copy lock.
+
+Load `aso-store-ops.md` and `app-store-listing-prep.md` for how the chosen markets become metadata, keyword fields, screenshots, custom product pages, and In-App Events. Load `paid-user-acquisition.md` before choosing Apple Search Ads / paid storefronts (campaign storefronts are selected _from_ this matrix). Load `geo-seo.md` before localizing landing/web surfaces (`hreflang`, localized `llms.txt`/schema). Load [`change-cascade.md`](../process/change-cascade.md) to propagate a market's tier across every surface. Load `revenue-monetization.md` for paywall/offer adaptation per market. Whether the app _can_ ship a Tier 1 market cheaply is decided long before this research: [`conversion-copy.md`](../words/conversion-copy.md) §Localization Readiness makes string externalization, ICU plurals, and locale-aware formatting a day-one engineering property, with `product/copy/COPY_DECK.md` keys as the translation keys and each deck row carrying this matrix's tier.
+
+Load [`paid-tool-routing.md`](../operations/paid-tool-routing.md) before replacing AppKittie, XPOZ, paid ASO/MMP tooling, or App Store Connect / Google Play account data with a free or manual fallback. Missing runtime access to a paid intelligence tool is a founder decision, not a reason to guess the language list.
+
+## The Principle
+
+> **Demand → Prioritize → Localize → Measure.**
+> No surface is localized into a market until that market clears a popularity / competition / opportunity bar. Translating everything into 20 languages before any demand evidence is the documented anti-pattern. Localize based on search demand, not language.
+
+## Contents
+
+- 1. Why Research First
+- 2. Tool Routing (No TryAstro Dependency)
+- 3. The Market Opportunity Matrix
+- 4. Priority Tiers Drive Effort
+- 5. Cross-Surface Rollout (Mobile And App)
+- 6. Phase Placement And Traceability
+- 7. Post-Launch Refresh
+- 8. Outputs
+- 9. Seasonal Windows And PPP
+- 10. Common Failure Modes
+
+## 1. Why Research First
+
+Translating metadata into every language is expensive (translation, screenshot re-renders, paywall adaptation, support load, review/cultural QA) and most of it earns nothing because there is no search demand or the keyword difficulty is unwinnable in that storefront. Researching demand first means you know, before spending effort:
+
+- which countries/storefronts have real keyword popularity for the app's job
+- where competition/difficulty is low enough to rank
+- which markets are already sending downloads/revenue (for existing apps)
+- which keywords users actually search in-language (not literal translations of the English ones)
+- which surfaces are worth localizing per market, and which to defer
+
+The output is a ranked, evidence-backed target list — not a language checklist.
+
+## 2. Tool Routing (No TryAstro Dependency)
+
+This skill does **not** depend on TryAstro or any single ASO MCP. Compose the same "keyword popularity > X, low difficulty, localization priority per country" research from the tools the skill already routes to. Record which tool produced each cell and the data basis (estimates vs first-party).
+
+| Research need                            | Routed tool (preferred)                                                                                                      | Free / fallback (founder-approved)                                     |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Keyword popularity by country/storefront | AppKittie keyword popularity/traffic by country; Apple Search Ads popularity (Search Match / Recommendations) per storefront | public App Store/Play search, store autocomplete, manual keyword sheet |
+| Keyword difficulty / competition         | AppKittie `batch_keyword_difficulty` / `get_keyword_difficulty` per storefront                                               | top-ranking-app inspection, manual difficulty estimate                 |
+| Market size (downloads/revenue)          | AppKittie downloads/revenue estimates by country                                                                             | category top-charts inspection, public estimates                       |
+| Real demand in existing markets          | App Store Connect App Analytics / Google Play statistics (first-party, by territory)                                         | console exports                                                        |
+| In-language user vocabulary              | XPOZ (Reddit/TikTok/X/Instagram) social-language research per locale                                                         | platform-native browser search, in-language App Store reviews          |
+| Web/landing demand per locale            | web search + Firecrawl on localized competitor/SEO surfaces                                                                  | manual SERP inspection (feeds `geo-seo.md`)                            |
+| "Localization priority" output           | **this matrix's tier column** (synthesized from the above)                                                                   | same, documented manually                                              |
+
+If an ASO `localization` / `keyword-research` / `market-pulse` skill pack is installed, delegate the per-market pulls to it and keep the same matrix + tier output. AppKittie and competitor estimates are directional unless first-party — cite them as estimates and pair with App Analytics or reviews/social evidence where it matters.
+
+## 3. The Market Opportunity Matrix
+
+`LOCALIZATION_MARKET_RESEARCH.md` is the single source of truth for _where_ the app localizes. Its core is one row per candidate country/storefront:
+
+| Country / storefront | Top keywords (native, not literal translations) | Popularity | Difficulty | Est. demand / revenue | In-market language notes | Tool source | **Priority tier** |
+| -------------------- | ----------------------------------------------- | ---------- | ---------- | --------------------- | ------------------------ | ----------- | ----------------- |
+
+Rules:
+
+- Keywords are the **native** terms users actually search, sourced from in-storefront popularity and social language — not machine translations of the English keyword set.
+- Every populated row cites the tool/source for popularity and difficulty (AppKittie, Apple Search Ads, App Analytics, XPOZ).
+- The tier is the decision; the other columns are the evidence behind it.
+- Record rejected markets too, with the reason (no demand, unwinnable difficulty, no support capacity), so a future agent does not re-open them blindly.
+
+## 4. Priority Tiers Drive Effort
+
+Effort scales with opportunity, **not** with the number of languages available:
+
+- **Tier 1 — full localize.** Metadata + keyword field + screenshots + App Preview + **paywall/offer adaptation** + landing page + lifecycle email + (optional) a market-specific custom product page. Tier 1 means adapting paywall layout, plan anchoring, and offers per market — not word-for-word translation (see `revenue-monetization.md`; e.g. region-adapted paywalls and monthly-equivalent anchoring materially lift conversion).
+- **Tier 2 — metadata-only.** Localized title/subtitle/keyword field/description; English (or nearest-Tier-1) screenshots, documented as an intentional gap. A low-cost bet on an emerging market.
+- **Tier 3 — defer / track.** No localization yet; revisited from real App Analytics in the post-launch refresh.
+
+Do not localize a surface into a market that has no Tier 1/2 entry. Do not ship translated keywords with English-only screenshots **unless** the matrix records it as an intentional Tier 2 decision.
+
+## 5. Cross-Surface Rollout (Mobile And App)
+
+A market's tier cascades to every surface via `change-cascade.md`, so localization stays consistent across mobile and web:
+
+- **App Store / Google Play:** localized metadata, keyword fields, screenshots, App Preview, In-App Events, and custom product pages (each Tier 1 market can become a CPP entry point).
+- **Paywall / RevenueCat:** localized offers, plan anchoring, and layout per Tier 1 market — localize the paywall, not only the listing.
+- **Landing / web funnel:** localized pages, `hreflang`, localized `llms.txt`/schema (route through `geo-seo.md`).
+- **Lifecycle email (Resend):** localized templates for Tier 1 markets.
+- **Paid UA / Apple Search Ads:** campaign storefronts chosen from the matrix (route through `paid-user-acquisition.md`).
+
+## 6. Phase Placement And Traceability
+
+- **Phase 1 (research-backed spec):** produce `LOCALIZATION_MARKET_RESEARCH.md` alongside category economics, before any metadata/screenshot/paywall lock.
+- **Phase 3 (store ops):** ASO consumes the tiers instead of defaulting to English-only or translate-everything.
+- Trace each Tier 1/2 decision into `state/LAUNCH_TRACE.md` so a future agent can see why a market was localized and which evidence backed it.
+
+## 7. Post-Launch Refresh
+
+The post-launch ASO loop (`aso-store-ops.md` §10) refreshes this same matrix from **first-party** App Analytics / Play statistics: countries that are downloading/converting but are still Tier 2/3 are promotion candidates; localized markets that under-deliver are pruning candidates. The matrix is a living artifact, not a one-time research dump.
+
+## 8. Outputs
+
+- `LOCALIZATION_MARKET_RESEARCH.md`: market matrix, tiers, tool sourcing, seasonal windows, PPP pricing, rejected markets, and refresh cadence.
+- `localization-market-research.html`: founder-visible board of the ranked markets and tiers.
+- Updated `APP_STORE_LISTING.md` localization matrix, `state/LAUNCH_TRACE.md` traces, and (when in scope) `PAID_UA.md` storefront choices that draw from the tiers.
+- The `research` lane's evidence in `state/business-state.json` records why localization is `not_needed`/`deferred`, or points at the completed opportunity matrix.
+
+## 9. Seasonal Windows And PPP
+
+Do not launch keywords or localization into a known peak on the same day.
+
+Record Seasonal Windows in `LOCALIZATION_MARKET_RESEARCH.md`.
+Name the category, the window, the peak date, and the submit-by date.
+The submit-by date must sit 14 or more days before a dated peak.
+ASO index lag is two to four weeks.
+
+Sample plans:
+
+| Category         | Window                    | Peak Date  | Submit By  |
+| ---------------- | ------------------------- | ---------- | ---------- |
+| habits / fitness | New Year restart          | 2026-01-01 | 2025-12-15 |
+| shopping         | Black Friday / Cyber week | 2026-11-27 | 2026-11-10 |
+
+Use In-App Events as hooks inside those windows.
+Do not treat the sample dates as this app's plan.
+Fill the table with this app's dates.
+
+Record PPP / Territory Pricing before storefront price lock.
+Name the territory, the PPP band, the price point, and whether to localize now.
+Skip localization when demand evidence is weak.
+`asc-ppp-pricing` in `app-store-connect-cli.md` is the store command after this table exists.
+
+`check:localization-research` fails a dated submit-by that sits fewer than 14 days before a dated peak.
+Every Seasonal Windows row needs complete ISO Peak Date and Submit By values.
+Blank or malformed dates fail before the 14-day check.
+An empty Seasonal Windows table fails.
+
+## 10. Common Failure Modes
+
+- **Translate-first:** localized metadata exists but there is no opportunity matrix or priority tiers — effort spent with no demand evidence.
+- **Literal keyword translation:** the localized keyword field is a machine translation of the English keywords instead of native search terms with their own popularity/difficulty evidence.
+- **Metadata-only drift:** translated keywords shipped with English screenshots and an un-adapted paywall, not recorded as an intentional Tier 2 decision.
+- **Single English paywall:** the listing is localized but the paywall/offers are not, under-serving whole regions.
+- **Stale tiers:** post-launch App Analytics shows real demand in deferred markets but the matrix is never refreshed.
+- **Silent paid-tool downgrade:** AppKittie/XPOZ unavailable in the runtime, so the agent guesses the language list instead of routing through `paid-tool-routing.md`.

package/knowledge/research/transformation-demo.md

@@ -0,0 +1,70 @@
+# Transformation Demo
+
+Use this before a consumer-app Go verdict.
+The product must show one before-to-after change in one screenshot and a 15-second script.
+
+This gate is the research-phase check.
+It does not replace the five-second demo moment in `influencer-sponsorship-engine.md`.
+Creatives and onboarding reuse this same asset later.
+
+## Contents
+
+- 1. Required Outcome
+- 2. Vitamin Rejection
+- 3. Shared Asset
+- 4. Outputs
+- 5. Common Failure Modes
+
+## 1. Required Outcome
+
+Record a Transformation Demo table in `strategy/RESEARCH.md`.
+
+The table must name:
+
+- one screenshot path
+- one 15-second spoken or on-screen script
+- the transformation the user sees
+- why the change is a painkiller, not a vitamin
+
+The screenshot path must be a real relative file path.
+The script must describe one action and one result.
+The transformation must name a before state and an after state.
+
+`check:research` reads this table when the research lane is done.
+A missing column or a vitamin transformation fails the gate.
+
+## 2. Vitamin Rejection
+
+A vitamin feature improves a vague good.
+It does not remove a concrete pain.
+
+Reject rows that rest on wellness, generic productivity, or "feel better" language in the transformation cell.
+A painkiller restores a lost result, removes a block, or finishes a job the user already pays to solve.
+
+Durable patterns, not clone recipes:
+
+- recover a broken streak
+- show the next action after a miss
+- turn a raw capture into a judged result
+
+Do not copy another app's UI.
+Do not treat a mood or a lifestyle claim as the demo.
+
+## 3. Shared Asset
+
+The same screenshot and script feed paid creative and onboarding later.
+Do not invent a second demo for ads.
+Do not invent a second demo for the first-value screen.
+
+## 4. Outputs
+
+- `strategy/RESEARCH.md` Transformation Demo table
+- screenshot file under a proofs path
+- later reuse in `PAID_UA.md` creative and `product/ONBOARDING.md` first value
+
+## 5. Common Failure Modes
+
+- Vitamin copy in the transformation cell
+- A screenshot path with no slash and no image suffix
+- A script too short to be spoken in 15 seconds
+- A new demo invented later for ads

package/knowledge/store/age-rating-questionnaire.md

@@ -0,0 +1,75 @@
+# Age Rating Questionnaire
+
+Part of the [ASO And Store Operations](./aso-store-ops.md) hub — it decides which store lane runs and what evidence each lane must leave behind.
+
+Use this before every Apple review submission.
+Apple requires extra age-rating answers from September 2026.
+A blank field is not a `false` answer.
+
+Load `store-console-workflow.md` for the console packet.
+Load `app-store-connect-cli.md` before any `asc` command.
+
+## Contents
+
+- 1. Required Answers
+- 2. Product Evidence
+- 3. Provider Audit
+- 4. Mutation Boundary
+- 5. Outputs
+- 6. Common Failure Modes
+
+## 1. Required Answers
+
+Record these fields in `store/STORE_CONSOLE.md`:
+
+- `socialMedia`
+- `messagingAndChat`
+- `socialMediaAgeRestricted`
+- `ageAssurance`
+- `userGeneratedContent`
+
+Each answer must be `true` or `false`.
+Do not infer `false` from a missing field.
+
+If `socialMediaAgeRestricted` is `true`, `ageAssurance` and `userGeneratedContent` must also be `true`.
+
+## 2. Product Evidence
+
+Each answer must cite a product fact.
+Do not copy a lower-risk answer to clear the gate.
+
+Ambiguous chat, UGC, or age-assurance behavior is a founder or legal escalation.
+
+## 3. Provider Audit
+
+Run this read before every review submission:
+
+```text
+asc age-rating audit --app "<APP_ID>"
+```
+
+Confirm `--help` first.
+Record the CLI version, app ID, audit time, and a redacted result digest.
+
+Missing or inconsistent provider fields block release.
+
+Use `--paginate` only for an authorized portfolio-wide audit.
+
+## 4. Mutation Boundary
+
+`asc age-rating edit` needs an exact mutation envelope and product evidence.
+Read the declaration back after any edit.
+Do not change product behavior only to make the questionnaire pass.
+
+## 5. Outputs
+
+- Age Rating Questionnaire table in `store/STORE_CONSOLE.md`
+- `asc age-rating audit` evidence
+- founder or legal escalation when the product fact is ambiguous
+
+## 6. Common Failure Modes
+
+- Inferring `false` from a blank field
+- Submitting with a missing social or UGC answer
+- Running `asc age-rating edit` without an envelope
+- Selecting a lower-risk answer to clear the gate