@topolo/cli 0.4.6 → 0.4.9

package/dist/index.js

@@ -9,7 +9,7 @@ import { platform as platform2 } from "os";
 import { createInterface } from "readline/promises";
 import { stdin as input } from "process";
 
-// ../topolo-sdk/dist/index.js
+// node_modules/@topolo/sdk/dist/index.js
 function applyAuthHeaders(headers, credential) {
   if (credential.kind === "api_key") {
     headers.set("X-Api-Key", credential.apiKey);
@@ -3504,7 +3504,7 @@ function createTopolo(options) {
   };
 }
 
-// ../topolo-sdk/dist/node/credential-store.js
+// node_modules/@topolo/sdk/dist/node/credential-store.js
 import { mkdir, readFile, writeFile, chmod } from "fs/promises";
 import { existsSync } from "fs";
 import { homedir, platform } from "os";
@@ -5792,6 +5792,42 @@ import { dirname as dirname3, resolve as resolve2 } from "path";
 import { constants } from "fs";
 import { access } from "fs/promises";
 import { relative, resolve } from "path";
+function normalizeHomePath(value) {
+  const path4 = String(value || "/dashboard").trim();
+  if (!path4.startsWith("/") || path4.startsWith("//") || /[?#]/.test(path4)) {
+    throw new Error("Invalid home path. Use an absolute application path such as /dashboard.");
+  }
+  if (["/", "/login", "/auth/callback", "/getting-started"].includes(path4)) {
+    throw new Error("Home path must be a protected product route, not a reserved entry route.");
+  }
+  return path4.replace(/\/$/, "") || "/dashboard";
+}
+function normalizeHomeLabel(value) {
+  const label = String(value || "Dashboard").trim();
+  if (!label || label.length > 80) {
+    throw new Error("Home label must contain between 1 and 80 characters.");
+  }
+  return label;
+}
+function normalizeNavigationMode(value) {
+  const mode = String(value || "sidebar").trim();
+  if (mode === "sidebar" || mode === "topbar" || mode === "none") return mode;
+  throw new Error("Invalid navigation mode. Use sidebar, topbar, or none.");
+}
+function normalizeWorkspaceSwitcherMode(value) {
+  const mode = String(value || "required").trim();
+  if (mode === "required" || mode === "optional" || mode === "off") return mode;
+  throw new Error("Invalid workspace switcher mode. Use required, optional, or off.");
+}
+function normalizeFirstPartyAppDir(value) {
+  const requested = String(value).trim().replace(/\\/g, "/").replace(/^\.\//, "");
+  const appDir = requested.startsWith("apps/") ? requested.slice("apps/".length) : requested;
+  const segments = appDir.split("/");
+  if (!appDir || appDir.startsWith("/") || appDir.startsWith("apps/") || segments.some((segment) => !segment || segment === "." || segment === "..")) {
+    throw new Error("Invalid first-party app directory. Use a repository name such as TopoloForms or apps/TopoloForms.");
+  }
+  return appDir;
+}
 function normalizeTarget(value) {
   if (!value) return "platform";
   if (value === "platform" || value === "developer") return value;
@@ -5934,18 +5970,60 @@ var STAGING_CLOUDFLARE_ACCOUNT_ID = "4f4e1c69a3830946f9fea7b1eb7531ac";
 var DEVELOPMENT_CLOUDFLARE_ACCOUNT_ID = "0ebdeec262a245481a721fc4f9d6d798";
 var CLOUDFLARE_COMPATIBILITY_DATE = "2026-05-05";
 
+// src/commands/app-scaffold-package-policy.ts
+var TOPOLO_PACKAGE_SCAFFOLD_POLICY = {
+  "@topolo-io/api-key-management": "browser-baseline",
+  "@topolo-io/app-funnel": "browser-baseline",
+  "@topolo-io/app-launcher": "browser-baseline",
+  "@topolo-io/app-manifest": "domain-opt-in",
+  "@topolo-io/app-shell": "browser-baseline",
+  "@topolo-io/auth-client": "browser-baseline",
+  "@topolo-io/auth-middleware": "api-baseline",
+  "@topolo-io/billing-manifest": "domain-opt-in",
+  "@topolo-io/billing-ui": "domain-opt-in",
+  "@topolo-io/bridge": "domain-opt-in",
+  "@topolo-io/calendar": "domain-opt-in",
+  "@topolo-io/chat-widget": "browser-baseline",
+  "@topolo-io/data": "domain-opt-in",
+  "@topolo-io/design-tokens": "browser-baseline",
+  "@topolo-io/error-middleware": "api-baseline",
+  "@topolo-io/mailbox": "domain-opt-in",
+  "@topolo-io/mobile-error-middleware": "domain-opt-in",
+  "@topolo-io/mobile-experience-contracts": "domain-opt-in",
+  "@topolo-io/nexus-client": "api-baseline",
+  "@topolo-io/node-canvas": "domain-opt-in",
+  "@topolo-io/notifications": "browser-baseline",
+  "@topolo-io/onboarding": "browser-baseline",
+  "@topolo-io/platform-mcp": "tooling",
+  "@topolo-io/resource-context": "browser-baseline",
+  "@topolo-io/security-headers": "api-baseline",
+  "@topolo-io/tour": "browser-baseline",
+  "@topolo-io/ui-kit": "browser-baseline",
+  "@topolo-io/widget-server": "api-baseline",
+  "@topolo-io/worker-runtime": "api-baseline",
+  "@topolo/cli": "tooling",
+  "@topolo/login": "developer-baseline",
+  "@topolo/mcp": "tooling",
+  "@topolo/sdk": "api-baseline"
+};
+function packagesForScaffoldClass(scaffoldClass) {
+  return Object.entries(TOPOLO_PACKAGE_SCAFFOLD_POLICY).filter(([, value]) => value === scaffoldClass).map(([name]) => name).sort();
+}
+var PLATFORM_BROWSER_TOPOLO_PACKAGES = packagesForScaffoldClass("browser-baseline");
+var PLATFORM_API_TOPOLO_PACKAGES = packagesForScaffoldClass("api-baseline");
+
 // src/commands/app-scaffold-package-template.ts
 function packageJson(application, target, options) {
   const dependencies = {};
   const devDependencies = {
     "@types/node": "^20.12.0",
     typescript: "^5.4.0",
-    vite: "^5.4.0"
+    ...options.browser ? { vite: "^5.4.0" } : {}
   };
   const scripts = {
-    dev: target === "platform" ? "vite --config apps/web/vite.config.ts --host 0.0.0.0" : "vite --host 0.0.0.0",
-    build: target === "platform" ? "vite build --config apps/web/vite.config.ts" : "vite build",
-    preview: target === "platform" ? "vite preview --config apps/web/vite.config.ts --host 0.0.0.0" : "vite preview --host 0.0.0.0",
+    dev: target === "platform" ? options.browser ? "vite --config apps/web/vite.config.ts --host 0.0.0.0" : "wrangler dev --config apps/api/wrangler.toml" : "vite --host 0.0.0.0",
+    build: target === "platform" ? options.browser ? "vite build --config apps/web/vite.config.ts" : 'wrangler deploy --config apps/api/wrangler.toml --env="" --dry-run --outdir dist' : "vite build",
+    preview: target === "platform" ? options.browser ? "vite preview --config apps/web/vite.config.ts --host 0.0.0.0" : "wrangler dev --config apps/api/wrangler.toml" : "vite preview --host 0.0.0.0",
     typecheck: "tsc --noEmit"
   };
   if (options.browser) {
@@ -5955,29 +6033,20 @@ function packageJson(application, target, options) {
     devDependencies["@types/react-dom"] = "^19.2.2";
     devDependencies["@vitejs/plugin-react"] = "^4.7.0";
     if (target === "platform") {
-      dependencies["@topolo-io/auth-client"] = topoloPackageVersion("@topolo-io/auth-client", target);
-      dependencies["@topolo-io/app-funnel"] = topoloPackageVersion("@topolo-io/app-funnel", target);
-      dependencies["@topolo-io/app-launcher"] = topoloPackageVersion("@topolo-io/app-launcher", target);
-      dependencies["@topolo-io/app-shell"] = topoloPackageVersion("@topolo-io/app-shell", target);
-      dependencies["@topolo-io/design-tokens"] = topoloPackageVersion("@topolo-io/design-tokens", target);
-      dependencies["@topolo-io/onboarding"] = topoloPackageVersion("@topolo-io/onboarding", target);
-      dependencies["@topolo-io/tour"] = topoloPackageVersion("@topolo-io/tour", target);
-      dependencies["@topolo-io/ui-kit"] = topoloPackageVersion("@topolo-io/ui-kit", target);
+      for (const packageName of PLATFORM_BROWSER_TOPOLO_PACKAGES) {
+        dependencies[packageName] = topoloPackageVersion(packageName, target);
+      }
       dependencies["react-router-dom"] = "^7.6.2";
     } else {
       dependencies["@topolo/login"] = topoloPackageVersion("@topolo/login", target);
     }
   }
   if (options.api) {
-    devDependencies["@cloudflare/workers-types"] = "^4.20260413.1";
+    devDependencies["@cloudflare/workers-types"] = "^5.20260716.1";
     if (target === "platform") {
-      dependencies["@topolo-io/worker-runtime"] = topoloPackageVersion("@topolo-io/worker-runtime", target);
-      dependencies["@topolo-io/auth-middleware"] = topoloPackageVersion("@topolo-io/auth-middleware", target);
-      dependencies["@topolo-io/error-middleware"] = topoloPackageVersion("@topolo-io/error-middleware", target);
-      dependencies["@topolo-io/security-headers"] = topoloPackageVersion("@topolo-io/security-headers", target);
-      dependencies["@topolo-io/resource-context"] = topoloPackageVersion("@topolo-io/resource-context", target);
-      dependencies["@topolo-io/data"] = topoloPackageVersion("@topolo-io/data", target);
-      dependencies["@topolo/sdk"] = topoloPackageVersion("@topolo/sdk", target);
+      for (const packageName of PLATFORM_API_TOPOLO_PACKAGES) {
+        dependencies[packageName] = topoloPackageVersion(packageName, target);
+      }
       dependencies.hono = "^4";
       dependencies.zod = "^4.4.3";
       scripts.deploy = `node -e 'console.error("\\nX Bare deploy is disabled. Use deploy:staging or deploy:production.\\n"); process.exit(1)'`;
@@ -5996,7 +6065,7 @@ function packageJson(application, target, options) {
     if (testDirs.length > 0) {
       const chain = (withCoverage) => testDirs.map((dir, index) => {
         const enter = index === 0 ? `cd ${dir}` : `cd ../${dir.split("/").pop()}`;
-        return `${enter} && vitest run --config vitest.config.ts --passWithNoTests${withCoverage ? " --coverage" : ""}`;
+        return `${enter} && vitest run --config vitest.config.ts${withCoverage ? " --coverage" : ""}`;
       }).join(" && ");
       scripts.test = chain(false);
       scripts.coverage = chain(true);
@@ -6011,7 +6080,11 @@ function packageJson(application, target, options) {
     }
   }
   if (target === "platform" && hasScaffoldResources(options.resources)) {
-    scripts["check:deploy-config"] = "wrangler deploy --config apps/api/wrangler.toml --env staging --dry-run --outdir .wrangler/api-build && wrangler deploy --config apps/web/wrangler.toml --env staging --dry-run --outdir .wrangler/web-build";
+    const deployChecks = [
+      ...options.api ? ["wrangler deploy --config apps/api/wrangler.toml --env staging --dry-run --outdir .wrangler/api-build"] : [],
+      ...options.browser ? ["wrangler deploy --config apps/web/wrangler.toml --env staging --dry-run --outdir .wrangler/web-build"] : []
+    ];
+    scripts["check:deploy-config"] = deployChecks.join(" && ");
   }
   return `${json({
     name: application.packageName,
@@ -6032,29 +6105,8 @@ function topoloPackageVersion(packageName, target) {
     if (packageName === "@topolo/sdk") return "^0.8.1";
     return "^0.1.0";
   }
-  const platformPackageVersions = {
-    "@topolo/sdk": "^0.8.1",
-    "@topolo/login": "^0.1.0",
-    "@topolo-io/app-funnel": "^0.1.6",
-    "@topolo-io/app-launcher": "^0.1.15",
-    "@topolo-io/app-shell": "^0.8.4",
-    "@topolo-io/auth-client": "^1.2.1",
-    "@topolo-io/auth-middleware": "^0.4.0",
-    "@topolo-io/error-middleware": "^0.6.0",
-    "@topolo-io/security-headers": "^0.2.2",
-    "@topolo-io/resource-context": "^0.3.0",
-    "@topolo-io/data": "^0.1.2",
-    "@topolo-io/worker-runtime": "^0.1.11",
-    "@topolo-io/design-tokens": "^0.1.8",
-    "@topolo-io/onboarding": "^0.9.5",
-    "@topolo-io/tour": "^0.3.4",
-    "@topolo-io/ui-kit": "^0.4.233"
-  };
-  const version = platformPackageVersions[packageName];
-  if (!version) {
-    throw new Error(`Unknown Topolo platform package: ${packageName}`);
-  }
-  return version;
+  if (packageName.startsWith("@topolo/") || packageName.startsWith("@topolo-io/")) return "latest";
+  throw new Error(`Unknown Topolo platform package: ${packageName}`);
 }
 function hasScaffoldResources(resources) {
   return resources.d1 || resources.r2 || resources.queue || resources.workflow || resources.containerProcessing;
@@ -6129,10 +6181,11 @@ function readme(application, target, options) {
     "## Development",
     "",
     "```bash",
-    "npm install",
-    "npm run typecheck",
-    "npm run build",
-    "npm run dev",
+    target === "platform" ? "pnpm install" : "npm install",
+    target === "platform" ? "pnpm run typecheck" : "npm run typecheck",
+    target === "platform" ? "pnpm run coverage" : "npm run build",
+    target === "platform" ? "pnpm run build" : "npm run dev",
+    ...target === "platform" ? ["pnpm run dev"] : [],
     "```",
     ""
   ];
@@ -6145,11 +6198,15 @@ function readme(application, target, options) {
       "- `@topolo-io/app-launcher` provides shared app switching and handoff helpers.",
       "- `@topolo-io/ui-kit` provides primitive account, command palette, icon, transition, and bug reporter UI.",
       "- `@topolo-io/auth-client` owns browser auth, callback exchange, token refresh, and logout.",
-      "- Generated first-party browser apps start on the shared landing page at `/`, use the shared login page at `/login`, and complete sign-in on `/auth/callback` before entering the workspace shell.",
+      "- `@topolo-io/api-key-management`, `@topolo-io/chat-widget`, `@topolo-io/notifications`, and `@topolo-io/resource-context` complete the AppShell capability baseline.",
+      "- Every Topolo-owned browser dependency is emitted at `latest`; product-domain packages are added only when the app actually adopts that domain.",
+      "- `.npmrc` routes private `@topolo-io` packages to GitHub Packages without storing credentials; public `@topolo` packages remain on npm. Local and CI environments must provide a GitHub Packages token.",
+      "- Generated first-party browser apps start on the shared landing page at `/`, use the shared login page at `/login`, and complete sign-in on `/auth/callback` before entering the configured authenticated home.",
+      "- The workspace selector renders in the top utility bar; Getting Started is an account-menu action and is not part of the left product rail.",
       "- `vite.config.ts` includes the standard React plugin plus React runtime dedupe so linked Topolo packages resolve one browser React runtime."
     );
     if (options.api) {
-      lines.push("- `@topolo-io/worker-runtime` owns Worker auth validation, `/api/auth/*` gatewaying, security headers, request ids, Nexus API-call usage monitoring, and BugFix reporting.");
+      lines.push("- `@topolo-io/worker-runtime` plus its auth, error, Nexus, security-header, and widget-server suite own Worker validation, request ids, usage monitoring, widget responses, and BugFix reporting.");
     }
     if (hasScaffoldResources(options.resources)) {
       lines.push(
@@ -6352,6 +6409,15 @@ function gitignore() {
     ""
   ].join("\n");
 }
+function npmrc() {
+  return [
+    "@topolo-io:registry=https://npm.pkg.github.com",
+    "strict-peer-dependencies=true",
+    "minimum-release-age-exclude[]=@topolo-io/*",
+    "minimum-release-age-exclude[]=@topolo/*",
+    ""
+  ].join("\n");
+}
 function envDts(api) {
   const lines = [
     '/// <reference types="vite/client" />',
@@ -6612,46 +6678,6 @@ function stylesCss() {
     "textarea {",
     "  font: inherit;",
     "}",
-    "",
-    ".topolo-starter-workspace {",
-    "  display: grid;",
-    "  gap: 18px;",
-    "  min-width: 0;",
-    "  width: auto;",
-    "  max-width: min(100%, calc(100vw - 56px));",
-    "  overflow-x: clip;",
-    "}",
-    "",
-    ".topolo-starter-card-stack {",
-    "  display: grid;",
-    "  gap: 18px;",
-    "  min-width: 0;",
-    "}",
-    "",
-    ".topolo-starter-workspace > *,",
-    ".topolo-starter-card-stack > * {",
-    "  min-width: 0;",
-    "}",
-    "",
-    ".topolo-starter-card h2 {",
-    "  margin: 0 0 12px;",
-    "  font-size: 24px;",
-    "  line-height: 1.2;",
-    "}",
-    "",
-    ".topolo-starter-card p {",
-    "  margin: 0;",
-    "  color: hsl(var(--muted-foreground));",
-    "  line-height: 1.55;",
-    "}",
-    "",
-    ".topolo-starter-card {",
-    "  border: 1px solid hsl(var(--border));",
-    "  border-radius: var(--radius);",
-    "  padding: 20px;",
-    "  background: hsl(var(--card));",
-    "  color: hsl(var(--card-foreground));",
-    "}",
     ""
   ].join("\n");
 }
@@ -6659,450 +6685,429 @@ function stylesCss() {
 // src/commands/app-scaffold-app-template.ts
 function appTsx(application, target, options) {
   if (target === "developer") return developerAppTsx(application);
-  return platformAppTsx(application, options);
-}
-function platformAppTsx(application, options) {
-  const isPersonal = options.audience === "personal";
-  const tagline = isPersonal ? "Topolo personal app" : "Topolo workspace";
-  const workspaceTitle = isPersonal ? "Personal app" : "Workspace";
-  const shellLabel = isPersonal ? "personal app shell" : "workspace shell";
-  const baselineHeading = isPersonal ? "Shared personal baseline" : "Shared workspace baseline";
-  const baselineDescription = isPersonal ? "This scaffold starts on the shared landing and login surfaces, completes sign-in on the shared callback path, and renders the signed personal app inside the shared Topolo shell." : "This scaffold starts on the shared landing and login surfaces, completes sign-in on the shared callback path, and renders the signed workspace inside the shared Topolo shell.";
+  return platformAppTsx();
+}
+function platformAppTsx() {
+  return `import { useEffect, useMemo, useState } from 'react';
+import { LandingPage } from '@topolo-io/app-funnel';
+import { LoginPage, TopoloAppLoadingScaffold, TopoloAppRoot, TopoloAuthFlowScreen, createTopoloAuth } from '@topolo-io/app-shell';
+import { setupBugReporterErrorCapture } from '@topolo-io/ui-kit';
+import AppErrorBoundary from './AppErrorBoundary';
+import { APP_NAME, AUTH_URL, HOME_PATH, LANDING_CONFIG, LOGIN_CONFIG, NAVIGATION_MODE, WORKSPACE_RESOURCE } from './app-config';
+import { createAppRoutes } from './app-routes';
+import { resolveAppId } from './app-identity';
+
+setupBugReporterErrorCapture();
+
+export default function App() {
+  return (
+    <AppErrorBoundary>
+      <CanonicalAppRoot />
+    </AppErrorBoundary>
+  );
+}
+
+export function CanonicalAppRoot() {
+  const [appId, setAppId] = useState('');
+  const [appIdentityError, setAppIdentityError] = useState('');
+
+  useEffect(() => {
+    let active = true;
+    setAppIdentityError('');
+    void resolveAppId()
+      .then((nextAppId) => {
+        if (active) setAppId(nextAppId);
+      })
+      .catch((error) => {
+        if (active) setAppIdentityError(errorMessage(error));
+      });
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  const auth = useMemo(() => appId ? createTopoloAuth({
+    authServiceUrl: AUTH_URL,
+    appId,
+    devSessionKey: \`\${appId}_session\`,
+    callbackPath: '/auth/callback',
+    sessionStorageRestoreEnabled: import.meta.env.DEV,
+    debug: import.meta.env.DEV,
+  }) : null, [appId]);
+  const routes = useMemo(() => appId ? createAppRoutes(appId) : [], [appId]);
+
+  if (appIdentityError) {
+    return (
+      <TopoloAuthFlowScreen
+        appName={APP_NAME}
+        status="error"
+        title="App identity unavailable"
+        message={appIdentityError}
+        actionLabel="Retry"
+        onAction={() => window.location.reload()}
+      />
+    );
+  }
+
+  if (!auth) {
+    return (
+      <TopoloAppLoadingScaffold
+        appId={appId}
+        appName={APP_NAME}
+        layout={{ shell: NAVIGATION_MODE, content: 'workspace' }}
+      />
+    );
+  }
+
+  return (
+    <TopoloAppRoot
+      appName={APP_NAME}
+      appId={appId}
+      auth={auth}
+      routes={routes}
+      home={HOME_PATH}
+      workspaceResource={WORKSPACE_RESOURCE}
+      gettingStarted={{ path: '/getting-started' }}
+      publicLanding={
+        <LandingPage
+          appId={appId}
+          authApiUrl={AUTH_URL}
+          config={LANDING_CONFIG}
+          onCTAClick={() => window.location.assign('/login')}
+        />
+      }
+      loginElement={
+        <LoginPage
+          appId={appId}
+          authApiUrl={AUTH_URL}
+          config={LOGIN_CONFIG}
+          onLogin={async (provider) => {
+            await auth.login(provider || 'topolo');
+          }}
+          onPasswordLogin={async (request) => {
+            const result = await auth.loginWithPassword(request);
+            if (!result.authenticated) return result;
+            window.dispatchEvent(new CustomEvent('auth:session-updated', { detail: { tokens: result.tokens, user: result.user } }));
+            return undefined;
+          }}
+        />
+      }
+      loadingFallback={({ loading }) => (
+        <TopoloAppLoadingScaffold
+          appId={appId}
+          appName={APP_NAME}
+          layout={{ shell: loading?.shell || NAVIGATION_MODE, content: loading?.content || 'workspace' }}
+        />
+      )}
+      shell={{
+        appId,
+        authUrl: AUTH_URL,
+        navigationMode: NAVIGATION_MODE,
+        title: APP_NAME,
+        commandPlaceholder: \`Search \${APP_NAME}\`,
+        bugReporterAppName: APP_NAME,
+        enableCommandPalette: true,
+        enableBugReporter: true,
+      }}
+    />
+  );
+}
+
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error && error.message) return error.message;
+  return 'Unexpected authentication error.';
+}
+`;
+}
+function platformAppConfigTs(application, experience) {
+  const appName = toTitle(application.name);
+  const workspaceResource = experience.workspaceSwitcher === "off" ? "{ enabled: false }" : `{ enabled: true, required: ${experience.workspaceSwitcher === "required"}, label: '${escapeSingleQuoted(experience.workspaceLabel)}' }`;
+  return `import { SCAFFOLD_APP_NAME, getBrowserAuthBaseUrl } from './app-identity';
+
+export const APP_NAME = SCAFFOLD_APP_NAME;
+export const AUTH_URL = getBrowserAuthBaseUrl();
+export const HOME_PATH = '${escapeSingleQuoted(experience.homePath)}';
+export const HOME_LABEL = '${escapeSingleQuoted(experience.homeLabel)}';
+export const NAVIGATION_MODE = '${experience.navigationMode}' as const;
+export const WORKSPACE_RESOURCE = ${workspaceResource} as const;
+export const PRODUCT_TAGLINE = '${escapeSingleQuoted(experience.tagline)}';
+
+export const LANDING_CONFIG = {
+  app_name: APP_NAME,
+  app_tagline: PRODUCT_TAGLINE,
+  hero_title: APP_NAME,
+  hero_subtitle: PRODUCT_TAGLINE,
+  hero_cta_text: 'Sign in',
+  hero_cta_url: '/login',
+  cta_title: 'Ready to continue?',
+  cta_subtitle: 'Sign in with your Topolo account.',
+};
+
+export const LOGIN_CONFIG = {
+  app_name: APP_NAME,
+  app_tagline: PRODUCT_TAGLINE,
+  hero_title: \`Sign in to \${APP_NAME}\`,
+  hero_subtitle: PRODUCT_TAGLINE,
+  authenticated_home_path: HOME_PATH,
+};
+
+export const APP_DISPLAY_NAME = '${escapeSingleQuoted(appName)}';
+`;
+}
+function platformAppRoutesTsx(experience) {
+  const nav = experience.navigationMode === "none" ? "" : "      nav: { id: 'home', label: HOME_LABEL },\n";
+  return `import type { AppRoute } from '@topolo-io/app-shell';
+import { HOME_LABEL, HOME_PATH, NAVIGATION_MODE } from './app-config';
+import GettingStartedRoute from './routes/GettingStartedRoute';
+import HomeRoute from './routes/HomeRoute';
+
+export function createAppRoutes(appId: string): AppRoute[] {
   return [
-    "import { Component, useCallback, useEffect, useMemo, useState, type ErrorInfo, type ReactNode } from 'react';",
-    "import { LandingPage } from '@topolo-io/app-funnel';",
-    "import { LoginPage, TopoloAppLoadingScaffold, TopoloAppRoot, TopoloAuthFlowScreen, createTopoloAuth, useAuth, type AppRoute as TopoloAppRoute } from '@topolo-io/app-shell';",
-    "import { setupBugReporterErrorCapture } from '@topolo-io/ui-kit';",
-    "import { GettingStarted, type OnboardingGuideStep } from '@topolo-io/onboarding';",
-    "import { IntroTour } from '@topolo-io/tour';",
-    "import { SCAFFOLD_APP_NAME, getBrowserAuthBaseUrl, resolveAppId } from './app-identity';",
-    "",
-    "// Wire global error/console capture so BugReporter (enabled in TopoloAppShell below)",
-    "// can attach the last few errors to any submitted bug report.",
-    "setupBugReporterErrorCapture();",
-    "",
-    "const APP_NAME = SCAFFOLD_APP_NAME;",
-    "const AUTH_URL = getBrowserAuthBaseUrl();",
-    "const LANDING_CONFIG = {",
-    "  app_name: APP_NAME,",
-    `  app_tagline: '${escapeSingleQuoted(tagline)}',`,
-    "  hero_title: `Open ${APP_NAME} in Topolo`,",
-    `  hero_subtitle: 'Shared landing, login, callback, auth, and ${escapeSingleQuoted(shellLabel)} wiring are already included in the generated baseline.',`,
-    "  hero_cta_text: 'Sign in',",
-    "  hero_cta_url: '/login',",
-    "  cta_title: 'Start from the shared platform entry flow',",
-    `  cta_subtitle: 'Unauthenticated routes stay on the shared Topolo surfaces before users enter the signed ${escapeSingleQuoted(shellLabel)}.',`,
-    "};",
-    "const LOGIN_CONFIG = {",
-    "  app_name: APP_NAME,",
-    `  app_tagline: '${escapeSingleQuoted(tagline)}',`,
-    "  hero_title: `Sign in to ${APP_NAME}`,",
-    `  hero_subtitle: 'Use Topolo Auth to open the shared ${escapeSingleQuoted(shellLabel)} for this application.',`,
-    "  authenticated_home_path: '/dashboard',",
-    "};",
-    "",
-    "export default function App() {",
-    "  return (",
-    "    <AppErrorBoundary>",
-    "      <CanonicalAppRoot />",
-    "    </AppErrorBoundary>",
-    "  );",
-    "}",
-    "",
-    "function CanonicalAppRoot() {",
-    "  const [appId, setAppId] = useState('');",
-    "  const [appIdentityError, setAppIdentityError] = useState('');",
-    "",
-    "  useEffect(() => {",
-    "    let active = true;",
-    "    setAppIdentityError('');",
-    "    void resolveAppId()",
-    "      .then((nextAppId) => {",
-    "        if (active) setAppId(nextAppId);",
-    "      })",
-    "      .catch((error) => {",
-    "        if (!active) return;",
-    "        setAppIdentityError(errorMessage(error));",
-    "      });",
-    "    return () => {",
-    "      active = false;",
-    "    };",
-    "  }, []);",
-    "",
-    "  const auth = useMemo(() => appId ? createTopoloAuth({",
-    "    authServiceUrl: AUTH_URL,",
-    "    appId,",
-    "    devSessionKey: `${appId}_session`,",
-    "    callbackPath: '/auth/callback',",
-    "    sessionStorageRestoreEnabled: import.meta.env.DEV,",
-    "    debug: import.meta.env.DEV,",
-    "  }) : null, [appId]);",
-    "",
-    "  const routes = useMemo<TopoloAppRoute[]>(() => appId ? [",
-    "    {",
-    "      path: '/workspace',",
-    "      nav: { id: 'home', label: '" + escapeSingleQuoted(workspaceTitle) + "' },",
-    "      loading: { shell: 'topbar', content: 'workspace', title: '" + escapeSingleQuoted(workspaceTitle) + "' },",
-    "      element: <ScaffoldWorkspace />,",
-    "    },",
-    "    {",
-    "      path: '/getting-started',",
-    "      nav: { id: 'getting-started', label: 'Getting started' },",
-    "      loading: { shell: 'topbar', content: 'card-grid', title: 'Getting started' },",
-    "      element: <ScaffoldGettingStartedRoute appId={appId} />,",
-    "    },",
-    "  ] : [], [appId]);",
-    "",
-    "  if (appIdentityError) {",
-    "    return (",
-    "      <TopoloAuthFlowScreen",
-    "        appName={APP_NAME}",
-    "        appId={appId}",
-    '        status="error"',
-    '        title="App identity unavailable"',
-    "        message={appIdentityError}",
-    '        actionLabel="Retry"',
-    "        onAction={() => window.location.reload()}",
-    "      />",
-    "    );",
-    "  }",
-    "",
-    "  if (!auth) {",
-    "    // Pre-AppRoot: appId is still resolving, so auth can't be built yet.",
-    "    // Render the SAME scaffold layout AppRoot uses below so this phase and",
-    "    // the auth-gate fallback read as one continuous loading state (the",
-    "    // scaffold resolves theme + rail width on its own to match the shell).",
-    "    return (",
-    "      <TopoloAppLoadingScaffold",
-    "        appId={appId}",
-    "        appName={APP_NAME}",
-    "        layout={{ shell: 'topbar', content: 'workspace' }}",
-    "      />",
-    "    );",
-    "  }",
-    "",
-    "  return (",
-    "    <TopoloAppRoot",
-    "      appName={APP_NAME}",
-    "      appId={appId}",
-    "      auth={auth}",
-    "      routes={routes}",
-    '      home="/workspace"',
-    "      publicLanding={",
-    "        <LandingPage",
-    "          appId={appId}",
-    "          authApiUrl={AUTH_URL}",
-    "          config={LANDING_CONFIG}",
-    "          onCTAClick={() => window.location.assign('/login')}",
-    "        />",
-    "      }",
-    "      loginElement={",
-    "        <LoginPage",
-    "          appId={appId}",
-    "          authApiUrl={AUTH_URL}",
-    "          config={LOGIN_CONFIG}",
-    "          onLogin={async (provider) => {",
-    "            await auth.login(provider || 'topolo');",
-    "          }}",
-    "          onPasswordLogin={async (request) => {",
-    "            const result = await auth.loginWithPassword(request);",
-    "            if (!result.authenticated) return result;",
-    "            window.dispatchEvent(new CustomEvent('auth:session-updated', { detail: { tokens: result.tokens, user: result.user } }));",
-    "            return undefined;",
-    "          }}",
-    "        />",
-    "      }",
-    "      loadingFallback={({ loading }) => (",
-    "        <TopoloAppLoadingScaffold",
-    "          appId={appId}",
-    "          appName={APP_NAME}",
-    "          layout={{ shell: loading?.shell || 'topbar', content: loading?.content || 'workspace' }}",
-    "        />",
-    "      )}",
-    "      shell={{",
-    "        appId: appId,",
-    "        authUrl: AUTH_URL,",
-    "        navigationMode: 'topbar',",
-    "        title: APP_NAME,",
-    "        commandPlaceholder: `Search ${APP_NAME}`,",
-    "        bugReporterAppName: APP_NAME,",
-    "        enableCommandPalette: true,",
-    "        enableBugReporter: true,",
-    "      }}",
-    "    />",
-    "  );",
-    "}",
-    "",
-    "function ScaffoldWorkspace() {",
-    "  const { user } = useAuth();",
-    "  const openWorkspace = useCallback(() => {",
-    "    window.history.pushState({}, '', '/workspace');",
-    "    window.dispatchEvent(new PopStateEvent('popstate'));",
-    "  }, []);",
-    "  const openGettingStarted = useCallback(() => {",
-    "    window.history.pushState({}, '', '/getting-started');",
-    "    window.dispatchEvent(new PopStateEvent('popstate'));",
-    "  }, []);",
-    "  return (",
-    '    <div className="topolo-starter-workspace">',
-    '      <section className="topolo-starter-card" data-tour="workspace-card">',
-    `        <h2>${baselineHeading}</h2>`,
-    "        <p>",
-    `          ${baselineDescription}`,
-    "        </p>",
-    "      </section>",
-    "      <IntroTour",
-    "        appName={APP_NAME}",
-    "        role={user?.role}",
-    "        onOpenGettingStarted={openGettingStarted}",
-    "        extraSteps={[",
-    "          {",
-    "            id: 'workspace-card',",
-    `            target: '[data-tour="workspace-card"]',`,
-    "            title: 'Your workspace',",
-    "            content: 'Everything you build renders here, inside the shared Topolo shell.',",
-    "            placement: 'bottom' as const,",
-    "            beforeStep: () => openWorkspace(),",
-    "          },",
-    "        ]}",
-    "      />",
-    "    </div>",
-    "  );",
-    "}",
-    "",
-    "function ScaffoldGettingStartedRoute({ appId }: { appId: string }) {",
-    "  const { user, tokens } = useAuth();",
-    "  return (",
-    "    <ScaffoldGettingStarted",
-    "      appId={appId}",
-    "      organizationId={String((user as any)?.organization?.id ?? user?.orgId ?? '')}",
-    "      role={user?.role}",
-    "      getAccessToken={() => tokens?.accessToken ?? null}",
-    "      onOpenWorkspace={() => window.location.assign('/workspace')}",
-    "    />",
-    "  );",
-    "}",
-    "",
-    "function ScaffoldGettingStarted(props: {",
-    "  appId: string;",
-    "  organizationId: string;",
-    "  role?: string;",
-    "  getAccessToken: () => string | null;",
-    "  onOpenWorkspace: () => void;",
-    "}) {",
-    "  const { appId, organizationId, role, getAccessToken, onOpenWorkspace } = props;",
-    "  const steps: OnboardingGuideStep[] = [",
-    "    {",
-    "      id: 'explore-workspace',",
-    "      title: 'Explore your workspace',",
-    "      description:",
-    "        'Your workspace lives in the Topolo shell \u2014 the launcher, command palette, and account menu are all one click away.',",
-    "      actionLabel: 'Open workspace',",
-    "      onAction: onOpenWorkspace,",
-    "    },",
-    "    {",
-    "      id: 'discover-platform',",
-    "      title: 'Move between your Topolo apps',",
-    "      description:",
-    "        'Use the launcher to switch between your Topolo apps, and the command palette (Cmd/Ctrl-K) to jump anywhere fast.',",
-    "      optional: true,",
-    "    },",
-    "    {",
-    "      id: 'build-feature',",
-    "      title: 'Make it your own',",
-    "      description:",
-    "        'Open the account menu to adjust your settings and theme \u2014 your preferences stay in sync across every Topolo app.',",
-    "    },",
-    "  ];",
-    "  return (",
-    '    <div className="topolo-starter-workspace">',
-    "      <GettingStarted",
-    "        authApiBaseUrl={`${AUTH_URL}/api`}",
-    "        organizationId={organizationId}",
-    "        appId={appId}",
-    "        getAccessToken={getAccessToken}",
-    "        role={role || undefined}",
-    "        steps={steps}",
-    "        eyebrow={`Welcome to ${APP_NAME}`}",
-    "        title={`Get started with ${APP_NAME}`}",
-    '        subtitle="A short checklist to orient you in your new Topolo workspace."',
-    '        completeLabel="Mark done"',
-    '        dismissLabel="Skip for now"',
-    "        completedContent={`You're all set \u2014 ${APP_NAME} is ready to build on.`}",
-    "        completeAction={{ label: 'Go to workspace', onClick: onOpenWorkspace }}",
-    "        onDismiss={onOpenWorkspace}",
-    "      />",
-    "    </div>",
-    "  );",
-    "}",
-    "",
-    "function errorMessage(error: unknown): string {",
-    "  if (error instanceof Error && error.message) return error.message;",
-    "  return 'Unexpected authentication error.';",
-    "}",
-    "",
-    "// Minimal error boundary so a render-time crash falls back to a recoverable surface",
-    "// instead of a blank page. The shared TopoloAppShell BugReporter still has access to",
-    "// the captured stack via setupBugReporterErrorCapture().",
-    "class AppErrorBoundary extends Component<{ children: ReactNode }, { error: Error | null }> {",
-    "  state = { error: null as Error | null };",
-    "  static getDerivedStateFromError(error: Error) {",
-    "    return { error };",
-    "  }",
-    "  componentDidCatch(error: Error, info: ErrorInfo) {",
-    "    // Surface to the platform error pipeline. setupBugReporterErrorCapture() also",
-    "    // records this via the console.error hook for BugReporter attachments.",
-    "    console.error('[' + APP_NAME + '] render error:', error, info.componentStack);",
-    "  }",
-    "  render() {",
-    "    if (!this.state.error) return this.props.children;",
-    "    return (",
-    "      <TopoloAuthFlowScreen",
-    "        appName={APP_NAME}",
-    '        status="error"',
-    "        title={APP_NAME + ' hit an unexpected error'}",
-    "        message={this.state.error.message}",
-    '        actionLabel="Reload"',
-    "        onAction={() => window.location.reload()}",
-    "      />",
-    "    );",
-    "  }",
-    "}",
-    ""
-  ].join("\n");
+    {
+      path: HOME_PATH,
+${nav}      loading: { shell: NAVIGATION_MODE, content: 'workspace', title: HOME_LABEL },
+      element: <HomeRoute />,
+    },
+    {
+      path: '/getting-started',
+      loading: { shell: NAVIGATION_MODE, content: 'card-grid', title: 'Getting started' },
+      element: <GettingStartedRoute appId={appId} />,
+    },
+  ];
+}
+`;
+}
+function platformHomeRouteTsx() {
+  return `import { TopoloAppPage, TopoloAppPageHeader, useAuth } from '@topolo-io/app-shell';
+import { IntroTour } from '@topolo-io/tour';
+import { useTranslation } from '@topolo-io/ui-kit';
+import { useNavigate } from 'react-router-dom';
+import { APP_NAME, HOME_LABEL, HOME_PATH, PRODUCT_TAGLINE } from '../app-config';
+
+export default function HomeRoute() {
+  const { user } = useAuth();
+  const { t } = useTranslation();
+  const navigate = useNavigate();
+  return (
+    <TopoloAppPage data-tour="home-page">
+      <TopoloAppPageHeader
+        eyebrow={APP_NAME}
+        title={t('app.home.title', { defaultValue: HOME_LABEL })}
+        description={t('app.home.description', { defaultValue: PRODUCT_TAGLINE })}
+      />
+      <IntroTour
+        appName={APP_NAME}
+        role={user?.role}
+        onOpenGettingStarted={() => navigate('/getting-started')}
+        extraSteps={[{
+          id: 'home-page',
+          target: '[data-tour="home-page"]',
+          title: HOME_LABEL,
+          content: PRODUCT_TAGLINE,
+          placement: 'bottom' as const,
+          beforeStep: () => navigate(HOME_PATH),
+        }]}
+      />
+    </TopoloAppPage>
+  );
+}
+`;
+}
+function platformGettingStartedRouteTsx() {
+  return `import { TopoloAppPage, useAuth } from '@topolo-io/app-shell';
+import { GettingStarted, type OnboardingGuideStep } from '@topolo-io/onboarding';
+import { useTranslation } from '@topolo-io/ui-kit';
+import { useNavigate } from 'react-router-dom';
+import { APP_NAME, AUTH_URL, HOME_LABEL, HOME_PATH } from '../app-config';
+
+export default function GettingStartedRoute({ appId }: { appId: string }) {
+  const { user, tokens } = useAuth();
+  const { t } = useTranslation();
+  const navigate = useNavigate();
+  const openHome = () => navigate(HOME_PATH);
+  const steps: OnboardingGuideStep[] = [
+    {
+      id: 'explore-home',
+      title: t('app.gettingStarted.explore.title', { defaultValue: \`Explore \${HOME_LABEL.toLowerCase()}\` }),
+      description: t('app.gettingStarted.explore.description', { defaultValue: 'Start with the main product surface and the actions available to you.' }),
+      actionLabel: t('app.gettingStarted.explore.action', { defaultValue: \`Open \${HOME_LABEL.toLowerCase()}\` }),
+      onAction: openHome,
+    },
+    {
+      id: 'discover-platform',
+      title: t('app.gettingStarted.platform.title', { defaultValue: 'Move between Topolo apps' }),
+      description: t('app.gettingStarted.platform.description', { defaultValue: 'Use the app launcher and command palette to move through your work.' }),
+      optional: true,
+    },
+    {
+      id: 'personalize',
+      title: t('app.gettingStarted.personalize.title', { defaultValue: 'Set your preferences' }),
+      description: t('app.gettingStarted.personalize.description', { defaultValue: 'Open the account menu to manage your settings and theme.' }),
+    },
+  ];
+  return (
+    <TopoloAppPage>
+      <GettingStarted
+        authApiBaseUrl={\`\${AUTH_URL}/api\`}
+        organizationId={String((user as { organization?: { id?: string } } | null)?.organization?.id ?? user?.orgId ?? '')}
+        appId={appId}
+        getAccessToken={() => tokens?.accessToken ?? null}
+        role={user?.role}
+        steps={steps}
+        eyebrow={t('app.gettingStarted.eyebrow', { defaultValue: \`Welcome to \${APP_NAME}\` })}
+        title={t('app.gettingStarted.title', { defaultValue: \`Get started with \${APP_NAME}\` })}
+        subtitle={t('app.gettingStarted.subtitle', { defaultValue: 'A short checklist to help you find your way around.' })}
+        completeLabel={t('app.gettingStarted.complete', { defaultValue: 'Mark done' })}
+        dismissLabel={t('app.gettingStarted.dismiss', { defaultValue: 'Skip for now' })}
+        completedContent={t('app.gettingStarted.completed', { defaultValue: \`You're all set \u2014 \${APP_NAME} is ready.\` })}
+        completeAction={{ label: t('app.gettingStarted.openHome', { defaultValue: \`Go to \${HOME_LABEL.toLowerCase()}\` }), onClick: openHome }}
+        onDismiss={openHome}
+      />
+    </TopoloAppPage>
+  );
+}
+`;
+}
+function platformAppErrorBoundaryTsx() {
+  return `import { Component, type ErrorInfo, type ReactNode } from 'react';
+import { TopoloAuthFlowScreen } from '@topolo-io/app-shell';
+import { APP_NAME } from './app-config';
+
+export default class AppErrorBoundary extends Component<{ children: ReactNode }, { error: Error | null }> {
+  state = { error: null as Error | null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    console.error('[' + APP_NAME + '] render error:', error, info.componentStack);
+  }
+
+  render() {
+    if (!this.state.error) return this.props.children;
+    return (
+      <TopoloAuthFlowScreen
+        appName={APP_NAME}
+        status="error"
+        title={APP_NAME + ' hit an unexpected error'}
+        message={this.state.error.message}
+        actionLabel="Reload"
+        onAction={() => window.location.reload()}
+      />
+    );
+  }
+}
+`;
 }
 function developerAppTsx(application) {
   const appName = toTitle(application.name);
   const defaultClientId = `${toSlug(application.id)}_local_client`;
-  return [
-    "import { useEffect, useMemo, useState } from 'react';",
-    "import { createAccountLinkPayload, createTopoloAuthorizationUrl, exchangeTopoloCode, fetchTopoloUserInfo, type TopoloUserInfo } from '@topolo/login';",
-    "",
-    "type AuthState = 'ready' | 'missing_client' | 'authorizing' | 'authenticated' | 'error';",
-    "",
-    `const APP_NAME = '${escapeSingleQuoted(appName)}';`,
-    "const AUTH_URL = import.meta.env.VITE_TOPOLO_AUTH_URL ?? import.meta.env.VITE_TOPOLO_AUTH_BASE_URL ?? 'https://auth.topolo.app';",
-    `const CLIENT_ID = import.meta.env.VITE_TOPOLO_CLIENT_ID || '${defaultClientId}';`,
-    "const REDIRECT_URI = import.meta.env.VITE_TOPOLO_REDIRECT_URI || `${window.location.origin}/auth/callback`;",
-    "const REQUESTED_SCOPES = (import.meta.env.VITE_TOPOLO_SCOPES || 'openid profile email organization:read entitlements:read').split(/[\\s,]+/).filter(Boolean);",
-    "",
-    "export default function App() {",
-    "  const [authState, setAuthState] = useState<AuthState>(() => CLIENT_ID ? 'ready' : 'missing_client');",
-    "  const [message, setMessage] = useState<string | null>(null);",
-    "  const [tokenPreview, setTokenPreview] = useState<string | null>(null);",
-    "  const [userInfo, setUserInfo] = useState<TopoloUserInfo | null>(null);",
-    "",
-    "  const callbackCode = useMemo(() => new URLSearchParams(window.location.search).get('code'), []);",
-    "  const callbackError = useMemo(() => new URLSearchParams(window.location.search).get('error'), []);",
-    "",
-    "  useEffect(() => {",
-    "    if (callbackError) {",
-    "      setAuthState('error');",
-    "      setMessage(callbackError);",
-    "      return;",
-    "    }",
-    "    if (!callbackCode) return;",
-    "",
-    "    setAuthState('authorizing');",
-    "    void exchangeAuthorizationCode(callbackCode)",
-    "      .then(async (tokens) => {",
-    "        sessionStorage.setItem(`${CLIENT_ID}:topolo_access_token`, tokens.access_token);",
-    "        if (tokens.refresh_token) {",
-    "          sessionStorage.setItem(`${CLIENT_ID}:topolo_refresh_token`, tokens.refresh_token);",
-    "        }",
-    "        const profile = await fetchTopoloUserInfo({ authBaseUrl: AUTH_URL, accessToken: tokens.access_token });",
-    "        const link = createAccountLinkPayload({",
-    "          localUserId: profile.email ? `local:${profile.email}` : `local:${profile.sub}`,",
-    "          userInfo: profile,",
-    "        });",
-    "        sessionStorage.setItem(`${CLIENT_ID}:topolo_account_link`, JSON.stringify(link));",
-    "        setUserInfo(profile);",
-    "        setTokenPreview(`${tokens.access_token.slice(0, 18)}...`);",
-    "        setAuthState('authenticated');",
-    "        window.history.replaceState({}, document.title, '/');",
-    "      })",
-    "      .catch((error: Error) => {",
-    "        setAuthState('error');",
-    "        setMessage(error.message);",
-    "      });",
-    "  }, [callbackCode, callbackError]);",
-    "",
-    "  return (",
-    '    <main className="topolo-starter-login">',
-    '      <section className="topolo-starter-login__panel">',
-    "        <h1>{APP_NAME}</h1>",
-    "        <p>Public Topolo OAuth starter using authorization-code + PKCE.</p>",
-    "        {authState === 'missing_client' && (",
-    "          <p>Set VITE_TOPOLO_CLIENT_ID after registering this app in Topolo Developers.</p>",
-    "        )}",
-    "        {authState === 'authenticated' && (",
-    "          <p>Topolo sign-in complete for {userInfo?.email ?? userInfo?.sub}. Access token: {tokenPreview}</p>",
-    "        )}",
-    "        {authState === 'error' && <p>{message}</p>}",
-    `        <button type="button" disabled={!CLIENT_ID || authState === 'authorizing'} onClick={() => void startTopoloLogin()}>`,
-    "          {authState === 'authorizing' ? 'Completing sign-in' : 'Sign in with Topolo'}",
-    "        </button>",
-    "      </section>",
-    "    </main>",
-    "  );",
-    "}",
-    "",
-    "async function startTopoloLogin(): Promise<void> {",
-    "  const authorization = await createTopoloAuthorizationUrl({",
-    "    authBaseUrl: AUTH_URL,",
-    "    clientId: CLIENT_ID,",
-    "    redirectUri: REDIRECT_URI,",
-    "    scopes: REQUESTED_SCOPES,",
-    "  });",
-    "  sessionStorage.setItem(`${CLIENT_ID}:topolo_pkce_verifier`, authorization.codeVerifier);",
-    "  sessionStorage.setItem(`${CLIENT_ID}:topolo_oauth_state`, authorization.state);",
-    "  window.location.assign(authorization.url);",
-    "}",
-    "",
-    "async function exchangeAuthorizationCode(code: string): Promise<{ access_token: string; refresh_token?: string }> {",
-    "  const params = new URLSearchParams(window.location.search);",
-    "  const expectedState = sessionStorage.getItem(`${CLIENT_ID}:topolo_oauth_state`);",
-    "  if (expectedState && params.get('state') !== expectedState) {",
-    "    throw new Error('OAuth state mismatch. Restart sign-in.');",
-    "  }",
-    "  const verifier = sessionStorage.getItem(`${CLIENT_ID}:topolo_pkce_verifier`);",
-    "  if (!verifier) throw new Error('Missing PKCE verifier. Restart sign-in.');",
-    "",
-    "  return exchangeTopoloCode({",
-    "    authBaseUrl: AUTH_URL,",
-    "    clientId: CLIENT_ID,",
-    "      code,",
-    "    redirectUri: REDIRECT_URI,",
-    "    codeVerifier: verifier,",
-    "  });",
-    "}",
-    ""
-  ].join("\n");
+  return `import { useEffect, useMemo, useState } from 'react';
+import { createAccountLinkPayload, createTopoloAuthorizationUrl, exchangeTopoloCode, fetchTopoloUserInfo, type TopoloUserInfo } from '@topolo/login';
+
+type AuthState = 'ready' | 'missing_client' | 'authorizing' | 'authenticated' | 'error';
+const APP_NAME = '${escapeSingleQuoted(appName)}';
+const AUTH_URL = import.meta.env.VITE_TOPOLO_AUTH_URL ?? import.meta.env.VITE_TOPOLO_AUTH_BASE_URL ?? 'https://auth.topolo.app';
+const CLIENT_ID = import.meta.env.VITE_TOPOLO_CLIENT_ID || '${defaultClientId}';
+const REDIRECT_URI = import.meta.env.VITE_TOPOLO_REDIRECT_URI || \`\${window.location.origin}/auth/callback\`;
+const REQUESTED_SCOPES = (import.meta.env.VITE_TOPOLO_SCOPES || 'openid profile email organization:read entitlements:read').split(/[\\s,]+/).filter(Boolean);
+
+export default function App() {
+  const [authState, setAuthState] = useState<AuthState>(() => CLIENT_ID ? 'ready' : 'missing_client');
+  const [message, setMessage] = useState<string | null>(null);
+  const [tokenPreview, setTokenPreview] = useState<string | null>(null);
+  const [userInfo, setUserInfo] = useState<TopoloUserInfo | null>(null);
+  const callbackCode = useMemo(() => new URLSearchParams(window.location.search).get('code'), []);
+  const callbackError = useMemo(() => new URLSearchParams(window.location.search).get('error'), []);
+
+  useEffect(() => {
+    if (callbackError) {
+      setAuthState('error');
+      setMessage(callbackError);
+      return;
+    }
+    if (!callbackCode) return;
+    setAuthState('authorizing');
+    void exchangeAuthorizationCode(callbackCode)
+      .then(async (tokens) => {
+        sessionStorage.setItem(\`\${CLIENT_ID}:topolo_access_token\`, tokens.access_token);
+        if (tokens.refresh_token) sessionStorage.setItem(\`\${CLIENT_ID}:topolo_refresh_token\`, tokens.refresh_token);
+        const profile = await fetchTopoloUserInfo({ authBaseUrl: AUTH_URL, accessToken: tokens.access_token });
+        const link = createAccountLinkPayload({ localUserId: profile.email ? \`local:\${profile.email}\` : \`local:\${profile.sub}\`, userInfo: profile });
+        sessionStorage.setItem(\`\${CLIENT_ID}:topolo_account_link\`, JSON.stringify(link));
+        setUserInfo(profile);
+        setTokenPreview(\`\${tokens.access_token.slice(0, 18)}...\`);
+        setAuthState('authenticated');
+        window.history.replaceState({}, document.title, '/');
+      })
+      .catch((error: Error) => {
+        setAuthState('error');
+        setMessage(error.message);
+      });
+  }, [callbackCode, callbackError]);
+
+  return (
+    <main className="topolo-starter-login">
+      <section className="topolo-starter-login__panel">
+        <h1>{APP_NAME}</h1>
+        <p>Public Topolo OAuth starter using authorization-code + PKCE.</p>
+        {authState === 'missing_client' && <p>Set VITE_TOPOLO_CLIENT_ID after registering this app in Topolo Developers.</p>}
+        {authState === 'authenticated' && <p>Topolo sign-in complete for {userInfo?.email ?? userInfo?.sub}. Access token: {tokenPreview}</p>}
+        {authState === 'error' && <p>{message}</p>}
+        <button type="button" disabled={!CLIENT_ID || authState === 'authorizing'} onClick={() => void startTopoloLogin()}>
+          {authState === 'authorizing' ? 'Completing sign-in' : 'Sign in with Topolo'}
+        </button>
+      </section>
+    </main>
+  );
+}
+
+async function startTopoloLogin(): Promise<void> {
+  const authorization = await createTopoloAuthorizationUrl({ authBaseUrl: AUTH_URL, clientId: CLIENT_ID, redirectUri: REDIRECT_URI, scopes: REQUESTED_SCOPES });
+  sessionStorage.setItem(\`\${CLIENT_ID}:topolo_pkce_verifier\`, authorization.codeVerifier);
+  sessionStorage.setItem(\`\${CLIENT_ID}:topolo_oauth_state\`, authorization.state);
+  window.location.assign(authorization.url);
+}
+
+async function exchangeAuthorizationCode(code: string): Promise<{ access_token: string; refresh_token?: string }> {
+  const params = new URLSearchParams(window.location.search);
+  const expectedState = sessionStorage.getItem(\`\${CLIENT_ID}:topolo_oauth_state\`);
+  if (expectedState && params.get('state') !== expectedState) throw new Error('OAuth state mismatch. Restart sign-in.');
+  const verifier = sessionStorage.getItem(\`\${CLIENT_ID}:topolo_pkce_verifier\`);
+  if (!verifier) throw new Error('Missing PKCE verifier. Restart sign-in.');
+  return exchangeTopoloCode({ authBaseUrl: AUTH_URL, clientId: CLIENT_ID, code, redirectUri: REDIRECT_URI, codeVerifier: verifier });
+}
+`;
 }
 
 // src/commands/app-scaffold-worker-template.ts
-function webWorkerTs(application) {
+function webWorkerTs(application, api) {
   const serviceName = toTitle(application.name);
   return [
-    "interface Env {",
-    "  API: { fetch(request: Request): Promise<Response> };",
-    "}",
+    ...api ? [
+      "interface Env {",
+      "  API: { fetch(request: Request): Promise<Response> };",
+      "}"
+    ] : ["type Env = Record<string, never>;"],
     "",
     `const SERVICE_NAME = '${escapeSingleQuoted(serviceName)}';`,
     "",
     "export default {",
-    "  async fetch(request: Request, env: Env): Promise<Response> {",
-    "    const url = new URL(request.url);",
-    "    if (url.pathname.startsWith('/api/')) {",
-    "      return env.API.fetch(request);",
-    "    }",
+    api ? "  async fetch(request: Request, env: Env): Promise<Response> {" : "  async fetch(): Promise<Response> {",
+    ...api ? [
+      "    const url = new URL(request.url);",
+      "    if (url.pathname.startsWith('/api/')) {",
+      "      return env.API.fetch(request);",
+      "    }"
+    ] : [],
     "    return Response.json({ ok: true, service: SERVICE_NAME }, { status: 200 });",
     "  },",
     "};",
     ""
   ].join("\n");
 }
-function platformWebWranglerToml(application) {
+function platformWebWranglerToml(application, api) {
   const slug = toSlug(application.id);
   const host = application.productionUrl ? new URL(application.productionUrl).host : `${slug}.topolo.app`;
   return [
@@ -7117,7 +7122,7 @@ function platformWebWranglerToml(application) {
     'directory = "./dist"',
     'binding = "ASSETS"',
     'not_found_handling = "single-page-application"',
-    'run_worker_first = ["/api/*"]',
+    ...api ? ['run_worker_first = ["/api/*"]'] : [],
     "",
     "[observability]",
     "enabled = true",
@@ -7130,10 +7135,12 @@ function platformWebWranglerToml(application) {
     `APP_ID = "${application.appId ?? ""}"`,
     `VITE_TOPOLO_APP_ID = "${application.appId ?? ""}"`,
     "",
-    "[[services]]",
-    'binding = "API"',
-    `service = "topolo-${slug}-api"`,
-    "",
+    ...api ? [
+      "[[services]]",
+      'binding = "API"',
+      `service = "topolo-${slug}-api"`,
+      ""
+    ] : [],
     "[env.development]",
     `name = "topolo-${slug}-development"`,
     `account_id = "${DEVELOPMENT_CLOUDFLARE_ACCOUNT_ID}"`,
@@ -7151,12 +7158,14 @@ function platformWebWranglerToml(application) {
     'directory = "./dist"',
     'binding = "ASSETS"',
     'not_found_handling = "single-page-application"',
-    'run_worker_first = ["/api/*"]',
-    "",
-    "[[env.development.services]]",
-    'binding = "API"',
-    `service = "topolo-${slug}-api-development"`,
+    ...api ? ['run_worker_first = ["/api/*"]'] : [],
     "",
+    ...api ? [
+      "[[env.development.services]]",
+      'binding = "API"',
+      `service = "topolo-${slug}-api-development"`,
+      ""
+    ] : [],
     "[env.staging]",
     `name = "topolo-${slug}-staging"`,
     `account_id = "${STAGING_CLOUDFLARE_ACCOUNT_ID}"`,
@@ -7174,12 +7183,14 @@ function platformWebWranglerToml(application) {
     'directory = "./dist"',
     'binding = "ASSETS"',
     'not_found_handling = "single-page-application"',
-    'run_worker_first = ["/api/*"]',
-    "",
-    "[[env.staging.services]]",
-    'binding = "API"',
-    `service = "topolo-${slug}-api-staging"`,
+    ...api ? ['run_worker_first = ["/api/*"]'] : [],
     "",
+    ...api ? [
+      "[[env.staging.services]]",
+      'binding = "API"',
+      `service = "topolo-${slug}-api-staging"`,
+      ""
+    ] : [],
     "[env.production]",
     `name = "topolo-${slug}-production"`,
     `account_id = "${CLOUDFLARE_ACCOUNT_ID}"`,
@@ -7197,12 +7208,14 @@ function platformWebWranglerToml(application) {
     'directory = "./dist"',
     'binding = "ASSETS"',
     'not_found_handling = "single-page-application"',
-    'run_worker_first = ["/api/*"]',
+    ...api ? ['run_worker_first = ["/api/*"]'] : [],
     "",
-    "[[env.production.services]]",
-    'binding = "API"',
-    `service = "topolo-${slug}-api-production"`,
-    ""
+    ...api ? [
+      "[[env.production.services]]",
+      'binding = "API"',
+      `service = "topolo-${slug}-api-production"`,
+      ""
+    ] : []
   ].join("\n");
 }
 function platformApiWranglerToml(application, resources, profile) {
@@ -7777,6 +7790,8 @@ function topoloConformanceWorkflow(options) {
     "  pull_request:",
     "  push:",
     "    branches:",
+    "      - staging",
+    "      - development",
     "      - main",
     "  workflow_dispatch:",
     "",
@@ -7814,10 +7829,11 @@ function topoloConformanceWorkflow(options) {
     "          token: ${{ steps.app-token.outputs.token || secrets.TOPOLO_CI_REPO_TOKEN }}",
     ...cliCheckoutStep,
     "",
-    "      - name: Skip conformance without cross-repo token",
+    "      - name: Require Topolo package and repository credentials",
     `        if: steps.app-token.outputs.token == '' && env.HAS_TOPOLO_CI_REPO_TOKEN != 'true'`,
     "        run: |",
-    '          echo "::warning::Skipping Topolo app conformance because no Topolo cross-repo token is available to this workflow context."',
+    '          echo "::error::Topolo conformance requires TOPOLO_PACKAGES_APP credentials or TOPOLO_CI_REPO_TOKEN."',
+    "          exit 1",
     "",
     "      - name: Setup Node.js",
     `        if: steps.app-token.outputs.token != '' || env.HAS_TOPOLO_CI_REPO_TOKEN == 'true'`,
@@ -7825,6 +7841,14 @@ function topoloConformanceWorkflow(options) {
     "        with:",
     "          node-version: 20",
     "",
+    "      - name: Enable pnpm and authenticate Topolo packages",
+    `        if: steps.app-token.outputs.token != '' || env.HAS_TOPOLO_CI_REPO_TOKEN == 'true'`,
+    "        env:",
+    `          NODE_AUTH_TOKEN: \${{ steps.app-token.outputs.token || secrets.TOPOLO_CI_REPO_TOKEN }}`,
+    "        run: |",
+    "          corepack enable",
+    '          printf "//npm.pkg.github.com/:_authToken=%s\\n" "$NODE_AUTH_TOKEN" >> "$HOME/.npmrc"',
+    "",
     "      - name: Build Topolo SDK",
     `        if: steps.app-token.outputs.token != '' || env.HAS_TOPOLO_CI_REPO_TOKEN == 'true'`,
     "        working-directory: topolo-platform/packages/topolo-sdk",
@@ -7839,16 +7863,30 @@ function topoloConformanceWorkflow(options) {
     "          npm install --no-audit --no-fund",
     "          npm run build",
     "",
-    "      - name: Run Topolo app conformance audit",
+    "      - name: Install generated application",
     `        if: steps.app-token.outputs.token != '' || env.HAS_TOPOLO_CI_REPO_TOKEN == 'true'`,
+    `        working-directory: ${appPath}`,
+    "        run: pnpm install --frozen-lockfile",
+    "",
+    "      - name: Run generated application quality gates",
+    `        if: steps.app-token.outputs.token != '' || env.HAS_TOPOLO_CI_REPO_TOKEN == 'true'`,
+    `        working-directory: ${appPath}`,
     "        run: |",
-    `          node topolo-platform/packages/topolo-cli/dist/index.js apps audit ${options.id} --local --repo-root "$GITHUB_WORKSPACE" --fail-on needs_review --json`,
+    "          pnpm run typecheck",
+    "          pnpm run coverage",
+    "          pnpm run build",
+    '          if pnpm run | grep -q "check:deploy-config"; then pnpm run check:deploy-config; fi',
     "",
-    "      - name: Record green CI evidence",
+    "      - name: Record verified CI evidence",
     `        if: \${{ success() && (steps.app-token.outputs.token != '' || env.HAS_TOPOLO_CI_REPO_TOKEN == 'true') }}`,
     `        working-directory: ${appPath}`,
     "        run: |",
-    `          node "$GITHUB_WORKSPACE/topolo-platform/packages/topolo-cli/dist/index.js" apps record-evidence ${options.id} --build --typecheck --test --commit "$GITHUB_SHA"`
+    `          node "$GITHUB_WORKSPACE/topolo-platform/packages/topolo-cli/dist/index.js" apps record-evidence ${options.id} --build --typecheck --test --commit "$GITHUB_SHA"`,
+    "",
+    "      - name: Run Topolo app conformance audit",
+    `        if: steps.app-token.outputs.token != '' || env.HAS_TOPOLO_CI_REPO_TOKEN == 'true'`,
+    "        run: |",
+    `          node topolo-platform/packages/topolo-cli/dist/index.js apps audit ${options.id} --local --repo-root "$GITHUB_WORKSPACE" --fail-on needs_review --json`
   ].join("\n");
 }
 
@@ -8022,6 +8060,15 @@ function topoloActionContractsMjs() {
     ""
   ].join("\n");
 }
+function topoloActionContractsDmts() {
+  return [
+    "import type { TopoloActionContracts } from '@topolo-io/worker-runtime/actions';",
+    "",
+    "export const topoloActionContracts: TopoloActionContracts;",
+    "export const topoloActionInputSchemas: Record<string, unknown>;",
+    ""
+  ].join("\n");
+}
 function baselineApiActions() {
   const emptyInputSchema = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -8715,6 +8762,131 @@ function envExample(application) {
   ].join("\n");
 }
 
+// src/commands/app-scaffold-test-template.ts
+var coverageThresholds = `      thresholds: {
+        statements: 100,
+        branches: 100,
+        functions: 100,
+        lines: 100,
+      },`;
+function platformBrowserVitestConfig() {
+  return `import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.{ts,tsx}'],
+    environment: 'jsdom',
+    coverage: {
+      provider: 'v8',
+      include: ['src/app-config.ts', 'src/app-routes.tsx', 'src/worker.ts'],
+${coverageThresholds}
+    },
+  },
+});
+`;
+}
+function platformApiVitestConfig() {
+  return `import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.{js,mjs,mts,ts,tsx}'],
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      include: ['src/app-identity.ts'],
+${coverageThresholds}
+    },
+  },
+});
+`;
+}
+function platformBrowserContractTest(application, experience) {
+  const required = experience.workspaceSwitcher === "required";
+  const enabled = experience.workspaceSwitcher !== "off";
+  const navExpectation = experience.navigationMode === "none" ? "    expect(home.nav).toBeUndefined();" : `    expect(home.nav).toEqual({ id: 'home', label: '${escapeSingleQuoted(experience.homeLabel)}' });`;
+  return `import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('../src/app-identity', () => ({
+  SCAFFOLD_APP_NAME: '${escapeSingleQuoted(application.name)}',
+  getBrowserAuthBaseUrl: () => 'https://auth.stg.topolo.us',
+}));
+
+import { HOME_LABEL, HOME_PATH, NAVIGATION_MODE, WORKSPACE_RESOURCE } from '../src/app-config';
+import { createAppRoutes } from '../src/app-routes';
+
+describe('generated application contract', () => {
+  it('uses the selected home, navigation, and context-switcher shape', () => {
+    expect(HOME_PATH).toBe('${escapeSingleQuoted(experience.homePath)}');
+    expect(HOME_LABEL).toBe('${escapeSingleQuoted(experience.homeLabel)}');
+    expect(NAVIGATION_MODE).toBe('${experience.navigationMode}');
+    expect(WORKSPACE_RESOURCE.enabled).toBe(${enabled});
+    expect('required' in WORKSPACE_RESOURCE ? WORKSPACE_RESOURCE.required : false).toBe(${required});
+  });
+
+  it('keeps Getting Started out of product navigation', () => {
+    const [home, gettingStarted] = createAppRoutes('app_test');
+    expect(home.path).toBe('${escapeSingleQuoted(experience.homePath)}');
+${navExpectation}
+    expect(gettingStarted.path).toBe('/getting-started');
+    expect(gettingStarted.nav).toBeUndefined();
+  });
+});
+`;
+}
+function platformWebWorkerTest(application, api) {
+  const apiTest = api ? `  it('proxies API paths to the API service binding', async () => {
+    const response = new Response('proxied', { status: 202 });
+    const fetch = vi.fn().mockResolvedValue(response);
+    await expect(worker.fetch(new Request('https://app.test/api/health'), { API: { fetch } })).resolves.toBe(response);
+    expect(fetch).toHaveBeenCalledOnce();
+  });
+
+` : "";
+  const env = api ? "{ API: { fetch: vi.fn() } }" : "{}";
+  return `import { describe, expect, it, vi } from 'vitest';
+import worker from '../src/worker';
+
+describe('browser worker routing', () => {
+${apiTest}
+  it('returns the browser service descriptor for asset paths', async () => {
+    const response = await worker.fetch(new Request('https://app.test/dashboard'), ${env});
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toEqual({ ok: true, service: '${escapeSingleQuoted(toTitle(application.name))}' });
+  });
+});
+`;
+}
+function platformApiHealthTest(application) {
+  return `import { describe, expect, it } from 'vitest';
+import worker from '../src/worker';
+import { resolveRuntimeAppId } from '../src/app-identity';
+
+const executionContext = {
+  waitUntil() {},
+  passThroughOnException() {},
+  props: {},
+} as unknown as ExecutionContext;
+
+describe('API runtime baseline', () => {
+  it('serves a real health response through the generated worker stack', async () => {
+    const response = await worker.fetch(
+      new Request('https://api.test/api/health'),
+      { APP_ID: '${escapeSingleQuoted(application.appId ?? application.id)}' },
+      executionContext,
+    );
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({ ok: true, app: '${escapeSingleQuoted(application.appId ?? application.id)}' });
+  });
+
+  it('requires runtime app identity', async () => {
+    await expect(resolveRuntimeAppId({ APP_ID: ' app_runtime ' })).resolves.toBe('app_runtime');
+    expect(() => resolveRuntimeAppId({})).toThrow('APP_ID is required');
+  });
+});
+`;
+}
+
 // src/commands/app-scaffold.ts
 function standardScriptStub() {
   return `#!/usr/bin/env python3
@@ -8807,9 +8979,18 @@ function applicationScaffoldPayload(application, options = {}) {
   }
   const ownerType = target === "platform" ? "topolo_first_party" : "third_party";
   const distributionModel = target === "platform" ? "marketplace" : "organization_internal";
-  const appDir = options.appDir ?? catalogApplication?.appDir ?? (target === "platform" ? `Topolo${toPascalCase(id)}` : `topolo-${slug}`);
+  const requestedAppDir = options.appDir ?? catalogApplication?.appDir ?? (target === "platform" ? `Topolo${toPascalCase(id)}` : `topolo-${slug}`);
+  const appDir = target === "platform" ? normalizeFirstPartyAppDir(requestedAppDir) : requestedAppDir;
   const name = options.name ?? catalogApplication?.name ?? `topolo-${slug}`;
   const packageName = options.packageName ?? catalogApplication?.packageName ?? `topolo-${slug}`;
+  const experience = {
+    homePath: normalizeHomePath(options.homePath),
+    homeLabel: normalizeHomeLabel(options.homeLabel),
+    navigationMode: normalizeNavigationMode(options.navigationMode),
+    workspaceSwitcher: normalizeWorkspaceSwitcherMode(options.workspaceSwitcher),
+    workspaceLabel: tenancy === "household" ? "Households" : "Workspaces",
+    tagline: String(options.tagline || "").trim() || `Manage your work in ${toTitle(name)}.`
+  };
   const serviceSlug = api ? target === "platform" ? `topolo-${slug}` : id : null;
   const defaultAppId = target === "platform" ? `app_topolo_${id}` : catalogApplication?.services[0] ?? id;
   const appId = api ? options.appId ?? defaultAppId : null;
@@ -8838,6 +9019,7 @@ function applicationScaffoldPayload(application, options = {}) {
     containerAppId,
     profile,
     resources,
+    experience,
     distributionModel,
     capabilities,
     application: applicationPayload,
@@ -8856,6 +9038,7 @@ function applicationScaffoldPayload(application, options = {}) {
         containerAppId,
         profile,
         resources,
+        experience,
         distributionModel,
         capabilities
       },
@@ -8924,18 +9107,10 @@ function scaffoldPackages(options) {
   }
   const packages = /* @__PURE__ */ new Set();
   if (options.browser) {
-    packages.add("@topolo-io/app-funnel");
-    packages.add("@topolo-io/app-launcher");
-    packages.add("@topolo-io/app-shell");
-    packages.add("@topolo-io/auth-client");
-    packages.add("@topolo-io/design-tokens");
-    packages.add("@topolo-io/onboarding");
-    packages.add("@topolo-io/tour");
-    packages.add("@topolo-io/ui-kit");
+    for (const packageName of PLATFORM_BROWSER_TOPOLO_PACKAGES) packages.add(packageName);
   }
   if (options.api) {
-    packages.add("@topolo-io/worker-runtime");
-    packages.add("@topolo/sdk");
+    for (const packageName of PLATFORM_API_TOPOLO_PACKAGES) packages.add(packageName);
   }
   return Array.from(packages);
 }
@@ -9015,6 +9190,12 @@ function scaffoldFiles(options) {
       ],
       content: gitignore()
     },
+    ...target === "platform" ? [{
+      path: `${base}/.npmrc`,
+      purpose: "Scoped package registry routing without persisted credentials.",
+      requiredSignals: ["routes private @topolo-io packages to GitHub Packages", "keeps public @topolo packages on npm", "does not contain an authentication token"],
+      content: npmrc()
+    }] : [],
     {
       path: `${base}/AGENTS.md`,
       purpose: "Local agent rules for safe work inside the generated project.",
@@ -9030,42 +9211,44 @@ function scaffoldFiles(options) {
         resources: options.payload.resources
       })
     },
-    {
-      path: `${browserBase}/vite.config.ts`,
-      purpose: "Vite browser build configuration.",
-      requiredSignals: [
-        "builds the authenticated browser surface",
-        "keeps generated apps on the standard React/Vite baseline"
-      ],
-      content: viteConfig(target)
-    },
-    {
-      path: `${browserBase}/index.html`,
-      purpose: "Browser entry document.",
-      requiredSignals: [
-        "mounts the React app at #root",
-        "uses the generated application display name"
-      ],
-      content: indexHtml(application.name)
-    },
-    {
-      path: `${browserBase}/src/main.tsx`,
-      purpose: "React app entrypoint.",
-      requiredSignals: [
-        "renders the generated app component",
-        "imports the generated app stylesheet"
-      ],
-      content: mainTsx()
-    },
-    {
-      path: `${browserBase}/src/env.d.ts`,
-      purpose: "Vite environment variable typing.",
-      requiredSignals: [
-        "loads vite/client import.meta.env types",
-        "declares the Topolo environment variables consumed by the starter"
-      ],
-      content: envDts(options.api)
-    },
+    ...options.browser ? [
+      {
+        path: `${browserBase}/vite.config.ts`,
+        purpose: "Vite browser build configuration.",
+        requiredSignals: [
+          "builds the authenticated browser surface",
+          "keeps generated apps on the standard React/Vite baseline"
+        ],
+        content: viteConfig(target)
+      },
+      {
+        path: `${browserBase}/index.html`,
+        purpose: "Browser entry document.",
+        requiredSignals: [
+          "mounts the React app at #root",
+          "uses the generated application display name"
+        ],
+        content: indexHtml(application.name)
+      },
+      {
+        path: `${browserBase}/src/main.tsx`,
+        purpose: "React app entrypoint.",
+        requiredSignals: [
+          "renders the generated app component",
+          "imports the generated app stylesheet"
+        ],
+        content: mainTsx()
+      },
+      {
+        path: `${browserBase}/src/env.d.ts`,
+        purpose: "Vite environment variable typing.",
+        requiredSignals: [
+          "loads vite/client import.meta.env types",
+          "declares the Topolo environment variables consumed by the starter"
+        ],
+        content: envDts(options.api)
+      }
+    ] : [],
     ...options.payload.resources.workflow ? [
       {
         path: `${base}/src/cloudflare-workers.d.ts`,
@@ -9077,7 +9260,7 @@ function scaffoldFiles(options) {
         content: cloudflareWorkersDts()
       }
     ] : [],
-    {
+    ...options.browser ? [{
       path: `${browserBase}/src/styles.css`,
       purpose: "Minimal app-local styles outside the shared Topolo shell.",
       requiredSignals: [
@@ -9085,7 +9268,39 @@ function scaffoldFiles(options) {
         "keeps app-specific layout scoped under generated classes"
       ],
       content: stylesCss()
-    }
+    }] : [],
+    ...target === "platform" && options.browser ? [
+      {
+        path: `${browserBase}/src/app-config.ts`,
+        purpose: "Product route, navigation, context-switcher, and entry-surface configuration.",
+        requiredSignals: ["defaults the authenticated home to /dashboard", "keeps product copy separate from shell wiring"],
+        content: platformAppConfigTs(application, options.payload.experience)
+      },
+      {
+        path: `${browserBase}/src/app-routes.tsx`,
+        purpose: "Canonical protected route manifest and product navigation metadata.",
+        requiredSignals: ["uses the configured home route", "keeps Getting Started out of product navigation"],
+        content: platformAppRoutesTsx(options.payload.experience)
+      },
+      {
+        path: `${browserBase}/src/routes/HomeRoute.tsx`,
+        purpose: "Focused authenticated home product surface.",
+        requiredSignals: ["uses shared page primitives", "uses translation-safe product copy"],
+        content: platformHomeRouteTsx()
+      },
+      {
+        path: `${browserBase}/src/routes/GettingStartedRoute.tsx`,
+        purpose: "Focused role-aware onboarding route reached from the account menu.",
+        requiredSignals: ["uses shared onboarding", "returns to the configured home route"],
+        content: platformGettingStartedRouteTsx()
+      },
+      {
+        path: `${browserBase}/src/AppErrorBoundary.tsx`,
+        purpose: "Recoverable render-error boundary for the product root.",
+        requiredSignals: ["uses the shared auth flow error surface", "forwards render errors to shared capture"],
+        content: platformAppErrorBoundaryTsx()
+      }
+    ] : []
   ];
   if (target === "platform") {
     if (options.browser) {
@@ -9136,6 +9351,15 @@ function scaffoldFiles(options) {
             "each contract has a zod input validator, keeping the manifest actions[] honest"
           ],
           content: topoloActionContractsMjs()
+        },
+        {
+          path: `${base}/topolo.action-contracts.d.mts`,
+          purpose: "TypeScript declaration for the generated JavaScript action-contract module.",
+          requiredSignals: [
+            "types topoloActionContracts against the canonical worker-runtime action contract",
+            "keeps generated API typecheck strict without enabling allowJs"
+          ],
+          content: topoloActionContractsDmts()
         }
       ] : [],
       {
@@ -9310,7 +9534,8 @@ function scaffoldFiles(options) {
       ],
       content: appTsx(application, target, {
         audience: options.payload.audience,
-        portfolio: options.payload.portfolio
+        portfolio: options.payload.portfolio,
+        experience: options.payload.experience
       })
     });
     if (target === "platform") {
@@ -9321,7 +9546,7 @@ function scaffoldFiles(options) {
           "runs component/unit tests under jsdom",
           "keeps the generated browser surface testable from day one"
         ],
-        content: `import { defineConfig } from 'vitest/config';
+        content: target === "platform" ? platformBrowserVitestConfig() : `import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
   test: {
@@ -9331,6 +9556,40 @@ export default defineConfig({
 });
 `
       });
+      if (target === "platform") {
+        files.push(
+          {
+            path: `${browserBase}/test/application-contract.test.tsx`,
+            purpose: "Executable route, navigation, and resource-switcher contract.",
+            requiredSignals: ["asserts the configured product shape", "proves Getting Started is absent from product navigation"],
+            content: platformBrowserContractTest(application, options.payload.experience)
+          },
+          {
+            path: `${browserBase}/test/worker.test.ts`,
+            purpose: "Executable browser Worker routing tests.",
+            requiredSignals: ["proves API proxying", "proves non-API browser fallback"],
+            content: platformWebWorkerTest(application, options.api)
+          },
+          {
+            path: `${browserBase}/src/worker.ts`,
+            purpose: "Browser Worker that serves assets and forwards API paths when an API target exists.",
+            requiredSignals: [
+              "keeps the frontend Worker thin",
+              "only declares an API service binding for API-backed scaffolds"
+            ],
+            content: webWorkerTs(application, options.api)
+          },
+          {
+            path: `${browserBase}/wrangler.toml`,
+            purpose: "Cloudflare Worker static-assets configuration for the browser surface.",
+            requiredSignals: [
+              "serves Vite assets through a Worker with assets",
+              "only binds an API Worker when the scaffold includes one"
+            ],
+            content: platformWebWranglerToml(application, options.api)
+          }
+        );
+      }
     }
   }
   if (options.api) {
@@ -9371,24 +9630,6 @@ export default defineConfig({
           ],
           content: apiAppIdentityTs(application)
         },
-        {
-          path: `${browserBase}/src/worker.ts`,
-          purpose: "Browser Worker that serves assets and forwards API paths to the API Worker binding.",
-          requiredSignals: [
-            "keeps the frontend Worker thin",
-            "routes /api/* to the API service binding instead of owning backend routes locally"
-          ],
-          content: webWorkerTs(application)
-        },
-        {
-          path: `${browserBase}/wrangler.toml`,
-          purpose: "Cloudflare Worker static-assets configuration for the browser surface.",
-          requiredSignals: [
-            "serves Vite assets through a Worker with assets",
-            "binds the frontend Worker to the API Worker for /api/* requests"
-          ],
-          content: platformWebWranglerToml(application)
-        },
         {
           path: `${apiBase}/vitest.config.ts`,
           purpose: "Vitest config for the API worker surface.",
@@ -9396,7 +9637,7 @@ export default defineConfig({
             "runs worker/unit tests under the node environment",
             "keeps the generated service testable from day one"
           ],
-          content: `import { defineConfig } from 'vitest/config';
+          content: target === "platform" ? platformApiVitestConfig() : `import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
   test: {
@@ -9413,7 +9654,7 @@ export default defineConfig({
             "asserts the scaffold boots",
             "is replaced by real route/repository tests as the surface grows"
           ],
-          content: "import { describe, expect, it } from 'vitest';\n\n// Smoke test so the API test suite is non-empty from day one. Replace with\n// real route/repository tests as the surface grows.\ndescribe('api scaffold', () => {\n  it('boots', () => {\n    expect(true).toBe(true);\n  });\n});\n"
+          content: target === "platform" ? platformApiHealthTest(application) : "import { describe, expect, it } from 'vitest';\n\ndescribe('api scaffold', () => {\n  it('boots', () => {\n    expect(true).toBe(true);\n  });\n});\n"
         }
       );
       if (options.payload.resources.d1) {
@@ -10176,10 +10417,10 @@ function registerPlatformCommand(program2) {
   const platformApps = platform3.command("apps").description("Scaffold and operate first-party Topolo platform and personal applications");
   platformApps.command("scaffold <application>").description(
     "Generate a first-party Topolo scaffold for the platform or personal portfolio."
-  ).option("--json", "Output JSON").option("--no-json", "Output human-readable checklist").option("--app-dir <path>", "Application directory under apps/").option("--name <name>", "Application display/package source name").option("--package-name <name>", "package.json name").option("--production-url <url>", "Production browser URL").option("--service <id>", "Stable SDK/Auth app id for API-backed apps").option("--portfolio <portfolio>", "First-party portfolio: platform or personal").option(
+  ).option("--json", "Output JSON").option("--no-json", "Output human-readable checklist").option("--app-dir <path>", "Application repo name or apps/<repo> path").option("--name <name>", "Application display/package source name").option("--package-name <name>", "package.json name").option("--production-url <url>", "Production browser URL").option("--service <id>", "Stable SDK/Auth app id for API-backed apps").option("--portfolio <portfolio>", "First-party portfolio: platform or personal").option(
     "--surface-model <surfaceModel>",
     "First-party surface model: web_app, mobile_container, mobile_module, or messaging_surface"
-  ).option("--container-app-id <appId>", "Container app id when --surface-model mobile_module is used").option("--profile <profile>", "First-party scaffold profile such as spatial-assets").option("--with-d1", "Declare a D1 binding in the first-party scaffold").option("--with-r2", "Declare an R2 binding in the first-party scaffold").option("--with-queue", "Declare a Queue binding in the first-party scaffold").option("--with-workflow", "Declare a Workflow binding in the first-party scaffold").option("--with-container-processing", "Declare container-processing metadata in CloudControl").option("--write", "Write the generated scaffold files to disk").option("--repo-root <path>", "Directory where scaffold files should be written").option("--force", "Overwrite existing scaffold files when --write is set").option("--with-api", "Include the API/service baseline").option("--no-api", "Do not include API/service requirements").option("--no-browser", "Do not include browser-shell requirements").option(
+  ).option("--container-app-id <appId>", "Container app id when --surface-model mobile_module is used").option("--profile <profile>", "First-party scaffold profile such as spatial-assets").option("--with-d1", "Declare a D1 binding in the first-party scaffold").option("--with-r2", "Declare an R2 binding in the first-party scaffold").option("--with-queue", "Declare a Queue binding in the first-party scaffold").option("--with-workflow", "Declare a Workflow binding in the first-party scaffold").option("--with-container-processing", "Declare container-processing metadata in CloudControl").option("--home-path <path>", "Authenticated home route (default: /dashboard)").option("--home-label <label>", "Home navigation label (default: Dashboard)").option("--navigation-mode <mode>", "Product navigation: sidebar, topbar, or none").option("--workspace-switcher <mode>", "Workspace context selector: required, optional, or off").option("--tagline <text>", "Product-facing landing and home description").option("--write", "Write the generated scaffold files to disk").option("--repo-root <path>", "Directory where scaffold files should be written").option("--force", "Overwrite existing scaffold files when --write is set").option("--with-api", "Include the API/service baseline").option("--no-api", "Do not include API/service requirements").option("--no-browser", "Do not include browser-shell requirements").option(
     "--provision",
     "Provision the generated first-party app into Topolo Developers and Auth using the authenticated Topolo admin session"
   ).option(
@@ -10214,7 +10455,12 @@ function registerPlatformCommand(program2) {
         withR2: opts.withR2,
         withQueue: opts.withQueue,
         withWorkflow: opts.withWorkflow,
-        withContainerProcessing: opts.withContainerProcessing
+        withContainerProcessing: opts.withContainerProcessing,
+        homePath: opts.homePath,
+        homeLabel: opts.homeLabel,
+        navigationMode: opts.navigationMode,
+        workspaceSwitcher: opts.workspaceSwitcher,
+        tagline: opts.tagline
       });
       if (opts.workflowOnly && !payload.ciWorkflow) {
         throw new Error("--workflow-only is only available for first-party scaffolds.");