@funnelsgrove/cli 0.1.10 → 0.1.12

package/template_docs/docs/ab-experiments.md

@@ -1,33 +1,53 @@
 # A/B Experiments
 
-Experiments live in `src/config/funnel.manifest.ts`. They are routing rules, not ad hoc conditionals inside step components.
+Experiments are config, not code: declared in `src/config/experiments.ts`, exported into the manifest, resolved by the shared runtime. Never write variant conditionals inside step components. If the variant step already exists, setting up the experiment is a one-file edit that takes under a minute.
 
-## Runtime Contract
+## Recipe: Step or Paywall Test
 
-An experiment attaches to a source step and maps variant keys to routable step ids:
+Open `src/config/experiments.ts` and add one entry inside `defineFunnelExperiments([...])`:
 
 ```ts
-{
-  experimentId: 'paywall-ab',
-  stepId: 'paywall',
-  variants: [
-    { variantKey: 'control', routeToStepId: 'paywall' },
-    { variantKey: 'variant_b', routeToStepId: 'paywall-b' },
-  ],
-}
+export const experiments = defineFunnelExperiments([
+  {
+    id: 'paywall-ab',                       // durable, readable, never reused
+    name: 'Paywall copy test',
+    type: 'paywall',                        // 'step' for quiz steps, 'paywall' for paywall tests
+    status: 'running',                      // 'paused' | 'stopped' removes it from the manifest
+    launchDate: '2026-06-12T00:00:00.000Z',
+    control: { stepId: 'paywall', label: 'paywall-ab-control', trafficPercent: 50 },
+    variant: { stepId: 'paywall-b', label: 'paywall-ab-variant-b', trafficPercent: 50 },
+  },
+] as const);
 ```
 
-The flow controller resolves the experiment assignment through the shared analytics/runtime integration and routes to the matched variant. `@funnelsgrove/analytics` encapsulates api for experiment tracking. If the assignment is not ready on an experiment step, rendering is suspended to avoid flashing the control before the variant resolves.
+That's it — `toManifestExperiments(experiments)` in the same file feeds the manifest, traffic percents are validated to sum to 100, and non-`running` entries are filtered out automatically. (Older funnels may declare a plain array and map it manually — follow the local file's existing shape there.) Preconditions (each is its own task if missing):
 
-## Editor and Preview
+1. Both `control.stepId` and `variant.stepId` exist in the manifest with normal `edgesByStepId` exits ([editing-step.md](editing-step.md) to create a variant step — usually a copy of the control step with one deliberate change).
+2. Both steps route to the same next step, unless the experiment is explicitly about the flow.
 
-When `?editor=true` is enabled, the editor panel can force runtime mode and select experiment variants. Builder preview can also navigate steps through the preview bridge. This lets agents verify each variant without changing the manifest.
+## How the Runtime Behaves
+
+When a visitor opens the source step, the runtime suspends rendering until the assignment from `@funnelsgrove/analytics` is ready, then routes to the assigned `stepId` and syncs the URL. After assignment, navigation continues through the assigned step's normal edges — the experiment is not re-evaluated mid-flow. Assignments are sticky per visitor.
+
+The paywall runtime is experiment-ready out of the box: paywall variants can differ in copy, layout, plan presentation, or pricing source, and checkout/discount state stays scoped per funnel.
+
+## Verify (part of the < 1 min setup)
+
+In local preview or builder preview, force each side with the editor override:
+
+```text
+/paywall?editor=true&experimentVariant=control
+/paywall?editor=true&experimentVariant=variant_b
+```
+
+Check: opening the source URL promotes to the assigned route, each variant renders, Continue advances to the step after the variant. Then run a normal (non-editor) open to confirm the suspension → assignment → route flow works.
 
 ## Rules
 
