@topolo/cli 0.8.2 → 0.8.3

package/README.md

@@ -1,16 +1,15 @@
 # TopoloCli
 
 Public customer command-line interface for Topolo organizations, developers,
-and agents. First-party engineering, seed, scaffold, audit, provisioning,
-deployment, and release commands belong to the restricted `topolo-platform`
-toolchain and are deliberately absent.
+and agents. Internal engineering and operations commands are deliberately
+absent.
 
 ## Current scope
 
 - API-key authentication (long-lived, service-scoped).
 - OAuth device-flow sign-in with a **built-in first-party client** — `topolo auth login` needs no client id; any Topolo user can sign in.
 - Stored access-token refresh; the `@topolo/mcp` server reads the same credential, so agents need no API-key plumbing.
-- First-class `production`, `staging`, `development`, and `local` environments with separate stored credentials and service URL overrides.
+- Production credentials by default, with isolated profiles for approved self-hosted environments.
 - **Per-context credentials** — hold and switch between your personal space and multiple organizations with `topolo context`.
 - **One-command agent setup** — `topolo setup` wires the bundled compatible skill + MCP into Claude Code / Codex.
 - **End-to-end diagnostics** — `topolo doctor` proves authentication and the MCP protocol path.
@@ -28,19 +27,12 @@ npx @topolo/cli whoami
 
 Credentials come from (in priority order):
 
-1. Environment-specific vars such as `TOPOLO_STAGING_API_KEY` or `TOPOLO_PRODUCTION_ACCESS_TOKEN`
+1. Environment-specific credential variables
 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
-topolo whoami --env staging --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.
+Production is the default customer environment. Use another environment only
+when your Topolo administrator provides its complete service configuration.
 
 For interactive use:
 
@@ -83,12 +75,12 @@ key returned by `topolo context ls --json`:
 
 ```bash
 topolo setup --name topolo-acme --context org:org_acme --env production
-topolo doctor --context org:org_acme --env production
+topolo doctor --name topolo-acme
 ```
 
 This creates separately named Claude Code and Codex registrations using the
-same exact nested MCP executable. `topolo-platform` is reserved for the
-restricted operator toolchain.
+same exact nested MCP executable. Reserved operator registrations cannot be
+created or removed by the public CLI.
 
 ## Cross-org isolation
 
@@ -225,8 +217,8 @@ topolo apps get mail --json
 ```
 
 Only live, credential-scoped applications are returned. The public CLI contains
-no first-party repository metadata or compiled fallback catalog. Internal app
-creation and conformance workflows use `topolo-platform apps`.
+no first-party repository metadata or compiled fallback catalog. Internal
+application lifecycle workflows are outside this customer CLI.
 
 ### `topolo oauth clients`
 

package/dist/index.js

@@ -9,7 +9,7 @@ import { platform as platform2 } from "os";
 import { createInterface } from "readline/promises";
 import { stdin as input } from "process";
 
-// ../../../public-platform-tooling-boundary-20260813/packages/topolo-sdk/dist/index.js
+// node_modules/@topolo/sdk/dist/index.js
 function applyAuthHeaders(headers, credential) {
   if (credential.kind === "api_key") {
     headers.set("X-Api-Key", credential.apiKey);
@@ -30,8 +30,8 @@ function generateRequestId() {
 }
 var TopoloSdkError = class extends Error {
   code;
-  constructor(code, message) {
-    super(message);
+  constructor(code, message2) {
+    super(message2);
     this.name = "TopoloSdkError";
     this.code = code;
   }
@@ -128,8 +128,8 @@ var TopoloAuthError = class extends TopoloSdkError {
   requestId;
   retryAfter;
   details;
-  constructor(message, code = "auth_error", options = {}) {
-    super(canonicalTopoloErrorCode(code) ?? "auth_error", message);
+  constructor(message2, code = "auth_error", options = {}) {
+    super(canonicalTopoloErrorCode(code) ?? "auth_error", message2);
     this.name = "TopoloAuthError";
     this.status = options.status ?? 401;
     this.body = options.body;
@@ -151,10 +151,10 @@ var TopoloPermissionError = class extends TopoloSdkError {
   requestId;
   retryAfter;
   details;
-  constructor(message, required, options = {}) {
+  constructor(message2, required, options = {}) {
     super(
       canonicalTopoloErrorCode(options.code) ?? serviceErrorCode(options.body, "permission_denied"),
-      message
+      message2
     );
     this.name = "TopoloPermissionError";
     this.required = canonicalTopoloRequired(required);
@@ -286,8 +286,8 @@ function topoloErrorHint(error) {
   return void 0;
 }
 var TopoloConfirmationRequiredError = class extends TopoloSdkError {
-  constructor(message) {
-    super("confirmation_required", message);
+  constructor(message2) {
+    super("confirmation_required", message2);
     this.name = "TopoloConfirmationRequiredError";
   }
 };
@@ -299,8 +299,8 @@ var TopoloHttpError = class extends TopoloSdkError {
   requestId;
   retryAfter;
   details;
-  constructor(service, path, status, body, message, options = {}) {
-    super(serviceErrorCode(body, "http_error"), message ?? `HTTP ${status} from ${service}${path}`);
+  constructor(service, path, status, body, message2, options = {}) {
+    super(serviceErrorCode(body, "http_error"), message2 ?? `HTTP ${status} from ${service}${path}`);
     this.name = "TopoloHttpError";
     this.status = status;
     this.body = body;
@@ -999,7 +999,7 @@ var TopoloClient = class _TopoloClient {
     const parsed = contentType.includes("application/json") ? await res.json().catch(() => null) : await res.text().catch(() => null);
     if (!res.ok) {
       const durationMs = Date.now() - startedAt;
-      const message = describeError(parsed, `HTTP ${res.status}`);
+      const message2 = describeError(parsed, `HTTP ${res.status}`);
       const publicCode = extractTopoloServiceErrorCode(parsed) ?? "http_error";
       this.emit({
         phase: "error",
@@ -1039,7 +1039,7 @@ var TopoloClient = class _TopoloClient {
         opts.path,
         res.status,
         parsed,
-        message,
+        message2,
         errorContext
       );
     }
@@ -2253,15 +2253,15 @@ function createTopolo(options) {
   };
 }
 
-// ../../../public-platform-tooling-boundary-20260813/packages/topolo-sdk/dist/node/credential-store.js
-import { mkdir, readFile, writeFile, chmod } from "fs/promises";
+// node_modules/@topolo/sdk/dist/node/credential-store.js
+import { mkdir, readFile, writeFile, chmod, rm, stat } from "fs/promises";
 import { existsSync } from "fs";
 import { homedir, platform } from "os";
 import { dirname, join } from "path";
 var TopoloSdkError2 = class extends Error {
   code;
-  constructor(code, message) {
-    super(message);
+  constructor(code, message2) {
+    super(message2);
     this.name = "TopoloSdkError";
     this.code = code;
   }
@@ -2358,8 +2358,8 @@ var TopoloAuthError2 = class extends TopoloSdkError2 {
   requestId;
   retryAfter;
   details;
-  constructor(message, code = "auth_error", options = {}) {
-    super(canonicalTopoloErrorCode2(code) ?? "auth_error", message);
+  constructor(message2, code = "auth_error", options = {}) {
+    super(canonicalTopoloErrorCode2(code) ?? "auth_error", message2);
     this.name = "TopoloAuthError";
     this.status = options.status ?? 401;
     this.body = options.body;
@@ -2451,8 +2451,8 @@ var TopoloHttpError2 = class extends TopoloSdkError2 {
   requestId;
   retryAfter;
   details;
-  constructor(service, path, status, body, message, options = {}) {
-    super(serviceErrorCode2(body, "http_error"), message ?? `HTTP ${status} from ${service}${path}`);
+  constructor(service, path, status, body, message2, options = {}) {
+    super(serviceErrorCode2(body, "http_error"), message2 ?? `HTTP ${status} from ${service}${path}`);
     this.name = "TopoloHttpError";
     this.status = status;
     this.body = body;
@@ -2755,6 +2755,41 @@ async function resolveCredential(environment = selectedEnvironment()) {
   return profileForEnvironment(config, environment).credential ?? null;
 }
 var REFRESH_SKEW_SECONDS = 60;
+var CONFIG_LOCK_RETRY_MS = 25;
+var CONFIG_LOCK_TIMEOUT_MS = 5e3;
+var CONFIG_LOCK_STALE_MS = 12e4;
+async function withConfigWriteLock(operation) {
+  const lockPath = `${configPath()}.lock`;
+  await mkdir(dirname(lockPath), { recursive: true });
+  const startedAt = Date.now();
+  while (true) {
+    try {
+      await mkdir(lockPath);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      try {
+        const lock = await stat(lockPath);
+        if (Date.now() - lock.mtimeMs > CONFIG_LOCK_STALE_MS) {
+          await rm(lockPath, { recursive: true, force: true });
+          continue;
+        }
+      } catch (inspectionError) {
+        if (inspectionError.code !== "ENOENT") throw inspectionError;
+        continue;
+      }
+      if (Date.now() - startedAt >= CONFIG_LOCK_TIMEOUT_MS) {
+        throw new Error(`Timed out waiting for credential configuration lock at ${lockPath}.`);
+      }
+      await new Promise((resolve3) => setTimeout(resolve3, CONFIG_LOCK_RETRY_MS));
+    }
+  }
+  try {
+    return await operation();
+  } finally {
+    await rm(lockPath, { recursive: true, force: true });
+  }
+}
 async function refreshCredentialIfNeeded(environment = selectedEnvironment(), options = {}) {
   const prefix = envVarPrefix(environment);
   if (process.env[`${prefix}_API_KEY`] || process.env[`${prefix}_ACCESS_TOKEN`] || environment === "production" && process.env.TOPOLO_API_KEY || environment === "production" && process.env.TOPOLO_ACCESS_TOKEN) {
@@ -2808,51 +2843,47 @@ async function refreshCredentialIfNeeded(environment = selectedEnvironment(), op
   }
 }
 async function refreshContextCredentialIfNeeded(environment, key, options = {}) {
-  const config = await readConfig();
-  const profile = profileForEnvironment(config, environment);
-  const context = profile.contexts?.[key];
-  const credential = context?.credential;
-  if (!credential || credential.kind !== "access_token") return credential ?? null;
-  const oauthClientId = context.oauthClientId ?? profile.oauthClientId;
-  if (!credential.refreshToken || !oauthClientId) return credential;
-  const now = Math.floor(Date.now() / 1e3);
-  if (!options.force && credential.expiresAt && credential.expiresAt - REFRESH_SKEW_SECONDS > now) return credential;
-  const serviceUrls = resolveServiceUrls(profile.serviceUrls, environment);
-  if (environment === "local" && !serviceUrls?.auth) {
-    throw new TopoloSdkError2(
-      "environment_service_url_required",
-      "Local Topolo context refresh requires an explicit local Auth service origin."
-    );
-  }
-  try {
-    const oauth = new TopoloOAuth2({
-      serviceUrls
-    });
-    const tokens = await oauth.refreshToken({
-      clientId: oauthClientId,
-      refreshToken: credential.refreshToken
-    });
-    const refreshed = {
-      kind: "access_token",
-      accessToken: tokens.access_token,
-      ...tokens.refresh_token ? { refreshToken: tokens.refresh_token } : { refreshToken: credential.refreshToken },
-      expiresAt: Math.floor(Date.now() / 1e3) + tokens.expires_in
-    };
-    await writeConfig(writeProfileConfig(config, environment, {
-      ...profile.activeContext === key ? { credential: refreshed } : {},
-      contexts: {
-        ...profile.contexts ?? {},
-        [key]: {
-          ...context,
-          credential: refreshed,
-          oauthClientId
+  return withConfigWriteLock(async () => {
+    const config = await readConfig();
+    const profile = profileForEnvironment(config, environment);
+    const context = profile.contexts?.[key];
+    const credential = context?.credential;
+    if (!credential || credential.kind !== "access_token") return credential ?? null;
+    const oauthClientId = context.oauthClientId ?? profile.oauthClientId;
+    if (!credential.refreshToken || !oauthClientId) return credential;
+    const now = Math.floor(Date.now() / 1e3);
+    if (!options.force && credential.expiresAt && credential.expiresAt - REFRESH_SKEW_SECONDS > now) return credential;
+    const serviceUrls = resolveServiceUrls(profile.serviceUrls, environment);
+    if (environment === "local" && !serviceUrls?.auth) {
+      throw new TopoloSdkError2(
+        "environment_service_url_required",
+        "Local Topolo context refresh requires an explicit local Auth service origin."
+      );
+    }
+    try {
+      const oauth = new TopoloOAuth2({ serviceUrls });
+      const tokens = await oauth.refreshToken({
+        clientId: oauthClientId,
+        refreshToken: credential.refreshToken
+      });
+      const refreshed = {
+        kind: "access_token",
+        accessToken: tokens.access_token,
+        ...tokens.refresh_token ? { refreshToken: tokens.refresh_token } : { refreshToken: credential.refreshToken },
+        expiresAt: Math.floor(Date.now() / 1e3) + tokens.expires_in
+      };
+      await writeConfig(writeProfileConfig(config, environment, {
+        ...profile.activeContext === key ? { credential: refreshed } : {},
+        contexts: {
+          ...profile.contexts ?? {},
+          [key]: { ...context, credential: refreshed, oauthClientId }
         }
-      }
-    }));
-    return refreshed;
-  } catch {
-    return credential;
-  }
+      }));
+      return refreshed;
+    } catch {
+      return credential;
+    }
+  });
 }
 function resolveAgentName(configAgentName) {
   return process.env.TOPOLO_AGENT_NAME ?? configAgentName;
@@ -2906,9 +2937,6 @@ function apiKeyIssuanceUrl(environment = selectedEnvironment()) {
   return `${developerConsoleUrl(environment)}/credentials`;
 }
 var DEFAULT_CLI_CLIENT_IDS = {
-  // First-party `topolo-cli` device-flow client, seeded per environment by Auth
-  // (core/TopoloAuth/scripts/seed-first-party-oauth-clients.sql). Each env's
-  // Auth must have this client before the CLI ships pointing at it.
   production: "topolo-cli",
   staging: "topolo-cli",
   development: "topolo-cli"
@@ -3270,13 +3298,13 @@ async function pollUntilApproved(params) {
   throw new Error("Device code expired. Run `topolo auth login` again.");
 }
 function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 
 // src/client.ts
 async function buildClient(options) {
-  const environment = selectedEnvironment();
-  const credential = await refreshCredentialIfNeeded(environment);
+  const environment = options?.environment ?? selectedEnvironment();
+  const credential = options?.context ? await refreshContextCredentialIfNeeded(environment, options.context) : await refreshCredentialIfNeeded(environment);
   if (!credential) return null;
   const config = await readConfig();
   const profile = resolvedProfileConfig(config, environment);
@@ -3290,7 +3318,9 @@ async function buildClient(options) {
     },
     serviceUrls: profile.serviceUrls,
     requireConfirmForWrites: options?.requireConfirmForWrites,
-    ...credential.kind === "access_token" && credential.refreshToken ? { refreshCredential: () => refreshCredentialIfNeeded(environment, { force: true }) } : {},
+    ...credential.kind === "access_token" && credential.refreshToken ? {
+      refreshCredential: () => options?.context ? refreshContextCredentialIfNeeded(environment, options.context, { force: true }) : refreshCredentialIfNeeded(environment, { force: true })
+    } : {},
     ...isDebugEnabled() ? { debug: stderrDebugLogger } : {}
   });
 }
@@ -4081,7 +4111,7 @@ function normalizeList(values, fallback = []) {
 }
 
 // src/commands/integrations.ts
-import { readdir, readFile as readFile2, stat } from "fs/promises";
+import { readdir, readFile as readFile2, stat as stat2 } from "fs/promises";
 import { join as join3, relative } from "path";
 function registerIntegrationsCommand(program2) {
   const integrations = program2.command("integrations").description("Generate and validate Topolo integration handoffs.");
@@ -4244,7 +4274,7 @@ async function collectFiles(repoRoot) {
         continue;
       }
       if (!entry.isFile() || !isInspectable(entry.name)) continue;
-      const info = await stat(fullPath);
+      const info = await stat2(fullPath);
       if (info.size > 25e4) continue;
       result.push({
         path: relative(root, fullPath),
@@ -4264,46 +4294,135 @@ function formatCheckResult(result) {
 }
 
 // src/commands/skills.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import { mkdir as mkdir2, copyFile, readFile as readFile4, writeFile as writeFile2, rm as rm2, rename } from "fs/promises";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname3, join as join5, resolve } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { createRequire } from "module";
+
+// src/commands/agent-host.ts
 import { spawnSync } from "child_process";
 import { existsSync as existsSync2 } from "fs";
-import { mkdir as mkdir2, copyFile, readFile as readFile3, writeFile as writeFile2, rm, rename } from "fs/promises";
+import { readFile as readFile3 } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { dirname as dirname3, join as join4, resolve } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { createRequire } from "module";
+import { isAbsolute, join as join4 } from "path";
+var RESERVED_OPERATOR_REGISTRATION = ["topolo", "platform"].join("-");
+function isPublicRegistrationName(name) {
+  return name === "topolo" || name.startsWith("topolo-") && name !== RESERVED_OPERATOR_REGISTRATION;
+}
+function selectStableNodeCommand(whichOutput, fallback = process.execPath) {
+  const candidate = whichOutput?.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+  return candidate && isAbsolute(candidate) ? candidate : fallback;
+}
+function stableNodeCommand() {
+  const probe = spawnSync(process.platform === "win32" ? "where" : "which", ["node"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  return selectStableNodeCommand(probe.status === 0 ? probe.stdout : void 0);
+}
+function agentSkillPath(agent, homeDir = homedir2()) {
+  return agent === "claude" ? join4(homeDir, ".claude", "skills", "topolo", "SKILL.md") : join4(homeDir, ".codex", "skills", "topolo", "SKILL.md");
+}
+async function readAgentRegistrations(agent, homeDir = homedir2()) {
+  return agent === "claude" ? readClaudeRegistrations(homeDir) : readCodexRegistrations(homeDir);
+}
+async function readClaudeRegistrations(homeDir) {
+  const path = join4(homeDir, ".claude.json");
+  if (!existsSync2(path)) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile3(path, "utf8"));
+  } catch (error) {
+    throw new Error(`Cannot read malformed Claude configuration at ${path}: ${message(error)}`);
+  }
+  const servers = parsed.mcpServers;
+  if (!servers || typeof servers !== "object" || Array.isArray(servers)) return [];
+  return Object.entries(servers).filter(([name]) => isPublicRegistrationName(name)).flatMap(([name, value]) => normalizeRegistration(name, value));
+}
+async function readCodexRegistrations(homeDir) {
+  const path = join4(homeDir, ".codex", "config.toml");
+  if (!existsSync2(path)) return [];
+  const registrations = /* @__PURE__ */ new Map();
+  let section;
+  for (const rawLine of (await readFile3(path, "utf8")).split(/\r?\n/)) {
+    const line = rawLine.trim();
+    const heading = line.match(/^\[mcp_servers\.([A-Za-z0-9_-]+)(\.env)?\]$/);
+    if (heading) {
+      section = { name: heading[1], env: Boolean(heading[2]) };
+      if (isPublicRegistrationName(section.name) && !registrations.has(section.name)) {
+        registrations.set(section.name, { name: section.name, command: "", args: [], env: {} });
+      }
+      continue;
+    }
+    if (line.startsWith("[")) {
+      section = void 0;
+      continue;
+    }
+    if (!section || !isPublicRegistrationName(section.name) || !line || line.startsWith("#")) continue;
+    const assignment = line.match(/^([A-Za-z0-9_]+)\s*=\s*(.+)$/);
+    if (!assignment) continue;
+    const registration = registrations.get(section.name);
+    try {
+      const value = JSON.parse(assignment[2]);
+      if (section.env && typeof value === "string") registration.env[assignment[1]] = value;
+      if (!section.env && assignment[1] === "command" && typeof value === "string") registration.command = value;
+      if (!section.env && assignment[1] === "args" && Array.isArray(value) && value.every((item) => typeof item === "string")) {
+        registration.args = value;
+      }
+    } catch {
+      throw new Error(`Cannot read unsupported MCP value in Codex configuration at ${path}.`);
+    }
+  }
+  return [...registrations.values()].filter((registration) => registration.command);
+}
+function normalizeRegistration(name, value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+  const candidate = value;
+  if (typeof candidate.command !== "string") return [];
+  const args = Array.isArray(candidate.args) && candidate.args.every((arg) => typeof arg === "string") ? candidate.args : [];
+  const env = candidate.env && typeof candidate.env === "object" && !Array.isArray(candidate.env) ? Object.fromEntries(Object.entries(candidate.env).filter((entry) => typeof entry[1] === "string")) : {};
+  return [{ name, command: candidate.command, args, env }];
+}
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/commands/skills.ts
 var AGENT_LABELS = { claude: "Claude Code", codex: "Codex" };
 var AGENT_NAME_FOR = { claude: "claude-code", codex: "codex" };
-var RESERVED_OPERATOR_REGISTRATION = ["topolo", "platform"].join("-");
 function skillsSourceDir() {
   const here = dirname3(fileURLToPath2(import.meta.url));
   const distCandidate = resolve(here, "../skills");
   const srcCandidate = resolve(here, "../../skills");
   for (const candidate of [distCandidate, srcCandidate]) {
-    if (existsSync2(join4(candidate, "topolo", "SKILL.md"))) return candidate;
+    if (existsSync3(join5(candidate, "topolo", "SKILL.md"))) return candidate;
   }
   return distCandidate;
 }
 function resolveMcpCommand() {
   const require2 = createRequire(import.meta.url);
-  return { command: process.execPath, args: [require2.resolve("@topolo/mcp/stdio")] };
+  return { command: stableNodeCommand(), args: [require2.resolve("@topolo/mcp/stdio")] };
 }
 function agentBinaryExists(bin) {
-  const probe = spawnSync(process.platform === "win32" ? "where" : "which", [bin], {
+  const probe = spawnSync2(process.platform === "win32" ? "where" : "which", [bin], {
     stdio: "ignore"
   });
   return probe.status === 0;
 }
-function claudeSkillDir(projectDir, homeDir = homedir2()) {
-  const base = projectDir ? resolve(projectDir, ".claude") : join4(homeDir, ".claude");
-  return join4(base, "skills", "topolo");
+function claudeSkillDir(projectDir, homeDir = homedir3()) {
+  const base = projectDir ? resolve(projectDir, ".claude") : join5(homeDir, ".claude");
+  return join5(base, "skills", "topolo");
 }
-function codexSkillDir(homeDir = homedir2()) {
-  return join4(homeDir, ".codex", "skills", "topolo");
+function codexSkillDir(homeDir = homedir3()) {
+  return join5(homeDir, ".codex", "skills", "topolo");
 }
 async function installSkillFile(sourceDir, targetDir) {
   await mkdir2(targetDir, { recursive: true });
-  const target = join4(targetDir, "SKILL.md");
-  await copyFile(join4(sourceDir, "topolo", "SKILL.md"), target);
+  const target = join5(targetDir, "SKILL.md");
+  await copyFile(join5(sourceDir, "topolo", "SKILL.md"), target);
   return target;
 }
 async function atomicWrite(path, contents) {
@@ -4327,11 +4446,11 @@ function withoutMcpServerSections(text, name) {
   }).join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
 }
 async function registerClaudeViaConfig(mcp, homeDir, registration) {
-  const path = join4(homeDir, ".claude.json");
+  const path = join5(homeDir, ".claude.json");
   let config = {};
-  if (existsSync2(path)) {
+  if (existsSync3(path)) {
     try {
-      config = JSON.parse(await readFile3(path, "utf8"));
+      config = JSON.parse(await readFile4(path, "utf8"));
     } catch (error) {
       throw new Error(`Cannot update malformed Claude configuration at ${path}: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -4348,9 +4467,9 @@ async function registerClaudeViaConfig(mcp, homeDir, registration) {
 `);
 }
 async function registerCodexViaConfig(mcp, homeDir, registration) {
-  const path = join4(homeDir, ".codex", "config.toml");
+  const path = join5(homeDir, ".codex", "config.toml");
   let text = "";
-  if (existsSync2(path)) text = await readFile3(path, "utf8");
+  if (existsSync3(path)) text = await readFile4(path, "utf8");
   text = withoutMcpServerSections(text, registration.name);
   const argsToml = mcp.args.length ? `
 args = [${mcp.args.map((a) => `"${a}"`).join(", ")}]` : "";
@@ -4391,21 +4510,21 @@ function resolveMcpRegistration(options) {
   }
   return { name, ...context ? { context } : {}, environment };
 }
-async function unregisterFromConfig(agent, homeDir) {
+async function unregisterFromConfig(agent, homeDir, name) {
   if (agent === "claude") {
-    const path2 = join4(homeDir, ".claude.json");
-    if (!existsSync2(path2)) return;
-    const config = JSON.parse(await readFile3(path2, "utf8"));
+    const path2 = join5(homeDir, ".claude.json");
+    if (!existsSync3(path2)) return;
+    const config = JSON.parse(await readFile4(path2, "utf8"));
     const servers = config.mcpServers ?? {};
-    delete servers.topolo;
+    delete servers[name];
     config.mcpServers = servers;
     await atomicWrite(path2, `${JSON.stringify(config, null, 2)}
 `);
     return;
   }
-  const path = join4(homeDir, ".codex", "config.toml");
-  if (!existsSync2(path)) return;
-  const text = withoutMcpServerSections(await readFile3(path, "utf8"), "topolo");
+  const path = join5(homeDir, ".codex", "config.toml");
+  if (!existsSync3(path)) return;
+  const text = withoutMcpServerSections(await readFile4(path, "utf8"), name);
   await atomicWrite(path, text ? `${text}
 ` : "");
 }
@@ -4418,6 +4537,11 @@ async function installForAgent(agent, sourceDir, mcp, opts) {
   try {
     if (agent === "claude") await registerClaudeViaConfig(mcp, opts.homeDir, opts.registration);
     else await registerCodexViaConfig(mcp, opts.homeDir, opts.registration);
+    const installed = (await readAgentRegistrations(agent, opts.homeDir)).find((registration) => registration.name === opts.registration.name);
+    const expectedEnvironment = registrationEnvironment(AGENT_NAME_FOR[agent], opts.registration);
+    if (!installed || installed.command !== mcp.command || JSON.stringify(installed.args) !== JSON.stringify(mcp.args) || Object.entries(expectedEnvironment).some(([key, value]) => installed.env[key] !== value)) {
+      throw new Error(`Host configuration did not retain the ${opts.registration.name} MCP registration.`);
+    }
     return { agent, skillPath, skillInstalled: true, mcp: "config-file" };
   } catch (err) {
     return {
@@ -4441,46 +4565,36 @@ function registerSkillsCommand(program2) {
       const mode = resolveOutputMode(opts.json);
       try {
         const { results, mcp } = await installAgentSurfaces({ ...opts, homeDir: opts.agentHome });
+        assertAgentSetupSucceeded(results);
         emit({ installed: results, mcpCommand: mcp }, mode, () => formatInstall(results, mcp));
       } catch (err) {
         fail(err, mode);
       }
     }
   );
-  skills.command("status").description("Show whether the skill file + MCP server are installed for each agent").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
+  skills.command("status").description("List public Topolo skill and MCP registrations for each agent").option("--agent-home <dir>", "Inspect an alternate agent home").option("--name <name>", "Inspect one registration name").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
-      const rows = ["claude", "codex"].map((agent) => {
-        const skillDir = agent === "claude" ? claudeSkillDir() : codexSkillDir();
-        return {
-          agent,
-          skillInstalled: existsSync2(join4(skillDir, "SKILL.md")),
-          skillPath: join4(skillDir, "SKILL.md"),
-          cliAvailable: agentBinaryExists(agent)
-        };
+      const rows = await agentSurfaceStatus({
+        homeDir: opts.agentHome ? resolve(opts.agentHome) : void 0,
+        name: opts.name
       });
       emit({ agents: rows }, mode, () => formatStatus(rows));
     } catch (err) {
       fail(err, mode);
     }
   });
-  skills.command("uninstall").description("Remove the skill file and MCP registration for each agent").option("--claude", "Target Claude Code only").option("--codex", "Target Codex only").option("--agent-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
+  skills.command("uninstall").description("Remove the skill file and MCP registration for each agent").option("--claude", "Target Claude Code only").option("--codex", "Target Codex only").option("--agent-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").option("--name <name>", "Remove one registration (defaults to topolo)").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
-      const homeDir = opts.agentHome ? resolve(opts.agentHome) : homedir2();
-      const removed = [];
-      for (const agent of resolveTargets(opts)) {
-        const skillDir = agent === "claude" ? claudeSkillDir(void 0, homeDir) : codexSkillDir(homeDir);
-        const skillFile = join4(skillDir, "SKILL.md");
-        const skillRemoved = existsSync2(skillFile);
-        if (skillRemoved) await rm(skillFile, { force: true });
-        await unregisterFromConfig(agent, homeDir);
-        removed.push({ agent, skillRemoved });
-      }
+      const removed = await uninstallAgentSurfaces({
+        ...opts,
+        homeDir: opts.agentHome ? resolve(opts.agentHome) : void 0
+      });
       emit(
         { removed },
         mode,
-        () => removed.map((r) => `${AGENT_LABELS[r.agent]}: skill removed=${r.skillRemoved}, MCP unregistered`).join("\n")
+        () => removed.map((r) => `${AGENT_LABELS[r.agent]}: ${r.name} removed=${r.registrationRemoved}, skill removed=${r.skillRemoved}`).join("\n")
       );
     } catch (err) {
       fail(err, mode);
@@ -4489,12 +4603,12 @@ function registerSkillsCommand(program2) {
 }
 async function installAgentSurfaces(opts) {
   const sourceDir = skillsSourceDir();
-  if (!existsSync2(join4(sourceDir, "topolo", "SKILL.md"))) {
+  if (!existsSync3(join5(sourceDir, "topolo", "SKILL.md"))) {
     throw new Error("Bundled skill file not found. Reinstall the CLI: npm install -g @topolo/cli");
   }
   const mcp = resolveMcpCommand();
   const registration = resolveMcpRegistration(opts);
-  const homeDir = opts.homeDir ?? homedir2();
+  const homeDir = opts.homeDir ?? homedir3();
   const results = [];
   for (const agent of resolveTargets(opts)) {
     results.push(await installForAgent(agent, sourceDir, mcp, {
@@ -4511,12 +4625,53 @@ function registerSetupCommand(program2) {
     const mode = resolveOutputMode(opts.json);
     try {
       const { results, mcp } = await installAgentSurfaces({ ...opts, homeDir: opts.agentHome });
+      assertAgentSetupSucceeded(results);
       emit({ installed: results, mcpCommand: mcp }, mode, () => formatInstall(results, mcp));
     } catch (error) {
       fail(error, mode);
     }
   });
 }
+function assertAgentSetupSucceeded(results) {
+  const failed = results.filter((result) => result.mcp === "failed");
+  if (failed.length) {
+    throw new Error(failed.map((result) => `${AGENT_LABELS[result.agent]}: ${result.detail ?? "MCP registration failed"}`).join("; "));
+  }
+}
+async function agentSurfaceStatus(options = {}) {
+  const homeDir = options.homeDir ?? homedir3();
+  const sourceSkill = await readFile4(join5(skillsSourceDir(), "topolo", "SKILL.md"), "utf8");
+  return Promise.all(["claude", "codex"].map(async (agent) => {
+    const skillPath = agentSkillPath(agent, homeDir);
+    const installedSkill = existsSync3(skillPath) ? await readFile4(skillPath, "utf8") : void 0;
+    const registrations = (await readAgentRegistrations(agent, homeDir)).filter((registration) => !options.name || registration.name === options.name);
+    return {
+      agent,
+      skillInstalled: installedSkill !== void 0,
+      skillCurrent: installedSkill === sourceSkill,
+      skillPath,
+      cliAvailable: agentBinaryExists(agent),
+      registrations
+    };
+  }));
+}
+async function uninstallAgentSurfaces(options) {
+  const homeDir = options.homeDir ?? homedir3();
+  const name = options.name?.trim() || "topolo";
+  resolveMcpRegistration({ name, ...name === "topolo" ? {} : { context: "uninstall-validation" } });
+  const removed = [];
+  for (const agent of resolveTargets(options)) {
+    const before = await readAgentRegistrations(agent, homeDir);
+    const registrationRemoved = before.some((entry) => entry.name === name);
+    await unregisterFromConfig(agent, homeDir, name);
+    const remaining = await readAgentRegistrations(agent, homeDir);
+    const skillPath = agentSkillPath(agent, homeDir);
+    const skillRemoved = remaining.length === 0 && existsSync3(skillPath);
+    if (skillRemoved) await rm2(dirname3(skillPath), { recursive: true, force: true });
+    removed.push({ agent, name, registrationRemoved, skillRemoved });
+  }
+  return removed;
+}
 function formatInstall(results, mcp) {
   const lines = [];
   const mcpStr = [mcp.command, ...mcp.args].join(" ");
@@ -4536,43 +4691,49 @@ function formatInstall(results, mcp) {
 }
 function formatStatus(rows) {
   return rows.map(
-    (r) => `${AGENT_LABELS[r.agent]}: skill ${r.skillInstalled ? "installed" : "not installed"} (${r.skillPath}), ${r.agent} CLI ${r.cliAvailable ? "available" : "not found"}`
+    (r) => `${AGENT_LABELS[r.agent]}: skill ${r.skillInstalled ? r.skillCurrent ? "current" : "stale" : "not installed"} (${r.skillPath}), ${r.agent} CLI ${r.cliAvailable ? "available" : "not found"}, MCP registrations: ${r.registrations.map((registration) => registration.name).join(", ") || "none"}`
   ).join("\n");
 }
 
 // src/commands/doctor.ts
 import { access } from "fs/promises";
+import { homedir as homedir4 } from "os";
+import { resolve as resolve2 } from "path";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 var defaultDependencies = {
   resolveMcp: resolveMcpCommand,
   verifyFile: (path) => access(path),
-  verifyAuthentication: async () => {
-    const topolo = await buildClient();
-    if (!topolo) throw new Error("No credential configured. Run `topolo auth login`.");
+  verifyAuthentication: async (context, environment) => {
+    const topolo = await buildClient({ context, environment });
+    if (!topolo) throw new Error(context ? `No credential configured for ${context}. Run \`topolo auth login\` for that context.` : "No credential configured. Run `topolo auth login`.");
     const identity = await topolo.identity.whoami();
     return identity.organization?.slug ?? identity.user.email;
   },
   verifyMcp: verifyMcpProtocol
 };
