docs(ui,protocol): document the six variants that only ever got name-checked (#4244)

Follow-up to the #4177 variant/doc gate, using the signal it produced. That gate
passes a variant if the page contains either `<disc>: '<variant>'` or a bare
`` `variant` ``, and its header says plainly that the second form is loose: a
pass means the page says the word, not that it documents the thing. Six variants
were passing on the loose form alone — the gate's own "weak pass" list, and a
precise worklist.

apps.mdx enumerated nine navigation item types but only documented six. `report`,
`action` and `component` shared one sentence — "the spec also defines …" — while
the other six each had a section with an example. They now have their own, and
the intro no longer implies a second tier of half-supported types.

The `action` section earns its place: `actionName` lives inside a nested
`actionDef` block, not at the top level, which is exactly the shape a reader
guesses wrong. Both it and `component` note which sub-object stays OPEN by design
(`actionDef.params`, `component.params`) — the sibling contract owns those, and
after #4165 everything around them is strict.

knowledge.mdx had a table naming `object` / `file` / `http` and no example of
any, so the per-kind keys (`contentFields` vs `prefix` vs `urls`) appeared
nowhere. Added one example each.

Every example was parsed against the real schema before committing —
NavigationItemSchema and KnowledgeSourceKindSchema, six for six. Writing docs
from memory is how the region example in #4218 ended up using an `id` key that
does not exist.

Anchored-form coverage for these two unions: 9/12 → 12/12.

Carries an empty changeset. The first push asserted a docs-only PR needs none;
Check Changeset disagreed and named the fix — an empty changeset is the repo's
way for work that releases nothing, and 72 of them already exist.

Refs #4001, #4177

Author: os-zhuang

.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.

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,

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