@thinkingai/ae-cli 6.0.24 → 6.0.27

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

@@ -0,0 +1,50 @@
+# agent +share-skill (Share Skill Peer-to-Peer)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skill Share (peer-to-peer) / write**
+
+## Use Cases
+- Share a personal Skill to another user in the same company.
+- Endpoint: `POST /api/sandbox/agent/skills/[id]/share`.
+- Sharing is Skill-only — MCP has no share flow.
+- The recipient gets a pending share; accepting creates an independent personal copy for the recipient.
+- Optional `--category` / `--icon-emoji` / `--icon-color` set the market meta proposed for the recipient's copy.
+
+## Mandatory Rules (MUST)
+- `--id` is required and must reference a **personal-scope** Skill (CUID). Obtain it via `+list-skills` — do not guess.
+- `--to-user-id` is required — the recipient user ID (must be in the same company).
+- `--category` must be one of the market category keys (see below) when provided.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Market Category Keys
+`ae_preset | dev_tool | search_tool | data_query | content_gen | enterprise | life | automation | other`
+
+## Command
+```bash
+ae-cli agent +share-skill --id <skill-cuid> --to-user-id <user-id> --yes
+ae-cli agent +share-skill --id <skill-cuid> --to-user-id <user-id> --category dev_tool --icon-emoji robot --yes
+ae-cli agent +share-skill --dry-run --id <skill-cuid> --to-user-id <user-id>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID, personal scope) |
+| `--to-user-id` | Yes | Recipient user ID (same company) |
+| `--category` | No | Market category key (see above) |
+| `--icon-emoji` | No | Market icon emoji (e.g. `robot`) |
+| `--icon-color` | No | Market icon color (e.g. `#1E76F0`) |
+
+## Decision Rules
+- `--id` here is a Skill ID (not a share ID) — `+accept-skill-share` / `+reject-skill-share` take a share ID instead.
+- Only personal-scope Skills can be shared; the recipient must be in the same company.
+- Do not guess `--to-user-id`; obtain it from the user or contact directory.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skills --scope personal` to verify the Skill ID.
+- Cross-company error: the recipient is not in the same company.
+
+## Recommended Chaining
+- `+list-skills` (personal) → `+share-skill` → recipient: `+list-skill-shares --direction received` → `+accept-skill-share` / `+reject-skill-share`

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

@@ -0,0 +1,51 @@
+# agent +submit-skill (Submit Skill for Approval)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skill Approval (company-scope publish) / write**
+
+## Use Cases
+- Submit a personal Skill for company-scope review.
+- Endpoint: `POST /api/sandbox/agent/skills/[id]/submit`.
+- Submitting writes a `SkillSubmit` row; the original personal Skill is untouched.
+- Approval is Skill-only — MCP has no approval flow.
+- Optional `--category` / `--icon-emoji` / `--icon-color` set the market meta proposed for the company copy.
+
+## Mandatory Rules (MUST)
+- `--id` is required and must reference a **personal-scope** Skill (CUID). Obtain it via `+list-skills` — do not guess.
+- `--description` is required (1–80 chars) — the submission reason.
+- `--category` must be one of the market category keys (see below) when provided.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- After submission, the Skill enters `pending` status until a root user approves or rejects it.
+
+## Market Category Keys
+`ae_preset | dev_tool | search_tool | data_query | content_gen | enterprise | life | automation | other`
+
+## Command
+```bash
+ae-cli agent +submit-skill --id <skill-cuid> --description "Code reviewer for the team" --yes
+ae-cli agent +submit-skill --id <skill-cuid> --description "Data query helper" --category data_query --icon-emoji robot --yes
+ae-cli agent +submit-skill --dry-run --id <skill-cuid> --description "Test submit"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID, personal scope) |
+| `--description` | Yes | Submission reason / description (1–80 chars) |
+| `--category` | No | Market category key (see above) |
+| `--icon-emoji` | No | Market icon emoji (e.g. `robot`) |
+| `--icon-color` | No | Market icon color (e.g. `#1E76F0`) |
+
+## Decision Rules
+- If the user wants to publish a personal Skill to the company, use `+submit-skill`.
+- `--id` here is a Skill ID (not a submission ID) — `+cancel-skill-submission` / `+approve-skill` / `+reject-skill` take a submission ID instead.
+- Only personal-scope Skills can be submitted; company/system Skills are not submittable.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `--description length must be between 1 and 80`: shorten the description.
+- `404` / not found: re-run `+list-skills --scope personal` to verify the Skill ID.
+
+## Recommended Chaining
+- `+list-skills` (personal) → `+submit-skill` → `+list-skill-submissions` (track) → root: `+approve-skill` / `+reject-skill`

