feat(showcase): ADR-0047 — lookup quick-filter example (project)

Adds the project master-detail field to the Task List view's dropdown
filters: the record-picker dropdown path (search + multi-select records)
that CRM consumers (hotcrm account workbench: owner user lookup) rely
on. Browser-verified + covered by objectui e2e (user-filters.spec.ts).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

content/docs/references/api/metadata.mdx

@@ -314,7 +314,7 @@ Metadata query with filtering, sorting, and pagination
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **types** | `Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>[]` | optional | Filter by metadata types |
+| **types** | `Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'doc' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>[]` | optional | Filter by metadata types |
 | **namespaces** | `string[]` | optional | Filter by namespaces |
 | **packageId** | `string` | optional | Filter by owning package |
 | **search** | `string` | optional | Full-text search query |
@@ -349,7 +349,7 @@ Metadata query with filtering, sorting, and pagination
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type |
+| **type** | `Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'doc' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type |
 | **name** | `string` | ✅ | Item name (snake_case) |
 | **data** | `Record<string, any>` | ✅ | Metadata payload |
 | **namespace** | `string` | optional | Optional namespace |

content/docs/references/automation/approval.mdx

@@ -71,6 +71,7 @@ const result = ApprovalDecision.parse(data);
 | **lockRecord** | `boolean` | ✅ | Lock the record from editing while pending |
 | **approvalStatusField** | `string` | optional | Business-object field to mirror request status onto |
 | **escalation** | `Object` | optional | Per-node SLA escalation |
+| **maxRevisions** | `integer` | ✅ | Max send-backs for revision before auto-reject (0 = send-back disabled) |
 
 
 ---

content/docs/references/automation/node-executor.mdx

@@ -76,6 +76,7 @@ Canonical cross-paradigm action/node descriptor (ADR-0018)
 | **supportsRetry** | `boolean` | ✅ | Supports retry on failure |
 | **needsOutbox** | `boolean` | ✅ | Dispatch via service-messaging outbox (retry/idempotency/dead-letter) |
 | **isAsync** | `boolean` | ✅ | Suspends the flow awaiting an external reply |
+| **maturity** | `Enum<'ga' \| 'beta' \| 'reserved'>` | ✅ | Runtime maturity: ga (shipped), beta, or reserved (contract only — designers grey this out) |
 | **source** | `Enum<'builtin' \| 'plugin'>` | ✅ | builtin = platform baseline; plugin = third-party contributed |
 | **deprecated** | `boolean` | ✅ | Deprecated alias kept for back-compat |
 | **aliasOf** | `string` | optional | Canonical type this alias forwards to |

content/docs/references/kernel/metadata-plugin.mdx

@@ -130,7 +130,7 @@ const result = MetadataBulkRegisterRequest.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **event** | `Enum<'metadata.registered' \| 'metadata.updated' \| 'metadata.unregistered' \| 'metadata.validated' \| 'metadata.deployed' \| 'metadata.overlay.applied' \| 'metadata.overlay.removed' \| 'metadata.imported' \| 'metadata.exported'>` | ✅ | Event type |
-| **metadataType** | `Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type |
+| **metadataType** | `Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'doc' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type |
 | **name** | `string` | ✅ | Metadata item name |
 | **namespace** | `string` | optional | Namespace |
 | **packageId** | `string` | optional | Owning package ID |
@@ -147,7 +147,7 @@ const result = MetadataBulkRegisterRequest.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **types** | `Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>[]` | optional | Filter by metadata types |
+| **types** | `Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'doc' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>[]` | optional | Filter by metadata types |
 | **namespaces** | `string[]` | optional | Filter by namespaces |
 | **packageId** | `string` | optional | Filter by owning package |
 | **search** | `string` | optional | Full-text search query |
@@ -202,6 +202,7 @@ const result = MetadataBulkRegisterRequest.parse(data);
 * `function`
 * `service`
 * `email_template`
+* `doc`
 * `permission`
 * `profile`
 * `role`

content/docs/references/system/doc.mdx

@@ -0,0 +1,68 @@
+---
+title: Doc
+description: Doc protocol schemas
+---
+
+{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}
+
+Package Documentation Metadata Protocol (ADR-0046)
+
+One `doc` item per Markdown file under the package's flat `src/docs/`
+
+directory (no subdirectories — flatness is the contract that keeps
+
+cross-references stable). The CLI compiles each file into this shape at
+
+build time; TS-first stacks may also declare items inline via
+
+`defineStack(\{ docs: [...] \})`.
+
+Identity model: `name` = filename stem and MUST carry the package
+
+namespace prefix (`crm_lead_guide.md` → `crm_lead_guide`). Unlike object
+
+names (validated in the kernel because they map to physical table
+
+names), doc-name prefixing is a *logical* uniqueness requirement — the
+
+metadata registry key carries no package coordinate — so it is enforced
+
+by build/publish lint, not by this schema.
+
+Docs are inert data: the kernel registers them without parsing
+
+`content`, and they participate in no runtime behavior. Renderers
+
+resolve relative links between docs (`[guide](./crm_lead_guide.md)`)
+
+by stripping `./` and `.md` to obtain the target doc name.
+
+<Callout type="info">
+**Source:** `packages/spec/src/system/doc.zod.ts`
+</Callout>
+
+## TypeScript Usage
+
+```typescript
+import { Doc } from '@objectstack/spec/system';
+import type { Doc } from '@objectstack/spec/system';
+
+// Validate data
+const result = Doc.parse(data);
+```
+
+---
+
+## Doc
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **name** | `string` | ✅ | Unique doc name (= filename stem, namespace-prefixed snake_case) |
+| **label** | `string` | optional | Display title; defaults to the first `#` heading, then the name |
+| **content** | `string` | ✅ | Raw Markdown content (CommonMark + GFM) |
+
+
+---
+