-- Keep `control` stable.
-- Keep variant keys durable and readable.
-- Test the attachment step and every variant route.
-- Do not put unrelated changes in a variant; isolate one major decision.
-- Do not remove a live variant until analysis and rollout are approved.
-- If a variant changes paywall plans or checkout behavior, update `@funnelsgrove/analytics` event expectations too.
+- One deliberate change per experiment. Don't bundle unrelated edits into a variant.
+- `control` stays stable; never edit the control step as part of launching a variant.
+- Add stable `control.label` and `variant.label` values in the `<experiment-id>-control` / `<experiment-id>-variant-b` format so builder labels and analytics views stay readable.
+- Variant keys and experiment ids are durable — they flow into analytics. Never recycle an id for a different hypothesis.
+- Keep every variant step's outgoing edge in `edgesByStepId`, or assigned visitors strand.
+- If a paywall variant changes plans or pricing, follow [payment-plans-and-discounts.md](payment-plans-and-discounts.md) for the plan/discount sync rules and QA both variants' checkout ([qa-checklist.md](qa-checklist.md)).
+- Don't remove a running variant until the user confirms the analysis is done; route all traffic to the winner by setting `trafficPercent` rather than deleting history.

package/template_docs/docs/analytics.md

@@ -18,15 +18,15 @@ Analytics should describe meaningful user behavior. `@funnelsgrove/analytics` is
 
 Experiment assignments are attached as feature flag properties when available. Preview runtime skips normal analytics delivery.
 
-## Custom Events
+## Standard Checkout Events
 
-Use `publicAnalyticsSdk.track(...)` from `@funnelsgrove/analytics`:
+Use named helpers from `@funnelsgrove/analytics` for checkout lifecycle events:
 
 ```ts
-publicAnalyticsSdk.track({
-  eventType: 'checkout_started',
+publicAnalyticsSdk.trackCheckoutStarted({
   stepId: stepPaywallId,
   stepName: stepPaywall.name || stepPaywall.title,
+  stepType: stepPaywall.type,
   metadata: {
     planId,
     providerPlanId,
@@ -37,6 +37,8 @@ publicAnalyticsSdk.track({
 });
 ```
 
