@topolo/cli 0.2.3 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/cli",
-  "version": "0.2.3",
+  "version": "0.3.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,213 @@
 ---
 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:
+## Mandatory clean-room workflow
 
-| 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` |
+For every Topolo task, follow this sequence.
 
-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.)
+### 1. Discover the application and resource boundary
 
-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.
+```bash
+topolo apps --json
+topolo apps get <application> --json
+topolo services --query <application> --json
+topolo resources <application> --json
+```
 
-## Output modes
+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.
 
-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.
+MCP equivalents:
 
-## Command reference
+- `topolo_search_applications`
+- `topolo_get_application`
+- `topolo_get_resource_types`
+- `topolo_list_resources`
 
-### Identity
+### 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:
+
+- public `docsUrl`
+- resource kind and id/version paths
+- effects
+- actionable error codes and recovery
+- verification steps
+- rollback action id
+- next actions
+- runnable examples
 
-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.
+MCP equivalents:
 
-### Contexts (personal + multiple organizations)
+- `topolo_search_actions`
+- `topolo_discover_capabilities`
+- `topolo_get_action`
+- `topolo_get_action_examples`
 
-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.
+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.
 
-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.
+### 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.
 
-### 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.