@funnelsgrove/cli 0.1.11 → 0.1.12

package/README.md

@@ -18,13 +18,27 @@ Common workflow:
 
 ```bash
 fgrove status
+git status --short
+fgrove github status
 fgrove docs
+# if GitHub is connected: git push, then fgrove github pull
+# if GitHub is not connected:
 fgrove sync up --message 'Update funnel copy'
 fgrove publish --env preview
 ```
 
 Inside a synced folder, `fgrove` reads `.funnelsgrove-sync.json` first, so you do not need to run `fgrove use` when switching between local funnel directories. Use `fgrove use` only when you want a global fallback context for commands outside a synced folder.
 
+`fgrove sync down` refuses to overwrite local changes in an existing synced
+folder unless `--force` is passed. If `fgrove sync up` says the remote draft
+changed since your local sync, download the latest draft into a clean temporary
+directory, merge your local changes, rerun checks, and sync again.
+
+`fgrove sync up` is for funnels without GitHub source sync. When GitHub is
+connected, commit and push source changes with normal git, then run `fgrove
+github pull` to sync GitHub into the hosted draft. Do not run `fgrove sync up`
+for the same local diff.
+
 Use `fgrove env pull` from a synced folder to refresh only the ignored local `.env` file after project settings change, without replacing source files.
 
 GitHub sync workflow:
@@ -32,12 +46,18 @@ GitHub sync workflow:
 ```bash
 fgrove github status --funnel claimbee-general
 fgrove github connect --funnel claimbee-general --account The-Solid-Grove --repo claimbee-funnel
-fgrove github push --funnel claimbee-general
+git push
 fgrove github pull --funnel claimbee-general
 fgrove publish --funnel claimbee-general --env preview
 ```
 
-The GitHub commands use the FunnelsGrove API only. When GitHub is connected, `fgrove sync up` pushes the resulting draft to GitHub before returning, and `fgrove publish` waits for the current draft to reach GitHub before publishing. Local `.env*` files remain CLI-local runtime material from `sync down`; they are not sent to GitHub sync.
+The GitHub commands use the FunnelsGrove API only. `fgrove github pull` pulls
+the repository into the hosted draft after you push normal git commits.
+`fgrove publish` waits for the current draft to reach GitHub before publishing.
+`fgrove github push` still exists for explicit hosted-draft-to-GitHub recovery
+work, but it is not the normal path for local source changes. Local `.env*`
+files remain CLI-local runtime material from `sync down`; they are not sent to
+GitHub sync.
 
 Analytics workflow:
 

