@funnelsgrove/cli 0.1.13 → 0.1.15

package/dist/cli.d.ts

@@ -17,6 +17,8 @@ type SyncTargetIdInput = {
     active?: Pick<ActiveContext, 'workspaceId' | 'funnelId'> | null;
     defaultWorkspaceId?: string;
 };
+type GeneratedConfigKind = 'offerSets' | 'experiments';
+export declare const SYNC_DOWN_GENERATED_CONFIG_KINDS: GeneratedConfigKind[];
 export declare function resolveSyncTargetIds(input: SyncTargetIdInput): {
     workspaceId: string;
     funnelId?: string;
@@ -42,5 +44,25 @@ export declare function buildPatchSourceInput(input: {
     files: SourceFile[];
     deletedPaths: string[];
 };
+export declare function buildSyncOfferSetPlansInput(input: {
+    workspaceId: string;
+    funnelId: string;
+    offerSet: string;
+}): {
+    workspaceId: string;
+    funnelId: string;
+    offerSetId?: string;
+    offerSetKey?: string;
+};
+export declare function buildGeneratedConfigSyncInput(input: {
+    workspaceId: string;
+    funnelId: string;
+    kinds: GeneratedConfigKind[];
+}): {
+    workspaceId: string;
+    funnelId: string;
+    kinds: GeneratedConfigKind[];
+};
+export declare function selectGeneratedConfigFiles(files: SourceFile[], kinds: GeneratedConfigKind[]): SourceFile[];
 export declare function assertCanDraftSyncSource(status: GitHubStatusResponse): void;
 export {};

package/dist/cli.js

@@ -38,6 +38,11 @@ const DEFAULT_API_URL = 'https://api.funnelsgrove.com/trpc';
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const PUBLISH_POLL_INTERVAL_MS = 2_000;
 const PUBLISH_WAIT_TIMEOUT_MS = 30 * 60_000;
+const GENERATED_CONFIG_PATH_BY_KIND = {
+    offerSets: 'src/config/offer-sets.generated.ts',
+    experiments: 'src/config/experiments.generated.ts',
+};
+export const SYNC_DOWN_GENERATED_CONFIG_KINDS = ['offerSets', 'experiments'];
 export function resolveSyncTargetIds(input) {
     const workspaceId = input.explicitWorkspaceId ||
         input.manifest?.workspaceId ||
@@ -83,6 +88,28 @@ export function buildPatchSourceInput(input) {
         deletedPaths: input.deletedPaths,
     };
 }
+export function buildSyncOfferSetPlansInput(input) {
+    const offerSet = input.offerSet.trim();
+    if (!offerSet) {
+        throw new Error('--offer-set is required');
+    }
+    return {
+        workspaceId: input.workspaceId,
+        funnelId: input.funnelId,
+        ...(UUID_PATTERN.test(offerSet) ? { offerSetId: offerSet } : { offerSetKey: offerSet }),
+    };
+}
+export function buildGeneratedConfigSyncInput(input) {
+    return {
+        workspaceId: input.workspaceId,
+        funnelId: input.funnelId,
+        kinds: input.kinds,
+    };
+}
+export function selectGeneratedConfigFiles(files, kinds) {
+    const allowedPaths = new Set(kinds.map((kind) => GENERATED_CONFIG_PATH_BY_KIND[kind]));
+    return files.filter((file) => allowedPaths.has(file.path));
+}
 export function assertCanDraftSyncSource(status) {
     if (status.connection && status.connection.status !== 'disconnected') {
         throw new Error('This funnel is connected to GitHub. Commit and push changes with git, then run `fgrove github pull` to sync the hosted draft. Do not use `fgrove sync up` for the same change.');
@@ -352,6 +379,22 @@ const syncGitHubDraftForCli = async (input) => {
         console.log(summary);
     }
 };
+const formatGeneratedFileCount = (count) => `${count} generated config ${count === 1 ? 'file' : 'files'}`;
+const syncGeneratedConfigFilesForCli = async (input) => {
+    const result = await callApi({
+        path: 'funnels.generatedConfigFiles',
+        type: 'query',
+        token: input.token,
+        data: buildGeneratedConfigSyncInput({
+            workspaceId: input.target.workspaceId,
+            funnelId: input.target.funnelId,
+            kinds: input.kinds,
+        }),
+    });
+    const files = selectGeneratedConfigFiles(result.files, input.kinds);
+    await writeSourceFiles(input.target.sourceDir, files);
+    return files;
+};
 const addExamples = (command, examples) => command.addHelpText('after', `\nExamples:\n${examples.map((example) => `  $ ${example}`).join('\n')}`);
 const program = new Command();
 program
@@ -525,6 +568,80 @@ addExamples(funnelsCommand
     });
     console.log(`${result.funnel.id}\t${result.funnel.name}\t${result.funnel.slug}`);
 });
