@tonyclaw/agent-inspector 3.0.44 → 3.0.46

package/README.md

@@ -28,7 +28,7 @@ Optional MCP-first companion package:
 
 ```bash
 npm install -g @tonyclaw/agent-inspector-mcp
-agent-inspector-mcp doctor
+agent-inspector-mcp doctor --url http://localhost:9527/inspector/api/mcp
 ```
 
 Agent Inspector requires Node.js 22 or newer. Node.js 24 LTS is recommended for production use.
@@ -55,10 +55,11 @@ and defaults to a 64 MiB hard limit and a 120 second body deadline; override the
 integer byte/millisecond values in `AGENT_INSPECTOR_MAX_REQUEST_BYTES` and
 `AGENT_INSPECTOR_REQUEST_TIMEOUT_MS` when a trusted workload requires different bounds.
 
-`@tonyclaw/agent-inspector` runs the local UI, proxy, REST API, storage, and built-in
-`/api/mcp` endpoint. `@tonyclaw/agent-inspector-mcp` is the enhancement package for
-stdio-first MCP clients and setup automation; it bridges to the local Inspector endpoint without
-moving your captured evidence out of the machine.
+`@tonyclaw/agent-inspector` runs the proxy, REST/SSE API, storage, and built-in `/api/mcp`
+endpoint. Its default composed mode also serves the independently built UI; `--backend-only`
+leaves every Coding Agent endpoint running without UI files. `@tonyclaw/agent-inspector-mcp` is the
+enhancement package for stdio-first MCP clients and setup automation; it bridges to the local
+Inspector endpoint without moving your captured evidence out of the machine.
 
 On Windows, the npm install step creates a local `agent-inspector.exe` runtime
 from the user's installed Node.js runtime. The long-running server process
@@ -84,15 +85,20 @@ agent-inspector onboard
 
 The onboarding command installs guided setup skills for local agents:
 
+The generated instructions and automatically merged MCP entries derive the backend Base URL from
+`AGENT_INSPECTOR_PUBLIC_ORIGIN` (or the default local CLI origin) plus
+`AGENT_INSPECTOR_BASE_PATH`. The default is `http://localhost:9527/inspector`. This control/agent
+Base URL is separate from both the optional UI URL and each Provider's upstream Base URL.
+
 - Claude Code: `~/.claude/skills/agent-inspector-onboard/SKILL.md` plus a slash command.
 - Codex: `~/.codex/skills/agent-inspector-onboard/SKILL.md`, focused on connecting
-  `http://localhost:9527/api/mcp` through Codex `mcp_servers.agent-inspector`.
+  `<agent-base-url>/api/mcp` through Codex `mcp_servers.agent-inspector`.
 - OpenCode: run `agent-inspector onboard --opencode-only` to merge
   `mcp.agent-inspector` into `~/.config/opencode/opencode.json` or `opencode.jsonc`, then verify
   with `opencode mcp list`.
 - MiMo Code: run `agent-inspector onboard --mimo-only` to merge `mcp.agent-inspector` into
   `~/.config/mimocode/mimocode.jsonc` or `mimocode.json`, then route MiMo through the proxy with
-  `OPENAI_BASE_URL=http://localhost:9527/proxy`.
+  `OPENAI_BASE_URL=<agent-base-url>/proxy/v1`.
 
 During npm global install, Agent Inspector also makes a best-effort onboarding skill install for
 detected local agents. If `~/.claude` exists, it installs the Claude Code skill and slash command.
@@ -116,6 +122,28 @@ edits a real tool config file instead of adding an Agent Inspector generated ski
 `agent-inspector onboard --status --opencode-only --json` or
 `agent-inspector onboard --status --mimo-only --json` to inspect those MCP entries.
 
