@funnelsgrove/cli 0.1.14 → 0.1.18

package/template_validation/src/contract/validate-funnel.cli.ts

@@ -0,0 +1,199 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  CURRENT_STEP_CONTRACT_VERSION,
+  type FunnelContractDiagnostic,
+} from '@funnelsgrove/runtime';
+
+export const VALIDATOR_CONTRACT_VERSION = CURRENT_STEP_CONTRACT_VERSION;
+
+export type FunnelValidationProtocol = {
+  schemaVersion: 1;
+  contractVersion: number;
+  valid: boolean;
+  diagnostics: readonly FunnelContractDiagnostic[];
+};
+
+type LoadedValidation = {
+  contractVersion: number;
+  diagnostics: readonly FunnelContractDiagnostic[];
+};
+
+type TextWriter = (text: string) => void;
+
+export type RunValidateFunnelCliOptions = {
+  args?: readonly string[];
+  loadValidation?: () => Promise<LoadedValidation>;
+  writeStdout?: TextWriter;
+  writeStderr?: TextWriter;
+};
+
+export type FunnelValidationExitCode = 0 | 1 | 2;
+
+const internalDiagnostic = (): FunnelContractDiagnostic => ({
+  code: 'FG-CLIENT-001',
+  severity: 'error',
+  file: 'src/contract/validate-funnel.cli.ts',
+  stepId: null,
+  expected: 'loadable funnel project validation module',
+  received: 'internal validator failure',
+  reason: 'The funnel project validator could not load or run.',
+  guide: 'docs/funnelsgrove/qa/local.md',
+  repair: 'Fix project import errors, then rerun fgrove validate.',
+});
+
+const loadProjectValidation = async (): Promise<LoadedValidation> => {
+  const projectValidation = await import('./funnel-project.validation');
+  return {
+    contractVersion: projectValidation.FUNNEL_PROJECT_CONTRACT_VERSION,
+    diagnostics: projectValidation.validateFunnelProject(),
+  };
+};
+
+const describeUnknownError = (error: unknown): string => {
+  try {
+    if (error instanceof Error && error.message.trim()) {
+      return error.message;
+    }
+    return String(error);
+  } catch {
+    return 'unknown validator failure';
+  }
+};
+
+const renderValue = (value: unknown): string => {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return '[unserializable]';
+  }
+};
+
+const renderDiagnostic = (diagnostic: FunnelContractDiagnostic): string => {
+  const location = diagnostic.file
+    ? `${diagnostic.file}${diagnostic.stepId ? ` (${diagnostic.stepId})` : ''}`
+    : diagnostic.stepId ?? 'project';
+  return [
+    `[${diagnostic.code}] ${diagnostic.reason}`,
+    `  Location: ${location}`,
+    `  Expected: ${renderValue(diagnostic.expected)}`,
+    `  Received: ${renderValue(diagnostic.received)}`,
+    `  Repair: ${diagnostic.repair}`,
+    `  Guide: ${diagnostic.guide}`,
+  ].join('\n');
+};
+
+const invokeWithoutStdoutNoise = async <T>(
+  operation: () => Promise<T>,
+  writeStderr: TextWriter,
+): Promise<T> => {
+  const originalWrite = process.stdout.write;
+  let captured = '';
+  process.stdout.write = ((chunk: string | Uint8Array, ...args: unknown[]) => {
+    const encoding = typeof args[0] === 'string' ? args[0] as BufferEncoding : undefined;
+    captured += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString(encoding);
+    const callback = args.find((arg) => typeof arg === 'function');
+    if (typeof callback === 'function') {
+      callback();
+    }
+    return true;
+  }) as typeof process.stdout.write;
+
+  try {
+    return await operation();
+  } finally {
+    process.stdout.write = originalWrite;
+    if (captured) {
+      writeStderr(captured);
+      if (!captured.endsWith('\n')) {
+        writeStderr('\n');
+      }
+    }
+  }
+};
+
+const isLoadedValidation = (value: LoadedValidation): boolean => {
+  return value.contractVersion === VALIDATOR_CONTRACT_VERSION
+    && Array.isArray(value.diagnostics);
+};
+
+const emitProtocol = (
+  protocol: FunnelValidationProtocol,
+  writeStdout: TextWriter,
+): void => {
+  writeStdout(`${JSON.stringify(protocol)}\n`);
+};
+
+const protocolFor = (
+  diagnostics: readonly FunnelContractDiagnostic[],
+): FunnelValidationProtocol => ({
+  schemaVersion: 1,
+  contractVersion: VALIDATOR_CONTRACT_VERSION,
+  valid: diagnostics.length === 0,
+  diagnostics,
+});
+
+const usageError = (
+  json: boolean,
+  writeStdout: TextWriter,
+  writeStderr: TextWriter,
+): FunnelValidationExitCode => {
+  const diagnostic = internalDiagnostic();
+  writeStderr('Usage: validate-funnel.cli.ts [--json]\n');
+  if (json) {
+    emitProtocol(protocolFor([diagnostic]), writeStdout);
+  }
+  return 2;
+};
+
+export const runValidateFunnelCli = async (
+  options: RunValidateFunnelCliOptions = {},
+): Promise<FunnelValidationExitCode> => {
+  const args = options.args ?? process.argv.slice(2);
+  const writeStdout = options.writeStdout ?? ((text) => {
+    process.stdout.write(text);
+  });
+  const writeStderr = options.writeStderr ?? ((text) => {
+    process.stderr.write(text);
+  });
+  const json = args.includes('--json');
+  if (args.some((arg) => arg !== '--json') || args.filter((arg) => arg === '--json').length > 1) {
+    return usageError(json, writeStdout, writeStderr);
+  }
+
+  try {
+    const loaded = await invokeWithoutStdoutNoise(
+      options.loadValidation ?? loadProjectValidation,
+      writeStderr,
+    );
+    if (!isLoadedValidation(loaded)) {
+      throw new Error('The project validator returned an invalid protocol result.');
+    }
+
+    const protocol = protocolFor(loaded.diagnostics);
+    if (json) {
+      emitProtocol(protocol, writeStdout);
+    }
+    for (const diagnostic of loaded.diagnostics) {
+      writeStderr(`${renderDiagnostic(diagnostic)}\n`);
+    }
+    return protocol.valid ? 0 : 1;
+  } catch (error) {
+    const diagnostic = internalDiagnostic();
+    writeStderr(`Funnel validation failed internally: ${describeUnknownError(error)}\n`);
+    if (json) {
+      emitProtocol(protocolFor([diagnostic]), writeStdout);
+    }
+    return 2;
+  }
+};
+
+const isCliEntrypoint = (argv: readonly string[], modulePath: string): boolean => {
+  const resolvedModulePath = path.resolve(modulePath);
+  return path.basename(argv[1] ?? '') === 'vite-node'
+    || argv.slice(1).some((argument) => path.resolve(argument) === resolvedModulePath);
+};
+
+if (isCliEntrypoint(process.argv, fileURLToPath(import.meta.url))) {
+  process.exitCode = await runValidateFunnelCli();
+}

