@thinkingai/ae-cli 6.0.24 → 6.0.27

package/skills/ae-agent/references/list-mcp-credentials.md

@@ -0,0 +1,65 @@
+# agent +list-mcp-credentials (List MCP Credentials)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Credentials / read**
+
+## Use Cases
+- List the current user's per-user credentials for system-scope MCP servers.
+- Endpoint: `GET /api/sandbox/agent/mcp-credentials`.
+- Returns one entry per system MCP server, with the user's credential (or `null` if none exists).
+
+## Mandatory Rules (MUST)
+- No flags required — lists all system MCP servers and the current user's credential status.
+- Only system-scope MCP servers are included; personal/company credentials are managed via the MCP server config and OAuth flow.
+
+## Command
+```bash
+# List all system MCP credentials
+ae-cli agent +list-mcp-credentials
+
+# Dry-run to inspect the request
+ae-cli agent +list-mcp-credentials --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| (none) | — | — |
+
+## Decision Rules
+- If the user wants to check which system MCP servers have credentials configured, use this command.
+- Each item shows `mcpServerId`, `mcpServerName`, and a `credential` object (or `null`).
+- The `credential` object includes `authType`, `enabled`, `expiresAt`, and whether a token is stored — but the token itself is not returned in plaintext here (use `+mcp-token` for that).
+
+## Response Shape
+```json
+{
+  "items": [
+    {
+      "mcpServerId": "clxxx",
+      "mcpServerName": "te-mcp",
+      "credential": {
+        "mcpServerId": "clxxx",
+        "userId": "uyyy",
+        "authType": "oauth",
+        "enabled": true,
+        "expiresAt": "2026-07-06T13:00:00.000Z",
+        "hasToken": true
+      }
+    },
+    {
+      "mcpServerId": "clzzz",
+      "mcpServerName": "other-mcp",
+      "credential": null
+    }
+  ]
+}
+```
+
+## Next Steps on Failure
+- `401` / auth expired: run `ae-cli auth login`.
+
+## Recommended Chaining
+- `+list-mcp-credentials` (check) → `+set-mcp-credential` (set) or `+auto-provision-mcp-credentials` (bulk)
+- `+list-mcp-credentials` → `+mcp-token` (get plaintext token for useMcpToken servers)

package/skills/ae-agent/references/list-mcp-market.md

@@ -0,0 +1,58 @@
+# agent +list-mcp-market (List MCP Market)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Market (browse) / read**
+
+## Use Cases
+- List MCP servers from the market (system / company / personal scopes).
+- Endpoint: `GET /api/sandbox/agent/mcp-servers/market`.
+- Supports filtering by scope, category, search, and sort, with pagination.
+- Use this to discover MCP servers before adding one with `+add-mcp`.
+
+## Mandatory Rules (MUST)
+- `--scope` must be one of the market scopes when provided (see below).
+- `--category` must be one of the market category keys when provided (see below).
+- `--sort` must be one of the sort options when provided (see below).
+
+## Market Scope
+`all | system | company | custom` (`custom` = personal; `all` = system + company + personal)
+
+## Market Category Keys
+`ae_preset | dev_tool | search_tool | data_query | content_gen | enterprise | life | automation | other`
+
+## Sort Options
+`newest | calls | likes` (`calls` sorts MCP by call count)
+
+## Command
+```bash
+ae-cli agent +list-mcp-market
+ae-cli agent +list-mcp-market --scope company --category dev_tool --sort calls --format table
+ae-cli agent +list-mcp-market --search "weather" --sort newest
+ae-cli agent +list-mcp-market --limit 20 --offset 0
+ae-cli agent +list-mcp-market --dry-run --scope system
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--scope` | No | Market scope (see above; default `all`) |
+| `--category` | No | Category key (see above) |
+| `--search` | No | Fuzzy search on name/displayName/description/url |
+| `--sort` | No | Sort option (see above; default `newest`) |
+| `--limit` | No | Page size (1–100, default 50) |
+| `--offset` | No | Page offset (>=0, default 0) |
+
+## Decision Rules
+- When the user wants to browse available MCP servers, call this first.
+- `--scope company` shows same-company MCP servers; `--scope system` shows built-in ones; `--scope custom` shows personal ones.
+- Use `--sort calls` to find the most-used MCP servers.
+- Use `--format table` for a scannable overview.
+
+## Next Steps on Failure
+- `--scope must be one of...`: use one of the market scope values.
+- `--category must be one of...`: use one of the category keys.
+- Empty result: widen filters (remove `--category` / `--scope`).
+
+## Recommended Chaining
+- `+list-mcp-market` (browse) → `+add-mcp` (add to personal) → `+list-mcps` (verify)

package/skills/ae-agent/references/list-mcps.md

@@ -0,0 +1,37 @@
+# agent +list-mcps (List MCP Servers)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / read**
+
+## Use Cases
+- List MCP servers visible to the current user (personal / company / system scopes).
+- Returns an array of MCP server summaries; key fields include `id`, `name`, `url`, `scope`, `enabled`.
+
+## Mandatory Rules (MUST)
+- Do not guess MCP server record IDs. Always call `+list-mcps` first when an ID is needed.
+
+## Command
+```bash
+ae-cli agent +list-mcps
+ae-cli agent +list-mcps --scope personal --format table
+ae-cli agent +list-mcps --scope company
+ae-cli agent +list-mcps --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--scope` | No | Filter by scope: `personal` \| `company` \| `system` |
+
+## Decision Rules
+- When the user needs an MCP server ID for `+del-mcp` / `+toggle-mcp` / `+set-mcp-meta`, call this first.
+- Use `--format table` for a scannable overview of many servers.
+
+## Next Steps on Failure
+- Empty result: confirm account permissions and the active AE host.
+- Auth error: run `ae-cli auth login`.
+
+## Recommended Chaining
+- `+list-mcps` → confirm `id` → `+toggle-mcp` / `+del-mcp` / `+set-mcp-meta`
+- `+list-mcp-market` (browse) → `+add-mcp` (add) → `+list-mcps` (verify)

package/skills/ae-agent/references/list-models.md

@@ -0,0 +1,38 @@
+# agent +list-models (List Models)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Models / read**
+
+## Use Cases
+- List models visible to the current user (personal / company / system scopes).
+- Returns an array of model summaries; key fields include `id`, `modelId`, `displayName`, `scope`, `enabled`.
+- The current selected model (from the runtime env) is annotated when available.
+
+## Mandatory Rules (MUST)
+- Do not guess model record IDs. Always call `+list-models` first when a model ID is needed.
+
+## Command
+```bash
+ae-cli agent +list-models
+ae-cli agent +list-models --scope personal --format table
+ae-cli agent +list-models --scope company
+ae-cli agent +list-models --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--scope` | No | Filter by scope: `personal` \| `company` \| `system` |
+
+## Decision Rules
+- When the user needs a model record ID for `+create-automation --model`, call this first.
+- `--scope personal` shows only the user's own custom models; `company` / `system` show shared models.
+- Use `--format table` for a scannable overview of many models.
+
+## Next Steps on Failure
+- Empty result: confirm account permissions and the active AE host.
+- Auth error: run `ae-cli auth login`.
+
+## Recommended Chaining
+- `+list-models` → confirm model ID → `+create-automation --model <id>` or `+toggle-model` / `+del-model`

package/skills/ae-agent/references/list-skill-assets.md

@@ -0,0 +1,35 @@
+# agent +list-skill-assets (List Skill Assets)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / read**
+
+## Use Cases
+- List all files in a Skill's `assets` directory.
+- Endpoint: `GET /api/sandbox/agent/skills/[id]/assets`.
+- Returns `{ items: [...] }` with file metadata (name, size, etc.).
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+
+## Command
+```bash
+ae-cli agent +list-skill-assets --id <skill-cuid>
+ae-cli agent +list-skill-assets --dry-run --id <skill-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+
+## Decision Rules
+- Use `+list-skills` to confirm the Skill ID before listing assets.
+- Read operation: no confirmation prompt needed.
+- Assets include images, documents, and other supporting files for the Skill.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skills` to verify the Skill ID and scope.
+
+## Recommended Chaining
+- `+list-skills` → confirm `id` → `+list-skill-assets` → `+read-skill-asset` or `+upload-skill-asset`

package/skills/ae-agent/references/list-skill-market.md

@@ -0,0 +1,59 @@
+# agent +list-skill-market (List Skill Market)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Market (browse) / read**
+
+## Use Cases
+- List Skills from the market (only approved items; system / company / personal scopes).
+- Endpoint: `GET /api/sandbox/agent/skills/market`.
+- Supports filtering by scope, category, search, and sort, with pagination.
+- Use this to discover Skills before copying one with `+copy-skill`.
+
+## Mandatory Rules (MUST)
+- `--scope` must be one of the market scopes when provided (see below).
+- `--category` must be one of the market category keys when provided (see below).
+- `--sort` must be one of the sort options when provided (see below).
+- Only approved Skills appear in the market; pending/rejected submissions are not listed.
+
+## Market Scope
+`all | system | company | custom` (`custom` = personal; `all` = system + company + personal)
+
+## Market Category Keys
+`ae_preset | dev_tool | search_tool | data_query | content_gen | enterprise | life | automation | other`
+
+## Sort Options
+`newest | calls | likes` (`calls` sorts Skills by download count)
+
+## Command
+```bash
+ae-cli agent +list-skill-market
+ae-cli agent +list-skill-market --search "code review" --sort newest --format table
+ae-cli agent +list-skill-market --scope company --category dev_tool --sort calls
+ae-cli agent +list-skill-market --limit 20 --offset 0
+ae-cli agent +list-skill-market --dry-run --scope system
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--scope` | No | Market scope (see above; default `all`) |
+| `--category` | No | Category key (see above) |
+| `--search` | No | Fuzzy search on name/displayName/description |
+| `--sort` | No | Sort option (see above; default `newest`) |
+| `--limit` | No | Page size (1–100, default 50) |
+| `--offset` | No | Page offset (>=0, default 0) |
+
+## Decision Rules
+- When the user wants to browse available Skills, call this first.
+- `--sort calls` finds the most-downloaded Skills; `--sort newest` finds the latest.
+- Use `--format table` for a scannable overview.
+- To bring a system/company Skill into your personal workspace, use `+copy-skill` (not `+add-skill`).
+
+## Next Steps on Failure
+- `--scope must be one of...`: use one of the market scope values.
+- `--category must be one of...`: use one of the category keys.
+- Empty result: widen filters (remove `--category` / `--scope`).
+
+## Recommended Chaining
+- `+list-skill-market` (browse) → `+copy-skill` (copy to personal) → `+list-skills` (verify)

package/skills/ae-agent/references/list-skill-references.md

@@ -0,0 +1,36 @@
+# agent +list-skill-references (List Skill References)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / read**
+
+## Use Cases
+- List all `.md` files in a Skill's `references` directory.
+- Endpoint: `GET /api/sandbox/agent/skills/[id]/references`.
+- Returns `{ items: [...] }` with file metadata (name, size, etc.).
+- Only `.md` files are listed (references directory is markdown-only).
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+
+## Command
+```bash
+ae-cli agent +list-skill-references --id <skill-cuid>
+ae-cli agent +list-skill-references --dry-run --id <skill-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+
+## Decision Rules
+- Use `+list-skills` to confirm the Skill ID before listing references.
+- Read operation: no confirmation prompt needed.
+- References are `.md` files that provide additional context for the Skill.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skills` to verify the Skill ID and scope.
+
+## Recommended Chaining
+- `+list-skills` → confirm `id` → `+list-skill-references` → `+read-skill-reference` or `+upload-skill-reference`

package/skills/ae-agent/references/list-skill-scripts.md

@@ -0,0 +1,35 @@
+# agent +list-skill-scripts (List Skill Scripts)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / read**
+
+## Use Cases
+- List all files in a Skill's `scripts` directory.
+- Endpoint: `GET /api/sandbox/agent/skills/[id]/scripts`.
+- Returns `{ items: [...] }` with file metadata (name, size, etc.).
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+
+## Command
+```bash
+ae-cli agent +list-skill-scripts --id <skill-cuid>
+ae-cli agent +list-skill-scripts --dry-run --id <skill-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+
+## Decision Rules
+- Use `+list-skills` to confirm the Skill ID before listing scripts.
+- Read operation: no confirmation prompt needed.
+- Scripts are executable files that support the Skill's functionality.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skills` to verify the Skill ID and scope.
+
+## Recommended Chaining
+- `+list-skills` → confirm `id` → `+list-skill-scripts` → `+read-skill-script` or `+upload-skill-script`

