Merge remote-tracking branch 'origin/main' into claude/issue-21565-hook-family-target-refused

dropped-refinements.baseline.json: both sides' sites kept (main's
ui/ObjectFormProps entry and this branch's five hook sites); the measured
counts stack to 218 schemas and 659 sites. registry.ts merged without a
conflict; its generated regions are re-checked by the generator next.

Claude-Session: https://claude.ai/code/session_01YDt3PzwfrkuFzUBF89WPmM
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/21464-component-props-form-family-typed.md

@@ -0,0 +1,43 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: four members of an `object-form` page block take the shape the form reads instead of any value — `contentLayout`, `submitBehavior`, `navigateOnSuccess` and `mobile` (#21464)
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered ui-object-form-members-typed -->
+
+**BREAKING** — an accept-set narrowing on a published authoring surface, shipped as `minor` under the repo's launch-window convention for accept-set narrowings. What reads the row: the component-props gate on `objectstack validate`, `objectstack build` and `objectstack lint`, which reports a refused value as an advisory `component-props-invalid` / `component-props-unknown-key` finding. A stored page still saves and loads, because a page component's `properties` is not parsed on the metadata save or load path.
+
+**`@objectstack/spec`**
+
+- **Four members are typed.** `ComponentPropsMap['object-form']` declared `contentLayout`, `submitBehavior`, `navigateOnSuccess` and `mobile` as `z.unknown()`, although the form reads each with one shape. Any value passed, and an off-shape one was answered with a silent default: a `submitBehavior` whose `kind` the form does not know showed the thank-you panel; a misspelled `contentLayout` stacked the modal's sections; a `navigateOnSuccess` that is not a string failed the submit after the record had been written; a misspelled `mobile` member was ignored.
+- **`submitBehavior` is the form view's own block, by reference** — `{ kind: 'thank-you', title?, message? }`, `{ kind: 'redirect', url, delayMs? }`, `{ kind: 'continue' }` or `{ kind: 'next-record' }` — with the same rule on a `redirect` `url` a form view carries: a relative path, interpolating declared record fields as `{{record.field_name}}`.
+- **The measured shape, where no form view declares the member:** `contentLayout` is `'simple'` or `'tabbed'`; `navigateOnSuccess` is a relative path string (`{id}` / `{recordId}` interpolate the saved record's id); `mobile` is `{ stickyActions?, stepper?, stepperMinFields?, stepperFieldsPerStep?, fullscreenLongText? }`, with `stepper` `true`, `false` or `'auto'` and the two counts positive integers.
+- **`ObjectFormProps`** carries these types on the four members instead of `unknown`.
+- **The form's `fields` and `sections`, and the master-detail form's `fields` and `sections`, are not narrowed** and still accept any value. The form draws a top-level `fields` entry written as `{ name }` by that name, and it draws an inline runtime field (`{ name, type, … }`) written inside a section's `fields` as it stands — two shapes the typed members (field-name strings; the form view's section, whose field entry is keyed by `field`) would refuse. Each is held until that read is ruled. The master-detail form hands both members to its form unchanged, so they are held with the form's.
+- **`customFields` is not narrowed either.** Its entries are the console's runtime form field (keyed by `name`), which the spec has not declared; it is typed once the spec declares it.
+
+## FROM → TO
+
+| you wrote on an `object-form` | write instead |
+|:--|:--|
+| `submitBehavior: 'thank-you'` | `submitBehavior: { kind: 'thank-you' }` |
+| `submitBehavior: { kind: 'toast' }` (any `kind` outside the four) | one of `thank-you`, `redirect`, `continue`, `next-record` |
+| `submitBehavior: { kind: 'thank-you', heading: 'Done' }` | `{ kind: 'thank-you', title: 'Done' }` |
+| `submitBehavior: { kind: 'redirect', url: 'https://app.example.com/done' }` | a relative path: `url: '/done'` |
+| `contentLayout: 'tabs'` | `contentLayout: 'tabbed'` |
+| `navigateOnSuccess: { url: '/orders/{id}' }` | `navigateOnSuccess: '/orders/{id}'`, or `submitBehavior: { kind: 'redirect', url: '/orders/{{record.id}}' }` |
+| `mobile: { stepper: 'yes' }` | `mobile: { stepper: true }`, or `'auto'` for phone-width viewports only |
+| `mobile: { stepperFieldsPerStep: 0 }` | delete the key (one field a step is the default), or a positive integer |
+
+The one-line fix: write each member as the table above shows. No conversion is registered, because an off-shape value has no rewrite that both keeps what the form shows today and honours what the author wrote; the D3 entry `ui-object-form-members-typed` carries that judgment.
+
+## Who is affected, measured
+
+A writer is a page-component node: an object literal naming the type, a literal annotated with the block's type, a `schema={{…}}` on the block's React component, a call into a local helper that builds the node, or a direct parse through the row. Each member's value is read through same-file constants and local helpers. The control is `objectName` on the same nodes.
+
+- **objectstack** at `e909aa0a23`, over `examples/`, `packages/` (with `packages/apps/`), `content/`, `skills/` and `apps/`: 16 `object-form` nodes (the control on 13). Three values among the four members: the showcase's new-project wizard `submitBehavior` (a thank-you panel) and two copies of it in the lint and spec tests. All three parse.
+- **objectui** at the `.objectui-sha` pin `89cad75d55`: 539 `object-form` nodes (the control on 522). Across the four members there are 73 values: 60 are static, and 56 of them parse. The 4 that do not are test fixtures of a protocol-relative redirect (`//example.com/thanks`), each asserting that the form refuses it and navigates nowhere. Of the 13 values that are not static, 9 are relative redirects that parse by inspection, and 4 are redirect fixtures the form refuses (three same-origin absolute URLs and one protocol-relative one). No refused value is one the form draws.
+- **Deployed metadata** was not measured.

README.md

@@ -9,22 +9,11 @@
 > **One executable business ontology.** AI writes it, the runtime runs it, agents
 > operate it, you own it.
 >
-> 本体即软件。一份可执行的业务本体。AI 写，运行时跑，Agent 用，归你所有。
+> 本体即软件。
 >
-> ObjectStack turns the whole app — data model, UI, workflows, permissions —
-> into typed metadata that fits in a single context window: apps small enough
-> for AI to hold whole. Agents read it whole, reason it whole, refactor it whole.
->
-> That metadata is your **business ontology** — an open, versioned definition of
-> your objects, relations, actions, permissions, flows, and agent and tool
-> definitions that you own, not code scattered across a framework. It is
-> executable, not a knowledge-representation ontology: no inheritance, no
-> axioms, no reasoner. Strict TypeScript, Zod schemas, and a validation gate
-> catch the agent's mistakes at authoring time; the runtime derives the
-> database, REST API, UI, and MCP server, and enforces permissions and audit on
-> every call.
+> Apps small enough for AI to hold whole.
 
-`Fits in an agent's context` · `Typed, validated, governed` · `Self-host anywhere` · Apache-2.0
+`Executable` · `AI-writable` · `Agent-operable` · `You own it` · Apache-2.0
 
 <p align="center">
   <a href="https://youtu.be/CX_FlOoOtr0">
@@ -34,11 +23,9 @@
   <a href="https://youtu.be/CX_FlOoOtr0"><b>▶&nbsp; Watch: ObjectStack in 90 Seconds</b></a>
 </p>
 
-**Everything in this repo is the open stack** — protocol, microkernel, SDK,
-CLI, and the production runtime, Apache-2.0 with no open-core asterisks
-([LICENSING.md](./LICENSING.md)). You build & ask with Claude Code or any coding
-agent: the agent writes the metadata in your repo and operates the running app
-over MCP. Want the same loop hosted, in the browser, nothing to install? That's
+You build & ask with Claude Code or any coding agent: the agent writes the
+metadata in your repo and operates the running app over MCP. Want the same loop
+hosted, in the browser, nothing to install? That's
 [ObjectOS](https://www.objectos.ai), the commercial runtime environment built on
 this stack.
 
@@ -87,7 +74,21 @@ No install at all? Open a live app on
 </p>
 <p align="center"><sub>Prefer clicking? Studio authors the same metadata visually — same artifacts, same gate.</sub></p>
 
-## What one definition gives you
+## What we mean by ontology
+
+Your app's definition — objects and fields, relations, actions, permissions,
+flows, and agent and tool definitions — is a **business ontology**: open,
+versioned, and yours, not code scattered across a framework. It is executable,
+not a knowledge-representation ontology: no inheritance, no axioms, no reasoner —
+validated rather than reasoned over — and it is not a semantic layer over your
+existing systems (federating an external datasource is read-only by default and
+early). Views, dashboards, apps, and translations are projections of the
+ontology, not part of it, and code does not disappear: it moves into the
+runtime, as hooks, action bodies, CEL, and constrained JSX. The full account is
+[Business Ontology](https://objectstack.ai/docs/concepts/ontology); the short
+form is the [glossary entry](https://objectstack.ai/docs/getting-started/glossary#business-ontology).
+
+## The runtime runs it
 
 Point an agent at an empty repo and you get a one-off codebase: every screen
 hand-invented, every mistake yours to find at runtime. ObjectStack gives the
@@ -144,6 +145,24 @@ curl http://localhost:3000/api/v1/data/support_desk_ticket
 In the browser, the typed client SDK and React hooks (`useQuery`, `useMutation`,
 `usePagination`) live in [`@objectstack/client-react`](packages/client-react).
 
+## Agents are the first users
+
+Objects are tools, actions are tools, permissions decide what an agent may call,
+and audit records what it did. Because the app is typed metadata, the runtime
+serves it as an **MCP server** at `/api/v1/mcp` — on by default. Point any MCP
+client at it and an agent can inspect and *operate* the app you just built,
+under the same permissions and RLS as a human:
+
+```bash
+claude mcp add --transport http my-app http://localhost:3000/api/v1/mcp
+```
+
+The first tool call opens a browser to sign you in — each deployment is its own
+OAuth server, so there's no token to copy-paste. Headless setups (CI,
+containers) use an API key instead. Objects are exposed automatically; actions
+opt in with `ai: { exposed: true }`. See
+[Connect an MCP Client](https://objectstack.ai/docs/ai/connect-mcp) for both flows.
+
 ## Why the mistakes don't ship
 
 "AI writes it" is only useful if AI's mistakes don't reach production. Four gates
@@ -171,35 +190,18 @@ hoping. Measure it yourself:
 find examples/app-crm/src -name '*.ts' -not -name '*.test.ts' | xargs cat | wc -l
 ```
 
+## You own it
+
+**Everything in this repo is the open stack** — protocol, microkernel, SDK,
+CLI, and the production runtime, Apache-2.0 with no open-core asterisks
+([LICENSING.md](./LICENSING.md)). The definition lives in your repository as
+ordinary TypeScript, versioned in your VCS and reviewable as a diff — not a
+graph held inside a vendor's system.
+
 > The ontology is the software. Your objects, relations, actions, permissions,
 > flows, and agent and tool definitions are your business ontology — and the
 > definition layer of the AI era should be an open protocol you own.
 > [Read why](https://www.objectos.ai/en/blog/ai-ontology-open-protocol/).
->
-> What that does and does not mean: the ontology is *executable*, so it is
-> validated rather than reasoned over — there is no object inheritance, no
-> axioms and no reasoner. It is not a semantic layer over your existing systems
-> (federating an external datasource is read-only by default and early). Views,
-> dashboards, apps, and translations are projections of the ontology, not part
-> of it. And code does not disappear: it moves into the runtime — hooks, action
-> bodies, CEL, and constrained JSX.
-
-## Your app is AI-operable, for free
-
-Because the app is typed metadata, the runtime serves it as an **MCP server** at
-`/api/v1/mcp` — on by default. Point any MCP client at it and an agent can
-inspect and *operate* the app you just built, under the same permissions and RLS
-as a human:
-
-```bash
-claude mcp add --transport http my-app http://localhost:3000/api/v1/mcp
-```
-
-The first tool call opens a browser to sign you in — each deployment is its own
-OAuth server, so there's no token to copy-paste. Headless setups (CI,
-containers) use an API key instead. Objects are exposed automatically; actions
-opt in with `ai: { exposed: true }`. See
-[Connect an MCP Client](https://objectstack.ai/docs/ai/connect-mcp) for both flows.
 
 ## Ship it
 

apps/docs/app/[lang]/page.tsx

@@ -31,7 +31,7 @@ const mono = IBM_Plex_Mono({
   variable: '--font-l-mono',
 });
 
-const HOME_TITLE = 'Metadata framework for AI-written apps';
+const HOME_TITLE = 'The ontology is the software';
 const HOME_DESCRIPTION =
   'One executable business ontology. AI writes it, the runtime runs it, agents operate it, you own it. The whole app — data model, UI, workflows, permissions — is typed metadata small enough for AI to hold whole.';
 
@@ -258,11 +258,13 @@ export default function HomePage() {
             className="mt-8 flex flex-wrap items-center justify-center gap-x-3 gap-y-2 text-[13px] text-fd-muted-foreground"
             style={{ fontFamily: 'var(--l-mono)' }}
           >
-            <span>Fits in an agent&apos;s context</span>
+            <span>Executable</span>
             <span aria-hidden className="text-fd-border">|</span>
-            <span>Typed, validated, governed</span>
+            <span>AI-writable</span>
             <span aria-hidden className="text-fd-border">|</span>
-            <span>Self-host anywhere</span>
+            <span>Agent-operable</span>
+            <span aria-hidden className="text-fd-border">|</span>
+            <span>You own it</span>
           </div>
         </section>
 

apps/docs/lib/site.ts

@@ -60,16 +60,20 @@ export function absoluteUrl(path: string): string {
  *
  * ## Provenance — how to re-encode it
  *
- * The master is `docs/screenshots/hero-cover-dark.png` (2400x1200, 406,703 B),
+ * The master is `docs/screenshots/hero-cover-dark.png` (2400x1200, 563,953 B),
  * which the README embeds directly from the repo and which is NOT served by this
- * site. This file is a lossy WebP derived from that master, and the derivation is
- * the whole reason it is small enough to sit above the fold:
+ * site. The master is itself a render of `docs/screenshots/hero-cover-dark.html`
+ * by `docs/screenshots/render-hero-cover.mjs` (the preinstalled Playwright
+ * Chromium), so a copy change is an edit to that template and one re-render —
+ * the script performs the derivation below as its second step. This file is a
+ * lossy WebP derived from that master, and the derivation is the whole reason it
+ * is small enough to sit above the fold:
  *
  *   sharp('docs/screenshots/hero-cover-dark.png')
- *     .webp({ quality: 80, effort: 6 })            // sharp 0.35.3 / libwebp 1.6.0
+ *     .webp({ quality: 80, effort: 6 })            // sharp 0.35.4 / libwebp 1.6.0
  *     .toFile('apps/docs/public/hero-cover-dark.webp')
  *
- * 83,272 B — 20.5% of the PNG. Re-encode from the master, never from this file:
+ * 85,472 B — 15.2% of the PNG. Re-encode from the master, never from this file:
  * a lossy re-encode of a lossy source compounds. And do not "restore" the PNG
  * alongside it — a `public/` holding both is how the next re-encode picks the
  * wrong one.
@@ -83,5 +87,5 @@ export const HERO_COVER = {
   url: '/hero-cover-dark.webp',
   width: 2400,
   height: 1200,
-  alt: 'ObjectStack — the metadata framework for AI-written apps',
+  alt: 'ObjectStack: the ontology is the software. One executable business ontology, written by AI, run by the runtime, operated by agents, owned by you.',
 } as const;

apps/docs/public/hero-cover-dark.webp

@@ -3,6 +3,7 @@
   "pages": [
     "architecture",
     "metadata-driven",
+    "ontology",
     "metadata-lifecycle",
     "design-principles",
     "north-star"

content/docs/concepts/meta.json

@@ -7,7 +7,8 @@ description: "Where ObjectStack is headed: a metadata-native backend that humans
 ObjectStack is the metadata-native backend for business software that humans and
 AI agents can both operate safely. The platform makes the business system
 explicit: data models, views, flows, permissions, actions, AI tools, and runtime
-requirements are typed metadata instead of scattered ad-hoc code.
+requirements are typed metadata instead of scattered ad-hoc code. In the
+enterprise-AI vocabulary, the ontology is the software.
 
 The goal is a small, inspectable, governed application surface: