@topolo/cli 0.7.4 → 0.8.1

package/README.md

@@ -1,8 +1,9 @@
 # TopoloCli
 
-Command-line interface for the Topolo platform. Designed for both humans and
-third-party agents (Claude Code, Codex, Cursor, etc.) that prefer to interact
-via `stdin`/`stdout`.
+Public customer command-line interface for Topolo organizations, developers,
+and agents. First-party engineering, seed, scaffold, audit, provisioning,
+deployment, and release commands belong to the restricted `topolo-platform`
+toolchain and are deliberately absent.
 
 ## Current scope
 
@@ -11,8 +12,9 @@ via `stdin`/`stdout`.
 - Stored access-token refresh; the `@topolo/mcp` server reads the same credential, so agents need no API-key plumbing.
 - First-class `production`, `staging`, `development`, and `local` environments with separate stored credentials and service URL overrides.
 - **Per-context credentials** — hold and switch between your personal space and multiple organizations with `topolo context`.
-- **One-command agent setup** — `topolo skills install` wires the skill + MCP into Claude Code / Codex.
-- Commands: `auth`, `whoami`, `context`, `skills`, `apps`, `services`, `workspaces`, credential-scoped `actions`, generic `api` passthrough, and internal `platform` scaffolding.
+- **One-command agent setup** — `topolo setup` wires the bundled compatible skill + MCP into Claude Code / Codex.
+- **End-to-end diagnostics** — `topolo doctor` proves authentication and the MCP protocol path.
+- Commands: `auth`, `whoami`, `context`, `setup`, `doctor`, `skills`, `apps`, `services`, `resources`, `workspaces`, credential-scoped `actions`, `oauth`, `integrations`, and generic `api` passthrough.
 
 ## Install
 
@@ -35,7 +37,7 @@ Production is the default. Select staging with `--env staging` anywhere in the c
 ```bash
 topolo auth status --env staging --json
 topolo auth login --env staging
-topolo platform apps scaffold home --env staging --write --json
+topolo whoami --env staging --json
 ```
 
 The staging profile uses `auth.stg.topolo.us`, `developers.stg.topolo.us`, and `seed.stg.topolo.us` by default. Other SDK service calls in staging must have an explicit staging URL override; the CLI refuses to call a production SDK URL while `--env staging` is selected.
@@ -71,10 +73,21 @@ topolo context use <organization|personal> # switch (validated + a fresh token m
 ### Wire into Claude Code / Codex
 
 ```bash
-topolo skills install    # copies the skill + registers the `topolo` MCP server, credential-free
+topolo setup             # copies the skill + registers the exact bundled MCP
+topolo doctor            # verifies auth, handshake, tool discovery, and identity
 ```
 
 The MCP reads the same credential `topolo auth login` writes — no API key to paste.
+For concurrent agents pinned to different organizations, use an exact context
+key returned by `topolo context ls --json`:
+
+```bash
+topolo setup --name topolo-acme --context org:org_acme --env production
+```
+
+This creates separately named Claude Code and Codex registrations using the
+same exact nested MCP executable. `topolo-platform` is reserved for the
+restricted operator toolchain.
 
 ## Cross-org isolation
 
@@ -208,48 +221,11 @@ generated application list.
 ```bash
 topolo apps --json
 topolo apps get mail --json
-topolo apps requirements mail --json
-topolo apps audit mail --json
-topolo apps audit mail --local --repo-root /Users/ashes/Projects/topolo --fail-on needs_review --json
-topolo apps scaffold insights --json
-topolo apps scaffold insights --write --repo-root /Users/ashes/Projects/topolo --json
-topolo apps scaffold score --target developer --write --repo-root ./starters --json
-topolo apps scaffold insights --workflow-only --no-json
 ```
 
-Agents should call `topolo apps requirements <app> --json` before creating or
-expanding a Topolo app. The output is the versioned platform contract for app
-metadata, canonical docs, shared auth, shared shell, service registration,
-deployment metadata, agent surfaces, observability, and verification.
-`topolo apps audit --json` returns compact per-app scores and a migration queue
-count. Add `--detail` for every finding and migration item, or
-`--local --repo-root <topolo-checkout>` to
-include filesystem evidence from the app repo, CloudControl metadata, and
-TopoloDocs. Add `--fail-on needs_review` for the default new-work gate, or
-`--fail-on partial` for strict release readiness.
-
-`topolo apps scaffold <app>` generates the required new-application scaffold,
-including package/auth/shell/docs/CloudControl files, a deploy-ready
-Wrangler Worker/static-assets baseline, an Auth service manifest, and a
-`topolo-conformance.yml` GitHub Actions workflow for first-party platform
-apps. Add `--write --repo-root <topolo-checkout>` to create the files on disk;
-existing files are refused unless `--force` is passed. The first-party scaffold
-writes apps under `apps/<AppDir>`, writes canonical docs under
-`system-apps/TopoloDocs/apps/web/src/content`, writes Auth service manifests
-under `topolo-platform/core/TopoloAuth/catalog/service-manifests`, emits a
-project-local `AGENTS.md` for future agent work in the scaffold, and pins the
-generated starter to the current published shared package baseline. The
-generated workflow checks out the app under `apps/<AppDir>`, checks out
-`Topolo-io/TopoloDocs`, `Topolo-io/topolo-sdk`, and `Topolo-io/TopoloCli`, builds
-the current CLI from source, then runs the local conformance audit with
-`--fail-on needs_review`.
-
-For third-party developers, use `--target developer` or `--developer`. Developer
-scaffolds are standalone starter projects with `topolo.app.json`, `.env.example`,
-an `@topolo/login` authorization-code + PKCE browser starter, and no internal TopoloDocs,
-CloudControl, or private first-party package dependencies. Developer scaffolds
-are browser-only by default; add `--with-api` to include a protected Worker
-baseline that validates bearer tokens through Topolo Auth over HTTP.
+Only live, credential-scoped applications are returned. The public CLI contains
+no first-party repository metadata or compiled fallback catalog. Internal app
+creation and conformance workflows use `topolo-platform apps`.
 
 ### `topolo oauth clients`
 
@@ -325,17 +301,12 @@ Installable guides for agents that drive the CLI on behalf of a user.
 - **Claude Code** — copy `skills/topolo/` into `~/.claude/skills/` (per-user)
   or `<your-project>/.claude/skills/` (per-project). Claude picks it up
   automatically when the description matches the user's request.
-- **Codex / Cursor / generic** — drop `skills/codex/AGENTS.md` at the root of
-  your repo (or alongside the code your agent works in). Codex reads
-  `AGENTS.md` files by convention.
-
-Both docs cover the same CLI surface: credential handling, the JSON invocation
-contract, the write-safety `--confirm` guardrail, and the cross-org isolation
-rules. Keep them in sync when adding new commands.
+- **Codex** — `topolo setup` installs `skills/topolo/SKILL.md` into the user
+  skill directory and writes the deterministic MCP registration.
 
-For agents that support MCP, also register `@topolo/mcp`; the skill/AGENTS
-guidance still matters because it tells the agent when to prefer MCP tools,
-when to fall back to shell commands, and how to handle writes.
+The one bundled skill covers credential handling, runtime discovery, write
+confirmation, and cross-org isolation. The CLI owns and registers its compatible
+MCP; do not install or synchronize `@topolo/mcp` separately.
 
 ## Debug output