package/skills/ae-agent/references/list-skill-shares.md

@@ -0,0 +1,49 @@
+# agent +list-skill-shares (List Skill Shares)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skill Share (peer-to-peer) / read**
+
+## Use Cases
+- List Skill shares (received by default; use `--direction sent` for outgoing).
+- Endpoint: `GET /api/sandbox/agent/skills/shares`.
+- Sharing is Skill-only — MCP has no share flow.
+- Use this to find a share ID before `+accept-skill-share` / `+reject-skill-share`.
+
+## Mandatory Rules (MUST)
+- `--direction` must be one of the share directions (see below) when provided.
+- `--status` must be one of the share statuses (see below) when provided.
+- Do not guess share IDs. Always call `+list-skill-shares` first when a share ID is needed.
+
+## Share Directions
+`received | sent`
+
+## Share Statuses
+`pending | accepted | rejected`
+
+## Command
+```bash
+ae-cli agent +list-skill-shares
+ae-cli agent +list-skill-shares --direction received --status pending --format table
+ae-cli agent +list-skill-shares --direction sent
+ae-cli agent +list-skill-shares --dry-run --direction received
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--direction` | No | `received` (default) \| `sent` |
+| `--status` | No | Filter by status (see above) |
+
+## Decision Rules
+- By default, lists shares the current user has **received**; use `--direction sent` to list outgoing shares.
+- `--status pending` filters to shares awaiting action.
+- Capture the share `id` for `+accept-skill-share` / `+reject-skill-share`.
+
+## Next Steps on Failure
+- `--direction must be one of...`: use `received` or `sent`.
+- `--status must be one of...`: use one of the share statuses.
+- Empty result: no shares match the filter.
+
+## Recommended Chaining
+- `+list-skill-shares --direction received --status pending` → confirm share `id` → `+accept-skill-share` / `+reject-skill-share`

