command-code 1.82.1 → 1.82.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # command-code
 
+## 1.82.3
+
+### Patch Changes
+
+- chore: bump deps to latest versions
+
+## 1.82.2
+
+### Patch Changes
+
+- feat: retire ling 3.1 flash free
+- feat: Add todo checklist as a built-in mod, disabled by default
+
 ## 1.82.1
 
 ### Patch Changes

package/dist/bundled/command-code-knowledge/live-models.ts

@@ -0,0 +1,227 @@
+/**
+ * The live half of the command-code-knowledge skill's model facts. reference/models.md is generated
+ * at build time, so a model the catalog launched after this release is missing from it, and the
+ * skill tells the model to "never invent a model id" — it then refuses to name the new model or pin
+ * an agent to it. On activation the skill body gains a section built from the catalog this process
+ * already holds (never a fetch): models the reference does not list, models the catalog has hidden
+ * or dropped since, and known models whose window or effort levels changed. "This build" is the
+ * catalog embedded in it, which the reference is generated from. No remote catalog, or a catalog
+ * that matches this build, adds nothing.
+ */
+
+import {
+	getSupportedEfforts,
+	listSelectableModelIds,
+} from '../../../config/known-models.js';
+import {getInstalledModelCatalogManager} from '../../../model/catalog-manager.js';
+import {
+	type EffectiveModelCatalog,
+	resolveCatalogModelStatus,
+	getSnapshotEffectiveCatalog,
+} from '../../../model/catalog-resolution.js';
+import type {CatalogModelV1} from '../../../model/model-catalog-wire.js';
+import {getKnownModelContextWindow} from '../../../model/model-registry.js';
+import type {Skill} from '../../skill-registry.js';
+
+export const KNOWLEDGE_SKILL_NAME = 'command-code-knowledge';
+
+interface ModelBuckets {
+	readonly added: readonly CatalogModelV1[];
+	// Shipped ids the catalog hides or no longer carries.
+	readonly hidden: readonly string[];
+	// Shipped ids the catalog now serves in a shape this build cannot run (an unknown profile).
+	readonly outdated: readonly string[];
+	readonly changed: readonly CatalogModelV1[];
+}
+
+// 205_000 → '205K'; 1_000_000 → '1M'; 1_050_000 → '1.05M' — the reference table's spelling.
+function formatContext(tokens: number): string {
+	if (tokens < 1_000_000) return `${Math.round(tokens / 1000)}K`;
+	const millions = tokens / 1_000_000;
+	return `${Number.isInteger(millions) ? millions : millions.toFixed(2)}M`;
+}
+
+function formatEfforts(efforts: readonly string[] | null): string {
+	return efforts && efforts.length > 0 ? efforts.join(', ') : '—';
+}
+
+function sameEfforts(
+	left: readonly string[] | null,
+	right: readonly string[] | null,
+): boolean {
+	return formatEfforts(left) === formatEfforts(right);
+}
+
+function modelRow(model: CatalogModelV1): string {
+	return `| \`${model.id}\` | ${model.display.label} | ${formatContext(model.contextWindow)} | ${formatEfforts(model.reasoningEfforts)} |`;
+}
+
+function modelTable(models: readonly CatalogModelV1[]): string {
+	return [
+		'| Id (use EXACTLY this) | Name | Context | Efforts |',
+		'|---|---|---|---|',
+		...models.map(modelRow),
+	].join('\n');
+}
+
+// The catalog this build ships, which the reference was generated from.
+function builtCatalog(): EffectiveModelCatalog {
+	return getSnapshotEffectiveCatalog({remoteDisabled: false});
+}
+
+// A known model whose served window or effort levels no longer match the embedded catalog the
+// reference was generated from.
+function changedSinceBuild(model: CatalogModelV1): boolean {
+	const built = builtCatalog();
+	const window = getKnownModelContextWindow(model.id, built);
+	if (window !== undefined && window !== model.contextWindow) return true;
+	return !sameEfforts(
+		getSupportedEfforts(model.id, built),
+		model.reasoningEfforts,
+	);
+}
+
+function bucketModels(effective: EffectiveModelCatalog): ModelBuckets {
+	const known = listSelectableModelIds({catalog: builtCatalog()});
+	const knownSet = new Set(known);
+	const added: CatalogModelV1[] = [];
+	const hidden: string[] = [];
+	const changed: CatalogModelV1[] = [];
+	for (const model of effective.catalog.models) {
+		const {state} = resolveCatalogModelStatus({
+			effective,
+			modelId: model.id,
+		});
+		if (state === 'hidden' && knownSet.has(model.id)) {
+			hidden.push(model.id);
+			continue;
+		}
+		if (state !== 'selectable') continue;
+		if (!knownSet.has(model.id)) {
+			added.push(model);
+			continue;
+		}
+		if (changedSinceBuild(model)) changed.push(model);
+	}
+	// A shipped id the catalog no longer carries at all (no row, no alias), or now marks update
+	// required, is refused by /model and sub-agents too.
+	const outdated: string[] = [];
+	for (const id of known) {
+		const {state} = resolveCatalogModelStatus({
+			effective,
+			modelId: id,
+		});
+		if (state === 'not-in-catalog') hidden.push(id);
+		if (state === 'client-update-required') outdated.push(id);
+	}
+	return {added, hidden, outdated, changed};
+}
+
+export interface BuildLiveModelSectionParams {
+	readonly catalog?: EffectiveModelCatalog;
+}
+
+/**
+ * The "live model catalog" section for the knowledge skill, or '' when there is no remote catalog
+ * or it differs from this build in nothing the reference covers. `catalog` defaults to the one this
+ * process's catalog manager holds.
+ */
+export function buildLiveModelSection(
+	params: BuildLiveModelSectionParams = {},
+): string {
+	const effective =
+		params.catalog ?? getInstalledModelCatalogManager()?.getEffective();
+	if (!effective) return '';
+	const {added, hidden, outdated, changed} = bucketModels(effective);
+	if (added.length + hidden.length + outdated.length + changed.length === 0)
+		return '';
+	const parts = [
+		'## Live model catalog (overrides reference/models.md)',
+		'The model catalog in force now differs from the one `reference/models.md` was generated from. Where they disagree, this section wins. Prices and minimum plans for models listed here are not in the reference. Point the user at /model or https://commandcode.ai/docs for those.',
+	];
+	if (added.length > 0) {
+		parts.push(
+			`### Available models the reference does not list\nThese ids are valid for \`/model\`, \`--model\` and an agent file's \`model:\`.\n\n${modelTable(added)}`,
+		);
+	}
+	if (changed.length > 0) {
+		parts.push(
+			`### Context window or efforts changed since the reference\n${modelTable(changed)}`,
+		);
+	}
+	if (hidden.length > 0) {
+		parts.push(
+			`### No longer offered\nDo not recommend these or pin new agents to them: ${hidden
+				.map(id => `\`${id}\``)
+				.join(', ')}.`,
+		);
+	}
+	if (outdated.length > 0) {
+		parts.push(
+			`### Needs a newer Command Code\nThis version cannot run these. Do not recommend them or pin agents to them; tell the user to update Command Code to use them: ${outdated
+				.map(id => `\`${id}\``)
+				.join(', ')}.`,
+		);
+	}
+	return parts.join('\n\n');
+}
+
+/**
+ * The section built once per catalog `getCatalog` answers with. A session hands in its pin when the
+ * pin came from the live catalog, else the newest catalog — so every activation (the activate_skill
+ * tool, a `/command-code-knowledge` turn, an inline mention) reads the same text until a catalog
+ * lands or /model re-pins.
+ */
+export function createLiveModelSectionCache(
+	getCatalog: () => EffectiveModelCatalog | undefined,
+): () => string {
+	let cached:
+		| {readonly catalog: EffectiveModelCatalog; readonly text: string}
+		| undefined;
+	return () => {
+		const catalog = getCatalog();
+		if (!catalog) return '';
+		if (cached?.catalog !== catalog) {
+			cached = {catalog, text: buildLiveModelSection({catalog})};
+		}
+		return cached.text;
+	};
+}
+
+export interface AppendLiveModelSectionParams {
+	readonly body: string;
+	readonly section: string;
+}
+
+/** A skill body plus the live model section, when there is one. */
+export function appendLiveModelSection(
+	params: AppendLiveModelSectionParams,
+): string {
+	return params.section ? `${params.body}\n\n${params.section}` : params.body;
+}
+
+export interface WithLiveModelSectionParams {
+	readonly skill: Skill;
+	readonly section: () => string | Promise<string>;
+}
+
+/**
+ * The bundled knowledge skill with the live model section on its body, so every path that loads the
+ * body gets it; any other skill (a user skill of the same name included) is returned unchanged.
+ */
+export function withLiveModelSection(
+	params: WithLiveModelSectionParams,
+): Skill {
+	const {skill} = params;
+	if (skill.source !== 'bundled' || skill.name !== KNOWLEDGE_SKILL_NAME) {
+		return skill;
+	}
+	return {
+		...skill,
+		loadBody: async () =>
+			appendLiveModelSection({
+				body: await skill.loadBody(),
+				section: await params.section(),
+			}),
+	};
+}

package/dist/bundled/command-code-knowledge/reference/custom-slash-commands.md

@@ -61,7 +61,7 @@ Every built-in command, grouped by area. Aliases are shown in parentheses on the
 | `/plans [name]`                      | Browse, review, and annotate saved plans; bare `/plans` opens the browser          |
 | `/plan-review`                       | Open this session's latest plan in review                                          |
 | `/goal <objective>\|clear\|status`   | Set an objective for the agent to work towards autonomously                        |
-| `/todos`                             | Manage the session todo list - `c` completes the selected item, `x` removes it, `a` clears the list |
+| `/todos`                             | Manage the session todo list (needs the `todos` mod: `cmd mods enable todos`)      |
 | `/review [pr-number]`                | Review a pull request                                                              |
 | `/pr-comments`                       | Fetch all PR comments for current branch                                           |
 
@@ -151,7 +151,7 @@ Most commands are **blocked mid-turn** - mode flips, session switches, model cha
 - `/trace` - capture the live trace id of the running turn (its main purpose)
 - `/session-file` - read-only session facts
 - `/copy` - clipboard only
-- `/todos` (also `ctrl+x`) - edits local todo state, most useful mid-turn while a plan is being driven
+- `/todos` (also `ctrl+x`) - edits local todo state, most useful mid-turn while a plan is being driven (needs the `todos` mod enabled)
 - `/exit` / `/quit` - always available
 - `/goal clear` - stops the goal loop; the current step finishes, then the loop stops. Setting a **new** goal mid-turn is refused with a busy notice.
 

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

@@ -100,7 +100,7 @@ cmd -p "..." --tools-all
 CMD_TOOLS_ALL_ENABLE=true cmd -p "..."
 
 # Only enable the ones you name (comma-separated, repeatable)
-cmd -p "..." --tools-enable ask_user_question,todo_write
+cmd -p "..." --tools-enable ask_user_question
 CMD_TOOLS_ASK_USER_QUESTION_ENABLE=true cmd -p "..."
 ```
 

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

