@funnelsgrove/cli 0.1.10 → 0.1.12

package/dist/cli.js

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 import { readFileSync, realpathSync } from 'node:fs';
-import { cp, mkdir } from 'node:fs/promises';
+import { cp, mkdir, writeFile } from 'node:fs/promises';
 import { createInterface } from 'node:readline/promises';
 import path from 'node:path';
 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, chunkChangedSourceFiles, collectChangedSourceFiles, collectSourceFiles, ensureGitignore, formatSyncUploadSummary, readSyncManifest, writeLocalEnvFile, writeSourceFiles, writeSyncManifest, } from './localSync.js';
+import { buildSyncManifest, chunkChangedSourceFiles, collectChangedSourceFiles, collectSourceFiles, ensureGitignore, formatSyncUploadSummary, hasLocalSourceChanges, readSyncManifest, writeLocalEnvFile, writeSourceFiles, writeSyncManifest, } from './localSync.js';
 import { pullEnvFile } from './envSync.js';
 import { formatGitHubConnectRows, formatGitHubJobRows, formatGitHubStatusRows, } from './githubOutput.js';
 import { syncGitHubDraftIfConnected } from './githubSyncFlow.js';
 import { isKnownTemplate, KNOWN_TEMPLATE_SLUGS, reskinFunnel } from './reskin.js';
 import { syncTemplateDocs, TEMPLATE_DOCS_DIR } from './templateDocs.js';
+import { assertHasCohortData, assertHasConversionData, assertHasFunnelPathData, assertHasTransitionData, buildCohortReportPayload, buildConversionReportPayload, buildFunnelPathReportPayload, buildTransitionReportPayload, formatAnalyticsJson, formatCohortTable, formatConversionsTable, formatFunnelPathTable, formatTransitionsTable, normalizeAnalyticsOutputFormat, parseAnalyticsDate, } from './analyticsOutput.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const readCliVersion = () => {
     try {
@@ -61,6 +62,32 @@ export function isCliEntrypoint(invokedPath, modulePath, realpath = realpathSync
         return path.resolve(invokedPath) === path.resolve(modulePath);
     }
 }
+export function buildAnalyticsCommandInput(options) {
+    const parsedDate = parseAnalyticsDate(options.date);
+    const timezone = options.timezone?.trim() || undefined;
+    return {
+        date: parsedDate.date,
+        from: parsedDate.fromIso,
+        to: parsedDate.toIso,
+        format: normalizeAnalyticsOutputFormat(options.format),
+        timezone,
+    };
+}
+export function buildPatchSourceInput(input) {
+    return {
+        workspaceId: input.workspaceId,
+        funnelId: input.funnelId,
+        message: input.message,
+        baseDraftVersionId: input.baseDraftVersionId,
+        files: input.files,
+        deletedPaths: input.deletedPaths,
+    };
+}
+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.');
+    }
+}
 const getApiUrl = () => {
     const options = program.opts();
     return options.apiUrl || process.env.FUNNELSGROVE_API_URL || DEFAULT_API_URL;
@@ -264,6 +291,34 @@ const resolveSyncTarget = async (input) => {
         manifest,
     };
 };
+const resolveAnalyticsProject = async (input) => {
+    const active = await loadActiveContext(getConfigPath());
+    const project = input.project || (active?.workspaceId === input.workspaceId ? active.projectId : undefined);
+    if (!project) {
+        throw new Error('No project selected. Pass `--project <id-or-slug>` or set one with `fgrove use --project <id-or-slug>`.');
+    }
+    return resolveProject(input.token, input.workspaceId, project);
+};
+const resolveAnalyticsFunnel = async (input) => {
+    const active = await loadActiveContext(getConfigPath());
+    const funnel = input.funnel || (active?.workspaceId === input.workspaceId ? active.funnelId : undefined);
+    if (!funnel) {
+        throw new Error('No funnel selected. Pass `--funnel <id-or-slug>` or set one with `fgrove use --funnel <id-or-slug>`.');
+    }
+    return resolveFunnel(input.token, input.workspaceId, funnel);
+};
+const writeOrPrintAnalyticsOutput = async (input) => {
+    const output = input.format === 'json'
+        ? formatAnalyticsJson(input.payload)
+        : input.table;
+    if (input.out?.trim()) {
+        const outputPath = path.resolve(process.cwd(), input.out);
+        await writeFile(outputPath, output, 'utf8');
+        console.log(`Wrote ${outputPath}`);
+        return;
+    }
+    process.stdout.write(output);
+};
 const printRows = (rows, columns) => {
     for (const row of rows) {
         console.log(columns.map((column) => row[column] || '').join('\t'));
@@ -470,6 +525,240 @@ addExamples(funnelsCommand
     });
     console.log(`${result.funnel.id}\t${result.funnel.name}\t${result.funnel.slug}`);
 });