package/skills/ae-agent/references/list-skill-submissions.md

@@ -0,0 +1,45 @@
+# agent +list-skill-submissions (List Skill Submissions)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skill Approval (company-scope publish) / read**
+
+## Use Cases
+- List Skill submissions (approvals).
+- Endpoint: `GET /api/sandbox/agent/skills/submissions`.
+- Root sees all company submissions; non-root users see only their own.
+- Use this to find a submission ID before `+cancel-skill-submission` / `+approve-skill` / `+reject-skill`.
+
+## Mandatory Rules (MUST)
+- `--status` must be one of the submission statuses (see below) when provided.
+- Do not guess submission IDs. Always call `+list-skill-submissions` first when a submission ID is needed.
+
+## Submission Statuses
+`pending | approved | rejected | cancelled`
+
+## Command
+```bash
+ae-cli agent +list-skill-submissions
+ae-cli agent +list-skill-submissions --status pending --format table
+ae-cli agent +list-skill-submissions --mine
+ae-cli agent +list-skill-submissions --dry-run --status pending
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--status` | No | Filter by status (see above) |
+| `--mine` | No | Only show submissions created by the current user (root only) |
+
+## Decision Rules
+- When the user wants to review pending submissions, use `--status pending`.
+- Root users can see all company submissions; non-root users only see their own.
+- `--mine` (root only) filters to the current user's own submissions.
+- Capture the submission `id` for `+cancel-skill-submission` / `+approve-skill` / `+reject-skill`.
+
+## Next Steps on Failure
+- `--status must be one of...`: use one of the submission statuses.
+- Empty result: no submissions match the filter.
+
+## Recommended Chaining
+- `+list-skill-submissions` → confirm submission `id` → `+cancel-skill-submission` (submitter/root) or `+approve-skill` / `+reject-skill` (root)

