@funnelsgrove/cli 0.1.5 → 0.1.6

package/README.md

@@ -24,6 +24,8 @@ fgrove sync up --message 'Update funnel copy'
 fgrove publish --env preview
 ```
 
+Use `fgrove env pull --dir <local-dir>` to refresh only the ignored local `.env` file after project settings change, without replacing source files.
+
 GitHub sync workflow:
 
 ```bash

package/dist/cli.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs';
-import { cp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { cp, mkdir } 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, readSyncManifest, writeSourceFiles, writeSyncManifest, } from './localSync.js';
+import { buildSyncManifest, chunkChangedSourceFiles, collectChangedSourceFiles, collectSourceFiles, ensureGitignore, 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';
@@ -197,19 +198,6 @@ const resolveSyncTarget = async (input) => {
         manifest,
     };
 };
-const ensureGitignore = async (dir) => {
-    const gitignorePath = path.join(dir, '.gitignore');
-    const existing = await readFile(gitignorePath, 'utf8').catch(() => '');
-    const lines = existing.split(/\r?\n/g).filter(Boolean);
-    const required = ['.env', '.env.local', '.env.*', '!.env.example', '.funnelsgrove-sync.json', 'node_modules', '.next', 'out'];
-    const seen = new Set(lines);
-    for (const line of required) {
-        if (!seen.has(line)) {
-            lines.push(line);
-        }
-    }
-    await writeFile(gitignorePath, `${lines.join('\n')}\n`, 'utf8');
-};
 const printRows = (rows, columns) => {
     for (const row of rows) {
         console.log(columns.map((column) => row[column] || '').join('\t'));
@@ -448,9 +436,7 @@ addExamples(syncCommand
     });
     await mkdir(target.sourceDir, { recursive: true });
     await writeSourceFiles(target.sourceDir, result.files);
-    if (result.envFile) {
-        await writeFile(path.join(target.sourceDir, '.env'), result.envFile, 'utf8');
-    }
+    await writeLocalEnvFile(target.sourceDir, result.envFile);
     await ensureGitignore(target.sourceDir);
     await writeSyncManifest(target.sourceDir, await buildSyncManifest(target.sourceDir, {
         workspaceId: target.workspaceId,
@@ -459,6 +445,40 @@ addExamples(syncCommand
     }));
     console.log(`Synced ${result.files.length} files to ${target.sourceDir}`);
 });