+const offerSetsCommand = addExamples(program.command('offer-sets').alias('offers').description('Manage project offer sets'), [
+    'fgrove offer-sets sync --offer-set default-paywall',
+    'fgrove offers sync --funnel claimbee-ios --offer-set three-month-test',
+]);
+addExamples(offerSetsCommand
+    .command('sync')
+    .description('Apply an offer set to a funnel draft billing snapshot')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--funnel <id-or-slug>', 'Funnel id or slug')
+    .option('--dir <path>', 'Local source directory for reading sync manifest', '.')
+    .requiredOption('--offer-set <key-or-id>', 'Offer set key or id'), [
+    'fgrove offer-sets sync --offer-set default-paywall',
+    'fgrove offers sync --funnel claimbee-ios --offer-set quarterly-test',
+])
+    .action(async (options) => {
+    const token = await readAuthToken();
+    const target = await resolveSyncTarget({
+        token,
+        workspace: options.workspace,
+        funnel: options.funnel,
+        dir: options.dir,
+    });
+    const result = await callApi({
+        path: 'funnels.syncOfferSetPlans',
+        type: 'mutation',
+        token,
+        data: buildSyncOfferSetPlansInput({
+            workspaceId: target.workspaceId,
+            funnelId: target.funnelId,
+            offerSet: options.offerSet,
+        }),
+    });
+    const generatedFiles = await syncGeneratedConfigFilesForCli({
+        token,
+        target,
+        kinds: ['offerSets'],
+    });
+    await syncGitHubDraftForCli({
+        token,
+        workspaceId: target.workspaceId,
+        funnelId: target.funnelId,
+    });
+    const offerSetLabel = result.offerSet?.key || result.offerSet?.display_name || options.offerSet.trim();
+    console.log(`Synced offer set ${offerSetLabel} to funnel draft`);
+    console.log(`Wrote ${formatGeneratedFileCount(generatedFiles.length)}`);
+});
+const experimentsCommand = addExamples(program.command('experiments').description('Manage funnel experiments'), [
+    'fgrove experiments sync',
+    'fgrove experiments sync --funnel claimbee-ios',
+]);
+addExamples(experimentsCommand
+    .command('sync')
+    .description('Write generated experiment config for a funnel')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--funnel <id-or-slug>', 'Funnel id or slug')
+    .option('--dir <path>', 'Local source directory for reading sync manifest', '.'), [
+    'fgrove experiments sync',
+    'fgrove experiments sync --funnel claimbee-ios --dir ./claimbee-ios',
+])
+    .action(async (options) => {
+    const token = await readAuthToken();
+    const target = await resolveSyncTarget({
+        token,
+        workspace: options.workspace,
+        funnel: options.funnel,
+        dir: options.dir,
+    });
+    const generatedFiles = await syncGeneratedConfigFilesForCli({
+        token,
+        target,
+        kinds: ['experiments'],
+    });
+    console.log(`Wrote ${formatGeneratedFileCount(generatedFiles.length)}`);
+});
 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',
@@ -794,6 +911,11 @@ addExamples(syncCommand
     });
     await mkdir(target.sourceDir, { recursive: true });
     await writeSourceFiles(target.sourceDir, result.files);
