@topolo/cli 0.2.4 → 0.4.0

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";
 
-// ../topolo-sdk/dist/index.js
+// ../../../topolo-platform/packages/topolo-sdk/dist/index.js
 function applyAuthHeaders(headers, credential) {
   if (credential.kind === "api_key") {
     headers.set("X-Api-Key", credential.apiKey);
@@ -2098,6 +2098,262 @@ function firstString(...values) {
   }
   return null;
 }
+var SUPPORTED_SCHEMA_KEYWORDS = /* @__PURE__ */ new Set([
+  "$schema",
+  "$id",
+  "$ref",
+  "$defs",
+  "definitions",
+  "title",
+  "description",
+  "default",
+  "examples",
+  "deprecated",
+  "readOnly",
+  "writeOnly",
+  "type",
+  "nullable",
+  "const",
+  "enum",
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "properties",
+  "required",
+  "additionalProperties",
+  "propertyNames",
+  "minProperties",
+  "maxProperties",
+  "items",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minLength",
+  "maxLength",
+  "pattern",
+  "format",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf"
+]);
+function validateTopoloActionInput(schema, input2) {
+  const schemaIssue = inspectSchema(schema, "$", schema, 0);
+  if (schemaIssue) return { valid: false, errors: [schemaIssue] };
+  const errors = [];
+  validateNode(schema, input2, "$", schema, errors, 0);
+  return { valid: errors.length === 0, errors };
+}
+function inspectSchema(schema, path4, root, depth) {
+  if (depth > 128) return { path: path4, code: "schema_depth", message: "Schema recursion exceeded 128 levels." };
+  const unsupportedKeyword = Object.keys(schema).find((keyword) => !SUPPORTED_SCHEMA_KEYWORDS.has(keyword));
+  if (unsupportedKeyword) {
+    return { path: path4, code: "unsupported_schema_keyword", message: `Action schema uses unsupported keyword ${unsupportedKeyword}.` };
+  }
+  if (typeof schema.format === "string" && !["uri", "email", "date-time"].includes(schema.format)) {
+    return { path: path4, code: "unsupported_schema_format", message: `Action schema uses unsupported format ${schema.format}.` };
+  }
+  if (typeof schema.$ref === "string" && !resolveLocalReference(root, schema.$ref)) {
+    return { path: path4, code: "unsupported_schema_ref", message: `Cannot resolve schema reference ${schema.$ref}.` };
+  }
+  const children = [];
+  if (isRecord(schema.properties)) children.push(...Object.entries(schema.properties));
+  if (isRecord(schema.$defs)) children.push(...Object.entries(schema.$defs));
+  if (isRecord(schema.definitions)) children.push(...Object.entries(schema.definitions));
+  children.push(
+    ["additionalProperties", schema.additionalProperties],
+    ["propertyNames", schema.propertyNames],
+    ["items", schema.items],
+    ...arraySchemaEntries("allOf", schema.allOf),
+    ...arraySchemaEntries("anyOf", schema.anyOf),
+    ...arraySchemaEntries("oneOf", schema.oneOf)
+  );
+  for (const [key, child] of children) {
+    if (!isRecord(child)) continue;
+    const issue = inspectSchema(child, `${path4}.${key}`, root, depth + 1);
+    if (issue) return issue;
+  }
+  return null;
+}
+function arraySchemaEntries(keyword, value) {
+  return Array.isArray(value) ? value.map((candidate, index) => [`${keyword}[${index}]`, candidate]) : [];
+}
+function validateNode(schema, value, path4, root, errors, depth) {
+  if (depth > 128) {
+    errors.push({ path: path4, code: "schema_depth", message: "Schema recursion exceeded 128 levels." });
+    return;
+  }
+  if (typeof schema.$ref === "string") {
+    const resolved = resolveLocalReference(root, schema.$ref);
+    if (!resolved) {
+      errors.push({ path: path4, code: "unsupported_schema_ref", message: `Cannot resolve schema reference ${schema.$ref}.` });
+      return;
+    }
+    validateNode(resolved, value, path4, root, errors, depth + 1);
+  }
+  if (Array.isArray(schema.allOf)) {
+    for (const candidate of schema.allOf) {
+      if (isRecord(candidate)) validateNode(candidate, value, path4, root, errors, depth + 1);
+    }
+  }
+  if (Array.isArray(schema.anyOf) && !schema.anyOf.some((candidate) => candidateMatches(candidate, value, root, depth))) {
+    errors.push({ path: path4, code: "any_of", message: "Value does not match any allowed schema." });
+    return;
+  }
+  if (Array.isArray(schema.oneOf)) {
+    const matches = schema.oneOf.filter((candidate) => candidateMatches(candidate, value, root, depth)).length;
+    if (matches !== 1) {
+      errors.push({ path: path4, code: "one_of", message: "Value must match exactly one allowed schema." });
+      return;
+    }
+  }
+  if (value === null && schema.nullable === true) return;
+  if (Object.prototype.hasOwnProperty.call(schema, "const") && !sameJsonValue(value, schema.const)) {
+    errors.push({ path: path4, code: "const", message: `Value must equal ${JSON.stringify(schema.const)}.` });
+    return;
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.some((candidate) => sameJsonValue(value, candidate))) {
+    errors.push({ path: path4, code: "enum", message: `Value must be one of ${schema.enum.map((item) => JSON.stringify(item)).join(", ")}.` });
+    return;
+  }
+  if (!matchesType(schema.type, value)) {
+    errors.push({ path: path4, code: "type", message: `Expected ${String(schema.type)}.` });
+    return;
+  }
+  if (typeof value === "string") validateString(schema, value, path4, errors);
+  if (typeof value === "number") validateNumber(schema, value, path4, errors);
+  if (Array.isArray(value)) validateArray(schema, value, path4, root, errors, depth);
+  if (isRecord(value)) validateObject(schema, value, path4, root, errors, depth);
+}
+function validateObject(schema, value, path4, root, errors, depth) {
+  if (typeof schema.minProperties === "number" && Object.keys(value).length < schema.minProperties) {
+    errors.push({ path: path4, code: "min_properties", message: `Expected at least ${schema.minProperties} properties.` });
+  }
+  if (typeof schema.maxProperties === "number" && Object.keys(value).length > schema.maxProperties) {
+    errors.push({ path: path4, code: "max_properties", message: `Expected at most ${schema.maxProperties} properties.` });
+  }
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  const required = Array.isArray(schema.required) ? schema.required.map(String) : [];
+  for (const key of required) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+      errors.push({ path: `${path4}.${key}`, code: "required", message: "Required property is missing." });
+    }
+  }
+  if (isRecord(schema.propertyNames)) {
+    for (const key of Object.keys(value)) {
+      validateNode(schema.propertyNames, key, `${path4}.${key}`, root, errors, depth + 1);
+    }
+  }
+  for (const [key, child] of Object.entries(value)) {
+    const childSchema = properties[key];
+    if (isRecord(childSchema)) {
+      validateNode(childSchema, child, `${path4}.${key}`, root, errors, depth + 1);
+    } else if (schema.additionalProperties === false) {
+      errors.push({ path: `${path4}.${key}`, code: "additional_property", message: "Property is not declared by the action schema." });
+    } else if (isRecord(schema.additionalProperties)) {
+      validateNode(schema.additionalProperties, child, `${path4}.${key}`, root, errors, depth + 1);
+    }
+  }
+}
+function validateArray(schema, value, path4, root, errors, depth) {
+  if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+    errors.push({ path: path4, code: "min_items", message: `Expected at least ${schema.minItems} items.` });
+  }
+  if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+    errors.push({ path: path4, code: "max_items", message: `Expected at most ${schema.maxItems} items.` });
+  }
+  if (schema.uniqueItems === true) {
+    const unique2 = new Set(value.map((item) => JSON.stringify(item)));
+    if (unique2.size !== value.length) errors.push({ path: path4, code: "unique_items", message: "Expected every item to be unique." });
+  }
+  if (isRecord(schema.items)) {
+    value.forEach((item, index) => validateNode(schema.items, item, `${path4}[${index}]`, root, errors, depth + 1));
+  }
+}
+function validateString(schema, value, path4, errors) {
+  if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+    errors.push({ path: path4, code: "min_length", message: `Expected at least ${schema.minLength} characters.` });
+  }
+  if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+    errors.push({ path: path4, code: "max_length", message: `Expected at most ${schema.maxLength} characters.` });
+  }
+  if (typeof schema.pattern === "string") {
+    try {
+      if (!new RegExp(schema.pattern).test(value)) errors.push({ path: path4, code: "pattern", message: "Value does not match the required pattern." });
+    } catch {
+      errors.push({ path: path4, code: "invalid_schema_pattern", message: "Action schema contains an invalid pattern." });
+    }
+  }
+  if (schema.format === "uri" && !isUrl(value)) errors.push({ path: path4, code: "format_uri", message: "Expected an absolute URL." });
+  if (schema.format === "email" && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value)) errors.push({ path: path4, code: "format_email", message: "Expected an email address." });
+  if (schema.format === "date-time" && !isDateTime(value)) errors.push({ path: path4, code: "format_date_time", message: "Expected an ISO-8601 date-time." });
+}
+function validateNumber(schema, value, path4, errors) {
+  if (typeof schema.minimum === "number" && value < schema.minimum) errors.push({ path: path4, code: "minimum", message: `Expected a value of at least ${schema.minimum}.` });
+  if (typeof schema.maximum === "number" && value > schema.maximum) errors.push({ path: path4, code: "maximum", message: `Expected a value of at most ${schema.maximum}.` });
+  const exclusiveMinimum = typeof schema.exclusiveMinimum === "number" ? schema.exclusiveMinimum : schema.exclusiveMinimum === true && typeof schema.minimum === "number" ? schema.minimum : null;
+  const exclusiveMaximum = typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : schema.exclusiveMaximum === true && typeof schema.maximum === "number" ? schema.maximum : null;
+  if (exclusiveMinimum !== null && value <= exclusiveMinimum) {
+    errors.push({ path: path4, code: "exclusive_minimum", message: `Expected a value greater than ${exclusiveMinimum}.` });
+  }
+  if (exclusiveMaximum !== null && value >= exclusiveMaximum) {
+    errors.push({ path: path4, code: "exclusive_maximum", message: `Expected a value less than ${exclusiveMaximum}.` });
+  }
+  if (typeof schema.multipleOf === "number" && !isMultipleOf(value, schema.multipleOf)) {
+    errors.push({ path: path4, code: "multiple_of", message: `Expected a multiple of ${schema.multipleOf}.` });
+  }
+}
+function candidateMatches(candidate, value, root, depth) {
+  if (!isRecord(candidate)) return false;
+  const issues = [];
+  validateNode(candidate, value, "$", root, issues, depth + 1);
+  return issues.length === 0;
+}
+function resolveLocalReference(root, reference) {
+  if (!reference.startsWith("#/")) return null;
+  let current = root;
+  for (const token of reference.slice(2).split("/").map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"))) {
+    if (Array.isArray(current)) {
+      if (!/^\d+$/.test(token) || Number(token) >= current.length) return null;
+      current = current[Number(token)];
+      continue;
+    }
+    if (!isRecord(current) || !Object.prototype.hasOwnProperty.call(current, token)) return null;
+    current = current[token];
+  }
+  return isRecord(current) ? current : null;
+}
+function matchesType(type, value) {
+  if (type === void 0) return true;
+  if (Array.isArray(type)) return type.some((candidate) => matchesType(candidate, value));
+  if (type === "null") return value === null;
+  if (type === "array") return Array.isArray(value);
+  if (type === "object") return isRecord(value);
+  if (type === "integer") return typeof value === "number" && Number.isInteger(value);
+  return typeof value === type;
+}
+function sameJsonValue(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function isUrl(value) {
+  try {
+    return Boolean(new URL(value).protocol);
+  } catch {
+    return false;
+  }
+}
+function isDateTime(value) {
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) && !Number.isNaN(Date.parse(value));
+}
+function isMultipleOf(value, divisor) {
+  if (!(divisor > 0)) return false;
+  const quotient = value / divisor;
+  return Math.abs(quotient - Math.round(quotient)) < Number.EPSILON * Math.max(1, Math.abs(quotient)) * 4;
+}
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 var TOPOLO_ACTION_ID_HEADER = "X-Topolo-Action-Id";
 var TOPOLO_ACTION_NAME_HEADER = "X-Topolo-Action-Name";
