diff --git a/content/docs/deployment/cli.mdx b/content/docs/deployment/cli.mdx
index 9e8c1af4c1..16766317b4 100644
--- a/content/docs/deployment/cli.mdx
+++ b/content/docs/deployment/cli.mdx
@@ -26,7 +26,7 @@ npm create objectstack@latest my-app
 cd my-app
 ```
 
-This scaffolds a working project with `objectstack.config.ts`, a sample object, and all dependencies installed — plus the AI skills bundle and an `AGENTS.md` for coding agents. (`os init` is the CLI's own scaffolder for plugin skeletons and bare configs — see [below](#os-init).)
+This scaffolds a working project with `objectstack.config.ts`, a sample object, and all dependencies installed — plus the AI skills bundle and an `AGENTS.md` for coding agents. (`os init` is the CLI's own scaffolder for metadata-plugin skeletons and bare configs — see [below](#os-init).)
 
 ### Add more metadata
 
@@ -83,11 +83,35 @@ Scaffolds a new ObjectStack project with configuration, TypeScript setup, and in
 > **Which scaffolder?** For a new app, prefer **`npm create objectstack@latest`** — it
 > also derives your namespace, pins the framework packages to the current release, and
 > installs the AI skills bundle + `AGENTS.md`. Reach for `os init` when you want a
-> **plugin** skeleton or a **bare config** in an existing directory.
+> **bare config** in an existing directory — or a **metadata plugin**, which is only one
+> of the two different artifacts the word `plugin` names in this CLI.
+
+**`plugin` names two artifacts. Route by the artifact you want, not by the word.**
+
+| You want | Command | What it emits | Built by | Publishable? | Read next |
+|:---------|:--------|:--------------|:---------|:-------------|:----------|
+| A **metadata plugin** — declarative objects another stack loads, no kernel code | `os init <name> -t plugin` | `objectstack.config.ts` whose manifest declares `type: 'plugin'`, plus `src/objects/*.object.ts` | `objectstack compile` (its `build` script) | **No** — the emitted `package.json` is `private: true` | [`os init`](#os-init) below, and [Object Metadata](/docs/data-modeling/objects) for the objects it holds |
+| A **kernel code plugin** — TypeScript implementing the kernel `Plugin` contract | `os create plugin <name>` | `src/index.ts` exporting a `Plugin` with `init` / `destroy` | `tsc` (its `build` script) | **Yes** — a publishable `@objectstack/plugin-<name>` package | [`os create`](#os-create) below, then [Plugin Anatomy](/docs/plugins/anatomy) and [Plugin Development](/docs/plugins/development) |
+
+Every page under [Plugins & Packages](/docs/plugins) teaches the **kernel code** plugin, so
+`os create plugin` is the scaffolder those pages mean — `os init -t plugin` will not give
+you a `Plugin` to implement, and `os create plugin` will not give you declarative objects
+to compile.
+
+<Callout type="info">
+**Why the two scaffolders are deliberately separate.** Merging the `os init` and
+`os create` command families was measured and ruled against in
+[#15531](https://github.com/objectstack-ai/objectstack/issues/15531): the two commands
+emit two different artifacts, so collapsing a metadata plugin and a kernel code plugin
+under one command word would make this collision **structural** instead of merely
+documented — teaching the wrong artifact to everyone, human or agent, who generates a
+plugin from the CLI. The collision, and the misdirection this table replaces, are recorded
+in [#15817](https://github.com/objectstack-ai/objectstack/issues/15817).
+</Callout>
 
 ```bash
 os init my-app                    # Create with default "app" template
-os init my-plugin -t plugin       # Create a plugin project
+os init my-plugin -t plugin       # Create a metadata plugin project
 os init blank -t empty            # Minimal config only
 os init my-app --no-install       # Skip dependency installation
 ```
@@ -102,7 +126,7 @@ os init my-app --no-install       # Skip dependency installation
 | Template | What it creates |
 |----------|-----------------|
 | `app` | Full application with objects, barrel imports |
-| `plugin` | Reusable plugin package with objects |
+| `plugin` | **Metadata** plugin: declarative objects, built by `objectstack compile`, `private` — *not* the kernel code plugin `os create plugin` emits |
 | `empty` | Minimal project with just `objectstack.config.ts` |
 
 #### `os dev`
@@ -1263,8 +1287,9 @@ third-party extension primitive, authored as `src/skills/<name>.skill.ts` with
 
 #### `os create`
 
-Scaffolds a **standalone** project — a plugin, or an example application — into
-the current directory:
+Scaffolds a **standalone** project — a **kernel code** plugin (the `Plugin` contract,
+built by `tsc`, publishable; *not* the metadata plugin `os init -t plugin` emits — see
+[Which scaffolder?](#os-init)), or an example application — into the current directory:
 
 ```bash
 os create plugin analytics    # Create ./plugin-analytics