@topolo/cli 0.1.16 → 0.1.18

package/README.md

@@ -9,6 +9,7 @@ via `stdin`/`stdout`.
 - API-key authentication (long-lived, service-scoped).
 - Access-token authentication via OAuth device flow when a CLI OAuth client id is configured.
 - Stored access-token refresh when the config includes a refresh token and OAuth client id.
+- First-class `production` and `staging` CLI environments with separate stored credentials, OAuth client ids, and service URL overrides.
 - Commands: `auth login/logout/status`, `whoami`, `apps`, `apps scaffold`, `services`, `crm contacts:list`, `crm contacts:get`, and generic `api` passthrough for SDK-registered services.
 
 ## Install
@@ -23,9 +24,19 @@ npx @topolo/cli whoami
 
 Credentials come from (in priority order):
 
-1. `TOPOLO_API_KEY` env var
-2. `TOPOLO_ACCESS_TOKEN` env var
-3. Config file (`$XDG_CONFIG_HOME/topolo/config.json`, mode `0600`)
+1. Environment-specific vars such as `TOPOLO_STAGING_API_KEY` or `TOPOLO_PRODUCTION_ACCESS_TOKEN`
+2. Global vars `TOPOLO_API_KEY` or `TOPOLO_ACCESS_TOKEN`
+3. The selected environment profile in the config file (`$XDG_CONFIG_HOME/topolo/config.json`, mode `0600`)
+
+Production is the default. Select staging with `--env staging` anywhere in the command, or set `TOPOLO_ENV=staging`:
+
+```bash
+topolo auth status --env staging --json
+topolo auth login --env staging --client-id doac_...
+topolo platform apps scaffold home --env staging --write --json
+```
+
+The staging profile uses `auth.stg.topolo.us`, `developers.stg.topolo.us`, and `seed.stg.topolo.us` by default. Other SDK service calls in staging must have an explicit staging URL override; the CLI refuses to call a production SDK URL while `--env staging` is selected.
 
 For interactive use:
 
@@ -38,7 +49,8 @@ topolo auth logout           # clears the stored credential
 
 If no client id is configured, `topolo auth login` falls back to an API-key
 prompt in an interactive terminal. Non-interactive sessions should pass
-`--api-key` or set `TOPOLO_CLI_CLIENT_ID`.
+`--api-key` or set `TOPOLO_PRODUCTION_CLI_CLIENT_ID`,
+`TOPOLO_STAGING_CLI_CLIENT_ID`, or the shared `TOPOLO_CLI_CLIENT_ID`.
 
 ## Cross-org isolation
 
@@ -97,9 +109,13 @@ topolo crm contacts:get contact_abc123
 ### `topolo services`
 
 Lists every service id and effective URL known to the generated SDK registry.
+In staging, `environmentSafe: false` means that service still resolves to a
+production SDK default and will be refused by `topolo api` until a staging URL
+override is configured.
 
 ```bash
 topolo services --json
+topolo services --env staging --json
 ```
 
 ### `topolo apps`

package/dist/index.js