@@ -35,6 +35,7 @@ The model catalog — every id `/model`, `--model`, `model:effort` shorthand, an
 | `xiaomi/mimo-v2.5-pro` | MiMo V2.5 Pro | 1M | — | $0.435/$0.87 · cache $0.0036 | Go and above | high-capability long-context agentic coding |
 | `xiaomi/mimo-v2.5` | MiMo V2.5 | 1M | — | $0.14/$0.28 · cache $0.0028 | Go and above | efficient long-context agentic coding |
 | `Qwen/Qwen3.8-Omni-Flash` | Qwen 3.8 Omni Flash | 1M | low, medium, xhigh | $0.15/$0.47 · cache $0.016 | Go and above | omni-modal understanding & multimedia agentic work |
+| `Qwen/Qwen3.8-Max-Prime` | Qwen 3.8 Max Prime | 1M | low, medium, xhigh | $4/$12 · cache $0.5 (write $5) | GOAT and above | high-speed Qwen 3.8 Max: 1.5–2× faster output |
 | `Qwen/Qwen3.8-Max-0902` | Qwen 3.8 Max 0902 | 1M | low, medium, xhigh | $2/$6 · cache $0.25 | Go and above | upgraded Qwen 3.8 Max: stronger coding & agentic tool use |
 | `Qwen/Qwen3.8-Max` | Qwen 3.8 Max | 1M | low, medium, xhigh | $2/$6 · cache $0.25 (write $2.5) | Go and above | autonomous long-horizon coding & professional work |
 | `Qwen/Qwen3.8-27B` | Qwen 3.8 27B | 262K | low, medium, xhigh | $0.4/$3 · cache $0.04 | Go and above | compact vision-language coding & agentic work |