-async function runDoctor(dependencies = defaultDependencies) {
-  const checks = [];
+async function runDoctor(dependencies = defaultDependencies, target) {
+  const checks = [...target?.preflightChecks ?? []];
   let mcp;
   try {
-    mcp = dependencies.resolveMcp();
+    mcp = target?.mcp ?? dependencies.resolveMcp();
     await dependencies.verifyFile(mcp.args[0]);
     checks.push({ name: "launcher", ok: true, detail: `${mcp.command} ${mcp.args.join(" ")}` });
   } catch (error) {
     checks.push({ name: "launcher", ok: false, detail: errorMessage(error) });
   }
   try {
-    checks.push({ name: "authentication", ok: true, detail: await dependencies.verifyAuthentication() });
+    checks.push({
+      name: "authentication",
+      ok: true,
+      detail: await dependencies.verifyAuthentication(target?.context, target?.environment)
+    });
   } catch (error) {
     checks.push({ name: "authentication", ok: false, detail: errorMessage(error) });
   }
   if (mcp) {
     try {
-      checks.push({ name: "mcp", ok: true, detail: await dependencies.verifyMcp(mcp.command, mcp.args) });
+      checks.push({ name: "mcp", ok: true, detail: await dependencies.verifyMcp(mcp.command, mcp.args, target?.env) });
     } catch (error) {
       checks.push({ name: "mcp", ok: false, detail: errorMessage(error) });
     }
@@ -4581,9 +4742,9 @@ async function runDoctor(dependencies = defaultDependencies) {
   }
   return { ok: checks.every((check) => check.ok), cliVersion: CLI_VERSION, checks };
 }
-async function verifyMcpProtocol(command, args) {
+async function verifyMcpProtocol(command, args, env = definedEnvironment(process.env)) {
   const client = new Client({ name: "topolo-cli-doctor", version: CLI_VERSION });
-  const transport = new StdioClientTransport({ command, args, stderr: "pipe" });
+  const transport = new StdioClientTransport({ command, args, stderr: "pipe", env });
   try {
     await client.connect(transport);
     const tools = await client.listTools();
@@ -4597,12 +4758,50 @@ async function verifyMcpProtocol(command, args) {
     await client.close();
   }
 }
+async function resolveInstalledDoctorTarget(options) {
+  const name = options.name?.trim() || "topolo";
+  const homeDir = options.agentHome ? resolve2(options.agentHome) : homedir4();
+  const expected = resolveMcpCommand();
+  const requestedAgents = options.claude && !options.codex ? ["claude"] : options.codex && !options.claude ? ["codex"] : ["claude", "codex"];
+  const rows = (await agentSurfaceStatus({ homeDir, name })).filter((row) => requestedAgents.includes(row.agent));
+  const preflightChecks = [];
+  let selected = rows.flatMap((row) => row.registrations)[0];
+  for (const row of rows) {
+    preflightChecks.push({
+      name: "skill",
+      ok: row.skillCurrent,
+      detail: `${row.agent}: ${row.skillCurrent ? "bundled skill is current" : row.skillInstalled ? "installed skill is stale" : "skill is missing"}`
+    });
+    const registration = row.registrations.find((entry) => entry.name === name);
+    const exact = Boolean(
+      registration && registration.command === expected.command && JSON.stringify(registration.args) === JSON.stringify(expected.args)
+    );
+    preflightChecks.push({
+      name: "registration",
+      ok: exact,
+      detail: `${row.agent}: ${exact ? `${name} uses the bundled launcher` : `${name} is missing or does not use the bundled launcher`}`
+    });
+  }
+  const context = options.context !== void 0 ? normalizeDoctorContext(options.context) : selected?.env.TOPOLO_CONTEXT;
+  const environment = normalizeEnvironment(options.environment ?? selected?.env.TOPOLO_ENV);
+  if (name !== "topolo") resolveMcpRegistration({ name, context, environment });
+  if (!selected) selected = { name, ...expected, env: {} };
+  const env = {
+    ...definedEnvironment(process.env),
+    ...selected.env,
+    ...context ? { TOPOLO_CONTEXT: context, TOPOLO_ENV: environment } : {}
+  };
+  return { mcp: selected, env, context, environment, preflightChecks };
+}
+function definedEnvironment(environment) {
+  return Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== void 0));
+}
 function registerDoctorCommand(program2) {
-  program2.command("doctor").description("Verify the CLI credential and bundled MCP server end to end").option("--context <context>", "Verify one exact personal or organization context").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
+  program2.command("doctor").description("Verify installed agent surfaces, exact credential, and MCP protocol end to end").option("--name <name>", "Verify one installed MCP registration (defaults to topolo)").option("--context <context>", "Verify one exact personal or organization context").option("--environment <env>", "Override the context environment").option("--claude", "Verify Claude Code only").option("--codex", "Verify Codex only").option("--agent-home <dir>", "Inspect an alternate agent home").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
-      if (opts.context !== void 0) applyDoctorContext(opts.context);
-      const result = await runDoctor();
+      const target = await resolveInstalledDoctorTarget(opts);
+      const result = await runDoctor(defaultDependencies, target);
       if (!result.ok) throw new Error(formatDoctor(result));
       emit(result, mode, () => formatDoctor(result));
     } catch (error) {
@@ -4617,9 +4816,6 @@ function normalizeDoctorContext(value) {
   }
   return context;
 }
-function applyDoctorContext(value, environment = process.env) {
-  environment.TOPOLO_CONTEXT = normalizeDoctorContext(value);
-}
 function formatDoctor(result) {
   return result.checks.map((check) => `${check.ok ? "PASS" : "FAIL"} ${check.name}: ${check.detail}`).join("\n");
 }

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@topolo/cli",
-  "version": "0.8.2",
-  "topoloPublishedVersion": "0.8.2",
+  "version": "0.8.3",
+  "topoloPublishedVersion": "0.8.3",
   "description": "Public command-line interface for Topolo customer organizations, developers, and agents.",
+  "license": "UNLICENSED",
+  "author": "Topolo",
+  "homepage": "https://docs.topolo.app/guides/agents-and-automation",
   "type": "module",
   "bin": {
     "topolo": "dist/index.js"
@@ -22,8 +25,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@topolo/mcp": "0.11.0",
-    "@topolo/sdk": "0.11.0",
+    "@topolo/mcp": "0.11.1",
+    "@topolo/sdk": "0.11.1",
     "commander": "^12.1.0"
   },
   "devDependencies": {

package/skills/topolo/SKILL.md

@@ -31,7 +31,8 @@ npm view @topolo/cli version
 
 If the CLI version differs, update `@topolo/cli`, run `topolo setup`, run `topolo doctor`, and restart the agent. The CLI owns compatible SDK and MCP versions; customers must not assemble that dependency set manually. Record the CLI version used with results.
 
-Production is the customer environment. Do not use internal development, staging, seed, deployment, audit, scaffold, or release workflows from this skill; those belong to the restricted `topolo-platform` toolchain.
+Production is the customer environment. Internal engineering, deployment,
+audit, provisioning, and release workflows are outside this public skill.
 
 ## Authentication gate
 
@@ -65,7 +66,7 @@ uses the exact bundled MCP instead of a global binary:
 
 ```bash
 topolo setup --name topolo-acme --context org:org_acme --env production
-topolo doctor --context org:org_acme --env production
+topolo doctor --name topolo-acme
 ```
 
 The context selector accepts an
@@ -100,6 +101,7 @@ Its `data.policy.canCreate` and `data.policy.reason` are the caller-specific cre
 
 MCP equivalents:
 
+- `topolo_whoami` for the current credential identity
 - `topolo_search_applications`
 - `topolo_get_application`
 - `topolo_get_resource_types`
@@ -165,7 +167,9 @@ Before every call, validate exact input against the published JSON Schema:
 topolo actions validate <action-id> --data '<json>' --json
 ```
 
-MCP: `topolo_validate_action`.
+MCP: `topolo_validate_action`. Use `topolo_prepare_action` for one compact
+validate-and-plan response, and `topolo_upload_action` only when the selected
+action publishes an upload contract.
 
 For large inputs, write one schema-valid JSON object to a file and pass it without shell escaping: