@topolo/cli 0.1.10 → 0.1.11

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
+// ../packages/topolo-sdk/dist/index.js
 function applyAuthHeaders(headers, credential) {
   if (credential.kind === "api_key") {
     headers.set("X-Api-Key", credential.apiKey);
@@ -67,14 +67,20 @@ var TopoloHttpError = class extends TopoloSdkError {
 var SERVICES = {
   agent: "https://topolo-agent-worker.topolo.workers.dev",
   auth: "https://auth.topolo.app",
+  books: "https://books.topolo.app",
   bugfix: "https://bugfix.topolo.app",
   bytes: "https://r2-media-manager-worker.topolo.workers.dev",
   calendar: "https://calendar.topolo.app",
   chat: "https://chat.topolo.app",
   commerce: "https://topolo-commerce-api.topolo.workers.dev",
   crm: "https://crm-api.topolo.app",
+  customer_success: "https://customer-success.topolo.app",
   feed: "https://topolo-feed-api.topolo.app",
+  flow: "https://flow.topolo.app",
   forecast: "https://forecast-worker-production.topolo.workers.dev",
+  forms: "https://forms.topolo.app",
+  insights: "https://insights.topolo.app",
+  inventory: "https://inventory.topolo.app",
   learn: "https://topololearn-api.topolo.workers.dev",
   mail: "https://mail.topolo.app",
   mdm: "https://topolo-mdm-api.topolo.app",
@@ -82,16 +88,30 @@ var SERVICES = {
   nexus: "https://topolo-nexus-gateway.topolo.workers.dev",
   one: "https://topoloone-worker.topolo.workers.dev",
   pay: "https://topolo-pay.topolo.workers.dev",
+  people: "https://people.topolo.app",
   "quro.api": "https://api.ol0.me",
   "quro.redirect": "https://ol0.me",
   roadmapper: "https://roadmapper-api.topolo.app",
+  sign: "https://sign.topolo.app",
   social_studio: "https://topolo-social-studio-api.topolo.workers.dev",
   socialize: "https://socialize-prod-api.topolo.workers.dev",
   support: "https://support.topolo.app",
+  survey: "https://survey.topolo.app",
+  voice: "https://voice.topolo.app",
   web: "https://web-api.topolo.app"
 };
 var PLATFORM_SERVICE_IDS = {
-  crm: "srv_iCwM4jGXcwlj"
+  books: "srv_topolo_books",
+  crm: "srv_iCwM4jGXcwlj",
+  customer_success: "srv_topolo_customer_success",
+  flow: "srv_topolo_flow",
+  forms: "srv_topolo_forms",
+  insights: "srv_topolo_insights",
+  inventory: "srv_topolo_inventory",
+  people: "srv_topolo_people",
+  sign: "srv_topolo_sign",
+  survey: "srv_topolo_survey",
+  voice: "srv_topolo_voice"
 };
 var APPLICATIONS = {
   "admin": {
@@ -164,6 +184,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "books": {
+    "id": "books",
+    "appDir": "TopoloBooks",
+    "name": "topolo-books",
+    "packageName": "topolo-books",
+    "productionUrl": "https://books.topolo.app",
+    "services": [
+      "books"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-books",
+        "kind": "worker",
+        "apiUrl": "https://books.topolo.app",
+        "domains": [
+          "books.topolo.app"
+        ],
+        "routes": [
+          "books.topolo.app"
+        ],
+        "serviceId": "books"
+      }
+    ]
+  },
   "bugfix": {
     "id": "bugfix",
     "appDir": "TopoloBugFix",
@@ -365,6 +409,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "customer_success": {
+    "id": "customer_success",
+    "appDir": "TopoloCustomerSuccess",
+    "name": "topolo-customer-success",
+    "packageName": "topolo-customer-success",
+    "productionUrl": "https://customer-success.topolo.app",
+    "services": [
+      "customer_success"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-customer-success",
+        "kind": "worker",
+        "apiUrl": "https://customer-success.topolo.app",
+        "domains": [
+          "customer-success.topolo.app"
+        ],
+        "routes": [
+          "customer-success.topolo.app"
+        ],
+        "serviceId": "customer_success"
+      }
+    ]
+  },
   "developers": {
     "id": "developers",
     "appDir": "TopoloDevelopers",
@@ -441,6 +509,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "flow": {
+    "id": "flow",
+    "appDir": "TopoloFlow",
+    "name": "topolo-flow",
+    "packageName": "topolo-flow",
+    "productionUrl": "https://flow.topolo.app",
+    "services": [
+      "flow"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-flow",
+        "kind": "worker",
+        "apiUrl": "https://flow.topolo.app",
+        "domains": [
+          "flow.topolo.app"
+        ],
+        "routes": [
+          "flow.topolo.app"
+        ],
+        "serviceId": "flow"
+      }
+    ]
+  },
   "forecast": {
     "id": "forecast",
     "appDir": "TopoloForecast",
@@ -469,6 +561,78 @@ var APPLICATIONS = {
       }
     ]
   },
+  "forms": {
+    "id": "forms",
+    "appDir": "TopoloForms",
+    "name": "topolo-forms",
+    "packageName": "topolo-forms",
+    "productionUrl": "https://forms.topolo.app",
+    "services": [
+      "forms"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-forms",
+        "kind": "worker",
+        "apiUrl": "https://forms.topolo.app",
+        "domains": [
+          "forms.topolo.app"
+        ],
+        "routes": [
+          "forms.topolo.app"
+        ],
+        "serviceId": "forms"
+      }
+    ]
+  },
+  "insights": {
+    "id": "insights",
+    "appDir": "TopoloInsights",
+    "name": "topolo-insights",
+    "packageName": "topolo-insights",
+    "productionUrl": "https://insights.topolo.app",
+    "services": [
+      "insights"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-insights",
+        "kind": "worker",
+        "apiUrl": "https://insights.topolo.app",
+        "domains": [
+          "insights.topolo.app"
+        ],
+        "routes": [
+          "insights.topolo.app"
+        ],
+        "serviceId": "insights"
+      }
+    ]
+  },
+  "inventory": {
+    "id": "inventory",
+    "appDir": "TopoloInventory",
+    "name": "topolo-inventory",
+    "packageName": "topolo-inventory",
+    "productionUrl": "https://inventory.topolo.app",
+    "services": [
+      "inventory"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-inventory",
+        "kind": "worker",
+        "apiUrl": "https://inventory.topolo.app",
+        "domains": [
+          "inventory.topolo.app"
+        ],
+        "routes": [
+          "inventory.topolo.app"
+        ],
+        "serviceId": "inventory"
+      }
+    ]
+  },
   "learn": {
     "id": "learn",
     "appDir": "TopoloLearn",
@@ -669,7 +833,9 @@ var APPLICATIONS = {
         "kind": "worker",
         "apiUrl": null,
         "domains": [
-          "one.topolo.io"
+          "one.topolo.io",
+          "topolo.io",
+          "www.topolo.io"
         ],
         "routes": [],
         "serviceId": null
@@ -706,6 +872,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "people": {
+    "id": "people",
+    "appDir": "TopoloPeople",
+    "name": "topolo-people",
+    "packageName": "topolo-people",
+    "productionUrl": "https://people.topolo.app",
+    "services": [
+      "people"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-people",
+        "kind": "worker",
+        "apiUrl": "https://people.topolo.app",
+        "domains": [
+          "people.topolo.app"
+        ],
+        "routes": [
+          "people.topolo.app"
+        ],
+        "serviceId": "people"
+      }
+    ]
+  },
   "quro": {
     "id": "quro",
     "appDir": "TopoloQuro",
@@ -777,6 +967,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "sign": {
+    "id": "sign",
+    "appDir": "TopoloSign",
+    "name": "topolo-sign",
+    "packageName": "topolo-sign",
+    "productionUrl": "https://sign.topolo.app",
+    "services": [
+      "sign"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-sign",
+        "kind": "worker",
+        "apiUrl": "https://sign.topolo.app",
+        "domains": [
+          "sign.topolo.app"
+        ],
+        "routes": [
+          "sign.topolo.app"
+        ],
+        "serviceId": "sign"
+      }
+    ]
+  },
   "social_studio": {
     "id": "social_studio",
     "appDir": "TopoloSocialStudio",
@@ -873,6 +1087,54 @@ var APPLICATIONS = {
       }
     ]
   },
+  "survey": {
+    "id": "survey",
+    "appDir": "TopoloSurvey",
+    "name": "topolo-survey",
+    "packageName": "topolo-survey",
+    "productionUrl": "https://survey.topolo.app",
+    "services": [
+      "survey"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-survey",
+        "kind": "worker",
+        "apiUrl": "https://survey.topolo.app",
+        "domains": [
+          "survey.topolo.app"
+        ],
+        "routes": [
+          "survey.topolo.app"
+        ],
+        "serviceId": "survey"
+      }
+    ]
+  },
+  "voice": {
+    "id": "voice",
+    "appDir": "TopoloVoice",
+    "name": "topolo-voice",
+    "packageName": "topolo-voice",
+    "productionUrl": "https://voice.topolo.app",
+    "services": [
+      "voice"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-voice",
+        "kind": "worker",
+        "apiUrl": "https://voice.topolo.app",
+        "domains": [
+          "voice.topolo.app"
+        ],
+        "routes": [
+          "voice.topolo.app"
+        ],
+        "serviceId": "voice"
+      }
+    ]
+  },
   "web": {
     "id": "web",
     "appDir": "TopoloWeb",
@@ -1938,11 +2200,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.11";
 
 // src/client.ts
 async function buildClient(options) {
@@ -2304,13 +2566,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 +2597,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 +2649,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 +2711,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 +2881,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 +2971,89 @@ 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 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 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,
+    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({
+      application: applicationPayload,
+      target,
+      browser,
+      api,
+      ciWorkflow
+    }),
+    commands: scaffoldCommands(id, target),
+    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 +3063,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 +3078,177 @@ 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 })
     },
     {
-      path: `${base}/topolo.cloudcontrol.json`,
-      purpose: "CloudControl source of truth for deploy targets, routes, bindings, and CI metadata.",
+      path: `${base}/.gitignore`,
+      purpose: "Generated-app ignore rules.",
       requiredSignals: [
-        "production URLs and Cloudflare targets are explicit",
-        "resource bindings and required secrets are declared without secret values"
-      ]
+        "ignores dependency installs and build output",
+        "keeps local environment files out of source control"
+      ],
+      content: gitignore()
     },
     {
-      path: `${base}/.github/workflows/topolo-conformance.yml`,
-      purpose: "PR/push gate that runs the local Topolo app audit with docs evidence.",
+      path: `${base}/tsconfig.json`,
+      purpose: "TypeScript configuration for the generated app.",
       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"
-      ]
+        "uses strict mode",
+        "includes browser DOM types for React and Worker types for API-backed apps"
+      ],
+      content: tsconfigJson(options.api)
     },
     {
-      path: `PlatformApplications/TopoloDocs/src/content/systems/topolo-${options.id}.json`,
-      purpose: "Canonical system registry entry.",
+      path: `${base}/vite.config.ts`,
+      purpose: "Vite browser build configuration.",
       requiredSignals: [
-        `repo_paths includes ${base}`,
-        "doc_paths includes internal handbook coverage",
-        "security_assurance records the auth, tenancy, deployment, and verification boundary"
-      ]
+        "builds the authenticated browser surface",
+        "keeps generated apps on the standard React/Vite baseline"
+      ],
+      content: viteConfig()
     },
     {
-      path: `PlatformApplications/TopoloDocs/src/content/internal/apps/${options.id}.mdx`,
-      purpose: "Internal operator handbook.",
+      path: `${base}/index.html`,
+      purpose: "Browser entry document.",
       requiredSignals: [
-        "documents ownership, routes, auth boundary, deployment, operations, and verification",
-        "last_verified is updated when behavior changes"
-      ]
+        "mounts the React app at #root",
+        "uses the generated application display name"
+      ],
+      content: indexHtml(application.name)
+    },
+    {
+      path: `${base}/src/main.tsx`,
+      purpose: "React app entrypoint.",
+      requiredSignals: [
+        "renders the generated app component",
+        "imports the generated app stylesheet"
+      ],
+      content: mainTsx()
+    },
+    {
+      path: `${base}/src/env.d.ts`,
+      purpose: "Vite environment variable typing.",
+      requiredSignals: [
+        "loads vite/client import.meta.env types",
+        "declares the Topolo environment variables consumed by the starter"
+      ],
+      content: envDts(options.api)
+    },
+    {
+      path: `${base}/src/styles.css`,
+      purpose: "Minimal app-local styles outside the shared Topolo shell.",
+      requiredSignals: [
+        "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 })
+      },
+      {
+        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 })
+      },
+      {
+        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 })
+      }
+    );
+    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)
+      });
+    }
+  } 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 })
+      },
+      {
+        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 +3256,10 @@ 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)
     });
   }
   if (options.api) {
@@ -2807,9 +3268,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,15 +3280,26 @@ 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)
       }
     );
   }
   return files;
 }