@@ -55,7 +56,7 @@ The model catalog — every id `/model`, `--model`, `model:effort` shorthand, an
 | `thinkingmachines/inkling-small` | Inkling Small | 1M | — | $0.5/$1.2 · cache $0.1 | Go and above | lightweight MoE reasoning at lower cost and latency |
 | `poolside/laguna-s-2.1-free` | Laguna S 2.1 | 256K | — | $0/$0 · cache $0 | Go and above | open-weight agentic coding and long-horizon work |
 | `inclusionai/ling-3.0-flash-sante:free` | Ling 3.0 Flash Sante | 262K | — | $0/$0 · cache $0 | Go and above | health & medicine tuned lightweight-MoE, still strong on code |
-| `inclusionai/ling-3.1-flash:free` | Ling 3.1 Flash | 262K | low, medium, high | $0/$0 · cache $0 | Go and above | hybrid-reasoning MoE for coding & tool-using agents |
+| `inclusionai/ling-3.1-flash` | Ling 3.1 Flash | 262K | low, medium, high | $0.3/$0.9 · cache $0.06 | Go and above | hybrid-reasoning MoE for coding & tool-using agents |
 | `mistral/mistral-large-4` | Mistral Large 4 | 524K | low, medium, high | $1.36/$4.18 · cache $0.14 | Go and above | frontier open-weight multimodal model for coding & analysis |
 ## Stealth
 