+For coding agents that must address more than one Inspector, onboarding can target either a
+registered Windows instance or an explicit wrapper URL:
+
+```powershell
+agent-inspector onboard --instance review --force
+agent-inspector onboard --instance review --mcp-name agent-inspector-review --opencode-only --force
+agent-inspector onboard --base-url https://tools.example.test/inspector --mcp-name team-inspector --force
+agent-inspector onboard --control-base-url https://control.example.test/inspector `
+  --agent-base-url https://agent.example.test/inspector `
+  --ui-url https://ui.example.test/observe --mcp-name team-inspector --force
+agent-inspector onboard --control-base-url https://control.example.test/inspector `
+  --agent-base-url https://agent.example.test/inspector --no-ui --force
+```
+
+`--instance` resolves the saved instance URL and defaults the MCP config key to
+`agent-inspector-<instance>`. `--base-url` accepts a credential-free HTTP(S) backend control/agent
+Base URL as a compatibility shortcut; it does not imply that a browser UI exists. Separated
+deployments can set `--control-base-url`, `--agent-base-url`, and either `--ui-url` or `--no-ui`.
+`--instance` is mutually exclusive with every explicit URL option. `--mcp-name` selects the exact MCP
+config key, allowing the generated config to preserve other Inspector entries. Explicit per-client
+MCP URL options still take precedence over the resolved target.
+
 Before uninstalling the npm package, run `agent-inspector onboard --uninstall` to remove matching
 generated onboarding files. The uninstall command only removes Agent Inspector generated files whose
 metadata version matches the currently installed npm package. npm v7+ does not run package uninstall
@@ -129,6 +157,111 @@ bun install
 bun run dev
 ```
 
+### Deployment modes and runtime Base URLs
+
+Agent Inspector ships one compatible UI/backend release but can run it in three topologies:
+
+| Mode | Start | UI | Coding Agent surfaces |
+| --- | --- | --- | --- |
+| Composed (default) | `agent-inspector` | Served by the protected public ingress | REST, SSE, proxy, health, and MCP use the same public backend Base URL. |
+| Backend-only | `agent-inspector --backend-only --no-open` | Not served; document requests return a bounded headless response | REST, SSE, proxy, health, MCP, capture, and named-instance control remain available. |
+| Standalone UI | Build/host `.output/ui` with SPA fallback | Served by a separate static host | The UI reads operator runtime configuration and calls an explicitly configured backend. |
+
+Do not use "Inspector Base URL" to mean every surface implicitly. The browser-safe runtime
+contract keeps three locations explicit:
+
+- UI Base Path: router/asset mount for the static UI.
+- Control Base URL: REST, uploads/downloads, mutations, and log SSE.
+- Agent Base URL: model proxy, OpenAI-compatible `/proxy/v1`, and MCP guidance.
+
+Composed and backend-only deployments currently publish the same backend Base URL for control and
+agent traffic, but clients must still use the corresponding runtime field. A separately hosted UI
+has its own origin and mount path. `GET <control-base-url>/api/runtime` returns a versioned,
+token-free, `no-store` discovery document with deployment mode and capabilities.
+
+The static UI loads `runtime-config.js` before the application bundle. For a separately hosted UI,
+replace `.output/ui/runtime-config.js` with an operator-owned value such as:
+
+```js
+window.__AGENT_INSPECTOR_RUNTIME_CONFIG__ = {
+  schemaVersion: 1,
+  deploymentMode: "separated",
+  ui: { basePath: "/" },
+  control: { baseUrl: "http://127.0.0.1:19527/inspector" },
+  agent: { baseUrl: "http://127.0.0.1:19527/inspector" },
+  capabilities: { rest: true, sse: true, proxy: true, mcp: true },
+};
+```
+
+Replace the example URLs with the exact backend URLs printed by the CLI or returned by
+`agent-inspector instance connect <name> --json`. Base URLs must be credential-free HTTP(S) URLs
+without query or fragment. Never put Provider keys, control tokens, or proxy tokens in
+`runtime-config.js`, bootstrap HTML, query strings, or browser storage.
+
+The standalone static host must send a CSP whose `connect-src` contains only `'self'` and the exact
+configured control origin; never use `*`. Composed mode generates a same-origin CSP at the protected
+ingress. If the control Base URL changes, update `runtime-config.js` and CSP together.
+
+For a local UI that directly calls another local origin, set a comma-separated exact loopback
+allowlist on the protected backend, for example:
+
+```bash
+AGENT_INSPECTOR_UI_ORIGINS=http://127.0.0.1:4173,http://localhost:4173 agent-inspector --backend-only
+```
+
+`AGENT_INSPECTOR_UI_ORIGINS` accepts only exact `http`/`https` loopback origins: no wildcard,
+credentials, path, query, fragment, or non-loopback hostname. It enables the control API/SSE CORS
+path only; browser CORS access to `/proxy` and `/api/mcp` stays forbidden. A non-loopback remote UI
+must use an authenticated same-origin gateway that protects the public edge and forwards to the
+loopback Inspector backend. Do not use the loopback CORS allowlist as remote authentication.
+
+When a reverse proxy changes the browser-visible scheme/host/port, set the exact external origin
+separately from the Base Path:
+
+```bash
+AGENT_INSPECTOR_PUBLIC_ORIGIN=https://tools.example.test \
+AGENT_INSPECTOR_BASE_PATH=/inspector \
+agent-inspector
+```
+
+`AGENT_INSPECTOR_PUBLIC_ORIGIN` is an origin only; it allows no credentials, path, query, or
+fragment. It drives request-local runtime discovery, copied endpoint guidance, and MCP outward URLs;
+the proxy must also be included in `AGENT_INSPECTOR_TRUSTED_HOSTS` when its hostname is not otherwise
+trusted.
+
+Independent source workflows:
+
+```bash
+bun run dev             # Windows-safe supervisor: backend dev server + UI dev server
+bun run dev:backend     # backend route tree only (development listener)
+bun run dev:ui          # static UI dev server; same-Base-Path proxy by default
+
+bun run build:backend   # .output/server
+bun run build:ui        # .output/ui
+bun run build           # both artifacts plus CLI/workers/MCP and boundary checks
+
+bun run start:backend   # protected production CLI in backend-only mode
+bun run preview:ui      # preview the independently built static UI
+```
+
+For a true separate-origin development UI, inject its runtime surfaces instead of relying on the
+same-Base-Path dev proxy:
+
+```bash
+AGENT_INSPECTOR_UI_BASE_PATH=/observe \
+AGENT_INSPECTOR_UI_CONTROL_BASE_URL=http://127.0.0.1:19527/inspector \
+AGENT_INSPECTOR_UI_AGENT_BASE_URL=http://127.0.0.1:19527/inspector \
+AGENT_INSPECTOR_UI_PORT=4173 bun run dev:ui
+```
+
+The backend must allow that exact local UI origin with `AGENT_INSPECTOR_UI_ORIGINS`. The explicit
+control/agent variables are used only by UI dev/preview; production static hosting continues to use
+the operator-owned `runtime-config.js` so one `.output/ui` artifact remains relocatable.
+
+The direct backend development listener is loopback-oriented and is not a replacement for the
+protected production ingress. An arbitrary static host must provide SPA fallback for supported deep
+links such as `/session/<id>`.
+
 Run a local health check when you need to verify the proxy and installed
 configuration:
 
