@topolo/cli 0.7.4 → 0.8.0

package/skills/codex/AGENTS.md

@@ -1,164 +0,0 @@
-# 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 assumes no repository access or private product knowledge; public Topolo docs and credential-scoped runtime discovery are authoritative.
-
-## What the platform is
-
-Topolo is a multi-app SaaS platform. The CLI and MCP server both use `@topolo/sdk`; every application resolves from the live credential-scoped registry, so newly registered apps and API/technical services work immediately — there is no bundled application catalog to rely on or wait for.
-
-- Use `topolo apps --json` or the MCP `topolo_search_applications` tool to discover platform applications, including browser-only Worker apps.
-- Use `topolo apps requirements <application_id> --json` or the MCP `topolo_list_application_requirements` tool before creating or expanding a Topolo app.
-- 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 any live Auth-catalog application or API/technical service when no action contract exists yet; discover ids with `topolo apps --json` first.
-
-Every call is scoped to the organization embedded in the credential. There is no `--org` flag anywhere — attempting to target another org will fail.
-
-## Invocation contract
-
-Always call `topolo` with `--json` from an agent. JSON schemas are stable; human text is not.
-
-```bash
-topolo <command> [args] --json
-```
-
-Production is the default CLI environment. Use `--env staging` anywhere in the
-command, or set `TOPOLO_ENV=staging`, for internal staging auth, staging service
-discovery, or staging scaffold provisioning. Staging credentials are stored
-separately from production credentials.
-
-On success the command prints JSON to stdout and exits 0. On failure it prints `{"error":{"message","code","hint","exitCode"}}` to stderr and exits non-zero. Branch on `code` (not on message text).
-
-Exit codes:
-
-- `0` success
-- `1` generic error
-- `2` auth error → run `topolo auth login` and retry
-- `3` permission denied → the user's role/scopes are insufficient; surface to user, do not retry
-
-## Setup flow
-
-1. Check install: `command -v topolo || npm install -g @topolo/cli` (requires Node ≥ 20). To wire the skill + MCP into this agent, run `topolo skills install` (credential-free — the MCP reads the `topolo auth login` credential).
-2. Check credential: `topolo auth status --json`.
-3. For staging work, check credential with `topolo auth status --env staging --json`.
-4. If `source` is `none`, run `topolo auth login` (add `--env staging` for staging) and wait for the user to approve in the browser tab that opens. **No `--client-id` is needed** — the CLI has a built-in first-party client, so any Topolo user can sign in; capabilities are decided by their permissions. (`--client-id=<doac_…>` is only for advanced/self-hosted OAuth clients.) For service-agent / headless installs, use an API key with `topolo auth login --api-key=<key>` or set `TOPOLO_API_KEY` for a single invocation.
-5. Confirm identity once: `topolo whoami --json`. Reference the returned `organization.name` when explaining results to the user.
-6. To act in a different org or personal space: `topolo context ls --json` then `topolo context use <organization-name|personal> --json`. Each context has its own credential; the CLI + MCP run in the active one. This does not change the user's web context, and later web switches do not alter the issued credential.
-
-## Command surface
-
-### Identity
-
-```bash
-topolo whoami --json
-#=> { "user": {...}, "organization": {...}, "kind": "access_token" | "api_key" }
-
-topolo auth status --json
-topolo auth login [--api-key=...] [--client-id=... (advanced)] [--scope="..."]
-topolo auth logout
-```
-
-### Contexts (personal + multiple organizations)
-
-```bash
-topolo context ls --json                                 # personal + your orgs; marks the active one
-topolo context use <organization-name|personal> --json   # switch the active context (validated server-side)
-```
-
-There is no `--org` flag — switch context to act in a different organization. `topolo whoami` reflects the active context.
-The switch is local to the CLI/MCP credential store and its token refresh chain;
-it never changes the shared web preference.
-
-### Application and service discovery
-
-```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
-```
-
-Use `topolo apps` to understand which Topolo application you are dealing with.
-Use `topolo apps requirements` before building so the current platform contract
-is in the agent context.
-Use `topolo services` before `topolo api` so you pass an exact SDK app id
-such as `auth`, `crm`, `mail`, `calendar`, `web`, or `quro.redirect`.
-In staging, `topolo services --env staging --json` also shows
-`environmentSafe`; false means the service still resolves to a production SDK
-URL and the CLI will refuse `topolo api` calls until a staging override is set.
-
-### Credential-scoped actions
-
-```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
-```
-
-`topolo actions` is the normal agent entrypoint for application-specific
-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
-
-For any endpoint without a typed subcommand:
-
-```bash
-topolo api <service> <GET|POST|PUT|PATCH|DELETE> <path> [--data '<json>'] [--query key=value] [--confirm] --json
-```
-
-- `<path>` begins with `/api/…` (no host).
-- Discover `<service>` with `topolo services --json`.
-- **Mutating methods require `--confirm`**. If omitted, the CLI refuses.
-
-## Write safety — mandatory
-
-Before any mutating call, you MUST:
-
-1. Print the exact method, path, and body you're about to send.
-2. Get explicit user confirmation.
-3. Only then run with `--confirm`.
-
-Do not batch writes. Do not retry a failed write without re-confirming. The `--confirm` flag exists so a mis-generated write fails loudly instead of silently mutating production data.
-
-## Credential handling
-
-- Never commit credentials. If a user shares an API key inline, use it for a single invocation via env var (`TOPOLO_API_KEY=… topolo whoami --json`) rather than writing it anywhere.
-- Prefer `TOPOLO_STAGING_API_KEY`, `TOPOLO_STAGING_ACCESS_TOKEN`, `TOPOLO_PRODUCTION_API_KEY`, or `TOPOLO_PRODUCTION_ACCESS_TOKEN` when a credential is meant for only one environment.
-- The stored config lives at `$XDG_CONFIG_HOME/topolo/config.json` (mode 0600). Don't read or modify it directly — use `topolo auth` commands.
-- Stored OAuth access tokens refresh automatically when the config contains a refresh token and OAuth client id. On `auth_error`, prompt the user to re-run `topolo auth login`.
-
-## Org isolation — do not try to bypass
-
-- There is no `orgId` argument on any command.
-- Do not add org hints to `topolo api` request bodies; the backend rederives org from the credential.
-- If the user asks you to access "another org's data", the correct response is: "I can only act as the signed-in user. Sign in with a credential for that org first."
-
-## Debugging
-
-- `--no-json` gives human-readable output (useful when showing something to the user directly).
-- `TOPOLO_DEBUG=1` writes request/response traces to stderr while keeping JSON stdout clean.
-- Every request carries `X-Topolo-Request-Id`; if the user reports a failure, ask them for the request-id so support can grep logs.
-- If you set `TOPOLO_AGENT_NAME=<yourAgentLabel>` in the shell before running `topolo`, it's recorded in `X-Topolo-Agent` for audit traceability.
-
-## Reference
-
-- Documentation: `https://docs.topolo.app` (guides, authentication, API reference).
-- Developers console (register apps / OAuth clients): `https://developers.topolo.app`
-- CLI help: `topolo --help` and `topolo <command> --help`.