command-code 1.87.0 → 1.87.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # command-code
 
+## 1.87.2
+
+### Patch Changes
+
+- fix: cmd acp can load --mod and mod options
+- fix: invalid reasoning effort no longer fails every request.
+- fix: stop re-setting the process name every 5 seconds, which on macOS made each open session trigger a LaunchServices check-in every 5s and drove `launchservicesd` CPU up with many sessions open
+- fix: show the provider's real error message (e.g. "Overloaded") when a stream fails mid-flight instead of "Stream failed: [object Object]" / "Connection error"
+
+## 1.87.1
+
+### Patch Changes
+
+- fix: warn and exit instead of crashing when the disk is full
+- fix: sub agent token count display in feed
+
 ## 1.87.0
 
 ### Minor Changes

package/dist/bundled/command-code-knowledge/reference/headless.md

@@ -30,6 +30,44 @@ Always wrap your query in quotes. Unquoted multi-word queries cause argument par
 
 ---
 
+## Authentication
+
+On your own machine, `cmd login` once and headless runs reuse that login. For non-interactive environments (CI pipelines, Docker images, scheduled jobs, SSH boxes without a browser), [create an API key](https://commandcode.ai/docs/studio#api-keys) and export it as the `COMMAND_CODE_API_KEY` environment variable. The CLI reads the env var at startup and uses it as the auth token. No need to run `cmd login` or pre-write an `auth.json` file.
+
+**Set the API key**
+
+```bash {{ title: 'macOS / Linux' }}
+export COMMAND_CODE_API_KEY=""  # add your API key here
+cmd -p "Run my workflow"        # already logged in
+```
+
+```bash {{ title: 'Windows' }}
+$env:COMMAND_CODE_API_KEY = ""  # PowerShell: add your API key here
+cmdc -p "Run my workflow"       # already logged in
+```
+
+The env var takes precedence over `~/.commandcode/auth.json`. It overrides any local authentication method.
+
+Run `cmd status` to confirm. The output shows `Source: $COMMAND_CODE_API_KEY` when the env var is the active credential.
+
+### GitHub Actions
+
+Store the key as a repository secret and pass it through `env`:
+
+```yaml
+- name: Install Command Code
+  run: npm i -g command-code@latest
+
+- name: Run Command Code
+  run: cmd -p "review the changes in this PR"
+  env:
+    COMMAND_CODE_API_KEY: ${{ secrets.COMMAND_CODE_API_KEY }}
+```
+
+Treat the key as a secret: use your CI provider's encrypted-secrets store (GitHub Actions secrets, GitLab CI variables, etc.) rather than committing it to the repo.
+
+---
+
 ## Input methods
 
 ### Direct argument
@@ -66,7 +104,7 @@ To enable all tools, pass `--yolo`:
 cmd -p "fix the lint errors" --yolo
 ```
 
-> `--dangerously-skip-permissions` is also accepted as an alias.
+> `--dangerously-skip-permissions` is also accepted as an alias. `--permission-mode yolo` does not lift the block in headless mode. Pass `--yolo`.
 
 | **Tool** | **Default (no flag)** | **With `--yolo`** |
 | -------- | --------------------- | ----------------------------------------- |

package/dist/bundled/command-code-knowledge/reference/models.md

@@ -27,12 +27,10 @@ The model catalog — every id `/model`, `--model`, `model:effort` shorthand, an
 | `zai-org/GLM-5.1` | GLM-5.1 | — | — | $1.4/$4.4 · cache $0.26 | Go and above | long-horizon autonomous coding agent |
 | `zai-org/GLM-5` | GLM-5 | 200K | — | $1/$3.2 · cache $0.2 | Go and above | multi-mode thinking & long-range planning |
 | `minimax/minimax-m3.1-flash` | MiniMax M3.1 Flash | 1M | low, medium, high, xhigh, max | $0.15/$0.6 · cache $0.015 | Go and above | multimodal coding with tunable thinking depth |
-| `minimax/minimax-m3.1-flash:free` | MiniMax M3.1 Flash | 1M | low, medium, high, xhigh, max | $0/$0 · cache $0 | Go and above | multimodal coding with tunable thinking depth |
 | `MiniMaxAI/MiniMax-M3` | MiniMax M3 | 1M | low, medium, high | $0.3/$1.2 · cache $0.06 | Go and above | frontier coding, agents & native multimodality |
 | `MiniMaxAI/MiniMax-M2.7` | MiniMax M2.7 | — | — | $0.3/$1.2 · cache $0.06 | Go and above | end-to-end software engineering agent |
 | `MiniMaxAI/MiniMax-M2.5` | MiniMax M2.5 | 200K | — | $0.3/$1.2 · cache $0.03 | Go and above | cross-platform full-stack agentic dev |
 | `ornith/ornith-1.5-122b` | Ornith 1.5 122B | 262K | — | $0.16/$0.64 · cache $0.02 | Go and above | open-weight MoE for fast agentic coding |
-| `ornith/ornith-1.5-122b:free` | Ornith 1.5 122B | 262K | — | $0/$0 · cache $0 | Go and above | open-weight MoE for fast agentic coding |
 | `xiaomi/mimo-v2.6-pro` | MiMo V2.6 Pro | 1.05M | — | $0.435/$0.87 · cache $0.0036 | Go and above | flagship multimodal agentic coding with 1M context |
 | `xiaomi/mimo-v2.6-pro-ultraspeed` | MiMo V2.6 Pro UltraSpeed | 1.05M | — | $4.35/$8.7 · cache $0.036 | GOAT and above | low-latency serving tier of MiMo V2.6 Pro |
 | `xiaomi/mimo-v2.6-flash` | MiMo V2.6 Flash | 1.05M | — | $0.14/$0.28 · cache $0.0028 | Go and above | efficient multimodal agentic coding with 1M context |

package/dist/bundled/command-code-knowledge/reference/permissions.md

@@ -140,7 +140,9 @@ cmd --plan                          # start in plan mode
 cmd --yolo                          # yolo (permission bypass) - alias for --dangerously-skip-permissions; use with care
 ```
 
-`--permission-mode` wins over `--plan`. `--permission-mode yolo` starts in permission bypass, same as `--yolo` / `--dangerously-skip-permissions`; the `disableBypass` kill switch covers all three.
+`--permission-mode` wins over `--plan`. In an interactive session, `--permission-mode yolo` starts in permission bypass, same as `--yolo` / `--dangerously-skip-permissions`; the `disableBypass` kill switch covers all three.
+
+Print mode (`-p`) is different. It blocks file writes, file edits, and shell commands unless you pass `--yolo` or `--dangerously-skip-permissions`. `--permission-mode yolo` sets the mode but does not lift that block, so a headless run that needs to change files takes `--yolo`. See [headless permissions](./headless.md#permissions).
 
 A mode switch also answers a prompt already on screen: `accept-edits` or `yolo` **approves** it (you said "stop asking"); `plan` **denies** it. A safety-forced prompt - destructive command, sensitive file, explicit `ask` rule - is never answered this way; it stays put for an explicit yes/no.
 

package/dist/bundled/command-code-knowledge/reference/tools.md

@@ -367,7 +367,7 @@ A client-side URL guard rejects credentials-in-URL, private/loopback/link-local
 
 ## Artifacts
 
-`artifact_publish` and `artifact_manage` publish an HTML page as a link to open and share. Their parameters are on [Artifact tools](https://commandcode.ai/docs/artifacts/tools).
+`artifact_publish` and `artifact_manage` publish an HTML page as a link to open and share. Their parameters are on [Artifacts](https://commandcode.ai/docs/artifacts#tools).
 
 ---
 

package/dist/bundled/mod-builder/SKILL.md

@@ -23,7 +23,7 @@ Two resources ship next to this file — use them instead of searching the codeb
 - `reference/api.md` — ModApi reference
 - `reference/hooks-and-events.md` — Hooks and events
 - `reference/ui.md` — UI surface
-- `reference/packaging.md` — Packaging and install
+- `reference/packaging.md` — Install and share mods
 - `reference/verify.md` — Verify a mod
 <!-- generated:reference-index:end -->
 

package/dist/bundled/mod-builder/reference/api.md

@@ -22,7 +22,9 @@
 | `cmd.process` | `ModProcessApi` | `spawn` - run a process and stream its output as it arrives |
 | `cmd.audio` | `ModAudioApi` | `play` / `bell` - sound files shipped with the mod, and the terminal bell |
 
-## Registration (factory-time; each returns `Disposable`)
+## Registration methods
+
+Call these while the mod's factory runs. Each one returns a `Disposable`.
 
 | Method | Signature |
 |---|---|
@@ -50,9 +52,11 @@ What each does:
 - `cmd.addAgent(definition)` - a sub-agent type the model can delegate to through the `task` tool, next to the bundled and on-disk agents. `tools` defaults to `'*'`. An agent name that already exists (bundled, project, user, or another mod's) is skipped with a warning. Read live, so a reload's agents show up on the next turn.
 - `cmd.expose(name, fn)` / `cmd.use(mod, name)` - share a function with other mods and call one another mod shared. `use` answers `undefined` until that mod has loaded and exposed the name, so call it from a hook or command, not only at factory time.
 - `cmd.addShortcut(keys, {description, handler})` - a keyboard shortcut in the interactive TUI. `keys` is a `modifier+key` chord that **must include Ctrl or Alt** (`alt+r`, `ctrl+r`); a modifier-less or Shift-only chord (`p`, `enter`, `shift+p`) is rejected with a warning, because it would also type into the prompt, and so is a `Ctrl+Shift` chord whose key reaches the terminal as a bare control byte — letters, digits, Enter, Tab, Backspace (`ctrl+shift+p`, `ctrl+shift+enter`) — where the Shift never arrives (arrow / navigation keys keep their modifiers, so `ctrl+shift+up` is fine). `ctrl+m`, `ctrl+i`, `ctrl+h` and `ctrl+[` are rejected too: terminals send them as Enter, Tab, Backspace and Escape. A chord a built-in already owns (`ctrl+c`, `ctrl+o`, an editor key like `ctrl+k`) is rejected the same way — the host's own bindings run first, so it would never fire — and so are the keys the prompt handles itself (`alt+w`, `ctrl+z`, `ctrl+g`, `ctrl+s`, `ctrl+v`, `alt+v`), which stay taken even when rebound. The handler gets the same `{args, ui, cwd, exec}` context a command handler does and may return the same `{message}` / `{prompt}` result. The host dispatches mod shortcuts AFTER its own bindings, so a mod can add keys but never shadow interrupt, exit, mode cycling, or the transcript toggles; `Esc` stays host-owned. First registration per chord wins across mods; `/hotkeys` lists them under **Mods**. Headless hosts never fire shortcuts.
-- `cmd.addSkillsPath(path)` - an extra skills location (one skill directory, or a directory of skills) for this session's skill discovery. Relative paths resolve against the mod's own file, so a package can point at the `./skills` it ships. Collected at factory time. A package can declare the same thing without code through its manifest - see [What a package ships](./packaging.md#what-a-package-ships).
+- `cmd.addSkillsPath(path)` - an extra skills location (one skill directory, or a directory of skills) for this session's skill discovery. Relative paths resolve against the mod's own file, so a package can point at the `./skills` it ships. Collected at factory time. A package can declare the same thing without code through its manifest - see [Turn a mod into a package](./packaging.md#turn-a-mod-into-a-package).
+
+## Live methods
 
-## Live methods (any time after the harness binds)
+These work any time after the harness binds to the mod host.
 
 | Method | Signature |
 |---|---|
@@ -92,7 +96,7 @@ Details:
 - `cmd.isIdle()` - `false` while an agent run is in flight on the bound harness (`run_start` … `run_end`), `true` otherwise and pre-bind.
 - `cmd.shutdown()` - asks the interactive host to exit once the current turn settles (the same path as `/exit`). Headless: no-op - the print run ends on its own.
 - `cmd.getToolInfo()` - the registered tools with `description`, `readOnly`, and `active` (per the mod-managed filter) - the descriptive counterpart of `getAllTools()`'s bare names.
-- `cmd.session` - the `ModSessionApi` persistence seam (appendCustomEntry / appendCustomMessageEntry / getCustomEntries), undefined until bound. See [ModContext.session - the mods' persistence surface](./hooks-and-events.md#mod-context-session-the-mods-persistence-surface).
+- `cmd.session` - the `ModSessionApi` persistence seam (appendCustomEntry / appendCustomMessageEntry / getCustomEntries), undefined until bound. See [ModContext.session - the mods' persistence surface](./hooks-and-events.md#mod-context-session-saved-mod-data).
 - `cmd.showEntry(customType, data)` - render a custom entry into the live feed through the renderer registered for that type (unrendered types pretty-print as JSON). The TUI wires the sink; headless runs drop entries. Pair with `cmd.session.appendCustomEntry` when the data should also persist.
 - `cmd.sessions` - live session controls: `compact()`, `tree()` (the session branch tree as stable `{id, label, children}` nodes), `leafId()`, `navigateTree({targetId, summarize?, customInstructions?})`, and `setLabel({targetId, label})`. These read live harness state, so unlike the buffered setters they throw with a clear message when no session is bound yet.
 - `cmd.exec({command, args})` - run a process through the harness Runtime (args are shell-quoted).
@@ -107,7 +111,9 @@ Details:
 - `cmd.ui.copy(text)` - write text to the system clipboard with the same helper `/copy` uses. See [Clipboard and sound](./ui.md#clipboard-and-sound).
 - `cmd.audio.play({file})` / `cmd.audio.bell()` - play a sound file shipped with the mod, or ring the terminal bell. See [Clipboard and sound](./ui.md#clipboard-and-sound).
 
-## `ModHooks` (the mutating lifecycle - all optional, all composable)
+## `ModHooks`: hooks that change behavior
+
+Every hook is optional, and hooks from several `cmd.hooks()` calls compose.
 
 `transformContext`, `appendSystemPrompt`, `transformSystemPrompt`, `transformMessage`, `transformTextDelta`, `beforeModelRequest`, `beforeToolCall`, `afterToolCall`, `onTurnStart`, `onTurnEnd`, `shouldStopAfterTurn`, `prepareNextTurn`, `onRunEnd`, `onStop`, plus the host-level `transformInput`, `onPermissionRequest`, `onSessionStart`, and `onSessionEnd`.
 

package/dist/bundled/mod-builder/reference/hooks-and-events.md

@@ -6,7 +6,7 @@ The harness's extension seam. A **mod** is a plain object of lifecycle hooks tha
 
 A mod may also contribute **tools**, and every hook receives a **`ModContext`** (`{emit, signal, cwd, session?}`) as an extra last argument, so a mod can raise its own events and persist durable state without extra plumbing.
 
-## Lifecycle - where each hook fires
+## Where each hook fires
 
 One `run()` = one user turn → many model turns ("rounds"). The loop below is the agent loop, verbatim in ordering; mod hooks are marked `◆`, events `→`.
 
@@ -199,7 +199,7 @@ const persistUntilTestsPass = {
 };
 ```
 
-## `ModContext.session` - the mods' persistence surface
+## `ModContext.session`: saved mod data
 
 The harness's tree-format session store gives mods a durable, per-entry seam onto the SAME append-only file the transcript lives in. Available in a loadable mod as `cmd.session` and inside hooks as `ctx.session`. Two entry kinds:
 
@@ -276,7 +276,7 @@ One sync sink, fan out with `createEventBus`. Payloads are snapshots - never liv
 | `interrupted` | abort observed | - |
 | `run_error` | non-retryable failure | the raw `Error` |
 
-## Worked example - a write-quota mod
+## Example: a write quota mod
 
 Blocks writes outside an allowlist, counts tool activity durably in modState, and reports at run end. Exercises the block channel, the closure-vs-modState split, and `onRunEnd`.
 

package/dist/bundled/mod-builder/reference/overview.md

@@ -164,7 +164,7 @@ It loads on the next session (or `cmd --mod ./review-guard.ts` to try it without
 | `~/.commandcode/mods/<dir>/` | user | `package.json` manifest → `mods/` dir → `index.ts` |
 | `<project>/.commandcode/mods/…` | project | same layout; loads only once the workspace is trusted |
 | settings `mods.paths` | user/project | explicit files/dirs, relative to the settings scope |
-| settings `mods.sources` | user/project | installed packages (see [Packaging and install](./packaging.md#packaging-and-install)) |
+| settings `mods.sources` | user/project | installed packages (see [Install and share mods](./packaging.md#install-and-share-mods)) |
 | `--mod <path>` | session | repeatable; loads ahead of installed, wins name collisions |
 
 Dot-entries and `node_modules` are never scanned (the package registry lives under `mods/.registry/` precisely so discovery skips it). Duplicate mod names keep the first and warn. Disable without deleting via settings:
@@ -200,7 +200,7 @@ Some built-ins are **opt-in** and are disabled by default; `cmd mods list --buil
 {"mods": {"enabled": ["todos"]}}
 ```
 
-`cmd mods disable <name>` disables the mod. A disable in any settings file wins and keeps the mod disabled. The change takes effect on the next session or `/reload`; see [Enable/Disable a mod](https://commandcode.ai/docs/mods#enabledisable-a-mod).
+`cmd mods disable <name>` disables the mod. A disable in any settings file wins and keeps the mod disabled. The change takes effect on the next session or `/reload`; see [Turn a mod on or off](./packaging.md#turn-a-mod-on-or-off).
 
 Built-in mods always win a name collision against a discovered mod of the same name (the loader shadows the file with a warning), and they are compiled in - never jiti-loaded from a writable path, so they are not supply-chain surface. Structural harness mods (workspace, compaction, checkpoints) are load-bearing for correctness and stay unconditional; only the observer-style built-ins above are disable-able.
 
@@ -239,7 +239,9 @@ Ask for any of these by name or by what you want:
 
 ---
 
-## Boundaries (deliberate)
+## What mods cannot do
+
+These limits are deliberate.
 
 - **Hooks mutate, `on` observes.** Event handlers cannot block tools or rewrite context; that is what `cmd.hooks` is for.
 - **Project mods are trust-gated** like project skills: they load only after the workspace trust prompt, because a mod is arbitrary code. User-scope and `--mod` mods always load. There is no sandbox - install packages you trust. Package installs run npm with `--ignore-scripts` (mods are jiti-loaded TypeScript; they need no build step, so lifecycle scripts are pure attack surface).
@@ -255,12 +257,13 @@ Embedders wire the same machinery directly: `createModHost` + `loadMods` + `crea
 
 ---
 
-## The reference sections
+## Reference overview
 
 The rest of this page is the complete reference, in order:
 
 - [ModApi reference](./api.md#mod-api-reference): every field, registration verb, and live method.
 - [Hooks and events](./hooks-and-events.md#hooks-and-events): the mutating lifecycle, the `AgentEvent` catalog.
 - [UI surface](./ui.md#ui-surface): dialogs, footer status, editor widgets, custom feed rendering.
-- [Packaging and install](./packaging.md#packaging-and-install): `cmd mods add`, manifests, filtering, scopes.
+- [Install and share mods](./packaging.md#install-and-share-mods): `cmd mods add`, packages, filtering, turning mods on and off.
+- [Listing a mod on the mods hub](./packaging.md#listing-a-mod-on-the-mods-hub): get your mod on the Command Code mods hub.
 - [Verify a mod](./verify.md#verify-a-mod): load it, list it, test it, ship it.

package/dist/bundled/mod-builder/reference/packaging.md

@@ -1,28 +1,28 @@
 <!-- Generated from the Command Code docs: https://commandcode.ai/docs -->
 
-# Packaging and install
+# Install and share mods
 
-A mod starts life as a loose file in `~/.commandcode/mods/`. When it should be shared - with a team, or the world - it becomes a **package**: an npm package, a git repo, or a local directory that `cmd mods add` installs and Command Code loads on every session.
+A mod starts as a single file in `~/.commandcode/mods/`. To share it with your team or anyone else, turn it into a **package**: an npm package, a git repo, or a local folder. `cmd mods add` installs a package, and Command Code loads it in every session after that.
 
-## Install, remove, list, update, open
+## Manage mods from the CLI
 
 ```bash
-cmd mods add cmd-mod-hi                     # bare name = npm package
-cmd mods add @team/review-mod@1.2.0         # scoped npm name, pinned (npm: prefix optional)
-cmd mods add owner/repo@v1                  # GitHub shorthand (any git host via git:<host>/…)
-cmd mods add ./tools/local-mod              # local path, referenced in place
-cmd mods add -g owner/repo                  # user scope instead of project
-cmd mods list                               # alias: cmd mods ls
-cmd mods update                             # reinstall missing, reconcile pinned refs (alias: up)
-cmd mods remove owner/repo                  # alias: cmd mods rm
-cmd mods remove fun-stuff                   # by the name `mods list` prints
-cmd mods enable <name>                      # enable a mod; -g for user level
-cmd mods disable <name>                     # disable a mod; -g for user level
-cmd mods open                               # open the mods dir (project); --user for ~
-cmd mods inspect ./some-mod                 # what it hooks, registers, and reaches (never runs it)
+cmd mods add cmd-mod-hi                     # npm package (a bare name means npm)
+cmd mods add @team/review-mod@1.2.0         # scoped npm package, pinned to a version
+cmd mods add owner/repo@v1                  # GitHub repo (other hosts: git:<host>/…)
+cmd mods add ./tools/local-mod              # local folder, used where it is
+cmd mods add -g owner/repo                  # install for your user instead of this project
+cmd mods list                               # list installed mods (alias: ls)
+cmd mods update                             # install anything missing, refresh pinned refs (alias: up)
+cmd mods remove owner/repo                  # remove by source (alias: rm)
+cmd mods remove fun-stuff                   # or by the name `mods list` prints
+cmd mods enable <name>                      # turn a mod on; -g for your user
+cmd mods disable <name>                     # turn a mod off; -g for your user
+cmd mods open                               # open this project's mods folder; --user for yours
+cmd mods inspect ./some-mod                 # show what a mod hooks and reaches, without running it
 ```
 
-`cmd mods list` prints one line per mod - name, scope, origin - project mods first, then user, then package-provided:
+`cmd mods list` prints one line per mod: its name, its scope, and where it comes from. Project mods come first, then user mods, then mods from packages.
 
 ```
 Mods (2)
@@ -30,17 +30,28 @@ Mods (2)
   cmd-mod-hi · user · from npm:cmd-mod-hi
 ```
 
-The origin is the file for a drop-in mod and `from <source>` for a package mod (whose file lives under `.registry/`, which you never edit by hand). Built-in mods are Command Code's own internals and are never listed. Configured package sources stay out of the output entirely unless one needs attention - not installed, or installed but contributing no mods.
+A mod you dropped in shows its file. A mod from a package shows `from <source>`; its files live under `.registry/`, which you never edit by hand. Built-in mods are not listed. A package source only appears when it needs attention: it is not installed yet, or it installed but added no mods.
 
-`remove` (`rm`) takes **either** a source or the mod NAME `cmd mods list` prints, and removes whatever backs that name: a drop-in file or directory is deleted from the mods dir, a package-provided mod removes its source (and says which sibling mods went with it), a `mods.paths` mod drops its settings entry. Scope follows where the mod actually lives, so a user-scope mod does not need `-g`; a source that is configured in neither scope reports that instead of a silent success.
+**Removing.** `cmd mods remove` takes either a source or a mod name from `cmd mods list`, and removes whatever provides it:
 
-`cmd mods open` opens the drop-in mods directory - `<project>/.commandcode/mods` by default, `~/.commandcode/mods` with `--user` (`-g`) - creating it if it does not exist yet. `--path` prints the directory instead of opening it.
+- a dropped-in file or folder is deleted from the mods folder;
+- a mod from a package removes that package, and tells you which other mods went with it;
+- a `mods.paths` mod has its settings entry removed.
 
-A source with no slash is an npm package name, and so is a `@scope/name` - git shorthand always carries an `owner/repo` slash, so `npm:` is optional (an explicit `git:` prefix always wins). Sources persist in the `mods.sources` settings key (project scope writes `.commandcode/settings.json`, `-g` writes `~/.commandcode/settings.json`). Identity is version/ref-agnostic - `owner/repo@v1` and `https://github.com/owner/repo` are the same package, and a project entry shadows the same identity at user scope. Installs land in `<scope>/.commandcode/mods/.registry/{npm,git}/…`; startup never runs npm/git on its own - a configured-but-missing package is a warning pointing at `cmd mods update`.
+It finds the right scope on its own, so a user mod does not need `-g`. If the source is not installed in either scope, it tells you so.
 
-## What a package ships
+**Opening the folder.** `cmd mods open` opens `<project>/.commandcode/mods`, or `~/.commandcode/mods` with `--user` (`-g`), and creates it if needed. `--path` prints the folder instead of opening it.
 
-A package declares what it ships via `package.json` - exact paths, directories, or globs (expanded against the package root; entries escaping the root are dropped):
+**How sources are read and saved.**
+
+- A source without a slash, or a `@scope/name`, is an npm package, so the `npm:` prefix is optional. A `git:` prefix always means git.
+- Sources are saved in the `mods.sources` settings key: `.commandcode/settings.json` for the project, `~/.commandcode/settings.json` with `-g`.
+- Versions and refs do not change what a source is: `owner/repo@v1` and `https://github.com/owner/repo` are the same package. A project entry takes priority over the same package at the user level.
+- Packages install into `<scope>/.commandcode/mods/.registry/{npm,git}/…`. Startup never runs npm or git by itself. A package that is configured but not installed shows a warning that points at `cmd mods update`.
+
+## Turn a mod into a package
+
+List what the package contains in `package.json`. Entries can be exact paths, folders, or globs, relative to the package root. Entries that point outside the root are ignored.
 
 ```json
 {
@@ -55,55 +66,15 @@ A package declares what it ships via `package.json` - exact paths, directories,
 }
 ```
 
-Include the `cmd-mod` keyword so maintainers can find the package during review.
-Kind keywords such as `cmd-mod-tool` and `cmd-mod-hook` help describe it, but the
-hub's categories and summary come from its reviewed registry entry. Publishing
-to npm does not list a package on the [mods hub](https://commandcode.ai/mods).
-
-No manifest → the `mods/` convention directory → a root `index.ts`, in that order.
-
-`commandcode.skills` lists skill directories the package ships beside its mods (each entry is one skill directory or a directory of skills, relative to the package root; entries escaping the root are dropped). They join skill discovery for every session the package loads in, so one `cmd mods add` brings the mods and the skills that go with them. A mod can contribute the same thing from code with `cmd.addSkillsPath`.
-
-After publishing, submit an entry to the public registry for review. Listed npm
-packages get live monthly downloads, latest version, and publish date from npm.
-A GitHub `repo` in the registry entry adds its star count.
-
-## Listing a mod on the hub
-
-The [hub](https://commandcode.ai/mods) lists the reviewed entries in
-`mods/registry.json` in the public
-[`CommandCodeAI/command-code`](https://github.com/CommandCodeAI/command-code) repo.
-Open a PR against that file for either an npm or a GitHub mod. Maintainers review
-npm candidates before adding them to the list. The hub automatically fetches
-GitHub entries and approved npm entries from this file within about 15 minutes
-of a merge, without a website deployment.
-
-```json
-{
-	"version": 1,
-	"hidden": [],
-	"mods": [
-		{
-			"name": "review-guard",
-			"source": "owner/review-guard",
-			"description": "Blocks risky diffs and adds a /review command.",
-			"author": {"name": "Ada", "github": "ada"},
-			"repo": "https://github.com/owner/review-guard",
-			"kinds": ["tool", "command"],
-			"tags": ["safety", "review"],
-			"official": false
-		}
-	]
-}
-```
+Without `commandcode.mods`, Command Code looks for a `mods/` folder, then a root `index.ts`.
 
-`name`, `source` (what `cmd mods add <source>` takes), `description` (≤240 chars), `author.name`, and at least one `kinds` value (`tool`/`command`/`hook`/`provider`/`renderer`/`flag`) are required; `repo`, `npm`, `tags`, `official`, and `addedAt` are optional. A GitHub `repo` adds a live star count, `npm` names the published package for live metadata and download counts, `official` marks a team-maintained mod, and a `hidden` name (a mod or an npm package) keeps spam or impersonation off the hub. The public schema is `mods/registry.schema.json`.
+`commandcode.skills` lists skill folders the package ships next to its mods. Each entry is one skill folder or a folder of skills, relative to the package root. They load in every session the package loads in, so one `cmd mods add` brings both the mods and their skills. A mod can add skills from code too, with `cmd.addSkillsPath`.
 
-The reviewed list, with live npm metadata and GitHub star counts, is served at [`commandcode.ai/mods.json`](https://commandcode.ai/mods.json), CORS-open, so the CLI or any script can read the same list the hub renders.
+Add the `cmd-mod` keyword so maintainers can find your package. Kind keywords such as `cmd-mod-tool` and `cmd-mod-hook` describe it further. Publishing to npm does not put your mod on the Command Code mods hub by itself. To list it, see [Listing a mod on the mods hub](#listing-a-mod-on-the-mods-hub).
 
-## Filtering a source's mods
+## Load only some mods from a package
 
-A `mods.sources` entry can be the object form to load only part of a package:
+To load part of a package, use the object form of a `mods.sources` entry:
 
 ```json
 {
@@ -115,24 +86,31 @@ A `mods.sources` entry can be the object form to load only part of a package:
 }
 ```
 
-Four pattern kinds, applied in precedence order: `-path` force-exclude (exact, beats everything) → `+path` force-include (exact, restores what globs dropped) → `!glob` exclude → plain-glob include (when any includes exist, an entry must match one). Patterns match the entry's package-relative path or its mod name. `cmd mods add` / `remove` preserve hand-written object entries - they never flatten your filters.
+Patterns match a file's path inside the package, or its mod name. There are four kinds, applied in this order:
 
-## Enable/Disable a mod
+1. `-path` always excludes that exact path, and beats everything else.
+2. `+path` always includes that exact path, even if a glob dropped it.
+3. `!glob` excludes matches.
+4. A plain glob includes matches. When any includes exist, a mod must match one of them.
 
-`cmd mods disable <name>` disables a mod without removing it, and `cmd mods enable <name>` enables it again. Both write the project level (`.commandcode/settings.json`) by default, or the user level (`~/.commandcode/settings.json`) with `-g` flag, and take effect on the next session or `/reload`:
+`cmd mods add` and `cmd mods remove` keep entries you wrote by hand, filters included.
+
+## Turn a mod on or off
+
+`cmd mods disable <name>` turns a mod off without removing it, and `cmd mods enable <name>` turns it back on. Both write to the project settings (`.commandcode/settings.json`) by default, or to your user settings (`~/.commandcode/settings.json`) with `-g`. The change applies on the next session or after `/reload`.
 
 ```bash
-cmd mods disable review-guard        # disable in this project
-cmd mods enable review-guard -g      # enable at the user level
+cmd mods disable review-guard        # off in this project
+cmd mods enable review-guard -g      # on for your user
 ```
 
-They work for discovered files, installed packages, and the disable-able built-ins (`provider-copilot`, `update-notice`, `titling`, `learning` etc). The `cmd mods disable` command adds the name to `mods.disabled`; `cmd mods enable` removes it from there and, for an opt-in built-in such as `todos`, adds it to `mods.enabled`:
+They work for dropped-in files, installed packages, and the built-ins that can be turned off (`provider-copilot`, `update-notice`, `titling`, `learning`, and others). `disable` adds the name to `mods.disabled`. `enable` removes it from there, and for an opt-in built-in such as `todos` it also adds the name to `mods.enabled`:
 
 ```json
 {"mods": {"disabled": ["review-guard"], "enabled": ["todos"]}}
 ```
 
-Disabling a mod anywhere will keep a mod disabled. Command Code reads the user, project, and project-local (`.commandcode/settings.local.json`) settings file, and a `mods.disabled` entry in any of them keeps the mod off, even when another file enables it. So when another settings file still disables the mod you enable, the command does not report success: it names that file, gives the one fix, and exits 1 so a script's `&&` chain stops:
+A disable in any settings file wins. Command Code reads the user, project, and project local (`.commandcode/settings.local.json`) settings, and a `mods.disabled` entry in any of them keeps the mod off, even if another file turns it on. So if another file still disables the mod you enable, the command does not report success. It names that file, gives the fix, and exits with code 1 so a script's `&&` chain stops:
 
 ```bash
 $ cmd mods enable review-guard
@@ -141,14 +119,14 @@ $ cmd mods enable review-guard
   To enable it at the user level, run: cmd mods enable review-guard -g
 ```
 
-A disable in `settings.local.json` has to be removed by hand; no command writes to that file.
+No command writes to `settings.local.json`, so a disable there has to be removed by hand.
 
-**A project you have not used yet:** Project settings are read only once Command Code has run in that project, the same gate project mods follow. Enabling or disabling there still saves the setting, which applies once you start Command Code in the project; use `-g` to apply it at the user level right away. `cmd mods list --builtin` marks a built-in whose state changes then, for example `enabled · disabled once you start Command Code here`.
+**In a project you have not opened yet.** Command Code reads project settings only after it has run in that project, the same rule project mods follow. Enabling or disabling there still saves the setting, and it applies once you start Command Code in the project. Use `-g` to apply it at the user level right away. `cmd mods list --builtin` shows when a built-in will change state, for example `enabled · disabled once you start Command Code here`.
 
 ## Trust and safety
 
-- **There is no sandbox** - a mod is arbitrary code that runs with your permissions; install packages you trust.
-- **Inspect before you trust** - `cmd mods inspect <path>` reads a mod's source (it never imports it) and lists the hooks it registers, what it adds, and what it can reach: processes, the network, the filesystem, the environment, permission answers, transcript rewrites. It is a lexical scan, so code a mod imports or names it builds at runtime can reach further, and the report says so.
+- **There is no sandbox.** A mod is code that runs with your permissions, so only install packages you trust.
+- **Inspect before you trust.** `cmd mods inspect <path>` reads a mod's source without importing it, and lists the hooks it registers, what it adds, and what it can reach: processes, the network, the filesystem, the environment, permission answers, and transcript rewrites. It only reads the text, so code the mod imports or builds at runtime can reach further, and the report says so.
 
 ```bash
 $ cmd mods inspect ./permission-policy.ts
@@ -159,7 +137,51 @@ reaches:   answers permission prompts (onPermissionRequest)
 imports:   none
 ```
 
-- **Kill switches** - `cmd --safe-mode` loads built-in mods only for one session (no installed mods, no `--mod`); `{"mods": {"disableAll": true}}` in any settings file does the same for every session until removed.
-- **Project mods are trust-gated** like project skills: they load only after the workspace trust prompt. User-scope and `--mod` mods always load.
-- **Package installs run npm with `--ignore-scripts`** - mods are jiti-loaded TypeScript; they need no build step, so lifecycle scripts are pure attack surface.
-- **Print mode loads user-scope and `--mod` mods only.** Project mods stay out of headless runs because print never shows a trust prompt; pass `--dangerously-skip-permissions` to opt a repo's own mods into a headless run (CI).
+- **Kill switches.** `cmd --safe-mode` loads only built-in mods for one session (no installed mods, no `--mod`). `{"mods": {"disableAll": true}}` in any settings file does the same for every session until you remove it.
+- **Project mods need workspace trust**, like project skills. They load only after you accept the workspace trust prompt. User mods and `--mod` mods always load.
+- **Packages install with `npm --ignore-scripts`.** Mods are TypeScript loaded directly, so they need no build step, and install scripts would only add risk.
+- **Print mode loads only user mods and `--mod` mods.** Print mode never shows a trust prompt, so project mods stay out of headless runs. Pass `--dangerously-skip-permissions` to include a repo's own mods in a headless run, for example in CI.
+
+# Listing a mod on the mods hub
+
+The [Command Code mods hub](https://commandcode.ai/mods) lists the reviewed entries in `mods/registry.json` in the public [`CommandCodeAI/command-code`](https://github.com/CommandCodeAI/command-code) repo. Every mod on the mods hub needs an entry there, whether it is published to npm or lives on GitHub. Publishing a package or adding a keyword does not list it.
+
+To list your mod:
+
+1. Publish it to npm or push it to a public GitHub repo. Check that `package.json` has the right mod entry points, description, and repository.
+2. Open a PR that adds one entry to [`mods/registry.json`](https://github.com/CommandCodeAI/command-code/blob/main/mods/registry.json). For an npm mod, set both `source` and `npm` to the full package name, including its scope.
+3. Maintainers review the published code. Once the PR is merged, the mods hub picks up the change within about 15 minutes, with no website deploy.
+
+```json
+{
+	"version": 1,
+	"hidden": [],
+	"mods": [
+		{
+			"name": "review-guard",
+			"source": "owner/review-guard",
+			"description": "Blocks risky diffs and adds a /review command.",
+			"author": {"name": "Ada", "github": "ada"},
+			"repo": "https://github.com/owner/review-guard",
+			"kinds": ["tool", "command"],
+			"tags": ["safety", "review"]
+		}
+	]
+}
+```
+
+| Field | Required | What it does |
+|---|:---:|---|
+| `name` | yes | Unique lowercase name the mods hub shows |
+| `source` | yes | What `cmd mods add <source>` installs: an npm name or `owner/repo` |
+| `description` | yes | The summary on the mods hub card, up to 240 characters |
+| `author.name` | yes | Who made it. Add `author.github` to link your profile |
+| `kinds` | yes | At least one of `tool`, `command`, `hook`, `provider`, `renderer`, `flag` |
+| `repo` | no | A GitHub URL. Adds a live star count |
+| `npm` | no | The published npm package. Adds the latest version, publish date, and monthly downloads |
+| `tags` | no | Lowercase search tags |
+| `addedAt` | no | `YYYY-MM-DD`, used to sort by newest |
+
+`official` marks a mod the Command Code team maintains, and the top level `hidden` list keeps spam or impersonation off the mods hub. Both are set by maintainers only. The full schema is `mods/registry.schema.json`.
+
+The mods hub's list, with live npm data and GitHub star counts, is also served at [`commandcode.ai/mods.json`](https://commandcode.ai/mods.json). It allows requests from any origin, so the CLI or any script can read the same list the mods hub shows.

package/dist/bundled/mod-builder/reference/verify.md

@@ -58,14 +58,9 @@ cmd -p "exercise the mod" --mod ./your-mod.ts
 
 Print mode loads user-scope and `--mod` mods with the UI bridge degraded to deterministic defaults (confirm → false, select/input → undefined). A mod that must work in CI should behave sensibly under those defaults.
 
-## 6. Submit the published mod for review
-
-Include `cmd-mod` in your package's keywords so maintainers can discover it.
-Before publishing, check `package.json` for the correct mod entrypoints,
-description, and repository. Publish with `pnpm publish`, then open a PR adding
-an entry to the public [`mods/registry.json`](https://github.com/CommandCodeAI/command-code/blob/main/mods/registry.json).
-Set `source` and `npm` to the full package name for an npm mod. Publishing or
-adding a keyword alone does not list it on the hub.
+## 6. List it on the mods hub
+
+Publish the mod, then add it to the Command Code mods hub with a PR to the public registry. See [Listing a mod on the mods hub](./packaging.md#listing-a-mod-on-the-mods-hub) for the steps and fields.
 
 ## Working from the bundled examples