diff --git a/.changeset/21286-cli-extension-tsdoc-discover.md b/.changeset/21286-cli-extension-tsdoc-discover.md
new file mode 100644
index 00000000000..a6783502f5d
--- /dev/null
+++ b/.changeset/21286-cli-extension-tsdoc-discover.md
@@ -0,0 +1,9 @@
+---
+'@objectstack/spec': patch
+---
+
+The `kernel/cli-extension` module documentation no longer tells plugin authors to run `os plugins install`. Step 2, "Discover", said the plugin is listed in `@objectstack/cli`'s `oclif.plugins` array, or that users install it with `os plugins install`. Neither is true: `@objectstack/cli` declares no `oclif.plugins` and ships no plugin manager, so `os plugins` is not a command. The step now says what loads a plugin: oclif loads a plugin that the CLI's own `package.json` lists in both `oclif.plugins` and `dependencies`. To add a plugin's commands to `os`, build an `os` distribution whose own `package.json` lists the plugin in both places. The generated reference page carries the same text.
+
+Clause-②: no
+
+Documentation only. No schema, export or type changes.
diff --git a/content/docs/references/kernel/cli-extension.mdx b/content/docs/references/kernel/cli-extension.mdx
index 172f6ce19e8..df95a843d90 100644
--- a/content/docs/references/kernel/cli-extension.mdx
+++ b/content/docs/references/kernel/cli-extension.mdx
@@ -17,8 +17,11 @@ built-in plugin system.
 
 1. **Declare** — Plugin's `package.json` includes an `oclif` config section
    declaring its commands directory and any topics.
-2. **Discover** — The main CLI (`@objectstack/cli`) lists the plugin in its
-   `oclif.plugins` array, or users install it via `os plugins install <pkg>`.
+2. **Discover** — oclif loads a plugin that the CLI's own `package.json`
+   lists in both `oclif.plugins` and `dependencies`. `@objectstack/cli`
+   lists none and ships no plugin manager, so `os plugins` is not a
+   command. To add a plugin's commands to `os`, build an `os` distribution:
+   a package whose own `package.json` lists the plugin in both places.
 3. **Load** — oclif automatically discovers and registers all Command classes
    exported from the plugin's commands directory.
 
diff --git a/packages/spec/src/kernel/cli-extension.zod.ts b/packages/spec/src/kernel/cli-extension.zod.ts
index 319283ca91a..9843fef08eb 100644
--- a/packages/spec/src/kernel/cli-extension.zod.ts
+++ b/packages/spec/src/kernel/cli-extension.zod.ts
@@ -14,8 +14,11 @@ import { z } from 'zod';
  * 
  * 1. **Declare** — Plugin's `package.json` includes an `oclif` config section
  *    declaring its commands directory and any topics.
- * 2. **Discover** — The main CLI (`@objectstack/cli`) lists the plugin in its
- *    `oclif.plugins` array, or users install it via `os plugins install <pkg>`.
+ * 2. **Discover** — oclif loads a plugin that the CLI's own `package.json`
+ *    lists in both `oclif.plugins` and `dependencies`. `@objectstack/cli`
+ *    lists none and ships no plugin manager, so `os plugins` is not a
+ *    command. To add a plugin's commands to `os`, build an `os` distribution:
+ *    a package whose own `package.json` lists the plugin in both places.
  * 3. **Load** — oclif automatically discovers and registers all Command classes
  *    exported from the plugin's commands directory.
  *