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

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;

content/docs/concepts/meta.json

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

content/docs/concepts/north-star.mdx

@@ -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/ontology.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.