@302ai/media-studio-cli 0.1.0-beta.3 → 0.1.0-beta.5

package/README.md

@@ -1,6 +1,6 @@
 # @302ai/media-studio-cli
 
-CLI for [AI Media Studio](https://302.ai) — drive media-studio chat from any
+CLI for AI Media Studio — drive media-studio chat from any
 terminal or external agent.
 
 ## Install
@@ -17,11 +17,11 @@ npm install -g @302ai/media-studio-cli@beta
 ```
 
 > **No stable release exists yet.** `latest` points at a prerelease, so both
-> commands above currently install the same build. Staging-server visibility is
-> gated on the package *version* carrying a prerelease tag — not on the
-> dist-tag — so it is on for both: **Staging** appears in `msc login` and in
-> `--region` whichever way you install. A future stable release will hide it
-> from both channels.
+> commands above currently install the same build. Staging- and Local-server
+> visibility is gated on the package *version* carrying a prerelease tag — not
+> on the dist-tag — so both are on for either install: **Staging** and
+> **Local** appear in `msc login` and in `--region` whichever way you install.
+> A future stable release will hide them from both channels.
 
 > If you installed via **bun** and get `command not found`: bun's global bin
 > dir is not on PATH by default. Run once:
@@ -33,14 +33,18 @@ npm install -g @302ai/media-studio-cli@beta
 ## Usage
 
 ```bash
-media-studio-cli login        # authenticate against a media-studio server
-media-studio-cli whoami       # show current auth status
-media-studio-cli chat "hi"    # one-shot chat turn
-media-studio-cli sessions     # list sessions from server
-media-studio-cli logout       # clear stored credentials
+msc login                   # authenticate in a browser
+msc guide                   # the full agent-facing manual
+msc whoami                  # show current auth status
+msc chat "hi"               # one chat turn (multi-turn by default)
+msc sessions                # list sessions from the server
+msc skills                  # list the skill catalog you can reference
+msc logout                  # clear stored credentials
 ```
 
-`msc` is the short alias for `media-studio-cli` (same program, both installed):
+`media-studio-cli` is the long alias for `msc` — the same program, both
+installed. The docs, the help output, and every error message use the short
+name:
 
 ```bash
 msc chat "画一只猫" -r        # -r/--show-reasoning = 展示模型推理过程
@@ -50,9 +54,24 @@ msc sessions                  # 列出所有会话（标记当前默认 `(curren
 msc sessions --json           # 机器可读的原始 JSON 数组
 msc sessions use <id>         # 纯本地切换默认会话（零请求、不校验）
 msc sessions rm <id>          # 删除服务端会话（交互确认，或加 -y/--yes 跳过）
+msc skills                    # 列出技能库（--plaza 浏览技能广场）
+msc skills add <slug>          # 从广场安装技能（如 brainstorming，见 --plaza --json 的 slug）
+msc skills rm <command>       # 从技能库移除（-y/--yes 跳过确认）
+msc skills enable <command>   # 启用 / disable 停用
 msc --help                    # all flags
 ```
 
+`msc --help` carries an agent-oriented quickstart — the auth prerequisite, the
+three canonical calls, and the `--json` contract. `msc guide` prints the full
+manual: every command, both JSON schemas, the `nextStep` values, exit codes,
+stream discipline, and skill semantics. Point an agent at those two instead of
+duplicating them here.
+
+Headless environments cannot complete browser sign-in, so `msc login` refuses
+immediately instead of waiting out the callback deadline: CI (`CI` set), and
+Linux with neither `DISPLAY` nor `WAYLAND_DISPLAY`. Sign in from a machine
+whose browser can reach the loopback callback.
+
 ### Multi-turn conversation
 
 `chat` is multi-turn by default — no flag needed. The CLI keeps a single
@@ -77,9 +96,89 @@ msc chat "记住数字42"
 msc chat "刚才的数字是几?"   # answers 42
 ```
 
-Point at a different server via `MEDIA_STUDIO_API_URL` env var, or
-`msc login --region local|cn|default` (the server you log into is saved and
-reused).
+Point at a different server via `msc login --region default|cn|local` (the
+server you log into is saved and reused; `local` — like `staging` — is a
+prerelease-only region, see the note at the top).
+
+### Configuration and storage
+
+The CLI stores credentials and local settings in:
+- **Default**: `~/.config/media-studio-cli/`
+- **XDG standard**: `$XDG_CONFIG_HOME/media-studio-cli/`
+- **Override**: `MEDIA_STUDIO_CONFIG_DIR=/path/to/dir`
+
+Key files:
+- `auth.json`: stores active platform credentials and user session metadata (permissions `0600`)
+- `config.json`: stores CLI client settings, including `lastSessionId` pointer
+
+### Skills
+
+Discover what your account can reference, then reference it — the reference
+must name a skill that exists in your catalog:
+
+```bash
+msc skills                     # list your library
+msc skills --json              # raw catalog array (see fields below)
+msc skills --plaza             # browse the Skill Plaza with your library
+                               # state merged in (built-ins excluded)
+msc skills --plaza --json
+
+msc skills add <slug>           # install a plaza entry by slug
+msc skills rm <command>        # remove a library skill by command
+msc skills enable <command>    # flip a library skill's enabled flag
+msc skills disable <command>
+```
+
+`add` takes the entry's plaza slug (`brainstorming`, shown in
+`msc skills --plaza --json` as `slug`); the library mutations take the
+command string (`brainstorming` and `/brainstorming` are the same entry) —
+the same string the prompt uses to reference the skill.
+
+`--json` is the intended output for agents: the catalog is the input to a
+decision the calling program makes itself. Both `descriptionEn`/`descriptionZh`
+are passed through untouched — upstream does not guarantee the `En` slot is
+English, so the CLI picks nothing. The human rendering lists names only (the
+command string is available in `--json`) with the full `descriptionEn` on a
+second line, and marks `[on]` enabled / `[off]` disabled / `[-]` not installed
+in the plaza view.
+
+**Shared API endpoints**: mutations use the exact same endpoints as the web app
+(`POST /api/skills` for installs, `DELETE /api/skills?skillId=` for removal,
+`POST /api/skills/enabled` for enable/disable). The CLI resolves the slug/command
+to the entry/id before calling the endpoint. `rm` requires `--yes` outside a
+terminal. Built-in entries are rejected (422): they sync into your library from
+the backend. Managing skills (upload, cover) stays in the Media Studio web app.
+
+Then reference a skill in the prompt and the CLI installs it into the session
+sandbox on demand:
+
+```bash
+msc chat "/always-hello 不管我说什么"      # leading slash command
+msc chat "%%/always-hello%%不管我说什么"    # web composer marker, paste-compatible
+```
+
+Both spellings resolve to the same thing. The upstream installs a skill only
+from the turn's `skill_urls` field, so the CLI looks the reference up in your
+catalog (`GET /api/skills`) and sends the matching package URL — prompt text
+alone triggers nothing.
+
+- A **bare `/command` counts only at the start of the prompt**, so mid-sentence
+  slashes stay prose (`check /etc/hosts` is not a skill reference). The `%%…%%`
+  marker is also recognized anywhere — a web prompt pasted verbatim keeps its
+  token — but the skill **activates upstream only when the marker leads the
+  message**, so lead the prompt with it. The leading token can be any bare slug,
+  single-segment included — `/tmp what is this` resolves `/tmp` — and a
+  reference that matches nothing fails the turn with the catalog listed, so a
+  typo never silently degrades to a skill-less answer.
+- The catalog is fetched **only when the prompt references a skill**; skill-free
+  turns cost no extra request.
+- Unknown skills fail the turn with a non-zero exit before any session is
+  provisioned. A **disabled** skill is auto-enabled first — the same ADR-0001
+  behavior as the web's "Use in Chat" — because the upstream treats `enabled`
+  as a hard precondition for invocation and would otherwise download the
+  package and silently never run it. The enable flips the skill's `enabled`
+  flag on your account (a persistent change), is reported as
+  `Auto-enabled for this turn: …`, and a failed enable aborts the turn.
 
 ### Staging server (expired TLS certificate)
 
@@ -88,12 +187,13 @@ CLI skips TLS certificate verification **only while pointed at the staging
 host**; the server choice itself is the opt-in, and the default / CN hosts
 always verify. The interactive `msc login` region list shows each server's
 URL and marks Staging with the auto-off behavior; `msc login --region
-staging` and `MEDIA_STUDIO_API_URL=https://media.tool302.com` behave the
-same.
+staging` opts in.
 
-Stable (production) builds hide Staging from the `msc login` region menu, but
-a persisted staging `auth.json` still auto-bypasses TLS verification — this is
-intentional (the login persists across upgrades), not an oversight.
+Stable (production) builds hide Staging and Local from the `msc login` region
+menu and `--region`, but a persisted `auth.json` from a prerelease login keeps
+pointing at that server — and a staging one still auto-bypasses TLS
+verification. This is intentional (the login persists across upgrades), not an
+oversight.
 
 The whitelist is the only way the bypass turns on — no environment variable can
 extend it to another server, so production can never skip verification. To
@@ -188,7 +288,7 @@ bun remove -g @302ai/media-studio-cli
 bun run dev
 
 # terminal 2:
-msc login                     # browser SSO, or: msc login <JWT>
+msc login                     # browser sign-in
 msc whoami                    # verify auth state
 msc chat "画一只猫" -r        # real streaming turn
 msc chat "hi" --json
@@ -204,8 +304,8 @@ msc sessions use <id>         # switch default pointer locally
 msc sessions rm <id> -y       # delete session upstream (-y skips prompt)
 ```
 
-Without the local server, point at production:
-`MEDIA_STUDIO_API_URL=https://media.302.ai`.
+Without the local server, point at production with
+`msc login --region default`.
 
 ### Notes learned the hard way