@funnelsgrove/cli 0.1.29 → 0.1.43

package/template_scaffold/docs/funnelsgrove/START-HERE.md

@@ -54,7 +54,10 @@ Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf
 - A paywall presents purchasable plans. A loading, reveal, or “ready” screen is an interstitial.
 - Every choice declares `choice.answerKey`, stores stable option IDs in the exact scalar/array shape, and uses `useStepChoices`.
 - Email capture uses `submitEmailCapture`; it never manually sends analytics or hard-codes paywall navigation.
-- `subscription-started` is the `purchase_completed` terminal. Browser terminal reach is not Quiz completed; only the trusted backend records `purchase_completed` after verifying an initial purchase.
+- Quiz completed counts each unique user who reaches a paywall step.
+- `purchase_completed` remains trusted-server-only purchase verification and does not define Quiz completed.
+- Browser terminal reach and `funnel_completed` remain lifecycle-only and are not purchase conversions.
+- `subscription-started` remains the contract-v3 `purchase_completed` terminal type, and only the trusted backend records the purchase event after verifying an initial purchase.
 - Let the controller distinguish completion from exit and suppress provider delivery in preview.
 
 ## Standard workflow

package/template_scaffold/docs/funnelsgrove/contracts/analytics-events.md

@@ -24,7 +24,9 @@ Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf
 | `step_exited` | `step_exited` | `step_exit` | `any` | `any` | `controller` | `true` | `step-visit` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `stepId`, `stepName`, `stepType` |
 | `step_started` | `step_started` | `step_start` | `any` | `any` | `controller` | `true` | `step-visit` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `stepId`, `stepName`, `stepType` |
 
-The `purchase_completed` event is owned by `trusted-server` and is recorded only after the backend verifies a successful initial purchase. Entering the browser terminal or emitting `funnel_completed` does not create this business conversion. The separate `registration_completed` event remains owned by `trusted-server` for the later app-link claim. The `email_captured` event is owned by `transactional-server` and uses `logical-email-conversion` deduplication.
+Quiz completed counts each unique user who reaches a paywall step. `purchase_completed` remains trusted-server-only purchase verification and does not define Quiz completed. Browser terminal reach and `funnel_completed` remain lifecycle-only and are not purchase conversions.
+
+The `purchase_completed` event is owned by `trusted-server` and is recorded only after the backend verifies a successful initial purchase. The separate `registration_completed` event remains owned by `trusted-server` for the later app-link claim. The `email_captured` event is owned by `transactional-server` and uses `logical-email-conversion` deduplication.
 <!-- funnelsgrove:generated:end contract-v3/contract/analytics-events -->
 
 ## Ownership rules
@@ -34,7 +36,7 @@ The `purchase_completed` event is owned by `trusted-server` and is recorded only
 - `submitEmailCapture` creates `email_captured` transactionally, then routes only after success.
 - Named payment helpers emit checkout semantic events at real payment boundaries.
 - The terminal helper owns funnel completion.
-- A trusted backend owns `purchase_completed` after verifying an initial subscription or one-time payment; browser code never emits it, and terminal reach does not count as Quiz completed.
+- A trusted backend owns `purchase_completed` after verifying an initial subscription or one-time payment; browser code never emits it. This purchase event is independent from the paywall-reach definition of Quiz completed.
 - A separate trusted server claim owns `registration_completed` when the purchased subscription is later linked in the app.
 - Provider adapters and the durable outbox own PostHog and server Meta delivery.
 

package/template_scaffold/docs/funnelsgrove/contracts/payments.md

@@ -37,6 +37,8 @@ A paywall presents purchasable plans. A reveal, loading state, calculation, or
 
 ## Purchase completion separation
 
-The canonical `subscription-started` route keeps its stable identity but uses the `purchase_completed` terminal type in contract v3. It may emit lifecycle-only `funnel_completed`, but entering it never counts as Quiz completed. Only the trusted backend emits `purchase_completed` after verifying an initial subscription or one-time payment; renewals, pending payments, and browser checkout returns do not qualify. `registration_completed` remains the later app-link conversion.
+Quiz completed counts each unique user who reaches a paywall step. `purchase_completed` remains trusted-server-only purchase verification and does not define Quiz completed. Browser terminal reach and `funnel_completed` remain lifecycle-only and are not purchase conversions.
+
+The canonical `subscription-started` route keeps its stable identity and remains the `purchase_completed` terminal type in contract v3. Only the trusted backend emits the purchase event after verifying an initial subscription or one-time payment; renewals, pending payments, and browser checkout returns do not qualify. `registration_completed` remains the later app-link conversion.
 
 Before publishing, complete [paywall/checkout QA](../qa/paywall-checkout.md) and [publish QA](../qa/publish.md).