package/template_docs/docs/ab-experiments.md

@@ -1,55 +0,0 @@
-# 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.
-
-## Recipe: Step or Paywall Test
-
-Open `src/config/experiments.ts` and add one entry inside `defineFunnelExperiments([...])`:
-
-```ts
-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);
-```
-
-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):
-
-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.
-
-## 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)
-
-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
-
-- 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

@@ -1,65 +0,0 @@
-# Analytics
-
-Analytics should describe meaningful user behavior. `@funnelsgrove/analytics` is the tracking boundary for funnel code: it encapsulates the analytics integration for event delivery and experiment metadata.
-
-## Standard Events
-
-`FunnelFlow` tracks:
-
-- `step_start` when a step becomes active.
-- `step_end` when the user leaves a step, including the answer diff selected during that step.
-
-`@funnelsgrove/analytics` maps canonical runtime event types to provider event names:
-
-- `step_start` -> `step_started`.
-- `step_end` -> `step_completed`.
-- `funnel_start` -> `funnel_started`.
-- Successful `POST /sdk/public/users/:user_id/claim_subscription` calls emit `registration_completed` from the server.
-
-Experiment assignments are attached as feature flag properties when available. Preview runtime skips normal analytics delivery.
-
-## Standard Checkout Events
-
-Use named helpers from `@funnelsgrove/analytics` for checkout lifecycle events:
-
-```ts
-publicAnalyticsSdk.trackCheckoutStarted({
-  stepId: stepPaywallId,
-  stepName: stepPaywall.name || stepPaywall.title,
-  stepType: stepPaywall.type,
-  metadata: {
-    planId,
-    providerPlanId,
-    couponId,
-    amountCents,
-    environment,
-  },
-});
-```
-
-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
-await publicAnalyticsSdk.flush().catch(() => 0);
-```
-
-## Experiment Tracking
-
-Flow and experiment assignment are configured in `src/config/funnel.manifest.ts`, while tracking uses the analytics package. When an experiment is active, the runtime passes assignment metadata into `publicAnalyticsSdk.trackStepStarted(...)`, `trackStepCompleted(...)`, and custom events through feature flag properties.
-
-Agents should only document and verify the analytics package surface: stable event names, step ids, selected answers, checkout metadata, and experiment metadata. Treat the underlying provider as an implementation detail.
-
-Provider-specific behavior is documented separately. Read [Meta Pixel and Conversions API](meta-pixel-conversions-api.md) before changing Meta event mapping, Pixel behavior, server-side conversions, or attribution matching.
-
-## Agent Rules
-
-- Keep event names stable.
-- Count Completed Registration only from successful subscription claim requests after app login/signup.
-- Use `metadata`, `payload`, `context`, and `selected` for small analysis fields only.
-- Do not send personal data, secrets, full payment objects, SDK keys, or raw Stripe responses.
-- 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

@@ -1,125 +0,0 @@
-# Editing Flow
-
-Flow is product logic. The source of truth is `src/config/funnel.manifest.ts`; runtime helpers in `@funnelsgrove/runtime` resolve paths, edges, entry points, experiments, and browser history.
-
-## Manifest Contract
-
-The manifest defines:
-
-- `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
-
-Sequential routes use:
-
-```ts
-edgesByStepId: {
-  claim: [{ toStepId: 'profile' }],
-}
-```
-
-Conditional routes use `conditionId` values written by `goChoice(...)`. For yes/no choices the runtime expects ids like:
-
-```ts
-eligibility: [
-  { toStepId: 'active-google-claim', conditionId: 'eligibility:yes' },
-  { toStepId: 'subscriptions', conditionId: 'eligibility:no' },
-]
-```
-
-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:
-
-- `goNext()` for normal manifest progression.
-- `goChoice('yes' | 'no')` when the current branch is represented by conditional edges.
-- `goToStep(stepId)` for explicit jumps such as paywall success or manage-subscription return.
-
-Do not hardcode route strings in step logic when `getPathForStep(...)` or context navigation is available.
-
-## Experiments
-
-Experiments attach to a step and route to variant steps:
-
-```ts
-{
-  experimentId: 'paywall-ab',
-  stepId: 'paywall',
-  variants: [
-    { variantKey: 'control', routeToStepId: 'paywall' },
-    { variantKey: 'variant_b', routeToStepId: 'paywall-b' },
-  ],
-}
-```
-
-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`, `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,125 +0,0 @@
-# Adding or Editing a Step
-
-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.
-
-| # | 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 |
-
-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.
-
-## Naming and URLs
-
-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`.
-
-## Recipe: New Step
-
-Copy the closest existing step as the starting point (`step-02` for selections, `step-03` for interstitials). Then:
-
-**1. View** — `src/steps/step-07-motivation.tsx`:
-
-```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...`;
-```
-
-**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.
-
-**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).
-
-**4. Register the component** — `src/runtime/step-registry.ts`:
-
-```ts
-stepMotivation: { component: StepMotivation, meta: stepMotivation },
-```
-
-**5. Register content/editor** — `src/steps/step-content.registry.ts`:
-
-```ts
-motivation: {
-  contentPath: 'src/steps/content/step-07-motivation.content.ts',
-  editorPath: 'src/steps/editor/step-07-motivation.editor.ts',
-},
-```
-
-**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
-
-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.
-
-## Rules
-
-- 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/editor-and-content.md

