docs: positioning follow-up: home title, cover re-render, README on the four promises, Business Ontology page (#21591)

Fixes #21586

Clause-②: no

## What changed

Positioning follow-up after the slogan landed: the four inconsistencies
that pass left behind, the README restructured on the four promises, a
Business Ontology concept page, and the glossary and north-star bridges.
Docs only: no `packages/**`, no `content/docs/references/**`, no
`content/docs/releases/**`, no CHANGELOG. The only binaries touched are
the two cover images.

### Part A: inconsistencies

- A1 `apps/docs/app/[lang]/page.tsx`: `HOME_TITLE` is now "The ontology
is the software". Measured: one constant, four readers (document title
line 56, Open Graph title 67, Twitter card title 76, JSON-LD headline
112), so one edit moved all four.
- A2 `apps/docs/lib/site.ts`: `HERO_COVER.alt` is now the descriptor
sentence.
- A3 the hero cover is re-rendered on the new copy (headline, subhead,
chips Executable · AI-writable · Agent-operable · You own it ·
Apache-2.0). There was no design source, so the cover is now a
screenshot of a committed template:
`docs/screenshots/hero-cover-dark.html` rendered by
`docs/screenshots/render-hero-cover.mjs` with the preinstalled
Playwright Chromium (`@playwright/test` resolved from
`examples/app-showcase`, the one workspace package that declares it;
never `playwright install`). The master
`docs/screenshots/hero-cover-dark.png` is 2400x1200, 563,953 B;
`apps/docs/public/hero-cover-dark.webp` is derived from that PNG by
sharp 0.35.4 / libwebp 1.6.0 at quality 80, effort 6, as the provenance
block prescribes: 2400x1200, 85,472 B, 15.2% of the PNG. The provenance
block on `HERO_COVER` records the new bytes and names the template; the
declared 2400x1200 is unchanged and matches both files. The dashboard on
the right is a simplified CSS card, because the repo holds no standalone
dashboard screenshot (the old one was baked into the previous master)
and the card allows no new binary. The script refuses to overwrite the
committed files when the web fonts (Inter, IBM Plex Mono, from Google
Fonts) did not load, so an offline render cannot ship the system
fallback silently; `--out DIR` previews without touching them.
- A4 glossary UI Protocol entry: "Themes" dropped. Evidence read first:
`packages/spec/src/migrations/entries/semantic/18.stack-themes-carrier-retired.ts`.

### Part B: README

- Hero: the slogan, the English descriptor, `本体即软件。` as the one Chinese
line, and the proof line "Apps small enough for AI to hold whole." The
Chinese descriptor sentence is removed per the PM ruling for this card
(no README.zh-CN.md).
- Chips: Executable · AI-writable · Agent-operable · You own it ·
Apache-2.0.
- New section "What we mean by ontology" (three sentences plus links to
the concept page and the glossary entry), placed right before the
capability section.
- Order: Try it in five minutes, What we mean by ontology, The runtime
runs it (was "What one definition gives you", body unchanged), Agents
are the first users (was "Your app is AI-operable, for free", moved up,
opened with the objects-are-tools sentence, `claude mcp add` snippet
kept), Why the mistakes don't ship (body unchanged), You own it (the
LICENSING sentence from under the video and the blog quote
consolidated), Ship it, Hack on the framework.
- Anchor sweep for the two renamed headings: `grep -rn "README.md#"
content/docs apps/docs README.md` hit 0; a `git grep` of all six section
slugs across the whole tree hit 0. Nothing to update;
`check:published-readme-links` and `check:doc-anchors` are green.

### Part C: docs site