package/skills/ae-agent/references/list-skills.md

@@ -0,0 +1,37 @@
+# agent +list-skills (List Skills)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / read**
+
+## Use Cases
+- List Skills visible to the current user (personal / company / system scopes).
+- Returns an array of Skill summaries; key fields include `id`, `name`, `description`, `scope`, `enabled`.
+
+## Mandatory Rules (MUST)
+- Do not guess Skill record IDs. Always call `+list-skills` first when an ID is needed.
+
+## Command
+```bash
+ae-cli agent +list-skills
+ae-cli agent +list-skills --scope personal --format table
+ae-cli agent +list-skills --scope company
+ae-cli agent +list-skills --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--scope` | No | Filter by scope: `personal` \| `company` \| `system` |
+
+## Decision Rules
+- When the user needs a Skill ID for `+del-skill` / `+toggle-skill` / `+copy-skill` / `+submit-skill` / `+share-skill` / `+set-skill-meta`, call this first.
+- Use `--format table` for a scannable overview of many skills.
+
+## Next Steps on Failure
+- Empty result: confirm account permissions and the active AE host.
+- Auth error: run `ae-cli auth login`.
+
+## Recommended Chaining
+- `+list-skills` → confirm `id` → `+toggle-skill` / `+del-skill` / `+copy-skill` / `+submit-skill` / `+share-skill`
+- `+list-skill-market` (browse) → `+add-skill` (create) → `+list-skills` (verify)