+Use `trackPaymentInfoSubmitted(...)` for payment details submitted, `trackCheckoutCompleted(...)` after a confirmed checkout, and `trackPaymentCheckoutSucceeded(...)` / `trackPaymentCheckoutReturned(...)` on redirect return screens.
+
 Flush before redirects or payment handoff when losing the page would drop the event:
 
 ```ts
@@ -60,3 +62,4 @@ Provider-specific behavior is documented separately. Read [Meta Pixel and Conver
 - Use `@funnelsgrove/analytics` for custom tracking; do not call the provider SDK directly.
 - When changing flow, verify step start/end still fires on the new path.
 - When changing offers, verify checkout events include plan id, provider plan id, coupon id, amount, and mode.
+- Use `stepType: 'paywall_offer'` on paywall checkout events so analytics rollups do not depend on step names.

package/template_docs/docs/editing-flow.md

@@ -6,15 +6,24 @@ Flow is product logic. The source of truth is `src/config/funnel.manifest.ts`; r
 
 The manifest defines:
 
-- `viewport`: the designed shell size, usually `430 x 932`.
-- `assets`: image metadata used by runtime/build tooling. Funnel shells may use
-  this data to warm likely next-step images, but first-viewport images should
-  still use the framework's normal priority/preload mechanism.
-- `steps`: every routable step with `id`, `path`, `filePath`, `componentKey`, `type`, optional `kind`, and optional `assetIds`.
+- `viewport`: the designed shell size. New funnels also declare default QA
+  `breakpoints`: small 375x667, medium 393x852, large 402x874, and
+  desktop-small 1280x800.
+- `assets`: image metadata used by runtime/build tooling. Declare every
+  funnel-critical raster image here with stable `src`, `width`, and `height`
+  so publish can reduce image size during the build and generate AVIF/WebP
+  variants. Funnel shells may use this data to warm likely next-step images,
+  but first-viewport images should still use the framework's normal
+  priority/preload mechanism.
+- `steps`: every routable step with `id`, `path`, `filePath`, `componentKey`, `type`, optional `kind`, optional `tags`, and optional `assetIds`. New `path` values must be meaningful public route slugs, not `/step-1` style URLs. Sequential ids are acceptable when the funnel uses them internally.
 - `edgesByStepId`: graph edges between steps.
+- `branches`: builder metadata for conditional paths that own one or more steps before reconverging.
 - `experiments`: optional variant routing.
 
 Keep `steps[].id`, `path`, and answer keys stable unless the request is a migration.
+When adding a step, prefer a semantic path like `/motivation`, `/fitness-goal`,
+or `/email-capture`; do not expose internal ordering through `/step-1` or
+`/step-07` routes.
 
 ## Routing Rules
 
@@ -37,6 +46,36 @@ eligibility: [
 
 The flow controller resolves the next step from configured edges first, then falls back to the sequential order. It also keeps the URL in sync through `getPathForStep(...)` and browser history.
 
+## Branch Labels
+
+A branch starts when one step has different next steps depending on an answer. If a direction owns one or more branch-only steps before all directions share a common next step again, add a `branches` entry:
+
+```ts
+branches: [
+  {
+    id: 'device-android',
+    name: 'Device type',
+    sourceStepId: 'eligibility',
+    conditionId: 'eligibility:yes',
+    label: 'yes-branch',
+    tags: ['android-branch', 'yes-branch'],
+    stepIds: ['active-google-claim', 'subscriptions'],
+  },
+]
+```
+
+`name` is the readable branch group shown in builder. `label` should come from the answer that opened the path, such as `yes-branch`, `no-branch`, or `family-branch`. `stepIds` includes only the steps owned by that direction; stop before the common next step. Directions that jump directly to the common next step do not need a branch entry.
+
+Keep branch and edge metadata builder-readable, following the ClaimBee pattern:
+`branches` should be an inline array on the manifest, and `edgesByStepId`
+should use literal string keys and `toStepId` values. Avoid hiding builder
+metadata behind constants such as `branches: flowBranches`, computed keys such
+as `[emailCaptureManifestStep.id]`, or targets such as
+`toStepId: emailCaptureManifestStep.id`; the builder reads these fields from
+source text without executing the module.
+
+Use `steps[].tags` for stable builder labels that belong to one step, including current experiment labels such as `paywall-test-control`. Keep stopped A/B variants and other intentional inactive screens tagged too; builder derives `unused` automatically when those steps are not reachable from the default entry point or any active experiment path.
+
 ## Step Navigation
 
 Use the funnel context:
@@ -62,12 +101,25 @@ Experiments attach to a step and route to variant steps:
 }
 ```
 
-The runtime resolves assignments through the shared analytics/runtime integration outside preview and uses editor overrides inside preview/editor mode. Keep the control variant stable and do not remove a running variant until analytics have been reviewed.
+The runtime resolves assignments through the shared analytics/runtime integration outside preview and uses editor overrides inside preview/editor mode. Opening the source step waits for the assignment, then opens the assigned route and keeps the URL in sync. Continue then advances from the assigned route's normal graph edge, with the already-applied experiment ignored for that continuation.
+
+Keep experiment redirects out of step components. Add normal `edgesByStepId` entries for the source/control step and every variant step, then let `goNext()` or the shell Continue button use the shared runtime.
+
+Keep the control variant stable and do not remove a running variant until analytics have been reviewed.
 
 ## Checklist
 
 - Add or update the manifest step.
 - Register the component in `src/runtime/step-registry.ts`.
-- Update `edgesByStepId`, `entryPoints`, and `assetIds` if needed.
+- Update `edgesByStepId`, `entryPoints`, `branches`, step `tags`, and `assetIds` if needed.
+- Label every branch-owned path with `branches[].name`, answer-derived `label`, useful `tags`, and owned `stepIds`.
+- Keep builder metadata inline/literal so groups, labels, and `unused` badges are visible in builder.
+- Label every running experiment variant with stable tags/labels like `<experiment-id>-control` and `<experiment-id>-variant-b`.
+- Confirm intentionally inactive/unreachable steps will show as `unused` in builder.
+- Use a meaningful public `path` for every new step. Internal ids can be
+  sequential, but URLs should describe the screen.
+- Keep image preloading manifest-driven: step images belong in
+  `funnelManifest.assets` and step `assetIds`; the shell should warm only likely
+  next-step images at low priority, not the entire funnel.
 - Make sure skipped steps do not own required answers.
 - Verify the step before, the edited step, and the step after.