package/skills/ae-agent/references/test-model.md

@@ -0,0 +1,61 @@
+# agent +test-model (Test Model Connectivity)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Models / read**
+
+## Use Cases
+- Test whether a model endpoint is reachable and the credentials are valid (LLM models only).
+- Probe a brand-new config (with `--api-key`) or reuse the stored key of an existing model (`--id`).
+- Run this before `+update-model --connectivity-verified true` to confirm connection changes.
+
+## Mandatory Rules (MUST)
+- `--model-id` and `--base-url` are required.
+- `--base-url` must be a valid URL.
+- Only LLM-type models can be tested; other provider types return `400`.
+- Read operation — no confirmation prompt (the test does not modify any state).
+
+## Command
+```bash
+# Test a brand-new config with an explicit key
+ae-cli agent +test-model \
+  --model-id gpt-4o \
+  --base-url "https://api.openai.com/v1" \
+  --api-key "sk-xxx" \
+  --provider openai
+
+# Test an existing model's stored key (--id reuses the decrypted key)
+ae-cli agent +test-model \
+  --model-id gpt-4o \
+  --base-url "https://api.openai.com/v1" \
+  --id <model-cuid>
+
+# Dry-run to inspect the request before executing
+ae-cli agent +test-model --dry-run \
+  --model-id gpt-4o \
+  --base-url "https://api.openai.com/v1"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--model-id` | Yes | Model identifier (e.g. `gpt-4o`) |
+| `--base-url` | Yes | API base URL (must be a valid URL) |
+| `--api-key` | No | API key; omit to reuse the stored key of `--id` |
+| `--provider` | No | Provider name |
+| `--id` | No | Existing model config ID; when `--api-key` is omitted, the stored key is decrypted and reused |
+
+## Decision Rules
+- When testing a model that already exists (e.g. before `+update-model`), pass `--id <existing-cuid>` and omit `--api-key` to reuse the stored key.
+- When testing a brand-new config, pass `--api-key` (and optionally `--provider`).
+- A successful test returns `{ "ok": true }`; a failure returns `{ "ok": false, "message": "<reason>" }` with a localized message.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `--base-url must be a valid URL`: check the URL formatting.
+- `仅支持 LLM 类型模型测试` (400): the provider maps to a non-LLM type (e.g. embedding) and cannot be tested via this endpoint.
+- `{ "ok": false, "message": "..." }`: the endpoint was unreachable or rejected the credentials. Fix the URL/key/provider and retry.
+- Auth error: run `ae-cli auth login`.
+
+## Recommended Chaining
+- `+list-models` → confirm `id` → `+test-model --id <cuid>` (verify) → `+update-model --connectivity-verified true`

package/skills/ae-agent/references/toggle-mcp.md