-function scaffoldCommands(id) {
+function scaffoldCommands(id, target) {
+  const scaffoldId = toSlug(id);
+  if (target === "developer") {
+    return [
+      `topolo apps scaffold ${scaffoldId} --target developer --write --repo-root .`,
+      `cd topolo-${scaffoldId}`,
+      "npm install",
+      "npm run typecheck",
+      "npm run build"
+    ];
+  }
   return [
-    `topolo apps scaffold ${id} --json`,
+    `topolo apps scaffold ${scaffoldId} --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`
@@ -2904,18 +3377,1235 @@ 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" ? "first-party platform application" : "third-party Topolo application";
+  const lines = [
+    `# ${displayName}`,
+    "",
+    `Generated ${targetLabel} scaffold for Topolo.`,
+    "",
+    "## 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 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) {
+  if (target === "developer") return developerAppTsx(application);
+  return platformAppTsx(application);
+}
+function platformAppTsx(application) {
+  const appName = toTitle(application.name);
+  const serviceId = application.serviceId ?? application.id;
+  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: 'Topolo workspace',",
+    "  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: 'Topolo workspace',",
+    "  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: 'Workspace' }]}",
+    "      onNavItemSelect={() => undefined}",
+    "      eyebrow={APP_NAME}",
+    '      title="Workspace"',
+    "      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) {
+  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);
+  return `${json({
+    id: `topolo-${slug}`,
+    name: toTitle(application.name),
+    slug: `topolo-${slug}`,
+    kind: "application",
+    summary: `${toTitle(application.name)} is a first-party Topolo application 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: "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: ["topolo-auth", "topolo-platform"]
+  })}
+`;
+}
+function internalDocs(application, options) {
+  const slug = toSlug(application.id);
+  const title = toTitle(application.name);
+  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 application scaffolded from the shared platform 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 organization 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 \`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);
+  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 business 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 organization-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) {
+  const slug = toSlug(application.id);
+  const title = toTitle(application.name);
+  const permissionPrefix = application.id.replace(/[^a-z0-9_]/g, "_");
+  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} workspace data`,
+        resourcePattern: null
+      },
+      {
+        id: `perm_${permissionPrefix}_workspace_write`,
+        name: "workspace:write",
+        description: `Manage ${title} workspace data`,
+        resourcePattern: null
+      }
+    ],
+    apiKeyScopes: [
+      {
+        id: `aks_${permissionPrefix}_workspace_read`,
+        name: "workspace.read",
+        description: `View ${title} workspace data`,
+        resourcePattern: null
+      },
+      {
+        id: `aks_${permissionPrefix}_workspace_write`,
+        name: "workspace.write",
+        description: `Manage ${title} workspace 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",
+    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 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 escapeFrontmatter(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
 
 // src/commands/apps.ts
@@ -2980,20 +4670,30 @@ 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) => {
+  ).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("--target <target>", "Scaffold target: platform or developer").option("--developer", "Shortcut for --target developer").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("--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 {
+      const target = resolveScaffoldTarget(opts.target, opts.developer);
+      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: opts.api,
-        browser: opts.browser
+        api,
+        browser: opts.browser,
+        target
       });
-      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.workflowOnly && !payload.ciWorkflow) {
+        throw new Error("--workflow-only is only available for platform scaffolds.");
+      }
+      const writeResult = opts.write ? await writeApplicationScaffold(payload, { repoRoot: opts.repoRoot, force: opts.force }) : null;
+      const output = opts.workflowOnly ? { application: payload.application, ciWorkflowPath: payload.ciWorkflowPath, ciWorkflow: payload.ciWorkflow } : writeResult ? { ...payload, write: writeResult } : payload;
+      emit(output, mode, () => opts.workflowOnly ? payload.ciWorkflow ?? "" : formatScaffold(payload, writeResult));
     } catch (err) {
       fail(err, mode);
     }
@@ -3154,9 +4854,10 @@ function formatAudit(payload) {
   }
   return lines.join("\n");
 }
-function formatScaffold(payload) {
+function formatScaffold(payload, writeResult = null) {
   const lines = [
     `Version: ${payload.version}`,
+    `Target: ${payload.target}`,
     `Application: ${payload.application.id}`,
     `Directory: ${payload.application.appDir}`,
     `Package: ${payload.application.packageName}`,
@@ -3177,9 +4878,31 @@ 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}`);
+    }
+  }
   return lines.join("\n");
 }
+function resolveScaffoldTarget(target, developer) {
+  const normalized = developer ? "developer" : target?.trim().toLowerCase();
+  if (!normalized) return "platform";
+  if (normalized === "platform" || normalized === "developer") return normalized;
+  throw new Error("Invalid --target value. Use platform or developer.");
+}
+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") {