diff --git a/.changeset/document-weak-pass-variants.md b/.changeset/document-weak-pass-variants.md
new file mode 100644
index 0000000000..93d666ca1f
--- /dev/null
+++ b/.changeset/document-weak-pass-variants.md
@@ -0,0 +1,4 @@
+---
+---
+
+docs(ui,protocol): document the six navigation / knowledge-source variants that the #4177 variant/doc gate was only ever name-checking. `apps.mdx` enumerated nine navigation item types but gave `report`, `action` and `component` a single shared sentence instead of sections; `knowledge.mdx` named `object` / `file` / `http` in a table with no example of any, leaving the per-kind keys undocumented. Each example was parsed against the real schema (`NavigationItemSchema`, `KnowledgeSourceKindSchema`) before landing. Documentation only; releases nothing.
diff --git a/content/docs/protocol/knowledge.mdx b/content/docs/protocol/knowledge.mdx
index 06988e69ed..105ec9519b 100644
--- a/content/docs/protocol/knowledge.mdx
+++ b/content/docs/protocol/knowledge.mdx
@@ -119,6 +119,34 @@ Three source kinds:
 | `file`   | A folder in `IStorageService`                       | Onboarded PDFs, uploads         |
 | `http`   | A list of remote URLs                               | External docs, RSS, sitemaps    |
 
+`kind` is the discriminator, and each kind carries its own keys — a key from one
+kind is rejected on another:
+
+```typescript
+// object — content comes from the named fields of each matching record
+source: {
+  kind: 'object',
+  object: 'kb_article',
+  contentFields: ['title', 'body'],       // at least one, required
+  metadataFields: ['category', 'author'], // optional, carried onto the document
+  where: { status: 'published' },         // optional ObjectQL filter
+}
+
+// file — every object under a storage prefix
+source: {
+  kind: 'file',
+  prefix: 'knowledge/handbook/',
+  mimeTypes: ['application/pdf', 'text/markdown'], // optional; omit to take all
+}
+
+// http — an explicit URL list (each must be a valid URL)
+source: {
+  kind: 'http',
+  urls: ['https://docs.example.com/guide', 'https://docs.example.com/faq'],
+  userAgent: 'ObjectStack-KnowledgeBot/1.0', // optional
+}
+```
+
 Every source binds to a named **adapter id** (e.g. `'ragflow'`,
 `'memory'`). The adapter id is resolved at runtime by the plugin that
 registers itself with that name. Adapter config (endpoint, dataset id,
diff --git a/content/docs/ui/apps.mdx b/content/docs/ui/apps.mdx
index 8d694a86e9..1276d19e52 100644
--- a/content/docs/ui/apps.mdx
+++ b/content/docs/ui/apps.mdx
@@ -57,7 +57,11 @@ const crmApp = {
 
 ## Navigation Items
 
-The navigation tree supports nine item types, combined to create rich menu structures. The most common are shown below (`object`, `dashboard`, `page`, `url`, `group`, `separator`); the spec also defines `report`, `action`, and `component` items.
+The navigation tree supports nine item types, combined to create rich menu structures: `object`, `dashboard`, `page`, `url`, `report`, `action`, `component`, `group` and `separator`. Each is documented below.
+
+`type` is the discriminator: a value outside that list is rejected with the full
+set of valid ones, and every other key is checked against the branch you picked
+rather than against all nine.
 
 ### Object Navigation
 
@@ -121,6 +125,48 @@ Groups items into collapsible sections with children:
 }
 ```
 
+### Report Navigation
+
+Links to a saved report:
+
+```typescript
+{ id: 'nav_pipeline', type: 'report', label: 'Pipeline Report', reportName: 'sales_pipeline', icon: 'file-bar-chart' }
+```
+
+### Action Navigation
+
+Runs an action instead of navigating to a surface. The reference lives in a
+nested `actionDef` block — `actionName` is **not** a top-level key on the item:
+
+```typescript
+{
+  id: 'nav_import',
+  type: 'action',
+  label: 'Import Records',
+  icon: 'upload',
+  actionDef: {
+    actionName: 'bulk_import',
+    params: { objectName: 'account', mode: 'upsert' },
+  },
+}
+```
+
+`actionDef` accepts only `actionName` and `params`. `params` itself is **open by
+design** — the action owns its own parameter contract, so the app schema does
+not validate what goes inside it.
+
+### Component Navigation
+
+Renders a registered component. `componentRef` is a component-registry key, not
+a file path:
+
+```typescript
+{ id: 'nav_directory', type: 'component', label: 'Directory', componentRef: 'metadata:directory', icon: 'contact' }
+```
+
+`params` is handed to the component as props and is **open by design** — the
+props are the component's own contract.
+
 ### Separator
 
 A visual divider in the navigation list. It renders no target and carries no