package/skills/ae-agent/references/mcp-auth-disconnect.md

@@ -0,0 +1,50 @@
+# agent +mcp-auth-disconnect (Disconnect MCP OAuth)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / write**
+
+## Use Cases
+- Disconnect the OAuth authorization for an MCP server.
+- Endpoint: `POST /api/sandbox/agent/mcp-servers/[id]/auth/disconnect`.
+- Clears the stored token / credentialJson / identityJson and marks the server `enabled=false`.
+- Use this to revoke a stale credential before re-authorizing, or to fully detach from an OAuth provider.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real MCP server record ID (CUID) via `+list-mcps` — do not guess.
+- After disconnect, the MCP server is disabled (`enabled=false`); re-enable with `+toggle-mcp --enabled true` after re-authorizing.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Disconnect OAuth
+ae-cli agent +mcp-auth-disconnect --id <mcp-cuid> --yes
+
+# Dry-run to inspect the request
+ae-cli agent +mcp-auth-disconnect --dry-run --id <mcp-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | MCP server record ID (CUID) |
+
+## Decision Rules
+- If the user wants to revoke an MCP's OAuth credential and disable the server, use this command.
+- After disconnecting, to use the MCP again: run `+mcp-auth-start` to re-authorize, then `+toggle-mcp --enabled true` (if not auto-enabled).
+- Disconnect does NOT delete the MCP server record — it only clears the OAuth credential. To delete the record, use `+del-mcp`.
+
+## Response Shape
+```json
+{
+  "ok": true,
+  "status": "disconnected",
+  "server": { "id": "clxxx", "name": "my-mcp", "displayName": "My MCP", "scope": "personal", "providerKey": "github" }
+}
+```
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-mcps` to verify the server ID.
+
+## Recommended Chaining
+- `+list-mcps` → confirm `id` → `+mcp-auth-disconnect` → `+mcp-auth-start` (re-authorize) → `+mcp-auth-status` (verify) → `+toggle-mcp --enabled true`

package/skills/ae-agent/references/mcp-auth-start.md

@@ -0,0 +1,61 @@
+# agent +mcp-auth-start (Start MCP OAuth)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / write**
+
+## Use Cases
+- Start the OAuth authorization flow for an MCP server (CLI mode).
+- Endpoint: `POST /api/sandbox/agent/mcp-servers/[id]/auth/start`.
+- The sandbox endpoint always uses `cliMode=true`: the server derives the OAuth callback URL itself, so no `origin` is required.
+- Returns an `authorizeUrl` — the user opens it in a browser, authorizes, then polls `+mcp-auth-status` until the status becomes `authenticated`.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real MCP server record ID (CUID) via `+list-mcps` — do not guess.
+- The MCP server must have `authMode=oauth2`; otherwise the server returns `oauth_not_required`.
+- `--redirect-after` (when provided) must be same-origin as the service base URL; otherwise it is rejected.
+- `--cli` defaults to `true` and is always true on the sandbox endpoint — it is for documentation/compat only.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Start OAuth for an MCP server
+ae-cli agent +mcp-auth-start --id <mcp-cuid> --yes
+
+# With a redirect-after URL
+ae-cli agent +mcp-auth-start --id <mcp-cuid> --redirect-after "https://app.example.com/mcp/done" --yes
+
+# Dry-run to inspect the request
+ae-cli agent +mcp-auth-start --dry-run --id <mcp-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | MCP server record ID (CUID) |
+| `--redirect-after` | No | URL to redirect to after OAuth completes (must be same-origin as the service base URL) |
+| `--cli` | No | CLI mode (always `true` on the sandbox endpoint; server derives the callback URL) |
+
+## Decision Rules
+- If the user needs to authorize an OAuth-based MCP server, use this command.
+- The command prints the `authorizeUrl` to stderr (when a TTY is detected) with guidance to open it in a browser and then poll `+mcp-auth-status`.
+- The response also includes `expiresAt` (the auth session expiry, ~10 minutes) and `redirectUri` (the server-derived callback).
+- After the user completes authorization in the browser, poll `+mcp-auth-status --id <id>` until `status` is `authenticated`.
+
+## Response Shape
+```json
+{
+  "authorizeUrl": "https://provider.com/oauth/authorize?...",
+  "expiresAt": "2026-07-06T12:10:00.000Z",
+  "redirectUri": "https://te-claude.example.com/agent/api/mcp-auth/callback",
+  "server": { "id": "clxxx", "name": "my-mcp", "displayName": "My MCP", "scope": "personal", "providerKey": "github" }
+}
+```
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-mcps` to verify the server ID.
+- `400` oauth_not_required: the MCP server does not use OAuth; check `--auth-mode`.
+- `400` origin_required / origin_protocol_unsupported / origin_illegal: check the `--redirect-after` URL.
+
+## Recommended Chaining
+- `+list-mcps` → confirm `id` → `+mcp-auth-start` → (browser authorize) → `+mcp-auth-status` (poll) → `+mcp-tools` (verify)