@@ -144,15 +277,20 @@ only checked when you ask for them explicitly:
 agent-inspector doctor --chrome-extension
 ```
 
-Then point an AI coding tool at the proxy:
+Then point an AI coding tool at the agent Base URL reported by the CLI or connection descriptor:
 
 ```bash
 ANTHROPIC_BASE_URL=http://localhost:9527/inspector/proxy <tool>
 ```
 
-The web UI runs at http://localhost:9527/inspector by default. The public proxy endpoint is
-`http://localhost:9527/inspector/proxy`; internally Agent Inspector may run the app on a private
-helper port, but AI tools should use the public URL printed by the CLI.
+In default composed mode, the web UI runs at `http://localhost:9527/inspector`. The public proxy
+endpoint is `http://localhost:9527/inspector/proxy`; internally Agent Inspector may run the app on a
+private helper port, but AI tools should use the public URL printed by the CLI.
+
+When the dashboard has no captured requests, its copyable Claude, OpenCode, OpenAI, OpenAI `/v1`,
+and MCP examples are derived from the resolved browser runtime contract. They therefore use the
+configured agent surface even when the UI origin, backend origin, or Base Path differs from the
+default.
 
 ### Base path
 
@@ -162,13 +300,19 @@ Agent Inspector defaults to the `/inspector` public base path:
 agent-inspector
 ```
 
-This generates prefixed public URLs for the UI, assets, REST API, MCP, sessions, and model proxy:
+In composed mode this additionally generates these browser document/asset URLs:
 
 - Web UI: `http://localhost:9527/inspector`
 - Assets: `http://localhost:9527/inspector/assets/...`
