@topolo/cli 0.1.34 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/cli",
-  "version": "0.1.34",
+  "version": "0.2.1",
   "description": "Command-line interface for Topolo developers, operators, and agents, with internal first-party scaffolding available under the topolo platform namespace.",
   "type": "module",
   "bin": {
@@ -11,10 +11,14 @@
     "skills"
   ],
   "scripts": {
+    "build:sdk": "pnpm --dir ../topolo-sdk build",
+    "prebuild": "pnpm run build:sdk",
     "build": "tsup",
     "dev": "tsup --watch",
+    "pretypecheck": "pnpm run build:sdk",
     "typecheck": "tsc --noEmit",
     "start": "node dist/index.js",
+    "pretest": "pnpm run build:sdk",
     "test": "vitest run",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage"
@@ -23,7 +27,7 @@
     "commander": "^12.1.0"
   },
   "devDependencies": {
-    "@topolo/sdk": "workspace:*",
+    "@topolo/sdk": "file:../topolo-sdk",
     "@types/node": "^20.12.0",
     "@vitest/coverage-v8": "^2.1.0",
     "tsup": "^8.0.0",

package/skills/codex/AGENTS.md

@@ -6,11 +6,11 @@ This file teaches an agent how to interact with the Topolo platform via the `top
 
 Topolo is a multi-app SaaS platform. The CLI and MCP server both use `@topolo/sdk`; bundled app IDs come from the generated registry, and newly registered API/technical services can be resolved from the live Auth catalog.
 
-- Use `topolo apps --json` or the MCP `topolo_list_applications` tool to discover platform applications, including browser-only Worker apps.
+- 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_list_services` tool to discover callable app ids and effective URLs.
-- Use `topolo actions --json` or MCP dynamic action tools to discover callable operations granted to the current credential.
+- 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`.
 - 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.
@@ -39,11 +39,12 @@ Exit codes:
 
 ## Setup flow
 
-1. Check install: `command -v topolo || npm install -g @topolo/cli` (requires Node ≥ 20).
+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 --client-id=<doac_…>` plus the right `--env` flag and wait for the user to approve in the browser tab that opens. To get a client_id, direct the user to `https://developers.topolo.app/developers/oauth-clients` for production or `https://developers.stg.topolo.us/developers/oauth-clients` for staging and tell them to pick the **CLI / desktop / mobile** tile (that's what enables the device flow). For service-agent installs, use an API key with `topolo auth login --api-key=<key>` or set `TOPOLO_API_KEY` for a single invocation.
+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
 
@@ -54,10 +55,21 @@ topolo whoami --json
 #=> { "user": {...}, "organization": {...}, "kind": "access_token" | "api_key" }
 
 topolo auth status --json
-topolo auth login [--client-id=...] [--api-key=...] [--scope="..."]
+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
@@ -80,17 +92,18 @@ URL and the CLI will refuse `topolo api` calls until a staging override is set.
 ### Credential-scoped actions
 
 ```bash
-topolo actions --json
 topolo actions --service mail --json
-topolo actions get topolo_mail_messages_send --json
-topolo actions call topolo_mail_messages_send \
+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` 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.
+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.
 
 ### Generic passthrough
 
@@ -136,6 +149,7 @@ Do not batch writes. Do not retry a failed write without re-confirming. The `--c
 
 ## Reference
 
-- Dev console (registration, scopes, clients): `https://developers.topolo.app`
+- 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.

package/skills/topolo/SKILL.md

@@ -5,7 +5,7 @@ description: Read and write Topolo platform data (identity, application/service
 
 # Topolo platform
 
-The `topolo` CLI is the agent-friendly entry point to the Topolo platform. Every command is scoped to the organization embedded in the current credential — you cannot target another org, and you cannot bypass the credential.
+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).
 
 ## When this skill fires
 
@@ -16,7 +16,7 @@ Use `topolo` whenever the user:
 - Wants to call an endpoint under a Topolo service from the shell.
 - Mentions a Topolo OAuth client (`doac_…`) or API key.
 
-If the user asks a platform question and `topolo` is not installed, install it: `npm install -g @topolo/cli`. Requires Node ≥ 20.
+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).
 
 ## Credentials — always check first
 
@@ -32,7 +32,7 @@ or provisioning a staging-only first-party app:
 
 ```bash
 topolo auth status --env staging --json
-topolo auth login --env staging --client-id=<doac_…>
+topolo auth login --env staging
 ```
 
 Possible `source` values:
@@ -46,14 +46,17 @@ Possible `source` values:
 | `config-file` | Token stored in the selected environment profile at `$XDG_CONFIG_HOME/topolo/config.json` |
 | `none` | Not signed in — call `topolo auth login` |
 
-If `source: none`, run `topolo auth login --client-id=<doac_…>` plus the right
-`--env` flag and tell the user to approve the device in the browser tab that
-opens. The CLI blocks until they approve, then stores the token in that
-environment profile.
+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.)
 
