@funnelsgrove/cli 0.1.2 → 0.1.4

package/dist/apiClient.js

@@ -46,6 +46,16 @@ export async function callTrpcProcedure(input) {
         ? `${baseUrl}?input=${encodeURIComponent(JSON.stringify(input.input))}`
         : baseUrl;
     const response = await fetchFn(url, init);
-    const json = await response.json();
+    const responseText = await response.text();
+    let json;
+    try {
+        json = JSON.parse(responseText);
+    }
+    catch {
+        const contentType = response.headers.get('content-type') || 'unknown content type';
+        const snippet = responseText.replace(/\s+/g, ' ').trim().slice(0, 500);
+        const details = snippet ? `: ${snippet}` : '';
+        throw new Error(`FunnelsGrove API returned ${response.status} ${response.statusText || 'Unknown status'} with ${contentType}${details}`);
+    }
     return parseTrpcJsonResponse(json);
 }

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { cp, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { createInterface } from 'node:readline/promises';
 import path from 'node:path';
@@ -6,10 +7,22 @@ import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { callTrpcProcedure } from './apiClient.js';
 import { clearActiveContext, getDefaultAuthConfigPath, loadActiveContext, loadAuthToken, saveActiveContext, saveAuthToken, } from './authStore.js';
-import { buildSyncManifest, collectSourceFiles, readSyncManifest, writeSourceFiles, writeSyncManifest, } from './localSync.js';
+import { buildSyncManifest, chunkChangedSourceFiles, collectChangedSourceFiles, collectSourceFiles, readSyncManifest, writeSourceFiles, writeSyncManifest, } from './localSync.js';
 import { isKnownTemplate, KNOWN_TEMPLATE_SLUGS, reskinFunnel } from './reskin.js';
 import { syncTemplateDocs, TEMPLATE_DOCS_DIR } from './templateDocs.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const readCliVersion = () => {
+    try {
+        const packageJson = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8'));
+        if (typeof packageJson.version === 'string' && packageJson.version.trim()) {
+            return packageJson.version;
+        }
+    }
+    catch {
+        // Fall through to the packaged fallback below.
+    }
+    return '0.1.3';
+};
 const toKebabCase = (value) => value
     .trim()
     .replace(/([a-z])([A-Z])/g, '$1-$2')
@@ -205,7 +218,7 @@ const program = new Command();
 program
     .name('fgrove')
     .description('FunnelsGrove CLI for editing, syncing, and publishing funnels')
