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

[objectstack-fleet]

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

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 901e7cf13abd61afb4990ebc1e3b9cd36cf9b33d → packageMentionDocs.