@funnelsgrove/cli 0.1.9 → 0.1.11

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
-import { cp, mkdir } from 'node:fs/promises';
+import { readFileSync, realpathSync } from 'node:fs';
+import { cp, mkdir, writeFile } from 'node:fs/promises';
 import { createInterface } from 'node:readline/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -13,6 +13,7 @@ import { formatGitHubConnectRows, formatGitHubJobRows, formatGitHubStatusRows, }
 import { syncGitHubDraftIfConnected } from './githubSyncFlow.js';
 import { isKnownTemplate, KNOWN_TEMPLATE_SLUGS, reskinFunnel } from './reskin.js';
 import { syncTemplateDocs, TEMPLATE_DOCS_DIR } from './templateDocs.js';
+import { assertHasCohortData, assertHasConversionData, assertHasFunnelPathData, assertHasTransitionData, buildCohortReportPayload, buildConversionReportPayload, buildFunnelPathReportPayload, buildTransitionReportPayload, formatAnalyticsJson, formatCohortTable, formatConversionsTable, formatFunnelPathTable, formatTransitionsTable, normalizeAnalyticsOutputFormat, parseAnalyticsDate, } from './analyticsOutput.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const readCliVersion = () => {
     try {
@@ -50,6 +51,28 @@ export function resolveSyncTargetIds(input) {
         funnelId: input.explicitFunnelId || input.manifest?.funnelId || input.active?.funnelId,
     };
 }
+export function isCliEntrypoint(invokedPath, modulePath, realpath = realpathSync) {
+    if (!invokedPath) {
+        return false;
+    }
+    try {
+        return realpath(path.resolve(invokedPath)) === realpath(modulePath);
+    }
+    catch {
+        return path.resolve(invokedPath) === path.resolve(modulePath);
+    }
+}
+export function buildAnalyticsCommandInput(options) {
+    const parsedDate = parseAnalyticsDate(options.date);
+    const timezone = options.timezone?.trim() || undefined;
+    return {
+        date: parsedDate.date,
+        from: parsedDate.fromIso,
+        to: parsedDate.toIso,
+        format: normalizeAnalyticsOutputFormat(options.format),
+        timezone,
+    };
+}
 const getApiUrl = () => {
     const options = program.opts();
     return options.apiUrl || process.env.FUNNELSGROVE_API_URL || DEFAULT_API_URL;
@@ -253,6 +276,34 @@ const resolveSyncTarget = async (input) => {
         manifest,
     };
 };
+const resolveAnalyticsProject = async (input) => {
+    const active = await loadActiveContext(getConfigPath());
+    const project = input.project || (active?.workspaceId === input.workspaceId ? active.projectId : undefined);
+    if (!project) {
+        throw new Error('No project selected. Pass `--project <id-or-slug>` or set one with `fgrove use --project <id-or-slug>`.');
+    }
+    return resolveProject(input.token, input.workspaceId, project);
+};
+const resolveAnalyticsFunnel = async (input) => {
+    const active = await loadActiveContext(getConfigPath());
+    const funnel = input.funnel || (active?.workspaceId === input.workspaceId ? active.funnelId : undefined);
+    if (!funnel) {
+        throw new Error('No funnel selected. Pass `--funnel <id-or-slug>` or set one with `fgrove use --funnel <id-or-slug>`.');
+    }
+    return resolveFunnel(input.token, input.workspaceId, funnel);
+};
+const writeOrPrintAnalyticsOutput = async (input) => {
+    const output = input.format === 'json'
+        ? formatAnalyticsJson(input.payload)
+        : input.table;
+    if (input.out?.trim()) {
+        const outputPath = path.resolve(process.cwd(), input.out);
+        await writeFile(outputPath, output, 'utf8');
+        console.log(`Wrote ${outputPath}`);
+        return;
+    }
+    process.stdout.write(output);
+};
 const printRows = (rows, columns) => {
     for (const row of rows) {
         console.log(columns.map((column) => row[column] || '').join('\t'));
@@ -459,6 +510,240 @@ addExamples(funnelsCommand
     });
     console.log(`${result.funnel.id}\t${result.funnel.name}\t${result.funnel.slug}`);
 });
