monkeyscode-cli 1.1.9 → 1.1.11

package/README.md

@@ -18,7 +18,7 @@ curl -fsSL https://monkeyscode.com/cli/install.sh | bash
 # Windows (PowerShell)
 irm https://monkeyscode.com/cli/install.ps1 | iex
 
-# npm (Node 18+)
+# npm (Node 20+)
 npm install -g monkeyscode-cli
 ```
 
@@ -28,6 +28,46 @@ install script) as aliases. A Homebrew formula template lives in
 
 ## Usage
 
+### Core Skills onboarding
+
+```bash
+mc plugin core-skills                 # stage MonkeysCode/core-skills from the signed catalog
+mc plugin bootstrap                   # alias for core-skills
+mc plugin enable core-skills          # review capabilities, confirm version trust, then enable
+mc plugin core-skills --enable        # explicitly combine installation and normal enable review
+```
+
+Installation alone displays the capability report but does not enable skills or
+change existing profiles. `--enable`, `--scope user|project` and `--yes` use the
+existing plugin trust policy; `--yes` never bypasses managed approval. This is
+the same native pipeline as `mc plugin install MonkeysCode/core-skills`, for
+catalog-managed updates, not another injection of shared legacy app content.
+The packaged 24-definition library is declarative application content, not a
+signed plugin or a trust root. Catalog/API unavailability or verification failure
+fails closed: no unsigned local, packaged or git fallback. No automatic onboarding
+runs at CLI startup.
+
+### Public plugin discovery
+
+```bash
+mc plugin search [query] [--category <category>] [--app <app>] [--json]
+mc plugin info <author/name>
+mc plugin outdated [--json]
+mc plugin update <name>
+mc plugin update --all
+# Interactive: /plugins browse [query] [--category <category>] [--app <app>]
+```
+
+Discovery uses https://marketplace.monkeyscode.com by default; set
+`MONKEYSCODE_CATALOG_ORIGIN` to another public HTTPS origin, or to an empty
+value to turn discovery off.
+It sends no account credentials. Metadata is not package trust. Signing pins
+are provisioned independently with `MONKEYSCODE_PLUGIN_SIGNING_KEYS`; never
+accept keys learned from discovery as trust roots. Bulk updates do not treat
+`--yes` as approval for expanded capabilities; each expansion needs review.
+Managed-policy pending trust must be resolved before enabling.
+
+
 ```bash
 # Interactive REPL (optionally with a first prompt)
 mc