package/dist/cli.d.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { type ActiveContext } from './authStore.js';
-import { type SyncManifest } from './localSync.js';
+import { type SourceFile, type SyncManifest } from './localSync.js';
+import { type GitHubStatusResponse } from './githubOutput.js';
 import { type AnalyticsOutputFormat } from './analyticsOutput.js';
 type AnalyticsCommandInput = {
     date: string;
@@ -26,4 +27,20 @@ export declare function buildAnalyticsCommandInput(options: {
     format?: string;
     timezone?: string;
 }): AnalyticsCommandInput;
+export declare function buildPatchSourceInput(input: {
+    workspaceId: string;
+    funnelId: string;
+    message?: string;
+    baseDraftVersionId?: string;
+    files: SourceFile[];
+    deletedPaths: string[];
+}): {
+    workspaceId: string;
+    funnelId: string;
+    message?: string;
+    baseDraftVersionId?: string;
+    files: SourceFile[];
+    deletedPaths: string[];
+};
+export declare function assertCanDraftSyncSource(status: GitHubStatusResponse): void;
 export {};

package/dist/cli.js

@@ -7,7 +7,7 @@ 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';
@@ -73,6 +73,21 @@ export function buildAnalyticsCommandInput(options) {
         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;
@@ -753,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) => {
@@ -764,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',
@@ -820,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', '.')
@@ -836,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;
@@ -854,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.11",
+  "version": "0.1.12",
   "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
   "type": "module",
   "bin": {

package/template_docs/AGENTS.md

@@ -33,23 +33,37 @@ Most edits touch one step file plus its matching `content/` and `editor/` files,
 ## Standard Workflow
 
 1. `fgrove status` — confirm the active project and funnel.
-2. Make the scoped edit per the topic doc.
-3. `npm run test:run && npm run lint` (or the checks this tree defines).
-4. `npm run dev` — verify in local preview at 430x932, spot-check 390x844 ([docs/step-ui-guidelines.md](docs/step-ui-guidelines.md)).
-5. Run the relevant part of [docs/qa-checklist.md](docs/qa-checklist.md).
-6. Ask the user before publishing. Then `fgrove sync up --message '<summary>'` and `fgrove publish --env preview --message '<summary>'`.
-7. QA the preview URL. Production publish only on explicit request, after preview QA.
+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 both viewports and Continue advances to step-X"), then loop until it passes.
+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.
 

package/template_docs/docs/ab-experiments.md

@@ -14,8 +14,8 @@ export const experiments = defineFunnelExperiments([
     type: 'paywall',                        // 'step' for quiz steps, 'paywall' for paywall tests
     status: 'running',                      // 'paused' | 'stopped' removes it from the manifest
     launchDate: '2026-06-12T00:00:00.000Z',
-    control: { stepId: 'paywall', trafficPercent: 50 },
-    variant: { stepId: 'paywall-b', trafficPercent: 50 },
+    control: { stepId: 'paywall', label: 'paywall-ab-control', trafficPercent: 50 },
+    variant: { stepId: 'paywall-b', label: 'paywall-ab-variant-b', trafficPercent: 50 },
   },
 ] as const);
 ```
@@ -46,6 +46,7 @@ Check: opening the source URL promotes to the assigned route, each variant rende
 
 - One deliberate change per experiment. Don't bundle unrelated edits into a variant.
 - `control` stays stable; never edit the control step as part of launching a variant.
+- Add stable `control.label` and `variant.label` values in the `<experiment-id>-control` / `<experiment-id>-variant-b` format so builder labels and analytics views stay readable.
 - Variant keys and experiment ids are durable — they flow into analytics. Never recycle an id for a different hypothesis.
 - Keep every variant step's outgoing edge in `edgesByStepId`, or assigned visitors strand.
 - If a paywall variant changes plans or pricing, follow [payment-plans-and-discounts.md](payment-plans-and-discounts.md) for the plan/discount sync rules and QA both variants' checkout ([qa-checklist.md](qa-checklist.md)).

package/template_docs/docs/analytics.md

@@ -18,15 +18,15 @@ Analytics should describe meaningful user behavior. `@funnelsgrove/analytics` is
 
 Experiment assignments are attached as feature flag properties when available. Preview runtime skips normal analytics delivery.
 
-## Custom Events
+## Standard Checkout Events
 
-Use `publicAnalyticsSdk.track(...)` from `@funnelsgrove/analytics`:
+Use named helpers from `@funnelsgrove/analytics` for checkout lifecycle events:
 
 ```ts
-publicAnalyticsSdk.track({
-  eventType: 'checkout_started',
+publicAnalyticsSdk.trackCheckoutStarted({
   stepId: stepPaywallId,
   stepName: stepPaywall.name || stepPaywall.title,
+  stepType: stepPaywall.type,
   metadata: {
     planId,
     providerPlanId,
@@ -37,6 +37,8 @@ publicAnalyticsSdk.track({
 });
 ```
 
+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
@@ -60,3 +62,4 @@ Provider-specific behavior is documented separately. Read [Meta Pixel and Conver
 - 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

@@ -6,15 +6,18 @@ Flow is product logic. The source of truth is `src/config/funnel.manifest.ts`; r
 
 The manifest defines:
 
-- `viewport`: the designed shell size, usually `430 x 932`.
+- `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`, and optional `assetIds`. New `path` values must be meaningful public route slugs, not `/step-1` style URLs. Sequential ids are acceptable when the funnel uses them internally.
+- `steps`: every routable step with `id`, `path`, `filePath`, `componentKey`, `type`, optional `kind`, optional `tags`, and optional `assetIds`. 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.
@@ -43,6 +46,36 @@ eligibility: [
 
 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:
@@ -78,7 +111,11 @@ Keep the control variant stable and do not remove a running variant until analyt
 
 - Add or update the manifest step.
 - Register the component in `src/runtime/step-registry.ts`.
-- Update `edgesByStepId`, `entryPoints`, and `assetIds` if needed.
+- 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

package/template_docs/docs/editing-step.md

@@ -94,7 +94,7 @@ motivation: {
 motivation: [{ toStepId: 'step-3' }],
 ```
 
-**Verify:** `npm run dev`, open `/motivation`, confirm it renders at 430x932 and 390x844, Continue (or auto-advance) lands on the next step, and `npm run test:run && npm run lint` pass.
+**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
 

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

@@ -6,10 +6,53 @@ Local edits are not public until they are synced and published. Sync creates or
 
 ```bash
 fgrove status
+git status --short
+fgrove github status
+fgrove publish --env preview --message '<summary>'
+```
+
+Before syncing down over an existing synced directory, check local changes. If
+`git status --short` shows local edits, checkpoint them first. `fgrove sync
+down` refuses to overwrite a dirty synced directory by default; use `--force`
+only when discarding local changes is intentional.
+
+When GitHub is connected and its branch is ahead, run `fgrove github pull` to
+pull GitHub into the hosted draft, then poll `fgrove github status` until the
+pull job is completed or skipped. Sync that latest draft into a clean directory
+and merge local changes intentionally before continuing.
+
+For GitHub-connected funnels, source changes must be pushed to GitHub first,
+then pulled into the hosted draft:
+
+```bash
+git push
+fgrove github pull
+fgrove github status
+fgrove publish --env preview --message '<summary>'
+```
+
+Poll `fgrove github status` until the pull job is completed or skipped before
+publishing. Do not run `fgrove sync up` for the same source diff; the CLI and
+API reject draft source sync for GitHub-connected funnels.
+
+When GitHub is not connected, the hosted draft is the remote source of truth.
+Download it into a temporary clean directory with `fgrove sync down --funnel
+<id-or-slug> --dir <temp-dir>` or an already selected `fgrove use` context,
+compare it with local changes, merge intentionally, rerun checks, then `fgrove
+sync up`.
+
+For funnels without GitHub, sync local source directly to the hosted draft:
+
+```bash
 fgrove sync up --message '<summary>'
 fgrove publish --env preview --message '<summary>'
 ```
 
+If `fgrove sync up` reports that the remote draft changed since the local
+directory was synced, do not retry blindly. Download the current draft into a
+temporary clean directory, merge local changes against it, rerun checks, and
+sync again.
+
 Refresh the ignored local `.env` from the remote project when project settings change:
 
 ```bash
@@ -40,7 +83,10 @@ calling the publish ready.
 
 ## 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.
+The CLI writes `.funnelsgrove-sync.json` into the local tree. Keep it there. It
+records workspace id, funnel id, current draft version id, and source hashes so
+later `sync up` can patch only changed/deleted files and detect stale remote
+drafts before overwriting them.
 
 Local-only files are excluded from upload:
 
@@ -57,8 +103,15 @@ Do not edit generated build output as the source of truth.
 ## Agent Rules
 
 - Run `fgrove status` before syncing.
+- Check local changes before `sync down`; checkpoint or merge instead of
+  overwriting.
+- For GitHub-connected funnels, push with normal git, then run `fgrove github
+  pull`; do not run `fgrove sync up` for the same source change.
 - Use clear sync and publish messages.
-- Sync before publishing.
+- Sync the hosted draft before publishing: GitHub-connected funnels use normal
+  `git push` plus `fgrove github pull`; funnels without GitHub use `fgrove sync
+  up`.
 - Publish preview first and verify the returned URL.
-- If preview verification fails, fix locally, run checks, sync up again, and publish a new preview.
+- If preview verification fails, fix locally, run checks, sync the hosted draft
+  again through the correct source path, and publish a new preview.
 - Do not production publish without explicit instruction and target domain.

package/template_docs/docs/qa-checklist.md

@@ -22,7 +22,14 @@ A production publish without a QA-passed matching preview build is a blocker unl
 
 ## 2. Visual Pass
 
-At **430x932**, then **390x844** (rules in [step-ui-guidelines.md](step-ui-guidelines.md)):
+Run every visual pass at all four default breakpoints (rules in [step-ui-guidelines.md](step-ui-guidelines.md)):
+
+| Breakpoint | Size |
+| --- | --- |
+| small | **375x667** |
+| medium | **393x852** |
+| large | **402x874** |
+| desktop-small | **1280x800** |
 
 - Nothing intersects or overlaps: text never collides with images, cards, badges, or the action bar; modals and dialogs fit the viewport.
 - Continue button sits on an opaque bar at the bottom and stays visible on every step, including while content scrolls.
@@ -70,4 +77,4 @@ If checkout, payment mode, or test credentials are unavailable, name the skipped
 
 ## Reporting
 
-Every QA run ends with a short report: stage + URLs tested, steps/branches/variants covered, viewports checked, image optimization/preload result when relevant, paywall items 1–7 pass/fail, payment method used, console findings, and named blockers or explicitly skipped items with the reason. Blockers block production unless the user accepts the risk in so many words.
+Every QA run ends with a short report: stage + URLs tested, steps/branches/variants covered, breakpoint results for small 375x667, medium 393x852, large 402x874, and desktop-small 1280x800, image optimization/preload result when relevant, paywall items 1–7 pass/fail, payment method used, console findings, and named blockers or explicitly skipped items with the reason. Blockers block production unless the user accepts the risk in so many words.

package/template_docs/docs/step-ui-guidelines.md

@@ -4,14 +4,18 @@ Every step must pass these rules before it counts as done. They are distilled fr
 
 ## Viewports
 
-Funnels are mobile-first. Build and verify at:
+Funnels are mobile-first, but QA must cover the desktop-small shell too. Build
+and verify every created or edited step at the default breakpoints in
+`src/config/funnel.manifest.ts`:
 
-| Viewport | Size | Role |
+| Breakpoint | Size | Role |
 | --- | --- | --- |
-| iPhone 16 Pro | **430 x 932** | Default. Matches `viewport` in `funnel.manifest.ts`. |
-| iPhone 12 / 13 / 14 | **390 x 844** | Required spot-check on every created or edited step. |
+| small | **375 x 667** | iPhone SE and smaller-width stress check. |
+| medium | **393 x 852** | iPhone 15 baseline. |
+| large | **402 x 874** | iPhone 17 Pro baseline. |
+| desktop-small | **1280 x 800** | 13-inch MacBook baseline. |
 
-Pass criteria at both sizes: no horizontal scroll, no clipped or overlapping content, the primary CTA visible without scrolling on selection/input steps, and tap targets at least 44px tall.
+Pass criteria at every breakpoint: no horizontal scroll, no clipped or overlapping content, the primary CTA visible without scrolling on selection/input steps, and tap targets at least 44px tall.
 
 ## Layout Shell Contract
 
@@ -95,7 +99,7 @@ Use the ClaimBee/Blessly image loading pattern:
 
 ## Content-Fit Audit
 
-Run on every created or edited step, at 430x932 then 390x844:
+Run on every created or edited step at small 375x667, medium 393x852, large 402x874, and desktop-small 1280x800:
 
 1. Open the step in local preview (`npm run dev`).
 2. Check: nothing clipped, nothing overlapping, no text truncated mid-word, images loaded with correct aspect, CTA fully visible above the fold on selection/input steps.
@@ -103,4 +107,4 @@ Run on every created or edited step, at 430x932 then 390x844:
 4. Check disabled→enabled CTA transition where applicable.
 5. Fix and re-check before moving to another step.
 
-Report the audit (both viewports, pass/fail per step) in your summary.
+Report the audit (all four breakpoints, pass/fail per step) in your summary.