+- Sessions: `http://localhost:9527/inspector/session/...`
+
+Both composed and backend-only modes keep these backend endpoints at the derived control/agent
+Base URL:
+
 - REST API: `http://localhost:9527/inspector/api/...`
+- Runtime discovery: `http://localhost:9527/inspector/api/runtime`
+- Health: `http://localhost:9527/inspector/api/health`
 - MCP: `http://localhost:9527/inspector/api/mcp`
-- Sessions: `http://localhost:9527/inspector/session/...`
 - Proxy: `http://localhost:9527/inspector/proxy`
 
 AI tools should use the prefixed proxy URL:
@@ -183,26 +327,144 @@ To run at the domain root instead, explicitly set the base path to `/`:
 AGENT_INSPECTOR_BASE_PATH=/ agent-inspector
 ```
 
-Reverse proxies should preserve the `/inspector` prefix when forwarding public requests to Agent
-Inspector.
+### Runtime Base Path aliases
 
-The legacy `http://localhost:9527` port is closed by default. If you need a temporary alias for
-older AI tool or MCP configs, start with `agent-inspector --legacy-port`.
+An already-running Inspector can expose an additional path without starting a second runtime or
+sharing its data directory with another process. For example, after starting the canonical UI at
+the domain root, add `/inspector` on the same origin and port:
 
-## v3.0 Port Migration
+```bash
+AGENT_INSPECTOR_BASE_PATH=/ agent-inspector --background --no-open
+agent-inspector alias add /inspector
+```
 
-Agent Inspector v3.0 changes the default public port from `9527` to `9527`. The packaged CLI now
-opens only `9527` by default. Existing AI coding tool and MCP configs that still point at `9527`
-should be moved to `9527`, or you can temporarily start with `agent-inspector --legacy-port`.
+The canonical and alias URLs share the same Providers, logs, sessions, MCP server, workers, and live
+SSE state. Manage the current runtime's aliases with:
 
-Use these default endpoints for new configs:
+```bash
+agent-inspector alias list
+agent-inspector alias remove /inspector
+```
 