package/template_docs/docs/editing-step.md

@@ -1,66 +1,125 @@
-# Editing or Creating a Step
+# Adding or Editing a Step
 
-A step is one screen or decision point. Keep its view, local state, validation, and step-specific CSS in the step file. Keep editable copy/images in a matching content file and builder fields in a matching editor file.
+A step is one screen, one decision. Target: a new step compiles and renders in local preview in under 3 minutes. Exactly six files are involved — no others.
 
-## Source Files
+| # | File | What goes there |
+| --- | --- | --- |
+| 1 | `src/steps/step-NN-<name>.tsx` | View, step meta, local state, one-off CSS |
+| 2 | `src/steps/content/step-NN-<name>.content.ts` | All copy and image refs (localized) |
+| 3 | `src/steps/editor/step-NN-<name>.editor.ts` | Which content fields the builder may edit |
+| 4 | `src/runtime/step-registry.ts` | `componentKey` → component + meta |
+| 5 | `src/steps/step-content.registry.ts` | step id → content/editor file paths |
+| 6 | `src/config/funnel.manifest.ts` | Step entry + `edgesByStepId` routing |
 
-For an existing step, start from `src/config/funnel.manifest.ts` and find:
+Before writing UI, read [step-ui-guidelines.md](step-ui-guidelines.md) — it defines the layout shell, the sticky action bar, and the viewport rules every step must pass.
 
-- `steps[].id`: stable route/runtime id, such as `paywall`.
-- `steps[].path`: URL path, such as `/paywall`.
-- `steps[].filePath`: React view file, such as `src/steps/step-32-paywall.tsx`.
-- `steps[].componentKey`: key registered in `src/runtime/step-registry.ts`.
+## Naming and URLs
 
-Most steps also have:
+Files may use ordered names like `step-07-motivation.tsx`, and step ids may stay
+sequential if the existing funnel uses sequential ids. Public route paths must
+be meaningful product slugs. Use `/motivation`, `/fitness-goal`, or
+`/email-capture`; do not create routes like `/step-1`, `/step-07`, or
+`/question-3`.
 
-- `src/steps/content/<step>.content.ts`: localized content using `LocalizedStepContent`.
-- `src/steps/editor/<step>.editor.ts`: builder editor fields using `StepEditorSection`.
-- `src/steps/step-content.registry.ts`: maps the runtime step id to those content/editor files.
+## Recipe: New Step
 
-## View Pattern
+Copy the closest existing step as the starting point (`step-02` for selections, `step-03` for interstitials). Then:
 
-Step files usually export:
+**1. View** — `src/steps/step-07-motivation.tsx`:
 
-- A stable `stepXId`.
-- A `FunnelStepMeta` object with `id`, `type`, `title`, optional `kind`, and optional `actionBar`.
-- A React component that reads content with `usePreviewStepLocalizedContent(...)` or the funnel's wrapper, such as `useClaimbeeStepContent(...)`.
+```tsx
+export const stepMotivationId = 'motivation';
+
+export const stepMotivation: FunnelStepMeta = {
+  id: stepMotivationId,
+  name: 'motivation',
+  type: 'single_step_choice',
+  title: 'Motivation',
+  description: 'Asks the user what motivates them.',
+  actionBar: { buttonText: 'Continue' }, // omit for auto-advance; { hidden: true } if the step owns its CTA
+};
+
+export function StepMotivation() {
+  const { attributes, setAnswer, goNext } = useFunnel();
+  const content = usePreviewStepLocalizedContent(
+    stepMotivationId,
+    stepMotivationContent,
+    getStepContentLocale(attributes),
+  );
+  // render options; on select: setAnswer('motivation', id) then goNext() for auto-advance
+  return (
+    <>
+      <section className='motivation-step'>...</section>
+      <style>{stepStyles}</style>
+    </>
+  );
+}
+
+const stepStyles = `...one-off CSS only...`;
+```
 