content/docs/references/system/index.mdx

@@ -16,6 +16,7 @@ This section contains all protocol schemas for the system layer of ObjectStack.
   <Card href="/docs/references/system/core-services" title="Core Services" description="Source: packages/spec/src/system/core-services.zod.ts" />
   <Card href="/docs/references/system/deploy-bundle" title="Deploy Bundle" description="Source: packages/spec/src/system/deploy-bundle.zod.ts" />
   <Card href="/docs/references/system/disaster-recovery" title="Disaster Recovery" description="Source: packages/spec/src/system/disaster-recovery.zod.ts" />
+  <Card href="/docs/references/system/doc" title="Doc" description="Source: packages/spec/src/system/doc.zod.ts" />
   <Card href="/docs/references/system/email-config" title="Email Config" description="Source: packages/spec/src/system/email-config.zod.ts" />
   <Card href="/docs/references/system/email-template" title="Email Template" description="Source: packages/spec/src/system/email-template.zod.ts" />
   <Card href="/docs/references/system/encryption" title="Encryption" description="Source: packages/spec/src/system/encryption.zod.ts" />

content/docs/references/system/meta.json

@@ -11,6 +11,7 @@
     "core-services",
     "deploy-bundle",
     "disaster-recovery",
+    "doc",
     "email-config",
     "email-template",
     "encryption",

content/docs/references/ui/page.mdx

@@ -78,10 +78,11 @@ Interface-level page configuration (Airtable parity)
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **source** | `string` | optional | Source object name for the page |
+| **sourceView** | `string` | optional | Named list view on the source object to inherit columns/filter/sort from (ADR-0047 iron rule: the page adds presentation policy only). Omit to use the object default view |
 | **levels** | `integer` | optional | Number of hierarchy levels to display |
 | **filterBy** | `Object[]` | optional | Page-level filter criteria |
 | **appearance** | `Object` | optional | Appearance and visualization configuration |