@@ -0,0 +1,39 @@
+# agent +toggle-mcp (Toggle MCP Server)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / write**
+
+## Use Cases
+- Enable or disable an MCP server.
+- Toggle operations on company/system resources only affect the current user's preference, not the global state.
+- For company/system MCP servers there is no copy flow — use `+toggle-mcp` to enable a system/company MCP per-user.
+
+## Mandatory Rules (MUST)
+- `--id` and `--enabled` are required.
+- Obtain the real MCP server record ID (CUID) via `+list-mcps` — do not guess.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+ae-cli agent +toggle-mcp --id <mcp-cuid> --enabled true --yes
+ae-cli agent +toggle-mcp --id <mcp-cuid> --enabled false --yes
+ae-cli agent +toggle-mcp --dry-run --id <mcp-cuid> --enabled false
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | MCP server record ID (CUID) |
+| `--enabled` | Yes | `true` to enable, `false` to disable |
+
+## Decision Rules
+- If the user wants to turn an MCP server on/off, use `--enabled true` / `--enabled false`.
+- Toggling a company/system server only changes the current user's preference.
+- MCP has no copy flow (unlike Skills); to use a system/company MCP, toggle it on per-user.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-mcps` to verify the server ID.
+
+## Recommended Chaining
+- `+list-mcps` → confirm `id` → `+toggle-mcp`

package/skills/ae-agent/references/toggle-model.md

@@ -0,0 +1,37 @@
+# agent +toggle-model (Toggle Model)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Models / write**
+
+## Use Cases
+- Enable or disable a model.
+- Toggle operations on company/system resources only affect the current user's preference, not the global state.
+
+## Mandatory Rules (MUST)
+- `--id` and `--enabled` are required.
+- Obtain the real model record ID (CUID) via `+list-models` — do not guess.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+ae-cli agent +toggle-model --id <model-cuid> --enabled true --yes
+ae-cli agent +toggle-model --id <model-cuid> --enabled false --yes
+ae-cli agent +toggle-model --dry-run --id <model-cuid> --enabled false
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Model record ID (CUID) |
+| `--enabled` | Yes | `true` to enable, `false` to disable |
+
+## Decision Rules
+- If the user wants to turn a model on/off, use `--enabled true` / `--enabled false`.
+- Toggling a company/system model only changes the current user's preference.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-models` to verify the model ID.
+
+## Recommended Chaining
+- `+list-models` → confirm `id` → `+toggle-model`

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

@@ -0,0 +1,37 @@
+# agent +toggle-skill (Toggle Skill)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / write**
+
+## Use Cases
+- Enable or disable a Skill.
+- Toggle operations on company/system resources only affect the current user's preference, not the global state.
+
+## Mandatory Rules (MUST)
+- `--id` and `--enabled` are required.
+- Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+ae-cli agent +toggle-skill --id <skill-cuid> --enabled true --yes
+ae-cli agent +toggle-skill --id <skill-cuid> --enabled false --yes
+ae-cli agent +toggle-skill --dry-run --id <skill-cuid> --enabled false
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+| `--enabled` | Yes | `true` to enable, `false` to disable |
+
+## Decision Rules
+- If the user wants to turn a Skill on/off, use `--enabled true` / `--enabled false`.
+- Toggling a company/system Skill only changes the current user's preference.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skills` to verify the Skill ID.
+
+## Recommended Chaining
+- `+list-skills` → confirm `id` → `+toggle-skill`

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