-Use `useFunnel()` for runtime state:
+**2. Content** — `src/steps/content/step-07-motivation.content.ts`: export a `LocalizedStepContent` object holding every user-visible string and image. The view must not contain literal copy.
 
-- `answers` / `attributes`: current funnel answers.
-- `setAnswer(key, value)` or `setAttribute(key, value)`: store data another step needs.
-- `goNext()`, `goToStep(stepId)`, or `goChoice('yes' | 'no')`: navigate through the manifest.
-- `user`, `setUser`, `completeStep`: only when the step explicitly needs user/session behavior.
+**3. Editor** — `src/steps/editor/step-07-motivation.editor.ts`: export `StepEditorSection[]` exposing only the fields a non-developer should edit (see an existing editor file for the field kinds).
 
-Do not bypass the flow controller with raw `window.location` for normal funnel navigation.
+**4. Register the component** — `src/runtime/step-registry.ts`:
 
-## CSS Pattern
+```ts
+stepMotivation: { component: StepMotivation, meta: stepMotivation },
+```
 
-Keep one-off step styling at the bottom of the step file:
+**5. Register content/editor** — `src/steps/step-content.registry.ts`:
 
-```tsx
-return (
-  <>
-    <section className='claimbee-step'>...</section>
-    <style>{stepStyles}</style>
-  </>
-);
-
-const stepStyles = `
-.claimbee-step { ... }
-`;
+```ts
+motivation: {
+  contentPath: 'src/steps/content/step-07-motivation.content.ts',
+  editorPath: 'src/steps/editor/step-07-motivation.editor.ts',
+},
 ```
 
-Use shared CSS under `src/steps/styles/shared/` only for patterns reused by multiple steps. Do not move one-off Figma parity or paywall-specific styling into shared files.
+**6. Manifest + routing** — `src/config/funnel.manifest.ts`:
+
+```ts
+// steps[]
+{
+  id: 'motivation',
+  path: '/motivation', // meaningful public URL, not '/step-07'
+  filePath: 'src/steps/step-07-motivation.tsx',
+  componentKey: 'stepMotivation',
+  type: 'single_step_choice',
+  title: 'Motivation',
+},
+// edgesByStepId — wire it in AND give it an exit
+'step-2': [{ toStepId: 'motivation' }],
+motivation: [{ toStepId: 'step-3' }],
+```
+
+**Verify:** `npm run dev`, open `/motivation`, confirm it renders at small 375x667, medium 393x852, large 402x874, and desktop-small 1280x800, Continue (or auto-advance) lands on the next step, and `npm run test:run && npm run lint` pass.
+
+## Editing an Existing Step
+
+Find the step in `src/config/funnel.manifest.ts` by `id` — `filePath` points at the view, `componentKey` at the registry entry. Copy changes go in the `content/` file, never inline in the view. Behavior changes go in the view file. Re-run the verify line above for the edited step.
+
+## Navigation Inside a Step
+
+Use `useFunnel()` only:
+
+- `setAnswer(key, value)` / `setAttribute(key, value)` — store data another step needs.
+- `goNext()` — normal manifest progression.
+- `goChoice('yes' | 'no')` — when the manifest has conditional edges for this step.
+- `goToStep(stepId)` — explicit jumps (paywall success, manage-subscription return).
+
+Never navigate with raw `window.location`, and never encode experiment routing in the step ([ab-experiments.md](ab-experiments.md) handles that in config).
+
+## CSS
 
-## Creating a Step
+One-off styling lives in a `const stepStyles` string at the bottom of the step file. Shared styling under `src/steps/styles/shared/` only when several steps already use the same pattern. Do not move paywall-specific styling into shared files.
 
-1. Add the view file in `src/steps/`.
-2. Add `content/<step>.content.ts` with the exact content shape the view needs.
-3. Add `editor/<step>.editor.ts` exposing only fields that should be editable.
-4. Register the component in `src/runtime/step-registry.ts`.
-5. Add content/editor paths in `src/steps/step-content.registry.ts`.
-6. Add the step and route edge in `src/config/funnel.manifest.ts`.
-7. Add focused tests when changing routing, state, checkout, parsing, or non-trivial UI behavior.
+## Rules
 
-Preserve existing ids unless the work is an explicit migration. A renamed step id changes routes, persisted answers, analytics, builder preview patches, and publish history.
+- Keep `id`, `path`, and answer keys stable — renames break routes, persisted answers, analytics, and publish history.
+- For new steps, use a meaningful `path`. Sequential ids and filenames are fine
+  when they match the project, but public URLs should not be `/step-1` style
+  routes.
+- Every step needs an outgoing edge (except terminal steps like subscription handoff).
+- Add a focused test when changing routing, state, checkout, parsing, or non-trivial UI logic.

package/template_docs/docs/payment-plans-and-discounts.md

@@ -33,6 +33,17 @@ Discounts use `BillingDiscountList` or `BillingDiscountCatalog` and are resolved
 
 Use `resolvePaywallDiscountState(...)`, `advancePaywallDiscountState(...)`, `activateSecondPaywallDiscount(...)`, `serializePaywallDiscountState(...)`, and `buildDiscountedPaywallPlans(...)`. Store discount state through runtime paywall state helpers (`readPaywallStateValue`, `updatePaywallStateValue`) so it is scoped by funnel id.
 
+### Discount on Closing Checkout
+
+The standard two-stage flow, wired in the paywall step:
+
+1. Paywall opens with the first-stage discount applied to plan cards.
+2. The checkout controller's `onFirstCheckoutClosed` callback fires when the visitor closes the card checkout without paying. The paywall opens `SharedCheckoutSpecialOfferDialog` (image, discount label, accept button — copy lives in the paywall content file).
+3. Accepting calls `activateSecondPaywallDiscount(...)`, which swaps to the stronger second-stage coupon, restarts its window, and re-renders plans via `buildDiscountedPaywallPlans(...)`.
+4. The next checkout open carries the second-stage coupon id in its payload.
+
+Keep both stages testable: QA must verify stage one on open and stage two after a checkout close ([qa-checklist.md](qa-checklist.md), paywall item 5).
+
 ## Checkout
 
 Prefer shared Stripe surfaces:

package/template_docs/docs/publishing-and-versioning.md

@@ -6,10 +6,53 @@ Local edits are not public until they are synced and published. Sync creates or
 
 ```bash
 fgrove status