@@ -1,58 +0,0 @@
-# Editor and Content
-
-Editable step content is a runtime contract. The step view should read from typed content, not from scattered hardcoded strings, when the value is copy, image, legal text, pricing label, FAQ, testimonial, or builder-editable UI.
-
-## Content Files
-
-Each step content file exports a typed `LocalizedStepContent<T>`:
-
-```ts
-export const stepContent = {
-  defaultLocale: 'en',
-  locales: {
-    en: {
-      headline: ['People getting', 'free money', 'know one secret'],
-      artwork: { src: '/figma/example.png', alt: '' },
-    },
-  },
-} as const satisfies LocalizedStepContent<StepLocaleContent>;
-```
-
-The runtime validates that a default locale exists and resolves locale from funnel attributes (`browserLanguage`, `language`, `locale`) or browser locale. In preview, builder content patches are merged before the step renders.
-
-Use runtime item types where possible:
-
-- `StepImage` for images.
-- `ChoiceItem`, `InfoItem`, `QuoteItem`, `QaItem`, `LinkItem`, `ReasonItem`, `StoreLinkItem`, `PlanPresentationItem` for lists.
-- `CountryPricingProfile` for country-specific plan ordering/defaults.
-
-## Editor Files
-
-Each editor file exports `readonly StepEditorSection[]`. A field's `path` must match the content object path:
-
-```ts
-{
-  id: 'hero.image',
-  label: 'Hero image',
-  kind: 'image',
-  path: 'hero.image',
-}
-```
-
-Supported field kinds are `text`, `textLines`, `textarea`, `image`, `boolean`, `select`, `list`, and `pricingProfile`. List fields must use a preset such as `choiceItems`, `infoItems`, `quoteItems`, `qaItems`, or `linkItems`.
-
-Only expose fields the builder should edit. Do not add spare content fields for possible future use.
-
-## Variables
-
-For builder variables, set `supportsVariables: true` on text-capable fields only. Editor variables map `user.*` tokens to answer paths, then runtime interpolation replaces `{{ user.token }}` style values in supported fields. Universal variables also support simple `{user_id}` replacement at render time.
-
-Keep variable use obvious. If a step depends on a value from an earlier step, make sure that earlier step writes a stable answer key.
-
-## Agent Rules
-
-- Keep copy, images, FAQ, testimonials, legal strings, and checkout labels in content files.
-- Keep layout decisions in the step file.
-- Keep editor sections aligned with the content shape.
-- Keep `src/steps/step-content.registry.ts` in sync when adding or renaming content/editor files.
-- Use checked-in public assets (`/paywall/...`, `/figma/...`, etc.); do not leave temporary localhost asset URLs.