package/dist/bundled/command-code-knowledge/reference/product-help.md

@@ -54,7 +54,7 @@
 - /export [path]: Export session — /export [html|jsonl|md] or a file path
 - /changelog: See what's new in Command Code
 - /hotkeys: Show all keyboard shortcuts
-- /todos: Manage the session todo list — x to remove an item, c to clear
+- /todos: Manage the session todo list — c completes an item, x removes it, a completes all (needs the `todos` mod: `cmd mods enable todos`)
 - /loop [interval] [task]: Re-run a task on fixed intervals, or let the agent pace itself
 - /rc: Remote-control this session from Telegram or Discord
 - /plan [task]: Enter plan mode; `/plan <task>` plans that task
@@ -277,22 +277,20 @@ Valid model ids (the /model catalog — use these EXACT ids):
 - gpt-5.4
 - gpt-5.3-codex
 - gpt-5.4-mini
-- moonshotai/Kimi-K3
-- thinkingmachines/inkling
-- thinkingmachines/inkling-small
 - deepseek/deepseek-v4-pro
 - deepseek/deepseek-v4-flash
 - deepseek/deepseek-v4-flash-vision-exp
 - deepseek/deepseek-v4-flash-fast
 - deepseek/deepseek-v4.1-flash
 - deepseek/deepseek-v4.1-flash-fast
+- moonshotai/Kimi-K3
 - moonshotai/Kimi-K2.7-Code
 - moonshotai/Kimi-K2.7-Code-Highspeed
 - moonshotai/Kimi-K2.6
 - moonshotai/Kimi-K2.5