-- Web UI: `http://localhost:9527/inspector`
-- Proxy: `http://localhost:9527/inspector/proxy`
-- OpenAI-compatible `/v1` proxy: `http://localhost:9527/inspector/proxy/v1`
-- MCP: `http://localhost:9527/inspector/api/mcp`
+Use `--port <port>` and `--host <host>` when the running local Inspector does not use
+`localhost:9527`. Runtime aliases are intentionally temporary and are cleared when the Inspector
+supervisor restarts; configure `AGENT_INSPECTOR_BASE_PATH` when a path must remain canonical across
+restarts.
+
+### Windows named instances
+
+Use a named instance when the second URL must have its own Providers, runtime configuration, logs,
+sessions, workers, and data directory. Named instances run as hidden background supervisors on
+Windows; the command waits for readiness before returning. The existing `agent-inspector` and
+`agent-inspector start` commands remain the unmanaged default-instance startup path and do not
+create an instance record.
+
+```powershell
+agent-inspector instance start <name> [--port <port>] [--base-path <path>] [--host <host>] [--mode simple|full] [--data-dir <absolute-path>] [--backend-only|--with-ui] [--open] [--json]
+agent-inspector instance list [--json]
+agent-inspector instance status <name> [--json]
+agent-inspector instance connect <name> [--json]
+agent-inspector instance stop <name> [--json]
+agent-inspector instance restart <name> [--port <port>] [--base-path <path>] [--host <host>] [--mode simple|full] [--data-dir <absolute-path>] [--backend-only|--with-ui] [--open] [--json]
+```
+
+Names use lowercase letters, digits, dots, hyphens, and underscores; `default` is reserved for the
+existing unmanaged runtime. A first start without `--port` allocates an available public/private
+port pair. The pair and the other launch options are saved, so later `start` calls reuse the same
+configuration. Use `restart` with overrides to change a saved value. `--backend-only` persists a
+headless instance; `--with-ui` restores composed UI serving. `--open` is valid only when UI serving
+is enabled. `--json` produces token-free output suitable for PowerShell:
+
+```powershell
+agent-inspector instance start review --base-path /inspector --json
+$review = agent-inspector instance status review --json | ConvertFrom-Json
+$connection = agent-inspector instance connect review --json | ConvertFrom-Json
+$env:OPENAI_BASE_URL = $connection.environment.OPENAI_BASE_URL
+$review
+```
+
+`connect` (also accepted as `connection`) returns a token-free connection descriptor with explicit
+`surfaces.ui`, `surfaces.control`, and `surfaces.agent` locations. Use
+`surfaces.control.baseUrl` for REST/SSE and `surfaces.agent.baseUrl` for proxy/MCP setup;
+`surfaces.ui.baseUrl` is `null` when `surfaces.ui.enabled` is false. The descriptor also includes
+protocol-ready environment variables, MCP settings, and a Codex Responses provider. The top-level
+`uiEnabled`, `baseUrl`, and `endpoints` fields remain for compatibility, but new integrations should
+use `surfaces`. In `--json` mode, success writes exactly one JSON document to stdout;
+errors write exactly one `{ "schemaVersion": 1, "error": ... }` document to stderr with empty
+stdout. Exit code `0` means success, `1` means an operational/lifecycle failure or a reported
+conflict, and `2` means invalid command syntax or arguments. A `status`/`connect` conflict remains a
+token-free state document on stdout while returning `1`. This makes the commands safe for coding
+agents and PowerShell without scraping human text.
+
+On Windows, instance records default below `%LOCALAPPDATA%\agent-inspector\instances`, and isolated
+runtime data defaults to `%LOCALAPPDATA%\agent-inspector\instances\<name>\data`. A per-user fallback
+is used when `LOCALAPPDATA` is unavailable. Set `AGENT_INSPECTOR_INSTANCES_DIR` before every lifecycle
+command, or set it persistently for the user, to move the registry root. `--data-dir` moves one
+instance's runtime data. Agent Inspector rejects a data directory already registered to another
+name rather than allowing Provider or capture state to be shared accidentally.
+
+```powershell
+[Environment]::SetEnvironmentVariable(
+  "AGENT_INSPECTOR_INSTANCES_DIR",
+  "$env:LOCALAPPDATA\agent-inspector-work",
+  "User"
+)
+```
+
+Runtime aliases and named instances solve different problems:
+
+| Feature | Process and storage | Paths | Persistence |
+| --- | --- | --- | --- |
+| `agent-inspector alias add /path` | Same runtime, Providers, and logs | Adds a path on the same port | Cleared on supervisor restart |
+| `agent-inspector instance start <name>` | Separate supervisor, Providers, and logs | Own saved port and Base Path | Saved until explicitly changed |
+
+#### External wrapper: root plus `/inspector`
+
+An external Windows reverse proxy can give two isolated backends one public origin. Start each
+backend on a distinct public ingress port; the lifecycle manager also reserves a different private
+runtime port for each supervisor:
+
+```powershell
+agent-inspector instance start root-site --port 19527 --base-path /
+agent-inspector instance start review-site --port 19537 --base-path /inspector
+```
+
+Configure the wrapper to send `/inspector` and `/inspector/*` to `127.0.0.1:19537` **without
+stripping the `/inspector` prefix**, and send the remaining root traffic to `127.0.0.1:19527`. Point
+the wrapper only at each instance's public ingress port, never its private helper port. Add the
+wrapper hostname to `AGENT_INSPECTOR_TRUSTED_HOSTS` when it differs from the local host.
+
+The wrapper is a routing layer only: the two instance data directories and Provider configurations
+remain independent. It also becomes the immediate TCP client seen by Inspector, so original coding
+tool PID attribution can be replaced by the wrapper process's PID. Connect a coding tool directly
+to the appropriate instance ingress when exact client-process attribution is required.
+
+A wrapper that forwards to loopback must authenticate and authorize its own remote callers:
+Inspector sees the wrapper as a local peer. Direct non-loopback calls to `/api/instances` always
+require `Authorization: Bearer <AGENT_INSPECTOR_CONTROL_TOKEN>`, even when general remote UI control
+is allowed. Keep that control token separate from `AGENT_INSPECTOR_PROXY_TOKEN`, which protects
+remote model-proxy traffic.
 