+git status --short
+fgrove github status
+fgrove publish --env preview --message '<summary>'
+```
+
+Before syncing down over an existing synced directory, check local changes. If
+`git status --short` shows local edits, checkpoint them first. `fgrove sync
+down` refuses to overwrite a dirty synced directory by default; use `--force`
+only when discarding local changes is intentional.
+
+When GitHub is connected and its branch is ahead, run `fgrove github pull` to
+pull GitHub into the hosted draft, then poll `fgrove github status` until the
+pull job is completed or skipped. Sync that latest draft into a clean directory
+and merge local changes intentionally before continuing.
+
+For GitHub-connected funnels, source changes must be pushed to GitHub first,
+then pulled into the hosted draft:
+
+```bash
+git push
+fgrove github pull
+fgrove github status
+fgrove publish --env preview --message '<summary>'
+```
+
+Poll `fgrove github status` until the pull job is completed or skipped before
+publishing. Do not run `fgrove sync up` for the same source diff; the CLI and
+API reject draft source sync for GitHub-connected funnels.
+
+When GitHub is not connected, the hosted draft is the remote source of truth.
+Download it into a temporary clean directory with `fgrove sync down --funnel
+<id-or-slug> --dir <temp-dir>` or an already selected `fgrove use` context,
+compare it with local changes, merge intentionally, rerun checks, then `fgrove
+sync up`.
+
+For funnels without GitHub, sync local source directly to the hosted draft:
+
+```bash
 fgrove sync up --message '<summary>'
 fgrove publish --env preview --message '<summary>'
 ```
 
+If `fgrove sync up` reports that the remote draft changed since the local
+directory was synced, do not retry blindly. Download the current draft into a
+temporary clean directory, merge local changes against it, rerun checks, and
+sync again.
+
 Refresh the ignored local `.env` from the remote project when project settings change:
 
 ```bash
@@ -26,9 +69,24 @@ fgrove publish --env production --domain <domain> --message '<summary>'
 
 Production publish requires a domain. Preview publish returns a deployment URL, version sequence, and version id.
 
+## Publish Image Optimization
+
+Publish builds reduce raster image size before upload. Keep this path enabled:
+PNG/JPEG sources are compressed, AVIF/WebP variants are generated for supported
+browsers, and the original image remains the fallback. Do not bypass this with
+remote funnel-critical image URLs.
+
+After publishing image edits or a production candidate, check the deployment
+metadata, CLI output, or `publishBuild.stageTimings.imageVariants`. If the
+image-variant stage is missing or unavailable, report that explicitly before
+calling the publish ready.
+
 ## Local Sync Contract
 
-The CLI writes `.funnelsgrove-sync.json` into the local tree. Keep it there. It records workspace id, funnel id, and current draft version id so later `sync up` can patch only changed/deleted files.
+The CLI writes `.funnelsgrove-sync.json` into the local tree. Keep it there. It
+records workspace id, funnel id, current draft version id, and source hashes so
+later `sync up` can patch only changed/deleted files and detect stale remote
+drafts before overwriting them.
 
 Local-only files are excluded from upload:
 
@@ -45,8 +103,15 @@ Do not edit generated build output as the source of truth.
 ## Agent Rules
 
 - Run `fgrove status` before syncing.
+- Check local changes before `sync down`; checkpoint or merge instead of
+  overwriting.
+- For GitHub-connected funnels, push with normal git, then run `fgrove github
+  pull`; do not run `fgrove sync up` for the same source change.
 - Use clear sync and publish messages.
-- Sync before publishing.
+- Sync the hosted draft before publishing: GitHub-connected funnels use normal
+  `git push` plus `fgrove github pull`; funnels without GitHub use `fgrove sync
+  up`.
 - Publish preview first and verify the returned URL.
-- If preview verification fails, fix locally, run checks, sync up again, and publish a new preview.
+- If preview verification fails, fix locally, run checks, sync the hosted draft
+  again through the correct source path, and publish a new preview.
 - Do not production publish without explicit instruction and target domain.

package/template_docs/docs/qa-checklist.md