+    const generatedFiles = await syncGeneratedConfigFilesForCli({
+        token,
+        target,
+        kinds: SYNC_DOWN_GENERATED_CONFIG_KINDS,
+    });
     await writeLocalEnvFile(target.sourceDir, result.envFile);
     await ensureGitignore(target.sourceDir);
     await writeSyncManifest(target.sourceDir, await buildSyncManifest(target.sourceDir, {
@@ -802,6 +924,7 @@ addExamples(syncCommand
         draftVersionId: result.draftVersionId,
     }));
     console.log(`Synced ${result.files.length} files to ${target.sourceDir}`);
+    console.log(`Wrote ${formatGeneratedFileCount(generatedFiles.length)}`);
 });
 const envCommand = addExamples(program.command('env').description('Manage local funnel environment files'), [
     'fgrove env pull --dir ./claimbee-ios',

package/dist/localSync.js

@@ -198,12 +198,12 @@ function formatByteSize(byteCount) {
 async function readSourceFiles(rootDir, manifestFiles) {
     const files = await Promise.all(manifestFiles.map(async (file) => {
         const absolutePath = path.join(rootDir, assertSafeSyncPath(file.path));
-        const imageContentType = inferImageContentType(file.path);
+        const binaryContentType = inferBinaryContentType(file.path);
         const buffer = await readFile(absolutePath);
         return {
             path: file.path,
-            content: imageContentType ? `data:${imageContentType};base64,${buffer.toString('base64')}` : buffer.toString('utf8'),
-            contentType: imageContentType || 'text/plain',
+            content: binaryContentType ? `data:${binaryContentType};base64,${buffer.toString('base64')}` : buffer.toString('utf8'),
+            contentType: binaryContentType || 'text/plain',
         };
     }));
     return files.sort((left, right) => left.path.localeCompare(right.path));
@@ -242,27 +242,31 @@ async function collectSyncFiles(rootDir, dir) {
 async function hashFile(filePath) {
     return createHash('sha256').update(await readFile(filePath)).digest('hex');
 }
-function inferImageContentType(filePath) {
-    const extension = path.extname(filePath).toLowerCase();
-    if (extension === '.png') {
-        return 'image/png';
-    }
-    if (extension === '.jpg' || extension === '.jpeg') {
-        return 'image/jpeg';
-    }
-    if (extension === '.webp') {
-        return 'image/webp';
-    }
-    if (extension === '.gif') {
-        return 'image/gif';
-    }
-    if (extension === '.svg') {
-        return 'image/svg+xml';
-    }
-    if (extension === '.avif') {
-        return 'image/avif';
-    }
-    return null;
+const BINARY_CONTENT_TYPE_BY_EXTENSION = {
+    '.aac': 'audio/aac',
+    '.avif': 'image/avif',
+    '.flac': 'audio/flac',
+    '.gif': 'image/gif',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.m4a': 'audio/mp4',
+    '.m4v': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.mp3': 'audio/mpeg',
+    '.mp4': 'video/mp4',
+    '.oga': 'audio/ogg',
+    '.ogg': 'audio/ogg',
+    '.ogv': 'video/ogg',
+    '.opus': 'audio/ogg',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.wav': 'audio/wav',
+    '.weba': 'audio/webm',
+    '.webm': 'video/webm',
+    '.webp': 'image/webp',
+};
+function inferBinaryContentType(filePath) {
+    return BINARY_CONTENT_TYPE_BY_EXTENSION[path.extname(filePath).toLowerCase()] || null;
 }
 function decodeDataUrl(content) {
     const match = content.trim().match(/^data:([^;,]+);base64,([A-Za-z0-9+/=\s_-]+)$/);

package/package.json

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

package/template_docs/AGENTS.md

@@ -8,7 +8,7 @@ Source-of-truth guide for editing this synced FunnelsGrove funnel. Read the matc
 | --- | --- | --- | --- |
 | 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 |
+| Set up an A/B experiment | [docs/ab-experiments.md](docs/ab-experiments.md) | FunnelsGrove UI/API + `src/config/experiments.generated.ts`; manifest steps/edges | < 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 |
@@ -63,7 +63,7 @@ with the same local source diff.
 4. **Goal-driven execution.** Define the success check before editing ("step renders at all default breakpoints 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`.
-7. **Flow labeling hygiene.** When changing `edgesByStepId`, keep manifest `branches` current for conditional paths that own steps before reconverging. Keep builder metadata ClaimBee-style and source-readable: `edgesByStepId` keys/targets and `branches: [...]` must use inline string literals, not `someStep.id` variables or a `branches: flowBranches` indirection. Each branch needs a readable `name`, answer-derived `label` such as `yes-branch`, useful `tags`, and the owned `stepIds`. Running experiment variants need labels/tags like `paywall-test-control` and `paywall-test-variant-b`; stopped A/B variants or other inactive screens should keep stable tags and remain unreachable from the default flow so builder marks them `unused`.
+7. **Flow labeling hygiene.** When changing `edgesByStepId`, keep manifest `branches` current for conditional paths that own steps before reconverging. Keep builder metadata ClaimBee-style and source-readable: `edgesByStepId` keys/targets and `branches: [...]` must use inline string literals, not `someStep.id` variables or indirection like `branches: flowBranches`. Each branch needs a readable `name`, answer-derived `label` such as `yes-branch`, useful `tags`, and the owned `stepIds`. Every experiment control or variant route target must be a real manifest step with normal outgoing edges. Prefer creating/updating experiments through the FunnelsGrove UI/API so the platform owns the database row, PostHog flag, and generated `src/config/experiments.generated.ts`; keep `src/config/experiments.ts` as the generated compatibility wrapper when possible. If a code-authored experiment is necessary, keep `sourceStepId`/`stepId`, variant labels, traffic percentages, and route target ids as explicit literals so deploy sync and analytics can import it. Running experiment variants need labels/tags like `paywall-test-control` and `paywall-test-variant-b`; stopped A/B variants or other inactive screens should keep stable tags and remain unreachable from the default flow so builder marks them `unused`.
 
 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.
 

package/template_docs/docs/ab-experiments.md

@@ -1,10 +1,53 @@
 # A/B Experiments
 
-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.
+Experiments are config, not component code. Prefer creating or updating the
+experiment through the FunnelsGrove UI/API, which owns the database row,
+PostHog flag, and generated `src/config/experiments.generated.ts` file. Keep
+`src/config/experiments.ts` as the generated compatibility wrapper when
+possible. Make sure every control or variant route target is a real manifest
+step with normal outgoing edges. Never write variant conditionals inside step
+components. If the variant step already exists, setting up the experiment is
+mostly config plus publish sync.
 
 ## Recipe: Step or Paywall Test
 
-Open `src/config/experiments.ts` and add one entry inside `defineFunnelExperiments([...])`:
+Open `src/config/funnel.manifest.ts` and make sure every control and variant
+screen exists in `steps` with readable tags:
+
+```ts
+steps: [
+  { id: 'paywall', path: '/offer', tags: ['paywall-ab-control'], /* ... */ },
+  { id: 'paywall-b', path: '/offer-b', tags: ['paywall-ab-variant-b'], /* ... */ },
+]
+```
+
+Add normal outgoing edges for both routes:
+
+```ts
+edgesByStepId: {
+  paywall: [{ toStepId: 'checkout' }],
+  'paywall-b': [{ toStepId: 'checkout' }],
+}
+```
+
+Then create the experiment in the FunnelsGrove UI/API and pull the generated
+config. The synced source should export it from `src/config/experiments.generated.ts`
+and keep `src/config/experiments.ts` as a wrapper:
+
+```ts
+import {
+  defineFunnelExperiments,
+  toManifestExperiments,
+} from '@funnelsgrove/runtime';
+import { generatedExperiments } from './experiments.generated';
+
+export const experiments = defineFunnelExperiments(generatedExperiments);
+
+export const manifestExperiments = toManifestExperiments(experiments);
+```
+
+If a code-authored experiment is necessary, add one explicit object inside the
+local experiment array or `defineFunnelExperiments([...])` call:
 
 ```ts
 export const experiments = defineFunnelExperiments([
@@ -12,23 +55,37 @@ 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
+    status: 'running',                      // non-running entries stay out of active routing
     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 },
+    stepId: 'paywall',
+    variants: [
+      { variantKey: 'control', stepId: 'paywall', label: 'paywall-ab-control', trafficPercent: 50 },
+      { variantKey: 'variant_b', stepId: 'paywall-b', label: 'paywall-ab-variant-b', trafficPercent: 50 },
+    ],
   },
 ] as const);
 ```
 
-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):
+Preconditions:
 
-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).
+1. Every control or variant `stepId` exists in the manifest `steps` array.
 2. Both steps route to the same next step, unless the experiment is explicitly about the flow.
+3. `steps`, `edgesByStepId`, experiment `stepId`, and experiment `label` values use explicit string literals that analytics can read.
+
+The manifest may keep `experiments: manifestExperiments` and import the
+runnable experiment shape from `src/config/experiments.ts`. That is fine as
+long as the separate file exports a generated wrapper or a source-readable
+`experiments` array. Do not hide step ids or labels behind computed variables.
+For route experiments where the source step differs from the rendered control
+step, set `sourceStepId` or `stepId` to the source step and set each variant's
+`stepId` to its rendered route.
 
 ## 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.
 
+Feature-flag evaluation is scoped by the public project and funnel ids (`NEXT_PUBLIC_PROJECT_ID` and `NEXT_PUBLIC_FUNNEL_ID`). The shared runtime bootstrap fills that scope from public env when callers omit it; if a local funnel owns a custom controller, keep those ids wired into PostHog flag bootstrap or verify the runtime fallback is still in place.
+
 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)
@@ -46,7 +103,8 @@ Check: opening the source URL promotes to the assigned route, each variant rende
 
 - 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.
+- Add stable variant `label` values in the `<experiment-id>-control` / `<experiment-id>-variant-b` format so builder labels and analytics views stay readable.
+- Add matching `steps[].tags` to every control and variant step.
 - 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)).

package/template_docs/docs/editing-flow.md

@@ -15,10 +15,10 @@ The manifest defines:
   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.
+- `steps`: every routable step with `id`, `path`, `filePath`, `componentKey`, `type`, optional `kind`, optional `tags`, and optional `assetIds`. This includes experiment variant screens and intentionally inactive screens that should appear as `unused` in builder. 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.
+- `experiments`: optional variant routing. This may be imported from `src/config/experiments.ts` when that file keeps source-readable experiment definitions.
 
 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`,
@@ -101,6 +101,13 @@ Experiments attach to a step and route to variant steps:
 }
 ```
 
+Keep every control and variant route target as a real step in
+`funnel.manifest.ts`. The runnable experiment entry may live in
+`src/config/experiments.ts` and be imported into the manifest as
+`experiments: manifestExperiments`; if so, keep the experiment `stepId`, labels,
+and traffic as explicit string/number literals so analytics can parse them.
+Do not hide step ids or labels behind computed variables.
+
 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.
@@ -112,6 +119,10 @@ Keep the control variant stable and do not remove a running variant until analyt
 - Add or update the manifest step.
 - Register the component in `src/runtime/step-registry.ts`.
 - Update `edgesByStepId`, `entryPoints`, `branches`, step `tags`, and `assetIds` if needed.
+- Add every experiment control and variant route target to `steps`.
+- Add normal outgoing `edgesByStepId` entries for every experiment route target.
+- Add each running experiment to `src/config/experiments.ts` or the manifest's inline `experiments` array, matching the local funnel pattern.
+- Keep experiment config synchronized with manifest steps, tags, and edges.
 - 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`.