sumelabs · chasehuh · Jun 25, 2026 · Jun 25, 2026
diff --git a/content/docs/cli.md b/content/docs/cli.md
@@ -1,60 +1,79 @@
 ---
 title: Overview
-description: Use Sume CLI as an agent-first shell wrapper over the Sume Public API.
+description: Use Sume CLI as an agent-first shell wrapper over the Sume Public API, MCP tools, and Sume skill packs.
 ---
 
-Sume CLI is a thin wrapper over the Sume Public API. It works for humans in a terminal and for agents through normal shell commands.
+Sume CLI is the local command-line interface for Sume. It is built for humans,
+automation scripts, and agents that need a structured way to call Sume without
+using internal services.
+
+The CLI is intentionally thin:
+
+- It calls Sume Public API v1.
+- It uses the API-key workspace resolved by Sume.
+- It supports human output and stable `--json` output.
+- It can start a local MCP stdio server from the same binary.
+- It can install Sume agent skill packs into local projects.
+- It does not connect to Sume databases, Railway services, provider APIs, or
+  internal routes.
 
 Default API base:
 
 ```text
 https://www.sume.so/api/v1
 ```
 
-## Why use the CLI
+## What the CLI is for
 
-- Human output is concise.
-- `--json` returns structured output for automation.
-- Commands map to public API endpoints.
-- It does not connect to Sume databases, queues, provider APIs, deployment services, or internal routes.
-- It can download safe public media URLs returned by Sume without exposing raw provider details.
+Use the CLI when you want to:
 
-## Install
+- check account, workspace, and credit state;
+- list jobs and fetch job results;
+- search Asset Library scenes;
+- create image, video, Paid Ads, Face Swap, or Reference Analysis jobs;
+- upload videos into Asset Library or Face Swap flows;
+- expose Sume tools to MCP clients;
+- install Sume skill guidance into coding-agent projects.
 
-macOS and Linux:
+## Quick install
 
 ```bash
 curl https://cli.sume.so/install -fsS | bash
 ```
 
-Windows PowerShell:
-
-```powershell
-irm https://cli.sume.so/install.ps1 | iex
-```
-
-Then authenticate:
+Then authenticate and verify:
 
 ```bash
 sume login
 sume me
 sume credits
 ```
 
-## Common read-only commands
+Remote, SSH, Hermes, Modal, and other headless terminals should use the device
+flow instead:
 
 ```bash
+sume login --no-browser --timeout 600
+```
+
+See [Authentication](/cli/authentication) for the full remote-agent pattern.
+
+## Common read-only workflow
+
+```bash
+sume --version
 sume auth status
 sume me --json
 sume credits --json
 sume jobs list --limit 5 --json
-sume assets search "product demo hook" --limit 5 --json
-sume assets get <asset_id> --json
+sume assets search "product demo hook" --source-type generated --limit 5 --json
 ```
 
-## Common create commands
+Read-only commands are safe starting points for agents. They still may return
+media metadata or public media URLs, so redact full URLs and private identifiers
+when copying results into chat or logs.
 
-Generation commands may spend credits. Confirm user intent before running them from an agent.
+## Common generation workflow
 
 ```bash
 sume images generate \
@@ -67,37 +86,60 @@ sume videos generate \
   --duration 4 \
   --resolution 480p \
   --json
-
-sume reference-analysis create \
-  --url "https://www.tiktok.com/@brand/video/1234567890" \
-  --locale ko \
-  --json
 ```
 
+Generation commands can spend credits or create provider work. Agents should
+confirm user intent before running them.
+
+## CLI docs
+
+| Page | Use it for |
+|---|---|
+| [Install and update](/cli/install-login) | Installer, version checks, binary updates, and release behavior. |
+| [Authentication](/cli/authentication) | Browser login, remote/headless login, API keys, and logout. |
+| [Configuration](/cli/configuration) | Config files, environment variables, update settings, and API base overrides. |
+| [Command reference](/cli/commands) | Top-level commands and safe command examples. |
+| [Jobs and assets](/cli/jobs-assets) | Async job polling, result download, Asset Library search, uploads, and finalize. |
+| [Generation workflows](/cli/generation-workflows) | Image, video, Paid Ads, Face Swap, and Reference Analysis workflows. |
+| [MCP server](/cli/mcp) | `sume mcp`, toolsets, write/paid gates, and MCP-only helpers. |
+| [Agent skills](/cli/agent-skills) | `sume init`, `sume skills`, skill packs, and agent guidance. |
+| [Troubleshooting](/cli/troubleshooting) | Missing keys, remote login, downloads, updates, jobs, and MCP startup. |
+| [Security](/cli/security) | Secrets, signed URLs, paid calls, and automation safety rules. |
+
+## Public API relationship
+
+CLI commands map to the [Public API](/public-api). Use the CLI for shell and
+agent workflows. Use the Public API directly for server integrations that need
+their own HTTP client, retry policy, or deployment environment.
+
+For exact API shapes, see:
+
+- [API reference](/api/reference)
+- [API cookbook](/api/cookbook)
+- [`/api/openapi.json`](/api/openapi.json)
+
 ## Agent mode
 
-Use `--json` whenever another program will parse output.
+Use `--json` whenever another program will parse output:
 
 ```bash
 sume tools list --json
 sume tools schema assets.search --json
 sume assets search "woman looking at camera hook" --source-type generated --limit 5 --json
 ```
 
-Agents should summarize output and redact full URLs, request ids, user emails, workspace ids, API key ids, and large raw payloads.
+Agents should summarize output and redact:
 
-## Local configuration
+- API keys;
+- login URLs and temporary user codes;
+- signed upload URLs;
+- storage object keys;
+- full private or signed media URLs;
+- user, workspace, and API key ids unless strictly needed for debugging.
 
-Environment variables override local config:
+## Release note
 
-```bash
-export SUME_API_KEY="sume_live_..."
-export SUME_API_BASE_URL="https://www.sume.so/api/v1"
-```
-
-Manual setup:
-
-```bash
-sume setup --api-key "$SUME_API_KEY"
-sume setup --base-url "https://www.sume.so/api/v1"
-```
+These docs describe the current `SumeLabs/sume-cli` release line around
+`v0.1.11` and the merged source on `main`. If a command appears in source but
+your installed binary does not recognize it, run `sume update --check` and see
+[Install and update](/cli/install-login).
diff --git a/content/docs/cli/agent-skills.md b/content/docs/cli/agent-skills.md
@@ -0,0 +1,130 @@
+---
+title: Agent skills
+description: Install Sume skill packs and project instructions for Claude, Cursor, AGENTS.md, and other agent workflows.
+---
+
+Sume CLI ships agent guidance in two forms:
+
+- `sume init` installs the default project instructions.
+- `sume skills` installs focused Sume skill packs from the public registry.
+
+Both are designed to route agents toward CLI/MCP schemas instead of copying
+large static API schemas into prompts.
+
+## Install default project instructions
+
+```bash
+sume init
+sume init --target all
+sume init --target claude,cursor,agents-md
+sume init --force
+```
+
+Targets:
+
+| Target | Output |
+|---|---|
+| `claude` | `.agents/skills/sume/SKILL.md` when `.agents/` exists, otherwise `.claude/skills/sume/SKILL.md`. |
+| `cursor` | `.cursor/rules/sume.mdc`. |
+| `agents-md` | Managed `<!-- BEGIN sume:sume -->` block in `AGENTS.md`. |
+| `all` | All supported targets. |
+
+In a blank project, create an agent root first:
+
+```bash
+mkdir -p .agents
+sume init --target claude
+```
+
+## Skill registry
+
+List available skills:
+
+```bash
+sume skills list
+sume skills list generation
+```
+
+Install a skill:
+
+```bash
+sume skills install sume
+sume skills install sume-assets
+```
+
+Update installed skills:
+
+```bash
+sume skills update
+sume skills update sume-generation
+```
+
+Remove a skill:
+
+```bash
+sume skills remove sume
+```
+
+The default registry is:
+
+```text
+https://cli.sume.so/skills/registry
+```
+
+The CLI verifies registry file checksums before writing installed skill files.
+
+## Available Sume skill packs
+
+| Skill | Use for |
+|---|---|
+| `sume` | Top-level setup, auth, safety, update, and workflow routing. |
+| `sume-assets` | Asset Library search, uploads, downloads, and scene clip semantics. |
+| `sume-brand` | Brand DNA read/analyze workflows and reference image handling. |
+| `sume-generation` | Image/video generation, async jobs, polling, results, and downloads. |
+| `sume-ads` | Paid Ads video, avatars, Face Swap, and source-video boundaries. |
+| `sume-reference-analysis` | Public Reel/TikTok reference analysis and result summaries. |
+| `sume-tools` | MCP setup, schema discovery, skill refresh, and tool routing. |
+
+## What skills should tell agents
+
+Sume skills should instruct agents to:
+
+- start read-only with `sume --version`, `sume me --json`, and `sume credits --json`;
+- use `sume login --no-browser --timeout 600` in remote/headless terminals;
+- inspect `sume tools list --json` and `sume tools schema <tool> --json`;
+- ask before running paid/provider generation;
+- avoid printing secrets, signed URLs, full private media URLs, provider
+  payloads, user ids, workspace ids, and raw emails;
+- prefer CLI/MCP schemas as the source of truth for exact parameters.
+
+## Hermes, Modal, and remote terminals
+
+When an agent is running in a remote terminal, it should not run plain
+`sume login` and assume a local browser exists. Use:
+
+```bash
+sume login --no-browser --timeout 600
+```
+
+For agent-controlled terminals, use the background login pattern from
+[Authentication](/cli/authentication), show the URL/code only to the requesting
+user, then verify with:
+
+```bash
+sume auth status --json
+sume me --json
+```
+
+Do not ask the user to paste API keys into chat unless the user explicitly
+chooses that credential path.
+
+## Registry overrides
+
+Use overrides only for local registry testing:
+
+```bash
+export SUME_SKILLS_URL="https://cli.sume.so/skills/registry"
+export SUME_SKILLS_API_URL="https://cli.sume.so/skills"
+```
+
+Production users should use the defaults.
diff --git a/content/docs/cli/agent-usage.md b/content/docs/cli/agent-usage.md
@@ -3,18 +3,44 @@ title: Agent usage
 description: Use Sume CLI safely from coding agents and automation scripts.
 ---
 