@@ -0,0 +1,80 @@
+# QA Checklist
+
+What to test, where to test it, and what blocks a publish. QA can take as long as it needs — it is the gate before anything user-facing ships. Scale the scope to the edit: a copy tweak needs the affected step only; anything touching flow, paywall, checkout, pricing, identity, or experiments needs the full list.
+
+## Where
+
+| Stage | URL | When |
+| --- | --- | --- |
+| Local | `npm run dev` → `http://localhost:3000` | Always, before sync |
+| Preview | URL returned by `fgrove publish --env preview` | Before any production publish |
+| Production | Live domain | After production publish |
+
+A production publish without a QA-passed matching preview build is a blocker unless the user explicitly accepts the risk.
+
+## 1. Flow Coverage
+
+- Open the first step and walk every step to the end.
+- Exercise every branch (`goChoice` yes/no paths) — check both sides.
+- For each experiment in `src/config/experiments.ts`, force both variants (`?editor=true&experimentVariant=control|variant_b`) and confirm each renders and advances.
+- Submit email/identity capture with a test address and confirm advancement.
+- Keep the browser console open the whole walk: zero uncaught errors and no failed requests (ignore third-party analytics noise).
+
+## 2. Visual Pass
+
+Run every visual pass at all four default breakpoints (rules in [step-ui-guidelines.md](step-ui-guidelines.md)):
+
+| Breakpoint | Size |
+| --- | --- |
+| small | **375x667** |
+| medium | **393x852** |
+| large | **402x874** |
+| desktop-small | **1280x800** |
+
+- Nothing intersects or overlaps: text never collides with images, cards, badges, or the action bar; modals and dialogs fit the viewport.
+- Continue button sits on an opaque bar at the bottom and stays visible on every step, including while content scrolls.
+- No horizontal scroll, no clipped or truncated content, no broken images.
+- Disabled CTA states render correctly and enable when valid.
+
+## 3. Image Performance
+
+For image edits and every preview-to-production candidate:
+
+- Confirm edited step images are listed in `funnelManifest.assets` and attached
+  to the relevant manifest steps with `assetIds`.
+- Confirm first-viewport images use the framework's priority/preload mechanism.
+- Confirm the shell warms only likely next-step images at low priority, not the
+  full funnel image set.
+- After preview or production publish, confirm build metadata includes the
+  `imageVariants` stage or name why it is unavailable.
+- In the browser/network panel, confirm AVIF/WebP variants are served when the
+  browser advertises support, with the original raster image as fallback.
+
+## 4. Paywall and Checkout (most important)
+
+Test the paywall on every QA run that touches it, pricing, discounts, or experiments — on the paywall step **and** every live paywall variant:
+
+1. **Plans render correctly** — titles, struck-through old price, discounted price, per-day price, featured/preselected plan match `src/config/billing.plans.ts` exactly. Verify discount math.
+2. **Countdown / discount state** — first-stage discount applies on open; timer counts down.
+3. **Checkout opens** — CTA opens the checkout with the selected plan; itemized totals match the selected plan and applied coupon.
+4. **Apple Pay / Google Pay buttons** — wallet slots render (Apple Pay needs Safari/iOS context, Google Pay needs Chrome; on unsupported browsers expect the documented fallback, not a broken gap). If wallets never appear in a supported context, treat as a defect.
+   **Note:** wallet buttons silently fail when the domain and checkout return URLs are not configured in the Stripe dashboard (payment method domains + return URL allowlist). New funnels and new domains must have Stripe configured before wallet QA can pass — if it is not configured, report it as a named blocker, not a pass.
+5. **Close-checkout discount** — close the checkout without paying: the special-offer dialog must appear; accepting it must apply the second-stage (larger) discount to the plan cards and the next checkout's payload. Verify the new prices and coupon id.
+6. **Test payment** — complete a payment with Stripe test card `4242 4242 4242 4242` (test mode) or the approved payment path. Confirm redirect to the subscription-started step with `user_id` preserved.
+7. **Success state** — subscription-started renders, registration/next-step handoff works.
+
+If checkout, payment mode, or test credentials are unavailable, name the skipped item explicitly — a silent skip counts as a fail.
+
+## 5. Registration and Links
+
+- Complete the registration page with valid test data; confirm validation errors on invalid data.
+- Click every legal/support/account link on paywall, checkout, and registration: terms, privacy, subscription policy, money-back, support email.
+
+## 6. Subscription Management
+
+- Open `/manage-subscription?user_id=<test-user>` (or with `stripe_customer_id`).
+- Confirm the subscription list loads and the cancellation flow completes when a test subscription is available; otherwise name it as a skipped item.
+
+## Reporting
+
+Every QA run ends with a short report: stage + URLs tested, steps/branches/variants covered, breakpoint results for small 375x667, medium 393x852, large 402x874, and desktop-small 1280x800, image optimization/preload result when relevant, paywall items 1–7 pass/fail, payment method used, console findings, and named blockers or explicitly skipped items with the reason. Blockers block production unless the user accepts the risk in so many words.