docs: document the html/react page-authoring tiers (ADR-0080/0081) (#2473)

Author: os-zhuang

content/docs/guides/skills.mdx

@@ -48,7 +48,7 @@ ObjectStack ships **9 domain-specific skills**. Each is self-contained — an AI
 | 1 | [Platform](#platform) | `platform` | `skills/objectstack-platform/` | Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready` and `data:*`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). |
 | 2 | [Data](#data) | `data` | `skills/objectstack-data/` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seed datasets (`defineDataset()`) that load fixtures and reference data alongside them. |
 | 3 | [Query](#query) | `query` | `skills/objectstack-query/` | Construct ObjectQL queries — filters, sorting, pagination, aggregation, joins/expansion, window functions, and full-text search. |
-| 4 | [UI](#ui) | `ui` | `skills/objectstack-ui/` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages, Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). |
+| 4 | [UI](#ui) | `ui` | `skills/objectstack-ui/` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages (structured plus the HTML and React source-authoring tiers, ADR-0080/0081), Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). |
 | 5 | [Automation](#automation) | `automation` | `skills/objectstack-automation/` | Design ObjectStack automation — Flows (visual logic), Workflows (declarative rules), Triggers, Approvals, scheduled jobs, and webhooks. |
 | 6 | [AI](#ai) | `ai` | `skills/objectstack-ai/` | Design ObjectStack AI agents, tools, skills, conversations, model registry entries, and MCP integrations. |
 | 7 | [API](#api) | `api` | `skills/objectstack-api/` | Design the server-side API surface that an ObjectStack runtime exposes — REST/GraphQL endpoints, auth providers, realtime channels, error envelopes, batch/versioning contracts. |
@@ -103,7 +103,7 @@ Do not use for defining objects / fields / relationships (see objectstack-data)
 
 **Domain** `ui` · **Path** `skills/objectstack-ui/`
 
-Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages, Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`).
+Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages (structured plus the HTML and React source-authoring tiers, ADR-0080/0081), Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`).
 
 Use when the user is adding `*.view.ts` / `*.app.ts` / `*.dashboard.ts` / `*.action.ts` / `src/docs/*.md` files or designing a Studio-rendered UI surface, including dataset-bound dashboard/report widgets.
 

content/docs/protocol/objectui/layout-dsl.mdx

@@ -22,6 +22,32 @@ Instead of giving you infinite layout freedom (and infinite ways to break respon
 - **Accessibility:** Keyboard navigation and screen readers work automatically
 - **Maintainability:** Designers can't create 47 different button sizes
 
+## Authoring Modes: Structured, HTML, and React
+
+A page's `kind` selects **how** it is authored. This document describes the
+**structured** mode (regions + the 12-column grid below) — but for layouts the
+fixed schema can't express, two *source-authoring* tiers let an author (or AI)
+write the page body as a string. Pick by what the page needs:
+
+| `kind` | You write | JavaScript | Use when |
+|:-------|:----------|:-----------|:---------|
+| `full` / `slotted` *(this doc)* | structured `regions` / `slots` | — | record, detail, home, and app layouts from the component catalogue |
+| `html` | constrained JSX = HTML + Tailwind + registered components, **parsed, never executed** | none | free-form layout, landing pages, or dashboards that *compose* blocks — no interactivity |
+| `react` | **real React** (hooks, `.map`, `onClick`, expressions) | executed in the app | complex interactive business UIs — master/detail, wizards, state-driven filters |
+
+For `html` / `react`, the page body is the `source` string (it is the
+source-of-truth; `regions` is ignored). `html` is **safe by construction** (it
+is parsed into the same SDUI tree this document describes, never executed).
+`react` executes author code, so it is gated by a host capability that is **ON
+by default** and disabled per-deployment with the `OS_PAGE_REACT=off` env
+variable. Both tiers can embed the platform's real data components
+(`<ObjectTable>`, `<ObjectForm>`, charts, metrics).
+
+> **Learn more:** [ADR-0080](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0080-ai-authored-ui-jsx-source.md)
+> (the `html` tier — parse ≠ execute; the registry is the contract) and
+> [ADR-0081](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0081-trusted-react-page-tier.md)
+> (the trusted `react` tier). The rest of this page covers the structured mode.
+
 ## Layout Hierarchy
 
 ```

skills/README.md

@@ -19,7 +19,7 @@ authoritative Zod sources in `node_modules/@objectstack/spec/src/...`.
 | [Platform](./objectstack-platform/SKILL.md) | `platform` | Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready` and `data:*`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). |
 | [Data](./objectstack-data/SKILL.md) | `data` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seed datasets (`defineDataset()`) that load fixtures and reference data alongside them. |
 | [Query](./objectstack-query/SKILL.md) | `query` | Construct ObjectQL queries — filters, sorting, pagination, aggregation, joins/expansion, window functions, and full-text search. |
-| [UI](./objectstack-ui/SKILL.md) | `ui` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages, Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). |
+| [UI](./objectstack-ui/SKILL.md) | `ui` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages (structured plus the HTML and React source-authoring tiers, ADR-0080/0081), Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). |
 | [Automation](./objectstack-automation/SKILL.md) | `automation` | Design ObjectStack automation — Flows (visual logic), Workflows (declarative rules), Triggers, Approvals, scheduled jobs, and webhooks. |
 | [AI](./objectstack-ai/SKILL.md) | `ai` | Design ObjectStack AI agents, tools, skills, conversations, model registry entries, and MCP integrations. |
 | [API](./objectstack-api/SKILL.md) | `api` | Design the server-side API surface that an ObjectStack runtime exposes — REST/GraphQL endpoints, auth providers, realtime channels, error envelopes, batch/versioning contracts. |

skills/objectstack-ui/SKILL.md

@@ -2,7 +2,8 @@
 name: objectstack-ui
 description: >
   Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt),
-  Apps (navigation), Pages, Dashboards, Reports, Charts, Actions, and
+  Apps (navigation), Pages (structured plus the HTML and React source-authoring
+  tiers, ADR-0080/0081), Dashboards, Reports, Charts, Actions, and
   package Docs (`src/docs/*.md`). Use when
   the user is adding `*.view.ts` / `*.app.ts` / `*.dashboard.ts` /
   `*.action.ts` / `src/docs/*.md` files or designing a Studio-rendered UI