package/template_scaffold/docs/funnelsgrove/migrations/step-contract-v3.md

@@ -17,7 +17,7 @@ Supported read versions: `1`, `2`, `3`. Authoring and publish target version `3`
 
 ### Package release order
 
-Release `@funnelsgrove/runtime` `0.1.60` first, then `@funnelsgrove/analytics` `0.1.37`, then `@funnelsgrove/payments` `0.1.55`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.29`. Publishing packages and deploying production remain separately approved operational actions.
+Release `@funnelsgrove/runtime` `0.1.63` first, then `@funnelsgrove/analytics` `0.1.41`, then `@funnelsgrove/payments` `0.1.58`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.43`. Publishing packages and deploying production remain separately approved operational actions.
 <!-- funnelsgrove:generated:end contract-v3/migration/step-contract-v3 -->
 
 ## Version-last policy

package/template_scaffold/docs/funnelsgrove/qa/analytics.md

@@ -32,7 +32,9 @@ Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf
 - Choice steps save the exact stable ID shape before completion.
 - Email success creates one server conversion; duplicate capture skips browser fanout; failure changes no state/lifecycle/route.
 - Checkout helpers fire only at real boundaries with complete metadata and stable event IDs.
-- Quiz completed requires trusted-server `purchase_completed`, deduplicated by `provider-payment`; browser `funnel_completed` is lifecycle-only and never satisfies it.
+- Quiz completed counts each unique user who reaches a paywall step.
+- `purchase_completed` remains trusted-server-only purchase verification and does not define Quiz completed.
+- Browser terminal reach and `funnel_completed` remain lifecycle-only and are not purchase conversions.
 - `registration_completed` remains the separate later app-link claim.
 - Preview sends no API/provider analytics.
 - No component sends PostHog or server Meta directly.

package/template_scaffold/funnel-docs.config.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.17",
+  "bundleVersion": "2.0.31",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",

package/template_scaffold/package-lock.json

@@ -8,9 +8,9 @@
       "name": "funnel-template",
       "version": "0.1.0",
       "dependencies": {
-        "@funnelsgrove/analytics": "^0.1.37",
-        "@funnelsgrove/payments": "^0.1.55",
-        "@funnelsgrove/runtime": "^0.1.60",
+        "@funnelsgrove/analytics": "^0.1.41",
+        "@funnelsgrove/payments": "^0.1.58",
+        "@funnelsgrove/runtime": "^0.1.63",
         "@stripe/react-stripe-js": "^5.6.0",
         "@stripe/stripe-js": "^8.7.0",
         "lucide-react": "^0.553.0",
@@ -891,17 +891,17 @@
       }
     },
     "node_modules/@funnelsgrove/analytics": {
-      "version": "0.1.37",
-      "resolved": "https://registry.npmjs.org/@funnelsgrove/analytics/-/analytics-0.1.37.tgz",
-      "integrity": "sha512-MlXNdsGmNZNpDl5k1J4jKMsB8PYXVTZ2QZjhvSL3Ii0QKoCD9Gru/PprS/TlJ6jQ0Hscy/0vqGB3FZ6sa2Fwag==",
+      "version": "0.1.41",
+      "resolved": "https://registry.npmjs.org/@funnelsgrove/analytics/-/analytics-0.1.41.tgz",
+      "integrity": "sha512-RrAlBajsJawxpG1ijthRhGcuyqoPCP29r4XNu3K980zrtkWidYu0E4TqBPdPHTmhBb6WNnMcfVHV6H7XaqkQ8A==",
       "dependencies": {
-        "@funnelsgrove/runtime": "0.1.60"
+        "@funnelsgrove/runtime": "0.1.63"
       }
     },
     "node_modules/@funnelsgrove/payments": {
-      "version": "0.1.55",
-      "resolved": "https://registry.npmjs.org/@funnelsgrove/payments/-/payments-0.1.55.tgz",
-      "integrity": "sha512-zrlnyPwUsqSYkaDYASBkB3bzNVSzS0+4glKC2+ai/+fIi4SZqEOAEo51WxR3jt0s5dAX2nFdX08r/YlvY7XqyA==",
+      "version": "0.1.58",
+      "resolved": "https://registry.npmjs.org/@funnelsgrove/payments/-/payments-0.1.58.tgz",
+      "integrity": "sha512-y1caUil8SFNiuYf/TxptheEf/cnK2urafy2eF2gFdfugfaybFiqUiyTzEVen+K+uKtX8tDCk2UtNeyWMO8inAA==",
       "dependencies": {
         "@funnelsgrove/analytics": "^0.1.28",
         "@funnelsgrove/runtime": "^0.1.54",
@@ -913,9 +913,9 @@
       }
     },
     "node_modules/@funnelsgrove/runtime": {
-      "version": "0.1.60",
-      "resolved": "https://registry.npmjs.org/@funnelsgrove/runtime/-/runtime-0.1.60.tgz",
-      "integrity": "sha512-ftjWXqcXmzPKlESo57B4o6VHc0NFiyxJrKB0CYMqVcxgBo9O5d7h/lZhs/1Wi3pQNRsBSGOfs//MUC/hJQ/NOw==",
+      "version": "0.1.63",
+      "resolved": "https://registry.npmjs.org/@funnelsgrove/runtime/-/runtime-0.1.63.tgz",
+      "integrity": "sha512-D0y7l/GwVc519CBr3TCxsXvr3H+B9RmcvebBUKks+FqdDx5j2AO5qdUbB838bqkBNCCjHOtcbs3u2Gsm4Qhk4w==",
       "dependencies": {
         "posthog-js": "^1.369.2",
         "react": "19.2.3",

package/template_scaffold/package.json

@@ -12,9 +12,9 @@
     "validate:funnel": "vite-node --config src/contract/funnel-validator.vite.config.ts src/contract/validate-funnel.cli.ts"
   },
   "dependencies": {
-    "@funnelsgrove/analytics": "^0.1.37",
-    "@funnelsgrove/payments": "^0.1.55",
-    "@funnelsgrove/runtime": "^0.1.60",
+    "@funnelsgrove/analytics": "^0.1.41",
+    "@funnelsgrove/payments": "^0.1.58",
+    "@funnelsgrove/runtime": "^0.1.63",
     "@stripe/react-stripe-js": "^5.6.0",
     "@stripe/stripe-js": "^8.7.0",
     "lucide-react": "^0.553.0",

package/template_scaffold/src/steps/step-32-paywall.tsx

@@ -463,7 +463,7 @@ export function StepPaywall({
       return;
     }
 
-    const readyClientSecret = await checkoutSession.prepareCardCheckout();
+    const readyClientSecret = await checkoutSession.prepareCardCheckout({ checkoutStartSource: 'checkout_render' });
     if (readyClientSecret) {
       setCheckoutDialogOpen(true);
     }
@@ -510,7 +510,7 @@ export function StepPaywall({
     }
 
     const readyClientSecret =
-      checkoutSession.activeClientSecret ?? await checkoutSession.prepareCardCheckout();
+      checkoutSession.activeClientSecret ?? await checkoutSession.prepareCardCheckout({ checkoutStartSource: 'checkout_render' });
     if (readyClientSecret) {
       setCheckoutDialogOpen(true);
     }

package/template_scaffold/src/steps/step-33-subscription-started.tsx

@@ -1,8 +1,6 @@
 // PLAN_STEP_PLACEHOLDER_ID:subscription-started
 'use client';
 
-import { useEffect } from 'react';
-import { publicAnalyticsSdk } from '@funnelsgrove/analytics';
 import {
   SubscriptionHandoffScreen,
   usePreviewStepLocalizedContent,
@@ -11,7 +9,6 @@ import {
 } from '@funnelsgrove/runtime';
 import { getStepContentLocale } from '@/runtime/step-content-context';
 import { subscriptionStartedContent } from '@/steps/content/subscription-started.content';
-import { funnelManifest } from '@/config/funnel.manifest';
 
 export const stepSubscriptionStartedId = 'subscription-started';
 
@@ -29,52 +26,13 @@ export const stepSubscriptionStarted: FunnelStepMeta = {
 };
 
 export function StepSubscriptionStarted() {
-  const { user, attributes } = useFunnel();
+  const { attributes } = useFunnel();
   const content = usePreviewStepLocalizedContent(
     stepSubscriptionStartedId,
     subscriptionStartedContent,
     getStepContentLocale(attributes),
   );
 
-  useEffect(() => {
-    if (typeof window === 'undefined') {
-      return;
-    }
-
-    const searchParams = new URLSearchParams(window.location.search);
-    const paymentIntent = searchParams.get('payment_intent');
-    const redirectStatus = searchParams.get('redirect_status');
-    if (!paymentIntent || !redirectStatus) {
-      return;
-    }
-
-    const dedupeKey = `app-deals:payment-intent:${paymentIntent}`;
-    if (window.sessionStorage.getItem(dedupeKey) === '1') {
-      return;
-    }
-    window.sessionStorage.setItem(dedupeKey, '1');
-
-    const eventInput = {
-      stepId: stepSubscriptionStartedId,
-      stepName: stepSubscriptionStarted.name || stepSubscriptionStarted.title,
-      stepType: stepSubscriptionStarted.type,
-      stepContractVersion: funnelManifest.stepContractVersion,
-      metadata: {
-        source: searchParams.get('source') || null,
-        paymentIntent,
-        redirectStatus,
-        user_id: searchParams.get('user_id') || null,
-        funnelUserId: user.id || null,
-      },
-    };
-
-    if (redirectStatus === 'succeeded') {
-      publicAnalyticsSdk.trackPaymentCheckoutSucceeded(eventInput);
-    } else {
-      publicAnalyticsSdk.trackPaymentCheckoutReturned(eventInput);
-    }
-  }, [user.id]);
-
   return (
     <SubscriptionHandoffScreen
       stepId={stepSubscriptionStartedId}

package/template_scaffold/{funnel-agent-docs.test.ts → tests/funnel-agent-docs.test.ts}

@@ -7,9 +7,9 @@ import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 
-import contract from '../funnel-runtime/contracts/step-contract-v2.json';
+import contract from '../../funnel-runtime/contracts/step-contract-v2.json';
 
-const templateRoot = dirname(fileURLToPath(import.meta.url));
+const templateRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const repoRoot = resolve(templateRoot, '../..');
 const cliDocsRoot = join(repoRoot, 'apps/cli/template_docs');
 
@@ -34,7 +34,7 @@ const renderCodes = (values: readonly unknown[]): string => (
 );
 
 async function loadGenerator() {
-  return import('../../scripts/generate-funnel-agent-docs.mjs');
+  return import('../../../scripts/generate-funnel-agent-docs.mjs');
 }
 
 describe('funnel agent documentation supply', () => {
@@ -300,21 +300,31 @@ describe('funnel agent documentation supply', () => {
     }
   });
 
-  it('requires trusted purchase completion for the Quiz completed QA assertion', async () => {
-    const content = await readFile(
-      join(templateRoot, 'docs/funnelsgrove/qa/analytics.md'),
-      'utf8',
-    );
-
-    expect(content).toContain(
-      'Quiz completed requires trusted-server `purchase_completed`, deduplicated by `provider-payment`',
-    );
-    expect(content).toContain(
-      'browser `funnel_completed` is lifecycle-only and never satisfies it',
-    );
-    expect(content).toContain(
-      '`registration_completed` remains the separate later app-link claim',
-    );
+  it('defines Quiz completed by unique paywall reach without conflating purchase verification', async () => {
+    const paths = [
+      'docs/funnelsgrove/qa/analytics.md',
+      'docs/funnelsgrove/contracts/analytics-events.md',
+      'docs/funnelsgrove/START-HERE.md',
+      'docs/funnelsgrove/contracts/payments.md',
+    ];
+    const contents = await Promise.all(paths.map(async (path) => ({
+      path,
+      content: await readFile(join(templateRoot, path), 'utf8'),
+    })));
+
+    for (const { path, content } of contents) {
+      expect(content, path).toContain(
+        'Quiz completed counts each unique user who reaches a paywall step.',
+      );
+      expect(content, path).toContain(
+        '`purchase_completed` remains trusted-server-only purchase verification and does not define Quiz completed.',
+      );
+      expect(content, path).toContain(
+        'Browser terminal reach and `funnel_completed` remain lifecycle-only and are not purchase conversions.',
+      );
+      expect(content, path).not.toMatch(/Quiz completed requires[^.]*purchase_completed/i);
+      expect(content, path).not.toMatch(/terminal reach[^.]*not (?:count|counts) as Quiz completed/i);
+    }
   });
 
   it('preserves the implementation-owned visitor metric while linking event ownership', async () => {
@@ -340,7 +350,7 @@ describe('funnel agent documentation supply', () => {
 
     expect(manifest).toMatchObject({
       schemaVersion: 1,
-      bundleVersion: '2.0.17',
+      bundleVersion: '2.0.31',
       stepContractVersion: contract.stepContractVersion,
       contractHash: contract.contractHash,
     });

package/template_scaffold/{package.test.ts → tests/package.test.ts}

@@ -11,10 +11,10 @@ const readPackageJson = (url: URL): PackageJson =>
 
 describe('funnel-template shared package dependencies', () => {
   it('tracks the current shared runtime, analytics, and payments package versions', () => {
-    const templatePackage = readPackageJson(new URL('./package.json', import.meta.url));
-    const runtimePackage = readPackageJson(new URL('../funnel-runtime/package.json', import.meta.url));
-    const analyticsPackage = readPackageJson(new URL('../funnel-analytics/package.json', import.meta.url));
-    const paymentsPackage = readPackageJson(new URL('../funnel-payments/package.json', import.meta.url));
+    const templatePackage = readPackageJson(new URL('../package.json', import.meta.url));
+    const runtimePackage = readPackageJson(new URL('../../funnel-runtime/package.json', import.meta.url));
+    const analyticsPackage = readPackageJson(new URL('../../funnel-analytics/package.json', import.meta.url));
+    const paymentsPackage = readPackageJson(new URL('../../funnel-payments/package.json', import.meta.url));
 
     expect(templatePackage.dependencies?.['@funnelsgrove/runtime']).toBe(`^${runtimePackage.version}`);
     expect(templatePackage.dependencies?.['@funnelsgrove/analytics']).toBe(`^${analyticsPackage.version}`);

package/template_scaffold/{src → tests/src}/app/layout.test.ts

@@ -4,7 +4,7 @@ import { describe, expect, it } from 'vitest';
 
 describe('RootLayout metadata source', () => {
   it('wires project page metadata settings into Next metadata', () => {
-    const layoutSource = readFileSync(path.resolve(__dirname, './layout.tsx'), 'utf8');
+    const layoutSource = readFileSync(path.resolve(__dirname, '../../../src/app/layout.tsx'), 'utf8');
 
     expect(layoutSource).toContain('runtimePublicConfig.pageTitle');
     expect(layoutSource).toContain('runtimePublicConfig.pageDescription');
@@ -15,7 +15,7 @@ describe('RootLayout metadata source', () => {
   });
 
   it('renders Google tag head scripts through the shared analytics package', () => {
-    const layoutSource = readFileSync(path.resolve(__dirname, './layout.tsx'), 'utf8');
+    const layoutSource = readFileSync(path.resolve(__dirname, '../../../src/app/layout.tsx'), 'utf8');
 
     expect(layoutSource).toContain("import { buildGoogleTagHeadScripts } from '@funnelsgrove/analytics'");
     expect(layoutSource).toContain('const googleTagHeadScripts = buildGoogleTagHeadScripts();');

package/template_scaffold/{src → tests/src}/components/FunnelFlow.test.tsx

@@ -3,9 +3,9 @@ import { describe, expect, it } from 'vitest';
 
 describe('FunnelFlow lifecycle wiring', () => {
   it('delegates one analytics adapter and the authoritative manifest version to the shared controller', () => {
-    const flowSource = readFileSync(new URL('./FunnelFlow.tsx', import.meta.url), 'utf8');
+    const flowSource = readFileSync(new URL('../../../src/components/FunnelFlow.tsx', import.meta.url), 'utf8');
     const adapterSource = readFileSync(
-      new URL('../runtime/use-funnel-flow-controller.ts', import.meta.url),
+      new URL('../../../src/runtime/use-funnel-flow-controller.ts', import.meta.url),
       'utf8',
     );
 

package/template_scaffold/{src → tests/src}/config/billing.plans.test.ts

@@ -45,7 +45,7 @@ describe('claimbee billing contract', () => {
   });
 
   it('exports minimal live billing config and normalized discounts', async () => {
-    const billingModule = await import('./billing.plans');
+    const billingModule = await import('../../../src/config/billing.plans');
     const {
       billing,
       billingDiscountList,
@@ -87,7 +87,7 @@ describe('claimbee billing contract', () => {
 
   it('uses test provider price ids when Stripe mode is test', async () => {
     stubRuntimeMode('test');
-    const { billing } = await import('./billing.plans');
+    const { billing } = await import('../../../src/config/billing.plans');
 
     expect(billing.plans.primary.projectPlanId).toBe(CLAIMBEE_PROJECT_PLAN_IDS.weekly);
     expect(billing.plans.primary.providerPlanId).toBe(CLAIMBEE_TEST_PROVIDER_PLAN_IDS.weekly);
@@ -98,7 +98,7 @@ describe('claimbee billing contract', () => {
   });
 
   it('exports the split test plan catalog under the generic billingTestPlans name', async () => {
-    const billingTestModule = await import('./billing.test.plans') as Record<string, unknown>;
+    const billingTestModule = await import('../../../src/config/billing.test.plans') as Record<string, unknown>;
 
     expect(billingTestModule.billingTestPlans).toEqual({
       primary: expect.objectContaining({
@@ -117,7 +117,7 @@ describe('claimbee billing contract', () => {
   });
 
   it('lets payments helpers derive ordered paywall plans from semantic keys', async () => {
-    const { billingPlans } = await import('./billing.plans');
+    const { billingPlans } = await import('../../../src/config/billing.plans');
 
     expect(buildConfigPaywallPlans(billingPlans, ['primary', 'secondary', 'tertiary'])).toEqual([
       expect.objectContaining({

package/template_scaffold/{src → tests/src}/config/experiments.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { experiments, manifestExperiments } from './experiments';
+import { experiments, manifestExperiments } from '../../../src/config/experiments';
 
 describe('funnel experiments config', () => {
   it('ships the generic template without brand-specific experiments', () => {

package/template_scaffold/{src → tests/src}/config/funnel.manifest.test.ts

@@ -8,7 +8,7 @@ import {
 import { stepRegistry } from '@/runtime/step-registry';
 import { stepTwoContent, stepTwoOptions } from '@/steps/content/step-02.content';
 import { contentOptionsByStepId } from '@/steps/step-content.registry';
-import { funnelManifest } from './funnel.manifest';
+import { funnelManifest } from '../../../src/config/funnel.manifest';
 
 describe('funnel manifest breakpoints', () => {
   it('ships the four default QA breakpoints for new funnels', () => {

package/template_scaffold/{src → tests/src}/contract/funnel-project.validation.test.ts

@@ -5,14 +5,14 @@ import {
   CURRENT_STEP_CONTRACT_VERSION,
   type FunnelStepContractProjectSnapshot,
 } from '@funnelsgrove/runtime';
-import docsManifest from '../../.funnelsgrove-docs.json';
+import docsManifest from '../../../.funnelsgrove-docs.json';
 import { manifestExperiments } from '@/config/experiments';
 import { funnelManifest, rawFunnelManifest } from '@/config/funnel.manifest';
 import { stepRegistry } from '@/runtime/step-registry';
 import { contentOptionsByStepId } from '@/steps/step-content.registry';
 
 const loadProjectValidation = async () => {
-  return import('./funnel-project.validation');
+  return import('../../../src/contract/funnel-project.validation');
 };
 
 describe('funnel project validation', () => {

package/template_scaffold/{src → tests/src}/contract/golden/golden-fixtures.test.ts

@@ -9,22 +9,22 @@ import {
   type FunnelManifest,
 } from '@funnelsgrove/runtime';
 import { publicAnalyticsSdk } from '@funnelsgrove/analytics';
-import { goldenFixture as cancellationOffer } from './cancellation_offer.fixture';
-import { goldenFixture as checkout } from './checkout.fixture';
-import { goldenFixture as purchaseCompleted } from './purchase_completed.fixture';
-import { goldenFixture as formInput } from './form_input.fixture';
-import { goldenFixture as introHero } from './intro_hero.fixture';
-import { goldenFixture as multiSelectChoice } from './multi_select_choice.fixture';
-import { goldenFixture as paywallOffer } from './paywall_offer.fixture';
-import { goldenFixture as progressInterstitial } from './progress_interstitial.fixture';
-import { goldenFixture as singleStepChoice } from './single_step_choice.fixture';
-import { goldenFixture as singleStepChoiceEmoji } from './single_step_choice_emoji.fixture';
-import { goldenFixture as socialProof } from './social_proof.fixture';
-import { goldenFixture as subscriptionHandoff } from './subscription_handoff.fixture';
-import { goldenFixture as subscriptionManagement } from './subscription_management.fixture';
-import { goldenFixture as summaryConfirmation } from './summary_confirmation.fixture';
-import { goldenFixture as upsellOffer } from './upsell_offer.fixture';
-import { goldenFixture as valuePropStory } from './value_prop_story.fixture';
+import { goldenFixture as cancellationOffer } from '../../../../src/contract/golden/cancellation_offer.fixture';
+import { goldenFixture as checkout } from '../../../../src/contract/golden/checkout.fixture';
+import { goldenFixture as purchaseCompleted } from '../../../../src/contract/golden/purchase_completed.fixture';
+import { goldenFixture as formInput } from '../../../../src/contract/golden/form_input.fixture';
+import { goldenFixture as introHero } from '../../../../src/contract/golden/intro_hero.fixture';
+import { goldenFixture as multiSelectChoice } from '../../../../src/contract/golden/multi_select_choice.fixture';
+import { goldenFixture as paywallOffer } from '../../../../src/contract/golden/paywall_offer.fixture';
+import { goldenFixture as progressInterstitial } from '../../../../src/contract/golden/progress_interstitial.fixture';
+import { goldenFixture as singleStepChoice } from '../../../../src/contract/golden/single_step_choice.fixture';
+import { goldenFixture as singleStepChoiceEmoji } from '../../../../src/contract/golden/single_step_choice_emoji.fixture';
+import { goldenFixture as socialProof } from '../../../../src/contract/golden/social_proof.fixture';
+import { goldenFixture as subscriptionHandoff } from '../../../../src/contract/golden/subscription_handoff.fixture';
+import { goldenFixture as subscriptionManagement } from '../../../../src/contract/golden/subscription_management.fixture';
+import { goldenFixture as summaryConfirmation } from '../../../../src/contract/golden/summary_confirmation.fixture';
+import { goldenFixture as upsellOffer } from '../../../../src/contract/golden/upsell_offer.fixture';
+import { goldenFixture as valuePropStory } from '../../../../src/contract/golden/value_prop_story.fixture';
 
 const fixtures = [
   cancellationOffer,

package/template_scaffold/{src → tests/src}/contract/validate-funnel.cli.test.ts

@@ -12,7 +12,7 @@ import {
 const execFileAsync = promisify(execFile);
 
 const loadCli = async () => {
-  return import('./validate-funnel.cli');
+  return import('../../../src/contract/validate-funnel.cli');
 };
 
 const diagnostic = createFunnelContractDiagnostic({
@@ -150,7 +150,7 @@ describe('validate funnel CLI protocol', () => {
   });
 
   it('runs through vite-node with one clean stdout protocol object', async () => {
-    const templateRoot = path.resolve(fileURLToPath(new URL('../..', import.meta.url)));
+    const templateRoot = path.resolve(fileURLToPath(new URL('../../..', import.meta.url)));
     const viteNode = path.resolve(templateRoot, '../../node_modules/.bin/vite-node');
     const script = path.resolve(templateRoot, 'src/contract/validate-funnel.cli.ts');
 

package/template_scaffold/{src → tests/src}/runtime/checkout-runtime-config.test.ts

@@ -23,7 +23,7 @@ describe('checkoutRuntimeConfig', () => {
   it('does not invent a checkout SDK publishable key from generic Stripe env', async () => {
     process.env.NEXT_PUBLIC_STRIPE_TEST_PUBLISHABLE_KEY = 'pk_test_generic_runtime_value';
 
-    const { checkoutRuntimeConfig } = await import('./checkout-runtime-config');
+    const { checkoutRuntimeConfig } = await import('../../../src/runtime/checkout-runtime-config');
 
     expect(checkoutRuntimeConfig.funnelSdkPublishableKey).toBeNull();
   });
@@ -43,7 +43,7 @@ describe('checkoutRuntimeConfig', () => {
       };
     });
 
-    const { checkoutRuntimeConfig, resolveClaimbeeCheckoutMode } = await import('./checkout-runtime-config');
+    const { checkoutRuntimeConfig, resolveClaimbeeCheckoutMode } = await import('../../../src/runtime/checkout-runtime-config');
 
     expect(checkoutRuntimeConfig.funnelSdkPublishableKey).toBe(
       'sdk_pub_claimbee_project',
@@ -52,7 +52,7 @@ describe('checkoutRuntimeConfig', () => {
   });
 
   it('uses the server-provided runtime mode when no preview key is injected', async () => {
-    const { resolveClaimbeeCheckoutMode } = await import('./checkout-runtime-config');
+    const { resolveClaimbeeCheckoutMode } = await import('../../../src/runtime/checkout-runtime-config');
 
     expect(resolveClaimbeeCheckoutMode('live')).toBe('live');
     expect(resolveClaimbeeCheckoutMode('test')).toBe('test');

package/template_scaffold/{src → tests/src}/runtime/funnel-runtime.test.ts

@@ -4,7 +4,7 @@ import {
   defaultFunnelStepId,
   resolveConfiguredNextStep,
   resolveRuntimeInitialStepId,
-} from './funnel-runtime';
+} from '../../../src/runtime/funnel-runtime';
 
 describe('funnel runtime', () => {
   it('falls back to the first manifest step when no valid step is requested', () => {

package/template_scaffold/{src → tests/src}/runtime/step-content-context.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 import {
   getStepContentLocale,
   getStepCountryCode,
-} from './step-content-context';
+} from '../../../src/runtime/step-content-context';
 
 describe('step content context helpers', () => {
   it('prefers stored browser language and explicit country when present', () => {

package/template_scaffold/{src → tests/src}/runtime/use-funnel-flow-controller.integration.test.ts

@@ -3,7 +3,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 const { posthogFlagsPath } = vi.hoisted(() => ({
   posthogFlagsPath: new URL(
-    '../../../funnel-runtime/src/runtime/posthog-flags.ts',
+    '../../../../funnel-runtime/src/runtime/posthog-flags.ts',
     import.meta.url,
   ).pathname,
 }));
@@ -31,7 +31,7 @@ import {
   resolveExperimentVariant,
   resolveNextStepId,
 } from '@funnelsgrove/runtime';
-import { computeRenderSuspended } from './use-funnel-flow-controller';
+import { computeRenderSuspended } from '../../../src/runtime/use-funnel-flow-controller';
 
 const mockedResolveVariant = vi.mocked(resolveExperimentVariant);
 
@@ -187,9 +187,9 @@ describe.skipIf(!insideMonorepo)('PostHog variant resolution (integration)', ()
   });
 
   it('renders experiment variants on the source URL before normal continuation', () => {
-    const adapterSource = readFileSync(new URL('./use-funnel-flow-controller.ts', import.meta.url), 'utf8');
+    const adapterSource = readFileSync(new URL('../../../src/runtime/use-funnel-flow-controller.ts', import.meta.url), 'utf8');
     const runtimeSource = readFileSync(
-      new URL('../../../funnel-runtime/src/runtime/use-funnel-flow-controller.ts', import.meta.url),
+      new URL('../../../../funnel-runtime/src/runtime/use-funnel-flow-controller.ts', import.meta.url),
       'utf8',
     );
 

package/template_scaffold/{src → tests/src}/runtime/use-funnel-flow-controller.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { readFileSync } from 'node:fs';
-import { computeRenderSuspended } from './use-funnel-flow-controller';
+import { computeRenderSuspended } from '../../../src/runtime/use-funnel-flow-controller';
 
 describe('computeRenderSuspended', () => {
   const experiments = [
@@ -52,7 +52,7 @@ describe('computeRenderSuspended', () => {
 
 describe('qualified visitor analytics', () => {
   it('delegates flow behavior to the shared runtime controller with template analytics', () => {
-    const source = readFileSync(new URL('./use-funnel-flow-controller.ts', import.meta.url), 'utf8');
+    const source = readFileSync(new URL('../../../src/runtime/use-funnel-flow-controller.ts', import.meta.url), 'utf8');
 
     expect(source).toContain('useFunnelFlowController as useSharedFunnelFlowController');
     expect(source).toContain('return useSharedFunnelFlowController<FunnelStepId>({');
@@ -66,7 +66,7 @@ describe('qualified visitor analytics', () => {
   });
 
   it('does not carry a local copy of shared controller internals', () => {
-    const source = readFileSync(new URL('./use-funnel-flow-controller.ts', import.meta.url), 'utf8');
+    const source = readFileSync(new URL('../../../src/runtime/use-funnel-flow-controller.ts', import.meta.url), 'utf8');
 
     expect(source).not.toContain('FIRST_STEP_ENGAGEMENT_THRESHOLD_MS');
     expect(source).not.toContain('apiService.bootstrapSession');

package/template_scaffold/{src → tests/src}/steps/paywall-checkout-options.test.ts

@@ -3,7 +3,7 @@ import {
   buildPaywallCheckoutBillingDetails,
   buildPaywallCheckoutExpressOptions,
   buildPaywallCheckoutPaymentElementOptions,
-} from './paywall-checkout-options';
+} from '../../../src/steps/paywall-checkout-options';
 
 describe('paywall checkout options', () => {
   it('prioritizes Link and stacked express checkout buttons for the checkout dialog', () => {