+const analyticsCommand = addExamples(program.command('analytics').description('Download and inspect project analytics'), [
+    'fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json --out analytics.json',
+    'fgrove analytics funnel-path --project claimbee --funnel claimbee-ios --date 2026-06-11',
+    'fgrove analytics transitions --project claimbee --funnel claimbee-ios --date 2026-06-11',
+    'fgrove analytics cohort --project claimbee --date 2026-06-11 --format json',
+]);
+const loadFunnelAnalyticsContext = async (options) => {
+    const token = await readAuthToken();
+    const workspace = await resolveWorkspace(token, options.workspace);
+    const project = await resolveAnalyticsProject({
+        token,
+        workspaceId: workspace.id,
+        project: options.project,
+    });
+    const funnel = await resolveAnalyticsFunnel({
+        token,
+        workspaceId: workspace.id,
+        funnel: options.funnel,
+    });
+    return {
+        token,
+        workspace,
+        project,
+        funnel,
+        commandInput: buildAnalyticsCommandInput(options),
+    };
+};
+const loadProjectAnalyticsContext = async (options) => {
+    const token = await readAuthToken();
+    const workspace = await resolveWorkspace(token, options.workspace);
+    const project = await resolveAnalyticsProject({
+        token,
+        workspaceId: workspace.id,
+        project: options.project,
+    });
+    return {
+        token,
+        workspace,
+        project,
+        commandInput: buildAnalyticsCommandInput(options),
+    };
+};
+const fetchStepDropoffAnalytics = async (input) => {
+    return callApi({
+        path: 'projects.analyticsStepDropoff',
+        type: 'query',
+        token: input.token,
+        data: {
+            workspaceId: input.workspaceId,
+            projectId: input.projectId,
+            funnelId: input.funnelId,
+            from: input.commandInput.from,
+            to: input.commandInput.to,
+            timezone: input.commandInput.timezone,
+        },
+    });
+};
+addExamples(analyticsCommand
+    .command('conversions')
+    .description('Download one-day conversion data, full funnel path, and step transitions')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
+    .option('--funnel <id-or-slug-or-name>', 'Funnel id, slug, or name')
+    .requiredOption('--date <yyyy-mm-dd>', 'Analytics date')
+    .option('--format <table-or-json>', 'Output format: table or json', 'table')
+    .option('--out <path>', 'Write output to a file')
+    .option('--timezone <iana-timezone>', 'Analytics timezone, for example America/Los_Angeles'), [
+    'fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11',
+    'fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json --out analytics.json',
+])
+    .action(async (options) => {
+    const context = await loadFunnelAnalyticsContext(options);
+    const [overview, stepDropoff] = await Promise.all([
+        callApi({
+            path: 'projects.analyticsOverview',
+            type: 'query',
+            token: context.token,
+            data: {
+                workspaceId: context.workspace.id,
+                projectId: context.project.id,
+                funnelId: context.funnel.id,
+                from: context.commandInput.from,
+                to: context.commandInput.to,
+                timezone: context.commandInput.timezone,
+                limit: 20_000,
+            },
+        }),
+        fetchStepDropoffAnalytics({
+            token: context.token,
+            workspaceId: context.workspace.id,
+            projectId: context.project.id,
+            funnelId: context.funnel.id,
+            commandInput: context.commandInput,
+        }),
+    ]);
+    assertHasConversionData(context.commandInput.date, overview, stepDropoff);
+    const payload = buildConversionReportPayload({
+        date: context.commandInput.date,
+        workspaceId: context.workspace.id,
+        project: context.project,
+        overview,
+        stepDropoff,
+    });
+    await writeOrPrintAnalyticsOutput({
+        format: context.commandInput.format,
+        payload,
+        table: formatConversionsTable({
+            date: context.commandInput.date,
+            overview,
+            stepDropoff,
+        }),
+        out: options.out,
+    });
+});
+addExamples(analyticsCommand
+    .command('funnel-path')
+    .description('Download the full one-day funnel path report')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
+    .option('--funnel <id-or-slug-or-name>', 'Funnel id, slug, or name')
+    .requiredOption('--date <yyyy-mm-dd>', 'Analytics date')
+    .option('--format <table-or-json>', 'Output format: table or json', 'table')
+    .option('--out <path>', 'Write output to a file')
+    .option('--timezone <iana-timezone>', 'Analytics timezone, for example America/Los_Angeles'), [
+    'fgrove analytics funnel-path --project claimbee --funnel claimbee-ios --date 2026-06-11',
+    'fgrove analytics funnel-path --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json',
+])
+    .action(async (options) => {
+    const context = await loadFunnelAnalyticsContext(options);
+    const stepDropoff = await fetchStepDropoffAnalytics({
+        token: context.token,
+        workspaceId: context.workspace.id,
+        projectId: context.project.id,
+        funnelId: context.funnel.id,
+        commandInput: context.commandInput,
+    });
+    assertHasFunnelPathData(context.commandInput.date, stepDropoff);
+    const payload = buildFunnelPathReportPayload({
+        date: context.commandInput.date,
+        workspaceId: context.workspace.id,
+        project: context.project,
+        stepDropoff,
+    });
+    await writeOrPrintAnalyticsOutput({
+        format: context.commandInput.format,
+        payload,
+        table: formatFunnelPathTable({
+            date: context.commandInput.date,
+            stepDropoff,
+        }),
+        out: options.out,
+    });
+});
+addExamples(analyticsCommand
+    .command('transitions')
+    .description('Download one-day step transitions and drop-offs')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
+    .option('--funnel <id-or-slug-or-name>', 'Funnel id, slug, or name')
+    .requiredOption('--date <yyyy-mm-dd>', 'Analytics date')
+    .option('--format <table-or-json>', 'Output format: table or json', 'table')
+    .option('--out <path>', 'Write output to a file')
+    .option('--timezone <iana-timezone>', 'Analytics timezone, for example America/Los_Angeles'), [
+    'fgrove analytics transitions --project claimbee --funnel claimbee-ios --date 2026-06-11',
+    'fgrove analytics transitions --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json',
+])
+    .action(async (options) => {
+    const context = await loadFunnelAnalyticsContext(options);
+    const stepDropoff = await fetchStepDropoffAnalytics({
+        token: context.token,
+        workspaceId: context.workspace.id,
+        projectId: context.project.id,
+        funnelId: context.funnel.id,
+        commandInput: context.commandInput,
+    });
+    assertHasTransitionData(context.commandInput.date, stepDropoff);
+    const payload = buildTransitionReportPayload({
+        date: context.commandInput.date,
+        workspaceId: context.workspace.id,
+        project: context.project,
+        stepDropoff,
+    });
+    await writeOrPrintAnalyticsOutput({
+        format: context.commandInput.format,
+        payload,
+        table: formatTransitionsTable({
+            date: context.commandInput.date,
+            stepDropoff,
+        }),
+        out: options.out,
+    });
+});
+addExamples(analyticsCommand
+    .command('cohort')
+    .description('Download one-day cohort marketing data')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
+    .requiredOption('--date <yyyy-mm-dd>', 'Cohort date')
+    .option('--format <table-or-json>', 'Output format: table or json', 'table')
+    .option('--out <path>', 'Write output to a file')
+    .option('--timezone <iana-timezone>', 'Reserved for consistency with conversion commands'), [
+    'fgrove analytics cohort --project claimbee --date 2026-06-11',
+    'fgrove analytics cohort --project claimbee --date 2026-06-11 --format json --out cohort.json',
+])
+    .action(async (options) => {
+    const context = await loadProjectAnalyticsContext(options);
+    const cohort = await callApi({
+        path: 'projects.marketingCohortPerformance',
+        type: 'query',
+        token: context.token,
+        data: {
+            workspaceId: context.workspace.id,
+            projectId: context.project.id,
+            from: context.commandInput.date,
+            to: context.commandInput.date,
+        },
+    });
+    assertHasCohortData(context.commandInput.date, cohort);
+    const payload = buildCohortReportPayload({
+        date: context.commandInput.date,
+        workspaceId: context.workspace.id,
+        project: context.project,
+        cohort,
+    });
+    await writeOrPrintAnalyticsOutput({
+        format: context.commandInput.format,
+        payload,
+        table: formatCohortTable({
+            date: context.commandInput.date,
+            cohort,
+        }),
+        out: options.out,
+    });
+});
 const syncCommand = addExamples(program.command('sync').description('Sync funnel source'), [
     'fgrove sync down --funnel claimbee-ios --dir ./claimbee-ios',
     'fgrove sync up --message "Update copy"',
@@ -845,7 +1130,7 @@ addExamples(program
     console.log('  npm install');
     console.log('  npm run dev');
 });
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isCliEntrypoint(process.argv[1], fileURLToPath(import.meta.url))) {
     program.parseAsync().catch((error) => {
         console.error(error instanceof Error ? error.message : String(error));
         process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
   "type": "module",
   "bin": {

package/template_docs/AGENTS.md

@@ -1,107 +1,56 @@
 # AGENTS.md
 
-Behavioral guidelines to reduce common LLM coding mistakes. Merge these rules with project-specific instructions as needed.
+Source-of-truth guide for editing this synced FunnelsGrove funnel. Read the matching topic doc before editing; the docs define the contracts the runtime expects.
 
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+## Find Your Task
 
-## Read Docs Before Editing
+| Task | Read | Edit | Target time |
+| --- | --- | --- | --- |
+| Add or edit a step | [docs/editing-step.md](docs/editing-step.md) + [docs/step-ui-guidelines.md](docs/step-ui-guidelines.md) | `src/steps/*` + registries + manifest | < 3 min to first preview |
+| Change step order / branching | [docs/editing-flow.md](docs/editing-flow.md) | `src/config/funnel.manifest.ts` | < 2 min |
+| Set up an A/B experiment | [docs/ab-experiments.md](docs/ab-experiments.md) | `src/config/experiments.ts` | < 1 min when variant step exists |
+| Edit copy or images | [docs/editor-and-content.md](docs/editor-and-content.md) | `src/steps/content/*.content.ts` | < 2 min |
+| Edit image loading/performance | [docs/editing-flow.md](docs/editing-flow.md) + [docs/step-ui-guidelines.md](docs/step-ui-guidelines.md) + [docs/publishing-and-versioning.md](docs/publishing-and-versioning.md) | `src/config/funnel.manifest.ts`, `src/components/FunnelFlow.tsx`, image assets | careful, QA required |
+| Change plans, prices, discounts | [docs/payment-plans-and-discounts.md](docs/payment-plans-and-discounts.md) | `src/config/billing.plans.ts` | careful, read doc fully |
+| Edit paywall or checkout | [docs/payment-plans-and-discounts.md](docs/payment-plans-and-discounts.md) + [docs/step-ui-guidelines.md](docs/step-ui-guidelines.md) | `src/steps/step-32-paywall*.tsx` | careful, QA required |
+| Change colors / fonts | [docs/theme.md](docs/theme.md) | `src/theme/theme.ts` | < 2 min |
+| QA before publish | [docs/qa-checklist.md](docs/qa-checklist.md) | nothing — test and report | as long as it takes |
+| Publish | [docs/publishing-and-versioning.md](docs/publishing-and-versioning.md) | nothing — `fgrove` commands | — |
 
-Before changing any funnel file, read the relevant topic docs in this folder and follow their contracts. Make the edit according to those docs first; if the requested change conflicts with the docs, stop and explain the conflict before editing.
+Deep dives: [Funnel Runtime Architecture](docs/funnel-runtime-architecture.md), [SDK API Endpoints](docs/sdk-api-endpoints.md), [Analytics](docs/analytics.md), [Meta Pixel and Conversions API](docs/meta-pixel-conversions-api.md).
 
-Architecture docs are part of the change. When you change funnel routing, runtime state, SDK API contracts, URL handoff parameters, checkout/subscription behavior, analytics events, environment config, or shared package boundaries, update `template_docs` in the same change so future agents inherit the new contract.
+## Architecture in 30 Seconds
 
-## 1. Think Before Coding
+The funnel is a small Next.js app on shared packages:
 
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
+- `@funnelsgrove/runtime` — routing, user state, content localization, builder preview, theme.
+- `@funnelsgrove/analytics` — event tracking and A/B assignment (wraps PostHog; never call PostHog directly).
+- `@funnelsgrove/payments` — plans, discounts, Stripe checkout, wallet buttons, shared checkout UI.
+- This repo — product decisions only: step views, content, editor fields, flow manifest, theme, assets, plan ids.
 
-Before implementing:
-- State your assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them. Do not pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
+Most edits touch one step file plus its matching `content/` and `editor/` files, or one config file. If an edit spreads wider than that, stop and re-read the topic doc.
 
-## 2. Simplicity First
+## Standard Workflow
 
-**Minimum code that solves the problem. Nothing speculative.**
+1. `fgrove status` — confirm the active project and funnel.
+2. Make the scoped edit per the topic doc.
+3. `npm run test:run && npm run lint` (or the checks this tree defines).
+4. `npm run dev` — verify in local preview at 430x932, spot-check 390x844 ([docs/step-ui-guidelines.md](docs/step-ui-guidelines.md)).
+5. Run the relevant part of [docs/qa-checklist.md](docs/qa-checklist.md).
+6. Ask the user before publishing. Then `fgrove sync up --message '<summary>'` and `fgrove publish --env preview --message '<summary>'`.
+7. QA the preview URL. Production publish only on explicit request, after preview QA.
 
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No flexibility or configurability that was not requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
+`fgrove env pull` refreshes the local `.env` when remote project settings changed.
 
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+## Behavioral Rules
 
-## 3. Surgical Changes
+1. **Think before coding.** State assumptions. If multiple interpretations exist, present them — don't pick silently. If something is unclear, ask before editing.
+2. **Simplicity first.** Minimum code that solves the problem. No speculative abstractions, options, or error handling for impossible states.
+3. **Surgical changes.** Touch only what the request requires. Match existing style. Remove only orphans your own change created. Every changed line should trace to the request.
+4. **Goal-driven execution.** Define the success check before editing ("step renders at both viewports and Continue advances to step-X"), then loop until it passes.
+5. **Image performance locked.** Keep build-time raster compression plus AVIF/WebP variants enabled. For funnel step images, use `funnelManifest.assets` + step `assetIds`, priority/preload only for first-viewport images, and low-priority next-step warming from the shell. Do not preload the whole funnel image set.
+6. **Meaningful URLs.** New step `path` values are public product routes, so use readable slugs like `/motivation`, `/fitness-goal`, or `/email-capture`. Sequential ids and `step-NN-*` filenames are okay for ordering, but do not create public routes like `/step-1`.
 
-**Touch only what you must. Clean up only your own mess.**
+Architecture docs are part of the change: if you change routing, runtime state, SDK contracts, URL handoff parameters, checkout behavior, analytics events, or shared package boundaries, update the matching doc in the same change.
 
-When editing existing code:
-- Do not improve adjacent code, comments, or formatting.
-- Do not refactor things that are not broken.
-- Match existing style, even if you would do it differently.
-- If you notice unrelated dead code, mention it. Do not delete it.
-
-When your changes create orphans:
-- Remove imports, variables, functions, and files that your changes made unused.
-- Do not remove pre-existing dead code unless asked.
-
-The test: every changed line should trace directly to the user's request.
-
-## 4. Goal-Driven Execution
-
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
-- "Add validation" -> "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" -> "Write a test that reproduces it, then make it pass"
-- "Refactor X" -> "Ensure tests pass before and after"
-
-For multi-step tasks, state a brief plan:
-
-```text
-1. [Step] -> verify: [check]
-2. [Step] -> verify: [check]
-3. [Step] -> verify: [check]
-```
-
-Strong success criteria let you loop independently. Weak criteria like "make it work" require constant clarification.
-
----
-
-**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
-
-## Documentation Index
-
-Use this folder as the local source-of-truth guide when editing a synced FunnelsGrove funnel.
-
-Current funnel templates are small Next.js apps built on shared runtime modules:
-
-- `@funnelsgrove/runtime` owns the funnel contract: routing, user state, content localization, builder preview patches, subscriptions, analytics helpers, runtime env, and theme variables.
-- `@funnelsgrove/analytics` owns analytics tracking and A/B experiment tracking. It encapsulates the PostHog integration so funnel steps do not call PostHog directly.
-- `@funnelsgrove/payments` owns checkout plans, discounts, Stripe sessions/intents, wallet slots, and shared checkout UI.
-- The local funnel owns product decisions: step views, content files, editor fields, flow manifest, theme, checked-in assets, and billing plan ids.
-
-Keep changes simple and local. Most edits should touch one step file plus its matching `content/` and `editor/` files, or one manifest/config file for flow, theme, or billing changes.
-
-## Funnel Workflow
-
-1. Run `fgrove status` and confirm the active project and funnel.
-2. Keep edits inside the synced funnel tree.
-3. Run `fgrove env pull` when remote project settings changed and you need the latest local `.env`.
-4. Run the funnel's local checks before syncing.
-5. Run `fgrove sync up --message '<summary>'`.
-6. Run `fgrove publish --env preview --message '<summary>'` and verify the preview.
-7. Publish production only when explicitly requested.
-
-- [Editing or Creating a Step](docs/editing-step.md)
-- [Editing Flow](docs/editing-flow.md)
-- [Funnel Runtime Architecture](docs/funnel-runtime-architecture.md)
-- [Editor and Content](docs/editor-and-content.md)
-- [Payment Plans and Discounts](docs/payment-plans-and-discounts.md)
-- [SDK API Endpoints](docs/sdk-api-endpoints.md)
-- [Analytics](docs/analytics.md)
-- [Meta Pixel and Conversions API](docs/meta-pixel-conversions-api.md)
-- [A/B Experiments](docs/ab-experiments.md)
-- [Theme](docs/theme.md)
-- [Publishing and Versioning](docs/publishing-and-versioning.md)
+Preserve existing step ids, paths, and answer keys unless the task is an explicit migration — they feed routes, persisted answers, analytics, and publish history.

package/template_docs/docs/ab-experiments.md

@@ -1,33 +1,52 @@
 # 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', trafficPercent: 50 },
+    variant: { stepId: 'paywall-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.
+- 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/editing-flow.md

@@ -7,14 +7,20 @@ 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`.
+- `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`, 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.
 - `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
 
@@ -62,12 +68,21 @@ 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.
+- 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.