@topolo/cli 0.7.0 → 0.7.3

package/README.md

@@ -153,6 +153,7 @@ and the CLI calls them through the shared SDK.
 
 ```bash
 topolo actions --service mail --json
+topolo actions --service mail --detail --json
 topolo actions get app_topolo_mail.messages.send --json
 topolo actions call app_topolo_mail.messages.send \
   --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
@@ -163,6 +164,11 @@ Use `topolo actions` before `topolo api` when an app has published a machine
 contract for the operation. `topolo api` remains the escape hatch for endpoints
 that are not yet in the action catalog.
 
+Action search, capability discovery, validation, and planning return compact
+agent guidance by default. Use `--detail` only when the full schemas and agent
+contract are required. `topolo resources --service <app>` is accepted alongside
+the positional application selector.
+
 Workspace-scoped actions carry resource context independently from the active
 personal/organization credential and independently from the browser session:
 
@@ -215,8 +221,9 @@ Agents should call `topolo apps requirements <app> --json` before creating or
 expanding a Topolo app. The output is the versioned platform contract for app
 metadata, canonical docs, shared auth, shared shell, service registration,
 deployment metadata, agent surfaces, observability, and verification.
-`topolo apps audit --json` turns the same contract into per-app scores and a
-catalog-backed migration queue. Add `--local --repo-root <topolo-checkout>` to
+`topolo apps audit --json` returns compact per-app scores and a migration queue
+count. Add `--detail` for every finding and migration item, or
+`--local --repo-root <topolo-checkout>` to
 include filesystem evidence from the app repo, CloudControl metadata, and
 TopoloDocs. Add `--fail-on needs_review` for the default new-work gate, or
 `--fail-on partial` for strict release readiness.

package/dist/index.js

@@ -3914,6 +3914,52 @@ function mergeSignals(a, b) {
   b.addEventListener("abort", onAbort, { once: true });
   return controller.signal;
 }
+function compactActionCatalogEntry(action) {
+  const required = Array.isArray(action.inputSchema["required"]) ? action.inputSchema["required"].filter((value) => typeof value === "string") : [];
+  const examples = action.agentContract?.examples ?? [];
+  return {
+    actionId: action.actionId,
+    title: action.title,
+    description: action.description,
+    method: action.method,
+    readOnly: action.readOnly,
+    requiresConfirmation: action.requiresConfirmation,
+    agentAccess: action.agentAccess ?? (action.requiresConfirmation ? "confirm" : action.readOnly ? "auto" : "confirm"),
+    requiredPermission: action.requiredPermission,
+    requiredInput: required,
+    resourceType: action.agentContract?.resource?.kind ?? null,
+    exampleInput: examples[0]?.input ?? null,
+    docsUrl: action.agentContract?.docsUrl ?? null
+  };
+}
+function compactActionValidation(actionId, validation) {
+  return { actionId, valid: validation.valid, errors: validation.errors };
+}
+function compactActionPlan(plan) {
+  return {
+    actionId: plan.action.actionId,
+    valid: plan.validation.valid,
+    errors: plan.validation.errors,
+    executable: plan.executable,
+    confirmationRequired: plan.confirmationRequired,
+    confirmationProvided: plan.confirmationProvided,
+    request: plan.request,
+    verification: plan.verification,
+    rollbackActionId: plan.rollbackActionId,
+    nextActionIds: plan.nextActionIds
+  };
+}
+function compactApplicationAudit(report) {
+  return {
+    version: report.version,
+    applications: report.applications.map((audit) => ({
+      applicationId: audit.application.id,
+      applicationName: audit.application.name,
+      score: audit.score
+    })),
+    migrationQueueCount: report.migrationQueue.length
+  };
+}
 var CrmModule = class {
   constructor(client) {
     this.client = client;
@@ -4598,6 +4644,18 @@ function emit(data, mode, pretty) {
     process.stdout.write(pretty() + "\n");
   }
 }
+function handleOutputStreamError(err, exit = process.exit) {
+  if (err?.code === "EPIPE") {
+    exit(0);
+    return;
+  }
+  throw err;
+}
+function installOutputErrorHandlers(stdout = process.stdout, stderr = process.stderr, exit = process.exit) {
+  const handler = (err) => handleOutputStreamError(err, exit);
+  stdout.on("error", handler);
+  stderr.on("error", handler);
+}
 function fail(err, mode) {
   const payload = normalizeError(err);
   if (mode === "json") {
@@ -5107,7 +5165,7 @@ function parseQueryPairs(pairs) {
 
 // src/commands/actions.ts
 function registerActionsCommand(program2) {
-  const actions = program2.command("actions").description("Search permission-scoped Topolo actions for one application").option("-s, --service <service>", "App id, slug, or name (required for search)").option("-q, --query <query>", "Filter by action id, name, or title").option("--cursor <cursor>", "Continuation cursor from the previous page").option("--limit <limit>", "Page size (1-100)", "25").option("--json", "Output JSON").option("--no-json", "Output human-readable table").action(async (opts) => {
+  const actions = program2.command("actions").description("Search permission-scoped Topolo actions for one application").option("-s, --service <service>", "App id, slug, or name (required for search)").option("-q, --query <query>", "Filter by action id, name, or title").option("--cursor <cursor>", "Continuation cursor from the previous page").option("--limit <limit>", "Page size (1-100)", "25").option("--detail", "Include full schemas and agent contracts").option("--json", "Output JSON").option("--no-json", "Output human-readable table").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
       const topolo = await buildClient();
@@ -5121,7 +5179,8 @@ function registerActionsCommand(program2) {
         cursor: opts.cursor,
         limit: parsePageSize(opts.limit)
       });
-      emit(result, mode, () => formatActionRows(result.actions, result.page.nextCursor));
+      const output2 = opts.detail ? result : { actions: result.actions.map(compactActionCatalogEntry), page: result.page };
+      emit(output2, mode, () => formatActionRows(result.actions, result.page.nextCursor));
     } catch (err) {
       fail(err, mode);
     }
@@ -5181,17 +5240,18 @@ function registerActionsCommand(program2) {
       fail(err, mode);
     }
   });
-  actions.command("validate <action>").description("Validate action input locally against the published JSON Schema").option("-d, --data <json-or-@file>", "JSON action input or @path to a JSON file", "{}").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
+  actions.command("validate <action>").description("Validate action input locally against the published JSON Schema").option("-d, --data <json-or-@file>", "JSON action input or @path to a JSON file", "{}").option("--detail", "Include the full action contract").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
     const mode = resolveOutputMode(opts.json ?? command.parent?.opts().json);
     try {
       const topolo = await requiredClient();
       const result = await topolo.client.validateActionInput(action, parseJsonObject(opts.data || "{}"));
-      emit(result, mode, () => result.validation.valid ? `Valid input for ${result.action.actionId}.` : result.validation.errors.map((issue) => `${issue.path}: ${issue.message}`).join("\n"));
+      const output2 = detailRequested(opts.detail, command) ? result : compactActionValidation(result.action.actionId, result.validation);
+      emit(output2, mode, () => result.validation.valid ? `Valid input for ${result.action.actionId}.` : result.validation.errors.map((issue) => `${issue.path}: ${issue.message}`).join("\n"));
     } catch (err) {
       fail(err, mode);
     }
   });
-  actions.command("plan <action>").description("Validate and preview the exact request, confirmation, verification, and rollback plan").option("-d, --data <json-or-@file>", "JSON action input or @path to a JSON file", "{}").option("--resource-type <type>", "App-local resource alias, such as workspace").option("--resource-id <id>", "Resource id for the selected resource type").option("--confirm", "Include confirmation in the plan without executing it").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
+  actions.command("plan <action>").description("Validate and preview the exact request, confirmation, verification, and rollback plan").option("-d, --data <json-or-@file>", "JSON action input or @path to a JSON file", "{}").option("--resource-type <type>", "App-local resource alias, such as workspace").option("--resource-id <id>", "Resource id for the selected resource type").option("--confirm", "Include confirmation in the plan without executing it").option("--detail", "Include the full action contract").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
     const mode = resolveOutputMode(opts.json ?? command.parent?.opts().json);
     try {
       const topolo = await requiredClient();
@@ -5200,7 +5260,7 @@ function registerActionsCommand(program2) {
         confirm: opts.confirm === true,
         ...resource ? { resource } : {}
       });
-      emit(plan, mode, () => formatActionPlan(plan));
+      emit(detailRequested(opts.detail, command) ? plan : compactActionPlan(plan), mode, () => formatActionPlan(plan));
     } catch (err) {
       fail(err, mode);
     }
@@ -5220,19 +5280,65 @@ function registerActionsCommand(program2) {
       fail(err, mode);
     }
   });
-  actions.command("capabilities").description("List every published action for one application (its capability contract)").option("-s, --service <service>", "App id, slug, or name").option("--json", "Output JSON").option("--no-json", "Output human-readable table").action(async (opts, command) => {
+  actions.command("capabilities").description("List every published action for one application (its capability contract)").option("-s, --service <service>", "App id, slug, or name").option("--summary", "Return compact capability counts without action rows").option("--detail", "Include full schemas and agent contracts").option("--json", "Output JSON").option("--no-json", "Output human-readable table").action(async (opts, command) => {
     const mode = resolveOutputMode(opts.json ?? command.parent?.opts().json);
     try {
       const topolo = await requiredClient();
       const service = opts.service || command.parent?.opts().service;
       if (!service?.trim()) throw new Error("--service is required for capability discovery");
-      const result = await topolo.client.searchActions({ service: service.trim(), limit: 100 });
-      emit(result, mode, () => formatActionRows(result.actions, result.page.nextCursor));
+      if (opts.summary && detailRequested(opts.detail, command)) {
+        throw new Error("--summary cannot be combined with --detail");
+      }
+      const resolvedService = service.trim();
+      const discovered = [];
+      const seenCursors = /* @__PURE__ */ new Set();
+      let cursor;
+      for (; ; ) {
+        const page = await topolo.client.searchActions({
+          service: resolvedService,
+          limit: 100,
+          ...cursor ? { cursor } : {}
+        });
+        discovered.push(...page.actions);
+        if (!page.page.hasMore) break;
+        const nextCursor = page.page.nextCursor?.trim();
+        if (!nextCursor || seenCursors.has(nextCursor)) {
+          throw new Error("Capability discovery returned an invalid continuation cursor.");
+        }
+        seenCursors.add(nextCursor);
+        cursor = nextCursor;
+      }
+      const result = { actions: discovered, page: { nextCursor: null, hasMore: false } };
+      const output2 = opts.summary ? summarizeActionCapabilities(resolvedService, discovered) : detailRequested(opts.detail, command) ? result : { actions: discovered.map(compactActionCatalogEntry), page: result.page };
+      emit(output2, mode, () => opts.summary ? formatActionCapabilitySummary(summarizeActionCapabilities(resolvedService, discovered)) : formatActionRows(discovered));
     } catch (err) {
       fail(err, mode);
     }
   });
 }
+function summarizeActionCapabilities(service, actions) {
+  return {
+    service,
+    total: actions.length,
+    readOnly: actions.filter((action) => action.readOnly).length,
+    mutating: actions.filter((action) => !action.readOnly).length,
+    destructive: actions.filter((action) => action.destructive).length,
+    confirmationRequired: actions.filter((action) => action.requiresConfirmation).length,
+    resourceTypes: [...new Set(actions.map((action) => action.agentContract?.resource?.kind).filter(Boolean))].sort()
+  };
+}
+function formatActionCapabilitySummary(summary) {
+  return [
+    `Service: ${summary.service}`,
+    `Actions: ${summary.total} (${summary.readOnly} read-only, ${summary.mutating} mutating)`,
+    `Destructive: ${summary.destructive}`,
+    `Confirmation required: ${summary.confirmationRequired}`,
+    `Resource types: ${summary.resourceTypes.join(", ") || "-"}`
+  ].join("\n");
+}
+function detailRequested(local, command) {
+  return local === true || command.parent?.opts().detail === true;
+}
 async function requiredClient() {
   const topolo = await buildClient();
   if (!topolo) throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
@@ -5336,7 +5442,7 @@ function formatActionPlan(plan) {
 
 // src/commands/apps.ts
 import { execSync } from "child_process";
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync6, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync6, writeFileSync as writeFileSync2 } from "fs";
 import path6 from "path";
 
 // src/commands/app-audit-local.ts
@@ -6639,7 +6745,7 @@ function firstPartyAppPath(appDir, _audience) {
 }
 
 // src/commands/app-scaffold-platform-versions.ts
-import { readdirSync as readdirSync2, readFileSync as readFileSync4 } from "fs";
+import { existsSync as existsSync3, readdirSync as readdirSync2, readFileSync as readFileSync4 } from "fs";
 import path2 from "path";
 var versionCache = /* @__PURE__ */ new Map();
 function platformPackagePin(packageName, options = {}) {
@@ -6647,7 +6753,7 @@ function platformPackagePin(packageName, options = {}) {
     options.repoRoot ?? process.env.TOPOLO_WORKSPACE_ROOT ?? void 0,
     options.cwd ?? process.cwd()
   );
-  if (!workspaceRoot) {
+  if (!workspaceRoot || !existsSync3(path2.join(workspaceRoot, "topolo-platform", "packages"))) {
     throw new Error(
       `Cannot resolve a concrete version for ${packageName}: platform-target scaffolds must run inside the Topolo workspace checkout (a directory containing apps/ and system-apps/), or receive --repo-root. The fleet pinning policy requires exact ^<latest> pins, never "latest".`
     );
@@ -7194,6 +7300,7 @@ function readme(application, target, options) {
       "- `@topolo-io/app-launcher` provides shared app switching and handoff helpers.",
       "- `@topolo-io/ui-kit` provides every control, table, panel, workbench, inspector, icon, transition, and bug reporter primitive used by the generated product surface.",
       "- `@topolo-io/auth-client` owns browser auth, callback exchange, token refresh, and logout.",
+      '- Build the app data client with `authClient.createJsonClient()` (or `createAuthenticatedFetch()`) from `@topolo-io/auth-client`. It already attaches the bearer token, refreshes proactively near expiry, and refreshes-and-retries once on a 401. NEVER hand-roll an `Authorization: Bearer` header in browser code: every app that has done so forgot the 401 recovery and showed raw auth errors ("Token expired") to the user on an ordinary 15-minute expiry. The `browser-auth-refresh` fleet static guard fails any browser file that builds its own bearer header.',
       "- `@topolo-io/api-key-management`, `@topolo-io/chat-widget`, `@topolo-io/notifications`, and `@topolo-io/resource-context` complete the AppShell capability baseline.",
       "- Every Topolo-owned browser dependency is emitted at `latest`; product-domain packages are added only when the app actually adopts that domain.",
       "- `.npmrc` routes private `@topolo-io` packages to GitHub Packages without storing credentials; public `@topolo` packages remain on npm. Local and CI environments must provide a GitHub Packages token.",
@@ -8760,7 +8867,7 @@ function developerWorkerTs(application) {
 }
 
 // src/commands/app-scaffold-generate.ts
-import { existsSync as existsSync3, mkdirSync, mkdtempSync, readFileSync as readFileSync5, rmSync, writeFileSync } from "fs";
+import { existsSync as existsSync4, mkdirSync, mkdtempSync, readFileSync as readFileSync5, rmSync, writeFileSync } from "fs";
 import { spawnSync } from "child_process";
 import { tmpdir } from "os";
 import path3 from "path";
@@ -8774,7 +8881,7 @@ function resolveGeneratorPath() {
   ];
   for (const candidate of candidates) {
     const p = decodeURIComponent(candidate.pathname);
-    if (existsSync3(p)) return p;
+    if (existsSync4(p)) return p;
   }
   throw new Error(
     `topolo: could not locate generate-wrangler.mjs. A published CLI vendors it into dist/ at build time; in-repo it is read from topolo-platform/tooling/. Looked in:
@@ -11668,7 +11775,7 @@ function registerAppsCommand(program2) {
   });
   apps.command("audit [application]").description(
     "Audit Topolo applications against the versioned application-build requirements."
-  ).option("--json", "Output JSON", true).option("--no-json", "Output human-readable table").option("--local", "Inspect the local Topolo checkout for filesystem-backed evidence").option("--repo-root <path>", "Topolo checkout root to inspect when --local is set").option(
+  ).option("--json", "Output JSON", true).option("--no-json", "Output human-readable table").option("--detail", "Include all findings and migration queue items").option("--local", "Inspect the local Topolo checkout for filesystem-backed evidence").option("--repo-root <path>", "Topolo checkout root to inspect when --local is set").option(
     "--fail-on <status>",
     "Exit non-zero when audit has findings at this severity or worse: missing, needs_review, partial"
   ).action(async (application, opts) => {
@@ -11680,8 +11787,9 @@ function registerAppsCommand(program2) {
         client: await directoryClient()
       });
       const gate = opts.failOn ? evaluateApplicationAuditGate(payload, opts.failOn) : null;
-      const output2 = gate ? { ...payload, conformanceGate: gate } : payload;
-      emit(output2, mode, () => formatAudit(output2));
+      const compact = opts.detail ? payload : compactApplicationAudit(payload);
+      const output2 = gate ? { ...compact, conformanceGate: gate } : compact;
+      emit(output2, mode, () => formatAudit(gate ? { ...payload, conformanceGate: gate } : payload));
       if (gate && !gate.passed) {
         if (mode === "json") {
           process.stderr.write(JSON.stringify({ error: gate.message, conformanceGate: gate }, null, 2) + "\n");
@@ -11824,7 +11932,7 @@ async function applicationAuditPayload(application, options = {}) {
 async function recordApplicationEvidence(application, options = {}) {
   const appId = (await resolveApplication(application, options.client ?? null)).id;
   const root = path6.resolve(options.appRoot ?? process.cwd());
-  if (!existsSync4(root)) {
+  if (!existsSync5(root)) {
     throw new Error(`Application root does not exist: ${root}`);
   }
   let commit = options.commit;
@@ -11838,7 +11946,7 @@ async function recordApplicationEvidence(application, options = {}) {
   const evidenceDir = path6.join(root, ".topolo");
   const evidencePath = path6.join(evidenceDir, "evidence.json");
   let before = null;
-  if (existsSync4(evidencePath)) {
+  if (existsSync5(evidencePath)) {
     try {
       const raw = JSON.parse(readFileSync6(evidencePath, "utf8"));
       if (raw && typeof raw === "object" && raw.version === 1) {
@@ -13110,7 +13218,7 @@ function formatCheckResult(result) {
 
 // src/commands/skills.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync5 } from "fs";
+import { existsSync as existsSync6 } from "fs";
 import { mkdir as mkdir4, copyFile, readFile as readFile7, writeFile as writeFile7, rm } from "fs/promises";
 import { homedir as homedir2 } from "os";
 import { dirname as dirname4, join as join5, resolve as resolve3 } from "path";
@@ -13122,7 +13230,7 @@ function skillsSourceDir() {
   const distCandidate = resolve3(here, "../skills");
   const srcCandidate = resolve3(here, "../../skills");
   for (const candidate of [distCandidate, srcCandidate]) {
-    if (existsSync5(join5(candidate, "topolo", "SKILL.md"))) return candidate;
+    if (existsSync6(join5(candidate, "topolo", "SKILL.md"))) return candidate;
   }
   return distCandidate;
 }
@@ -13167,7 +13275,7 @@ function registerViaOfficialCli(cli, mcp, agentName) {
 async function registerClaudeViaConfig(mcp) {
   const path9 = join5(homedir2(), ".claude.json");
   let config = {};
-  if (existsSync5(path9)) {
+  if (existsSync6(path9)) {
     try {
       config = JSON.parse(await readFile7(path9, "utf8"));
     } catch {
@@ -13188,7 +13296,7 @@ async function registerClaudeViaConfig(mcp) {
 async function registerCodexViaConfig(mcp) {
   const path9 = join5(homedir2(), ".codex", "config.toml");
   let text = "";
-  if (existsSync5(path9)) text = await readFile7(path9, "utf8");
+  if (existsSync6(path9)) text = await readFile7(path9, "utf8");
   text = text.replace(
     /(^|\n)\[mcp_servers\.topolo(?:\.[a-z]+)?\][^\[]*/g,
     (match) => match.startsWith("\n") ? "\n" : ""
@@ -13243,7 +13351,7 @@ function registerSkillsCommand(program2) {
       const mode = resolveOutputMode(opts.json);
       try {
         const sourceDir = skillsSourceDir();
-        if (!existsSync5(join5(sourceDir, "topolo", "SKILL.md"))) {
+        if (!existsSync6(join5(sourceDir, "topolo", "SKILL.md"))) {
           throw new Error(
             "Bundled skill file not found. Reinstall the CLI: npm install -g @topolo/cli"
           );
@@ -13272,7 +13380,7 @@ function registerSkillsCommand(program2) {
         const skillDir = agent === "claude" ? claudeSkillDir() : codexSkillDir();
         return {
           agent,
-          skillInstalled: existsSync5(join5(skillDir, "SKILL.md")),
+          skillInstalled: existsSync6(join5(skillDir, "SKILL.md")),
           skillPath: join5(skillDir, "SKILL.md"),
           cliAvailable: agentBinaryExists(agent)
         };
@@ -13289,7 +13397,7 @@ function registerSkillsCommand(program2) {
       for (const agent of resolveTargets(opts)) {
         const skillDir = agent === "claude" ? claudeSkillDir() : codexSkillDir();
         const skillFile = join5(skillDir, "SKILL.md");
-        const skillRemoved = existsSync5(skillFile);
+        const skillRemoved = existsSync6(skillFile);
         if (skillRemoved) await rm(skillFile, { force: true });
         if (agentBinaryExists(agent)) {
           spawnSync2(agent, ["mcp", "remove", "topolo"], { stdio: "ignore" });
@@ -13541,12 +13649,14 @@ function registerContextCommand(program2) {
 
 // src/commands/resources.ts
 function registerResourcesCommand(program2) {
-  program2.command("resources <application>").description("List bindable resource ids for one credential-scoped Topolo application").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (application, opts) => {
+  program2.command("resources [application]").description("List bindable resource ids for one credential-scoped Topolo application").option("-s, --service <service>", "App id, slug, or name").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (application, opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
       const topolo = await buildClient();
       if (!topolo) throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
-      const result = await topolo.client.listBindableResources(application);
+      const selector = application?.trim() || opts.service?.trim();
+      if (!selector) throw new Error("application or --service is required");
+      const result = await topolo.client.listBindableResources(selector);
       emit(result, mode, () => formatResources(result));
     } catch (err) {
       fail(err, mode);
@@ -13641,6 +13751,7 @@ Workspace: ${workspace.name} (${workspace.id})${workspace.isDefault ? "\nDefault
 }
 
 // src/index.ts
+installOutputErrorHandlers();
 var program = new Command();
 var argv;
 try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@topolo/cli",
-  "version": "0.7.0",
-  "topoloPublishedVersion": "0.7.0",
+  "version": "0.7.3",
+  "topoloPublishedVersion": "0.7.3",
   "description": "Command-line interface for Topolo developers, operators, and agents, with internal first-party scaffolding available under the topolo platform namespace.",
   "type": "module",
   "bin": {

package/skills/topolo/SKILL.md

@@ -20,6 +20,22 @@ topolo skills install
 
 `topolo skills install` installs this skill and registers the Topolo MCP server for Claude Code and Codex. Both use the same credential written by `topolo auth login`.
 
+Before testing platform behavior, verify every installed agent surface against
+the package registry. Do not diagnose behavior with stale tooling:
+
+```bash
+topolo --version
+npm list -g --depth=0 @topolo/cli @topolo/mcp @topolo/sdk
+npm view @topolo/cli version
+npm view @topolo/mcp version
+npm view @topolo/sdk version
+```
+
+If any version differs, install the three latest released versions together,
+run `topolo skills install`, and restart the MCP client before testing. Record
+the versions used with the results. Source builds may test a candidate fix, but
+must be labelled separately from released-tooling proof.
+
 Production is the default. Use `--env staging` on every staging command, or set `TOPOLO_ENV=staging`. Never mix staging discovery with production execution.
 
 ## Authentication gate
@@ -153,7 +169,7 @@ For large inputs, write one schema-valid JSON object to a file and pass it witho
 
 ```bash
 topolo actions validate <action-id> --data @payload.json --json
-topolo actions plan <action-id> --data @payload.json --json
+topolo actions plan <action-id> --data @payload.json --confirm --json
 topolo actions call <action-id> --data @payload.json --confirm --json
 ```
 
@@ -167,7 +183,7 @@ topolo actions plan <action-id> --data '<json>' --json
 
 MCP: `topolo_plan_action`.
 
-The plan must be valid and must expose the resolved request, confirmation requirement, verification steps, and rollback when one is published. If `executable` is false, do not call the action.
+The plan must be valid and must expose the resolved request, confirmation requirement, verification steps, and rollback when one is published. For a mutation that the user has already authorized, include `--confirm` in the plan so `executable` reflects the exact confirmed call; planning never executes the action. Before approval, omit `--confirm`, present the plan, and treat `executable: false` with `confirmationRequired: true` and `confirmationProvided: false` as awaiting approval rather than an invalid contract. Once approval is obtained, call the unchanged request with `--confirm` without planning it a second time. Any other `executable: false` result blocks the call.
 
 ### 6. Confirm mutations