docs(blog): four hand-drawn SVG figures for 'The Ontology Is the Software' — three interfaces and one user, four places to one definition, the ontology-runtime architecture, the three routes — readable in both themes

立卡门类别 ③ — 维护者直派的任务 (maintainer-directed task).

Maintainer ruling (verbatim, untranslated)

基于这个核心叙事，官网是否应该做一个专门的页面？

或者 blog 中是否应该适当增加配图

同意

Given in session https://claude.ai/code/session_011hRnra93sK5Q2gTYYTbdJR on 2026-10-12. The seat recommended figures in the existing essay over a new dedicated page (the essay is already the canonical statement that the README, the ontology concept page and the compare page point at; its weakness is being text only; a second page would split one narrative across three places), and the maintainer agreed. No dedicated page is part of this card.

What lands

Four figures added to content/blog/the-ontology-is-the-software.mdx, each placed after the paragraph that states its idea, each with a one-line italic caption under it and an accessible title and description. The prose is not rewritten; only the figures and their captions are added. The frontmatter (title, description, author, date, tags) does not change.

#	Section of the essay (heading on main)	Figure	What it shows
1	`## Why now`	Three interfaces, one user	A timeline of three eras: terminals and forms (people adapted to the software), web and mobile (the software adapted to people), a conversation box (the software disappears into language); beneath them one band spanning all three, "the user was a person: the API written for a programmer, the documentation for a reader, the audit log for an auditor"; then a fourth, highlighted column: the agent, the first new user in forty years
2	`## What an enterprise actually wants to say`	Four places to one definition	Four source boxes on the left (in veterans' heads; in policy documents; in spreadsheets; in a few hundred thousand lines of code) joined by a bus into one dark box on the right, "One definition", listing its five parts: what we have, how it relates, what can be done, who may do it, what happens when
3	`## Why code recedes`	The ontology runs	The architecture: a large model writes the ontology (and what is written wrong does not ship), people define and approve it, the ontology (the enterprise's definition of itself, five parts) is run directly by the runtime (every call permission-checked and audited), agents call the runtime, and database, API, UI and the tools agents call all derive from the ontology
4	`## What it is not`	Three routes for enterprise knowledge	Train it into the model (knowledge in the weights: change a rule, retrain; nothing to inspect; change the model, lose it all); keep it outside as a manual (knowledge graph or semantic layer: the model reads a description, acting needs another system, permissions yet another); keep it outside and it runs (ontology plus runtime: the model reads and writes it, the system runs it, agents act through it)

The visual reference is the English deck's slides, which already draw these four pictures at 1920 x 1080 with inline styles; they are HTML in this container, readable by the developer, and are the source of the layout, labels and colour roles (not of the pixels: this card wants SVG drawn for the page, never screenshots):

/tmp/claude-0/-home-user-objectstack/1ddacfa2-cbe3-50df-b1b3-5e4cbf5ac646/scratchpad/deck-ontology-en/project/slides/interfaces.html (figure 1)
/tmp/claude-0/-home-user-objectstack/1ddacfa2-cbe3-50df-b1b3-5e4cbf5ac646/scratchpad/deck-ontology-en/project/slides/scattered.html (figure 2)
/tmp/claude-0/-home-user-objectstack/1ddacfa2-cbe3-50df-b1b3-5e4cbf5ac646/scratchpad/deck-ontology-en/project/slides/thesis.html (figure 3)
/tmp/claude-0/-home-user-objectstack/1ddacfa2-cbe3-50df-b1b3-5e4cbf5ac646/scratchpad/deck-ontology-en/project/slides/routes.html (figure 4)

Mechanism, with what was measured

Both themes. The docs app switches theme with next-themes through fumadocs' RootProvider (apps/docs/app/[lang]/layout.tsx); apps/docs/components/mermaid.tsx reads resolvedTheme to re-render. The blog article body is prose prose-neutral dark:prose-invert (apps/docs/app/[lang]/blog/[[...slug]]/page.tsx). A figure must read correctly under that toggle, not under the OS preference: an SVG loaded through an img tag cannot follow the page's class, so the expected shape is inline SVG rendered by a React component registered in apps/docs/mdx-components.tsx beside Mermaid, with colours from currentColor and a small set of CSS custom properties or Tailwind dark: classes. Text in the figures at or above 4.5:1 contrast against its background in both themes, measured, not assumed.
The link lane. .github/workflows/check-links.yml runs lychee --offline with --root-dir at content/, so a root-relative /figures/x.svg reference in the MDX would resolve to content/figures/x.svg and go red (the same reason the deck PDF link in this essay is absolute). Inline figures have no link to check; if a file reference is used anywhere, it is absolute.
Fonts. Figures inherit the page's font stack (the prose column's), no font files, no web-font requests of their own.
Width. Each figure sits in the prose column with a viewBox and 100 percent width, legible at phone width (the three-column figures may stack or scale; the author decides, and says which, with a measurement at 390 px).
Captions. One italic line under each figure, the essay's register, no superlatives.
check:docs-image-tag is about Docker image tags, not pictures; it will run because the file surface touches content/, and it is not affected by this card.

Guardrails for the author

File surface: content/blog/the-ontology-is-the-software.mdx (figure placements and captions only), new files under apps/docs/components/ for the figures, and apps/docs/mdx-components.tsx for the registration. No packages/**, no content/docs/**, no README.md, no apps/docs/public/**, no CHANGELOG, no binaries.
English only. No model identifiers anywhere.
Every label in a figure is a phrase the essay or the deck already uses; no new claims, no numbers.
Build the docs app and open the essay in both themes with the preinstalled Chromium (never playwright install): report the four figures' rendered sizes at 1280 px and 390 px, and the measured text contrast in both themes.
Gates derived with scripts/pm/dispatch-gates.mjs from the real change set, every one run; the docs build (pnpm --filter @objectstack/docs build) under scripts/pm/os-verify-lock.sh must pass.
Changeset: nothing publishes; skip-changeset once packages/** is confirmed untouched.
Serial constraint: PR docs(site): refresh the English deck PDF under apps/docs/public/decks to the 19-slide version #22942 (the deck PDF refresh, in flight, apps/docs/public/decks/ only) does not touch these files; no other open PR touches the essay or apps/docs/components/.

Non-goals

A dedicated narrative page on the site (decided against for now; revisit after the talk).
The landscape figure (four cells) on the compare page; a later card if wanted.
Changes to the deck, the README, the home page, or the Chinese site (objectos.ai is a separate project).

Who acts

domain:devx lane, this seat, one os-dev dispatch at the derived tier, one draft PR. Precedent on the same page: #22263 via PR #22264 (the deck link at the end of the essay); precedent for a client-rendered figure component: apps/docs/components/mermaid.tsx.

Duplicate check (2026-10-12, open and closed)

Query "blog essay figures diagrams SVG illustrations the ontology is the software dark mode": 3 hits — docs(north-star): align the compass with the 'ontology is the software' positioning — identity line, two user classes, promise-to-step mapping, the 'you own it' row, rule 4 wording (Tier H, maintainer-directed) #22172, docs: publish 'The Ontology Is the Software' on the blog, add a Blog entry to the docs nav and home, point README's 'Read why' at it, and bridge the two 2024 posts #21838, docs: adopt the 'Ontology is the software' positioning across README, docs landing page and glossary #21574, all closed positioning work; none adds a figure.
Query "docs site inline SVG figure MDX component image in blog post": 0 hits.

Generated by Claude Code

Claim: PM loop round 4
Session: session_011hRnra93sK5Q2gTYYTbdJR
Account: hotlong (the seat's linked user; the card's assignee)
Branch: claude/issue-22948-blog-figures
Worktree: objectstack-issue-22948
Domain: domain:devx
Seat: domain:devx#2
File surface: content/blog/the-ontology-is-the-software.mdx, apps/docs/components/figures/ (new), apps/docs/mdx-components.tsx (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus (default tier; dispatch-gates --tier: no path-derived mandate, "the surface hits none of the 3 declared glob(s)")
Clause-②: no
Thread-read: none
Serial constraints cleared: PR #22942 (deck PDF refresh, in flight) touches apps/docs/public/decks/ only; no open PR touches the essay or apps/docs/components/

os-dev-report

{
 "issue": 22948,
 "status": "done",
 "branch": "claude/issue-22948-blog-figures",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/22958",
 "session": "session_011hRnra93sK5Q2gTYYTbdJR — this run's harness-stamped id (container CLAUDE_CODE_REMOTE_SESSION_ID cse_011hRnra93sK5Q2gTYYTbdJR; mode:subagent, the parent's)",
 "premise_still_valid": true,
 "summary": "Four inline SVG figures are added to the essay through new server components in apps/docs/components/figures/ (a shared drawing kit plus one file per figure), registered in apps/docs/mdx-components.tsx and placed in the four ruled sections, each with a one-line italic caption; the prose and frontmatter are unchanged (essay diff +8/-0). Each figure draws a wide layout from lg (1024 px) up and a stacked one below it, capped at 440 px, rather than scaling, because the wide drawing scaled to 390 px would set its text at about 5 px. Every colour is a Tailwind light/dark class pair, so the figures follow the site's dark class, not the OS preference (measured with the OS set opposite, and through the site's own Toggle Theme). All mechanism assumptions held on the branch: RootProvider plus next-themes, mermaid's resolvedTheme, the prose article container, the mdx-components registration point, zero images in content/blog (control: 8 headings matched in the same file), lychee --offline --root-dir content/, check:docs-image-tag concerning Docker tags, and no font loaded by app/layout.tsx. One refinement to the card's mechanism text: the article's prose-neutral and dark:prose-invert classes compile to no CSS under fumadocs' typography plugin. Figure 1 sits at the end of Why now, after the Karpathy paragraph, as ruled; its idea is stated in the essay's opening paragraphs, which the PR notes. Conflict with the standard text, flagged rather than silently resolved: the dispatch asked for a robot-emoji 'Generated with' line plus a session link to close the PR body, while os-dev.md prescribes the session-URL footer block and says it governs on conflict. The body ends with the os-dev.md footer and carries the session link in its prose.",
 "tests": "At HEAD fa8dda48. (1) pnpm --filter @objectstack/docs build under os-verify-lock: 'VERDICT command-exit 0 · held the lock 100s'; '✓ Compiled successfully in 30.4s'; '● /en/blog/the-ontology-is-the-software' prerendered; git status clean after the spec generators. An earlier build at f653e749 also gave VERDICT command-exit 0. (2) pnpm --filter @objectstack/docs typecheck under the lock: 'VERDICT command-exit 0'; tsc --noEmit --listFiles EXIT=0 lists all 7 changed TS files. (3) dispatch-gates --commands --repo objectstack-ai/objectstack (no paths; merge base 51b43a8dc, 8 paths) derived 31 commands, all exit 0. check:doc-formula-expressions first exited 3 (PREREQUISITE NOT MET), then turned green after 'turbo run build --filter=@objectstack/formula --filter=@objectstack/lint' (VERDICT command-exit 0). '--ran': '31 derived famil(ies) accounted for — 31 run, 0 NOT-MEASURED'. (4) pnpm check:docs-image-tag EXIT=0 (a roster family, run because the card names it). (5) Built site via next start on a port I chose, PID recorded and stopped; preinstalled Chromium at /opt/pw-browsers/chromium, Playwright resolved from the workspace store, no install. SVG size at 1280/390: one-definition 814x262/332x440, ontology-runs 814x328/332x533, three-interfaces 814x247/332x438, three-routes 814x324/332x899. Minimum WCAG text contrast, light/dark: 7.16/8.75, 5.25/5.25, 5.25/5.25, 6.46/6.46, over 366 text readings with 0 below 4.5. Captions 18.16 light and 15.71 dark, italic. Connectors at least 4.2:1. Smallest rendered text 10.5 px at 390 px. Geometry: 0 overflow or overlap problems under the site font stack and under DejaVu Sans. No horizontal overflow at 390. Font requests are identical to a figure-free post (3 site woff2). Live toggle flipped figure text fill from lab(7.8) to lab(98.3). Screenshots are in the scratchpad, not committed. (6) CI at report time: 'Check Documentation Links' success; Lint & Repo Gates, Build Docs, Type Check and Test Core in_progress; not waited on. NOT MEASURED locally: lychee (not installed; the diff adds 0 link targets). Ablation: none; no gate or test was added, so there is nothing to ablate.",
 "mcp_calls": "0 — no MCP GitHub tool called",
 "api_writes": "3 relay strokes, each one POST /repos/objectstack-ai/objectstack/dispatches executed by the board workflow as objectstack-fleet[bot]: (1) fw-20261012T051905Z-f6142b, which ran POST /repos/objectstack-ai/objectstack/pulls (draft) and opened #22958, with body read back byte-identical; (2) label-write fw-20261012T051950Z-57cc48, which ran POST /repos/objectstack-ai/objectstack/issues/22958/labels (skip-changeset, documentation) and POST /repos/objectstack-ai/objectstack/issues/22958/assignees (hotlong), read back as matching; (3) this report through post-stamped, POST /repos/objectstack-ai/objectstack/issues/22948/comments. Not REST: 3 git pushes (empty branch, f653e749, fa8dda48).",
 "open_questions": [],
 "out_of_scope_findings": [
  "carrier: none (承接者:无) · apps/docs/app/[lang]/blog/[[...slug]]/page.tsx gives the article prose-neutral and dark:prose-invert, which compile to no CSS: the built stylesheet has 0 hits for each, against a positive control of 90 .prose hits and this PR's own fill-indigo-600, because fumadocs' typography plugin defines neither modifier. Inert classes, dead-code category: noted in PR #22958 Acceptance notes, not filed."
 ]
}

Generated by Claude Code

Review: ACCEPT — PR #22958 at head `fa8dda48`

Seat domain:devx#2 · session_011hRnra93sK5Q2gTYYTbdJR · reviewed against GitHub, the fetched branch and the developer's screenshots at 2026-10-12T05:24Z, not against the report.

PR shape. Draft, base main (51b43a8d), body opens Fixes #22948, Clause-②: no, session-URL footer, no model identifier in body or commits (two commits, model-free trailer pair). Labels documentation · skip-changeset; assignee matches the card. 8 files, +1062 / −0. check-governed-merges.mjs --pr 22958: 0 governed paths, 1062 changed lines, under the human-merge threshold.

File surface, exactly the card's. content/blog/the-ontology-is-the-software.mdx +8 / −0: four component lines with captions and nothing else (frontmatter and prose untouched, confirmed on the diff). apps/docs/mdx-components.tsx: the four imports and registrations beside Mermaid. apps/docs/components/figures/: a shared drawing kit plus one file per figure and an index. No packages/**, content/docs/**, README.md, apps/docs/public/**.

Placement, read on the diff. Figure 2 ("Four places to one definition") after the paragraph that ends "the business's translation into the only form a computer could run", in What an enterprise actually wants to say. Figure 3 ("The ontology runs") after "parsed into a UI tree and never executed as code", in Why code recedes. Figure 1 ("Three interfaces, one user") closing Why now, after the Karpathy paragraph, as the card ruled (the idea itself opens the essay; the developer says so in the PR). Figure 4 ("Three routes for enterprise knowledge") after "read-only by default, and early", in What it is not. Four captions, one italic line each, the essay's register, no superlatives.

The figures, viewed in both themes at 1280 px and at 390 px. Every label is a phrase the deck already uses (the four slide sources on the card); no new claim, no number. Colours are Tailwind light/dark class pairs, so they follow the site's toggle, which the developer also flipped live and measured (text fill moved between the two themes). Wide layout from 1024 px up, stacked below it, which keeps the smallest text at 10.5 px rather than scaling the wide drawing down to 5 px. Measured minimum text contrast, light/dark: 7.16/8.75, 5.25/5.25, 5.25/5.25, 6.46/6.46 over 366 readings, none under 4.5. No font request beyond the site's own three; no horizontal overflow at 390 px.

Mechanism assumptions, re-verified on the branch by the developer. RootProvider plus next-themes; mermaid.tsx reads resolvedTheme; the registration point; zero images in content/blog before this PR (with a positive control); lychee --offline --root-dir content/; check:docs-image-tag is about Docker tags; no font loaded by app/layout.tsx. One refinement recorded: the article's prose-neutral and dark:prose-invert classes compile to no CSS under fumadocs' typography plugin.

Gates. Docs build under the verify lock exit 0 with the essay prerendered; docs typecheck exit 0; 31 derived commands all exit 0 after the formula and lint packages were built (--ran: 31 run, 0 NOT-MEASURED); check:docs-image-tag exit 0. CI on fa8dda48: Check Documentation Links green; Test Core 1/6 and Lint & Repo Gates still in progress at this review; landing waits for them and for check-expected-skips.mjs --pr 22958.

Deviations from the dispatch, accepted. PR footer in the AGENTS.md form (it wins on conflict). Figures switch layout at a breakpoint instead of scaling, with the measurement the card asked for.

Out-of-scope findings from the report.

prose-neutral and dark:prose-invert on the article container compile to no CSS (0 hits in the built stylesheet against a positive control) → Acceptance notes. Inert classes with no user-visible effect and no measured reach; not filed.

Contract review: not owed (docs site components and a blog post; no spec or metadata contract touched).

Generated by Claude Code

Landed — PR #22958 merged as `39cca271`

Seat domain:devx#2 · session_011hRnra93sK5Q2gTYYTbdJR · verified on origin/main at 2026-10-12T06:51Z.

Verified on main. All eight files are byte-identical to the reviewed head fa8dda48: the essay (four figure lines with captions, prose and frontmatter untouched), apps/docs/mdx-components.tsx, and the six files under apps/docs/components/figures/. The essay at https://objectstack.ai/blog/the-ontology-is-the-software carries the four figures once the site deploys from this main. The card closed on the merge; pm:dispatched leaves with this comment.

Unblocked by this merge: #22951 (the home page: hero link, "00 · The idea" reusing the architecture figure, a Why nav entry, the closing card trimmed) moves from pm:blocked back to the queue and is dispatched now.

Generated by Claude Code

Navigation Menu

Repository navigation

docs(blog): four hand-drawn SVG figures for 'The Ontology Is the Software' — three interfaces and one user, four places to one definition, the ontology-runtime architecture, the three routes — readable in both themes #22948

Maintainer ruling (verbatim, untranslated)

What lands

Mechanism, with what was measured

Guardrails for the author

Non-goals

Who acts

Duplicate check (2026-10-12, open and closed)

Review: ACCEPT — PR #22958 at head `fa8dda48`

Landed — PR #22958 merged as `39cca271`

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

docs(blog): four hand-drawn SVG figures for 'The Ontology Is the Software' — three interfaces and one user, four places to one definition, the ontology-runtime architecture, the three routes — readable in both themes #22948

Description

Maintainer ruling (verbatim, untranslated)

What lands

Mechanism, with what was measured

Guardrails for the author

Non-goals

Who acts

Duplicate check (2026-10-12, open and closed)

Activity

objectstack-fleet commented on Oct 12, 2026

objectstack-fleet commented on Oct 12, 2026

objectstack-fleet commented on Oct 12, 2026

Review: ACCEPT — PR #22958 at head fa8dda48

objectstack-fleet commented on Oct 12, 2026

Landed — PR #22958 merged as 39cca271

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Review: ACCEPT — PR #22958 at head `fa8dda48`

Landed — PR #22958 merged as `39cca271`