-If you intentionally need the old compatibility port, start with `agent-inspector --legacy-port`.
+Reverse proxies should preserve the configured prefix when forwarding public requests to Agent
+Inspector (`/inspector` by default).
+
+Treat the exact public backend URL printed by the CLI or connection descriptor as
+`<agent-base-url>` for Coding Agent endpoints. In composed mode it is also the UI URL; in
+backend-only or standalone-UI mode it is not. Client endpoints are derived from the agent surface:
+
+- Proxy: `<agent-base-url>/proxy`
+- OpenAI-compatible `/v1` proxy: `<agent-base-url>/proxy/v1`
+- MCP: `<agent-base-url>/api/mcp`
+- Health: `<control-base-url>/api/health`
+
+For example, keep startup and onboarding aligned when using a custom prefix:
+
+```bash
+AGENT_INSPECTOR_BASE_PATH=/team/inspector agent-inspector
+AGENT_INSPECTOR_BASE_PATH=/team/inspector agent-inspector onboard --force
+AGENT_INSPECTOR_BASE_PATH=/team/inspector agent-inspector onboard --opencode-only --force
+AGENT_INSPECTOR_BASE_PATH=/team/inspector agent-inspector onboard --mimo-only --force
+```
 
 For Codex-style OpenAI Responses clients, configure the proxy as an OpenAI-compatible `/v1` base:
 
@@ -214,11 +476,18 @@ base_url = "http://127.0.0.1:9527/inspector/proxy/v1"
 wire_api = "responses"
 ```
 
+Use `/proxy` as the base for Anthropic clients (which append `/v1/messages`) and generic
+`LLM_BASE_URL` clients. Use `/proxy/v1` as the OpenAI-compatible base for clients that append
+`/chat/completions` or `/responses`; Codex Responses belongs in this second category. The resulting
+full paths are `/proxy/v1/messages`, `/proxy/v1/chat/completions`, and `/proxy/v1/responses`.
+
 ## Documentation Map
 
 - [Installation](docs/Installation.md): install and runtime notes.
 - [Usage](docs/Usage.md): daily capture, browsing, replay, and export workflows.
 - [MCP Server](docs/MCP-Server.md): MCP setup plus tools, resources, prompts, and evidence usage for coding agents.
+- [Instance Control OpenAPI](docs/instance-control.openapi.yaml): versioned named-instance REST
+  contract for coding agents and external controllers.
 - [Troubleshooting](docs/TROUBLESHOOTING.md): port, provider, MCP, Replay, Jenkins, and GitCode fixes.
 - [Jenkins + GitCode WebHook](docs/JENKINS_GITCODE_WEBHOOK_TUNNEL.md): team CI and tunnel setup.
 - [Local Release Helper](docs/LOCAL_RELEASE.md): local maintainer release helper.
@@ -295,20 +564,55 @@ OpenAI Responses each get separate non-streaming and streaming probes. Test evid
 a provider-specific Session so the UI can show which exact path, payload shape, status code, and
 upstream URL failed.
 
+## Named Instance Control For Coding Agents
+
+Every backend control Base URL exposes a versioned, token-free Windows named-instance control
+contract.
+The six endpoints are:
+
+| Method | Endpoint | Purpose |
+| --- | --- | --- |
+| `GET` | `/api/instances` | List registered instances and their live state. |
+| `GET` | `/api/instances/{name}` | Read one instance. |
+| `GET` | `/api/instances/{name}/connection` | Read coding-agent URLs, environment, MCP, and Codex settings. |
+| `POST` | `/api/instances/{name}/start` | Create, start, or idempotently reuse an instance. |
+| `POST` | `/api/instances/{name}/stop` | Gracefully stop a sibling instance. |
+| `POST` | `/api/instances/{name}/restart` | Restart with saved or validated replacement settings. |
+
+`start` and `restart` accept a strict optional JSON object containing `port`, `basePath`, `host`,
+`captureMode`, `uiEnabled`, and `dataDir`; `stop` accepts only `{}`. Responses use `schemaVersion: 1`,
+never include lifecycle or Provider credentials, and send `Cache-Control: no-store`. Errors use the
+stable shape `{ "schemaVersion": 1, "error": { "code", "message", "retryable" } }` with `400`,
+`404`, `409`, `423`, or `503` according to the failure class. See the checked-in
+[OpenAPI 3.1 contract](docs/instance-control.openapi.yaml) for the complete schemas.
+
+Connection responses separate the optional browser surface from backend traffic:
+`surfaces.ui` has `{ enabled, baseUrl }`, while `surfaces.control.baseUrl` and
+`surfaces.agent.baseUrl` remain available for backend-only instances. Legacy top-level `baseUrl` and
+`endpoints` are retained for existing clients.
+
+Browser mutations require same-origin proof plus `x-agent-inspector-csrf: 1`. Direct non-loopback
+control calls require `Authorization: Bearer <AGENT_INSPECTOR_CONTROL_TOKEN>`. A managed instance
+cannot stop or restart itself through the REST/MCP transport it is currently serving; use the
+external CLI or a different controller/anchor instance. A failed restart reports whether the old
+launch was restored (`restart_failed_rolled_back`) or the instance remained degraded
+(`restart_failed_degraded`).
+
 ## MCP Evidence Workflows
 
-Agent Inspector exposes MCP at:
+Agent Inspector exposes MCP from the backend agent Base URL at `<agent-base-url>/api/mcp`, whether
+or not a Web UI is served. With the default public backend Base URL, that is:
 
 ```text