- C1 `content/docs/index.mdx`: the first paragraph is the slogan and the
descriptor, with one sentence linking the concept page; the frontmatter
description is aligned; the build-loop diagram and the rest are
unchanged.
- C2 `content/docs/concepts/ontology.mdx` (new): what the ontology is,
what the projections are, what it is not, how the runtime executes it,
how AI writes it and uses it. Registered in
`content/docs/concepts/meta.json` right after `metadata-driven`, and in
`scripts/docs-audit/handwritten-docs.json`, because
`check:docs-audit-scope` reds on a hand-written page the ledger does not
list (regenerated with the gate's own `--write`; that file is the one
path outside the card's named surface).
- C3 glossary Business Ontology entry: 44 lines to 13; the definition
paragraph is six lines ending in the link to the page, followed by a
short paragraph holding the knowledge-ontology sentence, the industry
semantic-layer sentence and the existing analytics-dataset sentence side
by side.
- C4 `content/docs/concepts/north-star.mdx`: the one bridge sentence,
nothing else.

The four facts are present in every piece of copy that explains the word
(README "What we mean by ontology", the ontology page, the glossary
entry): no object inheritance, axioms or reasoner; not a semantic layer
over existing systems; views, dashboards, apps and translations are
projections; code does not disappear, it moves into the runtime. No
retained figure was added.

## Verification (head 7a49e29, clean tree)

- `pnpm --filter @objectstack/spec build` under the verify lock: VERDICT
command-exit 0 (97s). `pnpm --filter @objectstack/docs build`: VERDICT
command-exit 0 (173s; "Compiled successfully", "Finished TypeScript in
5.9s"; `ignoreBuildErrors: false`, so the build is the docs app's type
check). No tracked generated file moved after the build (`git status`
clean).
- Doc gates re-run on 7a49e29, all exit 0: `check:nul-bytes`,
`check:doc-anchors`, `check:doc-authoring`, `check:docs-single-h1`,
`check:docs-transcript-drift`, `check:published-readme-links`,
`check:docs-redirects`, `check:docs-locale-catch-all`,
`check:page-declaration-shape`, `check:docs-audit-scope`,
`check:corpus-claim-drift`, `check:docs-spec-enumerations`,
`check:role-word`, `check:published-files`, `check-docs-nav-label`,
`check-docs-section-name`, `check-doc-frontmatter`,
`check-doc-route-spelling --advisory`, `check-section-landing-index`,
`check-undeclared-dep-imports`, lint `check:doc-formula-expressions`,
lint `check:doc-security-posture`.
- Spec package gates (spec dist rebuilt first; `check:skill-examples`
additionally needed `@objectstack/client-react` built): `check:docs`,
`check:empty-state`, `check:liveness`, `check:skill-examples` (260 prose
examples type-check), `check:strictness-ledger`, `check:variant-docs`,
`check:yaml-examples`, all exit 0.
- `scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 68 families from the change set;
every one was run with its exit captured before any pipe and reconciled
with `--ran`. Three gates first answered exit 3 PREREQUISITE NOT MET
(`@objectstack/lint` / `@objectstack/formula` not built) and were re-run
green after the build; those first answers are not measurements.
- Narrowed eslint, a measurement with its three pieces: `pnpm exec
eslint --no-inline-config --format json` over the three changed JS/TS
files (`render-hero-cover.mjs`, `site.ts`, `page.tsx`) reports 3 files,
0 errors, 0 warnings; the population is the config's generic block
`files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}']`, which covers all
three; the config is not type-aware (no `parserOptions.project`), so
this diff cannot move any untouched file's verdict. The whole-tree `pnpm
lint` stays CI's.
- Changeset: nothing publishes. `packages/**` is untouched (measured on
the diff against `origin/main`), so `skip-changeset` applies.

## Acceptance notes

- The docs home page's own chip row (`page.tsx`, the three `span`
elements near line 261: "Fits in an agent's context", "Typed, validated,
governed", "Self-host anywhere") still carries the pre-slogan chips,
directly above the poster whose chips are now the four promises. The
card does not name it, so it is left as is. Carrier: the next
positioning pass.
- PM mechanism assumptions, measured: the README-anchor grep hit 0, not
"several"; sharp in the closure is 0.35.4 (the provenance block said
0.35.3; now recorded as 0.35.4); Playwright resolves from
`examples/app-showcase`, not from `packages/qa` or `apps/docs`;
`HOME_TITLE` had exactly the four readers named.
- Two small departures from the card's letter, both toward C2's "the
page is the authority": the README's "What we mean by ontology" links
the concept page first and the glossary entry second; `index.mdx`'s
first paragraph carries one link sentence after the slogan and
descriptor.
- Out of git, for the maintainer (the card's own note): the repository
description field and the 90-second video narration still carry the old
tagline.

---
_Generated by [Claude
Code](https://claude.ai/code/session_011hRnra93sK5Q2gTYYTbdJR)_

---------

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

Author: objectstack-fleet[bot]

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:
 

content/docs/concepts/north-star.mdx

@@ -0,0 +1,100 @@
+---
+title: Business ontology — the executable definition the runtime runs
+navTitle: Business Ontology
+description: "What ObjectStack means by business ontology: the executable definition the runtime runs, its projections, what it is not, and how AI writes and uses it."
+---
+
+**The ontology is the software.** One executable business ontology. AI writes it, the
+runtime runs it, agents operate it, you own it. This page is the authority on what that
+word means here; the [glossary entry](/docs/getting-started/glossary#business-ontology)
+is the short form.
+
+## What the ontology is
+
+The ontology is the definition of your business that the runtime executes: authored as
+typed metadata in `objectstack.config.ts`, compiled into the `objectstack.json` artifact.
+Its core is six kinds of thing:
+
+| Core | What it declares |
+| :--- | :--- |
+| **Objects and fields** | The entities of the business and their typed attributes — validation, formulas, defaults, files |
+| **Relations** | Lookups and master-detail links between objects |
+| **Actions** | The operations a user or an agent may invoke on a record, and the conditions under which they show |
+| **Permissions** | Who may read, create, edit and delete what — RBAC, row-level and field-level security, sharing |
+| **Flows** | The business processes — DAG flows, record triggers, scheduled jobs, approvals, workflows |
+| **Agent and tool definitions** | The AI agents the app ships with, the tools they may call, and the skills that shape them |
+
+It is one definition, open and versioned. It lives in your repository as ordinary
+TypeScript, is reviewable as a diff, and is specified and licensed Apache-2.0 — not a
+graph held inside a vendor's system and reachable only through that vendor's console.
+The runtime derives everything else from it.
+
+## What the projections are
+
+Views, dashboards, apps, and translations are **projections** of the ontology — authored
+in metadata too, validated by the same gate, but not part of the ontology. A list view
+projects an object's fields and permissions onto a grid; a dashboard projects queries over
+objects onto charts; an app groups objects, views and actions into a navigable product; a
+translation projects every label into a locale. Change the core and the projections
+follow; remove a projection and the business it showed is unchanged. The distinction
+bounds what an agent must hold to reason about the business: the core, not every screen.
+
+## What it is not
+
+- **Not a knowledge ontology.** OWL, RDF and knowledge graphs *describe* a domain, carry
+  class inheritance and axioms, and are *reasoned over* by an inference engine.
+  ObjectStack has no object inheritance, no axioms and no reasoner: the definition is
+  *validated* — by Zod schemas and `os validate` — and then *run*. The `abstract` key was
+  removed from the spec for exactly that reason (ADR-0049).
+- **Not the industry's semantic layer.** A semantic layer is a read-only mapping over
+  existing systems: it describes the business but does not run it. ObjectStack's ontology
+  *is* the system — the database, API, UI and agent tools are derived from it. Federating
+  an external datasource is possible, read-only by default and early; see
+  [External Datasources](/docs/data-modeling/external-datasources). These docs also use
+  *semantic layer* in a narrower sense, for the analytics `dataset` layer that reports and
+  dashboards bind to; see [Analytics & Datasets](/docs/data-modeling/analytics).
+- **Not a formal ontology in the philosophical sense.** It makes no claim about what
+  exists in general. It is one business's application, defined precisely enough to run.
+
+## How the runtime executes it
+
+```text
+objectstack.config.ts -> objectstack.json -> ObjectStack runtime -> database · REST / realtime API · UI · MCP server
+```
+
+From the compiled artifact the runtime **derives** the database schema on an
+interchangeable driver, a generated REST and realtime API, server-driven UI for the
+Console, and an MCP server — and it **enforces** the definition on every call. RBAC,
+row-level and field-level security, sharing, and audit apply to a REST request, a Console
+click and an agent's tool call alike. Nothing is reasoned over at runtime: what runs is
+what was validated.
+
+Code does not disappear — it moves into the runtime. Hooks, action bodies, and the CEL
+expressions in formulas, predicates and policies run inside the runtime's permission and
+audit fence; constrained JSX in pages is parsed into a server-driven UI tree, never
+executed as code. None of it is scattered across a codebase the ontology would then have
+to describe. [Protocol Architecture](/docs/concepts/architecture) covers the layers;
+[Metadata-Driven Development](/docs/concepts/metadata-driven) shows what one definition
+derives.
+
+## How AI writes it and uses it
+
+**Writing it.** The scaffolder installs the AI skills bundle and writes an `AGENTS.md`, so
+a coding agent starts with the protocol's rules loaded rather than generic priors. The
+agent writes the definition as typed metadata; strict TypeScript and Zod reject shape
+errors in the editor, and `os validate` rejects metadata that type-checks but would fail
+silently at runtime — dangling bindings, bad CEL predicates, a missing security posture —
+as located, corrective text the agent reads and fixes itself. You approve a small,
+readable diff in the Console. The loop end to end is
+[Build with Claude Code](/docs/getting-started/build-with-claude-code); why it is fast
+and safe is [How AI Development Works](/docs/getting-started/how-ai-development-works).
+
+**Using it.** The running app is an MCP server, on by default: every object is a tool,
+every exposed action is a tool, permissions decide what an agent may call, and audit
+records what it did. An agent operates the app through the same typed, permission-aware
+surface as a human — never raw SQL or scraped UI. See
+[Connect an MCP Client](/docs/ai/connect-mcp).
+
+Size is what makes both halves work. An app whose definition fits in one context window
+is one an agent can read whole, reason about whole, and refactor whole — apps small
+enough for AI to hold whole.