-    .version('0.1.0')
+    .version(readCliVersion())
     .option('--api-url <url>', 'FunnelsGrove tRPC API URL', process.env.FUNNELSGROVE_API_URL || DEFAULT_API_URL)
     .option('--config <path>', 'Auth config path', process.env.FUNNELSGROVE_CONFIG || getDefaultAuthConfigPath());
 addExamples(program, [
@@ -434,24 +447,60 @@ addExamples(syncCommand
         funnel: options.funnel,
         dir: options.dir,
     });
-    const files = await collectSourceFiles(target.sourceDir);
-    const result = await callApi({
-        path: 'funnels.importSource',
-        type: 'mutation',
-        token,
-        data: {
-            workspaceId: target.workspaceId,
-            funnelId: target.funnelId,
-            message: options.message,
-            files,
-        },
-    });
+    const changes = target.manifest
+        ? await collectChangedSourceFiles(target.sourceDir, target.manifest)
+        : null;
+    if (changes && changes.files.length === 0 && changes.deletedPaths.length === 0) {
+        console.log('No local changes to sync.');
+        return;
+    }
+    let result = null;
+    let syncedFileCount = 0;
+    let deletedFileCount = 0;
+    if (changes) {
+        const batches = chunkChangedSourceFiles(changes);
+        for (const batch of batches) {
+            result = await callApi({
+                path: 'funnels.patchSource',
+                type: 'mutation',
+                token,
+                data: {
+                    workspaceId: target.workspaceId,
+                    funnelId: target.funnelId,
+                    message: options.message,
+                    files: batch.files,
+                    deletedPaths: batch.deletedPaths,
+                },
+            });
+            syncedFileCount += result.syncedFiles.length;
+            deletedFileCount += result.deletedFiles?.length || 0;
+        }
+    }
+    else {
+        result = await callApi({
+            path: 'funnels.importSource',
+            type: 'mutation',
+            token,
+            data: {
+                workspaceId: target.workspaceId,
+                funnelId: target.funnelId,
+                message: options.message,
+                files: await collectSourceFiles(target.sourceDir),
+            },
+        });
+        syncedFileCount = result.syncedFiles.length;
+        deletedFileCount = result.deletedFiles?.length || 0;
+    }
+    if (!result) {
+        throw new Error('No sync result returned.');
+    }
     await writeSyncManifest(target.sourceDir, await buildSyncManifest(target.sourceDir, {
         workspaceId: target.workspaceId,
         funnelId: target.funnelId,
         draftVersionId: result.versionId,
     }));
-    console.log(`Synced ${result.syncedFiles.length} files to draft v${result.versionSeq} (${result.versionId})`);
+    const deletedSummary = deletedFileCount > 0 ? ` and removed ${deletedFileCount} files` : '';
+    console.log(`Synced ${syncedFileCount} files${deletedSummary} to draft v${result.versionSeq} (${result.versionId})`);
 });
 addExamples(program
     .command('publish')

package/dist/localSync.d.ts

@@ -16,10 +16,22 @@ export type SourceFile = {
     content: string;
     contentType?: string;
 };
+export type ChangedSourceFiles = {
+    currentManifest: SyncManifest;
+    deletedPaths: string[];
+    files: SourceFile[];
+};
+export type SourceFilePatchBatch = {
+    deletedPaths: string[];
+    files: SourceFile[];
+};
+export declare const DEFAULT_PATCH_BATCH_CONTENT_CHARS = 12000000;
 export declare function normalizeSyncPath(filePath: string): string;
 export declare function shouldSyncFile(filePath: string): boolean;
 export declare function buildSyncManifest(rootDir: string, input: SyncManifestInput): Promise<SyncManifest>;
 export declare function writeSyncManifest(rootDir: string, manifest: SyncManifest): Promise<void>;
 export declare function readSyncManifest(rootDir: string): Promise<SyncManifest | null>;
 export declare function collectSourceFiles(rootDir: string): Promise<SourceFile[]>;
+export declare function collectChangedSourceFiles(rootDir: string, previousManifest: SyncManifest): Promise<ChangedSourceFiles>;
+export declare function chunkChangedSourceFiles(changes: Pick<ChangedSourceFiles, 'deletedPaths' | 'files'>, maxContentChars?: number): SourceFilePatchBatch[];
 export declare function writeSourceFiles(rootDir: string, files: SourceFile[]): Promise<void>;

package/dist/localSync.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 export const SYNC_MANIFEST_FILE = '.funnelsgrove-sync.json';
+export const DEFAULT_PATCH_BATCH_CONTENT_CHARS = 12_000_000;
 const EXCLUDED_PATH_PARTS = new Set(['node_modules', '.next', 'out']);
 export function normalizeSyncPath(filePath) {
     const normalized = path.posix.normalize(filePath.replaceAll('\\', '/'));
@@ -76,7 +77,58 @@ export async function collectSourceFiles(rootDir) {
         funnelId: '',
         draftVersionId: '',
     });
-    const files = await Promise.all(manifest.files.map(async (file) => {
+    return readSourceFiles(rootDir, manifest.files);
+}
+export async function collectChangedSourceFiles(rootDir, previousManifest) {
+    const currentManifest = await buildSyncManifest(rootDir, {
+        workspaceId: previousManifest.workspaceId,
+        funnelId: previousManifest.funnelId,
+        draftVersionId: previousManifest.draftVersionId,
+    });
+    const previousHashByPath = new Map(previousManifest.files.map((file) => [file.path, file.hash]));
+    const currentHashByPath = new Map(currentManifest.files.map((file) => [file.path, file.hash]));
+    const changedManifestFiles = currentManifest.files.filter((file) => previousHashByPath.get(file.path) !== file.hash);
+    const deletedPaths = previousManifest.files
+        .filter((file) => !currentHashByPath.has(file.path))
+        .map((file) => file.path)
+        .sort((left, right) => left.localeCompare(right));
+    return {
+        currentManifest,
+        deletedPaths,
+        files: await readSourceFiles(rootDir, changedManifestFiles),
+    };
+}
+export function chunkChangedSourceFiles(changes, maxContentChars = DEFAULT_PATCH_BATCH_CONTENT_CHARS) {
+    const batches = [];
+    let currentBatch = {
+        deletedPaths: changes.deletedPaths,
+        files: [],
+    };
+    let currentContentChars = 0;
+    const pushCurrentBatch = () => {
+        if (currentBatch.files.length === 0 && currentBatch.deletedPaths.length === 0) {
+            return;
+        }
+        batches.push(currentBatch);
+        currentBatch = {
+            deletedPaths: [],
+            files: [],
+        };
+        currentContentChars = 0;
+    };
+    for (const file of changes.files) {
+        if (currentBatch.files.length > 0 &&
+            currentContentChars + file.content.length > maxContentChars) {
+            pushCurrentBatch();
+        }
+        currentBatch.files.push(file);
+        currentContentChars += file.content.length;
+    }
+    pushCurrentBatch();
+    return batches;
+}
+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 buffer = await readFile(absolutePath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc",
+    "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
     "prepack": "npm run build",
     "test": "vitest run"
   },

package/template_docs/AGENTS.md

@@ -0,0 +1,102 @@
+# AGENTS.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge these rules with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## Read Docs Before Editing
+
+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.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+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.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- 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.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+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 the funnel's local checks before syncing.
+4. Run `fgrove sync up --message '<summary>'`.
+5. Run `fgrove publish --env preview --message '<summary>'` and verify the preview.
+6. Publish production only when explicitly requested.
+
+- [Editing or Creating a Step](docs/editing-step.md)
+- [Editing Flow](docs/editing-flow.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)
+- [A/B Experiments](docs/ab-experiments.md)
+- [Theme](docs/theme.md)
+- [Publishing and Versioning](docs/publishing-and-versioning.md)

package/template_docs/CLAUDE.md

@@ -0,0 +1,3 @@
+@AGENTS.md
+
+Claude Code should use `AGENTS.md` as the shared agent guidance for this synced funnel. Merge those rules with the user's current request and any project-specific instructions.

package/template_docs/docs/ab-experiments.md

@@ -1,10 +1,33 @@
 # A/B Experiments
 
-Experiments should isolate one decision and make results trustworthy.
-
-Principles:
-- Define the hypothesis before changing variants.
-- Keep assignment stable for a user during the experiment.
-- Change one major variable per experiment when possible.
-- Make variant names clear and durable.
-- Do not remove the control until results are reviewed and the rollout is approved.
+Experiments live in `src/config/funnel.manifest.ts`. They are routing rules, not ad hoc conditionals inside step components.
+
+## Runtime Contract
+
+An experiment attaches to a source step and maps variant keys to routable step ids:
+
+```ts
+{
+  experimentId: 'paywall-ab',
+  stepId: 'paywall',
+  variants: [
+    { variantKey: 'control', routeToStepId: 'paywall' },
+    { variantKey: 'variant_b', routeToStepId: 'paywall-b' },
+  ],
+}
+```
+
+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.
+
+## Editor and Preview
+
+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.
+
+## 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.

package/template_docs/docs/analytics.md

@@ -1,10 +1,58 @@
 # Analytics
 
-Analytics should describe meaningful user behavior, not implementation details.
-
-Principles:
-- Keep event names stable unless a migration is planned.
-- Track step views, key choices, checkout starts, purchases, and major errors.
-- Include only dimensions needed for analysis.
-- Do not send personal data or secrets.
-- When changing flow or offers, verify analytics still fires on the new path.
+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`.
+
+Experiment assignments are attached as feature flag properties when available. Preview runtime skips normal analytics delivery.
+
+## Custom Events
+
+Use `publicAnalyticsSdk.track(...)` from `@funnelsgrove/analytics`:
+
+```ts
+publicAnalyticsSdk.track({
+  eventType: 'checkout_started',
+  stepId: stepPaywallId,
+  stepName: stepPaywall.name || stepPaywall.title,
+  metadata: {
+    planId,
+    providerPlanId,
+    couponId,
+    amountCents,
+    environment,
+  },
+});
+```
+
+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.
+
+## Agent Rules
+
+- Keep event names stable.
+- 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.

package/template_docs/docs/editing-flow.md

@@ -1,10 +1,71 @@
 # Editing Flow
 
-The flow controls how users move between steps. Treat flow edits as product logic changes, not only UI changes.
-
-Principles:
-- Keep the happy path short and obvious.
-- Make every conditional branch easy to explain.
-- Preserve back/forward behavior when the funnel supports it.
-- Confirm that skipped steps do not leave required state missing.
-- Update analytics events when a branch, gate, or conversion path changes.
+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, usually `430 x 932`.
+- `assets`: preloaded image metadata used by runtime/build tooling.
+- `steps`: every routable step with `id`, `path`, `filePath`, `componentKey`, `type`, optional `kind`, and optional `assetIds`.
+- `edgesByStepId`: graph edges between steps.
+- `experiments`: optional variant routing.
+
+Keep `steps[].id`, `path`, and answer keys stable unless the request is a migration.
+
+## 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.
+
+## 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. 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.
+- 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,10 +1,66 @@
-# Editing a Step
+# Editing or Creating a Step
 
-A step is one screen or decision point in the funnel. Keep step changes focused: copy, layout, input behavior, validation, and navigation for that screen.
+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.
 
-Principles:
-- Preserve existing step ids and route keys unless the change is explicitly a migration.
-- Reuse existing UI components, tokens, and helper functions.
-- Keep step state local unless another step needs it.
-- Make button labels, validation messages, and analytics events match the changed user action.
-- Test the edited step directly and also test the step before and after it.
+## Source Files
+
+For an existing step, start from `src/config/funnel.manifest.ts` and find:
+
+- `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`.
+
+Most steps also have:
+
+- `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.
+
+## View Pattern
+
+Step files usually export:
+
+- 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(...)`.
+
+Use `useFunnel()` for runtime state:
+
+- `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.
+
+Do not bypass the flow controller with raw `window.location` for normal funnel navigation.
+
+## CSS Pattern
+
+Keep one-off step styling at the bottom of the step file:
+
+```tsx
+return (
+  <>
+    <section className='claimbee-step'>...</section>
+    <style>{stepStyles}</style>
+  </>
+);
+
+const stepStyles = `
+.claimbee-step { ... }
+`;
+```
+
+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.
+
+## Creating a Step
+
+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.
+
+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.

package/template_docs/docs/editor-and-content.md

@@ -1,10 +1,58 @@
 # Editor and Content
 
-Content should be editable without making the runtime fragile. Prefer existing content structures over hardcoded one-off strings.
-
-Principles:
-- Keep user-facing copy in the same content pattern the funnel already uses.
-- Use plain, direct copy for actions and error states.
-- Keep legal, pricing, and disclaimer text exact.
-- Do not add unused content fields.
-- If content is repeated across steps, centralize it only when that matches the current funnel pattern.
+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.

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

@@ -1,10 +1,53 @@
 # Payment Plans and Discounts
 
-Payment changes affect conversion, billing, and support. Keep them explicit and easy to review.
-
-Principles:
-- Treat plan ids, price ids, trial lengths, and discount codes as stable contracts.
-- Do not rename or remove a live plan unless the rollout calls for it.
-- Keep displayed price, billing period, trial text, and checkout payload in sync.
-- Test free trials, discounted offers, and default paid plans separately.
-- Update paywall copy and analytics when an offer changes.
+Payments are handled through `@funnelsgrove/payments`. Funnel steps should use the shared payment module instead of building raw Stripe calls.
+
+## Plan Sources
+
+Local plans live in `src/config/billing.plans.ts`. A plan catalog is keyed by stable funnel keys (`primary`, `secondary`, `tertiary`) and each plan includes:
+
+- `projectPlanId`: FunnelsGrove project plan id.
+- `providerPlanId`: Stripe price id.
+- `title`, `priceLabel`, `perDayAmount`, `amountCents`.
+- Optional `featuredTag`, `oldPriceLabel`, `checkoutSummaryLabel`, `billingInterval`, `billingIntervalCount`, `isDefault`.
+
+ClaimBee-style funnels may keep separate test/live catalogs with `createRuntimeModeBillingPlanCatalog(...)` and choose the active catalog through `useRuntimeMode()` plus checkout mode resolution.
+
+## Runtime Resolution
+
+Use the shared helpers:
+
+- `buildConfigPaywallPlans(...)` for local catalogs.
+- `useResolvedPaywallPlans(...)` when the funnel can load synced project Stripe plans.
+- `getDefaultPlanId(...)`, `findPaywallPlan(...)`, and `getPaywallPlanSelectionValue(...)` for selection.
+- `usePreviewStepPaywallPlans(stepId)` so builder paywall plan edits appear in preview.
+
+If a catalog is only a mapping of `{ projectPlanId }`, the payment module can load remote project plans from `/sdk/public/payments/plans` and map them back to funnel keys.
+
+## Discounts
+
+Discounts use `BillingDiscountList` or `BillingDiscountCatalog` and are resolved by `buildBillingDiscountCatalog(...)`. The current ClaimBee pattern has two stages:
+
+- First stage: coupon id, percent, duration.
+- Second stage: stronger coupon id, percent, duration, and previous percent.
+
+Use `resolvePaywallDiscountState(...)`, `advancePaywallDiscountState(...)`, `activateSecondPaywallDiscount(...)`, `serializePaywallDiscountState(...)`, and `buildDiscountedPaywallPlans(...)`. Store discount state through runtime paywall state helpers (`readPaywallStateValue`, `updatePaywallStateValue`) so it is scoped by funnel id.
+
+## Checkout
+
+Prefer shared Stripe surfaces:
+
+- `useStripeSubscriptionCheckoutSession(...)` for subscription checkout sessions.
+- `SharedStripeCheckoutV2Dialog` for card checkout UI.
+- `ApplePaySubscriptionCheckoutSlot` and `GooglePaySubscriptionCheckoutSlot` for wallet buttons.
+- `StripeExpressCheckoutButton` / `StripePlanSelector` for older paywall variants.
+
+Runtime config should come from `runtimePublicConfig` through a local `src/runtime/checkout-runtime-config.ts`. Include `apiBaseUrl`, `funnelId`, and the SDK publishable key. Preview seed keys may resolve to the preview payment key and force test checkout mode.
+
+## Agent Rules
+
+- Never change a live `projectPlanId`, `providerPlanId`, coupon id, or amount casually.
+- Keep displayed price, discounted price, amount cents, coupon id, checkout payload, and analytics metadata in sync.
+- Track checkout starts/completions with plan id, provider plan id, coupon id, amount, and environment.
+- Keep legal, renewal, guarantee, support, and button labels in content files.
+- Test test-mode and live-mode plan resolution separately when a payment change affects both.

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

@@ -1,10 +1,42 @@
 # Publishing and Versioning
 
-Syncing creates drafts. Publishing makes a draft available to users.
+Local edits are not public until they are synced and published. Sync creates or patches a draft version. Publish deploys that draft.
 
-Principles:
-- Use clear sync and publish messages so versions are reviewable.
+## CLI Flow
+
+```bash
+fgrove status
+fgrove sync up --message '<summary>'
+fgrove publish --env preview --message '<summary>'
+```
+
+Only publish production when explicitly requested:
+
+```bash
+fgrove publish --env production --domain <domain> --message '<summary>'
+```
+
+Production publish requires a domain. Preview publish returns a deployment URL, version sequence, and version id.
+
+## 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.
+
+Local-only files are excluded from upload:
+
+- `.env`, `.env.local`, `.env.*` except `.env.example`.
+- `.funnelsgrove-sync.json`.
+- `node_modules`.
+- `.next`.
+- `out`.
+
+Do not edit generated build output as the source of truth.
+
+## Agent Rules
+
+- Run `fgrove status` before syncing.
+- Use clear sync and publish messages.
+- Sync before publishing.
 - Publish preview first and verify the returned URL.
-- Production publish requires an explicit production request and target domain.
-- Keep `.funnelsgrove-sync.json` in the local tree; it records the synced draft.
-- If preview verification fails, fix locally, sync up again, and publish a new preview.
+- If preview verification fails, fix locally, run checks, sync up again, and publish a new preview.
+- Do not production publish without explicit instruction and target domain.

package/template_docs/docs/sdk-api-endpoints.md

@@ -1,10 +1,46 @@
 # SDK API Endpoints
 
-SDK calls should be thin, typed boundaries between the funnel and FunnelsGrove services.
-
-Principles:
-- Reuse existing SDK helpers instead of calling raw endpoints directly.
-- Keep request payloads minimal and typed.
-- Handle loading, retryable errors, and final failure states in the UI.
-- Avoid logging personal data, payment data, or secrets.
-- When an endpoint contract changes, update the caller, tests, and docs together.
+Funnel code should call shared runtime/payment/analytics services, not raw endpoints, unless a new shared helper is being built.
+
+## Runtime Config
+
+`@funnelsgrove/runtime` reads public config from env aliases and exposes `runtimePublicConfig`:
+
+- SDK API base URL.
+- funnel id and funnel version id.
+- SDK publishable key.
+- project id and analytics provider key.
+- support/legal/app-store/deep-link metadata.
+
+`buildMainApiUrl(...)` and `buildSdkHeaders(...)` add the correct SDK base URL and `x-sdk-publishable-key`. Preview frame runtime intentionally suppresses normal SDK calls.
+
+## User and State APIs
+
+Use `apiService` from `@funnelsgrove/runtime`:
+
+- `bootstrapSession(...)`: create/restore the visitor using local user id, URL `user_id`, attribution, email, or name.
+- `updateUser(...)`: persist email/name/progress attributes.
+- `uploadTempPhoto(...)`: upload or locally preview image captures.
+- `getManageSubscriptions()` and `updateSubscription(...)`: subscription management by `user_id` or `stripe_customer_id`.
+- `trackFunnelEvent(...)`, `trackStepStarted(...)`, `trackStepCompleted(...)`: legacy runtime event delivery.
+
+The flow controller already bootstraps the user, persists answer attributes, records completed steps, and connects analytics identity through the shared analytics/runtime integration. Steps should only call `apiService.updateUser(...)` directly when they collect profile data such as checkout email.
+
+## Payment APIs
+
+Use `@funnelsgrove/payments`:
+
+- `getPaywallPlans(...)` / `useResolvedPaywallPlans(...)` for `/sdk/public/payments/plans`.
+- `createStripePaymentIntent(...)` for payment intents.
+- `createStripeSubscriptionCheckout(...)` for subscription Elements checkout.
+- `createStripeCheckoutSession(...)` or `redirectToStripeCheckout(...)` for hosted checkout.
+
+Always pass runtime checkout config so published funnels, preview funnels, and local builds resolve the correct funnel id and SDK key.
+
+## Rules
+
+- Keep payloads minimal and typed.
+- Do not log personal data, payment details, SDK keys, or Stripe secrets.
+- Handle loading, unavailable config, API failure, and final failure states in UI.
+- Use local fallbacks only where the shared service already supports them.
+- If an endpoint contract changes, update the shared service, callers, tests, and these docs together.

package/template_docs/docs/theme.md

@@ -1,10 +1,35 @@
 # Theme
 
-Theme changes should make the funnel feel consistent, not create one-off styling.
-
-Principles:
-- Use existing tokens for colors, spacing, typography, and radius.
-- Keep contrast readable across all important states.
-- Check mobile and desktop layouts after theme edits.
-- Avoid changing component internals for a theme-only request.
-- Update shared theme values when the same style appears in multiple places.
+Theme is a runtime contract in `src/theme/theme.ts`. It is converted to CSS variables by `createThemeCssVariables(...)` from `@funnelsgrove/runtime`.
+
+## Theme Contract
+
+The theme owns:
+
+- Interface colors: `background`, `primary`, `primaryText`, `secondary`, `secondaryText`, `text`.
+- Semantic colors: `button`, `buttonText`, `surface`, `border`, `warning`, `danger`.
+- Derived colors: muted/success/warning/danger/neutral backgrounds, muted text, soft accents.
+- Typography: font family, weights, sizes, line heights.
+- Device shell: active preset, shell width, max width, padding, corner radius.
+- Safe area offsets.
+
+The generated CSS vars include `--color-bg`, `--color-primary`, `--color-secondary`, `--color-text`, `--font-family-base`, `--padding`, `--corner-radius`, and shell sizing vars.
+
+## Styling Rules
+
+- Use CSS variables in step CSS and shared CSS.
+- Use `src/app/globals.css` only for global reset, fonts, and body/root behavior.
+- Use `src/steps/styles/shared/` for repeated step patterns.
+- Keep one-off styles inside the step file at the bottom.
+- Keep the designed shell stable unless the request is explicitly about device size.
+
+ClaimBee-style funnels use a 430px mobile shell, Inter, and product colors through theme variables. If changing brand colors, update `theme.ts` first and only add local CSS overrides when the layout genuinely needs them.
+
+## Verification
+
+After theme edits, check:
+
+- Main happy path.
+- Paywall and checkout states.
+- Mobile shell and desktop centered preview.
+- Contrast for primary buttons, secondary accents, disabled/loading states, and error text.

package/template_docs/agent.md

@@ -1,24 +0,0 @@
-# Funnel Editing Guide
-
-Use this folder as the local source-of-truth guide when editing a synced FunnelsGrove funnel.
-
-## Workflow
-
-1. Run `fgrove status` and confirm the active project and funnel.
-2. Keep edits inside the synced funnel tree.
-3. Run the funnel's local checks before syncing.
-4. Run `fgrove sync up --message '<summary>'`.
-5. Run `fgrove publish --env preview --message '<summary>'` and verify the preview.
-6. Publish production only when explicitly requested.
-
-## Topics
-
-- [Editing a Step](docs/editing-step.md)
-- [Editing Flow](docs/editing-flow.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)
-- [A/B Experiments](docs/ab-experiments.md)
-- [Theme](docs/theme.md)
-- [Publishing and Versioning](docs/publishing-and-versioning.md)