@@ -0,0 +1,71 @@
+# agent +update-agent (Update Agent)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Agents / write**
+
+## Use Cases
+- Update an existing Agent's name, description, system prompt, model, MCP servers, Skills, or enabled state.
+- Only the fields you pass are changed; omitted fields keep their current values.
+- `--enabled` on a system/company Agent writes the current user's personal preference (does not change the global state).
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Agent record ID (CUID) via `+list-agents` — do not guess.
+- Only `personal` Agents can be fully edited by their owner; `company` Agents require root.
+- `--instructions` supports `@-` to read from stdin.
+- `--mcp-ids` / `--skill-ids` must be JSON array strings when provided; they replace the full list.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- PATCH does NOT support `--auto-rename`; a name conflict returns `409`.
+
+## Command
+```bash
+# Rename
+ae-cli agent +update-agent --id <agent-cuid> --name "new-name" --yes
+
+# Replace instructions from stdin
+echo "You are now a code reviewer..." | \
+  ae-cli agent +update-agent --id <agent-cuid> --instructions @-
+
+# Swap model and MCP list
+ae-cli agent +update-agent \
+  --id <agent-cuid> \
+  --model-id "cm1newuuid" \
+  --mcp-ids '["mcp-cuid-new"]'
+
+# Enable a system/company Agent (writes personal preference)
+ae-cli agent +update-agent --id <agent-cuid> --enabled true
+
+# Disable
+ae-cli agent +update-agent --id <agent-cuid> --enabled false
+
+# Dry-run to inspect the request before executing
+ae-cli agent +update-agent --dry-run --id <agent-cuid> --name "new-name"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Agent record ID (CUID) |
+| `--name` | No | New Agent name (1–100 chars) |
+| `--description` | No | New description (max 2000 chars) |
+| `--instructions` | No | New system prompt (use `@-` to read from stdin) |
+| `--model-id` | No | New model identifier (uuid or legacy modelId); omit to keep |
+| `--mcp-ids` | No | MCP server record IDs as JSON array string (replaces the list; `[]` clears) |
+| `--skill-ids` | No | Skill record IDs as JSON array string (replaces the list; `[]` clears) |
+| `--enabled` | No | `true` to enable, `false` to disable (system/company: personal preference) |
+
+## Decision Rules
+- Confirm the Agent ID with `+list-agents` (or `+get-agent`) before updating.
+- `--enabled` is optional; omit it to leave the enabled state unchanged. Pass `--enabled true` / `--enabled false` explicitly to toggle.
+- `--mcp-ids` / `--skill-ids` replace the entire list on update — pass the full new set, not just additions.
+- Use `--dry-run` first to verify the request shape before executing.
+- To rename safely without `409`, check for name conflicts first or use `+create-agent --auto-rename` (PATCH has no auto-rename).
+
+## Next Steps on Failure
+- `404` / `Agent 不存在`: re-run `+list-agents` to verify the Agent ID.
+- `403` / `无权编辑该 Agent`: the Agent is not yours and you are not root.
+- `409` / `NAME_EXISTS`: pick a different `--name` (PATCH cannot auto-rename).
+- `模型不存在或已删除`: verify the model ID with `+list-models`.
+
+## Recommended Chaining
+- `+list-agents` → confirm `id` → `+update-agent` → `+get-agent` (verify)

package/skills/ae-agent/references/update-automation.md

@@ -0,0 +1,83 @@
+# agent +update-automation (Update Automation)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Automations / write**
+
+## Use Cases
+- Update an existing Agent automation task's name, instruction, schedule, or enabled state.
+- Used to pause (`--enabled false`) or resume (`--enabled true`) an automation, or to change its schedule/message.
+- Obtain the automation `id` via `+list-automations` — never guess.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real ID via `+list-automations` — do not guess.
+- At least one update field must be provided (`--name`, `--message`, `--enabled`, `--cron`, or a `--schedule-kind` with its time/day fields).
+- `--cron` and `--schedule-kind` are mutually exclusive.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- Do not surface raw automation IDs, raw JSON, or concrete detail paths in user-facing replies.
+
+## Schedule Kinds (when updating schedule)
+| `--schedule-kind` | Required fields | Notes |
+|---|---|---|
+| `hourly` | `--minute` (optional, 0–59) | Runs every hour at the given minute |
+| `daily` | `--time HH:mm` | Runs once a day at the given time |
+| `weekly` | `--time HH:mm`, `--weekday 0-6` | `0` = Sunday |
+| `monthly` | `--time HH:mm`, `--day-of-month 1-28` | Day 1–28 only |
+
+## Command
+```bash
+# Pause an automation
+ae-cli agent +update-automation --id <automation-id> --enabled false --yes
+
+# Resume an automation
+ae-cli agent +update-automation --id <automation-id> --enabled true --yes
+
+# Rename and change the instruction
+ae-cli agent +update-automation \
+  --id <automation-id> \
+  --name "Daily AI Brief v2" \
+  --message "Summarize yesterday's AI news and trends" \
+  --yes
+
+# Change the schedule to weekly on Sunday
+ae-cli agent +update-automation \
+  --id <automation-id> \
+  --schedule-kind weekly \
+  --time 10:00 \
+  --weekday 0 \
+  --yes
+
+# Switch to a cron expression
+ae-cli agent +update-automation --id <automation-id> --cron "0 9 * * 1-5" --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +update-automation --dry-run --id <automation-id> --enabled false
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Automation task ID from `+list-automations` |
+| `--name` | No | New automation task name |
+| `--message` | No | New instruction sent to the Agent |
+| `--enabled` | No | `true` to enable, `false` to pause |
+| `--cron` | No | Cron expression (mutually exclusive with `--schedule-kind`) |
+| `--schedule-kind` | No | `hourly` \| `daily` \| `weekly` \| `monthly` |
+| `--time` | No | Time in `HH:mm` for daily/weekly/monthly |
+| `--minute` | No | Minute 0–59 for hourly schedules |
+| `--weekday` | No | Weekday 0–6 for weekly schedules; `0` is Sunday |
+| `--day-of-month` | No | Day 1–28 for monthly schedules |
+
+## Decision Rules
+- If the user wants to pause/resume, use `--enabled false` / `--enabled true` (no other fields needed).
+- If the user wants to change the schedule, provide `--schedule-kind` with its required time/day fields, or `--cron`.
+- At least one update field is required; a bare `--id` is rejected.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `至少提供一个更新字段`: add at least one of `--name` / `--message` / `--enabled` / `--cron` / `--schedule-kind`.
+- `必须提供 --cron 或 --schedule-kind`: if schedule detail flags (`--time` / `--minute` / `--weekday` / `--day-of-month`) are present, a `--schedule-kind` (or `--cron`) must accompany them.
+- `--time 格式必须是 HH:mm`: use 24-hour `HH:mm` (e.g. `09:00`).
+
+## Recommended Chaining
+- `+list-automations` → `+update-automation`