-Agents should use Sume CLI through explicit shell commands and parse `--json` output.
+This page is kept for existing links. For current agent guidance, use:
+
+- [Authentication](/cli/authentication)
+- [MCP server](/cli/mcp)
+- [Agent skills](/cli/agent-skills)
+- [Security](/cli/security)
+
+Agents should use Sume CLI through explicit shell commands and parse `--json`
+output.
 
 ## JSON-first workflow
 
 ```bash
+sume --version
+sume auth status
 sume me --json
 sume credits --json
 sume jobs list --limit 5 --json
 sume assets search "product demo hook" --source-type generated --limit 5 --json
-sume images generate --prompt "clean product photo" --wait --json
 ```
 
+Generation commands such as `images generate`, `videos generate`, `ads videos
+create`, `face-swap create`, and `reference-analysis create` can spend credits.
+Agents should ask for explicit user approval before running them.
+
+## Remote login
+
+In Hermes, Modal, SSH, Telegram-mediated terminals, or other remote/headless
+contexts, use:
+
+```bash
+sume login --no-browser --timeout 600
+```
+
+Do not ask the user to paste API keys into chat unless the user explicitly
+chooses that credential path. Treat login URLs/codes as temporary sensitive auth
+material.
+
 ## Install project instructions
 
 ```bash
@@ -28,7 +54,9 @@ sume init --target claude,cursor,agents-md
 ## Safety rules
 
 - Do not echo API keys.
+- Do not echo login URLs, user codes, signed upload URLs, or storage object keys.
 - Do not paste private URLs or signed query strings into prompts.
 - Use read-only commands before generation commands.
 - Treat generation as a credit-spending action.
 - Prefer fetching one asset by id after search rather than dumping large result sets.
+- Inspect `sume tools list --json` and `sume tools schema <tool> --json` before constructing unfamiliar commands.