-| **userFilters** | `Object` | optional | User filter configuration |
+| **userFilters** | `Object` | optional | End-user quick-filter bar for this page (overrides the source view's userFilters) |
 | **userActions** | `Object` | optional | User action toggles |
 | **addRecord** | `Object` | optional | Add record entry point configuration |
 | **showRecordCount** | `boolean` | optional | Show record count at page bottom |

content/docs/references/ui/report.mdx

@@ -36,6 +36,7 @@ const result = JoinedReportBlock.parse(data);
 | **chart** | `Object` | optional |  |
 | **dataset** | `string` | optional | Dataset name to bind (ADR-0021) |
 | **rows** | `string[]` | optional | Dimension names down (dataset-bound) |
+| **columns** | `string[]` | optional | Dimension names across (matrix, dataset-bound) |
 | **values** | `string[]` | optional | Measure names to show (dataset-bound) |
 | **runtimeFilter** | `[__schema0](./__schema0)` | optional | Render-time scope filter (dataset-bound) |
 
@@ -54,8 +55,10 @@ const result = JoinedReportBlock.parse(data);
 | **type** | `Enum<'tabular' \| 'summary' \| 'matrix' \| 'joined'>` | ✅ | Report format type |
 | **dataset** | `string` | optional | Dataset name to bind (ADR-0021) |
 | **rows** | `string[]` | optional | Dimension names down |
+| **columns** | `string[]` | optional | Dimension names across (matrix) |
 | **values** | `string[]` | optional | Measure names to show |
 | **runtimeFilter** | `[__schema0](./__schema0)` | optional | Render-time scope filter |
+| **drilldown** | `boolean` | ✅ | Click-through to underlying records |
 | **chart** | `Object` | optional | Embedded chart configuration |
 | **aria** | `Object` | optional | ARIA accessibility attributes |
 | **performance** | `Object` | optional | Performance optimization settings |

content/docs/references/ui/view.mdx

@@ -16,8 +16,8 @@ Migrated to shared/http.zod.ts. Re-exported here for backward compatibility.
 ## TypeScript Usage
 
 ```typescript
-import { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, GalleryConfig, GanttConfig, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, NavigationConfig, NavigationMode, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, UserActionsConfig, ViewData, ViewFilterRule, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';
-import type { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, GalleryConfig, GanttConfig, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, NavigationConfig, NavigationMode, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, UserActionsConfig, ViewData, ViewFilterRule, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';
+import { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, GalleryConfig, GanttConfig, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, NavigationConfig, NavigationMode, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, UserActionsConfig, UserFilterField, UserFilters, ViewData, ViewFilterRule, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';
+import type { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, GalleryConfig, GanttConfig, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, NavigationConfig, NavigationMode, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, UserActionsConfig, UserFilterField, UserFilters, ViewData, ViewFilterRule, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';
 
 // Validate data
 const result = AddRecordConfig.parse(data);
@@ -50,7 +50,7 @@ Appearance and visualization configuration
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **showDescription** | `boolean` | ✅ | Show the view description text |
-| **allowedVisualizations** | `Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map'>[]` | optional | Whitelist of visualization types users can switch between (e.g. ["grid", "gallery", "kanban"]) |
+| **allowedVisualizations** | `Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart'>[]` | optional | Whitelist of visualization types users can switch between (e.g. ["grid", "gallery", "kanban"]) |
 
 
 ---
@@ -316,6 +316,40 @@ User action toggles for the view toolbar
 | **buttons** | `string[]` | optional | Custom action button IDs to show in the toolbar |
 
 
+---
+
+## UserFilterField
+
+Quick-filter field configuration
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **field** | `string` | ✅ | Field name on the source object (must exist — checked by reference diagnostics) |
+| **label** | `string` | optional | Display label override (defaults to the field label) |
+| **type** | `Enum<'select' \| 'multi-select' \| 'boolean' \| 'date-range' \| 'text'>` | optional | Filter control type. Omit to infer from the field definition |
+| **options** | `Object[]` | optional | Static options. Omit to derive from the field definition (select options / lookup records) |
+| **showCount** | `boolean` | optional | Show per-option record counts |
+| **defaultValues** | `string \| number \| boolean[]` | optional | Pre-selected values when the view loads |
+
+
+---
+
+## UserFilters
+
+End-user quick-filter configuration (Airtable "User filters" parity)
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **element** | `Enum<'dropdown' \| 'tabs' \| 'toggle'>` | ✅ | Filter control style: dropdown selectors per field, tab presets, or on/off toggles |
+| **fields** | `Object[]` | optional | Fields exposed as quick filters (dropdown/toggle elements) |
+| **tabs** | `Object[]` | optional | Named filter presets rendered as tabs (tabs element). Reuses ViewTabSchema |
+| **showAllRecords** | `boolean` | optional | Show an "All records" tab before the presets (tabs element) |
+
+
 ---
 
 ## ViewData
@@ -464,6 +498,7 @@ Visualization type that users can switch to
 * `timeline`
 * `gantt`
 * `map`
+* `chart`
 
 
 ---