package/skills/ae-agent/references/update-mcp.md

@@ -0,0 +1,79 @@
+# agent +update-mcp (Update MCP Server Config)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / write**
+
+## Use Cases
+- Update an existing MCP server's configuration (name, URL, transport, headers, auth mode, etc.).
+- Endpoint: `PATCH /api/sandbox/agent/mcp-servers/[id]`.
+- Personal scope: requires ownership. Company scope: requires root. System scope: read-only.
+- Includes connectivity validation and OAuth reauth cascade when relevant.
+- Use `--auto-rename` to auto-rename on name conflict instead of returning a 409.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real MCP server record ID (CUID) via `+list-mcps` — do not guess.
+- At least one update field must be provided (aside from `--id`).
+- `--name` (when provided) must start with a letter and contain only letters, digits, `_`, or `-` (2–64 chars).
+- `--url` (when provided) must be a valid `http://` or `https://` URL (file://, ftp://, and other protocols are blocked).
+- `--transport` (when provided) must be `sse`, `http`, or `streamable-http` (stdio is disabled by policy on the sandbox endpoint).
+- `--auth-mode` (when provided) must be `none`, `oauth2`, `header`, or `manual`.
+- `--enabled` accepts `true` or `false`; **omit it to leave the enabled state unchanged**. To simply toggle, prefer `+toggle-mcp`.
+- `--headers` / `--secret-headers` must be valid JSON objects when provided. `--secret-headers` values are encrypted server-side.
+- The server runs a connectivity check on update; an unreachable URL fails with `connectivity_failed`.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Rename + update URL
+ae-cli agent +update-mcp --id <mcp-cuid> --name my-mcp-renamed --url "https://mcp.example.com/mcp" --yes
+
+# Update transport + headers
+ae-cli agent +update-mcp --id <mcp-cuid> --transport streamable-http --headers '{"Authorization":"Bearer token"}'
+
+# Enable with auto-rename on conflict
+ae-cli agent +update-mcp --id <mcp-cuid> --enabled true --auto-rename --yes
+
+# Disable (explicit)
+ae-cli agent +update-mcp --id <mcp-cuid> --enabled false --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +update-mcp --dry-run --id <mcp-cuid> --name new-name
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | MCP server record ID (CUID) |
+| `--name` | No* | Server name (2–64 chars, letter start, `[a-zA-Z0-9_-]`) |
+| `--url` | No* | MCP server URL (`http://` or `https://` only) |
+| `--display-name` | No* | Display name (max 100) |
+| `--description` | No* | Description (max 255) |
+| `--transport` | No* | `sse` \| `http` \| `streamable-http` |
+| `--headers` | No* | HTTP headers as JSON object |
+| `--secret-headers` | No* | Secret headers as JSON object (encrypted server-side) |
+| `--auth-mode` | No* | `none` \| `oauth2` \| `header` \| `manual` |
+| `--enabled` | No* | `true` \| `false` (omit to leave unchanged) |
+| `--auto-rename` | No* | Auto-rename on name conflict (default `false`) |
+
+\* At least one of these must be provided.
+
+## Decision Rules
+- If the user wants to change any MCP config field, use this command.
+- To only enable/disable an MCP (no other changes), prefer `+toggle-mcp` — it is simpler and has no connectivity check.
+- `--enabled` is a string (`true`/`false`), not a boolean flag, so that omitting it leaves the state unchanged.
+- If the server returns `NAME_EXISTS` (409), re-run with `--auto-rename` or pick a different `--name`.
+- After updating URL/transport/headers, the server re-validates connectivity; if it fails, the old config is preserved.
+- Updating OAuth-related fields (URL, auth mode, secret headers) may trigger a reauth cascade — affected credentials are expired and `reauthRequired` / `reauthCredentialCount` are returned in the response.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-mcps` to verify the server ID and scope.
+- `403` company_admin_only: the current user is not root (company-scope update).
+- `403` system_mcp_readonly: system-scope MCPs cannot be updated.
+- `409` NAME_EXISTS: re-run with `--auto-rename` or a different `--name`.
+- `400` connectivity_failed: verify the URL is reachable and transport is correct.
+- `400` needs_auth: refresh credentials first (`+mcp-auth-start`), then re-enable.
+
+## Recommended Chaining
+- `+list-mcps` → confirm `id` → `+update-mcp`
+- `+update-mcp` → (if reauth required) → `+mcp-auth-start` → `+mcp-auth-status`

package/skills/ae-agent/references/update-model.md

@@ -0,0 +1,77 @@
+# agent +update-model (Update Custom Model)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Models / write**
+
+## Use Cases
+- Update an existing custom model (the `--id` determines which record to update).
+- All connection/display fields can be changed; `--api-key` may be omitted to preserve the stored key.
+- Encouraged to verify connectivity with `+test-model` first, then pass `--connectivity-verified true`.
+- `--scope` controls target scope: `personal` (default) or `company`. Company scope requires root/agent_admin.
+
+## Mandatory Rules (MUST)
+- `--id`, `--model-id`, `--name`, and `--base-url` are required.
+- `--base-url` must be a valid URL.
+- `--api-key` is optional; omit or leave empty to preserve the existing key (do NOT pass an empty string to clear — the stored key is kept).
+- `--scope` controls target scope: `personal` (default) or `company`. Company scope requires root/agent_admin; system models are read-only.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Update display name and provider
+ae-cli agent +update-model \
+  --id <model-cuid> \
+  --model-id gpt-4o \
+  --name "GPT-4o (prod)" \
+  --base-url "https://api.openai.com/v1" \
+  --provider openai \
+  --yes
+
+# Rotate the API key
+ae-cli agent +update-model \
+  --id <model-cuid> \
+  --model-id gpt-4o \
+  --name "GPT-4o" \
+  --base-url "https://api.openai.com/v1" \
+  --api-key "sk-newkey" \
+  --connectivity-verified true
+
+# Dry-run to inspect the request before executing
+ae-cli agent +update-model --dry-run \
+  --id <model-cuid> \
+  --model-id gpt-4o \
+  --name "GPT-4o" \
+  --base-url "https://api.openai.com/v1"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Model record ID (CUID) to update |
+| `--model-id` | Yes | Model identifier (e.g. `gpt-4o`) |
+| `--name` | Yes | Display name |
+| `--base-url` | Yes | API base URL (must be a valid URL) |
+| `--api-key` | No | API key; omit or empty to preserve the existing key |
+| `--provider` | No | Provider name |
+| `--description` | No | Description |
+| `--context-length` | No | Context window length (positive integer) |
+| `--connectivity-verified` | No | Whether connectivity was verified (default `false`; pass `true` after `+test-model`) |
+| `--auto-rename` | No | Auto-rename on display name conflict (append `-N` suffix) |
+| `--scope` | No | Target scope: `personal` (default) or `company` (requires root/agent_admin) |
+
+## Decision Rules
+- Confirm the model ID with `+list-models` before updating.
+- To rotate the API key, pass `--api-key <new>`; to keep the stored key, simply omit `--api-key`.
+- `--connectivity-verified` defaults to `false`. After a successful `+test-model`, pass `--connectivity-verified true` to confirm the new connection config.
+- On display name conflict, the server returns `409`; pass `--auto-rename` to auto-resolve.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `模型不存在` (404): re-run `+list-models` to verify the model ID and scope.
+- `模型名称已存在` (409): re-run with `--auto-rename`, or pick a different `--name`.
+- `--base-url must be a valid URL`: check the URL formatting.
+- `仅支持 LLM 类型模型测试` (from `+test-model`): the provider maps to a non-LLM type and cannot be tested.
+
+## Recommended Chaining
+- `+list-models` → confirm `id` → `+test-model` (verify connectivity) → `+update-model --connectivity-verified true` → `+list-models` (verify)

package/skills/ae-agent/references/upload-skill-asset.md

@@ -0,0 +1,49 @@
+# agent +upload-skill-asset (Upload Skill Asset)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / write**
+
+## Use Cases
+- Upload a single file to a Skill's `assets` directory (multipart upload).
+- Endpoint: `POST /api/sandbox/agent/skills/[id]/assets` (multipart/form-data).
+- Max file size: 1MB per file.
+- Dangerous file types are rejected server-side.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+- `--file` is required and must point to an existing local file.
+- Max 1MB per file; server enforces `isDangerousFile` checks.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Upload a single asset
+ae-cli agent +upload-skill-asset --id <skill-cuid> --file ./icon.png --yes
+
+# Upload to a sub-directory
+ae-cli agent +upload-skill-asset --id <skill-cuid> --file ./data.csv --sub-path "sub/" --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +upload-skill-asset --dry-run --id <skill-cuid> --file ./icon.png
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+| `--file` | Yes | Local file path to upload (max 1MB) |
+| `--sub-path` | No | Sub-directory under assets (e.g. `"sub/"`) |
+
+## Decision Rules
+- Verify the file exists locally before uploading.
+- Use `--sub-path` to organize assets into sub-directories.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `File not found`: verify the local file path.
+- `文件过大（上限 1MB）`: the file exceeds the 1MB limit — compress or split it.
+- `禁止上传危险文件类型`: the file type is blocked by server-side security checks.
+
+## Recommended Chaining
+- `+list-skills` → `+list-skill-assets` → `+upload-skill-asset` → `+list-skill-assets` (verify)