-If you don't know the client_id, send them to `https://developers.topolo.app/developers/oauth-clients` for production or `https://developers.stg.topolo.us/developers/oauth-clients` for staging. Prefer a **public** (CLI/desktop/mobile) client — that's the tile that enables the device flow.
-
-For service-agent 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.
+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.
 
 ## Output modes
 
@@ -71,6 +74,22 @@ Returns `{ user: { email, name, role, permissions }, organization: { name, slug
 
 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.
 
+### Contexts (personal + multiple organizations)
+
+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.
+
+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.
+
+```bash
+topolo context ls --json                              # personal + your orgs, and which is active
+topolo context use <organization-name|personal> --json  # switch the active context
+```
+
+`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.
+
 ### Application and service discovery
 
 ```bash
@@ -79,7 +98,7 @@ topolo apps get <application_id> --json
 topolo apps requirements <application_id> --json
 topolo apps audit <application_id> --json
 topolo services --json
-topolo actions --json
+topolo actions --service <application_id_or_slug> --json
 ```
 
 `topolo apps` returns every cataloged Topolo application, including browser-only
@@ -95,18 +114,36 @@ before `topolo api` when you are not using a cataloged action.
 ### Credential-scoped actions
 
 ```bash
-topolo actions --json
 topolo actions --service mail --json
-topolo actions get topolo_mail_messages_send --json
-topolo actions call topolo_mail_messages_send \
+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` returns the callable action catalog filtered by the current
-credential's organization and permissions. Prefer it over `topolo api` when the
-target app has published a machine action contract through Topolo Developers.
-Writes require `--confirm`.
+`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`.
+
+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.
+
+```bash
+topolo actions call app_topolo_inventory.dashboard.get \
+  --resource-type workspace \
+  --resource-id <workspace_id> \
+  --data '{}' --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.
 
 ### Generic API passthrough
 
@@ -128,7 +165,7 @@ Examples:
 topolo api auth GET /api/me --json
 
 # Send mail through a published action (requires confirm)
-topolo actions call topolo_mail_messages_send \
+topolo actions call app_topolo_mail.messages.send \
   --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
   --confirm --json
 ```
@@ -152,7 +189,7 @@ Stored OAuth access tokens refresh automatically when the config contains both a
 
 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. Don't try to fake one via the passthrough; the backend ignores org hints in the body and rederives org from the credential.
+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.
 
 ## Common flows
@@ -165,7 +202,7 @@ topolo actions --service mail --json
 
 **"Send a message through Mail"**
 ```bash
-topolo actions call topolo_mail_messages_send \
+topolo actions call app_topolo_mail.messages.send \
   --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
   --confirm --json
 ```
@@ -181,25 +218,31 @@ topolo apps --json
 topolo apps requirements <application_id> --json
 topolo apps audit <application_id> --json
 topolo services --json
-topolo actions --json
+topolo actions --service mail --json
 ```
 
 **"Sign me in fresh"**
 ```bash
 topolo auth logout
-topolo auth login --client-id=<doac_…>
-# Then wait for the user to approve in the browser.
+topolo auth login          # no --client-id needed; approve in the browser
 ```
 
 **"Sign me in to staging"**
 ```bash
 topolo auth logout --env staging
-topolo auth login --env staging --client-id=<doac_…>
+topolo auth login --env staging
 topolo whoami --env staging --json
 ```
 
+**"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
+```
+
 ## Where to learn more
 
-- Topolo Developers console: https://developers.topolo.app
-- CLI source (for when the user asks about an undocumented flag): `TopoloCli/src/commands/` in the PlatformApplications repo.
+- **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.