@@ -75,13 +75,16 @@ var SERVICES = {
   chat: "https://chat.topolo.app",
   commerce: "https://commerce-api.topolo.app",
   compose: "https://compose.topolo.app",
+  consent: "https://consent.topolo.app",
   crm: "https://crm-api.topolo.app",
   customer_success: "https://success.topolo.app",
+  developers: "https://developers.topolo.app",
   director: "https://director.topolo.app",
   feed: "https://feed-api.topolo.app",
   flow: "https://flow.topolo.app",
   forecast: "https://forecast-api.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",
@@ -112,11 +115,14 @@ var PLATFORM_SERVICE_IDS = {
   books: "srv_topolo_books",
   bugfix: "srv_topolo_bugfix",
   compose: "srv_topolo_compose",
+  consent: "srv_topolo_consent",
   crm: "srv_iCwM4jGXcwlj",
   customer_success: "srv_topolo_success",
+  developers: "svc_topolo_developers",
   director: "srv_topolo_director",
   flow: "srv_topolo_flow",
   forms: "srv_topolo_forms",
+  home: "srv_topolo_home",
   insights: "srv_topolo_insights",
   inventory: "srv_topolo_inventory",
   localize: "srv_topolo_localize",
@@ -449,6 +455,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "consent": {
+    "id": "consent",
+    "appDir": "TopoloConsent",
+    "name": "topolo-consent",
+    "packageName": "topolo-consent",
+    "productionUrl": "https://consent.topolo.app",
+    "services": [
+      "consent"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-consent",
+        "kind": "worker",
+        "apiUrl": "https://consent.topolo.app",
+        "domains": [
+          "consent.topolo.app"
+        ],
+        "routes": [
+          "consent.topolo.app"
+        ],
+        "serviceId": "consent"
+      }
+    ]
+  },
   "crm": {
     "id": "crm",
     "appDir": "TopoloCRM",
@@ -529,7 +559,9 @@ var APPLICATIONS = {
     "name": "topolo-developers",
     "packageName": "topolo-developers",
     "productionUrl": "https://developers.topolo.app",
-    "services": [],
+    "services": [
+      "developers"
+    ],
     "deployTargets": [
       {
         "name": "topolo-catalog-cron",
@@ -541,13 +573,13 @@ var APPLICATIONS = {
       },
       {
         "name": "topolo-developers",
-        "kind": "pages",
-        "apiUrl": null,
+        "kind": "worker",
+        "apiUrl": "https://developers.topolo.app",
         "domains": [
           "developers.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "developers"
       }
     ]
   },
@@ -711,6 +743,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "home": {
+    "id": "home",
+    "appDir": "TopoloHome",
+    "name": "topolo-home",
+    "packageName": "topolo-home",
+    "productionUrl": "https://home.topolo.app",
+    "services": [
+      "home"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-home",
+        "kind": "worker",
+        "apiUrl": "https://home.topolo.app",
+        "domains": [
+          "home.topolo.app"
+        ],
+        "routes": [
+          "home.topolo.app"
+        ],
+        "serviceId": "home"
+      }
+    ]
+  },
   "insights": {
     "id": "insights",
     "appDir": "TopoloInsights",
@@ -2167,6 +2223,16 @@ import { mkdir, readFile, writeFile, chmod } from "fs/promises";
 import { existsSync } from "fs";
 import { homedir, platform } from "os";
 import { dirname, join } from "path";
+var ENVIRONMENT_DEFAULT_SERVICE_URLS = {
+  production: {
+    developers: "https://developers.topolo.app"
+  },
+  staging: {
+    auth: "https://auth.stg.topolo.us",
+    developers: "https://developers.stg.topolo.us",
+    seed: "https://seed.stg.topolo.us"
+  }
+};
 function configPath() {
   const override = process.env.TOPOLO_CONFIG_PATH;
   if (override) return override;
@@ -2194,31 +2260,113 @@ async function writeConfig(config) {
     }
   }
 }
-async function resolveCredential() {
-  const apiKey = process.env.TOPOLO_API_KEY;
+function normalizeEnvironment(value) {
+  const normalized = (value ?? "production").trim().toLowerCase();
+  if (normalized === "" || normalized === "production" || normalized === "prod") {
+    return "production";
+  }
+  if (normalized === "staging" || normalized === "stage" || normalized === "stg") {
+    return "staging";
+  }
+  throw new Error(`Unknown Topolo environment "${value}". Expected production or staging.`);
+}
+function selectedEnvironment() {
+  return normalizeEnvironment(process.env.TOPOLO_ENV);
+}
+function envVarPrefix(environment) {
+  return environment === "production" ? "TOPOLO_PRODUCTION" : "TOPOLO_STAGING";
+}
+function environmentLabel(environment = selectedEnvironment()) {
+  return environment === "production" ? "production" : "staging";
+}
+function developerConsoleUrl(environment = selectedEnvironment()) {
+  return environment === "production" ? "https://developers.topolo.app" : "https://developers.stg.topolo.us";
+}
+function oauthClientRegistrationUrl(environment = selectedEnvironment()) {
+  return `${developerConsoleUrl(environment)}/developers/oauth-clients`;
+}
+function apiKeyIssuanceUrl(environment = selectedEnvironment()) {
+  return `${developerConsoleUrl(environment)}/credentials`;
+}
+function profileForEnvironment(config, environment = selectedEnvironment()) {
+  const profile = config.profiles?.[environment] ?? {};
+  if (environment === "production") {
+    return {
+      credential: config.credential,
+      oauthClientId: config.oauthClientId,
+      ...profile,
+      serviceUrls: {
+        ...config.serviceUrls ?? {},
+        ...profile.serviceUrls ?? {}
+      },
+      agentName: profile.agentName ?? config.agentName
+    };
+  }
+  return profile;
+}
+function writeProfileConfig(config, environment, profile) {
+  const profiles = { ...config.profiles ?? {} };
+  profiles[environment] = {
+    ...profiles[environment] ?? {},
+    ...profile
+  };
+  return { ...config, profiles };
+}
+function clearProfileCredential(config, environment) {
+  const next = { ...config };
+  if (environment === "production") {
+    delete next.credential;
+    delete next.oauthClientId;
+  }
+  const profiles = { ...config.profiles ?? {} };
+  const profile = { ...profiles[environment] ?? {} };
+  delete profile.credential;
+  delete profile.oauthClientId;
+  profiles[environment] = profile;
+  return { ...next, profiles };
+}
+function resolveOAuthClientId(config, environment = selectedEnvironment()) {
+  const envSpecific = process.env[`${envVarPrefix(environment)}_CLI_CLIENT_ID`];
+  if (envSpecific) return envSpecific;
+  if (process.env.TOPOLO_CLI_CLIENT_ID) return process.env.TOPOLO_CLI_CLIENT_ID;
+  return profileForEnvironment(config, environment).oauthClientId;
+}
+function credentialSource(config, environment = selectedEnvironment()) {
+  const prefix = envVarPrefix(environment);
+  if (process.env[`${prefix}_API_KEY`]) return `env:${prefix}_API_KEY`;
+  if (process.env[`${prefix}_ACCESS_TOKEN`]) return `env:${prefix}_ACCESS_TOKEN`;
+  if (process.env.TOPOLO_API_KEY) return "env:TOPOLO_API_KEY";
+  if (process.env.TOPOLO_ACCESS_TOKEN) return "env:TOPOLO_ACCESS_TOKEN";
+  return profileForEnvironment(config, environment).credential ? "config-file" : "none";
+}
+async function resolveCredential(environment = selectedEnvironment()) {
+  const prefix = envVarPrefix(environment);
+  const apiKey = process.env[`${prefix}_API_KEY`] ?? process.env.TOPOLO_API_KEY;
   if (apiKey) return { kind: "api_key", apiKey };
-  const accessToken = process.env.TOPOLO_ACCESS_TOKEN;
+  const accessToken = process.env[`${prefix}_ACCESS_TOKEN`] ?? process.env.TOPOLO_ACCESS_TOKEN;
   if (accessToken) return { kind: "access_token", accessToken };
   const config = await readConfig();
-  return config.credential ?? null;
+  return profileForEnvironment(config, environment).credential ?? null;
 }
 var REFRESH_SKEW_SECONDS = 60;
-async function refreshCredentialIfNeeded() {
-  if (process.env.TOPOLO_API_KEY || process.env.TOPOLO_ACCESS_TOKEN) {
-    return resolveCredential();
+async function refreshCredentialIfNeeded(environment = selectedEnvironment()) {
+  const prefix = envVarPrefix(environment);
+  if (process.env[`${prefix}_API_KEY`] || process.env[`${prefix}_ACCESS_TOKEN`] || process.env.TOPOLO_API_KEY || process.env.TOPOLO_ACCESS_TOKEN) {
+    return resolveCredential(environment);
   }
   const config = await readConfig();
-  const cred = config.credential;
+  const profile = profileForEnvironment(config, environment);
+  const cred = profile.credential;
   if (!cred || cred.kind !== "access_token") return cred ?? null;
-  if (!cred.refreshToken || !cred.expiresAt || !config.oauthClientId) return cred;
+  if (!cred.refreshToken || !cred.expiresAt || !profile.oauthClientId) return cred;
   const now = Math.floor(Date.now() / 1e3);
   if (cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
   try {
     const oauth = new TopoloOAuth({
-      serviceUrls: resolveServiceUrls(config.serviceUrls)
+      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
     });
     const tokens = await oauth.refreshToken({
-      clientId: config.oauthClientId,
+      clientId: profile.oauthClientId,
       refreshToken: cred.refreshToken
     });
     const refreshed = {
@@ -2227,7 +2375,9 @@ async function refreshCredentialIfNeeded() {
       ...tokens.refresh_token ? { refreshToken: tokens.refresh_token } : { refreshToken: cred.refreshToken },
       expiresAt: Math.floor(Date.now() / 1e3) + tokens.expires_in
     };
-    await writeConfig({ ...config, credential: refreshed });
+    await writeConfig(
+      environment === "production" && !config.profiles?.production ? { ...config, credential: refreshed } : writeProfileConfig(config, environment, { credential: refreshed })
+    );
     return refreshed;
   } catch {
     return cred;
@@ -2236,10 +2386,17 @@ async function refreshCredentialIfNeeded() {
 function resolveAgentName(configAgentName) {
   return process.env.TOPOLO_AGENT_NAME ?? configAgentName;
 }
-function resolveServiceUrls(configUrls) {
+function resolveServiceUrls(configUrls, environment = selectedEnvironment()) {
   const merged = {
+    ...ENVIRONMENT_DEFAULT_SERVICE_URLS[environment],
     ...configUrls ?? {}
   };
+  const prefix = `${envVarPrefix(environment)}_SERVICE_URL_`;
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith(prefix) && v) {
+      merged[k.slice(prefix.length).toLowerCase()] = v;
+    }
+  }
   for (const [k, v] of Object.entries(process.env)) {
     if (k.startsWith("TOPOLO_SERVICE_URL_") && v) {
       merged[k.slice("TOPOLO_SERVICE_URL_".length).toLowerCase()] = v;
@@ -2247,6 +2404,28 @@ function resolveServiceUrls(configUrls) {
   }
   return Object.keys(merged).length > 0 ? merged : void 0;
 }
+function resolvedProfileConfig(config, environment = selectedEnvironment()) {
+  const profile = profileForEnvironment(config, environment);
+  return {
+    credential: profile.credential,
+    oauthClientId: profile.oauthClientId,
+    agentName: profile.agentName,
+    serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
+  };
+}
+function assertServiceUrlForEnvironment(service, serviceUrl, environment = selectedEnvironment()) {
+  if (environment !== "staging") return;
+  if (!serviceUrl) {
+    throw new Error(`No staging URL is configured for Topolo service "${service}".`);
+  }
+  const url = serviceUrl.toLowerCase();
+  if (url.includes(".stg.topolo.us") || url.includes("localhost") || url.includes("127.0.0.1") || url.includes("topolo-staging")) {
+    return;
+  }
+  throw new Error(
+    `Refusing to call ${service} in staging because its effective URL is not a staging endpoint: ${serviceUrl}`
+  );
+}
 
 // src/output.ts
 function resolveOutputMode(override) {
@@ -2293,38 +2472,38 @@ function normalizeError(err) {
 }
 
 // src/commands/auth.ts
-var API_KEY_ISSUANCE_URL = "https://developers.topolo.app/credentials";
-var OAUTH_CLIENT_REGISTRATION_URL = "https://developers.topolo.app/developers/oauth-clients";
 function registerAuthCommands(program2) {
   const auth = program2.command("auth").description("Manage Topolo credentials");
   auth.command("login").description("Authenticate with Topolo via OAuth device flow (default) or store an API key").option("--api-key <key>", "Store an API key directly, skipping the OAuth flow").option("--client-id <id>", "OAuth client_id (or set TOPOLO_CLI_CLIENT_ID)").option("--scope <scope>", "Scopes to request (space-separated)").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(
     async (opts) => {
       const mode = resolveOutputMode(opts.json);
+      const environment = selectedEnvironment();
       try {
         if (opts.apiKey) {
-          await storeApiKey(opts.apiKey.trim(), mode);
+          await storeApiKey(opts.apiKey.trim(), environment, mode);
           return;
         }
-        const clientId = opts.clientId ?? process.env.TOPOLO_CLI_CLIENT_ID;
+        const config = await readConfig();
+        const clientId = opts.clientId ?? resolveOAuthClientId(config, environment);
         if (!clientId) {
           if (!input.isTTY) {
             throw new Error(
-              `No OAuth client_id configured and stdin is not a TTY. Either register an OAuth client at ${OAUTH_CLIENT_REGISTRATION_URL} and export TOPOLO_CLI_CLIENT_ID, or pass --api-key <key> (mint one at ${API_KEY_ISSUANCE_URL}).`
+              `No OAuth client_id configured and stdin is not a TTY. Either register an OAuth client at ${oauthClientRegistrationUrl(environment)} and export TOPOLO_${environment === "staging" ? "STAGING" : "PRODUCTION"}_CLI_CLIENT_ID, or pass --api-key <key> (mint one at ${apiKeyIssuanceUrl(environment)}).`
             );
           }
           process.stderr.write(
-            `No OAuth client_id configured. Falling back to API key.
-Visit ${API_KEY_ISSUANCE_URL} to mint one, or configure an OAuth client at ${OAUTH_CLIENT_REGISTRATION_URL} and set TOPOLO_CLI_CLIENT_ID.
+            `No OAuth client_id configured for ${environmentLabel(environment)}. Falling back to API key.
+Visit ${apiKeyIssuanceUrl(environment)} to mint one, or configure an OAuth client at ${oauthClientRegistrationUrl(environment)} and set the environment-specific CLI client id.
 `
           );
           const rl = createInterface({ input, output: process.stderr });
           const apiKey = (await rl.question("Paste API key: ")).trim();
           rl.close();
           if (!apiKey) throw new Error("API key is required");
-          await storeApiKey(apiKey, mode);
+          await storeApiKey(apiKey, environment, mode);
           return;
         }
-        await runDeviceFlow({ clientId, scope: opts.scope, mode });
+        await runDeviceFlow({ clientId, environment, scope: opts.scope, mode });
       } catch (err) {
         fail(err, mode);
       }
@@ -2332,40 +2511,65 @@ Visit ${API_KEY_ISSUANCE_URL} to mint one, or configure an OAuth client at ${OAU
   );
   auth.command("logout").description("Remove stored credentials from this machine").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
+    const environment = selectedEnvironment();
     try {
       const config = await readConfig();
-      delete config.credential;
-      await writeConfig(config);
-      emit({ ok: true }, mode, () => "Logged out.");
+      await writeConfig(clearProfileCredential(config, environment));
+      emit(
+        { ok: true, environment },
+        mode,
+        () => `Logged out of Topolo ${environmentLabel(environment)}.`
+      );
     } catch (err) {
       fail(err, mode);
     }
   });
   auth.command("status").description("Show which credential source is in use (env vs config file)").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
+    const environment = selectedEnvironment();
     try {
-      const source = process.env.TOPOLO_API_KEY ? "env:TOPOLO_API_KEY" : process.env.TOPOLO_ACCESS_TOKEN ? "env:TOPOLO_ACCESS_TOKEN" : (await readConfig()).credential ? "config-file" : "none";
-      emit({ source }, mode, () => `Credential source: ${source}`);
+      const config = await readConfig();
+      const source = credentialSource(config, environment);
+      const profile = resolvedProfileConfig(config, environment);
+      emit(
+        {
+          environment,
+          source,
+          authUrl: profile.serviceUrls?.auth ?? null,
+          developersUrl: profile.serviceUrls?.developers ?? null
+        },
+        mode,
+        () => [
+          `Environment:       ${environmentLabel(environment)}`,
+          `Credential source: ${source}`,
+          `Auth URL:          ${profile.serviceUrls?.auth ?? "(sdk default)"}`,
+          `Developers URL:    ${profile.serviceUrls?.developers ?? "(sdk default)"}`
+        ].join("\n")
+      );
     } catch (err) {
       fail(err, mode);
     }
   });
 }
-async function storeApiKey(apiKey, mode) {
+async function storeApiKey(apiKey, environment, mode) {
   if (!apiKey) throw new Error("API key is required");
   const config = await readConfig();
-  config.credential = { kind: "api_key", apiKey };
-  await writeConfig(config);
+  await writeConfig(
+    writeProfileConfig(config, environment, {
+      credential: { kind: "api_key", apiKey }
+    })
+  );
   emit(
-    { ok: true, credential: { kind: "api_key" } },
+    { ok: true, environment, credential: { kind: "api_key" } },
     mode,
-    () => "Stored API key. Run `topolo whoami` to verify."
+    () => `Stored API key for Topolo ${environmentLabel(environment)}. Run \`topolo whoami\` to verify.`
   );
 }
 async function runDeviceFlow(options) {
   const config = await readConfig();
+  const resolved = resolvedProfileConfig(config, options.environment);
   const oauth = new TopoloOAuth({
-    serviceUrls: resolveServiceUrls(config.serviceUrls)
+    serviceUrls: resolved.serviceUrls
   });
   const start = await oauth.requestDeviceCode({
     clientId: options.clientId,
@@ -2377,7 +2581,7 @@ async function runDeviceFlow(options) {
   if (options.mode === "pretty") {
     process.stderr.write(
       `
-  Sign in to Topolo
+  Sign in to Topolo ${environmentLabel(options.environment)}
   \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 
 ` + (opened ? `  Opening your browser to approve...
@@ -2405,17 +2609,21 @@ async function runDeviceFlow(options) {
     spinner?.stop();
   }
   const updated = await readConfig();
-  updated.credential = {
-    kind: "access_token",
-    accessToken: token.access_token,
-    ...token.refresh_token ? { refreshToken: token.refresh_token } : {},
-    expiresAt: Math.floor(Date.now() / 1e3) + token.expires_in
-  };
-  updated.oauthClientId = options.clientId;
-  await writeConfig(updated);
+  await writeConfig(
+    writeProfileConfig(updated, options.environment, {
+      credential: {
+        kind: "access_token",
+        accessToken: token.access_token,
+        ...token.refresh_token ? { refreshToken: token.refresh_token } : {},
+        expiresAt: Math.floor(Date.now() / 1e3) + token.expires_in
+      },
+      oauthClientId: options.clientId
+    })
+  );
   emit(
     {
       ok: true,
+      environment: options.environment,
       credential: {
         kind: "access_token",
         expiresIn: token.expires_in,
@@ -2491,22 +2699,23 @@ function sleep(ms) {
 }
 
 // src/version.ts
-var CLI_VERSION = "0.1.15";
+var CLI_VERSION = "0.1.17";
 
 // src/client.ts
 async function buildClient(options) {
-  const credential = await refreshCredentialIfNeeded();
+  const environment = selectedEnvironment();
+  const credential = await refreshCredentialIfNeeded(environment);
   if (!credential) return null;
   const config = await readConfig();
-  const serviceUrls = resolveServiceUrls(config.serviceUrls);
+  const profile = resolvedProfileConfig(config, environment);
   return createTopolo({
     credential,
     agent: {
       clientName: "topolo-cli",
       clientVersion: CLI_VERSION,
-      agentName: resolveAgentName(config.agentName)
+      agentName: resolveAgentName(profile.agentName)
     },
-    serviceUrls,
+    serviceUrls: profile.serviceUrls,
     requireConfirmForWrites: options?.requireConfirmForWrites,
     ...isDebugEnabled() ? { debug: stderrDebugLogger } : {}
   });
@@ -2543,6 +2752,9 @@ function registerWhoamiCommand(program2) {
   program2.command("whoami").description("Show the user, organization, and scopes attached to the current credential").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
+      const environment = selectedEnvironment();
+      const profile = resolvedProfileConfig(await readConfig(), environment);
+      assertServiceUrlForEnvironment("auth", profile.serviceUrls?.auth, environment);
       const topolo = await buildClient();
       if (!topolo) {
         throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
@@ -2573,6 +2785,7 @@ function registerCrmCommands(program2) {
   crm.command("contacts:list").description("List contacts in the authenticated organization").option("-q, --query <text>", "Full-text search").option("-p, --page <n>", "Page number (1-indexed)", (v) => parseInt(v, 10), 1).option("-s, --page-size <n>", "Page size", (v) => parseInt(v, 10), 25).option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
+      await assertCrmRoutable();
       const topolo = await buildClient();
       if (!topolo) {
         throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
@@ -2590,6 +2803,7 @@ function registerCrmCommands(program2) {
   crm.command("contacts:get <id>").description("Fetch a single contact by id").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (id, opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
+      await assertCrmRoutable();
       const topolo = await buildClient();
       if (!topolo) {
         throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
@@ -2602,6 +2816,15 @@ function registerCrmCommands(program2) {
     }
   });
 }
+async function assertCrmRoutable() {
+  const environment = selectedEnvironment();
+  const profile = resolvedProfileConfig(await readConfig(), environment);
+  assertServiceUrlForEnvironment(
+    "crm",
+    resolveServiceUrl("crm", profile.serviceUrls),
+    environment
+  );
+}
 function formatContactsTable(rows, total, page) {
   if (rows.length === 0) return "No contacts found.";
   const lines = [];
@@ -2660,6 +2883,14 @@ function registerApiCommand(program2) {
         if (WRITE_METHODS2.has(httpMethod) && !opts.confirm) {
           throw new Error(`Mutating ${httpMethod} requires --confirm.`);
         }
+        const environment = selectedEnvironment();
+        const config = await readConfig();
+        const profile = resolvedProfileConfig(config, environment);
+        assertServiceUrlForEnvironment(
+          service,
+          resolveServiceUrl(service, profile.serviceUrls),
+          environment
+        );
         let body = void 0;
         if (opts.data) {
           try {
@@ -3641,7 +3872,9 @@ 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-05-01";
+var STAGING_CLOUDFLARE_ACCOUNT_ID = "4f4e1c69a3830946f9fea7b1eb7531ac";
+var CLOUDFLARE_COMPATIBILITY_DATE = "2026-05-05";
+var CURRENT_VERIFICATION_DATE = "2026-05-06";
 function applicationScaffoldPayload(application, options = {}) {
   const target = normalizeTarget(options.target);
   const portfolio = target === "platform" ? normalizePortfolio(options.portfolio) : null;
@@ -4148,9 +4381,13 @@ function packageJson(application, target, options) {
     if (target === "platform") {
       dependencies["@topolo-io/auth-middleware"] = topoloPackageVersion("@topolo-io/auth-middleware", target);
       dependencies["@topolo/sdk"] = topoloPackageVersion("@topolo/sdk", target);
+      scripts.deploy = `node -e 'console.error("\\nX Bare deploy is disabled. Use deploy:staging or deploy:production.\\n"); process.exit(1)'`;
+      scripts["deploy:staging"] = "DEPLOY_ENVIRONMENT=staging VITE_TOPOLO_AUTH_URL=https://auth.stg.topolo.us npm run build && wrangler deploy --env staging";
+      scripts["deploy:production"] = "DEPLOY_ENVIRONMENT=production npm run build && wrangler deploy";
+    } else {
+      scripts.deploy = "npm run build && wrangler deploy";
     }
     devDependencies.wrangler = "^4.40.2";
-    scripts.deploy = "npm run build && wrangler deploy";
   }
   return `${json({
     name: application.packageName,
@@ -4485,8 +4722,13 @@ function appTsx(application, target, options) {
 function platformAppTsx(application, options) {
   const appName = toTitle(application.name);
   const serviceId = application.serviceId ?? application.id;
-  const tagline = options.audience === "personal" ? "Topolo personal app" : "Topolo workspace";
-  const workspaceTitle = options.audience === "personal" ? "Personal app" : "Workspace";
+  const isPersonal = options.audience === "personal";
+  const tagline = isPersonal ? "Topolo personal app" : "Topolo workspace";
+  const workspaceTitle = isPersonal ? "Personal app" : "Workspace";
+  const shellLabel = isPersonal ? "personal app shell" : "workspace shell";
+  const 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, useEffect, useMemo, useState, type ErrorInfo, type ReactNode } from 'react';",
     "import { createBrowserAuthModule, type AuthUser } from '@topolo-io/auth-client';",
@@ -4512,17 +4754,17 @@ function platformAppTsx(application, options) {
     "  app_name: APP_NAME,",
     `  app_tagline: '${escapeSingleQuoted(tagline)}',`,
     "  hero_title: `Open ${APP_NAME} in Topolo`,",
-    "  hero_subtitle: 'Shared landing, login, callback, auth, and workspace shell wiring are already included in the generated baseline.',",
+    `  hero_subtitle: 'Shared landing, login, callback, auth, and ${escapeSingleQuoted(shellLabel)} wiring are already included in the generated baseline.',`,
     "  hero_cta_text: 'Sign in',",
     "  hero_cta_url: '/login',",
     "  cta_title: 'Start from the shared platform entry flow',",
-    "  cta_subtitle: 'Unauthenticated routes stay on the shared Topolo surfaces before users enter the signed workspace shell.',",
+    `  cta_subtitle: 'Unauthenticated routes stay on the shared Topolo surfaces before users enter the signed ${escapeSingleQuoted(shellLabel)}.',`,
     "};",
     "const LOGIN_CONFIG = {",
     "  app_name: APP_NAME,",
     `  app_tagline: '${escapeSingleQuoted(tagline)}',`,
     "  hero_title: `Sign in to ${APP_NAME}`,",
-    "  hero_subtitle: 'Use Topolo Auth to open the shared workspace shell for this application.',",
+    `  hero_subtitle: 'Use Topolo Auth to open the shared ${escapeSingleQuoted(shellLabel)} for this application.',`,
     "  authenticated_home_path: '/',",
     "};",
     "",
@@ -4542,6 +4784,7 @@ function platformAppTsx(application, options) {
     "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,",
@@ -4690,7 +4933,7 @@ function platformAppTsx(application, options) {
     "        appId={APP_ID}",
     "        serviceId={SERVICE_ID}",
     "        appName={APP_NAME}",
-    '        subtitle="Opening your workspace..."',
+    `        subtitle="Opening your ${escapeDoubleQuoted(signedSurfaceLabel)}..."`,
     "      />",
     "    );",
     "  }",
@@ -4701,6 +4944,9 @@ function platformAppTsx(application, options) {
     "      serviceId={SERVICE_ID}",
     "      appName={APP_NAME}",
     "      user={shellUser}",
+    "      orgId={user.activeContextType === 'organization' ? user.activeContextId ?? user.orgId ?? null : null}",
+    "      activeContextType={user.activeContextType}",
+    "      activeContextId={user.activeContextId}",
     '      activeNavItemId="home"',
     `      navItems={[{ id: 'home', label: '${escapeSingleQuoted(workspaceTitle)}' }]}`,
     '      navigationMode="topbar"',
@@ -4719,9 +4965,9 @@ function platformAppTsx(application, options) {
     "    >",
     '      <div className="topolo-starter-workspace">',
     '        <section className="topolo-starter-card">',
-    "          <h2>Shared workspace baseline</h2>",
+    `          <h2>${baselineHeading}</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.",
+    `            ${baselineDescription}`,
     "          </p>",
     "        </section>",
     "      </div>",
@@ -4913,7 +5159,7 @@ function wranglerToml(application, target) {
   const lines = [
     `name = "${workerName}"`,
     'main = "src/worker.ts"',
-    `compatibility_date = "${CURRENT_VERIFICATION_DATE}"`,
+    `compatibility_date = "${CLOUDFLARE_COMPATIBILITY_DATE}"`,
     'compatibility_flags = ["nodejs_compat"]'
   ];
   if (target === "platform") {
@@ -4948,15 +5194,51 @@ function wranglerToml(application, target) {
     `SERVICE_ID = "${application.serviceId ?? application.id}"`,
     ""
   );
+  if (target === "platform") {
+    lines.push(
+      "# Staging deploys use the separate Topolo Staging Cloudflare account.",
+      "[env.staging]",
+      `name = "${workerName}-staging"`,
+      `account_id = "${STAGING_CLOUDFLARE_ACCOUNT_ID}"`,
+      "workers_dev = true",
+      "routes = [",
+      `  { pattern = "${slug}.stg.topolo.us", custom_domain = true }`,
+      "]",
+      "",
+      "[env.staging.vars]",
+      'AUTH_BASE_URL = "https://auth.stg.topolo.us"',
+      `SERVICE_ID = "${application.serviceId ?? application.id}"`,
+      ""
+    );
+  }
   return lines.join("\n");
 }
-function workerTs(application, target, _options) {
+function workerTs(application, target, options) {
   if (target === "developer") return developerWorkerTs(application);
-  return platformWorkerTs(application);
+  return platformWorkerTs(application, options);
 }
-function platformWorkerTs(application) {
+function platformWorkerTs(application, options) {
   const serviceId = application.serviceId ?? application.id;
   const serviceName = toTitle(application.name);
+  const openActionLabel = options.audience === "personal" ? "Open app" : "Open workspace";
+  const bootstrapBody = options.tenancy === "household" ? [
+    "      const userContext = auth.user && typeof auth.user === 'object' ? (auth.user as unknown as Record<string, unknown>) : {};",
+    "      return json({",
+    "        user: auth.user,",
+    "        activeContextType: userContext.activeContextType ?? null,",
+    "        activeContextId: userContext.activeContextId ?? null,",
+    "        activeContext: userContext.activeContext ?? null,",
+    "        selectedHouseholdId: userContext.selectedHouseholdId ?? null,",
+    "        selectedHousehold: userContext.selectedHousehold ?? null,",
+    "        household: userContext.selectedHousehold ?? null,",
+    "        householdMemberships: userContext.householdMemberships ?? [],",
+    "      }, { status: 200 }, request);"
+  ] : [
+    "      return json({",
+    "        user: auth.user,",
+    "        organization: auth.organization,",
+    "      }, { status: 200 }, request);"
+  ];
   return [
     "import { createTopoloWidgetResponse } from '@topolo/sdk';",
     "import { verifyRequest } from '@topolo-io/auth-middleware';",
@@ -4995,7 +5277,7 @@ function platformWorkerTs(application) {
     "          {",
     "            type: 'quick-actions',",
     "            actions: [",
-    "              { id: 'open-workspace', label: 'Open workspace', link: '/', primary: true },",
+    `              { id: 'open-workspace', label: '${escapeSingleQuoted(openActionLabel)}', link: '/', primary: true },`,
     "              { id: 'view-health', label: 'View health', link: '/api/health' },",
     "            ],",
     "          },",
@@ -5004,10 +5286,7 @@ function platformWorkerTs(application) {
     "    }",
     "",
     "    if (url.pathname === '/api/bootstrap') {",
-    "      return json({",
-    "        user: auth.user,",
-    "        organization: auth.organization,",
-    "      }, { status: 200 }, request);",
+    ...bootstrapBody,
     "    }",
     "",
     "    return json({ error: 'not_found' }, { status: 404 }, request);",
@@ -5102,6 +5381,7 @@ function developerWorkerTs(application) {
 function cloudcontrolJson(application, options) {
   const slug = toSlug(application.id);
   const host = application.productionUrl ? new URL(application.productionUrl).host : `${slug}.topolo.app`;
+  const stagingHost = `${slug}.stg.topolo.us`;
   const deployTargets = options.api ? [
     {
       kind: "worker",
@@ -5117,6 +5397,21 @@ function cloudcontrolJson(application, options) {
       routes: [host],
       api_url: application.productionUrl,
       service_id: application.serviceId
+    },
+    {
+      kind: "worker",
+      environment: "staging",
+      target_name: `topolo-${slug}-staging`,
+      cloudflare_account_id: STAGING_CLOUDFLARE_ACCOUNT_ID,
+      config_path: "wrangler.toml",
+      build_command: "VITE_TOPOLO_AUTH_URL=https://auth.stg.topolo.us npm run build",
+      output_dir: "dist",
+      production_branch: "staging",
+      healthcheck_path: "/api/health",
+      domains: [stagingHost],
+      routes: [stagingHost],
+      api_url: `https://${stagingHost}`,
+      service_id: application.serviceId
     }
   ] : [
     {
@@ -5152,6 +5447,12 @@ function cloudcontrolJson(application, options) {
         url: application.productionUrl,
         branch: "main",
         status: "unknown"
+      },
+      {
+        name: "staging",
+        url: `https://${stagingHost}`,
+        branch: "staging",
+        status: "unknown"
       }
     ] : [],
     deploy_targets: deployTargets,
@@ -5175,6 +5476,9 @@ function systemJson(application, options) {
   const slug = toSlug(application.id);
   const suiteLabel = options.audience === "personal" ? "personal" : "platform";
   const summaryLabel = options.audience === "personal" ? "first-party Topolo personal application" : "first-party Topolo platform application";
+  const apiNotes = options.api ? options.tenancy === "household" ? "Protected Worker routes validate Topolo Auth credentials and derive active personal context plus selected household 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." : "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.";
+  const sensitiveData = options.tenancy === "household" ? ["identity", "personal_data", "household_data"] : ["identity", "org_data"];
+  const privacySensitiveData = options.tenancy === "household" ? ["identity", "personal", "household"] : ["identity", "organization"];
   return `${json({
     id: `topolo-${slug}`,
     name: toTitle(application.name),
@@ -5190,7 +5494,7 @@ function systemJson(application, options) {
     api_contract: {
       type: options.api ? "curated" : "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."
+      notes: apiNotes
     },
     primary_hosts: application.productionUrl ? [application.productionUrl] : [],
     doc_paths: [`internal/apps/${slug}`, `public/applications/${slug}`],
@@ -5199,12 +5503,26 @@ function systemJson(application, options) {
       auth_boundary: "Topolo Auth through @topolo-io/auth-client for browser sessions and @topolo-io/auth-middleware for Worker requests.",
       tenant_isolation: options.tenancy === "household" ? "household_scoped" : "organization_scoped",
       external_inputs: ["browser", ...options.api ? ["api"] : []],
-      sensitive_data: ["identity", "org_data"],
+      sensitive_data: sensitiveData,
       security_review_status: "not_started",
       last_security_review: CURRENT_VERIFICATION_DATE,
       pentest_status: "not_started",
       evidence_doc: `internal/apps/${slug}`
     },
+    data_privacy: {
+      classification: "confidential",
+      sensitive_data_classes: privacySensitiveData,
+      storage_locations: ["source_control"],
+      encryption_at_rest: "platform_managed",
+      encryption_in_transit: "https_only",
+      key_management: "cloudflare_managed",
+      retention_policy: "needs_policy",
+      deletion_export_status: "planned",
+      logging_redaction_status: "partial",
+      privacy_review_status: "not_started",
+      enterprise_ready: false,
+      evidence_doc: `internal/apps/${slug}`
+    },
     dependencies: options.audience === "personal" ? ["topolo-auth"] : ["topolo-auth", "topolo-platform"],
     tags: ["application", "cloudflare", "typescript", suiteLabel]
   })}
@@ -5215,6 +5533,8 @@ function internalDocs(application, options) {
   const title = toTitle(application.name);
   const suiteLabel = options.audience === "personal" ? "personal" : "platform";
   const tenantLabel = options.tenancy === "household" ? "household" : "organization";
+  const apiContextLabel = options.tenancy === "household" ? "active personal context and selected household context" : "organization context";
+  const boundaryFailureText = options.tenancy === "household" ? "Domain data is added without a household-scoped backend boundary." : "Domain data is added without an organization-scoped backend boundary.";
   return [
     "---",
     `title: "${escapeFrontmatter(title)} Handbook"`,
@@ -5257,11 +5577,11 @@ function internalDocs(application, options) {
     "",
     "## API Reference",
     "",
-    options.api ? "The generated API baseline exposes `/api/health`, `/api/widget`, and `/api/bootstrap`. `/api/widget` returns the SDK widget response contract for TopoloOne, while `/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.",
+    options.api ? `The generated API baseline exposes \`/api/health\`, \`/api/widget\`, and \`/api/bootstrap\`. \`/api/widget\` returns the SDK widget response contract for TopoloOne, while \`/api/bootstrap\` requires Topolo Auth validation and returns the verified user plus ${apiContextLabel}.` : "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.",
+    options.api ? `Browser sessions and Worker requests must be validated through Topolo Auth under service id \`${application.serviceId}\`. Worker routes derive ${apiContextLabel} from the verified credential.` : "Browser sessions must be established through Topolo Auth and rendered inside the shared Topolo shell.",
     "",
     "## Data Ownership",
     "",
@@ -5269,14 +5589,14 @@ function internalDocs(application, options) {
     "",
     "## 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.",
+    application.productionUrl ? `The planned production host is \`${application.productionUrl}\`. Staging mirrors the scaffold at \`https://${slug}.stg.topolo.us\` through the \`wrangler.toml\` staging environment and Topolo Staging Cloudflare account. 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.",
+    `- ${boundaryFailureText}`,
     "",
     "## Debugging",
     "",
@@ -5299,6 +5619,8 @@ function publicDocs(application, options) {
   const title = toTitle(application.name);
   const suiteLabel = options.audience === "personal" ? "personal" : "business";
   const tenantLabel = options.tenancy === "household" ? "household" : "organization";
+  const apiRouteLabel = options.tenancy === "household" ? "authenticated personal and household routes" : "authenticated workspace routes";
+  const dataModelFailure = options.tenancy === "household" ? "household-scoped data models are not implemented until domain work begins" : "organization-scoped data models are not implemented until domain work begins";
   return [
     "---",
     `title: "${escapeFrontmatter(title)}"`,
@@ -5334,7 +5656,7 @@ function publicDocs(application, options) {
     "",
     "## 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.",
+    options.api ? `The generated API baseline exposes ${apiRouteLabel} 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",
     "",
@@ -5346,12 +5668,12 @@ function publicDocs(application, options) {
     "",
     "## Deployments",
     "",
-    application.productionUrl ? `The planned production host is \`${application.productionUrl}\`.` : "The production host has not been assigned yet.",
+    application.productionUrl ? `The planned production host is \`${application.productionUrl}\`. Staging mirrors the scaffold at \`https://${slug}.stg.topolo.us\`.` : "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",
+    `- ${dataModelFailure}`,
     "",
     "## Debugging",
     "",
@@ -5360,7 +5682,7 @@ function publicDocs(application, options) {
     "",
     "## Change Log / Verification",
     "",
-    `- Scaffold generated on ${CURRENT_VERIFICATION_DATE} from \`topolo apps scaffold\`.`,
+    `- Scaffold generated on ${CURRENT_VERIFICATION_DATE} from \`${options.portfolio ? "topolo platform apps scaffold" : "topolo apps scaffold"}\`.`,
     ""
   ].join("\n");
 }
@@ -5369,8 +5691,17 @@ function serviceManifestJson(application, options) {
   const title = toTitle(application.name);
   const permissionPrefix = application.id.replace(/[^a-z0-9_]/g, "_");
   const resourceLabel = options.tenancy === "household" ? "household" : "workspace";
+  const launcherSettings = options.tenancy === "household" ? {
+    settings: {
+      launcher: {
+        supported_contexts: ["personal"],
+        household_capable: true
+      }
+    }
+  } : {};
   return `${json({
     serviceId: application.serviceId,
+    ...launcherSettings,
     systems: [
       {
         systemId: `topolo-${slug}`,
@@ -5569,7 +5900,6 @@ function escapeFrontmatter(value) {
 }
 
 // src/commands/app-scaffold-provision.ts
-var DEFAULT_DEVELOPERS_ORIGIN = "https://developers.topolo.app";
 var DEVELOPERS_SERVICE_ID = "svc_topolo_developers";
 async function provisionApplicationScaffold(payload) {
   if (!payload.application.productionUrl) {
@@ -5582,7 +5912,8 @@ async function provisionApplicationScaffold(payload) {
       "Platform scaffold provisioning requires a service id. Re-run without --no-api or pass --service."
     );
   }
-  const credential = await refreshCredentialIfNeeded();
+  const environment = selectedEnvironment();
+  const credential = await refreshCredentialIfNeeded(environment);
   if (!credential) {
     throw new Error(
       "topolo apps scaffold --provision requires an authenticated Topolo session. Run `topolo auth login` first."
@@ -5596,15 +5927,16 @@ async function provisionApplicationScaffold(payload) {
   }
   const identity = await client.client.introspect();
   const config = await readConfig();
-  const serviceUrls = resolveServiceUrls(config.serviceUrls) ?? {};
-  const developersOrigin = sanitizeOrigin(serviceUrls.developers ?? DEFAULT_DEVELOPERS_ORIGIN);
+  const profile = resolvedProfileConfig(config, environment);
+  const developersOrigin = sanitizeOrigin(profile.serviceUrls?.developers ?? "https://developers.topolo.app");
+  assertServiceUrlForEnvironment("developers", developersOrigin, environment);
   const endpoint = payload.target === "platform" ? "/api/developer-console/admin/first-party-app-scaffolds" : "/api/developer-console/apps/scaffold";
   const headers = new Headers({
     "Content-Type": "application/json",
     "X-Service-ID": DEVELOPERS_SERVICE_ID,
     "X-Topolo-Client": `topolo-cli/${CLI_VERSION}`
   });
-  const agentName = resolveAgentName(config.agentName);
+  const agentName = resolveAgentName(profile.agentName);
   if (agentName) {
     headers.set("X-Topolo-Agent", agentName);
   }
@@ -6361,39 +6693,48 @@ function registerServicesCommand(program2) {
   program2.command("services").description("List every Topolo service the SDK can route to").option("--json", "Output JSON", true).option("--no-json", "Output human-readable table").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
+      const environment = selectedEnvironment();
       const config = await readConfig();
-      const rows = buildRows(resolveServiceUrls(config.serviceUrls));
-      emit({ services: rows }, mode, () => formatRows2(rows));
+      const rows = buildRows(config.serviceUrls, environment);
+      emit({ environment, services: rows }, mode, () => formatRows2(rows, environment));
     } catch (err) {
       fail(err, mode);
     }
   });
 }
-function buildRows(overrides) {
+function buildRows(overrides, environment = selectedEnvironment()) {
+  const resolvedOverrides = resolveServiceUrls(overrides, environment);
   return Object.keys(DEFAULT_SERVICE_URLS).sort().map((id) => {
     const defaultUrl = DEFAULT_SERVICE_URLS[id];
-    const effectiveUrl = resolveServiceUrl(id, overrides);
+    const effectiveUrl = resolveServiceUrl(id, resolvedOverrides);
     return {
       id,
       defaultUrl,
       effectiveUrl,
-      overridden: defaultUrl !== effectiveUrl
+      overridden: defaultUrl !== effectiveUrl,
+      environmentSafe: environment !== "staging" || isStagingUrl(effectiveUrl)
     };
   });
 }
-function formatRows2(rows) {
+function formatRows2(rows, environment = selectedEnvironment()) {
   const idWidth = Math.max(3, ...rows.map((r) => r.id.length));
   const urlWidth = Math.max(7, ...rows.map((r) => r.effectiveUrl.length));
   const lines = [];
-  lines.push(`${"ID".padEnd(idWidth)}  ${"URL".padEnd(urlWidth)}  OVERRIDE`);
-  lines.push(`${"-".repeat(idWidth)}  ${"-".repeat(urlWidth)}  --------`);
+  lines.push(`Environment: ${environment}`);
+  lines.push("");
+  lines.push(`${"ID".padEnd(idWidth)}  ${"URL".padEnd(urlWidth)}  OVERRIDE  READY`);
+  lines.push(`${"-".repeat(idWidth)}  ${"-".repeat(urlWidth)}  --------  -----`);
   for (const r of rows) {
     lines.push(
-      `${r.id.padEnd(idWidth)}  ${r.effectiveUrl.padEnd(urlWidth)}  ${r.overridden ? "yes" : ""}`
+      `${r.id.padEnd(idWidth)}  ${r.effectiveUrl.padEnd(urlWidth)}  ${r.overridden ? "yes" : "".padEnd(8)}  ${r.environmentSafe ? "yes" : "no"}`
     );
   }
   return lines.join("\n");
 }
+function isStagingUrl(value) {
+  const url = value.toLowerCase();
+  return url.includes(".stg.topolo.us") || url.includes("localhost") || url.includes("127.0.0.1") || url.includes("topolo-staging");
+}
 
 // src/commands/seed.ts
 var DEFAULT_SEED_BASE_URL = "https://seed.stg.topolo.us";
@@ -6401,9 +6742,9 @@ function seedBaseUrl() {
   return process.env.TOPOLO_SEED_URL || DEFAULT_SEED_BASE_URL;
 }
 async function authedFetch(path4, init = {}) {
-  const credential = await refreshCredentialIfNeeded();
+  const credential = await refreshCredentialIfNeeded("staging");
   if (!credential) {
-    throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
+    throw new Error("No staging credential configured. Run `topolo auth login --env staging` or set TOPOLO_STAGING_API_KEY.");
   }
   const headers = new Headers(init.headers || {});
   if (credential.kind === "api_key") headers.set("X-Api-Key", credential.apiKey);
@@ -6611,9 +6952,22 @@ function formatManifestsTable(manifests) {
 
 // src/index.ts
 var program = new Command();
+var argv;
+try {
+  argv = consumeEnvironmentArg(process.argv);
+} catch (err) {
+  process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+}
 program.name("topolo").description(
   "Topolo CLI. Public commands are scoped to the authenticated organization or developer workspace, and first-party Topolo scaffolding lives under the internal `topolo platform` namespace."
-).version(CLI_VERSION);
+).version(CLI_VERSION).option("--env <environment>", "Topolo environment: production or staging");
+program.hook("preAction", (thisCommand) => {
+  const opts = thisCommand.opts();
+  if (!opts.env) return;
+  process.env.TOPOLO_ENV = normalizeEnvironment(opts.env);
+});
 registerAuthCommands(program);
 registerWhoamiCommand(program);
 registerCrmCommands(program);
@@ -6622,8 +6976,30 @@ registerAppsCommand(program);
 registerPlatformCommand(program);
 registerServicesCommand(program);
 registerSeedCommands(program);
-program.parseAsync(process.argv).catch((err) => {
+program.parseAsync(argv).catch((err) => {
   process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}
 `);
   process.exit(1);
 });
+function consumeEnvironmentArg(argv2) {
+  const next = argv2.slice(0, 2);
+  for (let i = 2; i < argv2.length; i += 1) {
+    const arg = argv2[i];
+    if (!arg) continue;
+    if (arg === "--env") {
+      const value = argv2[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("--env requires production or staging.");
+      }
+      process.env.TOPOLO_ENV = normalizeEnvironment(value);
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--env=")) {
+      process.env.TOPOLO_ENV = normalizeEnvironment(arg.slice("--env=".length));
+      continue;
+    }
+    next.push(arg);
+  }
+  return next;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/cli",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Command-line interface for Topolo developers, operators, and agents, with internal first-party scaffolding available under the topolo platform namespace.",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
     "commander": "^12.1.0"
   },
   "devDependencies": {
-    "@topolo/sdk": "^0.2.10",
+    "@topolo/sdk": "^0.2.11",
     "@types/node": "^20.12.0",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",