@thinkingai/ae-cli 6.0.24 → 6.0.27

package/dist/{te-engage-YPQIVF5H.js → te-engage-MIIUKY6M.js}

@@ -3,12 +3,12 @@ import {
   parseMcpResult,
   registerMcpMappings,
   resolveMcpUrl
-} from "./chunk-NGJDCOYA.js";
-import "./chunk-WXBCP6SD.js";
+} from "./chunk-GWZ5MYWE.js";
+import "./chunk-KGJQCYVC.js";
 import "./chunk-NOO24N7W.js";
-import "./chunk-OCQPQYHZ.js";
-import "./chunk-PFJFZVCK.js";
-import "./chunk-65DKFJZB.js";
+import "./chunk-2NDGFQHW.js";
+import "./chunk-AJTH7LT3.js";
+import "./chunk-YCLVYFK7.js";
 
 // src/commands/te-engage/utils.ts
 function buildMcpDryRun(ctx, serviceName46, toolName46, args) {
@@ -532,8 +532,8 @@ function buildArgs15(ctx) {
 var flowNodeConfigSchema = {
   service: "engage",
   command: "+flow_node_config_schema",
-  description: "Query the config schema for one flow node type.",
-  flags: [{ name: "node_type", type: "string", required: true, desc: "Node type" }],
+  description: "Query one type-specific node config schema before constructing save_flow nodes or nodeConfigs.",
+  flags: [{ name: "node_type", type: "string", required: true, desc: "Flow node type, for example single_trigger, event_trigger, event_split_flow, or message_push" }],
   risk: "read",
   dryRun: (ctx) => buildMcpDryRun(ctx, serviceName15, toolName15, buildArgs15(ctx)),
   execute: async (ctx) => executeMcpCommand(ctx, serviceName15, toolName15, buildArgs15(ctx))
@@ -779,26 +779,41 @@ var modifyFlowBaseInfo = {
 // src/commands/te-engage/flow/save-flow.ts
 var serviceName21 = "engage_flow";
 var toolName21 = "save_flow";
+var allowedOperations = ["build", "preview", "commit"];
+function readAndValidateReq(ctx) {
+  const req = readRequiredJsonObject(ctx, "req");
+  const operation = typeof req.operation === "string" ? req.operation.trim().toLowerCase() : "";
+  if (!allowedOperations.includes(operation)) {
+    throw new Error(`Flag --req.operation must be one of: ${allowedOperations.join(", ")}`);
+  }
+  if ("nodeList" in req || "edgeList" in req) {
+    throw new Error("Flag --req must use nodes/edges instead of legacy nodeList/edgeList");
+  }
+  if ("sourceFlowUuid" in req) {
+    throw new Error("Flag --req.sourceFlowUuid is no longer supported; call +flow_detail and build nodes/edges instead");
+  }
+  return req;
+}
 function buildArgs21(ctx) {
   return {
     projectId: ctx.num("project_id"),
     req: {
       projectId: ctx.num("project_id"),
-      ...readRequiredJsonObject(ctx, "req")
+      ...readAndValidateReq(ctx)
     }
   };
 }
 var saveFlow = {
   service: "engage",
   command: "+save_flow",
-  description: "Create or update a flow draft.",
+  description: "Create, preview, or commit an operation-based flow draft with req.operation=build, preview, or commit. Copy existing flows by querying detail first, then building nodes/edges.",
   flags: [
     { name: "project_id", type: "number", required: true, alias: "p", desc: "Project ID" },
-    { name: "req", type: "json", required: true, desc: "Flow save request as JSON object" }
+    { name: "req", type: "json", required: true, desc: "Operation-based flow save request JSON object. Use operation=build with nodes/edges, operation=preview with draftId, or operation=commit with draftVersion and confirmToken. Do not use sourceFlowUuid clone mode." }
   ],
   risk: "write",
   validate: (ctx) => {
-    readRequiredJsonObject(ctx, "req");
+    readAndValidateReq(ctx);
   },
   dryRun: (ctx) => buildMcpDryRun(ctx, serviceName21, toolName21, buildArgs21(ctx)),
   execute: async (ctx) => executeMcpCommand(ctx, serviceName21, toolName21, buildArgs21(ctx))
@@ -817,11 +832,11 @@ function buildArgs22(ctx) {
 var validateFlowNodeConfig = {
   service: "engage",
   command: "+validate_flow_node_config",
-  description: "Validate one node config before save_flow.",
+  description: "Validate and normalize one candidate node config before placing it into save_flow.",
   flags: [
-    { name: "node_type", type: "string", required: true, desc: "Node type" },
-    { name: "config", type: "string", required: true, desc: "Node config JSON string" },
-    { name: "operation_mode", type: "string", required: true, desc: "Validation mode" }
+    { name: "node_type", type: "string", required: true, desc: "Flow node type, for example single_trigger, event_trigger, event_split_flow, or message_push" },
+    { name: "config", type: "string", required: true, desc: "Node config JSON object encoded as a string" },
+    { name: "operation_mode", type: "string", required: true, desc: "Validation mode. Use save_flow for the current exposed MCP protocol; save_submit_flow applies stricter submit-time checks" }
   ],
   risk: "read",
   dryRun: (ctx) => buildMcpDryRun(ctx, serviceName22, toolName22, buildArgs22(ctx)),

package/dist/{te-kb-DOGDQIU4.js → te-kb-KQJ53M3A.js}

@@ -1,11 +1,11 @@
 import {
   kbApi,
   kbUpload
-} from "./chunk-IDXW6MEJ.js";
+} from "./chunk-MDJGDI6K.js";
 import "./chunk-NOO24N7W.js";
-import "./chunk-OCQPQYHZ.js";
-import "./chunk-PFJFZVCK.js";
-import "./chunk-65DKFJZB.js";
+import "./chunk-2NDGFQHW.js";
+import "./chunk-AJTH7LT3.js";
+import "./chunk-YCLVYFK7.js";
 
 // src/commands/te-kb/query.ts
 var API_PATH = "/agent/api/external/knowledge-bases/query";

package/dist/{te-meta-5ESSQ5B3.js → te-meta-QLANJ4B4.js}

@@ -2,12 +2,12 @@ import {
   callMcpTool,
   parseMcpResult,
   resolveMcpUrl
-} from "./chunk-NGJDCOYA.js";
-import "./chunk-WXBCP6SD.js";
+} from "./chunk-GWZ5MYWE.js";
+import "./chunk-KGJQCYVC.js";
 import "./chunk-NOO24N7W.js";
-import "./chunk-OCQPQYHZ.js";
-import "./chunk-PFJFZVCK.js";
-import "./chunk-65DKFJZB.js";
+import "./chunk-2NDGFQHW.js";
+import "./chunk-AJTH7LT3.js";
+import "./chunk-YCLVYFK7.js";
 
 // src/commands/te-meta/shared.ts
 function createMcpCommand(config) {

package/dist/{te-meta-Z47X4VT3.js → te-meta-TOA6FWDE.js}

@@ -2,12 +2,12 @@ import {
   callMcpTool,
   parseMcpResult,
   resolveMcpUrl
-} from "./chunk-NXJP4CES.js";
-import "./chunk-WXBCP6SD.js";
+} from "./chunk-7QQ4233A.js";
+import "./chunk-KGJQCYVC.js";
 import "./chunk-NOO24N7W.js";
-import "./chunk-OCQPQYHZ.js";
-import "./chunk-PFJFZVCK.js";
-import "./chunk-65DKFJZB.js";
+import "./chunk-2NDGFQHW.js";
+import "./chunk-AJTH7LT3.js";
+import "./chunk-YCLVYFK7.js";
 
 // src/commands/te-meta/shared.ts
 function createMcpCommand(config) {

package/dist/{te-team-SOVKZIDD.js → te-team-TQGMNHQQ.js}

@@ -1,15 +1,15 @@
 import {
   getAuthHeaders,
   kbApi
-} from "./chunk-IDXW6MEJ.js";
+} from "./chunk-MDJGDI6K.js";
 import {
   printError,
   printOutput
-} from "./chunk-ONOA6DYB.js";
+} from "./chunk-ZAOL36CG.js";
 import "./chunk-NOO24N7W.js";
-import "./chunk-OCQPQYHZ.js";
-import "./chunk-PFJFZVCK.js";
-import "./chunk-65DKFJZB.js";
+import "./chunk-2NDGFQHW.js";
+import "./chunk-AJTH7LT3.js";
+import "./chunk-YCLVYFK7.js";
 
 // src/commands/te-team/shared.ts
 var API_PREFIX = process.env.AE_API_PREFIX ?? "/agent";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingai/ae-cli",
-  "version": "6.0.24",
+  "version": "6.0.27",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {
@@ -33,6 +33,7 @@
     "verify:self-check-overlay": "node test/self-check-overlay.test.mjs",
     "verify:update-check": "npx tsx test/update-check.test.mjs",
     "self-check": "node self-check/scan.mjs",
+    "sync:skills-to-db": "node scripts/sync-skills-to-db.mjs",
     "check:agents-docs": "node scripts/check-agents-docs-sync.mjs",
     "prepublishOnly": "npm run build",
     "start": "node dist/index.js",
@@ -67,6 +68,7 @@
     "@types/node": "^22.0.0",
     "@types/turndown": "^5.0.6",
     "@types/ws": "^8.5.0",
+    "mysql2": "^3.22.6",
     "tsup": "^8.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.5.0"

package/skills/ae-agent/SKILL.md

@@ -1,174 +1,205 @@
 ---
 name: ae-agent
-version: 1.1.0
+version: 1.2.0
 description: "AE Agent platform resource management CLI for listing Agents, creating and updating automations, adding/removing/listing/toggling custom models, MCP servers, Skills, uploading sandbox files to the attachment library, browsing the MCP/Skill market, setting market category/icon, copying system/company Skills to personal, and submitting/approving/sharing Skills. Use when the user asks to manage Agent platform resources, browse the market, or create scheduled Agent automations. Must use ae-cli agent commands."
 ---
 
 # ae-agent
 
+> **CRITICAL — Before running any `+<command>` command, you MUST first read the corresponding `references/<command>.md`.** The reference filename equals the command name without the leading `+`, for example `+add-mcp` → `references/add-mcp.md`.
+> **CRITICAL — Never guess record IDs (Agent / automation / model / MCP / Skill / submission / share / attachment).** Always use the appropriate `+list-*` command to discover real IDs first.
+> **CRITICAL — All Agent platform resources are served under the `/api/sandbox/agent/*` path.** Do not reference legacy paths.
+
 AE CLI (`ae-cli`) agent platform resource commands are invoked through:
 
 ```bash
 ae-cli agent +<command> [options]
 ```
 
-## Global Rules
+All commands live under the `agent` service. Quick help:
+
+```bash
+ae-cli agent --help
+ae-cli agent +list-agents --help
+ae-cli agent +create-automation --help
+```
+
+## Global AE CLI Rules
 
 - Use this skill for Agent platform resource management: Agents, automations, models, MCP servers, Skills, attachments, the MCP/Skill market, and Skill copy/approval/share flows.
-- Read operations can run directly. Write operations require explicit user intent and normally keep the confirmation prompt unless `--yes` is passed.
-- Prefer `--dry-run` before destructive writes.
-- Only personal scope resources can be created or deleted; company/system resources are read-only in the CLI (exception: root users can approve/reject submissions and set company-scope meta).
+- **Read operations** (`+list-*`) can run directly once required IDs are known.
+- **Write operations** require explicit user intent and keep the confirmation prompt by default. Pass `--yes` only in fully automated pipelines.
+- Prefer `--dry-run` before destructive writes to inspect the request shape without executing.
+- Personal and company scope resources can be created/updated/deleted; company scope requires root/agent_admin role; system resources are read-only (exception: root users can approve/reject submissions and set company-scope meta).
 - Toggle operations on company/system resources only affect the current user's preference, not the global state.
+- Never invent record IDs. Discover them with `+list-*` commands or accept them from the user.
 - JSON flags must be valid JSON strings, usually wrapped in single quotes in shell.
-- Successful commands return JSON by default. Use `--format table` when a table is easier to scan.
-- `--host <url>` overrides the active AE host. It is available on every command and may be placed after the subcommand, e.g. `ae-cli agent +<command> --host <url>`.
 
-## Commands
+### Global Parameters
 
-### Agents
+| Parameter | Description |
+|---|---|
+| `--format <json\|table>` | Output format. Default is JSON. |
+| `--host <url>` | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli agent +<command> --host <url>`. |
+| `--yes` | Skip confirmation for write operations. |
+| `--dry-run` | Show request details (method + URL + body) without executing. |
 
-| Command        | Risk | Purpose                                                        |
-| -------------- | ---: | -------------------------------------------------------------- |
-| `+list-agents` | read | List Agents visible to current user (personal/company/system). |
+### Output and Errors
 
-### Automations
+- Successful commands return machine-readable JSON by default. Use `--format table` when a table is easier to scan.
+- Failed commands return `{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }` and exit non-zero.
 
-| Command              |  Risk | Purpose                                |
-| -------------------- | ----: | -------------------------------------- |
-| `+create-automation` | write | Create an Agent automation task. |
+## When to Use
 
-### Models
+Use `ae-agent` for all Agent platform resource work:
 
-| Command         |  Risk | Purpose                                                        |
-| --------------- | ----: | -------------------------------------------------------------- |
-| `+list-models`  |  read | List models visible to current user (personal/company/system). |
-| `+add-model`    | write | Add a custom model (personal scope).                           |
-| `+del-model`    | write | Delete a personal model.                                       |
-| `+toggle-model` | write | Enable or disable a model.                                     |
+- **Agents & automations**: list Agents, create / list / update scheduled Agent automations.
+- **Models**: list, add, delete, toggle custom models.
+- **MCP servers**: list, add, delete, toggle MCP servers; browse the MCP market; set market meta.
+- **Skills**: list, add, delete, toggle Skills; browse the Skill market; set market meta; copy system/company Skills to personal; submit/approve/reject company-scope Skills; share/accept/reject peer-to-peer Skills.
+- **Attachments**: list, upload, soft-delete sandbox files in the attachment library.
 
-### MCP Servers
+If the user's intent is data analysis, audience management, metadata governance, TeamRuns, or knowledge bases, switch to `ae-analysis` / `ae-engage` / `ae-dataops` / `ae-team` / `ae-kb`.
 
-| Command       |  Risk | Purpose                                   |
-| ------------- | ----: | ----------------------------------------- |
-| `+list-mcps`  |  read | List MCP servers visible to current user. |
-| `+add-mcp`    | write | Add an MCP server (personal scope).       |
-| `+del-mcp`    | write | Delete a personal MCP server.             |
-| `+toggle-mcp` | write | Enable or disable an MCP server.          |
+## Tool Groups (66 commands)
 
-### Skills
+### Agents (5)
 
-| Command         |  Risk | Purpose                                    |
-| --------------- | ----: | ------------------------------------------ |
-| `+list-skills`  |  read | List Skills visible to current user.       |
-| `+add-skill`    | write | Create a custom Skill (personal scope).    |
-| `+del-skill`    | write | Delete a personal Skill (physical delete). |
-| `+toggle-skill` | write | Enable or disable a Skill.                 |
+- `+list-agents` ([doc](references/list-agents.md)) — list Agents visible to current user (personal/company/system)
+- `+create-agent` ([doc](references/create-agent.md)) — create a new Agent (personal/company scope; company requires root/agent_admin; name/description/instructions/model/mcp-ids/skill-ids)
+- `+update-agent` ([doc](references/update-agent.md)) — update an Agent's name/description/instructions/model/mcp-ids/skill-ids/enabled
+- `+del-agent` ([doc](references/del-agent.md)) — soft-delete a personal/company Agent (company requires root/agent_admin; system Agents cannot be deleted)
+- `+get-agent` ([doc](references/get-agent.md)) — get a single Agent's detail
 
-### Market (browse)
+### Automations (3)
 
-| Command              | Risk | Purpose                                                                  |
-| -------------------- | ----: | ------------------------------------------------------------------------ |
-| `+list-mcp-market`   | read | List MCP servers from the market (filter by scope/category/search/sort). |
-| `+list-skill-market` | read | List Skills from the market (only approved; same filters).              |
+- `+list-automations` ([doc](references/list-automations.md)) — list current user's Agent automation tasks
+- `+create-automation` ([doc](references/create-automation.md)) — create an Agent automation task (hourly/daily/weekly/monthly or cron)
+- `+update-automation` ([doc](references/update-automation.md)) — update an automation's name, instruction, schedule, or enabled state
 
-### Category & Icon (meta)
+### Models (6)
 
-| Command           |  Risk | Purpose                                                                       |
-| ----------------- | ----: | ----------------------------------------------------------------------------- |
-| `+set-mcp-meta`   | write | Update an MCP server market category/icon. Company requires root; system RO. |
-| `+set-skill-meta` | write | Update a Skill market category/icon. Company requires root; system RO.       |
+- `+list-models` ([doc](references/list-models.md)) — list models visible to current user (personal/company/system)
+- `+add-model` ([doc](references/add-model.md)) — add a custom model (personal/company scope; company requires root/agent_admin)
+- `+update-model` ([doc](references/update-model.md)) — update a custom model (personal/company scope; company requires root/agent_admin; apiKey left blank to keep existing)
+- `+del-model` ([doc](references/del-model.md)) — delete a personal/company model (company requires root/agent_admin)
+- `+toggle-model` ([doc](references/toggle-model.md)) — enable or disable a model
+- `+test-model` ([doc](references/test-model.md)) — test custom model connectivity (LLM only)
 
-### Copy to personal
+### MCP Servers (14)
 
-| Command       |  Risk | Purpose                                                                |
-| ------------- | ----: | ---------------------------------------------------------------------- |
-| `+copy-skill` | write | Copy a system/company Skill to a personal copy (independent duplicate). |
+- `+list-mcps` ([doc](references/list-mcps.md)) — list MCP servers visible to current user
+- `+add-mcp` ([doc](references/add-mcp.md)) — add an MCP server (personal/company scope; company requires root/agent_admin)
+- `+update-mcp` ([doc](references/update-mcp.md)) — update an MCP server's config (url/transport/headers/auth-mode; connectivity validated)
+- `+del-mcp` ([doc](references/del-mcp.md)) — delete a personal MCP server
+- `+toggle-mcp` ([doc](references/toggle-mcp.md)) — enable or disable an MCP server
+- `+mcp-tools` ([doc](references/mcp-tools.md)) — list tools provided by an MCP server (OAuth auto-refresh)
+- `+mcp-auth-start` ([doc](references/mcp-auth-start.md)) — start OAuth authorization (cliMode; print authorizeUrl, then poll with +mcp-auth-status)
+- `+mcp-auth-status` ([doc](references/mcp-auth-status.md)) — query OAuth status (not_required/needs_auth/authenticated/reauth_required/disabled)
+- `+mcp-auth-disconnect` ([doc](references/mcp-auth-disconnect.md)) — disconnect OAuth, clear token and disable
+- `+list-mcp-credentials` ([doc](references/list-mcp-credentials.md)) — list per-user credentials for system MCPs
+- `+set-mcp-credential` ([doc](references/set-mcp-credential.md)) — upsert a per-user MCP credential (oauth/apikey)
+- `+auto-provision-mcp-credentials` ([doc](references/auto-provision-mcp-credentials.md)) — auto-inject credentials for all system MCPs (uses session token by default)
+- `+mcp-token` ([doc](references/mcp-token.md)) — get the shared MCP token (useMcpToken=true; plaintext, mind shell history)
+- `+mcp-stats` ([doc](references/mcp-stats.md)) — MCP call stats for recent N days (`--days` 1-365 default 30; by server / by day)
 
-### Skill Approval (company-scope publish)
+### Skills (4)
 
-| Command                    |  Risk | Purpose                                                            |
-| -------------------------- | ----: | ------------------------------------------------------------------ |
-| `+submit-skill`            | write | Submit a personal Skill for company-scope review.                  |
-| `+list-skill-submissions`  |  read | List submissions (root sees all; others see only their own).       |
-| `+cancel-skill-submission` | write | Cancel a pending submission (submitter or root).                   |
-| `+approve-skill`           | write | Approve a submission (root only). Creates a company-scope copy.    |
-| `+reject-skill`            | write | Reject a submission with a reason (root only).                     |
+- `+list-skills` ([doc](references/list-skills.md)) — list Skills visible to current user
+- `+add-skill` ([doc](references/add-skill.md)) — create a custom Skill (personal/company scope; company requires root/agent_admin)
+- `+del-skill` ([doc](references/del-skill.md)) — delete a personal Skill (physical delete)
+- `+toggle-skill` ([doc](references/toggle-skill.md)) — enable or disable a Skill
 
-### Skill Share (peer-to-peer)
+### Skill content & assets (16)
 
-| Command               |  Risk | Purpose                                                           |
-| --------------------- | ----: | ----------------------------------------------------------------- |
-| `+share-skill`        | write | Share a personal Skill to a same-company user.                    |
-| `+list-skill-shares`  |  read | List Skill shares (received by default; `--direction sent`).     |
-| `+accept-skill-share` | write | Accept a received share (creates a personal copy for recipient).  |
-| `+reject-skill-share` | write | Reject a received share.                                          |
+- `+edit-skill` ([doc](references/edit-skill.md)) — edit a Skill's content (name/description/instructions/category/icon)
+- `+get-skill-content` ([doc](references/get-skill-content.md)) — read a Skill's SKILL.md source
+- `+list-skill-assets` ([doc](references/list-skill-assets.md)) — list asset files of a Skill
+- `+upload-skill-asset` ([doc](references/upload-skill-asset.md)) — upload an asset file (`isDangerousFile` checked; 1MB)
+- `+read-skill-asset` ([doc](references/read-skill-asset.md)) — read an asset file (binary-safe with `--output`)
+- `+del-skill-asset` ([doc](references/del-skill-asset.md)) — delete an asset file
+- `+list-skill-references` ([doc](references/list-skill-references.md)) — list reference files (`.md` only)
+- `+upload-skill-reference` ([doc](references/upload-skill-reference.md)) — upload a reference file (`.md` only; 1MB)
+- `+read-skill-reference` ([doc](references/read-skill-reference.md)) — read a reference file
+- `+del-skill-reference` ([doc](references/del-skill-reference.md)) — delete a reference file
+- `+list-skill-scripts` ([doc](references/list-skill-scripts.md)) — list script files of a Skill
+- `+upload-skill-script` ([doc](references/upload-skill-script.md)) — upload a script file (`isDangerousFile` checked; 1MB)
+- `+read-skill-script` ([doc](references/read-skill-script.md)) — read a script file (binary-safe with `--output`)
+- `+del-skill-script` ([doc](references/del-skill-script.md)) — delete a script file
+- `+upload-skill` ([doc](references/upload-skill.md)) — create/replace a Skill from a ZIP package (parses SKILL.md; 5MB)
+- `+rescan-skills` ([doc](references/rescan-skills.md)) — rescan local filesystem and sync Skills to DB (root only)
 
-### Attachments
+### Market (browse) (2)
 
-| Command             |  Risk | Purpose                                       |
-| ------------------- | ----: | --------------------------------------------- |
-| `+list-attachments` |  read | List user attachments (paginated).            |
-| `+add-attachment`   | write | Upload sandbox file(s) to attachment library. |
-| `+del-attachment`   | write | Soft-delete an attachment.                    |
+- `+list-mcp-market` ([doc](references/list-mcp-market.md)) — list MCP servers from the market (filter by scope/category/search/sort)
+- `+list-skill-market` ([doc](references/list-skill-market.md)) — list Skills from the market (only approved; same filters)
 
-## Usage Examples
+### Category & Icon (meta) (2)
 
-### List all visible models
+- `+set-mcp-meta` ([doc](references/set-mcp-meta.md)) — update an MCP server market category/icon (company requires root; system RO)
+- `+set-skill-meta` ([doc](references/set-skill-meta.md)) — update a Skill market category/icon (company requires root; system RO)
 
-```bash
-ae-cli agent +list-models
-ae-cli agent +list-models --scope personal --format table
-```
+### Copy to personal (1)
 
-### List all visible Agents
+- `+copy-skill` ([doc](references/copy-skill.md)) — copy a system/company Skill to a personal copy (independent duplicate)
 
-```bash
-ae-cli agent +list-agents
-ae-cli agent +list-agents --scope personal --q "daily"
-```
+### Skill Approval (company-scope publish) (5)
 
-### Create an enabled daily automation
+- `+submit-skill` ([doc](references/submit-skill.md)) — submit a personal Skill for company-scope review
+- `+list-skill-submissions` ([doc](references/list-skill-submissions.md)) — list submissions (root sees all; others see only their own)
+- `+cancel-skill-submission` ([doc](references/cancel-skill-submission.md)) — cancel a pending submission (submitter or root)
+- `+approve-skill` ([doc](references/approve-skill.md)) — approve a submission (root only). Creates a company-scope copy
+- `+reject-skill` ([doc](references/reject-skill.md)) — reject a submission with a reason (root only)
 
-```bash
-ae-cli agent +create-automation \
-  --name "Daily AI Brief" \
-  --schedule-kind daily \
-  --time 09:00 \
-  --message "Summarize yesterday's AI news" \
-  --yes
+### Skill Share (peer-to-peer) (4)
 
-# Create but keep paused when the user explicitly asks not to enable it.
+- `+share-skill` ([doc](references/share-skill.md)) — share a personal Skill to a same-company user
+- `+list-skill-shares` ([doc](references/list-skill-shares.md)) — list Skill shares (received by default; `--direction sent`)
+- `+accept-skill-share` ([doc](references/accept-skill-share.md)) — accept a received share (creates a personal copy for recipient)
+- `+reject-skill-share` ([doc](references/reject-skill-share.md)) — reject a received share
+
+### Attachments (4)
+
+- `+list-attachments` ([doc](references/list-attachments.md)) — list user attachments (paginated)
+- `+add-attachment` ([doc](references/add-attachment.md)) — upload sandbox file(s) to attachment library
+- `+del-attachment` ([doc](references/del-attachment.md)) — soft-delete an attachment
+- `+attachment-stats` ([doc](references/attachment-stats.md)) — attachment library stats (total count/size, image/document breakdown)
+
+## Cross-Command Notes
+
+- **Automation IDs**: use `+list-automations` to find the target ID internally, but do not surface raw automation IDs, raw JSON, or concrete detail paths in user-facing replies.
+- **MCP connectivity**: `+add-mcp` does NOT validate server connectivity — an unreachable URL is accepted at create time and only fails when the agent calls the MCP at runtime. Double-check the URL.
+- **Attachments**: upload supports files up to 50MB each, with a 1GB user quota. Batch uploads support partial success — individual file failures don't affect others.
+- **Skill `--instructions @-`**: reads from stdin, useful for piping long instruction text.
+- **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, Skill by download count). Market scope: `all | system | company | custom` (`custom` = personal).
+- **Meta on create/copy**: `+add-mcp` / `+add-skill` / `+copy-skill` accept optional `--category / --icon-emoji / --icon-color`; these are applied via a follow-up meta PATCH after creation. MCP creation still does NOT validate server connectivity.
+- **Copy vs toggle**: `+copy-skill` copies a system/company Skill to an independent personal copy. MCP has no copy (use `+toggle-mcp` to enable a system/company MCP per-user).
+- **Approval & share are Skill-only**: MCP has no approval or share flow. `+approve-skill` / `+reject-skill` require root.
+- **`--id` semantics differ by command**: `+submit-skill` / `+share-skill` / `+copy-skill` take a Skill ID; `+cancel-skill-submission` / `+approve-skill` / `+reject-skill` take a submission ID; `+accept-skill-share` / `+reject-skill-share` take a share ID.
+
+## Typical Workflows
+
+### Create a scheduled automation
+
+```bash
+# 1. Discover available Agents
+ae-cli agent +list-agents
+
+# 2. Create an enabled daily automation
 ae-cli agent +create-automation \
   --name "Daily AI Brief" \
   --schedule-kind daily \
   --time 09:00 \
   --message "Summarize yesterday's AI news" \
-  --enabled false \
+  --agent-id <agent-id> \
   --yes
-```
-
-### Add a custom model
 
-```bash
-ae-cli agent +add-model \
-  --model-id gpt-4o \
-  --name "GPT-4o" \
-  --base-url "https://api.openai.com/v1" \
-  --api-key "sk-xxx" \
-  --provider openai
-```
-
-### Add an MCP server
-
-```bash
-ae-cli agent +add-mcp \
-  --name my-mcp \
-  --url "https://mcp.example.com/mcp" \
-  --transport http \
-  --headers '{"Authorization":"Bearer token"}'
+# 3. (Optional) Pause or edit later
+ae-cli agent +list-automations --status active
+ae-cli agent +update-automation --id <automation-id> --enabled false --yes
 ```
 
-### Add an MCP with a market category and icon
+### Add an MCP server with market meta
 
 ```bash
 ae-cli agent +add-mcp \
@@ -177,97 +208,35 @@ ae-cli agent +add-mcp \
   --transport http \
   --headers '{"Authorization":"Bearer token"}' \
   --category dev_tool \
-  --icon-emoji robot
-```
-
-### Create a Skill with inline instructions
-
-```bash
-ae-cli agent +add-skill \
-  --name code-reviewer \
-  --description "Reviews code for best practices" \
-  --instructions "You are a code reviewer. Analyze the code for..."
-```
-
-### Create a Skill with instructions from stdin
-
-```bash
-echo "You are a helpful assistant that..." | \
-  ae-cli agent +add-skill --name helper --description "Helper skill" --instructions @-
-```
-
-### Browse the market
-
-```bash
-ae-cli agent +list-mcp-market --scope company --category dev_tool --sort calls
-ae-cli agent +list-skill-market --search "code review" --sort newest --format table
-```
-
-### Set market category / icon
-
-```bash
-ae-cli agent +set-mcp-meta --id <mcp-cuid> --category dev_tool --icon-emoji robot
-ae-cli agent +set-skill-meta --id <skill-cuid> --category data_query
+  --icon-emoji robot \
+  --yes
 ```
 
-### Copy a system/company Skill to personal
+### Publish a personal Skill to the company (root review)
 
 ```bash
-ae-cli agent +copy-skill --id <skill-cuid>
-ae-cli agent +copy-skill --id <skill-cuid> --category dev_tool --icon-emoji robot
-```
+# 1. Create a Skill
+ae-cli agent +add-skill --name code-reviewer --description "Reviews code" --instructions "You are a code reviewer..."
 
-### Submit a Skill for company approval
-
-```bash
+# 2. Submit for company review
 ae-cli agent +submit-skill --id <skill-cuid> --description "Code reviewer for the team"
-```
-
-### Review approvals (root)
 
-```bash
+# 3. Root reviews and approves
 ae-cli agent +list-skill-submissions --status pending
-ae-cli agent +approve-skill --id <submission-cuid>
-ae-cli agent +reject-skill --id <submission-cuid> --reason "Needs more detail"
+ae-cli agent +approve-skill --id <submission-cuid> --yes
 ```
 
 ### Share a Skill peer-to-peer
 
 ```bash
-ae-cli agent +share-skill --id <skill-cuid> --to-user-id <user-id>
+ae-cli agent +share-skill --id <skill-cuid> --to-user-id <user-id> --yes
+# Recipient accepts:
 ae-cli agent +list-skill-shares --direction received --status pending
-ae-cli agent +accept-skill-share --id <share-cuid>
-```
-
-### Upload a single file to attachment library
-
-```bash
-ae-cli agent +add-attachment --file ./output/report.png
-```
-
-### Upload multiple files
-
-```bash
-ae-cli agent +add-attachment --files '["./report.png", "./data.csv", "./chart.pdf"]'
+ae-cli agent +accept-skill-share --id <share-cuid> --yes
 ```
 
-### Toggle a model on/off
+## Quick Verification
 
 ```bash
-ae-cli agent +toggle-model --id <model-cuid> --enabled true
-ae-cli agent +toggle-model --id <model-cuid> --enabled false
+ae-cli agent --help
 ```
-
-## Notes
-
-- Only `personal` scope resources can be created or deleted via CLI.
-- Automations are enabled by default; pass `--enabled false` only when the user explicitly asks to create or update the task without enabling it. Use `+list-automations` to find the target ID internally, but do not show automation IDs, raw JSON, or concrete detail paths in user-facing replies.
-- MCP creation does NOT validate server connectivity — an unreachable URL is accepted at create time and only fails when the agent actually calls the MCP at runtime. Double-check the URL.
-- Attachment upload supports files up to 50MB each, with a 1GB user quota.
-- Batch attachment uploads support partial success — individual file failures don't affect others.
-- Skill `--instructions @-` reads from stdin, useful for piping long instruction text.
-- 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, Skill by download count). Market scope: `all | system | company | custom` (`custom` = personal).
-- `+add-mcp` / `+add-skill` accept optional `--category / --icon-emoji / --icon-color`; these are applied via a follow-up meta PATCH after creation. MCP creation still does NOT validate server connectivity.
-- `+copy-skill` copies a system/company Skill to an independent personal copy. Optional `--category / --icon-emoji / --icon-color` override the copy's market meta; omit them to inherit the source's. MCP has no copy (use `+toggle-mcp` to enable a system/company MCP per-user).
-- Approval and share flows are Skill-only; MCP has no approval or share. `+approve-skill` / `+reject-skill` require root.
-- `--id` semantics differ by command: `+submit-skill` / `+share-skill` / `+copy-skill` take a Skill ID; `+cancel-skill-submission` / `+approve-skill` / `+reject-skill` take a submission ID; `+accept-skill-share` / `+reject-skill-share` take a share ID.