-http://localhost:9527/api/mcp
+http://localhost:9527/inspector/api/mcp
 ```
 
 Coding agents can connect to this MCP surface directly over Streamable HTTP, or through the
 companion stdio bridge:
 
 ```bash
-agent-inspector-mcp stdio
-agent-inspector-mcp config codex
+agent-inspector-mcp stdio --url http://localhost:9527/inspector/api/mcp
+agent-inspector-mcp config codex --url http://localhost:9527/inspector/api/mcp
 ```
 
 The companion package is useful for MCP clients that expect a local command. Direct HTTP remains the
@@ -318,13 +622,10 @@ The MCP HTTP surface is also documented as OpenAPI YAML in
 [`docs/mcp-openapi.yaml`](docs/mcp-openapi.yaml).
 
 Use only one transport for the same Inspector instance. If the MCP client supports Streamable HTTP,
-configure `http://localhost:9527/api/mcp` directly. If it only supports stdio, configure
+configure `<agent-base-url>/api/mcp` directly. If it only supports stdio, configure
 `agent-inspector-mcp stdio`; that command is only a bridge to `/api/mcp`, not a second Inspector
 server.
 
-Legacy MCP configs that still use `http://localhost:9527/api/mcp` require starting the CLI with
-`agent-inspector --legacy-port`; new configs should use `http://localhost:9527/api/mcp`.
-
 Coding agents can use the MCP surface in three ways:
 
 - Tools: perform actions such as listing logs, reading bounded log details, testing providers,
@@ -333,6 +634,33 @@ Coding agents can use the MCP surface in three ways:
   paths without invoking a tool call.
 - Prompts: start common analysis/reporting tasks from reusable templates.
 
+The current catalog contains 51 tools, 25 resources, and 5 prompts. Named-instance control adds six
+tools—`inspector_list_instances`, `inspector_get_instance`,
+`inspector_get_instance_connection`, `inspector_start_instance`, `inspector_stop_instance`, and
+`inspector_restart_instance`—plus these resources:
+
+| Resource URI | Purpose |
+| --- | --- |
+| `inspector://instances` | Token-free list of named instances. |
+| `inspector://instances/{name}` | One named instance and its live state. |
+| `inspector://instances/{name}/connection` | Protocol-correct connection descriptor for a coding agent. |
+
+The three discovery tools and resources remain available in read-only mode. Instance start/stop/
+restart require both `AGENT_INSPECTOR_MCP_WRITES=1` and
+`AGENT_INSPECTOR_MCP_INSTANCE_WRITES=1`; their tool descriptions require explicit user approval.
+They cannot stop or restart the instance serving the active MCP connection.
+
+For an authenticated remote MCP endpoint, keep the token outside config and pass only its variable
+name to the companion:
+
+```bash
+agent-inspector-mcp doctor --url https://tools.example.test/inspector/api/mcp --token-env INSPECTOR_CONTROL_TOKEN --json
+agent-inspector-mcp stdio --url https://tools.example.test/inspector/api/mcp --token-env INSPECTOR_CONTROL_TOKEN
+```
+
+The companion reads the raw value from `INSPECTOR_CONTROL_TOKEN`, sends it as a Bearer credential,
+and never prints it. `doctor` verifies health, MCP initialization, and `tools/list` before returning.
+
 The evaluation-oriented run flow is:
 
 1. Call `inspector_create_run` before a task starts to declare a stable `runId`, optional