@@ -193,6 +233,49 @@ mc team status
 mc team merge team-abc123
 ```
 
+## Command-line Command Families
+
+These are the root registrations in `src/main.ts` (slash commands are a
+separate REPL interface). Run `mc --help`, `mc <family> --help`, and then
+`mc <family> <subcommand> --help` for exact arguments and nested flags.
+
+| Root command/family | Purpose |
+|---------------------|---------|
+| `mc auth` | Login, logout, token, status and refresh |
+| `mc status` | Account and agent status |
+| `mc doctor`, `mc setup` | Health checks and setup wizard |
+| `mc update`, `mc telemetry [action]`, `mc bug [description]` | Updates, telemetry and bug reports |
+| `mc config` | Layered settings, origins and migration |
+| `mc index [path]`, `mc context` | Workspace indexing and semantic retrieval |
+| `mc mcp` | Server configuration, approval, OAuth, browsing and serving tools |
+| `mc import <from>`, `mc plugin` | Import other tools' setups and manage plugins |
+| `mc agents`, `mc team`, `mc worktrees` | Agent dashboard, parallel teams and worktree lifecycle |
+| `mc triggers`, `mc schedule` | Event-driven triggers and scheduled runs |
+| `mc completions <shell>` | Shell completion scripts |
+| `mc sessions` | List, inspect, export, fork, delete and prune saved conversations |
+| `mc jobs` | Background job status, logs, cancellation, retry, diff and pull |
+| `mc cloud` | Persistent remote workspaces (distinct from one-shot jobs) |
+| `mc messages`, `mc join <sessionId>`, `mc share` | Cross-session messages and live collaboration |
+| `mc hooks`, `mc trust` | Lifecycle hooks and execution trust records |
+| `mc models`, `mc usage` | Model catalog/pricing and account or session usage |
+| `mc init`, `mc memory`, `mc rules`, `mc dream` | Project conventions and memory consolidation |
+| `mc review`, `mc bugfind [target]` | Code review and bug scanning |
+| `mc trace`, `mc benchmark` | Execution traces and benchmarks |
+| `mc marketplace`, `mc design` | Skill marketplace and local design artboard |
+| `mc ci` (hidden integration family) | GitHub Actions protocol helpers; used by the action |
+
+Root flags also include `--json-schema <file>`, `--append-system-prompt <text>`,
+`--system-prompt-file <file>`, `--settings <fileOrJson>`,
+`--ignore-repo-settings`, `--mcp-config <files...>`, `--strict-mcp-config`,
+`--add-dir <dirs...>` and the resume/fork and stdio permission flags described
+below. MCP config files passed explicitly are trusted for that run;
+`--strict-mcp-config` requires at least one such file. See `mc --help` and
+[headless](../../docs/cli/headless.md),
+[permissions](../../docs/cli/permissions.md) and
+[extensibility](../../docs/cli/extensibility.md) for constraints. Nested commands
+have their own options: for example, `mc sessions export --help` and
+`mc mcp serve --help` describe different output/permission flags than the root.
+
 ## Output Formats
 
 | Format | Use Case |
@@ -221,9 +304,20 @@ mc --effort high "find the race condition"            # low | medium | high
 
 In a session: Shift+Tab cycles `default` → `acceptEdits` → `plan`, `/plan` jumps to plan mode, `/effort high` changes
 effort from the next request, and `/permissions` lists every effective rule
-and the file it came from. Headless runs never prompt. A call that would
-prompt is denied and reported in `permissionDenials`. If *only* denials
-happened, the exit code is **6**.
+and the file it came from. Print/headless runs are non-interactive: they do
+not open TTY approval dialogs. By default, calls that would ask are denied
+and reported in `permissionDenials`. The explicit exception is
+`mc -p --permission-prompt stdio -o stream-json --input-format stream-json`: a
+protocol client sends user messages on stdin and answers `control_request`
+permission messages with `control_response` messages (not terminal input).
+See the [headless protocol](../../docs/cli/headless.md) for message shapes and timeouts.
+If *only* denials happened, the exit code is **6**.
+
+`--auto-approve`, bypass mode and background delegation are not blanket trust:
+explicit deny rules, protected/guarded operations and destructive-command
+checks still apply; these cannot be silently auto-approved. Prefer narrow
+allow rules for CI. Plugins and MCP tools remain subject to trust and
+permission checks, including when invoked by custom commands.
 
 The rule syntax, evaluation order and shell-command handling are in
 [docs/cli/permissions.md](../../docs/cli/permissions.md).
@@ -257,24 +351,168 @@ mc completions pwsh >> $PROFILE
 
 ## Slash Commands (REPL)
 
-| Command | Description |
-|---------|-------------|
-| `/help` | Show all commands |
-| `/clear` | Start a fresh conversation (the old one stays resumable); Ctrl+L only clears the screen |
-| `/model <name>` | Switch model |
-| `/plan` | Switch to plan (read-only) mode; Shift+Tab to cycle back |
-| `/effort [low\|medium\|high]` | Show or set reasoning effort |
-| `/permissions` | Show rules and their sources; `allow`/`deny`/`ask`/`remove` |
-| `/status` | Model, mode, effort, context and cost at a glance |
-| `/compact ["focus"]` | Summarise the conversation to free context |
-| `/diff` | Show session changes |
-| `/undo` | Revert the last turn's file changes |
-| `/commit [msg]` | Commit changes |
-| `/files` | List touched files |
-| `/cost [all]` | Session cost totals plus a per-turn breakdown |
-| `/vim` | Toggle Vim keybindings |
-| `/cloud` | Hand off to cloud |
-| `/context [file]` | Show context usage, or add a file to it |
+The 54 visible built-ins below follow the default registry and its full
+`usageOf(c)` strings. `/help` and the palette reflect the live registry.
+
+<!-- BEGIN SLASH COMMANDS -->
+### Session
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `/exit` | `/exit` | Exit the REPL |
+| `/clear` | `/clear` | Start a fresh conversation; the old one stays resumable (Ctrl+L only clears the screen) |
+| `/sessions` | `/sessions` | List saved sessions |
+| `/resume` | `/resume [id]` | Resume a saved session |
+| `/vim` | `/vim` | Toggle Vim keybindings in the composer |
+| `/logout` | `/logout` | Sign out and exit |
+| `/copy` | `/copy [n]` | Copy the last reply (or the n-th last) |
+| `/export` | `/export [file]` | Save the conversation as Markdown |
+| `/rewind` | `/rewind` | Roll back conversation and files to an earlier prompt (Esc Esc) |
+
+### Model & Mode
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `/model` | `/model [id]` | Show or switch the model |
+| `/mode` | `/mode <plan\|fast\|thinking>` | Switch legacy mode; prefer effort for fast/thinking |
+| `/plan` | `/plan` | Research and propose without edits |
+| `/ask` | `/ask` | Read-only Q&A about the codebase |
+| `/effort` | `/effort [low\|medium\|high\|default]` | Show or set reasoning effort |
+| `/output-style` | `/output-style [name] [--save]` | Show or switch output style |
+
+### Context & Stats
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `/cost` | `/cost [all]` | Session token usage and cost, per turn |
+| `/context` | `/context [file]` | Show context usage or add a file |
+| `/compact` | `/compact ["focus"]` | Compact the conversation to free context |
+| `/status` | `/status` | Model, permissions, effort, MCP and usage |
+
+### Git & Files
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `/files` | `/files` | List files read and modified this session |
+| `/diff` | `/diff [session\|staged] [--plain]` | Open Diff; --plain prints git diff |
+| `/undo` | `/undo [--force]` | Revert the last turn's file changes; keep conversation |
+| `/redo` | `/redo [--force]` | Re-apply changes reverted by undo |
+| `/commit` | `/commit [message]` | Stage everything and commit |
+| `/review` | `/review [staged\|session\|<path>] [--chat]` | Open Code Review or review in chat |
+
+### Agents & Delegation
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `/agents` | `/agents [create <name> ["purpose"] \| edit <name> \| run <name> <task>]` | List, create, edit or run custom subagents |
+| `/goal` | `/goal "target" \| /goal status \| /goal cancel` | Autonomous plan → execute → verify loop |
+| `/loop` | `/loop [iterations] "command"` | Iterate until a command passes |
+| `/subtask` | `/subtask "task" \| /subtask status \| /subtask cancel <id>` | Spawn or manage isolated background subtasks |
+| `/fork` | `/fork "task"` | Isolated background task; no conversation inherited |
+| `/delegate` | `/delegate "task 1" "task 2" [...]` | Parallel agents and merged results |
+| `/search` | `/search "query"` | Web search via the agent |
+| `/docs` | `/docs <topic>` | Look up documentation |
+
+### Skills, Hooks & Permissions
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `/permissions` | `/permissions [show \| allow\|deny\|ask <rule> [--project] \| remove <rule> \| edit]` | Effective rules and origins; add or remove rules |
+| `/add-dir` | `/add-dir <path> [--save]` | Allow another directory this session |
+| `/skill` | `/skill [create <name>]` | List or create skills |
+| `/hooks` | `/hooks [create <name>]` | List or create hooks |
+| `/trust` | `/trust [revoke]` | Review and trust workspace hooks/status line |
+| `/setup` | `/setup [step]` | Setup wizard |
+| `/terminal-setup` | `/terminal-setup` | Configure Shift+Enter and Option-as-Meta |
+| `/shells` | `/shells [id \| kill <id\|all>]` | List, inspect or stop background shells |
+| `/mcp` | `/mcp [tools\|approve\|reconnect\|disable\|enable] [server]` | Inspect/control session MCP servers |
+| `/plugins` | `/plugins [list \| browse [query] \| install <author>/<name>[@version] [--enable] \| info <name> \| enable <name> \| disable <name> \| update <name> \| rollback <name> \| remove <name> \| reload]` | Find, install, review, enable, update and remove plugins without leaving the session. `enable` on a new plugin shows its capabilities and asks before trusting it; `disable` is session-only |
+
+### Project & Memory
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `/init` | `/init` | Initialize rules, permissions, skills and hooks |
+| `/memory` | `/memory [show\|add [--user] "rule"\|edit [project\|user\|local]]` | Show memory, add rules or edit a memory file |
+
+### Cloud & Messaging
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `/cloud` | `/cloud` | Hand current task off to a hosted cloud job |
+| `/message` | `/message <session-id> "text"` | Message another session |
+| `/broadcast` | `/broadcast "text"` | Message all active sessions |
+
+### Info & Help
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `/bug` | `/bug` | Diagnostic context for a bug report |
+| `/doctor` | `/doctor` | System health check |
+| `/config` | `/config [key [value]]` | Show/change user settings |
+| `/update` | `/update [check]` | Check for or install updates |
+| `/help` | `/help` | Show live help |
+
+### Custom (project, user, plugins, MCP)
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `/commands` | `/commands [reload]` | List and reload custom commands |
+
+**Aliases** — each row maps every registered alias to its canonical command
+(name without the leading slash). Aliases accept the same arguments and are
+not additional built-ins.
+
+| Canonical name | Aliases |
+|----------------|---------|
+| `exit` | `/quit`, `/q` |
+| `clear` | `/cls`, `/new` |
+| `resume` | `/continue` |
+| `model` | `/models` |
+| `output-style` | `/style` |
+| `context` | `/ctx` |
+| `subtask` | `/sub` |
+| `delegate` | `/del` |
+| `permissions` | `/allowed-tools` |
+| `skill` | `/skills` |
+| `hooks` | `/hook` |
+| `shells` | `/bashes`, `/bg` |
+| `plugins` | `/plugin` (legacy alias until the next release) |
+| `bug` | `/feedback` |
+| `config` | `/settings` |
+| `update` | `/upgrade` |
+| `help` | `/h`, `/?` |
+<!-- END SLASH COMMANDS -->
+
+Aliases (for example `/h`, `/quit`, `/ctx`, `/models`, `/skills`, `/plugin`)
+resolve to their primary commands, not additional built-ins. Project/user
+Markdown commands, enabled plugins and connected MCP prompts can add dynamic
+entries; `/help` shows their sources and name conflicts (built-ins win).
+Use `/commands reload` after editing command files and `/plugins reload` to
+refresh extensions. Custom command shell expansions and their tool scopes
+remain permission-gated; enabling a plugin does not bypass MCP trust or tool rules.
+
+`/plugins` defaults to `list`; `browse` searches the configured public catalog
+(default app: `cli`; `--app` accepts `ide`, `agent` or `cli`).
+`info <name>` shows capabilities and version trust,
+and `reload` refreshes extensions. `enable <name>` and `disable <name>` change
+only the current session, never persistent settings or trust. Install and review
+version-pinned trust explicitly with `mc plugin install` and `mc plugin enable`;
+no slash command automatically grants trust. `/plugin` is the legacy Markdown
+command alias until the next release; migrate examples to `/plugins`.
+
+Local authoring commands are `mc plugin init [dir]`, `mc plugin validate [dir]`
+and `mc plugin migrate-skills <from> <to>` (copies skills without changing
+originals or granting trust). `mc plugin remove <name>` also accepts
+`mc plugin uninstall <name>`. Catalog discovery uses https://marketplace.monkeyscode.com unless
+`MONKEYSCODE_CATALOG_ORIGIN` overrides it; an empty value reports
+unavailability rather than sending a remote request. Plugin publishing remains unavailable until Phase 6.
+
+**Two different kinds of fork:** `/fork "task"` starts an isolated background
+task without inheriting conversation history. `mc sessions fork <id>` copies
+a saved conversation to a new id. `mc -r <id> --fork-session` (or
+`mc -c --fork-session`) resumes history in a new session, leaving the original
+untouched; it is not a background task.
 
 Type `/` to open the commands menu: it filters as you type and shows 5 rows
 at a time (↑↓ move, PgUp/PgDn jump, Tab completes, Enter runs the
@@ -292,11 +530,13 @@ and context size, and Enter switches to the highlighted one.
 | Ctrl+] | Next tab (works in every terminal) |
 
 The ⌥ keys work with your terminal's default settings (Terminal.app, iTerm2,
-VS Code, kitty, WezTerm, Ghostty, Windows Terminal). On Diff and Code Review
-you can also click a tab and scroll with the wheel; hold Shift (⌥ in iTerm2
-and Terminal.app) while dragging to select text there. Set `mouse` to `all`
-to click the Chat footer as well (the wheel then stops scrolling the chat
-history), or to `off` to turn the mouse off.
+VS Code, kitty, WezTerm, Ghostty, Windows Terminal). You can click a tab and
+scroll with the wheel in every tab: the wheel scrolls whichever pane is under
+the pointer (chat history, the Changes column, Diff, Code Review). Hold Shift
+(⌥ in iTerm2 and Terminal.app) while dragging to select text, or use `/copy`
+for the last answer. Set `mouse` to `tabs` to keep the mouse to Diff / Code
+Review (plain drag selects in Chat, but the wheel no longer scrolls it), or to
+`off` to turn the mouse off.
 
 **In-app chat scrolling:** The chat viewport is internally scrollable — the
 composer and status line stay fixed while you navigate history. Use the mouse
@@ -304,6 +544,11 @@ wheel, PageUp/PageDown, or Ctrl+G to jump to the latest. Scrolling anchors
 survive streaming, tab switches, and terminal resizes. A "new output"
 indicator appears when you're scrolled up during a run.
 
+**Changes column:** on terminals 120 columns or wider, the chat shows the
+session's changed files and their diffs on the right. Ctrl+F focuses it (←/→
+file, ↑/↓ or the wheel to scroll), Ctrl+Y hides or shows it, and
+`changesPane: false` starts without it. `/diff` opens the full Diff tab.
+
 **Multi-line input:** Press **Shift+Enter** for a newline (or **Alt+Enter**,
 or end a line with `\`). Enter sends the message. Run `mc setup` to configure
 your terminal for distinguishable Shift+Enter if it isn't already.