-- zai-org/GLM-5.3
 - z-ai/glm-5.3-flash
 - z-ai/glm-5.3-flashx
+- zai-org/GLM-5.3
 - zai-org/GLM-5.2
 - zai-org/GLM-5.2-Fast
 - zai-org/GLM-5.1
@@ -305,22 +303,23 @@ Valid model ids (the /model catalog — use these EXACT ids):
 - xiaomi/mimo-v2.6-flash
 - xiaomi/mimo-v2.5-pro
 - xiaomi/mimo-v2.5
-- Qwen/Qwen3.6-Max-Preview
-- Qwen/Qwen3.6-Plus
-- Qwen/Qwen3.7-Max
-- Qwen/Qwen3.7-Plus
 - Qwen/Qwen3.8-Omni-Flash
+- Qwen/Qwen3.8-Max-Prime
 - Qwen/Qwen3.8-Max-0902
 - Qwen/Qwen3.8-Max
 - Qwen/Qwen3.8-27B
 - Qwen/Qwen3.8-Flash
+- Qwen/Qwen3.7-Max
+- Qwen/Qwen3.7-Plus
 - Qwen/Qwen3.7-Flash
+- Qwen/Qwen3.6-Max-Preview
+- Qwen/Qwen3.6-Plus
 - meituan/LongCat-2.0
 - stepfun/Step-5-Preview
 - stepfun/Step-3.7-Flash
 - stepfun/Step-3.5-Flash
-- tencent/hy4-preview
 - tencent/hy3-paid
+- tencent/hy4-preview
 - google/gemini-4-argon
 - google/gemini-3.8-flash
 - google/gemini-3.7-flash
@@ -329,21 +328,23 @@ Valid model ids (the /model catalog — use these EXACT ids):
 - google/gemini-3.5-flash-lite
 - google/gemini-3.1-flash-lite
 - sakana/fugu-ultra
-- xai/grok-4.5
-- xai/grok-4.6
-- xai/grok-4.7
-- mistral/mistral-large-4
+- nvidia/nemotron-3-ultra-550b-a55b
+- thinkingmachines/inkling
+- thinkingmachines/inkling-small
+- stealth/glyph-cluster:free
+- poolside/laguna-s-2.1-free
+- inclusionai/ling-3.0-flash-sante:free
+- inclusionai/ling-3.1-flash
 - meta/muse-spark-1.1
 - meta/muse-spark-1.2
 - meta/muse-spark-1.2-contributor
 - meta/muse-spark-1.3
 - meta/muse-spark-1.3-contributor
 - meta/muse-wonder-1.0
-- nvidia/nemotron-3-ultra-550b-a55b
-- poolside/laguna-s-2.1-free
-- inclusionai/ling-3.0-flash-sante:free
-- inclusionai/ling-3.1-flash:free
-- stealth/glyph-cluster:free
+- xai/grok-4.5
+- xai/grok-4.6
+- xai/grok-4.7
+- mistral/mistral-large-4
 A BYO-provider id (from a configured custom provider) also works and is passed through as-is.
 
 WHEN THE USER ASKS YOU TO CREATE AN AGENT (e.g. "make a changelog agent with a cheap model"):

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

@@ -228,8 +228,29 @@ Resolves ports to pids via `lsof` (or `Get-NetTCPConnection` on Windows), reconc
 
 ## Work state & task management
 