@@ -2317,7 +2573,10 @@ var TopoloClient = class _TopoloClient {
       serviceKey,
       overrides: this.serviceUrls
     });
-    return baseUrl ? { serviceKey, baseUrl } : null;
+    if (baseUrl) return { serviceKey, baseUrl };
+    const actionPage = await this.searchActions({ service: match.appId, limit: 1 }).catch(() => null);
+    const actionBaseUrl = actionPage?.actions.find((action) => action.apiBaseUrl)?.apiBaseUrl ?? null;
+    return actionBaseUrl ? { serviceKey, baseUrl: requireHttpOrigin(actionBaseUrl) } : null;
   }
   /**
    * Resolve a service-slug → opaque app-id via caller config or TopoloAuth.
@@ -2402,7 +2661,7 @@ var TopoloClient = class _TopoloClient {
     }
     const entries = [];
     for (const item of raw) {
-      if (!isRecord(item)) continue;
+      if (!isRecord2(item)) continue;
       const s = item;
       const appId = typeof s.app_id === "string" ? s.app_id : typeof s.id === "string" ? s.id : null;
       if (!appId) continue;
@@ -2452,6 +2711,44 @@ var TopoloClient = class _TopoloClient {
     }
     return entry;
   }
+  async listBindableResources(application) {
+    const service = await this.getService(application);
+    const identity = await this.introspect();
+    if (identity.apiKey) {
+      return {
+        application: { appId: service.appId, slug: service.slug, name: service.name },
+        organizationId: identity.organization?.id ?? null,
+        resources: identity.apiKey.resourceBindings.map((binding) => ({
+          resourceType: binding.resourceType,
+          resourceId: binding.resourceId,
+          label: null,
+          slug: null,
+          status: "active",
+          organizationId: identity.organization?.id ?? null,
+          metadata: {}
+        })),
+        resourceTypes: service.apiKeyResources,
+        syncError: null,
+        source: "api_key_binding"
+      };
+    }
+    const response = await this.readAction(
+      "app_topolo_auth.service_api_key_resources.list",
+      { appId: service.appId }
+    );
+    const payload = isRecord2(response) && isRecord2(response.data) ? response.data : response;
+    if (!isRecord2(payload) || !Array.isArray(payload.resources)) {
+      throw new TopoloSdkError("resource_catalog_unavailable", "TopoloAuth did not return bindable resources.");
+    }
+    return {
+      application: { appId: service.appId, slug: service.slug, name: service.name },
+      organizationId: readOptionalString(payload.organizationId ?? payload.organization_id),
+      resources: payload.resources.map(normalizeBindableResource).filter((resource) => Boolean(resource)),
+      resourceTypes: normalizeApiKeyResourceMetadataList(payload.resourceTypes ?? payload.resource_types),
+      syncError: readOptionalString(payload.syncError ?? payload.sync_error),
+      source: "auth_catalog"
+    };
+  }
   /**
    * List callable actions from the live registry-canonical catalog (definitions
    * from the Catalog registry, scoping from Auth). The response is scoped to the
@@ -2546,10 +2843,44 @@ var TopoloClient = class _TopoloClient {
     const entry = await this.getAction(action);
     return this.executeResolvedAction(entry, input2, options);
   }
+  async validateActionInput(action, input2 = {}) {
+    const entry = await this.getAction(action);
+    return { action: entry, validation: validateTopoloActionInput(entry.inputSchema, input2) };
+  }
+  async planAction(action, input2 = {}, options = {}) {
+    const entry = await this.getAction(action);
+    const validation = validateTopoloActionInput(entry.inputSchema, input2);
+    const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
+    const confirmationRequired = agentAccess === "confirm" || entry.requiresConfirmation || entry.destructive;
+    let request = null;
+    if (validation.valid) {
+      const mapped = mapActionInput(entry, input2);
+      request = {
+        method: entry.method,
+        service: entry.appSlug || entry.appId,
+        apiBaseUrl: entry.apiBaseUrl,
+        path: mapped.path,
+        ...mapped.query ? { query: mapped.query } : {},
+        ...mapped.body !== void 0 ? { body: mapped.body } : {},
+        ...options.resource ? { resource: options.resource } : {}
+      };
+    }
+    return {
+      action: entry,
+      validation,
+      confirmationRequired,
+      confirmationProvided: options.confirm === true,
+      executable: validation.valid && agentAccess !== "off" && (!confirmationRequired || options.confirm === true),
+      request,
+      verification: stringArray(entry.agentContract?.verify),
+      rollbackActionId: pickActionString(entry.agentContract?.rollbackActionId),
+      nextActionIds: stringArray(entry.agentContract?.nextActionIds)
+    };
+  }
   async readAction(action, input2 = {}, options = {}) {
     const entry = await this.getAction(action);
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
-    if (entry.method !== "GET" || !entry.readOnly || entry.destructive || entry.requiresConfirmation || agentAccess !== "auto") {
+    if (!entry.readOnly || entry.destructive || entry.requiresConfirmation || agentAccess !== "auto") {
       throw new TopoloPermissionError(
         `Topolo action "${entry.actionId}" is not an automatic read-only action.`,
         entry.requiredPermission ? [entry.requiredPermission] : []
@@ -2570,6 +2901,13 @@ var TopoloClient = class _TopoloClient {
         `Topolo action "${entry.actionId}" requires { confirm: true } before invocation.`
       );
     }
+    const validation = validateTopoloActionInput(entry.inputSchema, input2);
+    if (!validation.valid) {
+      throw new TopoloSdkError(
+        "invalid_action_input",
+        `Topolo action "${entry.actionId}" input is invalid: ${validation.errors.map((issue) => `${issue.path} ${issue.message}`).join("; ")}`
+      );
+    }
     const mapped = mapActionInput(entry, input2);
     const service = entry.appSlug || entry.appId;
     return this.request({
@@ -2584,7 +2922,7 @@ var TopoloClient = class _TopoloClient {
         [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
         [TOPOLO_ACTION_NAME_HEADER]: entry.name
       },
-      confirm: options.confirm === true
+      confirm: options.confirm === true || entry.readOnly && !entry.destructive && !entry.requiresConfirmation
     });
   }
   /**
@@ -2641,7 +2979,14 @@ var TopoloClient = class _TopoloClient {
         id: organization.id,
         slug: organization.slug,
         name: organization.name ?? organization.slug
-      } : user.orgId && user.orgSlug ? { id: user.orgId, slug: user.orgSlug, name: user.orgSlug } : null
+      } : user.orgId && user.orgSlug ? { id: user.orgId, slug: user.orgSlug, name: user.orgSlug } : null,
+      apiKey: kind === "api_key" ? {
+        id: readOptionalString(payload.apiKey?.id),
+        name: readOptionalString(payload.apiKey?.name),
+        appId: readOptionalString(payload.apiKey?.appId),
+        scopes: stringArray(payload.apiKey?.scopes),
+        resourceBindings: normalizeResourceBindings(payload.apiKey?.resourceBindings)
+      } : null
     };
   }
 };
@@ -2656,7 +3001,7 @@ function resolveConfiguredAppId(slug, appIds) {
   return null;
 }
 function normalizeApiKeyResourceMetadata(input2) {
-  if (!isRecord(input2)) return null;
+  if (!isRecord2(input2)) return null;
   const resourceType = readString(input2.resourceType ?? input2.resource_type);
   const label = readString(input2.label);
   const emptyLabel = readString(input2.emptyLabel ?? input2.empty_label);
@@ -2689,10 +3034,38 @@ function normalizeApiKeyResourceMetadataList(input2) {
   }
   return resources;
 }
+function normalizeBindableResource(input2) {
+  if (!isRecord2(input2)) return null;
+  const resourceType = readString(input2.resourceType ?? input2.resource_type);
+  const resourceId = readString(input2.resourceId ?? input2.resource_id);
+  if (!resourceType || !resourceId) return null;
+  return {
+    resourceType,
+    resourceId,
+    label: readOptionalString(input2.label),
+    slug: readOptionalString(input2.slug),
+    status: readOptionalString(input2.status),
+    organizationId: readOptionalString(input2.organizationId ?? input2.organization_id),
+    metadata: isRecord2(input2.metadata) ? input2.metadata : {}
+  };
+}
+function normalizeResourceBindings(input2) {
+  if (!Array.isArray(input2)) return [];
+  return input2.flatMap((binding) => {
+    if (!isRecord2(binding)) return [];
+    const resourceType = readString(binding.resourceType ?? binding.resource_type);
+    const resourceId = readString(binding.resourceId ?? binding.resource_id);
+    return resourceType && resourceId ? [{ resourceType, resourceId }] : [];
+  });
+}
 function readString(value) {
   return typeof value === "string" ? value.trim() : "";
 }
-function isRecord(value) {
+function readOptionalString(value) {
+  const normalized = readString(value);
+  return normalized || null;
+}
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function resolveConfiguredServiceUrl(slug, serviceUrls) {
@@ -2764,14 +3137,14 @@ function catalogSearchQuery(options) {
   return query;
 }
 function normalizeCatalogPage(value) {
-  if (!isRecord(value)) return { nextCursor: null, hasMore: false };
+  if (!isRecord2(value)) return { nextCursor: null, hasMore: false };
   return {
     nextCursor: typeof value.nextCursor === "string" && value.nextCursor ? value.nextCursor : null,
     hasMore: value.hasMore === true
   };
 }
 function normalizeServiceCatalogEntry(item) {
-  if (!isRecord(item)) return null;
+  if (!isRecord2(item)) return null;
   const appId = typeof item.app_id === "string" ? item.app_id : typeof item.id === "string" ? item.id : null;
   if (!appId) return null;
   const permissions = Array.isArray(item.granted_permissions) ? item.granted_permissions.filter(
@@ -2826,6 +3199,7 @@ function normalizeActionCatalogEntry(item) {
     authorizationMode: pickAuthorizationMode(a.authorization_mode ?? a.authorizationMode),
     inputSchema: plainObject(a.input_schema ?? a.inputSchema),
     outputSchema: plainObject(a.output_schema ?? a.outputSchema),
+    agentContract: plainObject(a.agent_contract ?? a.agentContract),
     readOnly: Boolean(a.read_only ?? a.readOnly),
     destructive: Boolean(a.destructive),
     requiresConfirmation: Boolean(a.requires_confirmation ?? a.requiresConfirmation),
@@ -2849,6 +3223,9 @@ function pickAuthorizationMode(value) {
 function plainObject(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
+function stringArray(value) {
+  return Array.isArray(value) ? value.map((item) => String(item || "").trim()).filter(Boolean) : [];
+}
 function mapActionInput(action, input2) {
   const remaining = { ...input2 || {} };
   const path4 = action.path.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, key) => {
@@ -3076,7 +3453,7 @@ function createTopolo(options) {
   };
 }
 
-// ../topolo-sdk/dist/node/credential-store.js
+// ../../../topolo-platform/packages/topolo-sdk/dist/node/credential-store.js
 import { mkdir, readFile, writeFile, chmod } from "fs/promises";
 import { existsSync } from "fs";
 import { homedir, platform } from "os";
@@ -3959,8 +4336,10 @@ function formatPretty(info) {
   return lines.join("\n");
 }
 
+// src/commands/actions.ts
+import { readFileSync as readFileSync2 } from "fs";
+
 // src/commands/api.ts
-var STATIC_APP_IDS = new Set(Object.keys(DEFAULT_APP_URLS));
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 var WRITE_METHODS2 = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 function registerApiCommand(program2) {
@@ -3987,9 +4366,8 @@ function registerApiCommand(program2) {
         const config = await readConfig();
         const profile = resolvedProfileConfig(config, environment);
         const configuredUrl = resolveConfiguredServiceUrl2(service, profile.serviceUrls);
-        const staticUrl = STATIC_APP_IDS.has(service) ? DEFAULT_APP_URLS[service] : void 0;
-        if (configuredUrl || staticUrl) {
-          assertServiceUrlForEnvironment(service, configuredUrl ?? staticUrl, environment);
+        if (configuredUrl) {
+          assertServiceUrlForEnvironment(service, configuredUrl, environment);
         }
         let body = void 0;
         if (opts.data) {
@@ -4096,7 +4474,7 @@ function registerActionsCommand(program2) {
       fail(err, mode);
     }
   });
-  actions.command("call <action>").description("Call a permission-scoped Topolo action").option("-d, --data <json>", "JSON action input", "{}").option("--resource-type <type>", "App-local resource alias, such as workspace").option("--resource-id <id>", "Resource id for the selected resource type").option("--confirm", "Acknowledge a mutating action").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
+  actions.command("call <action>").description("Call a permission-scoped Topolo action").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", "Acknowledge a mutating action").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 buildClient();
@@ -4114,11 +4492,78 @@ 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) => {
+    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"));
+    } 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) => {
+    const mode = resolveOutputMode(opts.json ?? command.parent?.opts().json);
+    try {
+      const topolo = await requiredClient();
+      const resource = parseResourceOption(opts.resourceType, opts.resourceId);
+      const plan = await topolo.client.planAction(action, parseJsonObject(opts.data || "{}"), {
+        confirm: opts.confirm === true,
+        ...resource ? { resource } : {}
+      });
+      emit(plan, mode, () => formatActionPlan(plan));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+  actions.command("examples <action>").description("Show published examples and public docs for one action").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 entry = await topolo.client.getAction(action);
+      const result = {
+        actionId: entry.actionId,
+        docsUrl: entry.agentContract?.docsUrl ?? null,
+        examples: entry.agentContract?.examples ?? []
+      };
+      emit(result, mode, () => result.examples.length ? JSON.stringify(result, null, 2) : `No inline examples published. Docs: ${result.docsUrl || "not published"}`);
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+  actions.command("capabilities").description("Discover capability and schema actions for one application").option("-s, --service <service>", "App id, slug, or name").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(), query: "capabilities", limit: 100 });
+      emit(result, mode, () => formatActionRows(result.actions, result.page.nextCursor));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+}
+async function requiredClient() {
+  const topolo = await buildClient();
+  if (!topolo) throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
+  return topolo;
 }
 function parseJsonObject(value) {
+  let source = value;
+  if (value.startsWith("@")) {
+    const path4 = value.slice(1);
+    if (!path4) throw new Error("--data @file path must not be empty");
+    try {
+      source = readFileSync2(path4, "utf8");
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(`Could not read --data file ${path4}: ${detail}`);
+    }
+  }
   let parsed;
   try {
-    parsed = JSON.parse(value);
+    parsed = JSON.parse(source);
   } catch {
     throw new Error("--data must be valid JSON");
   }
@@ -4164,21 +4609,37 @@ function formatActionDetail(action) {
     `Path:         ${action.path}`,
     `Permission:   ${action.requiredPermission}`,
     `Confirmation: ${action.requiresConfirmation ? "required" : "not required"}`,
+    `Docs:         ${action.agentContract?.docsUrl || "-"}`,
+    `Rollback:     ${action.agentContract?.rollbackActionId || "-"}`,
     "",
     action.description
   ].join("\n");
 }
+function formatActionPlan(plan) {
+  const lines = [
+    `Action:       ${plan.action.actionId}`,
+    `Valid:        ${plan.validation.valid ? "yes" : "no"}`,
+    `Executable:   ${plan.executable ? "yes" : "no"}`,
+    `Confirmation: ${plan.confirmationRequired ? plan.confirmationProvided ? "provided" : "required" : "not required"}`
+  ];
+  if (plan.request) lines.push(`Request:      ${plan.request.method} ${plan.request.apiBaseUrl || plan.request.service}${plan.request.path}`);
+  if (plan.request?.resource) lines.push(`Resource:     ${plan.request.resource.resourceType}:${plan.request.resource.resourceId}`);
+  if (plan.validation.errors.length) lines.push("", ...plan.validation.errors.map((issue) => `${issue.path}: ${issue.message}`));
+  if (plan.verification.length) lines.push("", "Verify:", ...plan.verification.map((step) => `- ${step}`));
+  if (plan.rollbackActionId) lines.push("", `Rollback: ${plan.rollbackActionId}`);
+  return lines.join("\n");
+}
 
 // src/commands/apps.ts
 import { execSync } from "child_process";
-import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync4, writeFileSync } from "fs";
 import path2 from "path";
 
 // src/commands/app-audit-local.ts
 import {
   existsSync as existsSync2,
   readdirSync,
-  readFileSync as readFileSync2,
+  readFileSync as readFileSync3,
   statSync
 } from "fs";
 import path from "path";
@@ -4189,7 +4650,7 @@ function readEvidenceFile(appRoot) {
   const candidate = path.join(appRoot, ".topolo", "evidence.json");
   if (!isFile(candidate)) return null;
   try {
-    const raw = JSON.parse(readFileSync2(candidate, "utf8"));
+    const raw = JSON.parse(readFileSync3(candidate, "utf8"));
     if (raw && typeof raw === "object" && raw.version === 1) {
       return raw;
     }
@@ -5133,7 +5594,7 @@ function readSourceIndex(root) {
   const files = collectSourceFiles(root, 4e3);
   const chunks = files.map((file) => {
     try {
-      return readFileSync2(file, "utf8");
+      return readFileSync3(file, "utf8");
     } catch {
       return "";
     }
@@ -5193,7 +5654,7 @@ function sortedDirEntries(dir) {
 function readJson(filePath) {
   if (!isFile(filePath)) return null;
   try {
-    return JSON.parse(readFileSync2(filePath, "utf8"));
+    return JSON.parse(readFileSync3(filePath, "utf8"));
   } catch {
     return null;
   }
@@ -9289,7 +9750,8 @@ function applicationRowsFromCatalog(catalog) {
     name: entry.name ?? entry.slug ?? entry.appId,
     appDir: "-",
     packageName: null,
-    productionUrl: entry.launchUrl ?? null,
+    apiBaseUrl: entry.apiBaseUrl ?? null,
+    launchUrl: entry.launchUrl ?? null,
     services: [displayCatalogId(entry)],
     deployTargets: 0
   })).sort((left, right) => left.id.localeCompare(right.id));
@@ -9354,7 +9816,7 @@ function recordApplicationEvidence(application, options = {}) {
   let before = null;
   if (existsSync3(evidencePath)) {
     try {
-      const raw = JSON.parse(readFileSync3(evidencePath, "utf8"));
+      const raw = JSON.parse(readFileSync4(evidencePath, "utf8"));
       if (raw && typeof raw === "object" && raw.version === 1) {
         before = raw;
       }
@@ -9434,7 +9896,7 @@ function evaluateApplicationAuditGate(payload, failOn) {
 function formatRows(rows) {
   const idWidth = Math.max(2, ...rows.map((r) => r.id.length));
   const nameWidth = Math.max(4, ...rows.map((r) => r.name.length));
-  const urlWidth = Math.max(3, ...rows.map((r) => (r.productionUrl ?? "-").length));
+  const urlWidth = Math.max(3, ...rows.map((r) => (applicationUrl(r) ?? "-").length));
   const servicesWidth = Math.max(
     8,
     ...rows.map((r) => r.services.length ? r.services.join(",").length : 1)
@@ -9449,7 +9911,7 @@ function formatRows(rows) {
   for (const r of rows) {
     const services = r.services.length ? r.services.join(",") : "-";
     lines.push(
-      `${r.id.padEnd(idWidth)}  ${r.name.padEnd(nameWidth)}  ${(r.productionUrl ?? "-").padEnd(urlWidth)}  ${services.padEnd(servicesWidth)}  ${r.deployTargets}`
+      `${r.id.padEnd(idWidth)}  ${r.name.padEnd(nameWidth)}  ${(applicationUrl(r) ?? "-").padEnd(urlWidth)}  ${services.padEnd(servicesWidth)}  ${r.deployTargets}`
     );
   }
   return lines.join("\n");
@@ -9458,10 +9920,14 @@ function formatApplicationRow(application) {
   return [
     `ID: ${application.id}`,
     `Name: ${application.name}`,
-    `URL: ${application.productionUrl ?? "-"}`,
+    `API URL: ${application.apiBaseUrl ?? "-"}`,
+    `Launch URL: ${application.launchUrl ?? application.productionUrl ?? "-"}`,
     `Services: ${application.services.length ? application.services.join(", ") : "-"}`
   ].join("\n");
 }
+function applicationUrl(application) {
+  return application.apiBaseUrl ?? application.launchUrl ?? application.productionUrl ?? null;
+}
 function displayCatalogId(entry) {
   for (const value of [entry.slug, entry.name, entry.appId]) {
     if (typeof value !== "string" || !value.trim()) continue;
@@ -9645,7 +10111,7 @@ function statusesAtOrWorse(threshold) {
 }
 
 // src/commands/platform.ts
-import { readdirSync as readdirSync2, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync5, statSync as statSync2 } from "fs";
 import path3 from "path";
 function registerPlatformCommand(program2) {
   const platform3 = program2.command("platform").description("Internal Topolo first-party platform and personal app commands");
@@ -9779,7 +10245,7 @@ function scanStagingProductionUrls(rootInput, allowPatterns) {
   function scanFile(filePath) {
     if (shouldSkipFile(filePath)) return;
     const relativePath = path3.relative(root, filePath);
-    const content = readFileSync4(filePath, "utf8");
+    const content = readFileSync5(filePath, "utf8");
     const lines = content.split(/\r?\n/);
     lines.forEach((line, index) => {
       const matches = [...line.matchAll(PRODUCTION_TOPOLO_URL_PATTERN)].map((match) => match[0]);
@@ -10859,6 +11325,34 @@ 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) => {
+    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);
+      emit(result, mode, () => formatResources(result));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+}
+function formatResources(result) {
+  const lines = [
+    `Application: ${result.application.name || result.application.slug || result.application.appId}`,
+    `Source:      ${result.source}`
+  ];
+  if (result.resources.length === 0) return [...lines, "", "No bindable resources available."].join("\n");
+  lines.push("", "TYPE  ID  LABEL");
+  for (const resource of result.resources) {
+    lines.push(`${resource.resourceType}  ${resource.resourceId}  ${resource.label || resource.slug || "-"}`);
+  }
+  if (result.syncError) lines.push("", `Sync warning: ${result.syncError}`);
+  return lines.join("\n");
+}
+
 // src/index.ts
 var program = new Command();
 var argv;
@@ -10889,6 +11383,7 @@ registerServicesCommand(program);
 registerSeedCommands(program);
 registerSkillsCommand(program);
 registerContextCommand(program);
+registerResourcesCommand(program);
 program.parseAsync(argv).catch((err) => {
   process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/cli",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "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/codex/AGENTS.md

@@ -1,6 +1,6 @@
 # Topolo — agent guide (Codex / general-purpose agents)
 
-This file teaches an agent how to interact with the Topolo platform via the `topolo` CLI and, when available, the Topolo MCP server. It is intentionally short, shell-first, and stable across Codex, Cursor, and any other agent that reads `AGENTS.md`.
+This file teaches an agent how to interact with the Topolo platform via the `topolo` CLI and, when available, the Topolo MCP server. It assumes no repository access or private product knowledge; public Topolo docs and credential-scoped runtime discovery are authoritative.
 
 ## What the platform is
 
@@ -11,6 +11,7 @@ Topolo is a multi-app SaaS platform. The CLI and MCP server both use `@topolo/sd
 - Use `topolo apps audit <application_id> --json` or the MCP `topolo_audit_applications` tool to inspect current requirement conformance and migration work.
 - Use `topolo services --json` or the MCP `topolo_search_applications` tool to discover callable app ids and effective URLs.
 - Use `topolo actions --service <app> --json` or MCP `topolo_search_actions` to discover callable operations granted to the current credential; invoke automatic reads with `topolo_read_action` and confirmation-gated operations with `topolo_call_action`.
+- Use `topolo actions capabilities`, `actions examples`, `actions validate`, and `actions plan` (or their MCP equivalents) to obtain schemas, examples, verification, and rollback before execution.
 - The generic `api` command and MCP `topolo_api_call` tool can reach bundled SDK services and live Auth-catalog API/technical services when no action contract exists yet.
 
 Every call is scoped to the organization embedded in the credential. There is no `--org` flag anywhere — attempting to target another org will fail.
@@ -94,6 +95,11 @@ URL and the CLI will refuse `topolo api` calls until a staging override is set.
 ```bash
 topolo actions --service mail --json
 topolo actions get app_topolo_mail.messages.send --json
+topolo actions examples app_topolo_mail.messages.send --json
+topolo actions validate app_topolo_mail.messages.send \
+  --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' --json
+topolo actions plan app_topolo_mail.messages.send \
+  --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' --json
 topolo actions call app_topolo_mail.messages.send \
   --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
   --confirm --json
@@ -104,6 +110,10 @@ operations. It is filtered by the signed-in organization and the exact service
 permissions on the credential. Actions marked `authorizationMode: "runtime"`
 have input-dependent policy and are definitively authorized by the target app
 for the supplied organization, application, and resource at invocation time.
+Never guess a missing action, field, resource id, endpoint, verification step,
+or rollback. If catalog metadata and `https://docs.topolo.app` do not provide a
+complete contract, report the missing publication contract instead of reading
+source code or inferring a private API.
 
 ### Generic passthrough
 
@@ -151,5 +161,4 @@ Do not batch writes. Do not retry a failed write without re-confirming. The `--c
 
 - Documentation: `https://docs.topolo.app` (guides, authentication, API reference).
 - Developers console (register apps / OAuth clients): `https://developers.topolo.app`
-- CLI README: the `README.md` alongside this file.
-- Schemas: `packages/topolo-sdk/src/modules/` in the monorepo.
+- CLI help: `topolo --help` and `topolo <command> --help`.

package/skills/topolo/SKILL.md

@@ -1,248 +1,226 @@
 ---
 name: topolo
-description: Read and write Topolo platform data (identity, application/service discovery, credential-scoped actions, and any SDK-registered Topolo API) from the shell via the `topolo` CLI. Use whenever the user references their Topolo organization, a Topolo app/service, or asks to mint/inspect Topolo credentials.
+description: Operate the Topolo platform from any computer using only public Topolo documentation and credential-scoped CLI or MCP discovery. Use for Topolo identity, organizations, applications, resources, actions, OAuth, and API keys.
 ---
 
-# Topolo platform
+# Topolo clean-room operator
 
-The `topolo` CLI is the agent-friendly entry point to the Topolo platform. Every command runs in the **active context** embedded in the current credential — the user's personal space or a specific organization. You cannot bypass the credential or forge a context; to act in a different organization (or personal), switch with `topolo context use` (see Contexts).
+Use Topolo without repository access, private schemas, or prior product knowledge. The authenticated CLI/MCP catalog and `https://docs.topolo.app` are the only operational sources of truth.
 
-## When this skill fires
+Never inspect or request Topolo source code for ordinary platform work. Never invent an endpoint, action id, field, enum, resource id, permission, verification step, or rollback. If the live contract and public docs do not provide enough information, report the exact missing metadata as a platform contract defect.
 
-Use `topolo` whenever the user:
+## Install and connect
 
-- References records, messages, customers, or any other data stored in a Topolo app.
-- Asks about their Topolo identity ("who am I logged in as", "what org am I in", "what scopes do I have").
-- Wants to call an endpoint under a Topolo service from the shell.
-- Mentions a Topolo OAuth client (`doac_…`) or API key.
+The CLI requires Node 20 or newer:
 
-If the user asks a platform question and `topolo` is not installed, install it: `npm install -g @topolo/cli`. Requires Node ≥ 20. To wire this skill and the MCP server into Claude Code / Codex in one step, run `topolo skills install` (copies the skill file, registers the `topolo` MCP; no API key needed — the MCP reads the same credential `topolo auth login` writes).
+```bash
+command -v topolo || npm install -g @topolo/cli
+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`.
 
-## Credentials — always check first
+Production is the default. Use `--env staging` on every staging command, or set `TOPOLO_ENV=staging`. Never mix staging discovery with production execution.
 
-Before any data command, confirm a credential is configured:
+## Authentication gate
+
+Start every session with:
 
 ```bash
 topolo auth status --json
+topolo whoami --json
 ```
 
-Production is the default environment. Use `--env staging` anywhere in the
-command, or set `TOPOLO_ENV=staging`, when the user is testing internal staging
-or provisioning a staging-only first-party app:
+If `source` is `none`, run `topolo auth login` and wait for browser approval. The built-in first-party OAuth client needs no client id. For a headless session, use `topolo auth login --api-key=<key>` or inject `TOPOLO_API_KEY` for one command. Never store credentials in a project or tracked file.
+
+Authentication scopes and effective authorization are different:
+
+- OAuth scopes describe what the token may ask the platform to do.
+- `whoami`, the credential-scoped application catalog, action catalog, target policy, and resource binding determine what the current identity may actually do.
+- An action with `authorizationMode: "runtime"` is discoverable, but the target application makes the final authorization decision from the concrete input and credential context.
+- A 403 is authoritative. Do not retry it with guessed fields, another endpoint, or broader behavior.
+
+The credential fixes the personal or organization context. There is no `--org` override:
 
 ```bash
-topolo auth status --env staging --json
-topolo auth login --env staging
+topolo context ls --json
+topolo context use <organization-name|personal> --json
+topolo whoami --json
 ```
 
-Possible `source` values:
+For concurrent agents or multiple MCP connections, never coordinate by changing
+one shared active context. Register one named `topolo-mcp` process per context
+with both `TOPOLO_ENV` and `TOPOLO_CONTEXT`. The context selector accepts an
+exact key returned by `topolo context ls --json` (such as `personal` or
+`org:<orgId>`) or a unique stored organization id, slug, or name. Each process
+reads and refreshes only its pinned credential without changing the CLI or web
+session. Do not set `TOPOLO_CONTEXT` alongside an injected API key or access
+token because that credential already carries its immutable context.
 
-| source | meaning |
-| --- | --- |
-| `env:TOPOLO_STAGING_API_KEY` / `env:TOPOLO_PRODUCTION_API_KEY` | Environment-specific service-scoped API key in env |
-| `env:TOPOLO_STAGING_ACCESS_TOKEN` / `env:TOPOLO_PRODUCTION_ACCESS_TOKEN` | Environment-specific short-lived access token in env |
-| `env:TOPOLO_API_KEY` | Shared service-scoped API key in env |
-| `env:TOPOLO_ACCESS_TOKEN` | Shared short-lived access token in env (dev/testing) |
-| `config-file` | Token stored in the selected environment profile at `$XDG_CONFIG_HOME/topolo/config.json` |
-| `none` | Not signed in — call `topolo auth login` |
+## Mandatory clean-room workflow
 
-If `source: none`, run `topolo auth login` (add `--env staging` for staging) and
-tell the user to approve the device in the browser tab that opens. The CLI uses
-its **built-in first-party client**, so **no `--client-id` is needed** — any
-Topolo user can sign in; what they can then do is decided by their permissions.
-The CLI blocks until they approve, then stores the token in that environment's
-active-context profile. (`--client-id=<doac_…>` is only for advanced/self-hosted
-setups that register their own OAuth client.)
+For every Topolo task, follow this sequence.
 
-For service-agent / headless installs, use an API key with
-`topolo auth login --api-key=<key>` or set `TOPOLO_API_KEY` only for the single
-command that needs it.
+### 1. Discover the application and resource boundary
 
-## Output modes
+```bash
+topolo apps --json
+topolo apps get <application> --json
+topolo services --query <application> --json
+topolo resources <application> --json
+```
 
-All commands support `--json` (machine) and `--no-json` (human). The CLI autodetects: pretty when stdout is a TTY, JSON when piped. **When you call `topolo` from an agent, always pass `--json`** — the JSON shape is stable; the pretty text is not.
+Use the returned app id or slug. Read `apiKeyResources` to learn whether calls can be scoped to aliases such as a workspace, site, mailbox, brand, or venue. Use `topolo resources` to resolve the actual credential-scoped resource ids. With an API key it returns only the key's bound resources; with OAuth it uses the published Auth resource catalog. Never assume that an organization id is a valid app resource id.
 
-## Command reference
+MCP equivalents:
 
-### Identity
+- `topolo_search_applications`
+- `topolo_get_application`
+- `topolo_get_resource_types`
+- `topolo_list_resources`
+
+### 2. Discover credential-scoped actions
 
 ```bash
-topolo whoami --json
+topolo actions --service <app-id-or-slug> --query <task-keyword> --limit 25 --json
+topolo actions capabilities --service <app-id-or-slug> --json
+topolo actions get <exact-action-id> --json
+topolo actions examples <exact-action-id> --json
 ```
 
-Returns `{ user: { email, name, role, permissions }, organization: { name, slug } | null, kind }`.
+Inspect the published input/output JSON Schemas and agent contract. The agent contract may provide:
 
-Use this once at the start of a session to confirm the active user + org — then reference that org context in subsequent explanations so the user doesn't have to re-orient.
+- public `docsUrl`
+- resource kind and id/version paths
+- effects
+- actionable error codes and recovery
+- verification steps
+- rollback action id
+- next actions
+- runnable examples
 
-### Contexts (personal + multiple organizations)
+MCP equivalents:
 
-A user can act in their **personal** space or in any **organization** they belong to. Each context has its own credential; the CLI and MCP always operate in the **active** one.
+- `topolo_search_actions`
+- `topolo_discover_capabilities`
+- `topolo_get_action`
+- `topolo_get_action_examples`
 
-CLI/MCP context is credential-bound and independent from the user's web
-switcher preference. `topolo context use` does not move the browser session;
-switching in the browser does not alter any issued CLI/MCP token or refresh
-chain. Multiple cached personal/org credentials can therefore coexist safely.
+If discovery returns no relevant action, search `https://docs.topolo.app`. Use `topolo api` only when public docs give the exact service, method, path, schema, authorization, and verification behavior. Absence of a catalog action is not permission to infer a private API.
+
+### 3. Resolve identifiers through published reads
+
+Prefer `topolo resources <application> --json` or `topolo_list_resources` to resolve required resource ids. If the target publishes a more specific read-only resource action, use it for app-local identifiers. Do not guess ids from names or copy ids from a different organization/context.
+
+For an app-local resource boundary, pass resource context separately from action input:
 
 ```bash
-topolo context ls --json                              # personal + your orgs, and which is active
-topolo context use <organization-name|personal> --json  # switch the active context
+topolo actions call <read-action-id> \
+  --resource-type <published-resource-type> \
+  --resource-id <resolved-resource-id> \
+  --data '<schema-valid-json>' --json
 ```
 
-`topolo context use` activates a cached context or exchanges the current credential for a fresh token scoped to the target (membership is validated server-side). After switching, `topolo whoami` and every subsequent command run in that context. There is **no `--org` flag** — switch context instead. If a command returns a permission error, the user may need to switch to the org that owns the resource, or be granted access there.
+Provide `--resource-type` and `--resource-id` together. MCP read actions use `topolo_read_action` with the same separate resource fields.
+
+For API-key creation or updates, do not use the application's general resource list as the authorization decision. Discover and call Auth's `api_keys.options` action with the selected application and active organization. Its response is the complete caller-specific contract for that key operation: organization-wide scopes, deduplicated resource types, authorized resources, each resource's access level and allowed scopes, and whether key creation is allowed.
+
+Choose resource bindings before scopes. With no bindings, use only `organizationWideScopes`. With one or more bindings, use only the intersection of `allowedScopes` across every selected resource. Then validate and plan `api_keys.create` or `api_keys.update` with that exact selection. Never widen, merge, or infer eligibility from application metadata, organization ownership alone, or a resource returned in another organization context.
 
-### Application and service discovery
+### 4. Validate locally
+
+Before every call, validate exact input against the published JSON Schema:
 
 ```bash
-topolo apps --json
-topolo apps get <application_id> --json
-topolo apps requirements <application_id> --json
-topolo apps audit <application_id> --json
-topolo services --json
-topolo actions --service <application_id_or_slug> --json
+topolo actions validate <action-id> --data '<json>' --json
 ```
 
-`topolo apps` returns every cataloged Topolo application, including browser-only
-Worker apps that do not expose a callable API. `topolo services` returns every
-SDK-app id with its default and effective URL. In staging, a
-service with `environmentSafe: false` still resolves to a production SDK URL and
-the CLI refuses `topolo api` calls for it until a staging URL override is set.
-`topolo apps requirements` returns the current versioned app-build contract and should be run
-before creating or expanding a Topolo app. `topolo apps audit` returns
-catalog-backed requirement scores and migration work. Run `topolo services`
-before `topolo api` when you are not using a cataloged action.
+MCP: `topolo_validate_action`.
 
-### Credential-scoped actions
+For large inputs, write one schema-valid JSON object to a file and pass it without shell escaping:
 
 ```bash
-topolo actions --service mail --json
-topolo actions get app_topolo_mail.messages.send --json
-topolo actions call app_topolo_mail.messages.send \
-  --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
-  --confirm --json
+topolo actions validate <action-id> --data @payload.json --json
+topolo actions plan <action-id> --data @payload.json --json
+topolo actions call <action-id> --data @payload.json --confirm --json
 ```
 
-`topolo actions` returns the credential-scoped action catalog. Static actions
-are filtered by the current organization and permissions. An action with
-`authorizationMode: "runtime"` has input-dependent policy; it remains
-discoverable, and the target app authorizes the concrete organization,
-application, and resource on every call. Prefer catalog actions over `topolo
-api` when the target app has published a machine contract through Topolo
-Developers. Writes require `--confirm`.
+Fix every returned path-level validation error. Never add undeclared fields to work around a failure.
 
-For an app-local workspace or other resource boundary, pass the resource
-separately from the action input. Resource selection is per invocation: it does
-not switch the personal/organization credential context or the browser session.
+### 5. Plan without execution
 
 ```bash
-topolo actions call app_topolo_inventory.dashboard.get \
-  --resource-type workspace \
-  --resource-id <workspace_id> \
-  --data '{}' --json
+topolo actions plan <action-id> --data '<json>' --json
 ```
 
-Use a published workspace-list action to discover IDs when the app has multiple
-workspaces. For a single default workspace, use the active organization ID from
-`topolo whoami --json` when that app defines its workspace as the organization
-boundary. Always provide `--resource-type` and `--resource-id` together.
+MCP: `topolo_plan_action`.
 
-### Generic API passthrough
+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.
 
-For any endpoint that doesn't yet have a typed subcommand:
+### 6. Confirm mutations
 
-```bash
-topolo api <service> <method> <path> [--data '<json>'] [--query key=value] [--confirm]
-```
+For a mutation, show the user:
 
-- `<service>`: any id from `topolo services --json`.
-- `<method>`: `GET` | `POST` | `PUT` | `PATCH` | `DELETE`.
-- `<path>`: starts with `/api/…` — don't include the host.
-- **Mutating calls require `--confirm`**. If you omit it, the CLI refuses and exits non-zero. This is intentional: confirm before sending writes.
+- exact action id
+- target method and path from the plan
+- exact input and resource context
+- published effects
+- verification steps
+- rollback action, or that no rollback is published
 
-Examples:
+Obtain explicit approval unless the user already gave unambiguous authorization for this exact production work. The CLI’s `--confirm` is a transport guardrail, not user approval.
 
-```bash
-# Read current user via auth service
-topolo api auth GET /api/me --json
+Automatic read-only actions use no confirmation. Confirmed actions use:
 
-# Send mail through a published action (requires confirm)
-topolo actions call app_topolo_mail.messages.send \
-  --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
-  --confirm --json
+```bash
+topolo actions call <action-id> --data '<json>' --confirm --json
 ```
 
-## Error handling
+MCP uses `topolo_read_action` for automatic reads and `topolo_call_action` with `confirm: true` for approved mutations.
 
-Exit codes:
+### 7. Verify and recover
 
-| Code | Meaning | Action |
-| --- | --- | --- |
-| 0 | Success | — |
-| 1 | Generic error | Surface message to user |
-| 2 | Auth error (expired, invalid token) | Run `topolo auth login` and retry |
-| 3 | Permission denied | User's role/scopes lack the capability — point them to the Developers console |
+Run every published verification step immediately after execution. Prefer a credential-scoped read action and compare returned ids, versions, status, or URLs to the mutation result.
 
-In `--json` mode, errors come on stderr as `{"error":{"message","code","hint","exitCode"}}`. Parse `code` first when branching.
+If verification fails:
 
-Stored OAuth access tokens refresh automatically when the config contains both a refresh token and the OAuth client id used at login. If `whoami` still returns `auth_error`, have the user re-run `topolo auth login`.
+1. Preserve the action result and request id.
+2. Read the published error recovery guidance.
+3. Plan the published rollback action before calling it.
+4. Obtain confirmation for the rollback unless prior authorization explicitly covered recovery.
+5. Execute and verify the rollback.
 
-## Safety rules
+Never improvise a rollback.
 
-1. **Never run a mutating `topolo actions call …` or `topolo api … POST|PUT|PATCH|DELETE …` without surfacing the exact body to the user first** and confirming. The `--confirm` flag is a guardrail, not your approval.
-2. **Never write credentials to tracked files.** If a user pastes an API key inline, use it via env var for that invocation (`TOPOLO_API_KEY=… topolo whoami`) rather than committing it.
-3. **Cross-org isolation is built-in** — there is no `--org` flag anywhere, and the backend rederives the org from the credential (it ignores org hints in a request body). To act in a different organization, use `topolo context use <org>` to switch the active context — never try to fake one via the passthrough.
-4. Audit headers (`X-Topolo-Client`, `X-Topolo-Request-Id`, optional `X-Topolo-Agent`) are set by the CLI automatically. If `TOPOLO_AGENT_NAME` is already exported in the user's shell, leave it alone — it's the audit trail.
+## Generic public API escape hatch
 
-## Common flows
+Only when public docs provide a complete contract:
 
-**"Show me the available Mail actions"**
 ```bash
-topolo whoami --json   # confirm org
-topolo actions --service mail --json
+topolo api <service> <GET|POST|PUT|PATCH|DELETE> <path> \
+  [--query key=value] [--data '<json>'] [--confirm] --json
 ```
 
-**"Send a message through Mail"**
-```bash
-topolo actions call app_topolo_mail.messages.send \
-  --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
-  --confirm --json
-```
+Discover `<service>` with `topolo services --json`. Mutating methods require explicit approval and `--confirm`. Prefer catalog actions because they carry schemas, effects, verification, and recovery metadata.
 
-**"What scopes does my CLI token have?"**
-```bash
-topolo whoami --json | jq '.user.permissions'
-```
+## Errors and recovery
 
-**"What app id should I use?"**
-```bash
-topolo apps --json
-topolo apps requirements <application_id> --json
-topolo apps audit <application_id> --json
-topolo services --json
-topolo actions --service mail --json
-```
+In JSON mode, branch on `error.code`, not message text:
 
-**"Sign me in fresh"**
-```bash
-topolo auth logout
-topolo auth login          # no --client-id needed; approve in the browser
-```
+- exit 2 / authentication error: run `topolo auth login`, then repeat identity and discovery.
+- exit 3 / permission denied: surface the missing permission or target denial; do not retry or widen access.
+- `invalid_action_input`: correct only the reported schema paths.
+- `confirmation_required`: plan, obtain approval, then retry once with confirmation.
+- unknown action/service: repeat bounded discovery; never substitute a guessed identifier.
+- missing docs/schema/examples/verification/recovery: stop the affected operation and report the missing publication contract.
 
-**"Sign me in to staging"**
-```bash
-topolo auth logout --env staging
-topolo auth login --env staging
-topolo whoami --env staging --json
-```
+Use `TOPOLO_DEBUG=1` only when diagnostics are needed. Preserve `X-Topolo-Request-Id` from failures for support. Do not expose tokens or API keys in output.
 
-**"Switch to my <Acme> organization" / "work in my personal space"**
-```bash
-topolo context ls --json
-topolo context use acme --json      # or: topolo context use personal
-```
+## Public references
 
-## Where to learn more
+- Documentation: `https://docs.topolo.app`
+- Staging documentation: `https://docs.stg.topolo.us`
+- Developers console: `https://developers.topolo.app`
+- CLI help: `topolo --help` and `topolo <command> --help`
 
-- **Topolo documentation:** https://docs.topolo.app — guides (authentication, quick start), API reference, and per-app docs. (Staging: https://docs.stg.topolo.us)
-- Register apps / OAuth clients: the Developers console at https://developers.topolo.app
-- CLI source (for an undocumented flag): `packages/topolo-cli/src/commands/` in the topolo-platform monorepo.
-- SDK package: `packages/topolo-sdk/src/` — authoritative client, dynamic action catalog, and shared response contracts.
+These public surfaces and credential-scoped runtime responses are authoritative. Repository access is neither required nor an accepted fallback.