@topolo/cli 0.1.10 → 0.1.12

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";
 
-// ../../PlatformApplications/packages/topolo-sdk/dist/index.js
+// ../../../../../Users/ashes/Projects/topolo/PlatformApplications/packages/topolo-sdk/dist/index.js
 function applyAuthHeaders(headers, credential) {
   if (credential.kind === "api_key") {
     headers.set("X-Api-Key", credential.apiKey);
@@ -1938,11 +1938,11 @@ async function pollUntilApproved(params) {
   throw new Error("Device code expired. Run `topolo auth login` again.");
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
 // src/version.ts
-var CLI_VERSION = "0.1.10";
+var CLI_VERSION = "0.1.12";
 
 // src/client.ts
 async function buildClient(options) {
@@ -2304,13 +2304,26 @@ function enrichFinding(application, finding2, evidence) {
         });
       }
       if (shellEvidence.length === 0) return finding2;
+      if (shellEvidence.includes("local=account-menu")) {
+        return mergeFinding(finding2, {
+          status: "needs_review",
+          reason: "An app-local account menu implementation is visible locally. Account dropdown chrome must come from TopoloAppShell or TopoloAccountMenu, with app-specific actions passed as additive menu items.",
+          evidence: shellEvidence,
+          nextActions: [
+            "Replace app-local UserMenu, user-menu, or accountMenuOpen dropdown code with TopoloAccountMenu",
+            "Use TopoloAppShell accountMenuItems for app-specific account actions",
+            "Keep sign-out, app launcher, command palette, theme, and support actions on the shared account-menu surface"
+          ]
+        });
+      }
       if (!shellEvidence.includes("source=TopoloAppShell")) {
         return mergeFinding(finding2, {
           status: "needs_review",
-          reason: "Shared UI-kit or primitive shell usage is visible locally, but authenticated browser apps must use TopoloAppShell so launcher, account-menu, command, theme, and bug-reporting chrome stay on the shared platform surface.",
+          reason: "Shared UI-kit or primitive shell usage is visible locally, but authenticated browser apps must use TopoloAppShell so launcher, TopoloAccountMenu, command, theme, and bug-reporting chrome stay on the shared platform surface.",
           evidence: shellEvidence,
           nextActions: [
             "Use TopoloAppShell for authenticated first-party app layouts",
+            "Use TopoloAccountMenu when a partial shell still needs account chrome",
             "Keep launcher, account menu, command palette, theme toggle, and bug reporter on the shared shell surface",
             "Keep mobile and desktop shell behavior aligned with the platform UI kit"
           ]
@@ -2322,6 +2335,7 @@ function enrichFinding(application, finding2, evidence) {
         evidence: shellEvidence,
         nextActions: [
           "Use TopoloAppShell for authenticated first-party app layouts",
+          "Pass app-specific account actions through accountMenuItems instead of app-local dropdowns",
           "Keep launcher, account menu, command palette, theme toggle, and bug reporter on the shared shell surface",
           "Keep mobile and desktop shell behavior aligned with the platform UI kit"
         ]
@@ -2373,14 +2387,14 @@ function enrichFinding(application, finding2, evidence) {
 function collectEvidence(repoRoot, application) {
   const appRoot = path.join(repoRoot, "PlatformApplications", application.appDir);
   const packageJsonPath = path.join(appRoot, "package.json");
-  const packageJson = readPackageJson(packageJsonPath);
+  const packageJson2 = readPackageJson(packageJsonPath);
   const cloudcontrolPath = path.join(appRoot, "topolo.cloudcontrol.json");
   const systems = matchingSystems(repoRoot, application);
   return {
     appRoot,
     appExists: isDirectory(appRoot),
     packageJsonPath,
-    packageJson,
+    packageJson: packageJson2,
     packageJsons: collectPackageJsons(appRoot),
     cloudcontrolPath,
     hasCloudControl: isFile(cloudcontrolPath),
@@ -2435,8 +2449,12 @@ function sharedShellEvidence(evidence) {
   if (text.includes("@topolo/ui-kit")) items.push("source=@topolo/ui-kit");
   if (text.includes("TopoloShell")) items.push("source=TopoloShell");
   if (text.includes("TopoloAppShell")) items.push("source=TopoloAppShell");
+  if (text.includes("TopoloAccountMenu")) items.push("source=TopoloAccountMenu");
   if (text.includes("TopoloLauncher")) items.push("source=TopoloLauncher");
   if (text.includes("AppSwitcher")) items.push("source=AppSwitcher");
+  if (/\baccountMenuOpen\b|\bsetAccountMenuOpen\b|\buserMenuOpen\b|\bUserMenu\b|user-menu/.test(text)) {
+    items.push("local=account-menu");
+  }
   return unique(items);
 }
 function hasDocumentationSurface(application, evidence) {
@@ -2601,8 +2619,8 @@ function collectPackageJsons(root) {
         continue;
       }
       if (!entry.isFile() || entry.name !== "package.json") continue;
-      const packageJson = readPackageJson(entryPath);
-      if (packageJson) records.push({ path: entryPath, packageJson });
+      const packageJson2 = readPackageJson(entryPath);
+      if (packageJson2) records.push({ path: entryPath, packageJson: packageJson2 });
     }
   };
   visit(root);
@@ -2691,38 +2709,121 @@ function isFile(filePath) {
 }
 
 // src/commands/app-scaffold.ts
+import { constants } from "fs";
+import { access, mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, relative, resolve } from "path";
+var CLOUDFLARE_ACCOUNT_ID = "49ef1ba682ad8cfd720c86699ae17521";
+var CURRENT_VERIFICATION_DATE = "2026-04-23";
 function applicationScaffoldPayload(application, options = {}) {
+  const target = normalizeTarget(options.target);
+  const portfolio = target === "platform" ? normalizePortfolio(options.portfolio) : null;
   const id = normalizeApplicationId(application);
+  const slug = toSlug(id);
   const catalogApplication = APPLICATIONS[id];
   const browser = options.browser !== false;
-  const api = options.api !== false;
-  const appDir = options.appDir ?? catalogApplication?.appDir ?? `Topolo${toPascalCase(id)}`;
-  const name = options.name ?? catalogApplication?.name ?? `topolo-${id}`;
-  const packageName = options.packageName ?? catalogApplication?.packageName ?? `topolo-${id}`;
-  const serviceId = api ? options.service ?? catalogApplication?.services[0] ?? id : null;
-  const productionUrl = browser ? options.productionUrl ?? catalogApplication?.productionUrl ?? `https://${id}.topolo.app` : null;
+  const api = options.api ?? target === "platform";
+  const audience = normalizeAudience(
+    options.audience,
+    target === "platform" ? portfolio : null
+  );
+  const tenancy = normalizeTenancy(options.tenancy, audience);
+  const surfaceModel = normalizeSurfaceModel(options.surfaceModel);
+  const containerAppId = normalizeContainerAppId(options.containerAppId, surfaceModel);
+  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 name = options.name ?? catalogApplication?.name ?? `topolo-${slug}`;
+  const packageName = options.packageName ?? catalogApplication?.packageName ?? `topolo-${slug}`;
+  const defaultServiceId = target === "platform" ? `srv_topolo_${id}` : id;
+  const serviceId = api ? options.service ?? (target === "platform" ? defaultServiceId : catalogApplication?.services[0] ?? defaultServiceId) : null;
+  const productionUrl = browser ? options.productionUrl ?? catalogApplication?.productionUrl ?? `https://${slug}.topolo.app` : null;
   const scopes = scaffoldScopes({ browser, api });
+  const ciWorkflowPath = target === "platform" ? ".github/workflows/topolo-conformance.yml" : null;
+  const ciWorkflow = target === "platform" ? topoloConformanceWorkflow({ id, appDir }) : null;
+  const applicationPayload = {
+    id,
+    name,
+    appDir,
+    packageName,
+    productionUrl,
+    serviceId
+  };
   return {
     version: APPLICATION_REQUIREMENTS_VERSION,
-    application: {
-      id,
-      name,
-      appDir,
-      packageName,
-      productionUrl,
-      serviceId
-    },
+    target,
+    ownerType,
+    portfolio,
+    audience,
+    tenancy,
+    surfaceModel,
+    containerAppId,
+    distributionModel,
+    application: applicationPayload,
     scopes,
     requirements: APPLICATION_REQUIREMENTS.filter(
       (requirement) => requirement.appliesTo.some((scope) => scopes.includes(scope))
     ),
-    packages: scaffoldPackages({ browser, api }),
-    files: scaffoldFiles({ id, appDir, browser, api }),
-    commands: scaffoldCommands(id),
-    ciWorkflowPath: ".github/workflows/topolo-conformance.yml",
-    ciWorkflow: topoloConformanceWorkflow({ id, appDir })
+    packages: scaffoldPackages({ browser, api, target }),
+    files: scaffoldFiles({
+      payload: {
+        ownerType,
+        portfolio,
+        audience,
+        tenancy,
+        surfaceModel,
+        containerAppId,
+        distributionModel
+      },
+      application: applicationPayload,
+      target,
+      browser,
+      api,
+      ciWorkflow
+    }),
+    commands: scaffoldCommands({
+      id,
+      target,
+      audience,
+      tenancy,
+      portfolio
+    }),
+    ciWorkflowPath,
+    ciWorkflow
   };
 }
+async function writeApplicationScaffold(payload, options = {}) {
+  const root = resolve(options.repoRoot ?? process.cwd());
+  const plannedFiles = payload.files.map((file) => ({
+    file,
+    absolutePath: resolveInside(root, file.path)
+  }));
+  const existingFiles = [];
+  for (const planned of plannedFiles) {
+    if (await pathExists(planned.absolutePath)) {
+      existingFiles.push(planned.file.path);
+    }
+  }
+  if (existingFiles.length > 0 && !options.force) {
+    throw new Error(
+      [
+        "Refusing to overwrite existing scaffold files:",
+        ...existingFiles.map((filePath) => `- ${filePath}`),
+        "Pass --force to overwrite these files."
+      ].join("\n")
+    );
+  }
+  const files = [];
+  for (const planned of plannedFiles) {
+    const existed = await pathExists(planned.absolutePath);
+    await mkdir2(dirname2(planned.absolutePath), { recursive: true });
+    await writeFile2(planned.absolutePath, planned.file.content, "utf8");
+    files.push({
+      path: planned.file.path,
+      status: existed ? "overwritten" : "created"
+    });
+  }
+  return { root, files };
+}
 function scaffoldScopes(options) {
   const scopes = ["all"];
   if (options.browser) scopes.push("browser");
@@ -2732,6 +2833,9 @@ function scaffoldScopes(options) {
   return scopes;
 }
 function scaffoldPackages(options) {
+  if (options.target === "developer") {
+    return [];
+  }
   const packages = /* @__PURE__ */ new Set();
   if (options.browser) {
     packages.add("@topolo/ui-kit");
@@ -2744,52 +2848,206 @@ function scaffoldPackages(options) {
   return Array.from(packages);
 }
 function scaffoldFiles(options) {
-  const base = `PlatformApplications/${options.appDir}`;
+  const { application, target } = options;
+  const slug = toSlug(application.id);
+  const base = target === "platform" ? `PlatformApplications/${application.appDir}` : application.appDir;
   const files = [
     {
       path: `${base}/package.json`,
       purpose: "Package metadata and verification commands.",
       requiredSignals: [
         "name matches the packageName in the SDK application catalog",
-        "scripts include build plus typecheck or test where the stack supports them"
-      ]
+        "scripts include build plus typecheck where the stack supports them"
+      ],
+      content: packageJson(application, target, { browser: options.browser, api: options.api })
+    },
+    {
+      path: `${base}/README.md`,
+      purpose: "Starter README with install, run, and verification commands.",
+      requiredSignals: [
+        "documents the generated app target",
+        "points maintainers to the shared Topolo packages used by the scaffold"
+      ],
+      content: readme(application, target, {
+        api: options.api,
+        audience: options.payload.audience,
+        tenancy: options.payload.tenancy,
+        portfolio: options.payload.portfolio
+      })
+    },
+    {
+      path: `${base}/.gitignore`,
+      purpose: "Generated-app ignore rules.",
+      requiredSignals: [
+        "ignores dependency installs and build output",
+        "keeps local environment files out of source control"
+      ],
+      content: gitignore()
+    },
+    {
+      path: `${base}/tsconfig.json`,
+      purpose: "TypeScript configuration for the generated app.",
+      requiredSignals: [
+        "uses strict mode",
+        "includes browser DOM types for React and Worker types for API-backed apps"
+      ],
+      content: tsconfigJson(options.api)
+    },
+    {
+      path: `${base}/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()
     },
     {
-      path: `${base}/topolo.cloudcontrol.json`,
-      purpose: "CloudControl source of truth for deploy targets, routes, bindings, and CI metadata.",
+      path: `${base}/index.html`,
+      purpose: "Browser entry document.",
       requiredSignals: [
-        "production URLs and Cloudflare targets are explicit",
-        "resource bindings and required secrets are declared without secret values"
-      ]
+        "mounts the React app at #root",
+        "uses the generated application display name"
+      ],
+      content: indexHtml(application.name)
     },
     {
-      path: `${base}/.github/workflows/topolo-conformance.yml`,
-      purpose: "PR/push gate that runs the local Topolo app audit with docs evidence.",
+      path: `${base}/src/main.tsx`,
+      purpose: "React app entrypoint.",
       requiredSignals: [
-        "checks out this repo under its PlatformApplications app directory",
-        "checks out TopoloDocs under PlatformApplications/TopoloDocs",
-        "checks out topolo-sdk and TopoloCli from main so the gate does not wait for an npm publish",
-        "runs topolo apps audit with --local and --fail-on needs_review"
-      ]
+        "renders the generated app component",
+        "imports the generated app stylesheet"
+      ],
+      content: mainTsx()
     },
     {
-      path: `PlatformApplications/TopoloDocs/src/content/systems/topolo-${options.id}.json`,
-      purpose: "Canonical system registry entry.",
+      path: `${base}/src/env.d.ts`,
+      purpose: "Vite environment variable typing.",
       requiredSignals: [
-        `repo_paths includes ${base}`,
-        "doc_paths includes internal handbook coverage",
-        "security_assurance records the auth, tenancy, deployment, and verification boundary"
-      ]
+        "loads vite/client import.meta.env types",
+        "declares the Topolo environment variables consumed by the starter"
+      ],
+      content: envDts(options.api)
     },
     {
-      path: `PlatformApplications/TopoloDocs/src/content/internal/apps/${options.id}.mdx`,
-      purpose: "Internal operator handbook.",
+      path: `${base}/src/styles.css`,
+      purpose: "Minimal app-local styles outside the shared Topolo shell.",
       requiredSignals: [
-        "documents ownership, routes, auth boundary, deployment, operations, and verification",
-        "last_verified is updated when behavior changes"
-      ]
+        "does not fork the shared shell chrome",
+        "keeps app-specific layout scoped under generated classes"
+      ],
+      content: stylesCss()
     }
   ];
+  if (target === "platform") {
+    files.push(
+      {
+        path: `${base}/topolo.cloudcontrol.json`,
+        purpose: "CloudControl source of truth for deploy targets, routes, bindings, and CI metadata.",
+        requiredSignals: [
+          "production URLs and Cloudflare targets are explicit",
+          "resource bindings and required secrets are declared without secret values"
+        ],
+        content: cloudcontrolJson(application, { api: options.api })
+      },
+      {
+        path: `${base}/.github/workflows/topolo-conformance.yml`,
+        purpose: "PR/push gate that runs the local Topolo app audit with docs evidence.",
+        requiredSignals: [
+          "checks out this repo under its PlatformApplications app directory",
+          "checks out TopoloDocs under PlatformApplications/TopoloDocs",
+          "checks out topolo-sdk and TopoloCli from main so the gate does not wait for an npm publish",
+          "runs topolo apps audit with --local and --fail-on needs_review"
+        ],
+        content: options.ciWorkflow ?? ""
+      },
+      {
+        path: `PlatformApplications/TopoloDocs/src/content/systems/topolo-${slug}.json`,
+        purpose: "Canonical system registry entry.",
+        requiredSignals: [
+          `repo_paths includes ${base}`,
+          "doc_paths includes internal handbook coverage",
+          "security_assurance records the auth, tenancy, deployment, and verification boundary"
+        ],
+        content: systemJson(application, {
+          api: options.api,
+          audience: options.payload.audience,
+          tenancy: options.payload.tenancy,
+          portfolio: options.payload.portfolio
+        })
+      },
+      {
+        path: `PlatformApplications/TopoloDocs/src/content/internal/apps/${slug}.mdx`,
+        purpose: "Internal operator handbook.",
+        requiredSignals: [
+          "documents ownership, routes, auth boundary, deployment, operations, and verification",
+          "last_verified is updated when behavior changes"
+        ],
+        content: internalDocs(application, {
+          api: options.api,
+          audience: options.payload.audience,
+          tenancy: options.payload.tenancy,
+          portfolio: options.payload.portfolio
+        })
+      },
+      {
+        path: `PlatformApplications/TopoloDocs/src/content/public/applications/${slug}.mdx`,
+        purpose: "Public application overview.",
+        requiredSignals: [
+          "documents the product surface without internal-only details",
+          "links back to the canonical system registry entry"
+        ],
+        content: publicDocs(application, {
+          api: options.api,
+          audience: options.payload.audience,
+          tenancy: options.payload.tenancy,
+          portfolio: options.payload.portfolio
+        })
+      }
+    );
+    if (options.api && application.serviceId) {
+      files.push({
+        path: `PlatformApplications/TopoloAuth/catalog/service-manifests/${application.serviceId}.json`,
+        purpose: "Auth service manifest for first-party permissions, role bundles, and API-key scopes.",
+        requiredSignals: [
+          "serviceId matches the generated Worker service id",
+          "permissions, role bundles, and API-key scopes exist before the app is catalog-visible",
+          "systems metadata maps the service back to the generated TopoloDocs entries"
+        ],
+        content: serviceManifestJson(application, {
+          tenancy: options.payload.tenancy
+        })
+      });
+    }
+  } else {
+    files.push(
+      {
+        path: `${base}/topolo.app.json`,
+        purpose: "Third-party Topolo application manifest.",
+        requiredSignals: [
+          "declares the external app id, callback URLs, and requested platform scopes",
+          "does not include internal Topolo CloudControl or canonical-docs ownership"
+        ],
+        content: developerManifest(application, {
+          api: options.api,
+          audience: options.payload.audience,
+          tenancy: options.payload.tenancy,
+          surfaceModel: options.payload.surfaceModel,
+          containerAppId: options.payload.containerAppId,
+          distributionModel: options.payload.distributionModel
+        })
+      },
+      {
+        path: `${base}/.env.example`,
+        purpose: "Developer environment template for local auth configuration.",
+        requiredSignals: [
+          "names the Topolo Auth URL",
+          "keeps OAuth client ids and service ids out of source control by default"
+        ],
+        content: envExample(application)
+      }
+    );
+  }
   if (options.browser) {
     files.push({
       path: `${base}/src/App.tsx`,
@@ -2797,8 +3055,13 @@ function scaffoldFiles(options) {
       requiredSignals: [
         "imports shared TopoloAppShell from @topolo/ui-kit",
         "uses @topolo/auth-client for app-origin auth flows",
-        "keeps launcher and account-menu behavior on the shared platform surface"
-      ]
+        "keeps launcher and account-menu behavior on the shared platform surface",
+        "passes app-specific account actions through accountMenuItems or TopoloAccountMenu"
+      ],
+      content: appTsx(application, target, {
+        audience: options.payload.audience,
+        portfolio: options.payload.portfolio
+      })
     });
   }
   if (options.api) {
@@ -2807,9 +3070,10 @@ function scaffoldFiles(options) {
         path: `${base}/wrangler.toml`,
         purpose: "Cloudflare Worker runtime configuration.",
         requiredSignals: [
-          "bindings match topolo.cloudcontrol.json",
+          "bindings match topolo.cloudcontrol.json or topolo.app.json",
           "secrets are referenced by name only"
-        ]
+        ],
+        content: wranglerToml(application, target)
       },
       {
         path: `${base}/src/worker.ts`,
@@ -2818,18 +3082,34 @@ function scaffoldFiles(options) {
           "uses @topolo/auth-middleware or Auth validation for protected routes",
           "derives organization from the credential rather than client-supplied orgId",
           "emits or propagates X-Topolo-Request-Id and X-Topolo-Client"
-        ]
+        ],
+        content: workerTs(application, target, {
+          audience: options.payload.audience,
+          tenancy: options.payload.tenancy
+        })
       }
     );
   }
   return files;
 }
-function scaffoldCommands(id) {
+function scaffoldCommands(options) {
+  const scaffoldId = toSlug(options.id);
+  if (options.target === "developer") {
+    const audienceFlags = options.audience === "personal" ? " --audience personal --tenancy household" : "";
+    return [
+      `topolo apps scaffold ${scaffoldId}${audienceFlags} --write --repo-root .`,
+      `cd topolo-${scaffoldId}`,
+      "npm install",
+      "npm run typecheck",
+      "npm run build"
+    ];
+  }
+  const portfolioFlags = options.portfolio === "personal" ? " --portfolio personal" : "";
   return [
-    `topolo apps scaffold ${id} --json`,
+    `topolo platform apps scaffold ${scaffoldId}${portfolioFlags} --write --repo-root /Users/ashes/Projects/topolo --json`,
     "topolo apps requirements --json",
-    `topolo apps audit ${id} --local --repo-root /Users/ashes/Projects/topolo --fail-on needs_review --json`,
-    `topolo apps audit ${id} --local --repo-root /Users/ashes/Projects/topolo --fail-on partial --json`
+    `topolo apps audit ${options.id} --local --repo-root /Users/ashes/Projects/topolo --fail-on needs_review --json`,
+    `topolo apps audit ${options.id} --local --repo-root /Users/ashes/Projects/topolo --fail-on partial --json`
   ];
 }
 function topoloConformanceWorkflow(options) {
@@ -2904,18 +3184,1448 @@ function topoloConformanceWorkflow(options) {
     `          node PlatformApplications/TopoloCli/dist/index.js apps audit ${options.id} --local --repo-root "$GITHUB_WORKSPACE" --fail-on needs_review --json`
   ].join("\n");
 }
+function packageJson(application, target, options) {
+  const dependencies = {};
+  const devDependencies = {
+    "@types/node": "^20.12.0",
+    typescript: "^5.4.0",
+    vite: "^5.4.0"
+  };
+  const scripts = {
+    dev: "vite --host 0.0.0.0",
+    build: "vite build",
+    preview: "vite preview --host 0.0.0.0",
+    typecheck: "tsc --noEmit"
+  };
+  if (options.browser) {
+    dependencies.react = "^18.3.1";
+    dependencies["react-dom"] = "^18.3.1";
+    devDependencies["@types/react"] = "^18.3.3";
+    devDependencies["@types/react-dom"] = "^18.3.0";
+    devDependencies["@vitejs/plugin-react"] = "^4.7.0";
+    if (target === "platform") {
+      dependencies["@topolo/auth-client"] = topoloPackageVersion("@topolo/auth-client", target);
+      dependencies["@topolo/ui-kit"] = topoloPackageVersion("@topolo/ui-kit", target);
+    }
+  }
+  if (options.api) {
+    if (target === "platform") {
+      dependencies["@topolo/auth-middleware"] = topoloPackageVersion("@topolo/auth-middleware", target);
+      dependencies["@topolo/sdk"] = topoloPackageVersion("@topolo/sdk", target);
+    }
+    devDependencies.wrangler = "^4.40.2";
+    scripts.deploy = "npm run build && wrangler deploy";
+  }
+  return `${json({
+    name: application.packageName,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    scripts,
+    dependencies,
+    devDependencies
+  })}
+`;
+}
+function topoloPackageVersion(packageName, target) {
+  if (target === "developer") {
+    if (packageName === "@topolo/auth-client") return "^1.0.0";
+    return "^0.1.0";
+  }
+  const folder = packageName === "@topolo/sdk" ? "topolo-sdk" : packageName.replace("@topolo/", "topolo-");
+  return `file:../packages/${folder}`;
+}
+function readme(application, target, options) {
+  const displayName = toTitle(application.name);
+  const targetLabel = target === "platform" ? options.portfolio === "personal" ? "first-party Topolo personal application" : "first-party Topolo platform application" : options.audience === "personal" ? "third-party Topolo personal application" : "third-party Topolo business application";
+  const lines = [
+    `# ${displayName}`,
+    "",
+    `Generated ${targetLabel} scaffold for Topolo.`,
+    "",
+    `Audience: ${options.audience}`,
+    `Tenancy: ${options.tenancy}`,
+    ...target === "platform" && options.portfolio ? [`Portfolio: ${options.portfolio}`] : [],
+    "",
+    "## Development",
+    "",
+    "```bash",
+    "npm install",
+    "npm run typecheck",
+    "npm run build",
+    "npm run dev",
+    "```",
+    ""
+  ];
+  if (target === "platform") {
+    lines.push(
+      "## Shared Topolo Surface",
+      "",
+      "- `@topolo/ui-kit` provides the shared shell, launcher, account menu, command palette, and bug reporter.",
+      "- `@topolo/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.",
+      "- `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/auth-middleware` validates Worker requests through Topolo Auth.");
+    }
+  } else {
+    lines.push(
+      "## Topolo Developer Surface",
+      "",
+      "- `topolo.app.json` declares callback URLs, requested scopes, and runtime shape for Topolo Developers.",
+      "- Browser sign-in uses the public Topolo OAuth authorization-code + PKCE flow.",
+      `- The generated app is seeded as a ${options.audience}/${options.tenancy} developer application.`,
+      "- The starter intentionally avoids private first-party packages so it can install outside the Topolo monorepo."
+    );
+  }
+  if (target === "platform") {
+    lines.push(
+      "",
+      "## Platform Registration",
+      "",
+      "This scaffold includes CloudControl metadata, TopoloDocs system coverage, and a Topolo app conformance workflow."
+    );
+  } else {
+    lines.push(
+      "",
+      "## Developer Registration",
+      "",
+      "`topolo.app.json` is the app manifest used to register callback URLs, requested scopes, and local development metadata with Topolo."
+    );
+  }
+  return `${lines.join("\n")}
+`;
+}
+function tsconfigJson(api) {
+  return `${json({
+    compilerOptions: {
+      target: "ES2022",
+      useDefineForClassFields: true,
+      lib: api ? ["ES2022", "DOM", "DOM.Iterable", "WebWorker"] : ["ES2022", "DOM", "DOM.Iterable"],
+      allowJs: false,
+      skipLibCheck: true,
+      esModuleInterop: true,
+      allowSyntheticDefaultImports: true,
+      strict: true,
+      forceConsistentCasingInFileNames: true,
+      module: "ESNext",
+      moduleResolution: "Bundler",
+      resolveJsonModule: true,
+      isolatedModules: true,
+      noEmit: true,
+      jsx: "react-jsx",
+      types: ["vite/client"]
+    },
+    include: ["src"],
+    references: []
+  })}
+`;
+}
+function gitignore() {
+  return [
+    "node_modules/",
+    "dist/",
+    ".wrangler/",
+    ".env",
+    ".env.*",
+    "!.env.example",
+    ""
+  ].join("\n");
+}
+function envDts(api) {
+  const lines = [
+    '/// <reference types="vite/client" />',
+    "",
+    "interface ImportMetaEnv {",
+    "  readonly VITE_TOPOLO_AUTH_URL?: string;",
+    "  readonly VITE_TOPOLO_CLIENT_ID?: string;",
+    "  readonly VITE_TOPOLO_REDIRECT_URI?: string;",
+    "  readonly VITE_TOPOLO_SCOPES?: string;",
+    "  readonly VITE_TOPOLO_SERVICE_ID?: string;"
+  ];
+  if (api) {
+    lines.push("  readonly VITE_TOPOLO_API_URL?: string;");
+  }
+  lines.push(
+    "}",
+    "",
+    "interface ImportMeta {",
+    "  readonly env: ImportMetaEnv;",
+    "}",
+    ""
+  );
+  return lines.join("\n");
+}
+function viteConfig() {
+  return [
+    "import { defineConfig } from 'vite';",
+    "import react from '@vitejs/plugin-react';",
+    "",
+    "export default defineConfig({",
+    "  plugins: [react()],",
+    "  resolve: {",
+    "    dedupe: ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime'],",
+    "  },",
+    "  build: { outDir: 'dist' },",
+    "});",
+    ""
+  ].join("\n");
+}
+function indexHtml(name) {
+  return [
+    "<!doctype html>",
+    '<html lang="en">',
+    "  <head>",
+    '    <meta charset="UTF-8" />',
+    '    <meta name="viewport" content="width=device-width, initial-scale=1.0" />',
+    `    <title>${escapeHtml(toTitle(name))}</title>`,
+    "  </head>",
+    "  <body>",
+    '    <div id="root"></div>',
+    '    <script type="module" src="/src/main.tsx"></script>',
+    "  </body>",
+    "</html>",
+    ""
+  ].join("\n");
+}
+function mainTsx() {
+  return [
+    "import React from 'react';",
+    "import { createRoot } from 'react-dom/client';",
+    "import App from './App';",
+    "import './styles.css';",
+    "",
+    "const root = document.getElementById('root');",
+    "",
+    "if (!root) {",
+    "  throw new Error('Missing #root element.');",
+    "}",
+    "",
+    "createRoot(root).render(",
+    "  <React.StrictMode>",
+    "    <App />",
+    "  </React.StrictMode>,",
+    ");",
+    ""
+  ].join("\n");
+}
+function stylesCss() {
+  return [
+    ":root {",
+    "  color-scheme: light dark;",
+    "  font-family:",
+    '    Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;',
+    "  background: #f7f8fb;",
+    "  color: #182032;",
+    "}",
+    "",
+    "* {",
+    "  box-sizing: border-box;",
+    "}",
+    "",
+    "body {",
+    "  margin: 0;",
+    "  background: #f7f8fb;",
+    "}",
+    "",
+    "button,",
+    "input,",
+    "select,",
+    "textarea {",
+    "  font: inherit;",
+    "}",
+    "",
+    ".topolo-starter-workspace,",
+    ".topolo-starter-card-stack {",
+    "  display: grid;",
+    "  gap: 18px;",
+    "}",
+    "",
+    ".topolo-starter-card h2 {",
+    "  margin: 0 0 12px;",
+    "  font-size: 24px;",
+    "  line-height: 1.2;",
+    "}",
+    "",
+    ".topolo-starter-card p {",
+    "  margin: 0;",
+    "  color: #526071;",
+    "  line-height: 1.55;",
+    "}",
+    "",
+    ".topolo-starter-card {",
+    "  border: 1px solid rgba(24, 32, 50, 0.12);",
+    "  border-radius: 8px;",
+    "  padding: 20px;",
+    "  background: #ffffff;",
+    "}",
+    ""
+  ].join("\n");
+}
+function appTsx(application, target, options) {
+  if (target === "developer") return developerAppTsx(application);
+  return platformAppTsx(application, options);
+}
+function platformAppTsx(application, options) {
+  const appName = toTitle(application.name);
+  const serviceId = application.serviceId ?? application.id;
+  const tagline = options.audience === "personal" ? "Topolo personal app" : "Topolo workspace";
+  const workspaceTitle = options.audience === "personal" ? "Personal app" : "Workspace";
+  return [
+    "import { useEffect, useMemo, useState } from 'react';",
+    "import { createBrowserAuthModule, type AuthUser } from '@topolo/auth-client';",
+    "import { LandingPage, LoginPage, TopoloAppShell, TopoloAuthFlowScreen, TopoloLoadingScreen, type TopoloAppShellUser } from '@topolo/ui-kit';",
+    "",
+    "type NavItem = 'home';",
+    "type AppRoute = { kind: 'root' } | { kind: 'login' } | { kind: 'callback' };",
+    "",
+    `const APP_ID = '${application.id}';`,
+    `const APP_NAME = '${escapeSingleQuoted(appName)}';`,
+    `const DEFAULT_SERVICE_ID = '${serviceId}';`,
+    "const AUTH_URL = import.meta.env.VITE_TOPOLO_AUTH_URL ?? 'https://auth.topolo.app';",
+    "const SERVICE_ID = import.meta.env.VITE_TOPOLO_SERVICE_ID ?? DEFAULT_SERVICE_ID;",
+    "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 workspace shell 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 workspace shell.',",
+    "};",
+    "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 workspace shell for this application.',",
+    "  authenticated_home_path: '/',",
+    "};",
+    "",
+    "const auth = createBrowserAuthModule({",
+    "  authServiceUrl: AUTH_URL,",
+    "  serviceId: SERVICE_ID,",
+    "  devSessionKey: `${SERVICE_ID}_session`,",
+    "  devSessionStorageEnabled: import.meta.env.DEV,",
+    "  callbackPath: '/auth/callback',",
+    "  debug: import.meta.env.DEV,",
+    "});",
+    "",
+    "function getAccessToken(): string | null {",
+    "  return auth.accessTokenMemory.get() ?? auth.accessTokenSession.get();",
+    "}",
+    "",
+    "function toShellUser(user: AuthUser | null): TopoloAppShellUser | null {",
+    "  if (!user) return null;",
+    "  return {",
+    "    name: user.name ?? user.email,",
+    "    email: user.email,",
+    "    role: user.role,",
+    "    organizationName: user.organization?.name ?? user.orgSlug ?? null,",
+    "    organizationId: user.organization?.id ?? user.orgId ?? null,",
+    "  };",
+    "}",
+    "",
+    "export default function App() {",
+    "  const route = getRoute();",
+    "  const [user, setUser] = useState<AuthUser | null>(null);",
+    "  const [loading, setLoading] = useState(true);",
+    "  const [authError, setAuthError] = useState('');",
+    "  const [loginAttempted, setLoginAttempted] = useState(false);",
+    "",
+    "  useEffect(() => {",
+    "    let active = true;",
+    "    const syncAuth = async () => {",
+    "      setLoading(true);",
+    "      setAuthError('');",
+    "",
+    "      if (route.kind === 'callback') {",
+    "        const result = await auth.authClient.handleAuthCallbackAsync(window.location.href);",
+    "        if (!active) return;",
+    "        if (!result.authenticated) {",
+    "          setAuthError(result.error || 'Authentication failed.');",
+    "          setLoading(false);",
+    "          return;",
+    "        }",
+    "        setUser(result.user ?? null);",
+    "        window.location.replace('/');",
+    "        return;",
+    "      }",
+    "",
+    "      const nextUser = await auth.authClient.initialize();",
+    "      if (!active) return;",
+    "      setUser(nextUser);",
+    "      setLoading(false);",
+    "    };",
+    "",
+    "    void syncAuth().catch((error) => {",
+    "      if (!active) return;",
+    "      setAuthError(errorMessage(error));",
+    "      setLoading(false);",
+    "    });",
+    "    return () => {",
+    "      active = false;",
+    "    };",
+    "  }, [route.kind]);",
+    "",
+    "  useEffect(() => {",
+    "    if (!loading && user && route.kind === 'login') {",
+    "      window.location.replace('/');",
+    "    }",
+    "  }, [loading, route.kind, user]);",
+    "",
+    "  const shellUser = useMemo(() => toShellUser(user), [user]);",
+    "",
+    "  if (route.kind === 'callback') {",
+    "    if (loading) {",
+    "      return (",
+    "        <TopoloLoadingScreen",
+    "          appId={APP_ID}",
+    "          serviceId={SERVICE_ID}",
+    "          appName={APP_NAME}",
+    '          subtitle="Completing secure sign-in..."',
+    "        />",
+    "      );",
+    "    }",
+    "",
+    "    return (",
+    "      <TopoloAuthFlowScreen",
+    "        appName={APP_NAME}",
+    "        appId={APP_ID}",
+    "        serviceId={SERVICE_ID}",
+    '        status="error"',
+    '        title="Authentication failed"',
+    "        message={authError || `We could not complete sign-in for ${APP_NAME}.`}",
+    '        actionLabel="Back to sign in"',
+    "        onAction={() => window.location.replace('/login')}",
+    "      />",
+    "    );",
+    "  }",
+    "",
+    "  if (loading) {",
+    "    return (",
+    "      <TopoloLoadingScreen",
+    "        appId={APP_ID}",
+    "        serviceId={SERVICE_ID}",
+    "        appName={APP_NAME}",
+    "        subtitle={`Loading ${APP_NAME}...`}",
+    "      />",
+    "    );",
+    "  }",
+    "",
+    "  if (!user) {",
+    "    if (route.kind === 'login') {",
+    "      return (",
+    "        <LoginPage",
+    "          serviceId={SERVICE_ID}",
+    "          authApiUrl={AUTH_URL}",
+    "          config={LOGIN_CONFIG}",
+    "          isLoading={loginAttempted}",
+    "          onLogin={async (provider) => {",
+    "            setLoginAttempted(true);",
+    "            try {",
+    "              await auth.authClient.login(provider || 'topolo');",
+    "            } catch {",
+    "              setLoginAttempted(false);",
+    "            }",
+    "          }}",
+    "          onPasswordLogin={async (request) => {",
+    "            const result = await auth.authClient.loginWithPassword(request);",
+    "            if (!result.authenticated) {",
+    "              return result;",
+    "            }",
+    "            setUser(result.user ?? null);",
+    "            window.location.replace('/');",
+    "            return undefined;",
+    "          }}",
+    "        />",
+    "      );",
+    "    }",
+    "",
+    "    return (",
+    "      <LandingPage",
+    "        serviceId={SERVICE_ID}",
+    "        authApiUrl={AUTH_URL}",
+    "        config={LANDING_CONFIG}",
+    "        onCTAClick={() => window.location.assign('/login')}",
+    "      />",
+    "    );",
+    "  }",
+    "",
+    "  if (route.kind === 'login') {",
+    "    return (",
+    "      <TopoloLoadingScreen",
+    "        appId={APP_ID}",
+    "        serviceId={SERVICE_ID}",
+    "        appName={APP_NAME}",
+    '        subtitle="Opening your workspace..."',
+    "      />",
+    "    );",
+    "  }",
+    "",
+    "  return (",
+    "    <TopoloAppShell<NavItem>",
+    "      appId={APP_ID}",
+    "      serviceId={SERVICE_ID}",
+    "      appName={APP_NAME}",
+    "      user={shellUser}",
+    '      activeNavItemId="home"',
+    `      navItems={[{ id: 'home', label: '${escapeSingleQuoted(workspaceTitle)}' }]}`,
+    "      onNavItemSelect={() => undefined}",
+    "      eyebrow={APP_NAME}",
+    `      title="${escapeDoubleQuoted(workspaceTitle)}"`,
+    "      authUrl={AUTH_URL}",
+    "      getAccessToken={getAccessToken}",
+    "      onSignOut={async () => {",
+    "        await auth.authClient.logout();",
+    "        window.location.assign('/login');",
+    "      }}",
+    "      commandPlaceholder={`Search ${APP_NAME}`}",
+    "      bugReporterAppName={APP_NAME}",
+    "      enableCommandPalette",
+    "      enableBugReporter",
+    "      showThemeToggle",
+    "    >",
+    '      <div className="topolo-starter-workspace">',
+    '        <section className="topolo-starter-card">',
+    "          <h2>Shared workspace baseline</h2>",
+    "          <p>",
+    "            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.",
+    "          </p>",
+    "        </section>",
+    "      </div>",
+    "    </TopoloAppShell>",
+    "  );",
+    "}",
+    "",
+    "function getRoute(): AppRoute {",
+    "  const pathname = window.location.pathname.replace(/\\/+$/, '') || '/';",
+    "  if (pathname === '/login') return { kind: 'login' };",
+    "  if (pathname === '/auth/callback') return { kind: 'callback' };",
+    "  return { kind: 'root' };",
+    "}",
+    "",
+    "function errorMessage(error: unknown): string {",
+    "  if (error instanceof Error && error.message) return error.message;",
+    "  return 'Unexpected authentication error.';",
+    "}",
+    ""
+  ].join("\n");
+}
+function developerAppTsx(application) {
+  const appName = toTitle(application.name);
+  const defaultClientId = `${toSlug(application.id)}_local_client`;
+  return [
+    "import { useEffect, useMemo, useState } from 'react';",
+    "",
+    "type AuthState = 'ready' | 'missing_client' | 'authorizing' | 'authenticated' | 'error';",
+    "",
+    `const APP_NAME = '${escapeSingleQuoted(appName)}';`,
+    "const AUTH_URL = import.meta.env.VITE_TOPOLO_AUTH_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 || 'identity:read organization:read').trim();",
+    "",
+    "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 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((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);",
+    "        }",
+    "        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. 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 verifier = randomString(64);",
+    "  const challenge = await pkceChallenge(verifier);",
+    "  const state = randomString(32);",
+    "  sessionStorage.setItem(`${CLIENT_ID}:topolo_pkce_verifier`, verifier);",
+    "  sessionStorage.setItem(`${CLIENT_ID}:topolo_oauth_state`, state);",
+    "",
+    "  const authorizeUrl = new URL('/api/developer-oauth/authorize', AUTH_URL);",
+    "  authorizeUrl.searchParams.set('response_type', 'code');",
+    "  authorizeUrl.searchParams.set('client_id', CLIENT_ID);",
+    "  authorizeUrl.searchParams.set('redirect_uri', REDIRECT_URI);",
+    "  authorizeUrl.searchParams.set('scope', REQUESTED_SCOPES);",
+    "  authorizeUrl.searchParams.set('state', state);",
+    "  authorizeUrl.searchParams.set('code_challenge', challenge);",
+    "  authorizeUrl.searchParams.set('code_challenge_method', 'S256');",
+    "  window.location.assign(authorizeUrl.toString());",
+    "}",
+    "",
+    "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.');",
+    "",
+    "  const tokenUrl = new URL('/api/developer-oauth/token', AUTH_URL);",
+    "  const response = await fetch(tokenUrl, {",
+    "    method: 'POST',",
+    "    headers: { 'Content-Type': 'application/json' },",
+    "    body: JSON.stringify({",
+    "      grant_type: 'authorization_code',",
+    "      client_id: CLIENT_ID,",
+    "      code,",
+    "      redirect_uri: REDIRECT_URI,",
+    "      code_verifier: verifier,",
+    "    }),",
+    "  });",
+    "  const payload = await response.json().catch(() => null);",
+    "  if (!response.ok || !payload?.access_token) {",
+    "    throw new Error(payload?.error_description || payload?.error || 'Token exchange failed.');",
+    "  }",
+    "  return payload;",
+    "}",
+    "",
+    "function randomString(length: number): string {",
+    "  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';",
+    "  const bytes = crypto.getRandomValues(new Uint8Array(length));",
+    "  return Array.from(bytes, (byte) => alphabet[byte % alphabet.length]).join('');",
+    "}",
+    "",
+    "async function pkceChallenge(verifier: string): Promise<string> {",
+    "  const data = new TextEncoder().encode(verifier);",
+    "  const digest = await crypto.subtle.digest('SHA-256', data);",
+    "  return base64Url(new Uint8Array(digest));",
+    "}",
+    "",
+    "function base64Url(bytes: Uint8Array): string {",
+    "  let binary = '';",
+    "  for (const byte of bytes) binary += String.fromCharCode(byte);",
+    "  return btoa(binary).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/g, '');",
+    "}",
+    ""
+  ].join("\n");
+}
+function wranglerToml(application, target) {
+  const slug = toSlug(application.id);
+  const workerName = target === "platform" ? `topolo-${slug}` : application.packageName;
+  const routeHost = application.productionUrl ? new URL(application.productionUrl).host : null;
+  const lines = [
+    `name = "${workerName}"`,
+    'main = "src/worker.ts"',
+    `compatibility_date = "${CURRENT_VERIFICATION_DATE}"`,
+    'compatibility_flags = ["nodejs_compat"]'
+  ];
+  if (target === "platform") {
+    lines.push(
+      `account_id = "${CLOUDFLARE_ACCOUNT_ID}"`,
+      "workers_dev = false"
+    );
+  }
+  lines.push(
+    "",
+    "[observability]",
+    "enabled = true",
+    "",
+    "[assets]",
+    'directory = "dist"',
+    'binding = "ASSETS"',
+    'not_found_handling = "single-page-application"',
+    'run_worker_first = ["/api/*"]'
+  );
+  if (target === "platform" && routeHost) {
+    lines.push(
+      "",
+      "[[routes]]",
+      `pattern = "${routeHost}"`,
+      "custom_domain = true"
+    );
+  }
+  lines.push(
+    "",
+    "[vars]",
+    'AUTH_BASE_URL = "https://auth.topolo.app"',
+    `SERVICE_ID = "${application.serviceId ?? application.id}"`,
+    ""
+  );
+  return lines.join("\n");
+}
+function workerTs(application, target, _options) {
+  if (target === "developer") return developerWorkerTs(application);
+  return platformWorkerTs(application);
+}
+function platformWorkerTs(application) {
+  const serviceId = application.serviceId ?? application.id;
+  return [
+    "import { verifyRequest } from '@topolo/auth-middleware';",
+    "",
+    "export interface Env {",
+    "  AUTH_BASE_URL?: string;",
+    "  SERVICE_ID?: string;",
+    "  TOPOLO_SERVICE_API_KEY?: string;",
+    "}",
+    "",
+    "const CLIENT_HEADER = 'topolo-worker-starter';",
+    "",
+    "export default {",
+    "  async fetch(request: Request, env: Env): Promise<Response> {",
+    "    const url = new URL(request.url);",
+    "",
+    "    if (url.pathname === '/api/health') {",
+    "      return json({ ok: true, service: env.SERVICE_ID ?? DEFAULT_SERVICE_ID }, { status: 200 }, request);",
+    "    }",
+    "",
+    "    const auth = await verifyRequest(request, {",
+    "      authBaseUrl: env.AUTH_BASE_URL,",
+    "      serviceId: env.SERVICE_ID ?? DEFAULT_SERVICE_ID,",
+    "      serviceApiKey: env.TOPOLO_SERVICE_API_KEY,",
+    "    });",
+    "",
+    "    if (!auth.ok) {",
+    "      return json({ error: auth.error }, { status: auth.status }, request);",
+    "    }",
+    "",
+    "    if (url.pathname === '/api/bootstrap') {",
+    "      return json({",
+    "        user: auth.user,",
+    "        organization: auth.organization,",
+    "      }, { status: 200 }, request);",
+    "    }",
+    "",
+    "    return json({ error: 'not_found' }, { status: 404 }, request);",
+    "  },",
+    "};",
+    "",
+    `const DEFAULT_SERVICE_ID = '${serviceId}';`,
+    "",
+    "function json(body: unknown, init: ResponseInit, request: Request): Response {",
+    "  const headers = new Headers(init.headers);",
+    "  headers.set('Content-Type', 'application/json');",
+    "  headers.set('X-Topolo-Client', CLIENT_HEADER);",
+    "  headers.set('X-Topolo-Request-Id', request.headers.get('X-Topolo-Request-Id') ?? crypto.randomUUID());",
+    "  return new Response(JSON.stringify(body), { ...init, headers });",
+    "}",
+    ""
+  ].join("\n");
+}
+function developerWorkerTs(application) {
+  const serviceId = application.serviceId ?? application.id;
+  return [
+    "export interface Env {",
+    "  AUTH_BASE_URL?: string;",
+    "  SERVICE_ID?: string;",
+    "}",
+    "",
+    "const CLIENT_HEADER = 'topolo-developer-starter';",
+    `const DEFAULT_SERVICE_ID = '${serviceId}';`,
+    "",
+    "export default {",
+    "  async fetch(request: Request, env: Env): Promise<Response> {",
+    "    const url = new URL(request.url);",
+    "",
+    "    if (url.pathname === '/api/health') {",
+    "      return json({ ok: true, service: env.SERVICE_ID ?? DEFAULT_SERVICE_ID }, { status: 200 }, request);",
+    "    }",
+    "",
+    "    const auth = await verifyTopoloRequest(request, env);",
+    "    if (!auth.ok) {",
+    "      return json({ error: auth.error }, { status: auth.status }, request);",
+    "    }",
+    "",
+    "    if (url.pathname === '/api/bootstrap') {",
+    "      return json({",
+    "        user: auth.user,",
+    "        organization: auth.organization,",
+    "      }, { status: 200 }, request);",
+    "    }",
+    "",
+    "    return json({ error: 'not_found' }, { status: 404 }, request);",
+    "  },",
+    "};",
+    "",
+    "async function verifyTopoloRequest(request: Request, env: Env): Promise<",
+    "  | { ok: true; user: unknown; organization: unknown }",
+    "  | { ok: false; status: number; error: string }",
+    "> {",
+    "  const authHeader = request.headers.get('Authorization') || '';",
+    "  const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : null;",
+    "  if (!token) return { ok: false, status: 401, error: 'Bearer token required' };",
+    "",
+    "  try {",
+    "    const authBaseUrl = env.AUTH_BASE_URL || 'https://auth.topolo.app';",
+    "    const response = await fetch(`${authBaseUrl}/validate`, {",
+    "      method: 'POST',",
+    "      headers: {",
+    "        Authorization: `Bearer ${token}`,",
+    "        'X-Service-ID': env.SERVICE_ID ?? DEFAULT_SERVICE_ID,",
+    "      },",
+    "    });",
+    "",
+    "    const payload = await response.json().catch(() => null);",
+    "    if (!response.ok) return { ok: false, status: 401, error: 'Token validation failed' };",
+    "    const user = payload?.data?.user;",
+    "    if (!user) return { ok: false, status: 401, error: 'Invalid auth response' };",
+    "    return { ok: true, user, organization: payload?.data?.organization ?? null };",
+    "  } catch {",
+    "    return { ok: false, status: 503, error: 'Topolo Auth unavailable' };",
+    "  }",
+    "}",
+    "",
+    "function json(body: unknown, init: ResponseInit, request: Request): Response {",
+    "  const headers = new Headers(init.headers);",
+    "  headers.set('Content-Type', 'application/json');",
+    "  headers.set('X-Topolo-Client', CLIENT_HEADER);",
+    "  headers.set('X-Topolo-Request-Id', request.headers.get('X-Topolo-Request-Id') ?? crypto.randomUUID());",
+    "  return new Response(JSON.stringify(body), { ...init, headers });",
+    "}",
+    ""
+  ].join("\n");
+}
+function cloudcontrolJson(application, options) {
+  const slug = toSlug(application.id);
+  const host = application.productionUrl ? new URL(application.productionUrl).host : `${slug}.topolo.app`;
+  const deployTargets = options.api ? [
+    {
+      kind: "worker",
+      environment: "production",
+      target_name: `topolo-${slug}`,
+      cloudflare_account_id: CLOUDFLARE_ACCOUNT_ID,
+      config_path: "wrangler.toml",
+      build_command: "npm run build",
+      output_dir: "dist",
+      production_branch: "main",
+      healthcheck_path: "/api/health",
+      domains: [host],
+      routes: [host],
+      api_url: application.productionUrl,
+      service_id: application.serviceId
+    }
+  ] : [
+    {
+      kind: "pages",
+      environment: "production",
+      target_name: `topolo-${slug}`,
+      cloudflare_account_id: CLOUDFLARE_ACCOUNT_ID,
+      config_path: null,
+      build_command: "npm run build",
+      output_dir: "dist",
+      production_branch: "main",
+      healthcheck_path: null,
+      domains: [host],
+      routes: [host],
+      api_url: null
+    }
+  ];
+  return `${json({
+    name: `topolo-${slug}`,
+    description: `Canonical documentation for ${toTitle(application.name)} lives in PlatformApplications/TopoloDocs.`,
+    deploy_method: options.api ? "wrangler" : "cloudflare_pages",
+    ci_provider: "github_actions",
+    repo_identity: {
+      provider: "github",
+      owner: "Topolo-io",
+      repo: `topolo-${slug}`,
+      remote_url: `git@github.com:Topolo-io/topolo-${slug}.git`,
+      default_branch: "main"
+    },
+    environments: application.productionUrl ? [
+      {
+        name: "production",
+        url: application.productionUrl,
+        branch: "main",
+        status: "unknown"
+      }
+    ] : [],
+    deploy_targets: deployTargets,
+    resource_bindings: [],
+    ci_workflows: [
+      {
+        provider: "github_actions",
+        workflow_name: "topolo-conformance.yml",
+        path: ".github/workflows/topolo-conformance.yml",
+        branch: null,
+        required: true
+      }
+    ],
+    ci_targets: [],
+    tags: ["application", "cloudflare", "typescript"],
+    cloudflare_account_id: CLOUDFLARE_ACCOUNT_ID
+  })}
+`;
+}
+function systemJson(application, options) {
+  const slug = toSlug(application.id);
+  const suiteLabel = options.audience === "personal" ? "personal" : "platform";
+  const summaryLabel = options.audience === "personal" ? "first-party Topolo personal application" : "first-party Topolo platform application";
+  return `${json({
+    id: `topolo-${slug}`,
+    name: toTitle(application.name),
+    slug: `topolo-${slug}`,
+    kind: "application",
+    summary: `${toTitle(application.name)} is a ${summaryLabel} scaffolded on shared Auth, UI Kit, CloudControl, and conformance contracts.`,
+    lifecycle: "planned",
+    last_verified: CURRENT_VERIFICATION_DATE,
+    owners: ["platform-engineering"],
+    repo_paths: [`PlatformApplications/${application.appDir}`],
+    service_ids: options.api && application.serviceId ? [application.serviceId] : [],
+    visibility: "internal",
+    api_contract: {
+      type: options.api ? "worker" : "none",
+      source: options.api ? `PlatformApplications/${application.appDir}/src/worker.ts` : `PlatformApplications/${application.appDir}/src/App.tsx`,
+      notes: options.api ? "Protected Worker routes validate Topolo Auth credentials and derive organization context from the credential. The browser baseline starts on shared landing and login routes, completes auth on /auth/callback, and dedupes React when linked Topolo packages are installed locally." : "Browser-only application surface using shared Topolo Auth landing/login/callback routes, shared shell packages, and React runtime dedupe."
+    },
+    primary_hosts: application.productionUrl ? [application.productionUrl] : [],
+    doc_paths: [`internal/apps/${slug}`, `public/applications/${slug}`],
+    security_assurance: {
+      risk_tier: "internal",
+      auth_boundary: "Topolo Auth through @topolo/auth-client for browser sessions and @topolo/auth-middleware for Worker requests.",
+      tenant_isolation: options.tenancy === "household" ? "household_scoped" : "organization_scoped",
+      external_inputs: ["browser", ...options.api ? ["api"] : []],
+      sensitive_data: ["identity", "org_data"],
+      security_review_status: "not_started",
+      last_security_review: CURRENT_VERIFICATION_DATE,
+      pentest_status: "not_started",
+      evidence_doc: `internal/apps/${slug}`
+    },
+    dependencies: options.audience === "personal" ? ["topolo-auth"] : ["topolo-auth", "topolo-platform"],
+    tags: ["application", "cloudflare", "typescript", suiteLabel]
+  })}
+`;
+}
+function internalDocs(application, options) {
+  const slug = toSlug(application.id);
+  const title = toTitle(application.name);
+  const suiteLabel = options.audience === "personal" ? "personal" : "platform";
+  const tenantLabel = options.tenancy === "household" ? "household" : "organization";
+  return [
+    "---",
+    `title: "${escapeFrontmatter(title)} Handbook"`,
+    `summary: "Internal handbook for ${escapeFrontmatter(title)}."`,
+    'owners: ["platform-engineering"]',
+    'status: "planned"',
+    `last_verified: "${CURRENT_VERIFICATION_DATE}"`,
+    "source_repos:",
+    `  - "PlatformApplications/${application.appDir}"`,
+    '  - "PlatformApplications/TopoloDocs"',
+    'audience: "internal"',
+    "tags:",
+    `  - "${slug}"`,
+    '  - "application"',
+    "system_ids:",
+    `  - "topolo-${slug}"`,
+    '  - "topolo-auth"',
+    "related_docs:",
+    `  - "/systems/topolo-${slug}"`,
+    `  - "/applications/${slug}"`,
+    "---",
+    "",
+    "## What It Is",
+    "",
+    `${title} is a first-party Topolo ${suiteLabel} application scaffolded from the shared first-party application contract.`,
+    "",
+    "## Architecture",
+    "",
+    "The generated browser surface uses `@topolo/ui-kit` for the shared landing page, shared login page, auth callback state, and shared signed shell. `vite.config.ts` includes the standard React plugin plus React runtime dedupe so linked Topolo packages resolve a single browser React runtime.",
+    "",
+    "## Runtime Surfaces",
+    "",
+    `- \`PlatformApplications/${application.appDir}/src/App.tsx\``,
+    "- public landing route: `/`",
+    "- public sign-in route: `/login`",
+    "- auth callback route: `/auth/callback`",
+    ...options.api ? [`- \`PlatformApplications/${application.appDir}/src/worker.ts\``] : [],
+    `- \`PlatformApplications/${application.appDir}/topolo.cloudcontrol.json\``,
+    ...options.api && application.serviceId ? [`- \`PlatformApplications/TopoloAuth/catalog/service-manifests/${application.serviceId}.json\``] : [],
+    "",
+    "## API Reference",
+    "",
+    options.api ? "The generated API baseline exposes `/api/health` and `/api/bootstrap`. `/api/bootstrap` requires Topolo Auth validation and returns the verified user plus organization context." : "This generated baseline is browser-only and does not expose a callable API service.",
+    "",
+    "## Auth and Permissions",
+    "",
+    options.api ? `Browser sessions and Worker requests must be validated through Topolo Auth under service id \`${application.serviceId}\`. Worker routes derive organization context from the verified credential.` : "Browser sessions must be established through Topolo Auth and rendered inside the shared Topolo shell.",
+    "",
+    "## Data Ownership",
+    "",
+    `The generated scaffold stores no durable application data yet. Future domain tables, Durable Objects, queues, KV namespaces, R2 buckets, and external provider records must be scoped to the authenticated ${tenantLabel} context at the backend boundary.`,
+    "",
+    "## Deployments",
+    "",
+    application.productionUrl ? `The planned production host is \`${application.productionUrl}\`. Deployment metadata starts in \`topolo.cloudcontrol.json\` and must stay aligned with CloudControl before live release.` : "No production host has been assigned yet. Deployment metadata must be completed before live release.",
+    "",
+    "## Failure Modes",
+    "",
+    "- Auth service registration drifts from the generated Worker `SERVICE_ID`.",
+    "- CloudControl metadata does not match the eventual Cloudflare project or route.",
+    "- linked Topolo packages resolve a second React runtime and the browser shell renders blank instead of mounting the shared surfaces.",
+    "- Domain data is added without an organization-scoped backend boundary.",
+    "",
+    "## Debugging",
+    "",
+    "- run `npm run typecheck` and `npm run build` in the application directory",
+    "- run `topolo apps audit <app> --local --repo-root /Users/ashes/Projects/topolo --fail-on needs_review --json` after SDK catalog registration",
+    "- inspect `topolo.cloudcontrol.json` before deployment changes",
+    ...options.api && application.serviceId ? [`- inspect \`PlatformApplications/TopoloAuth/catalog/service-manifests/${application.serviceId}.json\` when permission grants fail`] : [],
+    "",
+    "## Change Log / Verification",
+    "",
+    `- Scaffold generated on ${CURRENT_VERIFICATION_DATE} from \`${options.portfolio ? "topolo platform apps scaffold" : "topolo apps scaffold"}\`.`,
+    "- `npm run typecheck`",
+    "- `npm run build`",
+    "- `npm run validate` in TopoloDocs",
+    ""
+  ].join("\n");
+}
+function publicDocs(application, options) {
+  const slug = toSlug(application.id);
+  const title = toTitle(application.name);
+  const suiteLabel = options.audience === "personal" ? "personal" : "business";
+  const tenantLabel = options.tenancy === "household" ? "household" : "organization";
+  return [
+    "---",
+    `title: "${escapeFrontmatter(title)}"`,
+    `summary: "Public overview of ${escapeFrontmatter(title)} in the Topolo application suite."`,
+    'owners: ["platform-engineering"]',
+    'status: "planned"',
+    `last_verified: "${CURRENT_VERIFICATION_DATE}"`,
+    "source_repos:",
+    `  - "PlatformApplications/${application.appDir}"`,
+    'audience: "public"',
+    "tags:",
+    `  - "${slug}"`,
+    '  - "application"',
+    "system_ids:",
+    `  - "topolo-${slug}"`,
+    '  - "topolo-auth"',
+    "related_docs:",
+    `  - "/systems/topolo-${slug}"`,
+    `  - "/internal/apps/${slug}"`,
+    "---",
+    "",
+    "## What It Is",
+    "",
+    `${title} is part of the Topolo ${suiteLabel} application suite.`,
+    "",
+    "## Architecture",
+    "",
+    "The application uses the shared Topolo landing page, shared login page, auth callback handling, and shared Topolo shell from the outset.",
+    "",
+    "## Runtime Surfaces",
+    "",
+    application.productionUrl ? `The planned production host is \`${application.productionUrl}\`, with public entry at \`/\`, sign-in at \`/login\`, and callback completion at \`/auth/callback\`.` : "The production host has not been assigned yet.",
+    "",
+    "## API Reference",
+    "",
+    options.api ? "The generated API baseline exposes authenticated workspace routes under `/api/*` and validates requests through Topolo Auth." : "This generated baseline is browser-only and does not expose a callable API service.",
+    "",
+    "## Auth and Permissions",
+    "",
+    options.api && application.serviceId ? `Signed browser and API requests use Topolo Auth through service id \`${application.serviceId}\`.` : "Signed browser requests use Topolo Auth and the shared Topolo shell.",
+    "",
+    "## Data Ownership",
+    "",
+    `The generated baseline has no durable domain data yet. Future data must be ${tenantLabel}-scoped at the backend boundary.`,
+    "",
+    "## Deployments",
+    "",
+    application.productionUrl ? `The planned production host is \`${application.productionUrl}\`.` : "The production host has not been assigned yet.",
+    "",
+    "## Failure Modes",
+    "",
+    "- service registration and app routing can drift while the product is still planned",
+    "- organization-scoped data models are not implemented until domain work begins",
+    "",
+    "## Debugging",
+    "",
+    "- use the matching internal handbook for operational details",
+    "- verify the system registry entry before deployment or service-registration changes",
+    "",
+    "## Change Log / Verification",
+    "",
+    `- Scaffold generated on ${CURRENT_VERIFICATION_DATE} from \`topolo apps scaffold\`.`,
+    ""
+  ].join("\n");
+}
+function serviceManifestJson(application, options) {
+  const slug = toSlug(application.id);
+  const title = toTitle(application.name);
+  const permissionPrefix = application.id.replace(/[^a-z0-9_]/g, "_");
+  const resourceLabel = options.tenancy === "household" ? "household" : "workspace";
+  return `${json({
+    serviceId: application.serviceId,
+    systems: [
+      {
+        systemId: `topolo-${slug}`,
+        name: title,
+        repoPaths: [`PlatformApplications/${application.appDir}`],
+        docPaths: [`applications/${slug}`, `internal/apps/${slug}`]
+      }
+    ],
+    permissions: [
+      {
+        id: `perm_${permissionPrefix}_workspace_read`,
+        name: "workspace:read",
+        description: `View ${title} ${resourceLabel} data`,
+        resourcePattern: null
+      },
+      {
+        id: `perm_${permissionPrefix}_workspace_write`,
+        name: "workspace:write",
+        description: `Manage ${title} ${resourceLabel} data`,
+        resourcePattern: null
+      }
+    ],
+    apiKeyScopes: [
+      {
+        id: `aks_${permissionPrefix}_workspace_read`,
+        name: "workspace.read",
+        description: `View ${title} ${resourceLabel} data`,
+        resourcePattern: null
+      },
+      {
+        id: `aks_${permissionPrefix}_workspace_write`,
+        name: "workspace.write",
+        description: `Manage ${title} ${resourceLabel} data`,
+        resourcePattern: null
+      }
+    ],
+    roleBundles: {
+      admin: ["workspace:read", "workspace:write"],
+      member: ["workspace:read", "workspace:write"],
+      guest: ["workspace:read"],
+      super_admin: ["workspace:read", "workspace:write"]
+    }
+  })}
+`;
+}
+function developerManifest(application, options) {
+  return `${json({
+    schema: "https://topolo.app/schemas/topolo-app-manifest.v1.json",
+    id: application.id,
+    name: toTitle(application.name),
+    type: "third_party",
+    audience: options.audience,
+    tenancy: options.tenancy,
+    distribution_model: options.distributionModel,
+    surface_model: options.surfaceModel,
+    container_app_id: options.containerAppId,
+    package_name: application.packageName,
+    service_id: options.api ? application.serviceId : null,
+    auth: {
+      provider: "topolo",
+      flow: "authorization_code_pkce",
+      callback_path: "/auth/callback",
+      local_callback_url: "http://localhost:5173/auth/callback",
+      production_callback_url: application.productionUrl ? `${application.productionUrl.replace(/\/$/, "")}/auth/callback` : null,
+      requested_scopes: options.api ? ["identity:read", "organization:read", `${application.id}:read`] : ["identity:read", "organization:read"]
+    },
+    runtime: {
+      browser: true,
+      api: options.api
+    }
+  })}
+`;
+}
+function envExample(application) {
+  return [
+    "VITE_TOPOLO_AUTH_URL=https://auth.topolo.app",
+    "VITE_TOPOLO_CLIENT_ID=",
+    "VITE_TOPOLO_REDIRECT_URI=http://localhost:5173/auth/callback",
+    "VITE_TOPOLO_SCOPES=identity:read organization:read",
+    `VITE_TOPOLO_SERVICE_ID=${application.serviceId ?? application.id}`,
+    ""
+  ].join("\n");
+}
+function normalizeTarget(value) {
+  if (!value) return "platform";
+  if (value === "platform" || value === "developer") return value;
+  throw new Error("Invalid scaffold target. Use platform or developer.");
+}
+function normalizePortfolio(value) {
+  if (!value) return "platform";
+  if (value === "platform" || value === "personal") return value;
+  throw new Error("Invalid scaffold portfolio. Use platform or personal.");
+}
+function normalizeAudience(value, portfolio) {
+  if (!value) {
+    return portfolio === "personal" ? "personal" : "business";
+  }
+  if (value === "business" || value === "personal") {
+    return value;
+  }
+  throw new Error("Invalid scaffold audience. Use business or personal.");
+}
+function normalizeTenancy(value, audience) {
+  const resolved = value ?? (audience === "personal" ? "household" : "organization");
+  if (resolved !== "organization" && resolved !== "household") {
+    throw new Error("Invalid scaffold tenancy. Use organization or household.");
+  }
+  if (audience === "business" && resolved !== "organization") {
+    throw new Error("Business scaffolds must use organization tenancy.");
+  }
+  if (audience === "personal" && resolved !== "household") {
+    throw new Error("Personal scaffolds must use household tenancy.");
+  }
+  return resolved;
+}
+function normalizeSurfaceModel(value) {
+  if (!value) return "web_app";
+  if (value === "web_app" || value === "mobile_container" || value === "mobile_module" || value === "messaging_surface") {
+    return value;
+  }
+  throw new Error(
+    "Invalid scaffold surface model. Use web_app, mobile_container, mobile_module, or messaging_surface."
+  );
+}
+function normalizeContainerAppId(value, surfaceModel) {
+  const trimmed = String(value || "").trim();
+  if (surfaceModel === "mobile_module") {
+    if (!trimmed) {
+      throw new Error("Mobile-module scaffolds require --container-app-id.");
+    }
+    return trimmed;
+  }
+  return trimmed || null;
+}
 function normalizeApplicationId(application) {
-  const id = application.trim().toLowerCase();
-  if (Object.prototype.hasOwnProperty.call(APPLICATIONS, id)) {
-    return id;
+  const raw = application.trim().toLowerCase();
+  const normalized = raw.replace(/-/g, "_");
+  if (Object.prototype.hasOwnProperty.call(APPLICATIONS, raw)) {
+    return raw;
   }
-  if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(id)) {
-    throw new Error("Application id must be kebab-case using lowercase letters, numbers, and hyphens.");
+  if (Object.prototype.hasOwnProperty.call(APPLICATIONS, normalized)) {
+    return normalized;
   }
-  return id;
+  if (/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(raw) || /^[a-z0-9](?:[a-z0-9_]*[a-z0-9])?$/.test(raw)) {
+    return normalized;
+  }
+  throw new Error(
+    "Application id must be kebab-case or snake_case using lowercase letters, numbers, hyphens, and underscores."
+  );
+}
+function toSlug(value) {
+  return value.replace(/_/g, "-");
 }
 function toPascalCase(value) {
-  return value.split("-").filter(Boolean).map((part) => part.slice(0, 1).toUpperCase() + part.slice(1)).join("");
+  return value.split(/[-_]/).filter(Boolean).map((part) => part.slice(0, 1).toUpperCase() + part.slice(1)).join("");
+}
+function toTitle(value) {
+  return value.replace(/^topolo[-_\s]*/i, "Topolo ").split(/[-_\s]+/).filter(Boolean).map((part) => part.slice(0, 1).toUpperCase() + part.slice(1)).join(" ");
+}
+function json(value) {
+  return JSON.stringify(value, null, 2);
+}
+async function pathExists(path2) {
+  try {
+    await access(path2, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function resolveInside(root, filePath) {
+  const resolved = resolve(root, filePath);
+  const relativePath = relative(root, resolved);
+  if (relativePath.startsWith("..") || relativePath === "" || relativePath.startsWith("/")) {
+    throw new Error(`Scaffold file path escapes the target root: ${filePath}`);
+  }
+  return resolved;
+}
+function escapeHtml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function escapeSingleQuoted(value) {
+  return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+function escapeDoubleQuoted(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function escapeFrontmatter(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+// src/commands/app-scaffold-provision.ts
+var DEFAULT_DEVELOPERS_ORIGIN = "https://developers.topolo.app";
+var DEVELOPERS_SERVICE_ID = "svc_topolo_developers";
+async function provisionApplicationScaffold(payload) {
+  if (!payload.application.productionUrl) {
+    throw new Error(
+      "Scaffold provisioning requires a browser-capable application with a production URL."
+    );
+  }
+  if (payload.target === "platform" && !payload.application.serviceId) {
+    throw new Error(
+      "Platform scaffold provisioning requires a service id. Re-run without --no-api or pass --service."
+    );
+  }
+  const credential = await refreshCredentialIfNeeded();
+  if (!credential) {
+    throw new Error(
+      "topolo apps scaffold --provision requires an authenticated Topolo session. Run `topolo auth login` first."
+    );
+  }
+  const client = await buildClient();
+  if (!client) {
+    throw new Error(
+      "Could not build a Topolo client for scaffold provisioning. Run `topolo auth login` first."
+    );
+  }
+  const identity = await client.client.introspect();
+  const config = await readConfig();
+  const serviceUrls = resolveServiceUrls(config.serviceUrls) ?? {};
+  const developersOrigin = sanitizeOrigin(serviceUrls.developers ?? DEFAULT_DEVELOPERS_ORIGIN);
+  const endpoint = payload.target === "platform" ? "/api/developer-console/admin/first-party-app-scaffolds" : "/api/developer-console/apps/scaffold";
+  const headers = new Headers({
+    "Content-Type": "application/json",
+    "X-Service-ID": DEVELOPERS_SERVICE_ID,
+    "X-Topolo-Client": `topolo-cli/${CLI_VERSION}`
+  });
+  const agentName = resolveAgentName(config.agentName);
+  if (agentName) {
+    headers.set("X-Topolo-Agent", agentName);
+  }
+  if (credential.kind === "api_key") {
+    headers.set("X-Api-Key", credential.apiKey);
+  } else {
+    headers.set("Authorization", `Bearer ${credential.accessToken}`);
+  }
+  const response = await fetch(`${developersOrigin}${endpoint}`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(buildProvisioningRequest(payload))
+  });
+  const envelope = await response.json().catch(() => null);
+  if (!response.ok || !envelope?.success || !envelope.data) {
+    throw new Error(
+      resolveProvisioningError(envelope, response.status, payload.target)
+    );
+  }
+  const app = pickRecord(envelope.data.app);
+  const service = pickRecord(envelope.data.service);
+  const authConfig = pickRecord(envelope.data.authConfig);
+  if (!app) {
+    throw new Error("Developers provisioning did not return an app record.");
+  }
+  const appId = readRequiredString(app.id, "Developers provisioning did not return an app id.");
+  return {
+    target: payload.target,
+    actor: {
+      kind: identity.kind,
+      userId: identity.user.id,
+      email: identity.user.email,
+      role: identity.user.role,
+      organizationId: identity.organization?.id ?? null,
+      organizationSlug: identity.organization?.slug ?? null
+    },
+    developersOrigin,
+    developersApp: {
+      id: appId,
+      slug: readString(app.slug),
+      listingStatus: readString(app.listingStatus),
+      organizationId: readString(app.organizationId)
+    },
+    authService: service ? {
+      id: readRequiredString(
+        service.id,
+        "Auth registration did not return a service id."
+      ),
+      status: readString(service.status),
+      baseUrl: readString(service.base_url) ?? readString(service.baseUrl)
+    } : null,
+    authConfig: authConfig ? {
+      login: authConfig.login === true,
+      landing: authConfig.landing === true,
+      appUi: authConfig.appUi === true
+    } : null
+  };
+}
+function buildProvisioningRequest(payload) {
+  return {
+    target: payload.target,
+    ownerType: payload.ownerType,
+    portfolio: payload.portfolio,
+    audience: payload.audience,
+    tenancy: payload.tenancy,
+    surfaceModel: payload.surfaceModel,
+    containerAppId: payload.containerAppId,
+    distributionModel: payload.distributionModel,
+    applicationId: payload.application.id,
+    appDir: payload.application.appDir,
+    packageName: payload.application.packageName,
+    name: payload.application.name,
+    productionUrl: payload.application.productionUrl,
+    serviceId: payload.application.serviceId
+  };
+}
+function resolveProvisioningError(envelope, status, target) {
+  const message = (typeof envelope?.error === "string" ? envelope.error : envelope?.error?.message) || envelope?.message || `Scaffold provisioning failed with status ${status}.`;
+  if (status === 401 || status === 403) {
+    if (target === "platform") {
+      return `${message} Platform scaffold provisioning requires a Topolo platform-admin session with Developers commerce access.`;
+    }
+    return `${message} Developer scaffold provisioning requires a signed-in Topolo developer workspace session.`;
+  }
+  return message;
+}
+function sanitizeOrigin(value) {
+  return value.replace(/\/+$/, "");
+}
+function pickRecord(value) {
+  return value && typeof value === "object" ? value : null;
+}
+function readString(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+function readRequiredString(value, message) {
+  const resolved = readString(value);
+  if (!resolved) {
+    throw new Error(message);
+  }
+  return resolved;
 }
 
 // src/commands/apps.ts
@@ -2979,21 +4689,46 @@ function registerAppsCommand(program2) {
     }
   });
   apps.command("scaffold <application>").description(
-    "Generate the required Topolo new-application scaffold, including a conformance workflow."
-  ).option("--json", "Output JSON").option("--no-json", "Output human-readable checklist").option("--app-dir <path>", "Application directory under PlatformApplications").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 service id for API-backed apps").option("--no-api", "Do not include API/service requirements").option("--no-browser", "Do not include browser-shell requirements").option("--workflow-only", "Output only the generated GitHub Actions workflow in human mode").action((application, opts) => {
+    "Generate a third-party Topolo application scaffold for business or personal/household use."
+  ).option("--json", "Output JSON").option("--no-json", "Output human-readable checklist").option("--app-dir <path>", "Application directory under PlatformApplications").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 service id for API-backed apps").option("--audience <audience>", "Developer app audience: business or personal").option("--tenancy <tenancy>", "Developer app tenancy: organization or household").option(
+    "--surface-model <surfaceModel>",
+    "Developer app 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("--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 API/service files for developer scaffolds").option("--no-api", "Do not include API/service requirements").option("--no-browser", "Do not include browser-shell requirements").option(
+    "--provision",
+    "Provision the generated app into the current Topolo developer workspace using the authenticated session"
+  ).action(async (application, opts) => {
     const mode = opts.json === false || process.argv.includes("--no-json") ? "pretty" : resolveOutputMode(opts.json);
     try {
+      const api = resolveScaffoldApiOption(opts.api, opts.withApi);
       const payload = applicationScaffoldPayload(application, {
         appDir: opts.appDir,
         name: opts.name,
         packageName: opts.packageName,
         productionUrl: opts.productionUrl,
         service: opts.service,
-        api: opts.api,
-        browser: opts.browser
+        api,
+        browser: opts.browser,
+        target: "developer",
+        audience: resolveScaffoldAudience(opts.audience),
+        tenancy: resolveScaffoldTenancy(opts.tenancy),
+        surfaceModel: resolveScaffoldSurfaceModel(opts.surfaceModel),
+        containerAppId: opts.containerAppId
       });
-      const output = opts.workflowOnly ? { application: payload.application, ciWorkflowPath: payload.ciWorkflowPath, ciWorkflow: payload.ciWorkflow } : payload;
-      emit(output, mode, () => opts.workflowOnly ? payload.ciWorkflow : formatScaffold(payload));
+      if (opts.provision && !opts.write) {
+        throw new Error("--provision requires --write so remote developer records match written scaffold files.");
+      }
+      const writeResult = opts.write ? await writeApplicationScaffold(payload, { repoRoot: opts.repoRoot, force: opts.force }) : null;
+      const provisionResult = opts.provision ? await provisionApplicationScaffold(payload) : null;
+      const output = {
+        ...payload,
+        ...writeResult ? { write: writeResult } : {},
+        ...provisionResult ? { provision: provisionResult } : {}
+      };
+      emit(
+        output,
+        mode,
+        () => formatScaffold(payload, writeResult, provisionResult)
+      );
     } catch (err) {
       fail(err, mode);
     }
@@ -3154,9 +4889,17 @@ function formatAudit(payload) {
   }
   return lines.join("\n");
 }
-function formatScaffold(payload) {
+function formatScaffold(payload, writeResult = null, provisionResult = null) {
   const lines = [
     `Version: ${payload.version}`,
+    `Target: ${payload.target}`,
+    `Owner: ${payload.ownerType}`,
+    `Audience: ${payload.audience}`,
+    `Tenancy: ${payload.tenancy}`,
+    `Portfolio: ${payload.portfolio ?? "-"}`,
+    `Surface: ${payload.surfaceModel}`,
+    `Container: ${payload.containerAppId ?? "-"}`,
+    `Distribution: ${payload.distributionModel}`,
     `Application: ${payload.application.id}`,
     `Directory: ${payload.application.appDir}`,
     `Package: ${payload.application.packageName}`,
@@ -3177,9 +4920,72 @@ function formatScaffold(payload) {
   for (const command of payload.commands) {
     lines.push(`  - ${command}`);
   }
-  lines.push(`CI workflow: ${payload.ciWorkflowPath}`);
+  lines.push(`CI workflow: ${payload.ciWorkflowPath ?? "-"}`);
+  if (writeResult) {
+    lines.push(`Written root: ${writeResult.root}`);
+    lines.push("Written files:");
+    for (const file of writeResult.files) {
+      lines.push(`  - ${file.status}: ${file.path}`);
+    }
+  }
+  if (provisionResult) {
+    lines.push("Provisioning:");
+    lines.push(`  - target: ${provisionResult.target}`);
+    lines.push(
+      `  - actor: ${provisionResult.actor.email} (${provisionResult.actor.role}, org=${provisionResult.actor.organizationSlug ?? provisionResult.actor.organizationId ?? "-"})`
+    );
+    lines.push(`  - developers origin: ${provisionResult.developersOrigin}`);
+    lines.push(
+      `  - developers app: ${provisionResult.developersApp.id} (listing=${provisionResult.developersApp.listingStatus ?? "-"}, org=${provisionResult.developersApp.organizationId ?? "-"})`
+    );
+    if (provisionResult.authService) {
+      lines.push(
+        `  - auth service: ${provisionResult.authService.id} (status=${provisionResult.authService.status ?? "-"}, url=${provisionResult.authService.baseUrl ?? "-"})`
+      );
+    }
+    if (provisionResult.authConfig) {
+      lines.push(
+        `  - auth config: login=${provisionResult.authConfig.login} landing=${provisionResult.authConfig.landing} app_ui=${provisionResult.authConfig.appUi}`
+      );
+    }
+  }
   return lines.join("\n");
 }
+function resolveScaffoldAudience(value) {
+  if (!value) return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "business" || normalized === "personal") {
+    return normalized;
+  }
+  throw new Error("Invalid --audience value. Use business or personal.");
+}
+function resolveScaffoldTenancy(value) {
+  if (!value) return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "organization" || normalized === "household") {
+    return normalized;
+  }
+  throw new Error("Invalid --tenancy value. Use organization or household.");
+}
+function resolveScaffoldSurfaceModel(value) {
+  if (!value) return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "web_app" || normalized === "mobile_container" || normalized === "mobile_module" || normalized === "messaging_surface") {
+    return normalized;
+  }
+  throw new Error(
+    "Invalid --surface-model value. Use web_app, mobile_container, mobile_module, or messaging_surface."
+  );
+}
+function resolveScaffoldApiOption(api, withApi) {
+  const noApi = process.argv.includes("--no-api");
+  if (withApi && noApi) {
+    throw new Error("--with-api cannot be combined with --no-api.");
+  }
+  if (withApi) return true;
+  if (noApi || api === false) return false;
+  return void 0;
+}
 function normalizeFailOn(value) {
   const normalized = value.trim().toLowerCase().replace(/-/g, "_");
   if (normalized === "missing" || normalized === "needs_review" || normalized === "partial") {
@@ -3193,6 +4999,98 @@ function statusesAtOrWorse(threshold) {
   return ["missing", "needs_review", "partial"];
 }
 
+// src/commands/platform.ts
+function registerPlatformCommand(program2) {
+  const platform3 = program2.command("platform").description("Internal Topolo first-party platform and personal app commands");
+  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 PlatformApplications").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 service 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("--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("--workflow-only", "Output only the generated GitHub Actions workflow in human mode").action(async (application, opts) => {
+    const mode = opts.json === false || process.argv.includes("--no-json") ? "pretty" : resolveOutputMode(opts.json);
+    try {
+      await requirePlatformAdminSession();
+      if (opts.workflowOnly && opts.write) {
+        throw new Error("--workflow-only cannot be used with --write.");
+      }
+      const api = resolveScaffoldApiOption(opts.api, opts.withApi);
+      const payload = applicationScaffoldPayload(application, {
+        appDir: opts.appDir,
+        name: opts.name,
+        packageName: opts.packageName,
+        productionUrl: opts.productionUrl,
+        service: opts.service,
+        api,
+        browser: opts.browser,
+        target: "platform",
+        portfolio: resolvePlatformPortfolio(opts.portfolio),
+        surfaceModel: resolvePlatformSurfaceModel(opts.surfaceModel),
+        containerAppId: opts.containerAppId
+      });
+      if (opts.workflowOnly && !payload.ciWorkflow) {
+        throw new Error("--workflow-only is only available for first-party scaffolds.");
+      }
+      if (opts.provision && !opts.write) {
+        throw new Error("--provision requires --write so remote first-party records match written scaffold files.");
+      }
+      const writeResult = opts.write ? await writeApplicationScaffold(payload, { repoRoot: opts.repoRoot, force: opts.force }) : null;
+      const provisionResult = opts.provision ? await provisionApplicationScaffold(payload) : null;
+      const output = opts.workflowOnly ? { application: payload.application, ciWorkflowPath: payload.ciWorkflowPath, ciWorkflow: payload.ciWorkflow } : {
+        ...payload,
+        ...writeResult ? { write: writeResult } : {},
+        ...provisionResult ? { provision: provisionResult } : {}
+      };
+      emit(
+        output,
+        mode,
+        () => opts.workflowOnly ? payload.ciWorkflow ?? "" : formatScaffold(payload, writeResult, provisionResult)
+      );
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+}
+function resolvePlatformPortfolio(value) {
+  if (!value) return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "platform" || normalized === "personal") {
+    return normalized;
+  }
+  throw new Error("Invalid --portfolio value. Use platform or personal.");
+}
+function resolvePlatformSurfaceModel(value) {
+  if (!value) return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "web_app" || normalized === "mobile_container" || normalized === "mobile_module" || normalized === "messaging_surface") {
+    return normalized;
+  }
+  throw new Error(
+    "Invalid --surface-model value. Use web_app, mobile_container, mobile_module, or messaging_surface."
+  );
+}
+function isPlatformAdminIdentity(identity) {
+  return String(identity?.user?.role || "").trim().toLowerCase() === "super_admin" && String(identity?.organization?.slug || "").trim().toLowerCase() === "admin";
+}
+async function requirePlatformAdminSession() {
+  const client = await buildClient();
+  if (!client) {
+    throw new Error(
+      "`topolo platform ...` requires an authenticated Topolo platform-admin session. Run `topolo auth login` first."
+    );
+  }
+  const identity = await client.client.introspect();
+  if (!isPlatformAdminIdentity(identity)) {
+    throw new Error(
+      "`topolo platform ...` is restricted to Topolo platform admins in the Auth `admin` organization."
+    );
+  }
+}
+
 // src/commands/services.ts
 function registerServicesCommand(program2) {
   program2.command("services").description("List every Topolo service the SDK can route to").option("--json", "Output JSON", true).option("--no-json", "Output human-readable table").action((opts) => {
@@ -3231,13 +5129,14 @@ function formatRows2(rows) {
 // src/index.ts
 var program = new Command();
 program.name("topolo").description(
-  "Topolo platform CLI. Every command is scoped to the authenticated organization \u2014 there is no way to target a different org."
+  "Topolo CLI. Public commands are scoped to the authenticated organization or developer workspace, and first-party Topolo scaffolding lives under the internal `topolo platform` namespace."
 ).version(CLI_VERSION);
 registerAuthCommands(program);
 registerWhoamiCommand(program);
 registerCrmCommands(program);
 registerApiCommand(program);
 registerAppsCommand(program);
+registerPlatformCommand(program);
 registerServicesCommand(program);
 program.parseAsync(process.argv).catch((err) => {
   process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}