+### `task_create` / `task_update` / `task_list` / `task_get`
+
+A durable, dependency-aware task ledger for coordination-heavy work - tasks persist across restarts with stable ids, three states, owners, metadata, and `blockedBy`/`blocks` edges.
+
+- **`task_create`** - `subject` (required), `description` (required), `activeForm`, `blockedBy`, `blocks`, `metadata`.
+- **`task_update`** - `taskId` (required), `status` (`pending` | `in_progress` | `completed` | `deleted`), `subject`, `description`, `activeForm`, `owner`, `metadata` (merge; null deletes a key), `addBlockedBy` / `addBlocks` / `removeBlockedBy` / `removeBlocks`. Completing a task reports which tasks it unblocked.
+- **`task_list`** - optional `status` filter; shows unresolved blockers and a tally.
+- **`task_get`** - `taskId` (required); full detail.
+
+All four are plan-safe - capturing a plan as tasks *is* planning.
+
+### `task_output` (alias)
+
+Retired into `shell_output`. Calls to this name still work: they run as `shell_output` with `wait: "exit"` carried, so "block until the task settles" keeps its meaning. Use `shell_output` directly in new work.
+
+### `task_stop`
+
+Stop a tracked background task by `taskId`. Signals the whole process group, flips the registry state, and distinguishes "unknown id" from "already finished."
+
 ### `todo_write`
 
+Provided by the opt-in `todos` built-in mod, which is **disabled by default** - enable it with `cmd mods enable todos` (`-g` for user scope) and it appears on the next session or `/reload`. While the mod is disabled the model never sees this tool.
+
 The session checklist - the same list you manage with `/todos` and see in the TODOS panel.
 
 | Parameter | Type | Required | Description |
@@ -286,25 +307,6 @@ A single edit in a single place. The agent makes it.
 
 One command, immediate result. A checklist around it adds a panel and no information.
 
-### `task_create` / `task_update` / `task_list` / `task_get`
-
-A durable, dependency-aware task ledger for coordination-heavy work - tasks persist across restarts with stable ids, three states, owners, metadata, and `blockedBy`/`blocks` edges.
-
-- **`task_create`** - `subject` (required), `description` (required), `activeForm`, `blockedBy`, `blocks`, `metadata`.
-- **`task_update`** - `taskId` (required), `status` (`pending` | `in_progress` | `completed` | `deleted`), `subject`, `description`, `activeForm`, `owner`, `metadata` (merge; null deletes a key), `addBlockedBy` / `addBlocks` / `removeBlockedBy` / `removeBlocks`. Completing a task reports which tasks it unblocked.
-- **`task_list`** - optional `status` filter; shows unresolved blockers and a tally.
-- **`task_get`** - `taskId` (required); full detail.
-
-All four are plan-safe - capturing a plan as tasks *is* planning.
-
-### `task_output` (alias)
-
-Retired into `shell_output`. Calls to this name still work: they run as `shell_output` with `wait: "exit"` carried, so "block until the task settles" keeps its meaning. Use `shell_output` directly in new work.
-
-### `task_stop`
-
-Stop a tracked background task by `taskId`. Signals the whole process group, flips the registry state, and distinguishes "unknown id" from "already finished."
-
 ---
 
 ## Scheduling & waiting

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

@@ -116,11 +116,13 @@ run `pnpm generate:knowledge` after editing the docs under `packages/docs/src/ap
 - Personal: leave it in `~/.commandcode/mods/`.
 - A package: a `package.json` with `{"keywords": ["cmd-mod"], "commandcode": {"mods": ["./index.ts"]}}`,
   installed via `cmd mods add npm:<name>` / `cmd mods add owner/repo` / `cmd mods add ./local-dir`.
-  **Always include the `cmd-mod` keyword** — it is what lists the package on the
-  [mods hub](https://commandcode.ai/mods) once it is published to npm; without it the mod is
-  invisible there. Add a kind keyword too (`cmd-mod-tool`, `cmd-mod-command`, …) and a
-  `repository` field so the hub row shows the right category and a star count. Full
-  packaging/filtering detail: `reference/packaging.md`.
+  Include the exact `cmd-mod` keyword so maintainers can discover it for review.
+  After publishing with `pnpm publish`, submit an entry to `mods/registry.json`
+  in the public `CommandCodeAI/command-code` repo. Publishing alone does not list
+  a mod on the [mods hub](https://commandcode.ai/mods). The reviewed entry supplies
+  its description and categories; `npm` enables live package metadata and monthly
+  downloads, and a GitHub `repo` enables stars. Full packaging and submission
+  detail: `reference/packaging.md`.
 
 ## Boundaries to state up front
 

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

@@ -188,10 +188,10 @@ Command Code's own features ride this exact API. First-party providers (`provide
 {"mods": {"disabled": ["provider-copilot", "update-notice", "titling", "learning"]}}
 ```
 
-A built-in can also ship **opt-in** - off by default; `cmd mods list --builtin` marks it `off by default`. Enable mods with `cmd mods enable <name>` (project level; `-g` for the user level), which adds it to the `enabled` key in the settings file:
+Some built-ins are **opt-in** and are disabled by default; `cmd mods list --builtin` marks them `disabled by default`. The session todo checklist (`todo_write`, the TODOS panel, `/todos`, `ctrl+x`) is the `todos` mod: enable it with `cmd mods enable todos` (project level; `-g` for the user level), which adds it to the `enabled` key in the settings file:
 
 ```json
