@topolo/cli 0.1.29 → 0.1.30

package/dist/index.js

@@ -65,54 +65,53 @@ var TopoloHttpError = class extends TopoloSdkError {
   }
 };
 var SERVICES = {
-  agent: "https://agent-api.topolo.app",
+  agent: "https://agent.topolo.app",
   auth: "https://auth.topolo.app",
   backup: "https://backup.topolo.app",
   books: "https://books.topolo.app",
   bugfix: "https://bugfix.topolo.app",
-  bytes: "https://bytes-api.topolo.app",
+  bytes: "https://bytes.topolo.app",
   calendar: "https://calendar.topolo.app",
   capacity: "https://capacity.topolo.app",
   chat: "https://chat.topolo.app",
-  commerce: "https://commerce-api.topolo.app",
+  commerce: "https://commerce.topolo.app",
   compose: "https://compose.topolo.app",
   consent: "https://consent.topolo.app",
-  crm: "https://crm-api.topolo.app",
+  crm: "https://crm.topolo.app",
   developers: "https://developers.topolo.app",
   director: "https://director.topolo.app",
-  feed: "https://feed-api.topolo.app",
+  feed: "https://feed.topolo.app",
   flow: "https://flow.topolo.app",
-  forecast: "https://forecast-api.topolo.app",
+  forecast: "https://forecast.topolo.app",
   forms: "https://forms.topolo.app",
   home: "https://home.topolo.app",
   insights: "https://insights.topolo.app",
   inventory: "https://inventory.topolo.app",
-  learn: "https://learn-api.topolo.app",
+  learn: "https://learn.topolo.app",
   localize: "https://localize.topolo.app",
-  mail: "https://mail-api.topolo.app",
-  mdm: "https://mdm-api.topolo.app",
+  mail: "https://mail.topolo.app",
+  mdm: "https://mdm.topolo.app",
   messages: "https://messages.topolo.app",
   nexus: "https://nexus-api.topolo.app",
   notify: "https://notify.topolo.app",
   observability_watch: "https://observability-watch.topolo.app",
-  one: "https://one.topolo.app",
+  one: "https://www.topolo.app",
   p2p: "https://p2p.topolo.app",
   pay: "https://pay.topolo.app",
   people: "https://people.topolo.app",
-  pulse: "https://pulse.topolo.app",
   "quro.api": "https://api.ol0.me",
   "quro.redirect": "https://ol0.me",
-  roadmapper: "https://roadmapper-api.topolo.app",
+  roadmapper: "https://roadmapper.topolo.app",
   sign: "https://sign.topolo.app",
-  social_studio: "https://studio-api.topolo.app",
-  socialize: "https://socialize-api.topolo.app",
+  social_studio: "https://studio.topolo.app",
+  socialize: "https://socialize.topolo.app",
   spaces: "https://spaces.topolo.app",
   status: "https://status.topolo.app",
   success: "https://success.topolo.app",
   support: "https://support.topolo.app",
   survey: "https://survey.topolo.app",
   voice: "https://voice.topolo.app",
-  web: "https://web-api.topolo.app"
+  web: "https://web.topolo.app"
 };
 var APPLICATIONS = {
   "admin": {
@@ -161,17 +160,15 @@ var APPLICATIONS = {
           "agent.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "agent"
       },
       {
         "name": "topolo-agent-api",
         "kind": "worker",
-        "apiUrl": "https://agent-api.topolo.app",
-        "domains": [
-          "agent-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "agent"
+        "serviceId": null
       }
     ]
   },
@@ -291,17 +288,15 @@ var APPLICATIONS = {
           "bytes.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "bytes"
       },
       {
         "name": "topolo-bytes-api",
         "kind": "worker",
-        "apiUrl": "https://bytes-api.topolo.app",
-        "domains": [
-          "bytes-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "bytes"
+        "serviceId": null
       }
     ]
   },