+const analyticsCommand = addExamples(program.command('analytics').description('Download and inspect project analytics'), [
+    'fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json --out analytics.json',
+    'fgrove analytics funnel-path --project claimbee --funnel claimbee-ios --date 2026-06-11',
+    'fgrove analytics transitions --project claimbee --funnel claimbee-ios --date 2026-06-11',
+    'fgrove analytics cohort --project claimbee --date 2026-06-11 --format json',
+]);
+const loadFunnelAnalyticsContext = async (options) => {
+    const token = await readAuthToken();
+    const workspace = await resolveWorkspace(token, options.workspace);
+    const project = await resolveAnalyticsProject({
+        token,
+        workspaceId: workspace.id,
+        project: options.project,
+    });
+    const funnel = await resolveAnalyticsFunnel({
+        token,
+        workspaceId: workspace.id,
+        funnel: options.funnel,
+    });
+    return {
+        token,
+        workspace,
+        project,
+        funnel,
+        commandInput: buildAnalyticsCommandInput(options),
+    };
+};
+const loadProjectAnalyticsContext = async (options) => {
+    const token = await readAuthToken();
+    const workspace = await resolveWorkspace(token, options.workspace);
+    const project = await resolveAnalyticsProject({
+        token,
+        workspaceId: workspace.id,
+        project: options.project,
+    });
+    return {
+        token,
+        workspace,
+        project,
+        commandInput: buildAnalyticsCommandInput(options),
+    };
+};
+const fetchStepDropoffAnalytics = async (input) => {
+    return callApi({
+        path: 'projects.analyticsStepDropoff',
+        type: 'query',
+        token: input.token,
+        data: {
+            workspaceId: input.workspaceId,
+            projectId: input.projectId,
+            funnelId: input.funnelId,
+            from: input.commandInput.from,
+            to: input.commandInput.to,
+            timezone: input.commandInput.timezone,
+        },
+    });
+};
+addExamples(analyticsCommand
+    .command('conversions')
+    .description('Download one-day conversion data, full funnel path, and step transitions')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
+    .option('--funnel <id-or-slug-or-name>', 'Funnel id, slug, or name')
+    .requiredOption('--date <yyyy-mm-dd>', 'Analytics date')
+    .option('--format <table-or-json>', 'Output format: table or json', 'table')
+    .option('--out <path>', 'Write output to a file')
+    .option('--timezone <iana-timezone>', 'Analytics timezone, for example America/Los_Angeles'), [
+    'fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11',
+    'fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json --out analytics.json',
+])
+    .action(async (options) => {
+    const context = await loadFunnelAnalyticsContext(options);
+    const [overview, stepDropoff] = await Promise.all([
+        callApi({
+            path: 'projects.analyticsOverview',
+            type: 'query',
+            token: context.token,
+            data: {
+                workspaceId: context.workspace.id,
+                projectId: context.project.id,
+                funnelId: context.funnel.id,
+                from: context.commandInput.from,
+                to: context.commandInput.to,
+                timezone: context.commandInput.timezone,
+                limit: 20_000,
+            },
+        }),
+        fetchStepDropoffAnalytics({
+            token: context.token,
+            workspaceId: context.workspace.id,
+            projectId: context.project.id,
+            funnelId: context.funnel.id,
+            commandInput: context.commandInput,
+        }),
+    ]);
+    assertHasConversionData(context.commandInput.date, overview, stepDropoff);
+    const payload = buildConversionReportPayload({
+        date: context.commandInput.date,
+        workspaceId: context.workspace.id,
+        project: context.project,
+        overview,
+        stepDropoff,
+    });
+    await writeOrPrintAnalyticsOutput({
+        format: context.commandInput.format,
+        payload,
+        table: formatConversionsTable({
+            date: context.commandInput.date,
+            overview,
+            stepDropoff,
+        }),
+        out: options.out,
+    });
+});
+addExamples(analyticsCommand
+    .command('funnel-path')
+    .description('Download the full one-day funnel path report')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
+    .option('--funnel <id-or-slug-or-name>', 'Funnel id, slug, or name')
+    .requiredOption('--date <yyyy-mm-dd>', 'Analytics date')
+    .option('--format <table-or-json>', 'Output format: table or json', 'table')
+    .option('--out <path>', 'Write output to a file')
+    .option('--timezone <iana-timezone>', 'Analytics timezone, for example America/Los_Angeles'), [
+    'fgrove analytics funnel-path --project claimbee --funnel claimbee-ios --date 2026-06-11',
+    'fgrove analytics funnel-path --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json',
+])
+    .action(async (options) => {
+    const context = await loadFunnelAnalyticsContext(options);
+    const stepDropoff = await fetchStepDropoffAnalytics({
+        token: context.token,
+        workspaceId: context.workspace.id,
+        projectId: context.project.id,
+        funnelId: context.funnel.id,
+        commandInput: context.commandInput,
+    });
+    assertHasFunnelPathData(context.commandInput.date, stepDropoff);
+    const payload = buildFunnelPathReportPayload({
+        date: context.commandInput.date,
+        workspaceId: context.workspace.id,
+        project: context.project,
+        stepDropoff,
+    });
+    await writeOrPrintAnalyticsOutput({
+        format: context.commandInput.format,
+        payload,
+        table: formatFunnelPathTable({
+            date: context.commandInput.date,
+            stepDropoff,
+        }),
+        out: options.out,
+    });
+});
+addExamples(analyticsCommand
+    .command('transitions')
+    .description('Download one-day step transitions and drop-offs')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
+    .option('--funnel <id-or-slug-or-name>', 'Funnel id, slug, or name')
+    .requiredOption('--date <yyyy-mm-dd>', 'Analytics date')
+    .option('--format <table-or-json>', 'Output format: table or json', 'table')
+    .option('--out <path>', 'Write output to a file')
+    .option('--timezone <iana-timezone>', 'Analytics timezone, for example America/Los_Angeles'), [
+    'fgrove analytics transitions --project claimbee --funnel claimbee-ios --date 2026-06-11',
+    'fgrove analytics transitions --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json',
+])
+    .action(async (options) => {
+    const context = await loadFunnelAnalyticsContext(options);
+    const stepDropoff = await fetchStepDropoffAnalytics({
+        token: context.token,
+        workspaceId: context.workspace.id,
+        projectId: context.project.id,
+        funnelId: context.funnel.id,
+        commandInput: context.commandInput,
+    });
+    assertHasTransitionData(context.commandInput.date, stepDropoff);
+    const payload = buildTransitionReportPayload({
+        date: context.commandInput.date,
+        workspaceId: context.workspace.id,
+        project: context.project,
+        stepDropoff,
+    });
+    await writeOrPrintAnalyticsOutput({
+        format: context.commandInput.format,
+        payload,
+        table: formatTransitionsTable({
+            date: context.commandInput.date,
+            stepDropoff,
+        }),
+        out: options.out,
+    });
+});
+addExamples(analyticsCommand
+    .command('cohort')
+    .description('Download one-day cohort marketing data')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
+    .requiredOption('--date <yyyy-mm-dd>', 'Cohort date')
+    .option('--format <table-or-json>', 'Output format: table or json', 'table')
+    .option('--out <path>', 'Write output to a file')
+    .option('--timezone <iana-timezone>', 'Reserved for consistency with conversion commands'), [
+    'fgrove analytics cohort --project claimbee --date 2026-06-11',
+    'fgrove analytics cohort --project claimbee --date 2026-06-11 --format json --out cohort.json',
+])
+    .action(async (options) => {
+    const context = await loadProjectAnalyticsContext(options);
+    const cohort = await callApi({
+        path: 'projects.marketingCohortPerformance',
+        type: 'query',
+        token: context.token,
+        data: {
+            workspaceId: context.workspace.id,
+            projectId: context.project.id,
+            from: context.commandInput.date,
+            to: context.commandInput.date,
+        },
+    });
+    assertHasCohortData(context.commandInput.date, cohort);
+    const payload = buildCohortReportPayload({
+        date: context.commandInput.date,
+        workspaceId: context.workspace.id,
+        project: context.project,
+        cohort,
+    });
+    await writeOrPrintAnalyticsOutput({
+        format: context.commandInput.format,
+        payload,
+        table: formatCohortTable({
+            date: context.commandInput.date,
+            cohort,
+        }),
+        out: options.out,
+    });
+});
 const syncCommand = addExamples(program.command('sync').description('Sync funnel source'), [
     'fgrove sync down --funnel claimbee-ios --dir ./claimbee-ios',
     'fgrove sync up --message "Update copy"',
@@ -479,7 +768,8 @@ addExamples(syncCommand
     .description('Download funnel draft source to a local directory')
     .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
     .option('--funnel <id-or-slug>', 'Funnel id or slug')
-    .requiredOption('--dir <path>', 'Local target directory'), [
+    .requiredOption('--dir <path>', 'Local target directory')
+    .option('--force', 'Overwrite local changes in an existing synced directory'), [
     'fgrove sync down --funnel claimbee-ios --dir ./claimbee-ios',
 ])
     .action(async (options) => {
@@ -490,6 +780,9 @@ addExamples(syncCommand
         funnel: options.funnel,
         dir: options.dir,
     });
+    if (!options.force && target.manifest && await hasLocalSourceChanges(target.sourceDir, target.manifest)) {
+        throw new Error('Local sync directory has unuploaded changes. Commit, stash, sync up, or merge them before `fgrove sync down`; pass `--force` only if overwriting local changes is intentional.');
+    }
     const result = await callApi({
         path: 'funnels.exportSource',
         type: 'query',
@@ -546,7 +839,7 @@ addExamples(envCommand
 });
 addExamples(syncCommand
     .command('up')
-    .description('Upload local source into a new funnel draft version')
+    .description('Upload local source into a new funnel draft version for funnels without GitHub source sync')
     .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', '.')
@@ -562,6 +855,16 @@ addExamples(syncCommand
         funnel: options.funnel,
         dir: options.dir,
     });
+    const githubStatus = await callApi({
+        path: 'github.status',
+        type: 'query',
+        token,
+        data: {
+            workspaceId: target.workspaceId,
+            funnelId: target.funnelId,
+        },
+    });
+    assertCanDraftSyncSource(githubStatus);
     const changes = target.manifest
         ? await collectChangedSourceFiles(target.sourceDir, target.manifest)
         : null;
@@ -580,19 +883,22 @@ addExamples(syncCommand
     if (changes) {
         console.log(formatSyncUploadSummary(changes).join('\n'));
         const batches = chunkChangedSourceFiles(changes);
+        let baseDraftVersionId = changes.currentManifest.draftVersionId;
         for (const batch of batches) {
             result = await callApi({
                 path: 'funnels.patchSource',
                 type: 'mutation',
                 token,
-                data: {
+                data: buildPatchSourceInput({
                     workspaceId: target.workspaceId,
                     funnelId: target.funnelId,
                     message: options.message,
+                    baseDraftVersionId,
                     files: batch.files,
                     deletedPaths: batch.deletedPaths,
-                },
+                }),
             });
+            baseDraftVersionId = result.versionId;
             syncedFileCount += result.syncedFiles.length;
             deletedFileCount += result.deletedFiles?.length || 0;
         }

package/dist/localSync.d.ts

@@ -35,6 +35,7 @@ export declare function writeLocalEnvFile(rootDir: string, envFile: string | nul
 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 hasLocalSourceChanges(rootDir: string, previousManifest: SyncManifest): Promise<boolean>;
 export declare function chunkChangedSourceFiles(changes: Pick<ChangedSourceFiles, 'deletedPaths' | 'files'>, maxContentChars?: number): SourceFilePatchBatch[];
 export declare function formatSyncUploadSummary(changes: Pick<ChangedSourceFiles, 'deletedPaths' | 'files'>, largestFileLimit?: number): string[];
 export declare function writeSourceFiles(rootDir: string, files: SourceFile[]): Promise<void>;

package/dist/localSync.js

@@ -127,6 +127,10 @@ export async function collectChangedSourceFiles(rootDir, previousManifest) {
         files: await readSourceFiles(rootDir, changedManifestFiles),
     };
 }
+export async function hasLocalSourceChanges(rootDir, previousManifest) {
+    const changes = await collectChangedSourceFiles(rootDir, previousManifest);
+    return changes.files.length > 0 || changes.deletedPaths.length > 0;
+}
 export function chunkChangedSourceFiles(changes, maxContentChars = DEFAULT_PATCH_BATCH_CONTENT_CHARS) {
     const batches = [];
     let currentBatch = {

package/package.json

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

package/template_docs/AGENTS.md

@@ -1,107 +1,70 @@
 # 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.
-
-Architecture docs are part of the change. When you change funnel routing, runtime state, SDK API contracts, URL handoff parameters, checkout/subscription behavior, analytics events, environment config, or shared package boundaries, update `template_docs` in the same change so future agents inherit the new contract.
-
-## 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 `fgrove env pull` when remote project settings changed and you need the latest local `.env`.
-4. Run the funnel's local checks before syncing.
-5. Run `fgrove sync up --message '<summary>'`.
-6. Run `fgrove publish --env preview --message '<summary>'` and verify the preview.
-7. Publish production only when explicitly requested.
-
-- [Editing or Creating a Step](docs/editing-step.md)
-- [Editing Flow](docs/editing-flow.md)
-- [Funnel Runtime Architecture](docs/funnel-runtime-architecture.md)
-- [Editor and Content](docs/editor-and-content.md)
-- [Payment Plans and Discounts](docs/payment-plans-and-discounts.md)
-- [SDK API Endpoints](docs/sdk-api-endpoints.md)
-- [Analytics](docs/analytics.md)
-- [Meta Pixel and Conversions API](docs/meta-pixel-conversions-api.md)
-- [A/B Experiments](docs/ab-experiments.md)
-- [Theme](docs/theme.md)
-- [Publishing and Versioning](docs/publishing-and-versioning.md)
+Source-of-truth guide for editing this synced FunnelsGrove funnel. Read the matching topic doc before editing; the docs define the contracts the runtime expects.
+
+## Find Your Task
+
+| Task | Read | Edit | Target time |
+| --- | --- | --- | --- |
+| Add or edit a step | [docs/editing-step.md](docs/editing-step.md) + [docs/step-ui-guidelines.md](docs/step-ui-guidelines.md) | `src/steps/*` + registries + manifest | < 3 min to first preview |
+| Change step order / branching | [docs/editing-flow.md](docs/editing-flow.md) | `src/config/funnel.manifest.ts` | < 2 min |
+| Set up an A/B experiment | [docs/ab-experiments.md](docs/ab-experiments.md) | `src/config/experiments.ts` | < 1 min when variant step exists |
+| Edit copy or images | [docs/editor-and-content.md](docs/editor-and-content.md) | `src/steps/content/*.content.ts` | < 2 min |
+| Edit image loading/performance | [docs/editing-flow.md](docs/editing-flow.md) + [docs/step-ui-guidelines.md](docs/step-ui-guidelines.md) + [docs/publishing-and-versioning.md](docs/publishing-and-versioning.md) | `src/config/funnel.manifest.ts`, `src/components/FunnelFlow.tsx`, image assets | careful, QA required |
+| Change plans, prices, discounts | [docs/payment-plans-and-discounts.md](docs/payment-plans-and-discounts.md) | `src/config/billing.plans.ts` | careful, read doc fully |
+| Edit paywall or checkout | [docs/payment-plans-and-discounts.md](docs/payment-plans-and-discounts.md) + [docs/step-ui-guidelines.md](docs/step-ui-guidelines.md) | `src/steps/step-32-paywall*.tsx` | careful, QA required |
+| Change colors / fonts | [docs/theme.md](docs/theme.md) | `src/theme/theme.ts` | < 2 min |
+| QA before publish | [docs/qa-checklist.md](docs/qa-checklist.md) | nothing — test and report | as long as it takes |
+| Publish | [docs/publishing-and-versioning.md](docs/publishing-and-versioning.md) | nothing — `fgrove` commands | — |
+
+Deep dives: [Funnel Runtime Architecture](docs/funnel-runtime-architecture.md), [SDK API Endpoints](docs/sdk-api-endpoints.md), [Analytics](docs/analytics.md), [Meta Pixel and Conversions API](docs/meta-pixel-conversions-api.md).
+
+## Architecture in 30 Seconds
+
+The funnel is a small Next.js app on shared packages:
+
+- `@funnelsgrove/runtime` — routing, user state, content localization, builder preview, theme.
+- `@funnelsgrove/analytics` — event tracking and A/B assignment (wraps PostHog; never call PostHog directly).
+- `@funnelsgrove/payments` — plans, discounts, Stripe checkout, wallet buttons, shared checkout UI.
+- This repo — product decisions only: step views, content, editor fields, flow manifest, theme, assets, plan ids.
+
+Most edits touch one step file plus its matching `content/` and `editor/` files, or one config file. If an edit spreads wider than that, stop and re-read the topic doc.
+
+## Standard Workflow
+
+1. `fgrove status` — confirm the active project and funnel.
+2. `git status --short` — if local changes exist, checkpoint them before any refresh.
+3. `fgrove github status` — when GitHub is connected and remote is ahead, run `fgrove github pull`, then poll `fgrove github status` until the pull job is completed or skipped before syncing the latest draft into a clean directory and merging the local checkpoint intentionally.
+4. When GitHub is not connected, use `fgrove sync down --funnel <id-or-slug> --dir <temp-dir>` or an already selected `fgrove use` context as the remote source, then merge that clean hosted draft with local changes before editing further.
+5. Make the scoped edit per the topic doc.
+6. `npm run test:run && npm run lint` (or the checks this tree defines).
+7. `npm run dev` — verify in local preview at all four default breakpoints: small 375x667, medium 393x852, large 402x874, and desktop-small 1280x800 ([docs/step-ui-guidelines.md](docs/step-ui-guidelines.md)).
+8. Run the relevant part of [docs/qa-checklist.md](docs/qa-checklist.md).
+9. Ask the user before publishing. If GitHub is connected, commit and push with normal git, run `fgrove github pull`, then poll `fgrove github status` until the pull job is completed or skipped. Do not also run `fgrove sync up` for the same diff.
+10. If GitHub is not connected, run `fgrove sync up --message '<summary>'`.
+11. Publish preview with `fgrove publish --env preview --message '<summary>'`.
+12. QA the preview URL. Production publish only on explicit request, after preview QA.
+
+`fgrove env pull` refreshes the local `.env` when remote project settings changed.
+Do not run `fgrove sync down` over a dirty synced directory unless discarding
+local changes is intentional and `--force` is passed. If `fgrove sync up`
+reports that the remote draft changed since this directory was synced, download
+the current draft into a temp directory, merge local changes, rerun checks, and
+sync again.
+For GitHub-connected funnels, source changes must flow through GitHub first:
+`git push`, then `fgrove github pull`, then publish. Do not mix `fgrove sync up`
+with the same local source diff.
+
+## Behavioral Rules
+
+1. **Think before coding.** State assumptions. If multiple interpretations exist, present them — don't pick silently. If something is unclear, ask before editing.
+2. **Simplicity first.** Minimum code that solves the problem. No speculative abstractions, options, or error handling for impossible states.
+3. **Surgical changes.** Touch only what the request requires. Match existing style. Remove only orphans your own change created. Every changed line should trace to the request.
+4. **Goal-driven execution.** Define the success check before editing ("step renders at 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`.
+
+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.
+
+Preserve existing step ids, paths, and answer keys unless the task is an explicit migration — they feed routes, persisted answers, analytics, and publish history.