-{"mods": {"enabled": ["<name>"]}}
+{"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).

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

@@ -54,22 +54,28 @@ A package declares what it ships via `package.json` - exact paths, directories,
 }
 ```
 
-The `cmd-mod` keyword is **required** — it is the only thing that lists your package on the
-[mods hub](https://commandcode.ai/mods). Everything else shapes the hub row: a `description`
-becomes the summary, a kind keyword (`cmd-mod-tool`, `cmd-mod-command`, `cmd-mod-hook`,
-`cmd-mod-provider`, `cmd-mod-renderer`, `cmd-mod-flag`) sets the category badge, and a
-`repository` pointing at GitHub adds the star count. Ship these from the start so the hub
-lists the mod well the moment you publish, with nothing to submit.
+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`.
 
-Publish to npm with the `cmd-mod` keyword and the package is listed on the [mods hub](https://commandcode.ai/mods) automatically - the hub reads the npm registry for that keyword, so there is nothing to submit. Monthly downloads come straight from npm; a GitHub `repository` field adds the star count.
+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 git-only mod (the curated registry)
+## Listing a mod on the hub
 
-Two things feed [the hub](https://commandcode.ai/mods). Any npm package with the `cmd-mod` keyword lists automatically (above). A **curated registry** - `mods/registry.json` in the public [`CommandCodeAI/command-code`](https://github.com/CommandCodeAI/command-code) repo - adds what npm can't: mods that live only in a git repo and never hit npm, richer metadata layered over an npm entry (matched by `npm`), an `official` badge, and a `hidden` list for moderation. Open a PR against that file to get a git-only mod listed - nothing else to submit.
+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
 {
@@ -90,9 +96,9 @@ Two things feed [the hub](https://commandcode.ai/mods). Any npm package with the
 }
 ```
 
-`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` merges the entry with its npm package for the download count, `official` marks a team-maintained mod, and a `hidden` name (a mod or an npm package) keeps spam or impersonation off the hub. The schema is `mods.schema.json` beside the file.
+`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`.
 
-The resolved list - npm discovery merged with the curated file, live numbers included - 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.
+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.
 
 ## Filtering a source's mods
 
@@ -119,10 +125,10 @@ cmd mods disable review-guard        # disable in this project
 cmd mods enable review-guard -g      # enable at the user level
 ```
 
-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, adds it to `mods.enabled`:
+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`:
 
 ```json
-{"mods": {"disabled": ["review-guard"], "enabled": ["<opt-in-built-in>"]}}
+{"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:
@@ -136,7 +142,7 @@ $ cmd mods enable review-guard
 
 A disable in `settings.local.json` has to be removed by hand; no command writes to that file.
 
-**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.
+**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`.
 
 ## Trust and safety
 

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

@@ -54,6 +54,15 @@ 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.
+
 ## Working from the bundled examples
 
 Ask Command Code to build the mod you want and it starts from a bundled example rather than a blank file - see [Runnable examples](./overview.md#runnable-examples) for the list. Each one loads through the real mod loader in CI on every test run, so what you start from is proven to load.