@@ -400,12 +395,10 @@ var APPLICATIONS = {
       {
         "name": "topolo-commerce-api",
         "kind": "worker",
-        "apiUrl": "https://commerce-api.topolo.app",
-        "domains": [
-          "commerce-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "commerce"
+        "serviceId": null
       },
       {
         "name": "topolo-commerce-guest-web",
@@ -425,7 +418,7 @@ var APPLICATIONS = {
           "commerce.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "commerce"
       },
       {
         "name": "topolo-commerce-station-web",
@@ -512,12 +505,10 @@ var APPLICATIONS = {
       {
         "name": "topolo-crm-api",
         "kind": "worker",
-        "apiUrl": "https://crm-api.topolo.app",
-        "domains": [
-          "crm-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "crm"
+        "serviceId": null
       },
       {
         "name": "topolo-crm-app",
@@ -527,7 +518,7 @@ var APPLICATIONS = {
           "crm.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "crm"
       }
     ]
   },
@@ -650,12 +641,10 @@ var APPLICATIONS = {
       {
         "name": "topolo-feed-api",
         "kind": "worker",
-        "apiUrl": "https://feed-api.topolo.app",
-        "domains": [
-          "feed-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "feed"
+        "serviceId": null
       },
       {
         "name": "topolo-feed-web",
@@ -665,7 +654,7 @@ var APPLICATIONS = {
           "feed.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "feed"
       }
     ]
   },
@@ -717,17 +706,15 @@ var APPLICATIONS = {
           "forecast.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "forecast"
       },
       {
         "name": "topolo-forecast-api",
         "kind": "worker",
-        "apiUrl": "https://forecast-api.topolo.app",
-        "domains": [
-          "forecast-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "forecast"
+        "serviceId": null
       }
     ]
   },
@@ -869,17 +856,15 @@ var APPLICATIONS = {
           "learn.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "learn"
       },
       {
         "name": "topolo-learn-api",
         "kind": "worker",
-        "apiUrl": "https://learn-api.topolo.app",
-        "domains": [
-          "learn-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "learn"
+        "serviceId": null
       }
     ]
   },
@@ -925,17 +910,15 @@ var APPLICATIONS = {
           "mail.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "mail"
       },
       {
         "name": "topolo-mail-api",
         "kind": "worker",
-        "apiUrl": "https://mail-api.topolo.app",
-        "domains": [
-          "mail-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "mail"
+        "serviceId": null
       }
     ]
   },
@@ -952,12 +935,10 @@ var APPLICATIONS = {
       {
         "name": "topolo-mdm-api",
         "kind": "worker",
-        "apiUrl": "https://mdm-api.topolo.app",
-        "domains": [
-          "mdm-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "mdm"
+        "serviceId": null
       },
       {
         "name": "topolo-mdm-console",
@@ -967,7 +948,7 @@ var APPLICATIONS = {
           "mdm.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "mdm"
       }
     ]
   },
@@ -1100,20 +1081,23 @@ var APPLICATIONS = {
       {
         "name": "topolo-one",
         "kind": "worker",
-        "apiUrl": null,
-        "domains": [],
-        "routes": [],
+        "apiUrl": "https://one.topolo.app",
+        "domains": [
+          "one.topolo.app"
+        ],
+        "routes": [
+          "one.topolo.app/*"
+        ],
         "serviceId": null
       },
       {
         "name": "topolo-one-api",
         "kind": "worker",
-        "apiUrl": "https://one.topolo.app",
+        "apiUrl": "https://www.topolo.app",
         "domains": [
-          "one.topolo.app"
+          "www.topolo.app"
         ],
         "routes": [
-          "one.topolo.app/*",
           "www.topolo.app/*"
         ],
         "serviceId": "one"
@@ -1223,36 +1207,6 @@ var APPLICATIONS = {
       }
     ]
   },
-  "pulse": {
-    "id": "pulse",
-    "appDir": "TopoloPulse",
-    "name": "topolo-pulse",
-    "packageName": "topolo-pulse",
-    "productionUrl": "https://pulse.topolo.app",
-    "services": [
-      "pulse"
-    ],
-    "deployTargets": [
-      {
-        "name": "topolo-pulse",
-        "kind": "worker",
-        "apiUrl": "https://pulse.topolo.app",
-        "domains": [
-          "pulse.topolo.app"
-        ],
-        "routes": [],
-        "serviceId": "pulse"
-      },
-      {
-        "name": "topolo-pulse-api",
-        "kind": "worker",
-        "apiUrl": null,
-        "domains": [],
-        "routes": [],
-        "serviceId": null
-      }
-    ]
-  },
   "quro": {
     "id": "quro",
     "appDir": "TopoloQuro",
@@ -1318,17 +1272,15 @@ var APPLICATIONS = {
           "roadmapper.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "roadmapper"
       },
       {
         "name": "topolo-roadmapper-api",
         "kind": "worker",
-        "apiUrl": "https://roadmapper-api.topolo.app",
-        "domains": [
-          "roadmapper-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "roadmapper"
+        "serviceId": null
       }
     ]
   },
@@ -1380,17 +1332,15 @@ var APPLICATIONS = {
           "studio.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "social_studio"
       },
       {
         "name": "topolo-social-studio-api",
         "kind": "worker",
-        "apiUrl": "https://studio-api.topolo.app",
-        "domains": [
-          "studio-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "social_studio"
+        "serviceId": null
       },
       {
         "name": "topolo-social-studio-queue",
@@ -1420,17 +1370,15 @@ var APPLICATIONS = {
           "socialize.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "socialize"
       },
       {
         "name": "topolo-socialize-api",
         "kind": "worker",
-        "apiUrl": "https://socialize-api.topolo.app",
-        "domains": [
-          "socialize-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "socialize"
+        "serviceId": null
       },
       {
         "name": "topolo-socialize-scheduler",
@@ -1631,12 +1579,10 @@ var APPLICATIONS = {
       {
         "name": "topolo-web-api",
         "kind": "worker",
-        "apiUrl": "https://web-api.topolo.app",
-        "domains": [
-          "web-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "web"
+        "serviceId": null
       },
       {
         "name": "topolo-web-runtime",
@@ -1659,12 +1605,12 @@ var APPLICATIONS = {
           "web.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "web"
       }
     ]
   }
 };
-var APPLICATION_REQUIREMENTS_VERSION = "2026-05-01.1";
+var APPLICATION_REQUIREMENTS_VERSION = "2026-06-07.1";
 var APPLICATION_REQUIREMENTS = [
   {
     id: "platform-metadata",
@@ -1720,16 +1666,20 @@ var APPLICATION_REQUIREMENTS = [
     summary: "Browser applications should feel like one platform and should not create isolated navigation or account surfaces.",
     appliesTo: ["browser"],
     evidence: [
-      "@topolo/ui-kit is used for the platform shell where the app has authenticated UI",
-      "The shared launcher/app switcher is reachable from authenticated app chrome",
-      "Account menu and sign-out behavior use TopoloAppShell or TopoloAccountMenu",
+      "@topolo-io/app-shell is used for the platform shell where the app has authenticated UI",
+      "@topolo-io/app-launcher keeps the shared launcher/app switcher reachable from authenticated app chrome",
+      "Account menu and sign-out behavior use TopoloAppShell or the ui-kit TopoloAccountMenu primitive",
+      "Repeated app body surfaces use shared TopoloAppLayout primitives instead of local stat cards, empty states, or status badges",
+      "Local preview supports deterministic visual QA fixtures for overview, list, detail, settings, and empty/loading states",
       "Authenticated app body content stays inside the viewport on mobile and desktop widths"
     ],
     implementation: [
-      "Use TopoloAppShell for authenticated app layouts",
-      "Use TopoloAccountMenu when a partial-shell surface still needs account chrome",
+      "Use @topolo-io/app-shell TopoloAppShell for authenticated app layouts",
+      "Use the @topolo-io/ui-kit TopoloAccountMenu primitive when a partial-shell surface still needs account chrome",
       "Pass app-specific account actions as additive menu items instead of forking dropdowns",
       "Use shared design tokens and platform UI primitives before creating local equivalents",
+      "Use TopoloAppMetricCard, TopoloAppEmptyState, TopoloAppStatusBadge, TopoloAppGrid, and TopoloAppSection for repeated app body patterns",
+      "Keep visual QA fixtures available through visualQa=1 or __devpreview=1 so screenshot checks do not depend on live API state",
       "Keep mobile and desktop shell behavior aligned with the platform UI kit",
       "Constrain app-owned workspace wrappers with min-width: 0, width: auto, and viewport-aware max-width so shell padding cannot create page-level horizontal overflow"
     ]
@@ -1808,11 +1758,13 @@ var APPLICATION_REQUIREMENTS = [
     evidence: [
       "The app-owned API exposes GET /api/widget",
       "The endpoint returns TopoloWidgetApiResponse from @topolo/sdk",
+      "Every returned widget includes snapshot.summary with app-owned operational prose",
       "The endpoint derives organization/user context from the app auth boundary"
     ],
     implementation: [
       "Import createTopoloWidgetResponse from @topolo/sdk in the app backend",
       "Return native app metrics or action widgets instead of generic launch-card fallbacks",
+      "Populate snapshot.summary in the producing app for every widget instead of synthesizing summaries in TopoloOne",
       "Add a route-level test that validates the response with validateTopoloWidgetResponse"
     ]
   },
@@ -2105,6 +2057,8 @@ function firstString(...values) {
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 var TOPOLO_ACTION_ID_HEADER = "X-Topolo-Action-Id";
 var TOPOLO_ACTION_NAME_HEADER = "X-Topolo-Action-Name";
+var TOPOLO_RESOURCE_TYPE_HEADER = "X-Topolo-Resource-Type";
+var TOPOLO_RESOURCE_ID_HEADER = "X-Topolo-Resource-ID";
 var POSITIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
 var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
 var CATALOG_CACHE_TTL_MS = 60 * 1e3;
@@ -2183,6 +2137,18 @@ var TopoloClient = class _TopoloClient {
     if (opts.headers) {
       for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
     }
+    if (opts.resource) {
+      const resourceType = opts.resource.resourceType.trim();
+      const resourceId = opts.resource.resourceId.trim();
+      if (!resourceType || !resourceId) {
+        throw new TopoloSdkError(
+          "invalid_resource_context",
+          "Both resource.resourceType and resource.resourceId are required when resource context is provided."
+        );
+      }
+      headers.set(TOPOLO_RESOURCE_TYPE_HEADER, resourceType);
+      headers.set(TOPOLO_RESOURCE_ID_HEADER, resourceId);
+    }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
     const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
@@ -2365,6 +2331,11 @@ var TopoloClient = class _TopoloClient {
       const serviceId = typeof s.service_id === "string" ? s.service_id : typeof s.id === "string" ? s.id : null;
       if (!serviceId) continue;
       const permissions = Array.isArray(s.granted_permissions) ? s.granted_permissions.filter((permission) => typeof permission === "string" && permission.trim().length > 0) : [];
+      const catalogApiKeyResources = normalizeApiKeyResourceMetadataList(
+        s.api_key_resources ?? s.apiKeyResources
+      );
+      const apiKeyResource = normalizeApiKeyResourceMetadata(s.api_key_resource ?? s.apiKeyResource) ?? catalogApiKeyResources[0] ?? null;
+      const apiKeyResources = catalogApiKeyResources.length > 0 ? catalogApiKeyResources : apiKeyResource ? [apiKeyResource] : [];
       entries.push({
         serviceId,
         slug: typeof s.app_slug === "string" ? s.app_slug : null,
@@ -2375,7 +2346,9 @@ var TopoloClient = class _TopoloClient {
         status: typeof s.status === "string" ? s.status : null,
         surfaceKind: typeof s.surface_kind === "string" ? s.surface_kind : null,
         launchable: s.launchable === true,
-        permissions
+        permissions,
+        apiKeyResource,
+        apiKeyResources
       });
     }
     this.serviceCatalogCache = {
@@ -2461,7 +2434,9 @@ var TopoloClient = class _TopoloClient {
       status: "bundled",
       surfaceKind: "application",
       launchable: Boolean(app.productionUrl),
-      permissions: []
+      permissions: [],
+      apiKeyResource: null,
+      apiKeyResources: []
     }));
   }
   /**
@@ -2510,6 +2485,46 @@ function resolveConfiguredServiceId(slug, serviceIds) {
   }
   return null;
 }
+function normalizeApiKeyResourceMetadata(input2) {
+  if (!isRecord(input2)) return null;
+  const resourceType = readString(input2.resourceType ?? input2.resource_type);
+  const label = readString(input2.label);
+  const emptyLabel = readString(input2.emptyLabel ?? input2.empty_label);
+  const resourceConcept = readString(input2.resourceConcept ?? input2.resource_concept);
+  const canonicalResourceType = readString(input2.canonicalResourceType ?? input2.canonical_resource_type);
+  const defaultEntitlement = readString(input2.defaultEntitlement ?? input2.default_entitlement);
+  const exceptionPolicy = readString(input2.exceptionPolicy ?? input2.exception_policy);
+  if (!resourceType || !label || !emptyLabel || resourceConcept !== "workspace" || canonicalResourceType !== "workspace" || defaultEntitlement !== "enterprise" || exceptionPolicy !== "app_or_organization") {
+    return null;
+  }
+  return {
+    resourceType,
+    label,
+    emptyLabel,
+    resourceConcept,
+    canonicalResourceType,
+    defaultEntitlement,
+    exceptionPolicy
+  };
+}
+function normalizeApiKeyResourceMetadataList(input2) {
+  if (!Array.isArray(input2)) return [];
+  const resources = [];
+  const seenTypes = /* @__PURE__ */ new Set();
+  for (const item of input2) {
+    const resource = normalizeApiKeyResourceMetadata(item);
+    if (!resource || seenTypes.has(resource.resourceType)) continue;
+    seenTypes.add(resource.resourceType);
+    resources.push(resource);
+  }
+  return resources;
+}
+function readString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function resolveConfiguredServiceUrl(slug, serviceUrls) {
   for (const serviceKey of serviceKeyCandidates2(slug)) {
     const configured = serviceUrls?.[serviceKey];
@@ -3498,7 +3513,7 @@ function registerApiCommand(program2) {
   ).option("-d, --data <json>", "JSON body (for POST/PUT/PATCH)").option(
     "-q, --query <kv...>",
     "Query params as key=value (repeatable), e.g. --query source=cli page=2"
-  ).option("--confirm", "Acknowledge a mutating request").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(
+  ).option("--resource-type <type>", "Cataloged app-local workspace resource alias for resource-scoped API keys").option("--resource-id <id>", "Workspace resource id for resource-scoped API keys").option("--confirm", "Acknowledge a mutating request").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(
     async (service, method, path4, opts) => {
       const mode = resolveOutputMode(opts.json);
       try {
@@ -3529,6 +3544,7 @@ function registerApiCommand(program2) {
           }
         }
         const query = parseQueryPairs(opts.query);
+        const resource = parseResourceOption(opts.resourceType, opts.resourceId);
         const topolo = await buildClient();
         if (!topolo) {
           throw new Error(
@@ -3541,6 +3557,7 @@ function registerApiCommand(program2) {
           path: path4,
           body,
           ...query ? { query } : {},
+          ...resource ? { resource } : {},
           confirm: opts.confirm === true
         });
         emit(result, mode, () => JSON.stringify(result, null, 2));
@@ -3550,6 +3567,15 @@ function registerApiCommand(program2) {
     }
   );
 }
+function parseResourceOption(resourceType, resourceId) {
+  const normalizedType = resourceType?.trim() || "";
+  const normalizedId = resourceId?.trim() || "";
+  if (!normalizedType && !normalizedId) return void 0;
+  if (!normalizedType || !normalizedId) {
+    throw new Error("--resource-type and --resource-id must be provided together.");
+  }
+  return { resourceType: normalizedType, resourceId: normalizedId };
+}
 function resolveConfiguredServiceUrl2(service, serviceUrls) {
   const normalized = service.trim().toLowerCase();
   const withoutTopolo = normalized.startsWith("topolo-") ? normalized.slice("topolo-".length) : normalized;
@@ -3595,7 +3621,7 @@ import {
 import path from "path";
 var EVIDENCE_FRESHNESS_MS = 36 * 60 * 60 * 1e3;
 var REQUIRED_AUTH_CLIENT_VERSION = "1.1.9";
-var REQUIRED_UI_KIT_VERSION = "0.4.67";
+var REQUIRED_UI_KIT_VERSION = "0.4.196";
 function readEvidenceFile(appRoot) {
   const candidate = path.join(appRoot, ".topolo", "evidence.json");
   if (!isFile(candidate)) return null;
@@ -3871,7 +3897,7 @@ function enrichFinding(application, finding2, evidence) {
           nextActions: []
         });
       }
-      if (shellEvidence.length === 0 && hasDocumentationSurface(application, evidence)) {
+      if (hasDocumentationSurface(application, evidence)) {
         return mergeFinding(finding2, {
           status: "met",
           reason: "This is a documentation surface rather than an authenticated app workspace, so the shared application shell requirement does not apply.",
@@ -3889,7 +3915,7 @@ function enrichFinding(application, finding2, evidence) {
       if (shellEvidence.includes(`dependency-version=@topolo-io/ui-kit<${REQUIRED_UI_KIT_VERSION}`)) {
         return mergeFinding(finding2, {
           status: "needs_review",
-          reason: `The app depends on @topolo-io/ui-kit below ${REQUIRED_UI_KIT_VERSION}; launcher catalog cache/dedupe fixes require the current shared kit.`,
+          reason: `The app depends on @topolo-io/ui-kit below ${REQUIRED_UI_KIT_VERSION}; shared primitive fixes require the current kit.`,
           evidence: shellEvidence,
           nextActions: [
             `Update @topolo-io/ui-kit to ${REQUIRED_UI_KIT_VERSION}`,
@@ -3922,13 +3948,61 @@ function enrichFinding(application, finding2, evidence) {
           ]
         });
       }
+      if (shellEvidence.includes("local=raw-symbol-icons")) {
+        return mergeFinding(finding2, {
+          status: "needs_review",
+          reason: "Raw symbolic UI icons are visible locally. Product apps must use TopoloPlatformIcon, TopoloAppIcon, or the shared @topolo-io/ui-kit/icons entrypoint so nav, status, and provider icons stay consistent.",
+          evidence: shellEvidence,
+          nextActions: [
+            "Replace raw nav/status/provider glyphs with TopoloPlatformIcon or TopoloAppIcon",
+            "Use @topolo-io/ui-kit/icons for lucide icons instead of text symbols",
+            "Keep app page content on TopoloAppLayout primitives where available"
+          ]
+        });
+      }
+      if (shellEvidence.includes("local=direct-lucide-react")) {
+        return mergeFinding(finding2, {
+          status: "needs_review",
+          reason: "The app imports lucide-react directly. First-party browser apps should import icons through @topolo-io/ui-kit/icons so the fleet shares one icon library contract.",
+          evidence: shellEvidence,
+          nextActions: [
+            "Change direct lucide-react imports to @topolo-io/ui-kit/icons",
+            "Use TopoloPlatformIcon for recurring platform, provider, capability, and status icons",
+            "Remove the app-local lucide-react dependency when nothing else needs it"
+          ]
+        });
+      }
+      if (shellEvidence.includes("local=missing-shared-page-primitives")) {
+        return mergeFinding(finding2, {
+          status: "needs_review",
+          reason: "The app uses shared shell chrome, but app-owned page content still appears to rely on local layout primitives. Use TopoloAppLayout primitives for metrics, empty states, status badges, grids, and page sections so app bodies stay visually aligned.",
+          evidence: shellEvidence,
+          nextActions: [
+            "Replace repeated local stat cards, empty states, status pills, and page section wrappers with TopoloAppLayout primitives",
+            "Keep app-owned workspace wrappers constrained with min-width: 0 and shared shell spacing tokens",
+            "Rerun visual QA at desktop and mobile widths after moving the page body primitives"
+          ]
+        });
+      }
+      if (shellEvidence.includes("local=missing-visual-qa-fixtures")) {
+        return mergeFinding(finding2, {
+          status: "needs_review",
+          reason: "The app has a browser workspace but no deterministic visual QA mode was found. Staging visual checks need fixture-backed pages so layout, icons, empty states, and loading states can be reviewed without live API/CORS noise.",
+          evidence: shellEvidence,
+          nextActions: [
+            "Add a visualQa=1 or __devpreview=1 mode for local preview builds",
+            "Provide fixture responses for overview, list/table, detail, settings, and empty/loading surfaces",
+            "Use Playwright screenshots against the fixture mode before staging rollout"
+          ]
+        });
+      }
       const usesCanonicalAppShell = shellEvidence.includes("source=TopoloAppShell");
       const usesSharedAccountPrimitive = shellEvidence.includes("source=TopoloAccountMenu");
       const usesSharedSuite = usesCanonicalAppShell || usesSharedAccountPrimitive;
       if (!usesSharedSuite) {
         return mergeFinding(finding2, {
           status: "needs_review",
-          reason: "The app depends on @topolo-io/ui-kit, but no canonical TopoloAppShell or shared account primitive is visible locally.",
+          reason: "The app depends on shared Topolo browser packages, but no canonical TopoloAppShell or shared account primitive is visible locally.",
           evidence: shellEvidence,
           nextActions: [
             "Use TopoloAppShell for authenticated first-party app layouts",
@@ -4278,12 +4352,30 @@ function sharedShellEvidence(evidence) {
   const deps = dependencyNames(evidence);
   const text = evidence.source.text;
   const items = [];
+  if (deps.has("@topolo-io/app-shell")) items.push("dependency=@topolo-io/app-shell");
   if (deps.has("@topolo-io/ui-kit")) items.push("dependency=@topolo-io/ui-kit");
   if (packageDependencyVersions(evidence, "@topolo-io/ui-kit").some((version) => isStaleDependencyVersion(version, REQUIRED_UI_KIT_VERSION))) {
     items.push(`dependency-version=@topolo-io/ui-kit<${REQUIRED_UI_KIT_VERSION}`);
   }
   if (text.includes("@topolo-io/ui-kit")) items.push("source=@topolo-io/ui-kit");
+  if (text.includes("@topolo-io/ui-kit/icons")) items.push("source=@topolo-io/ui-kit/icons");
+  if (text.includes("TopoloPlatformIcon")) items.push("source=TopoloPlatformIcon");
+  const usesSharedPagePrimitives = /\bTopoloApp(?:MetricCard|Toolbar|EmptyState|StatusBadge|Page|PageHeader|Section|Grid)\b/.test(text);
+  if (/\bTopoloApp(?:MetricCard|Toolbar|EmptyState|StatusBadge|Page|PageHeader|Section|Grid)\b/.test(text)) {
+    items.push("source=TopoloAppLayout");
+  }
+  if (text.includes("@topolo-io/app-shell")) items.push("source=@topolo-io/app-shell");
   if (text.includes("TopoloAppShell")) items.push("source=TopoloAppShell");
+  const hasVisualQaMode = /visualQa|__devpreview|visual qa/i.test(text);
+  const hasVisualQaFixtures = hasVisualQaMode && /fixture|visualQaResponse|visualQaApi|mock[A-Z]\w*|devpreview/i.test(text) && /fetch|useQuery|api/i.test(text);
+  if (hasVisualQaFixtures) items.push("source=visual-qa-fixtures");
+  if (/from\s+['"]lucide-react['"]/.test(text)) items.push("local=direct-lucide-react");
+  if (/(?:icon|Icon)\s*:\s*['"][◈◇⬡⬢▣◉✉▷✦○◆✕⚙🔑💡⚠✓♫]/.test(text)) {
+    items.push("local=raw-symbol-icons");
+  }
+  if (/(?:<span[^>]*>|<div[^>]*>)[^<]{0,16}[◈◇⬡⬢▣◉✉▷✦○◆✕⚙🔑💡⚠✓♫]/.test(text)) {
+    items.push("local=raw-symbol-icons");
+  }
   if (text.includes(["Topolo", "Workspace", "Shell"].join(""))) items.push("forbidden=workspace-shell");
   if (/\bTopoloShell\b/.test(text)) items.push("legacy=TopoloShellFrame");
   if (text.includes("TopoloAccountMenu")) items.push("source=TopoloAccountMenu");
@@ -4291,6 +4383,12 @@ function sharedShellEvidence(evidence) {
   if (/\baccountMenuOpen\b|\bsetAccountMenuOpen\b|\buserMenuOpen\b|\bUserMenu\b|user-menu/.test(text)) {
     items.push("local=account-menu");
   }
+  if (deps.has("@topolo-io/app-shell") && !usesSharedPagePrimitives) {
+    items.push("local=missing-shared-page-primitives");
+  }
+  if (hasLocalBrowserSurface(evidence) && !hasVisualQaFixtures) {
+    items.push("local=missing-visual-qa-fixtures");
+  }
   return unique(items);
 }
 function hasDocumentationSurface(application, evidence) {
@@ -4299,7 +4397,7 @@ function hasDocumentationSurface(application, evidence) {
 }
 function hasLocalBrowserSurface(evidence) {
   const deps = dependencyNames(evidence);
-  if (deps.has("react") || deps.has("react-dom") || deps.has("astro") || deps.has("@vitejs/plugin-react") || deps.has("@topolo-io/ui-kit")) {
+  if (deps.has("react") || deps.has("react-dom") || deps.has("astro") || deps.has("@vitejs/plugin-react") || deps.has("@topolo-io/app-shell") || deps.has("@topolo-io/ui-kit")) {
     return true;
   }
   return evidence.source.files.some(
@@ -4743,8 +4841,11 @@ function scaffoldPackages(options) {
   }
   const packages = /* @__PURE__ */ new Set();
   if (options.browser) {
-    packages.add("@topolo-io/ui-kit");
+    packages.add("@topolo-io/app-funnel");
+    packages.add("@topolo-io/app-launcher");
+    packages.add("@topolo-io/app-shell");
     packages.add("@topolo-io/auth-client");
+    packages.add("@topolo-io/ui-kit");
   }
   if (options.api) {
     packages.add("@topolo-io/worker-runtime");
@@ -5031,8 +5132,8 @@ function scaffoldFiles(options) {
       path: `${browserBase}/src/App.tsx`,
       purpose: "Authenticated browser surface.",
       requiredSignals: [
-        "imports shared TopoloAppShell from @topolo-io/ui-kit",
-        "uses @topolo-io/auth-client for app-origin auth flows",
+        "bootstraps routes, auth provider, and shared shell through @topolo-io/app-shell",
+        "uses @topolo-io/auth-client through the app-shell wrapper for app-origin auth flows",
         "keeps launcher and account-menu behavior on the shared platform surface",
         "passes app-specific account actions through accountMenuItems or TopoloAccountMenu"
       ],
@@ -5248,10 +5349,14 @@ function packageJson(application, target, options) {
     devDependencies["@vitejs/plugin-react"] = "^4.7.0";
     if (target === "platform") {
       dependencies["@topolo-io/auth-client"] = topoloPackageVersion("@topolo-io/auth-client", target);
+      dependencies["@topolo-io/app-funnel"] = topoloPackageVersion("@topolo-io/app-funnel", target);
+      dependencies["@topolo-io/app-launcher"] = topoloPackageVersion("@topolo-io/app-launcher", target);
+      dependencies["@topolo-io/app-shell"] = topoloPackageVersion("@topolo-io/app-shell", target);
       dependencies["@topolo-io/design-tokens"] = topoloPackageVersion("@topolo-io/design-tokens", target);
       dependencies["@topolo-io/onboarding"] = topoloPackageVersion("@topolo-io/onboarding", target);
       dependencies["@topolo-io/tour"] = topoloPackageVersion("@topolo-io/tour", target);
       dependencies["@topolo-io/ui-kit"] = topoloPackageVersion("@topolo-io/ui-kit", target);
+      dependencies["react-router-dom"] = "^7.6.2";
     } else {
       dependencies["@topolo/login"] = topoloPackageVersion("@topolo/login", target);
     }
@@ -5295,6 +5400,9 @@ function topoloPackageVersion(packageName, target) {
   const platformPackageFolders = {
     "@topolo/sdk": "topolo-sdk",
     "@topolo/login": "topolo-login",
+    "@topolo-io/app-funnel": "topolo-app-funnel",
+    "@topolo-io/app-launcher": "topolo-app-launcher",
+    "@topolo-io/app-shell": "topolo-app-shell",
     "@topolo-io/auth-client": "topolo-auth-client",
     "@topolo-io/auth-middleware": "topolo-auth-middleware",
     "@topolo-io/worker-runtime": "topolo-worker-runtime",
@@ -5380,7 +5488,10 @@ function readme(application, target, options) {
     lines.push(
       "## Shared Topolo Surface",
       "",
-      "- `@topolo-io/ui-kit` provides the shared shell, launcher, account menu, command palette, and bug reporter.",
+      "- `@topolo-io/app-funnel` provides the generated public application funnel/landing surface.",
+      "- `@topolo-io/app-shell` provides the generated route/auth bootstrap, product shell, login, callback, and loading surfaces.",
+      "- `@topolo-io/app-launcher` provides shared app switching and handoff helpers.",
+      "- `@topolo-io/ui-kit` provides primitive account, command palette, icon, transition, and bug reporter UI.",
       "- `@topolo-io/auth-client` owns browser auth, callback exchange, token refresh, and logout.",
       "- Generated first-party browser apps start on the shared landing page at `/`, use the shared login page at `/login`, and complete sign-in on `/auth/callback` before entering the workspace shell.",
       "- `vite.config.ts` includes the standard React plugin plus React runtime dedupe so linked Topolo packages resolve one browser React runtime."
@@ -5802,13 +5913,13 @@ function platformAppTsx(application, options) {
   const tagline = isPersonal ? "Topolo personal app" : "Topolo workspace";
   const workspaceTitle = isPersonal ? "Personal app" : "Workspace";
   const shellLabel = isPersonal ? "personal app shell" : "workspace shell";
-  const signedSurfaceLabel = isPersonal ? "personal app" : "workspace";
   const baselineHeading = isPersonal ? "Shared personal baseline" : "Shared workspace baseline";
   const baselineDescription = isPersonal ? "This scaffold starts on the shared landing and login surfaces, completes sign-in on the shared callback path, and renders the signed personal app inside the shared Topolo shell." : "This scaffold starts on the shared landing and login surfaces, completes sign-in on the shared callback path, and renders the signed workspace inside the shared Topolo shell.";
   return [
     "import { Component, useCallback, useEffect, useMemo, useState, type ErrorInfo, type ReactNode } from 'react';",
-    "import { createBrowserAuthSessionController, type AuthUser } from '@topolo-io/auth-client';",
-    "import { LandingPage, LoginPage, TopoloAppShell, TopoloAuthFlowScreen, TopoloLoadingScreen, setupBugReporterErrorCapture, type TopoloAppShellUser } from '@topolo-io/ui-kit';",
+    "import { LandingPage } from '@topolo-io/app-funnel';",
+    "import { LoginPage, TopoloAppLoadingScaffold, TopoloAppRoot, TopoloAuthFlowScreen, createTopoloAuth, useAuth, type AppRoute as TopoloAppRoute } from '@topolo-io/app-shell';",
+    "import { setupBugReporterErrorCapture } from '@topolo-io/ui-kit';",
     "import { GettingStarted, type OnboardingGuideStep } from '@topolo-io/onboarding';",
     "import { IntroTour } from '@topolo-io/tour';",
     "import { SCAFFOLD_APP_ID, SCAFFOLD_APP_NAME, SCAFFOLD_SERVICE_SLUG, getBrowserAuthBaseUrl, resolveAppServiceId } from './service-identity';",
@@ -5817,11 +5928,6 @@ function platformAppTsx(application, options) {
     "// can attach the last few errors to any submitted bug report.",
     "setupBugReporterErrorCapture();",
     "",
-    "type NavItem = 'home' | 'getting-started';",
-    "type WorkspaceView = 'workspace' | 'getting-started';",
-    "type AppRoute = { kind: 'root' } | { kind: 'login' } | { kind: 'callback' };",
-    "type BrowserAuthModule = ReturnType<typeof createBrowserAuthSessionController>;",
-    "",
     "const APP_ID = SCAFFOLD_APP_ID;",
     "const APP_NAME = SCAFFOLD_APP_NAME;",
     "const AUTH_URL = getBrowserAuthBaseUrl();",
@@ -5843,69 +5949,17 @@ function platformAppTsx(application, options) {
     "  authenticated_home_path: '/',",
     "};",
     "",
-    "let activeAuthServiceId = '';",
-    "let activeAuthModule: BrowserAuthModule | null = null;",
-    "",
-    "function getAuthModule(serviceId: string): BrowserAuthModule {",
-    "  const normalizedServiceId = serviceId.trim();",
-    "  if (!normalizedServiceId) throw new Error(`Missing Auth service id for ${SCAFFOLD_SERVICE_SLUG}`);",
-    "  if (!activeAuthModule || activeAuthServiceId !== normalizedServiceId) {",
-    "    activeAuthServiceId = normalizedServiceId;",
-    "    activeAuthModule = createBrowserAuthSessionController({",
-    "      authServiceUrl: AUTH_URL,",
-    "      serviceId: normalizedServiceId,",
-    "      devSessionKey: `${normalizedServiceId}_session`,",
-    "      devSessionStorageEnabled: import.meta.env.DEV,",
-    "      callbackPath: '/auth/callback',",
-    "      debug: import.meta.env.DEV,",
-    "    });",
-    "  }",
-    "  return activeAuthModule;",
-    "}",
-    "",
-    "function getAccessToken(): string | null {",
-    "  return activeAuthModule?.accessTokenMemory.get() ?? activeAuthModule?.accessTokenSession.get() ?? null;",
-    "}",
-    "",
-    "function toShellUser(user: AuthUser | null): TopoloAppShellUser | null {",
-    "  if (!user) return null;",
-    "  return {",
-    "    id: user.id,",
-    "    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() {",
     "  return (",
     "    <AppErrorBoundary>",
-    "      <AppRoot />",
+    "      <CanonicalAppRoot />",
     "    </AppErrorBoundary>",
     "  );",
     "}",
     "",
-    "function AppRoot() {",
-    "  const route = getRoute();",
-    "  const [user, setUser] = useState<AuthUser | null>(null);",
+    "function CanonicalAppRoot() {",
     "  const [serviceId, setServiceId] = useState('');",
     "  const [serviceIdentityError, setServiceIdentityError] = useState('');",
-    "  const [loading, setLoading] = useState(true);",
-    "  const [authError, setAuthError] = useState('');",
-    "  const [loginAttempted, setLoginAttempted] = useState(false);",
-    "  const [view, setView] = useState<WorkspaceView>('workspace');",
-    "  const auth = useMemo(() => serviceId ? getAuthModule(serviceId) : null, [serviceId]);",
-    "  const openWorkspace = useCallback(() => setView('workspace'), []);",
-    "  const openGettingStarted = useCallback(() => {",
-    "    setView('getting-started');",
-    "    if (typeof window !== 'undefined') window.scrollTo({ top: 0, behavior: 'smooth' });",
-    "  }, []);",
-    "  const handleNavSelect = useCallback((id: NavItem) => {",
-    "    if (id === 'getting-started') openGettingStarted();",
-    "    else openWorkspace();",
-    "  }, [openGettingStarted, openWorkspace]);",
     "",
     "  useEffect(() => {",
     "    let active = true;",
@@ -5917,229 +5971,139 @@ function platformAppTsx(application, options) {
     "      .catch((error) => {",
     "        if (!active) return;",
     "        setServiceIdentityError(errorMessage(error));",
-    "        setLoading(false);",
     "      });",
     "    return () => {",
     "      active = false;",
     "    };",
     "  }, []);",
     "",
-    "  useEffect(() => {",
-    "    if (!auth) return;",
-    "    let active = true;",
-    "    const syncAuth = async () => {",
-    "      const publicRoute = route.kind === 'root' || route.kind === 'login';",
-    "      if (publicRoute) setLoading(false);",
-    "      else 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({",
-    "        cookieRefresh: publicRoute ? 'background' : 'blocking',",
-    "      });",
-    "      if (!active) return;",
-    "      setUser(nextUser);",
-    "      setLoading(false);",
-    "    };",
-    "",
-    "    void syncAuth().catch((error) => {",
-    "      if (!active) return;",
-    "      setAuthError(errorMessage(error));",
-    "      setLoading(false);",
-    "    });",
-    "    return () => {",
-    "      active = false;",
-    "    };",
-    "  }, [auth, route.kind]);",
-    "",
-    "  useEffect(() => {",
-    "    if (!auth) return;",
-    "    const handleSessionUpdated = () => {",
-    "      const nextUser = auth.authClient.getHydratedCurrentUser() || auth.authClient.getTokenIdentity();",
-    "      if (nextUser) setUser(nextUser);",
-    "    };",
-    "    window.addEventListener('auth:session-updated', handleSessionUpdated);",
-    "    return () => window.removeEventListener('auth:session-updated', handleSessionUpdated);",
-    "  }, [auth]);",
+    "  const auth = useMemo(() => serviceId ? createTopoloAuth({",
+    "    authServiceUrl: AUTH_URL,",
+    "    serviceId,",
+    "    devSessionKey: `${serviceId}_session`,",
+    "    callbackPath: '/auth/callback',",
+    "    sessionStorageRestoreEnabled: import.meta.env.DEV,",
+    "    debug: import.meta.env.DEV,",
+    "  }) : null, [serviceId]);",
     "",
-    "  useEffect(() => {",
-    "    if (!loading && user && route.kind === 'login') {",
-    "      window.location.replace('/');",
-    "    }",
-    "  }, [loading, route.kind, user]);",
-    "",
-    "  const shellUser = useMemo(() => toShellUser(user), [user]);",
-    "  const activeServiceId = serviceId || SCAFFOLD_SERVICE_SLUG;",
-    "",
-    "  if (!auth) {",
-    "    if (serviceIdentityError) {",
-    "      return (",
-    "        <TopoloAuthFlowScreen",
-    "          appName={APP_NAME}",
-    "          appId={APP_ID}",
-    "          serviceId={SCAFFOLD_SERVICE_SLUG}",
-    '          status="error"',
-    '          title="Service identity unavailable"',
-    "          message={serviceIdentityError}",
-    '          actionLabel="Retry"',
-    "          onAction={() => window.location.reload()}",
-    "        />",
-    "      );",
-    "    }",
-    "    return (",
-    "      <TopoloLoadingScreen",
-    "        appId={APP_ID}",
-    "        serviceId={SCAFFOLD_SERVICE_SLUG}",
-    "        appName={APP_NAME}",
-    "        subtitle={`Loading ${APP_NAME}...`}",
-    "      />",
-    "    );",
-    "  }",
-    "",
-    "  if (route.kind === 'callback') {",
-    "    if (loading) {",
-    "      return (",
-    "        <TopoloLoadingScreen",
-    "          appId={APP_ID}",
-    "          serviceId={activeServiceId}",
-    "          appName={APP_NAME}",
-    '          subtitle="Completing secure sign-in..."',
-    "        />",
-    "      );",
-    "    }",
+    "  const routes = useMemo<TopoloAppRoute[]>(() => serviceId ? [",
+    "    {",
+    "      path: '/workspace',",
+    "      nav: { id: 'home', label: '" + escapeSingleQuoted(workspaceTitle) + "' },",
+    "      loading: { shell: 'topbar', content: 'workspace', title: '" + escapeSingleQuoted(workspaceTitle) + "' },",
+    "      element: <ScaffoldWorkspace />,",
+    "    },",
+    "    {",
+    "      path: '/getting-started',",
+    "      nav: { id: 'getting-started', label: 'Getting started' },",
+    "      loading: { shell: 'topbar', content: 'card-grid', title: 'Getting started' },",
+    "      element: <ScaffoldGettingStartedRoute serviceId={serviceId} />,",
+    "    },",
+    "  ] : [], [serviceId]);",
     "",
+    "  if (serviceIdentityError) {",
     "    return (",
     "      <TopoloAuthFlowScreen",
     "        appName={APP_NAME}",
     "        appId={APP_ID}",
-    "        serviceId={activeServiceId}",
+    "        serviceId={SCAFFOLD_SERVICE_SLUG}",
     '        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')}",
+    '        title="Service identity unavailable"',
+    "        message={serviceIdentityError}",
+    '        actionLabel="Retry"',
+    "        onAction={() => window.location.reload()}",
     "      />",
     "    );",
     "  }",
     "",
-    "  if (loading) {",
+    "  if (!auth) {",
     "    return (",
-    "      <TopoloLoadingScreen",
+    "      <TopoloAppLoadingScaffold",
     "        appId={APP_ID}",
-    "        serviceId={activeServiceId}",
+    "        serviceId={SCAFFOLD_SERVICE_SLUG}",
     "        appName={APP_NAME}",
+    "        layout={{ shell: 'topbar', content: 'workspace' }}",
     "        subtitle={`Loading ${APP_NAME}...`}",
     "      />",
     "    );",
     "  }",
     "",
-    "  if (!user) {",
-    "    if (route.kind === 'login') {",
-    "      return (",
+    "  return (",
+    "    <TopoloAppRoot",
+    "      appName={APP_NAME}",
+    "      serviceId={serviceId}",
+    "      auth={auth}",
+    "      routes={routes}",
+    '      home="/workspace"',
+    "      publicLanding={",
+    "        <LandingPage",
+    "          serviceId={serviceId}",
+    "          authApiUrl={AUTH_URL}",
+    "          config={LANDING_CONFIG}",
+    "          onCTAClick={() => window.location.assign('/login')}",
+    "        />",
+    "      }",
+    "      loginElement={",
     "        <LoginPage",
-    "          serviceId={activeServiceId}",
+    "          serviceId={serviceId}",
     "          authApiUrl={AUTH_URL}",
     "          config={LOGIN_CONFIG}",
-    "          isLoading={loginAttempted}",
     "          onLogin={async (provider) => {",
-    "            setLoginAttempted(true);",
-    "            try {",
-    "              await auth.authClient.login(provider || 'topolo');",
-    "            } catch {",
-    "              setLoginAttempted(false);",
-    "            }",
+    "            await auth.login(provider || 'topolo');",
     "          }}",
     "          onPasswordLogin={async (request) => {",
-    "            const result = await auth.authClient.loginWithPassword(request);",
-    "            if (!result.authenticated) {",
-    "              return result;",
-    "            }",
-    "            setUser(result.user ?? null);",
-    "            window.location.replace('/');",
+    "            const result = await auth.loginWithPassword(request);",
+    "            if (!result.authenticated) return result;",
+    "            window.dispatchEvent(new CustomEvent('auth:session-updated', { detail: { tokens: result.tokens, user: result.user } }));",
     "            return undefined;",
     "          }}",
     "        />",
-    "      );",
-    "    }",
-    "",
-    "    return (",
-    "      <LandingPage",
-    "        serviceId={activeServiceId}",
-    "        authApiUrl={AUTH_URL}",
-    "        config={LANDING_CONFIG}",
-    "        onCTAClick={() => window.location.assign('/login')}",
-    "      />",
-    "    );",
-    "  }",
-    "",
-    "  if (route.kind === 'login') {",
-    "    return (",
-    "      <TopoloLoadingScreen",
-    "        appId={APP_ID}",
-    "        serviceId={activeServiceId}",
-    "        appName={APP_NAME}",
-    `        subtitle="Opening your ${escapeDoubleQuoted(signedSurfaceLabel)}..."`,
-    "      />",
-    "    );",
-    "  }",
-    "",
-    "  return (",
-    "    <TopoloAppShell<NavItem>",
-    "      appId={APP_ID}",
-    "      serviceId={activeServiceId}",
-    "      appName={APP_NAME}",
-    "      user={shellUser}",
-    "      orgId={user.activeContextType === 'organization' ? user.activeContextId ?? user.orgId ?? null : null}",
-    "      activeContextType={user.activeContextType}",
-    "      activeContextId={user.activeContextId}",
-    "      activeNavItemId={view === 'getting-started' ? 'getting-started' : 'home'}",
-    `      navItems={[{ id: 'home', label: '${escapeSingleQuoted(workspaceTitle)}' }, { id: 'getting-started', label: 'Getting started' }]}`,
-    '      navigationMode="topbar"',
-    "      onNavItemSelect={handleNavSelect}",
-    `      title={view === 'getting-started' ? 'Getting started' : '${escapeSingleQuoted(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",
-    "    >",
-    "      {view === 'getting-started' ? (",
-    "        <ScaffoldGettingStarted",
-    "          serviceId={activeServiceId}",
-    "          organizationId={user.organization?.id ?? user.orgId ?? ''}",
-    "          role={user.role}",
-    "          onOpenWorkspace={openWorkspace}",
+    "      }",
+    "      loadingFallback={({ loading }) => (",
+    "        <TopoloAppLoadingScaffold",
+    "          appId={APP_ID}",
+    "          serviceId={serviceId}",
+    "          appName={APP_NAME}",
+    "          layout={{ shell: loading?.shell || 'topbar', content: loading?.content || 'workspace' }}",
+    "          title={loading?.title}",
+    "          subtitle={`Loading ${APP_NAME}...`}",
     "        />",
-    "      ) : (",
-    '        <div className="topolo-starter-workspace">',
-    '          <section className="topolo-starter-card" data-tour="workspace-card">',
-    `            <h2>${baselineHeading}</h2>`,
-    "            <p>",
-    `              ${baselineDescription}`,
-    "            </p>",
-    "          </section>",
-    "        </div>",
     "      )}",
+    "      shell={{",
+    "        appId: APP_ID,",
+    "        authUrl: AUTH_URL,",
+    "        navigationMode: 'topbar',",
+    "        title: APP_NAME,",
+    "        commandPlaceholder: `Search ${APP_NAME}`,",
+    "        bugReporterAppName: APP_NAME,",
+    "        enableCommandPalette: true,",
+    "        enableBugReporter: true,",
+    "      }}",
+    "    />",
+    "  );",
+    "}",
+    "",
+    "function ScaffoldWorkspace() {",
+    "  const { user } = useAuth();",
+    "  const openWorkspace = useCallback(() => {",
+    "    window.history.pushState({}, '', '/workspace');",
+    "    window.dispatchEvent(new PopStateEvent('popstate'));",
+    "  }, []);",
+    "  const openGettingStarted = useCallback(() => {",
+    "    window.history.pushState({}, '', '/getting-started');",
+    "    window.dispatchEvent(new PopStateEvent('popstate'));",
+    "  }, []);",
+    "  return (",
+    '    <div className="topolo-starter-workspace">',
+    '      <section className="topolo-starter-card" data-tour="workspace-card">',
+    `        <h2>${baselineHeading}</h2>`,
+    "        <p>",
+    `          ${baselineDescription}`,
+    "        </p>",
+    "      </section>",
     "      <IntroTour",
     "        appName={APP_NAME}",
-    "        role={user.role}",
+    "        role={user?.role}",
     "        onOpenGettingStarted={openGettingStarted}",
     "        extraSteps={[",
     "          {",
@@ -6152,7 +6116,20 @@ function platformAppTsx(application, options) {
     "          },",
     "        ]}",
     "      />",
-    "    </TopoloAppShell>",
+    "    </div>",
+    "  );",
+    "}",
+    "",
+    "function ScaffoldGettingStartedRoute({ serviceId }: { serviceId: string }) {",
+    "  const { user, tokens } = useAuth();",
+    "  return (",
+    "    <ScaffoldGettingStarted",
+    "      serviceId={serviceId}",
+    "      organizationId={String((user as any)?.organization?.id ?? user?.orgId ?? '')}",
+    "      role={user?.role}",
+    "      getAccessToken={() => tokens?.accessToken ?? null}",
+    "      onOpenWorkspace={() => window.location.assign('/workspace')}",
+    "    />",
     "  );",
     "}",
     "",
@@ -6160,15 +6137,16 @@ function platformAppTsx(application, options) {
     "  serviceId: string;",
     "  organizationId: string;",
     "  role?: string;",
+    "  getAccessToken: () => string | null;",
     "  onOpenWorkspace: () => void;",
     "}) {",
-    "  const { serviceId, organizationId, role, onOpenWorkspace } = props;",
+    "  const { serviceId, organizationId, role, getAccessToken, onOpenWorkspace } = props;",
     "  const steps: OnboardingGuideStep[] = [",
     "    {",
     "      id: 'explore-workspace',",
     "      title: 'Explore your workspace',",
     "      description:",
-    "        'Your app renders inside the shared Topolo shell \u2014 launcher, command palette, and account menu are already wired in.',",
+    "        'Your workspace lives in the Topolo shell \u2014 the launcher, command palette, and account menu are all one click away.',",
     "      actionLabel: 'Open workspace',",
     "      onAction: onOpenWorkspace,",
     "    },",
@@ -6181,9 +6159,9 @@ function platformAppTsx(application, options) {
     "    },",
     "    {",
     "      id: 'build-feature',",
-    "      title: 'Build your first feature',",
+    "      title: 'Make it your own',",
     "      description:",
-    "        'Replace the starter card with your product surface, and gate write actions with service scopes before you ship.',",
+    "        'Open the account menu to adjust your settings and theme \u2014 your preferences stay in sync across every Topolo app.',",
     "    },",
     "  ];",
     "  return (",
@@ -6192,7 +6170,7 @@ function platformAppTsx(application, options) {
     "        authApiBaseUrl={`${AUTH_URL}/api`}",
     "        organizationId={organizationId}",
     "        serviceId={serviceId}",
-    "        getAccessToken={() => getAccessToken()}",
+    "        getAccessToken={getAccessToken}",
     "        role={role || undefined}",
     "        steps={steps}",
     "        eyebrow={`Welcome to ${APP_NAME}`}",
@@ -6208,13 +6186,6 @@ function platformAppTsx(application, options) {
     "  );",
     "}",
     "",
-    "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.';",
@@ -6761,6 +6732,9 @@ function platformWorkerTs(application, options) {
     "  return [",
     "    {",
     "      type: 'quick-actions',",
+    "      snapshot: {",
+    "        summary: `${SCAFFOLD_APP_NAME} is ready for workspace operations and exposes health checks for operators.`,",
+    "      },",
     "      actions: [",
     `        { id: 'open-workspace', label: '${escapeSingleQuoted(openActionLabel)}', link: '/', primary: true },`,
     "        { id: 'view-health', label: 'View health', link: '/api/health' },",
@@ -6872,6 +6846,9 @@ function developerWorkerTs(application) {
     "  return [",
     "    {",
     "      type: 'quick-actions',",
+    "      snapshot: {",
+    "        summary: `${SERVICE_NAME} is ready for workspace operations and exposes health checks for operators.`,",
+    "      },",
     "      actions: [",
     "        { id: 'open-app', label: `Open ${SERVICE_NAME}`, link: '/', primary: true },",
     "        { id: 'view-health', label: 'View health', link: '/api/health' },",
@@ -7438,7 +7415,7 @@ function internalDocs(application, options) {
     "",
     "## Architecture",
     "",
-    "The generated browser surface in `apps/web` uses `@topolo-io/ui-kit` for the shared landing page, shared login page, auth callback state, and shared signed shell. `apps/web/vite.config.ts` includes the standard React plugin plus React runtime dedupe so linked Topolo packages resolve a single browser React runtime.",
+    "The generated browser surface in `apps/web` uses `@topolo-io/app-funnel` for the shared public landing page, `@topolo-io/app-shell` for shared login, auth callback state, and signed shell, `@topolo-io/app-launcher` for app switching, and `@topolo-io/ui-kit` for shared primitives. `apps/web/vite.config.ts` includes the standard React plugin plus React runtime dedupe so linked Topolo packages resolve a single browser React runtime.",
     options.api ? `The generated app keeps browser service identity in \`${appPath}/apps/web/src/service-identity.ts\` and API runtime service identity in \`${appPath}/apps/api/src/service-identity.ts\`. Runtime code reads the provisioned Auth service id from the API Worker \`SERVICE_ID\` binding and exposes it to the browser through the same-origin service-identity route forwarded by the web Worker.` : `The generated app centralizes browser service identity in \`${appPath}/apps/web/src/service-identity.ts\` and reads Auth identity from the app runtime instead of calling Auth for slug lookups.`,
     "",
     "## Runtime Surfaces",
@@ -7843,9 +7820,6 @@ function escapeHtml(value) {
 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, '\\"');
 }
@@ -7959,17 +7933,17 @@ async function provisionApplicationScaffold(payload) {
     developersOrigin,
     developersApp: {
       id: appId,
-      slug: readString(app.slug),
-      listingStatus: readString(app.listingStatus),
-      organizationId: readString(app.organizationId)
+      slug: readString2(app.slug),
+      listingStatus: readString2(app.listingStatus),
+      organizationId: readString2(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)
+      status: readString2(service.status),
+      baseUrl: readString2(service.base_url) ?? readString2(service.baseUrl)
     } : null,
     authConfig: authConfig ? {
       login: authConfig.login === true,
@@ -8035,7 +8009,7 @@ async function resolveServiceIdBySlug(authOrigin, slug) {
 function pickRecord(value) {
   return value && typeof value === "object" ? value : null;
 }
-function readString(value) {
+function readString2(value) {
   if (typeof value !== "string") {
     return null;
   }
@@ -8043,7 +8017,7 @@ function readString(value) {
   return trimmed ? trimmed : null;
 }
 function readRequiredString(value, message) {
-  const resolved = readString(value);
+  const resolved = readString2(value);
   if (!resolved) {
     throw new Error(message);
   }
@@ -8818,7 +8792,9 @@ function buildRows(catalog, overrides, environment = selectedEnvironment()) {
       effectiveUrl,
       overridden: Boolean(configuredUrl && configuredUrl !== defaultUrl),
       environmentSafe: environment !== "staging" || !effectiveUrl || isStagingUrl(effectiveUrl),
-      permissions: [...entry.permissions]
+      permissions: [...entry.permissions],
+      apiKeyResource: entry.apiKeyResource,
+      apiKeyResources: [...entry.apiKeyResources]
     };
   }).sort((left, right) => left.id.localeCompare(right.id));
 }
@@ -8828,12 +8804,13 @@ function formatRows2(rows, environment = selectedEnvironment()) {
   const lines = [];
   lines.push(`Environment: ${environment}`);
   lines.push("");
-  lines.push(`${"ID".padEnd(idWidth)}  ${"URL".padEnd(urlWidth)}  OVERRIDE  READY`);
-  lines.push(`${"-".repeat(idWidth)}  ${"-".repeat(urlWidth)}  --------  -----`);
+  lines.push(`${"ID".padEnd(idWidth)}  ${"URL".padEnd(urlWidth)}  OVERRIDE  READY  API KEY RESOURCE`);
+  lines.push(`${"-".repeat(idWidth)}  ${"-".repeat(urlWidth)}  --------  -----  ----------------`);
   for (const r of rows) {
     const effectiveUrl = r.effectiveUrl ?? "-";
+    const apiKeyResource = r.apiKeyResources.length > 0 ? r.apiKeyResources.map((resource) => `${resource.resourceType}:${resource.canonicalResourceType}`).join(",") : "-";
     lines.push(
-      `${r.id.padEnd(idWidth)}  ${effectiveUrl.padEnd(urlWidth)}  ${r.overridden ? "yes" : "".padEnd(8)}  ${r.environmentSafe ? "yes" : "no"}`
+      `${r.id.padEnd(idWidth)}  ${effectiveUrl.padEnd(urlWidth)}  ${r.overridden ? "yes" : "".padEnd(8)}  ${r.environmentSafe ? "yes" : "no"}    ${apiKeyResource}`
     );
   }
   return lines.join("\n");