docs(plugin-tree): compile the README's snippet against the authorable surface (#8251)

The page's only collected fence was a bare `object-view` literal carrying
`views: [{ type: 'tree', tree: { ... } }]`. It never parsed (TS1005 x2 +
TS1109), so the ledger row was the whole of what this gate knew about the
page, and a genuine type error in that literal left the row byte-identical.

Two facts made the obvious repair wrong. `ObjectViewSchema` declares no
`views` member at all, so annotating the literal with it compiles green
while checking nothing that matters -- measured: `views: 'not-even-an-array'`
is accepted, only `objectName` turns red. And `tree` is a host-composition
view type, not an authorable one: objectui#5321 ruled it recorded rather
than declared, and ObjectView.tsx states verbatim that its config surface is
"not authoring surface to teach in the docs". The example taught, as
authored metadata, the one shape that ruling forbids teaching.

So the example now writes the `object-tree` node an author can actually
select, bound through the exported `ObjectQLComponentSchema` union, which
narrows on `type` and checks all five declared members. The host-only `tree`
alias keeps its paragraph, as prose rather than as a copyable example.

The four documented defaults were each checked against ObjectTree.tsx and
were already correct; they are unchanged.

Part of #5174 (batch 33)


Claude-Session: https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

packages/plugin-tree/README.md

@@ -9,28 +9,26 @@ handles *fixed-depth* hierarchies; a tree handles arbitrary depth.)
 
 It registers two component types via the `ComponentRegistry`:
 
-- `object-tree` — the object-bound renderer
-- `tree` — the view-type alias used by `ObjectView` / `ViewSwitcher`
+- `object-tree` — the object-bound renderer, and the one an author selects
+- `tree` — a view-type alias reached only by host composition (see below)
 
 ## Usage
 
+Author an `object-tree` node. Its config keys sit **flat on the node**, and
+`ObjectQLComponentSchema` narrows on `type`, so each one is checked against
+`ObjectTreeSchema`:
+
 ```ts
-// As a view inside an ObjectView
-{
-  type: 'object-view',
+import type { ObjectQLComponentSchema } from '@object-ui/types';
+
+const schema: ObjectQLComponentSchema = {
+  type: 'object-tree',
   objectName: 'business_unit',
-  views: [
-    {
-      type: 'tree',
-      tree: {
-        parentField: 'parent',        // single-parent pointer (auto-detected if omitted)
-        labelField: 'name',           // indented first column
-        fields: ['name', 'manager'],  // additional flat columns
-        defaultExpandedDepth: 1,      // 0 = roots only; omit = expand all
-      },
-    },
-  ],
-}
+  parentField: 'parent',        // single-parent pointer (auto-detected if omitted)
+  labelField: 'name',           // indented first column
+  fields: ['name', 'manager'],  // additional flat columns
+  defaultExpandedDepth: 1,      // 0 = roots only; omit = expand all
+};
 ```
 
 ### Config
@@ -45,6 +43,23 @@ It registers two component types via the `ComponentRegistry`:
 Records whose parent is missing (or points outside the result set) are kept as
 roots, so nothing is silently dropped.
 
+### The `tree` view type is host composition, not authoring
+
+`tree` is **not** an authorable view type. Neither `ObjectViewSchema.defaultViewType`
+nor `NamedListView.type` admits it — both are the same seven-value union that stops
+at `map` — so no authored document selects a tree view, and `ObjectViewSchema`
+declares no `views` member at all. The `tree` branch runs only when a **host**
+composes `ObjectView` with a `views` prop, whose entries carry `id` and `label`
+and are typed `ViewType`. That was ruled deliberate on objectui#5321
+(2026-08-20): `tree` and `chart` are recorded as host-composition-only surfaces
+rather than added to the authored unions. The per-view `tree` config block that
+path reads is host config, so it is not documented here as authoring surface.
+
+The live consumer is the console: it passes stored view records to `ObjectView`
+as `views`, and its create-view dialog offers `tree` among the types a console
+user can create. To render a tree from authored metadata, write the
+`object-tree` node above.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

scripts/check-doc-snippet-types.mjs

@@ -781,8 +781,6 @@ const UNGATED_DOCS = {
     '1 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies; 1 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; plus TS2322x1 — candidate real defects, un-triaged',
   'packages/plugin-markdown/README.md':
     '2 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies',
-  'packages/plugin-tree/README.md':
-    '3 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies',
 };
 
 // ── Fence scanning ───────────────────────────────────────────────────────────