package/skills/ae-agent/references/mcp-auth-status.md

@@ -0,0 +1,56 @@
+# agent +mcp-auth-status (Query MCP OAuth Status)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / read**
+
+## Use Cases
+- Query the OAuth authorization status of an MCP server.
+- Endpoint: `GET /api/sandbox/agent/mcp-servers/[id]/auth/status`.
+- Used as the polling step after `+mcp-auth-start`: the user authorizes in a browser, then polls this command until `status` becomes `authenticated`.
+- Internally attempts an auto-refresh of soon-to-expire tokens before reporting status.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real MCP server record ID (CUID) via `+list-mcps` — do not guess.
+
+## Command
+```bash
+# Poll OAuth status
+ae-cli agent +mcp-auth-status --id <mcp-cuid>
+
+# Dry-run to inspect the request
+ae-cli agent +mcp-auth-status --dry-run --id <mcp-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | MCP server record ID (CUID) |
+
+## Decision Rules
+- Poll this command after `+mcp-auth-start` until `status` is `authenticated`.
+- The `status` field can be:
+  - `not_required` — the MCP does not use OAuth (authMode ≠ oauth2).
+  - `needs_auth` — no credential exists yet; run `+mcp-auth-start`.
+  - `reauth_required` — the credential has expired; run `+mcp-auth-start` to re-authorize.
+  - `disabled` — the MCP server is disabled; run `+toggle-mcp --enabled true`.
+  - `authenticated` — the credential is valid and ready to use.
+- `authenticated` is `true` only when `status` is `authenticated`.
+- `expiresAt` is the credential expiry (ISO string) or `null` if not applicable.
+
+## Response Shape
+```json
+{
+  "status": "authenticated",
+  "authenticated": true,
+  "expiresAt": "2026-07-06T13:00:00.000Z",
+  "updatedAt": "2026-07-06T12:30:00.000Z",
+  "reason": "oauth_not_required"
+}
+```
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-mcps` to verify the server ID.
+
+## Recommended Chaining
+- `+mcp-auth-start` → (browser authorize) → `+mcp-auth-status` (poll until `authenticated`) → `+mcp-tools` (verify tools are accessible)