+const envCommand = addExamples(program.command('env').description('Manage local funnel environment files'), [
+    'fgrove env pull --dir ./claimbee-ios',
+]);
+addExamples(envCommand
+    .command('pull')
+    .description('Refresh the ignored local .env file without downloading source files')
+    .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 funnel directory', '.'), [
+    'fgrove env pull',
+    'fgrove env pull --dir ./claimbee-ios',
+    'fgrove env pull --funnel claimbee-ios --dir ./claimbee-ios',
+])
+    .action(async (options) => {
+    const token = await readAuthToken();
+    const target = await resolveSyncTarget({
+        token,
+        workspace: options.workspace,
+        funnel: options.funnel,
+        dir: options.dir,
+    });
+    const result = await pullEnvFile({
+        callApi,
+        token,
+        workspaceId: target.workspaceId,
+        funnelId: target.funnelId,
+        sourceDir: target.sourceDir,
+    });
+    if (!result.wroteEnvFile) {
+        console.log(`No env file returned for ${result.sourceDir}`);
+        return;
+    }
+    console.log(`Updated ${path.join(result.sourceDir, '.env')}`);
+});
 addExamples(syncCommand
     .command('up')
     .description('Upload local source into a new funnel draft version')

package/dist/envSync.d.ts

@@ -0,0 +1,17 @@
+export type EnvPullCallApi = <T>(input: {
+    path: string;
+    type: 'query' | 'mutation';
+    data?: unknown;
+    token?: string | null;
+}) => Promise<T>;
+export type PullEnvFileResult = {
+    sourceDir: string;
+    wroteEnvFile: boolean;
+};
+export declare function pullEnvFile(input: {
+    callApi: EnvPullCallApi;
+    token: string;
+    workspaceId: string;
+    funnelId: string;
+    sourceDir: string;
+}): Promise<PullEnvFileResult>;

package/dist/envSync.js

@@ -0,0 +1,20 @@
+import { mkdir } from 'node:fs/promises';
+import { ensureGitignore, writeLocalEnvFile } from './localSync.js';
+export async function pullEnvFile(input) {
+    await mkdir(input.sourceDir, { recursive: true });
+    const result = await input.callApi({
+        path: 'funnels.exportSource',
+        type: 'query',
+        token: input.token,
+        data: {
+            workspaceId: input.workspaceId,
+            funnelId: input.funnelId,
+        },
+    });
+    const wroteEnvFile = await writeLocalEnvFile(input.sourceDir, result.envFile);
+    await ensureGitignore(input.sourceDir);
+    return {
+        sourceDir: input.sourceDir,
+        wroteEnvFile,
+    };
+}

package/dist/localSync.d.ts

@@ -30,6 +30,8 @@ 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 ensureGitignore(rootDir: string): Promise<void>;
+export declare function writeLocalEnvFile(rootDir: string, envFile: string | null | undefined): Promise<boolean>;
 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>;

package/dist/localSync.js

@@ -4,6 +4,16 @@ 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']);
+const LOCAL_ONLY_GITIGNORE_LINES = [
+    '.env',
+    '.env.local',
+    '.env.*',
+    '!.env.example',
+    SYNC_MANIFEST_FILE,
+    'node_modules',
+    '.next',
+    'out',
+];
 export function normalizeSyncPath(filePath) {
     const normalized = path.posix.normalize(filePath.replaceAll('\\', '/'));
     return normalized.replace(/^(\.\/|\/)+/, '');
@@ -43,6 +53,26 @@ export async function buildSyncManifest(rootDir, input) {
 export async function writeSyncManifest(rootDir, manifest) {
     await writeFile(path.join(rootDir, SYNC_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
 }
+export async function ensureGitignore(rootDir) {
+    const gitignorePath = path.join(rootDir, '.gitignore');
+    const existing = await readFile(gitignorePath, 'utf8').catch(() => '');
+    const lines = existing.split(/\r?\n/g).filter(Boolean);
+    const seen = new Set(lines);
+    for (const line of LOCAL_ONLY_GITIGNORE_LINES) {
+        if (!seen.has(line)) {
+            lines.push(line);
+        }
+    }
+    await writeFile(gitignorePath, `${lines.join('\n')}\n`, 'utf8');
+}
+export async function writeLocalEnvFile(rootDir, envFile) {
+    if (!envFile) {
+        return false;
+    }
+    await mkdir(rootDir, { recursive: true });
+    await writeFile(path.join(rootDir, '.env'), envFile, 'utf8');
+    return true;
+}
 export async function readSyncManifest(rootDir) {
     try {
         const raw = JSON.parse(await readFile(path.join(rootDir, SYNC_MANIFEST_FILE), 'utf8'));

package/package.json

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

package/template_docs/AGENTS.md

@@ -8,6 +8,8 @@ Behavioral guidelines to reduce common LLM coding mistakes. Merge these rules wi
 
 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.**
@@ -86,17 +88,20 @@ Keep changes simple and local. Most edits should touch one step file plus its ma
 
 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.
+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)

package/template_docs/docs/analytics.md

@@ -14,6 +14,7 @@ Analytics should describe meaningful user behavior. `@funnelsgrove/analytics` is
 - `step_start` -> `step_started`.
 - `step_end` -> `step_completed`.
 - `funnel_start` -> `funnel_started`.
+- Successful `POST /sdk/public/users/:user_id/claim_subscription` calls emit `registration_completed` from the server.
 
 Experiment assignments are attached as feature flag properties when available. Preview runtime skips normal analytics delivery.
 
@@ -48,9 +49,12 @@ Flow and experiment assignment are configured in `src/config/funnel.manifest.ts`
 
 Agents should only document and verify the analytics package surface: stable event names, step ids, selected answers, checkout metadata, and experiment metadata. Treat the underlying provider as an implementation detail.
 
+Provider-specific behavior is documented separately. Read [Meta Pixel and Conversions API](meta-pixel-conversions-api.md) before changing Meta event mapping, Pixel behavior, server-side conversions, or attribution matching.
+
 ## Agent Rules
 
 - Keep event names stable.
+- Count Completed Registration only from successful subscription claim requests after app login/signup.
 - Use `metadata`, `payload`, `context`, and `selected` for small analysis fields only.
 - Do not send personal data, secrets, full payment objects, SDK keys, or raw Stripe responses.
 - Use `@funnelsgrove/analytics` for custom tracking; do not call the provider SDK directly.

package/template_docs/docs/funnel-runtime-architecture.md

@@ -0,0 +1,125 @@
+# Funnel Runtime Architecture
+
+This doc explains the runtime contracts a synced funnel should preserve. Update this file when changing funnel architecture, routing, identity handoff, SDK payloads, payments, subscriptions, or analytics.
+
+## Runtime Boundary
+
+A funnel is a small Next.js app that owns product-specific steps, content, assets, theme, and billing plan ids. Shared packages own the reusable runtime behavior:
+
+- `@funnelsgrove/runtime`: routing, user state, URL user attributes, SDK calls, preview mode, content localization, subscription handoff, runtime config, and theme variables.
+- `@funnelsgrove/payments`: Stripe plan resolution, discounts, checkout sessions, wallet/card checkout UI, and manage-subscription UI.
+- `@funnelsgrove/analytics`: canonical analytics events and provider delivery.
+
+Keep funnel code thin. Step files should use the shared runtime/payment/analytics surfaces instead of calling raw SDK endpoints, Stripe, PostHog, or browser routing directly.
+
+## Flow And Routing
+
+The local source of truth is `src/config/funnel.manifest.ts`.
+
+- `steps[]` defines every routable step with stable `id`, `path`, `filePath`, `componentKey`, `type`, optional `kind`, and asset references.
+- `edgesByStepId` defines normal and conditional navigation.
+- `entryPoints` lets public routes such as `/paywall` and `/manage-subscription` land directly on a step.
+- `src/runtime/step-registry.ts` maps manifest step ids to React components.
+
+Use `useFunnel()` navigation (`goNext`, `goChoice`, `goToStep`) so runtime history, experiments, and step tracking remain consistent.
+
+## User Identity
+
+The runtime persists a local user id under the funnel-scoped local storage key `funnel:<funnelId>:user-id`. Public URLs can also pass user attributes:
+
+- `user_id`: canonical public funnel user id when a known user is being resumed.
+- `email`: shopper/contact email. The runtime validates it and syncs it into the funnel user profile.
+- `name`, `fullName`, `full_name`: optional profile name aliases.
+- `stripe_customer_id`: Stripe customer id used by subscription management links.
+
+At startup, the flow controller bootstraps a user through `apiService.bootstrapSession(...)` with the URL or local user id, email/name, and first-touch attribution. Step answers are stored in runtime attributes and persisted through `apiService.updateUser(...)` as `document.progress.attributes` plus completed step records.
+
+Do not invent new identity query names casually. If a new URL parameter becomes part of the funnel contract, add it to the URL attribute parser, SDK docs, and this file.
+
+## Paywall Entry
+
+Paywall routes can be opened directly, usually as `/paywall`.
+
+Supported identity handoff:
+
+- `/paywall?user_id=u_123`: resume a known funnel user and preserve that id through checkout metadata.
+- `/paywall?email=user@example.com`: seed/sync the shopper email and pass it as Stripe `customerEmail`.
+- `/paywall?user_id=u_123&email=user@example.com`: preferred when both are known.
+
+Email-only links are useful for prefilled checkout and later private user lookup by email, but `user_id` is the stronger join key for existing answers, attribution, and subscription reconciliation.
+
+Paywall checkout should use `@funnelsgrove/payments` helpers. Checkout payloads must include the selected plan, amount, coupon, checkout mode, runtime config, `user_id` when available, and `customerEmail` when available. Stripe sessions receive `client_reference_id` and FunnelsGrove metadata with plan id, price id, user id, environment, funnel id, funnel version id, coupon id, and customer email.
+
+Success/return URLs should route to the subscription-started step and preserve `user_id`, for example `/subscription-started?user_id=u_123&source=stripe-elements`.
+
+## Subscription Started Handoff
+
+The subscription-started step uses `SubscriptionHandoffScreen` and `resolveSubscriptionHandoff(...)`.
+
+The handoff requires a user id. App store URLs, universal links, and deep links may include `{user_id}` and `{email}` templates; runtime also appends `user_id` and first-touch attribution parameters when it can parse the URL.
+
+This step is also the right place to track payment return events such as `payment_checkout_succeeded` or `payment_checkout_returned`. Keep raw payment objects and secrets out of analytics metadata.
+
+## Manage Subscription
+
+The manage-subscription route is a public customer support route, usually `/manage-subscription`.
+
+Supported identity handoff:
+
+- `/manage-subscription?user_id=u_123`: resolve the funnel user, then resolve Stripe customer/subscriptions from the linked user, user document, or billing records.
+- `/manage-subscription?stripe_customer_id=cus_123`: resolve subscriptions directly by Stripe customer id when the funnel user id is unavailable.
+- `/manage-subscription?user_id=u_123&stripe_customer_id=cus_123`: preferred for support/admin generated links.
+
+The runtime calls:
+
+- `GET /sdk/public/subscriptions?user_id=...&stripe_customer_id=...&funnelId=...`
+- `POST /sdk/public/subscriptions/:subscriptionId/:action` with `action` of `cancel` or `renew`
+
+If neither `user_id` nor `stripe_customer_id` is available, the list endpoint returns an empty public summary and mutation rejects the request. The UI should show an empty/error state and the support email from runtime config.
+
+## Webhooks And Reconciliation
+
+Stripe webhooks reconcile payment/subscription state back into the funnel user. The important join points are:
+
+- Stripe metadata `userId` and `customerEmail`.
+- Stripe `client_reference_id`.
+- provider customer id (`stripe_customer_id` / `providerCustomerId`).
+- stored funnel user subscription fields and document subscription snapshots.
+
+Webhook reconciliation updates the funnel user subscription status, Stripe customer/subscription ids, subscription document snapshots, billing records, analytics, and project webhooks. When editing checkout metadata or URL handoff, verify the webhook still has enough information to find the correct funnel user.
+
+## Analytics
+
+The flow controller emits canonical runtime events:
+
+- `step_start`
+- `step_end`
+- `step_engaged` on the first step after the engagement threshold
+
+The analytics provider may receive mapped names such as `step_started` and `step_completed`.
+Paywalls should track checkout intent and completion through `@funnelsgrove/analytics` with plan id, provider plan id, coupon id, amount, and environment. Do not send personal data, SDK keys, Stripe secrets, or raw provider responses.
+Completed Registration is tracked by the server only when the app successfully calls `POST /sdk/public/users/:user_id/claim_subscription` after login/signup.
+
+## Preview Runtime
+
+Builder preview is intentionally different from production:
+
+- normal SDK writes are skipped or replaced with local fallbacks;
+- manage-subscription uses a preview fallback payload;
+- runtime mode and paywall plans can be patched by the builder preview bridge;
+- checkout may force test mode when the preview payment key is active.
+
+Do not make preview-only shortcuts the production contract.
+
+## Architecture Change Checklist
+
+When a funnel architecture change touches any item below, update `template_docs` with the new behavior:
+
+- route paths, manifest step ids, entry points, or step kinds;
+- runtime user state, URL parameters, attribution, or answer persistence;
+- SDK endpoint paths, query/body fields, response shape, or auth headers;
+- payment plan mapping, checkout metadata, return URLs, discounts, or Stripe mode resolution;
+- manage-subscription identity resolution or mutation behavior;
+- subscription handoff links, app/deep-link templates, or post-checkout routing;
+- analytics event names or required metadata;
+- preview/editor runtime behavior.

package/template_docs/docs/meta-pixel-conversions-api.md

@@ -0,0 +1,50 @@
+# Meta Pixel and Conversions API
+
+Meta analytics is provider-specific. Keep funnel code on the `@funnelsgrove/analytics` API surface; do not call `fbq`, Meta Pixel, or Conversions API directly from funnel steps.
+
+## Browser Pixel Events
+
+The browser Pixel is initialized by `@funnelsgrove/analytics` when both public env vars are set:
+
+- `NEXT_PUBLIC_META_PIXEL_ENABLED=true`
+- `NEXT_PUBLIC_META_PIXEL_ID=<pixel id>`
+
+Browser events:
+
+- `publicAnalyticsSdk.trackFirstStepViewed(...)` sends Meta `ViewContent` when the user lands on the real first funnel page.
+- `publicAnalyticsSdk.trackFirstStepClicked(...)` is still supported for funnels or experiments that need click-specific first-step analytics. It also maps to Meta `ViewContent`.
+- `checkout_started` maps to Meta `InitiateCheckout`.
+- `checkout_completed` maps to Meta `AddPaymentInfo`.
+
+Do not fire both `trackFirstStepViewed(...)` and `trackFirstStepClicked(...)` for the same intended conversion unless the product explicitly wants two separate analytics events. Preview runtime must not send normal Pixel events.
+
+The browser Pixel owns browser attribution automatically through Meta cookies such as `_fbp` and `_fbc`.
+
+## Server Conversions API Events
+
+Server-side Meta events go through the API analytics service and Facebook Conversions API. Project env requires:
+
+- `META_CONVERSIONS_ACCESS_TOKEN=<server token>`
+- Optional test helper: `META_TEST_EVENT_CODE=<Meta test code>`
+
+Trusted server events currently come from Stripe webhooks:
+
+- Paid checkout session, invoice, or payment intent sends Meta `Purchase`.
+- Active or trialing subscription webhook sends Meta `Subscribe`.
+
+Server events use the funnel user id as Meta `external_id`; do not use the funnel user id as an event id. Event ids must be unique per event. Use one generated event id for a browser/server pair only when both sides represent the same user action and should be deduplicated.
+
+## Attribution Matching
+
+Runtime stores URL/referrer attribution in `funnelUser.document.attribution`.
+
+Keep `fbclid` in attribution. The API can derive Meta `fbc` from stored `fbclid` and the attribution capture time for later Stripe webhook conversions. The API also sends known email, funnel user id, user agent, and other available match fields.
+
+Do not invent or strip attribution URL params unless the funnel runtime attribution docs and SDK contract are updated in the same change.
+
+## Agent Rules
+
+- Use analytics package helpers instead of raw Meta calls.
+- When changing first-page routing, verify `ViewContent` still fires only for the real first landing page and not preview runtime.
+- When changing checkout or subscription behavior, verify the corresponding server CAPI event still has project id, funnel user id, event id, currency/value where available, and stored attribution.
+- Do not send secrets, raw Stripe objects, access tokens, or full payment payloads to browser analytics.

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

@@ -44,10 +44,48 @@ Prefer shared Stripe surfaces:
 
 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.
 
+### Shared Checkout V2 and Wallet Slots
+
+Subscription paywalls with on-page wallet buttons should share one `useStripeSubscriptionCheckoutSession(...)` instance across the manual card checkout and wallet checkout. Do not build funnel-local Stripe PaymentIntent or Express Checkout flows.
+
+- Use `SharedStripeCheckoutV2Dialog` for the manual/card checkout modal. Open it from the paywall CTA after the checkout session has an `activeClientSecret` and `stripePromise`.
+- Render real wallet slots on the paywall with `ApplePaySubscriptionCheckoutSlot` and `GooglePaySubscriptionCheckoutSlot`, usually above the manual/card CTA. Pass the same checkout session, selected plan amount, return URL, customer details, summary label, success handler, and any `beforeConfirm` logic used to finalize email or analytics metadata.
+- Use `usePlatformWalletPaymentMethods()` to decide which slots to render. Desktop web can show Apple Pay and Google Pay; iOS shows Apple Pay; Android shows Google Pay.
+- Track each slot's `onAvailabilityChange` result by the current `checkoutSession.intentKey`. When opening `SharedStripeCheckoutV2Dialog`, derive `initialWalletAvailable` from the current intent's confirmed wallet availability and pass it into the dialog so checkout can show the wallet tab immediately when a wallet is already known to be available.
+- Treat unknown wallet availability as `null`, not `false`. Only hide/fallback from a wallet after Stripe or the shared slot reports that wallet unavailable.
+- Suspend paywall wallet slots while the shared checkout dialog or another blocking offer modal is open, so two Stripe Express Checkout elements do not compete for the same active checkout session.
+
+## Paywall Identity Handoff
+
+Paywall steps may be opened directly by support/admin links:
+
+- `/paywall?user_id=u_123` resumes a known funnel user and carries that id into checkout metadata.
+- `/paywall?email=user@example.com` seeds the runtime user email and Stripe `customerEmail`.
+- `/paywall?user_id=u_123&email=user@example.com` is preferred when both are known.
+
+`user_id` is the strongest join key for answers, attribution, checkout metadata, and webhook reconciliation. Email-only handoff is useful for prefilled checkout and private user lookup, but do not treat it as a full replacement for `user_id` when exact progress/subscription state is required.
+
+Checkout return URLs should route to the subscription-started step and preserve the user id, for example `/subscription-started?user_id=u_123&source=stripe-elements`.
+
+## Manage Subscription Handoff
+
+Manage subscription is a customer support route, usually `/manage-subscription`.
+
+Supported links:
+
+- `/manage-subscription?user_id=u_123`
+- `/manage-subscription?stripe_customer_id=cus_123`
+- `/manage-subscription?user_id=u_123&stripe_customer_id=cus_123`
+
+The runtime calls `apiService.getManageSubscriptions()` and `apiService.updateSubscription(...)`, which send `user_id`, `stripe_customer_id`, and `funnelId` to the public subscriptions SDK endpoints. If neither id is present, the list endpoint returns an empty summary and mutation is rejected.
+
+Generated support/admin links should include `user_id` and add `stripe_customer_id` when the paid customer id is known.
+
 ## 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.
+- Keep paywall, checkout, subscription-started, and manage-subscription identity handoff parameters in sync with [Funnel Runtime Architecture](funnel-runtime-architecture.md).
 - 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

@@ -10,6 +10,14 @@ fgrove sync up --message '<summary>'
 fgrove publish --env preview --message '<summary>'
 ```
 
+Refresh the ignored local `.env` from the remote project when project settings change:
+
+```bash
+fgrove env pull
+# or, from outside the synced funnel directory:
+fgrove env pull --dir ./path/to/local-funnel
+```
+
 Only publish production when explicitly requested:
 
 ```bash
@@ -30,6 +38,8 @@ Local-only files are excluded from upload:
 - `.next`.
 - `out`.
 
+The local `.env` is runtime material generated from remote project/funnel settings. Use `fgrove env pull` to refresh it without replacing source files.
+
 Do not edit generated build output as the source of truth.
 
 ## Agent Rules

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

@@ -26,6 +26,17 @@ Use `apiService` from `@funnelsgrove/runtime`:
 
 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.
 
+## URL User Attributes
+
+The runtime understands these public URL attributes:
+
+- `user_id`: canonical funnel user id.
+- `email`: validated user/customer email.
+- `name`, `fullName`, `full_name`: profile name aliases.
+- `stripe_customer_id`: Stripe customer id for subscription management.
+
+Keep these names stable. If an SDK endpoint or route starts accepting a new identity parameter, update the URL parser, shared services, and docs together.
+
 ## Payment APIs
 
 Use `@funnelsgrove/payments`:
@@ -37,6 +48,25 @@ Use `@funnelsgrove/payments`:
 
 Always pass runtime checkout config so published funnels, preview funnels, and local builds resolve the correct funnel id and SDK key.
 
+Checkout endpoints receive `user_id` and `customerEmail` when available. Stripe metadata and `client_reference_id` rely on these values for webhook reconciliation, analytics, and project user support links.
+
+## Subscription APIs
+
+Use the runtime service methods instead of calling the endpoints directly:
+
+- `GET /sdk/public/users/:user_id/subscription` or `GET /sdk/public/users/subscription?email=...` -> lightweight entitlement status with the resolved `user_id`, `active`, `activeUntil`, and active Stripe subscription ids.
+- `POST /sdk/public/users/:user_id/claim_subscription` -> claim the first unclaimed active subscription for that `user_id`.
+- `apiService.getManageSubscriptions()` -> `GET /sdk/public/subscriptions`.
+- `apiService.updateSubscription(...)` -> `POST /sdk/public/subscriptions/:subscriptionId/:action`.
+
+The status endpoint accepts `user_id` or `email` and returns the resolved `user.user_id` when a funnel user is found. The claim endpoint accepts `funnelId` in the JSON body and only resolves by path `user_id`; it returns `409` if every active subscription is already claimed.
+
+The subscription list endpoint accepts `user_id`, `stripe_customer_id`, and `funnelId`. `user_id` resolves the funnel user first; `stripe_customer_id` can resolve the Stripe customer directly when user id is unavailable. Mutation requires `user_id` or `stripe_customer_id` and supports `cancel` or `renew`.
+
+## Private User Reads
+
+Private SDK user reads are for server-side/admin use only. They can resolve a funnel user by `funnelUserId`, `user_id`, `email`, or `stripeCustomerId` when scoped by the SDK secret key and funnel. This is why paywall email handoff is still useful even when a public link does not know the user id yet.
+
 ## Rules
 
 - Keep payloads minimal and typed.