docs: explain ObjectOS in ontology terms, and correct four capability claims 17.7 contradicts

[objectstack-fleet]

Fixes #328

Below the gated lede, the docs now explain ObjectOS in the official docs' ontology terms: the ontology core, its projections, "executable, not a knowledge ontology", "not a semantic layer". Four pages also stated capabilities that ObjectStack 17.7 contradicts. Those are corrected. Each work item was checked against main 76988da first; the readings are below.

What changed

B. Ontology framing (links the objectstack.ai concept pages and copies none of their content, per #171 ruling A):

• New content/docs/ontology.mdx, "Your ontology in ObjectOS", plus one meta.json entry after why. It holds:
  • the six core kinds, each mapped to a page on this site;
  • the four projections, mapped to Interface and Localization;
  • where the ontology lives: tenant metadata (AI Builder, Studio), repository source, or the compiled artifact;
  • what it is not;
  • four objectstack.ai links.
  • It writes no export steps; it keeps only the positioning sentence.
• architecture.mdx:
  • the "two thin layers" text and a new diagram now read ontology → runtime (derive + enforce) → database · REST · Console · MCP;
  • the process diagram gains the MCP server;
  • the request path gains MCP tool calls, plus one paragraph saying an agent's call takes the same auth and permission path.
• build/index.mdx:
  • Build is now described as authoring the ontology core and its projections, and every path passes the same validation gate.
  • The vocabulary table gains Permissions.
• index.mdx, below :7-13 and leaving :35 alone:
  • the AI Builder bullet;
  • the Salesforce row;
  • a new MCP server row;
  • a fourth audience, agents.
• why.mdx:
  • the not-a-fit list now agrees with objectstack's when-to-use list (core ERP, integration-heavy work, lake analytics, algorithm-heavy domains, certified platforms) and links it;
  • two fit rows added (departmental apps around an ERP; back offices agents operate);
  • "vibe-code" reworded;
  • the Salesforce "Same" rows rewritten;
  • npm create objectstack@latest.
• resources/glossary.mdx: "Business ontology" now also says no inheritance, axioms or reasoner, and not a semantic layer. New entries: Projection and Validation gate.
• resources/faq.mdx: a new section answers "What does ObjectOS mean by ontology?" and "Is ObjectOS a semantic layer?".

A. Capability claims 17.7 contradicts:

#	Where	Was	Now	Reading
1	extend-existing-systems.mdx:29-31, :48; configure/data-sources.mdx	readOnly datasource / capabilities table; "objects now read and write your existing tables"	Connect as schemaMode: 'external': no DDL, read-only by default. Writes need external.allowWrites: true and external.writable: true on the object. A SELECT-only DB user is the boundary on every path. The pushdown section says the driver decides	@objectstack/spec 17.7.0 DatasourceSchema.safeParse refuses readOnly, capabilities, readReplicas, healthCheck, retryPolicy, each with its tombstone (RETIRED_CAPABILITIES, RETIRED_DATASOURCE_BLOCKS); objectstack external-datasources.mdx §5
1b	data-sources.mdx:29, :43 (in-memory rows)	memory … "In-process (tests, demos)"	:29 kept; :43 "In-process, for tests — not a boot store since ObjectStack 17.7"	Measured: a named driver: 'memory' datasource still parses on 17.7.0, and the factory still builds it (service-datasource/default-datasource-driver-factory.ts:1341-1350). 17.7 retired it as a boot store only (releases/v17/17-7.mdx:787-793)
2	build/agents.mdx:86-97, build/ai-builder.mdx:59-63, build/interface/actions.mdx:10-13 and the derived lines :62, :68, :91-92, :151-156	every action becomes an action_NAME tool	Only with ai: { exposed: true } + an ai.description of at least 40 characters, on a headless type (script/flow/api). The approve_invoice sample now carries the ai block, so its "the assistant can call it" line is true	objectstack ai/actions-as-tools.mdx:90-113; this repo's configure/mcp.mdx:134-137
3	resources/glossary.mdx MCP entry, resources/faq.mdx:152-158	"can expose … via @objectstack/mcp"; MCP framed as the open-source path only	Every deployment is an MCP server at /api/v1/mcp, on by default; objects are tools, exposed actions are tools; each call runs as the caller	this repo's configure/mcp.mdx:6-15
4	build/templates.mdx:98	os package export	The change is live deployment metadata; it does not travel back to the template's repo on its own. No export steps	@objectstack/cli@17.7.0 tag (4e4e881): packages/cli/src/commands/package/ holds install.ts, publish.ts only
5	resources/glossary.mdx:261 (self sign-up)	—	Unchanged	NOT MEASURED for ObjectOS. The framework default since 17.3 is auth.audience.posture = invite_only (17-3.mdx:181-216). ObjectOS's runtime and image are not reachable from this container, and nothing on this site documents auth.audience; OS_AUTH_MEMBERSHIP_POLICY governs what a sign-up joins, not whether one is admitted. Left for a measurement on an ObjectOS deployment

Locale siblings. Item 4 removes a capability assertion, so the seven build/templates.*.mdx siblings are deleted. zh-Hant is regenerated, and the generator prunes nothing further. The other pages that reverse a capability claim have no siblings. build/index.mdx keeps its siblings: its change is framing, which the translation pass handles (#256 ruling 5989567068).

Bounded in-place corrections (same defect class, same files, form set by this site or the 17.7 contract)

• build/interface/actions.mdx § Permissions. It said action bodies run with the caller's object permissions and FLS. On 17.7 the invoke-time gates are requiredPermissions (403), the subject-record load as the caller, and AI exposure. A script body then runs elevated (buildActionExecutionContext → isSystem: true, runtime/src/action-execution.ts:1514-1542 at the 17.7.0 tag 4e4e881). This site's own configure/mcp.mdx:153-156 already says so. Left as it was, the rewritten "From an AI Agent" section would have contradicted the next section on the same page.
• resources/glossary.mdx Action entry.
  • The route /api/v1/data/OBJECT/actions/ACTION does not exist (rest/src/rest-route-ledger.ts:323-331 at 4e4e881). The entry now uses /api/v1/actions/OBJECT/ACTION, as actions.mdx:11 does.
  • "flow steps" is gone: actions.mdx says no flow node calls an action.
  • "Inherits the caller's permissions" is replaced by the invoke-gate wording above.
• build/index.mdx. The vocabulary row said actions are "callable from … flows"; that is gone for the same reason.
• configure/data-sources.mdx.
  • The core-field table also listed readReplicas and healthCheck, retired with capabilities. They are replaced by schemaMode and external.
  • The security note "Pull host/user/password from environment variables" contradicted the page's own credentials note, which says the schema refuses a password in config; it now points to external.credentialsRef.
  • The biz_customer sample gains sharingModel (an os validate error without it) and external.remoteName.
  • The com.example.logs routing rule now points at default, not a read-only federated source.
• build/agents.mdx. The 'action_*' wildcard comment is corrected to "every action the app exposes to AI".

Checks, at d4f1305

All exit codes were captured before any pipe:

Command	Exit	Verdict line
node apps/docs/scripts/gen-zh-hant.mjs --check	0	53 generated files match byte for byte
npm ci --prefix .github/scripts/doc-samples … then node .github/scripts/check-doc-samples.mjs	0 / 0	98 pass · 10 N/A · 2 opted out, spec 17.7.0; every block edited here is judged PASS, none is N/A
node .github/scripts/check-translations.mjs	0	translations gate passed
check-translation-ownership.mjs --actor os-tesla --files (from git diff --name-status --no-renames origin/main...HEAD)	0	not enforced (no TRANSLATION_BOT_LOGIN); with it set to a bot login: 7 translation artifacts deleted, none added or modified
check-translation-output.mjs --files … / --self-test	0 / 0	passed (203 pre-existing findings reported)
os-verify-lock.sh -- pnpm turbo run type-check --continue	0	@objectos/docs:type-check cache miss, executed
os-verify-lock.sh -- pnpm turbo run build	0	1005 static pages. The Satori OG fonts fail to fetch through this container's TLS proxy; that is environmental and not a build failure
node .github/scripts/check-locale-surface.mjs	0	every advertised URL has a source and vice versa
node .github/scripts/check-positioning.mjs	0	4 copies equal their constants; no stale sentence in 80 English sources
node .github/scripts/check-search-locales.mjs	0	8 locales answer 200; en 80/80 own pages found by title
os-verify-lock.sh -- pnpm turbo run test	0	11 self-tests passed

The Worker size budget and the render smoke-check run in CI on this PR.

Browser check (AGENTS.md rule 2)

Chromium (/opt/pw-browsers/chromium) drove next start on the production build, at desktop 1366×900 and phone 390×844. Both /docs/ontology and /docs/architecture:

• answer 200, with zero console errors;
• have no page-level horizontal overflow;
• list the new page in the sidebar.

On the phone, all three tables on the new page fit (356 of 358px). The new diagram fits too (356px). The two older code blocks on the architecture page scroll in their own frame, as before. A second commit (d4f1305) narrowed the "Where it lives" table and the diagram after the first capture showed them overflowing at phone width.

Screenshots (desktop and phone, full page, plus detail shots): https://claude.ai/artifact/GU4WWGXrKEeuWE3poYbCdx. The page is private to the maintainer's account until shared.

Acceptance notes (observations, not filed)

• objectstack.ai routes. They are confirmed against the objectstack README (:25, :90-95, :217) and objectstack apps/docs/app/[lang]/{docs,blog}. They were not fetched: this container's proxy refuses objectstack.ai.
• Export mechanism. No ObjectOS export procedure is documented in this repo. The nearest documented read path is reference/cli.mdx:146-155, os meta list/get: a per-item metadata read, not an export. No steps were written.
• why.mdx:153. os init does exist at 17.7 (packages/cli/src/commands/init.ts), so the old command worked. It changed only to the official docs' recommended entry point.
• objectstack docs link https://docs.objectos.app/docs/ai (ai/actions-as-tools.mdx:149, :234 and three more). This site is docs.objectos.ai (apps/docs/lib/site.ts:44) and has no /docs/ai route. NOT MEASURED over HTTP.

Out of scope here (reported to the seat)

• reference/rest-api.mdx:142 and reference/security.mdx:206 repeat the "every action is an action_NAME tool" claim. Those files belong to Build, API and operations pages predate ObjectStack 17.0–17.7: the changelog stops at 17.1, upgrade has no 17.x steps, and the REST reference lists removed cursor paging, error codes and routes #330 and Access, audit and approval pages predate ObjectStack 17.0–17.6: masking, record-view audit, deactivation, query-door FLS, the guest baseline and approval visibility are missing or wrong #329. Build, API and operations pages predate ObjectStack 17.0–17.7: the changelog stops at 17.1, upgrade has no 17.x steps, and the REST reference lists removed cursor paging, error codes and routes #330 is not addressed here; neither is Access, audit and approval pages predate ObjectStack 17.0–17.6: masking, record-view audit, deactivation, query-door FLS, the guest baseline and approval visibility are missing or wrong #329.
• build/templates.mdx:46-51 "Fork as a codebase" runs pnpm dlx @objectstack/cli create my-app --template todo, which fails on 17.7:
  • at the 17.7.0 tag, os create takes TYPE [NAME] and answers Unknown type (cli/src/commands/create.ts:640);
  • todo, compliance, content, contracts and procurement are retired, "delisted from the ObjectStack template marketplace" (create-objectstack/src/template-registry.ts:46-52).
  • The template catalog on this page, index.mdx:43-44 and build/index.mdx:15, :46-48 name them as installable. Whether the ObjectOS marketplace still lists them is not measurable from here.
• build/interface/actions.mdx:43-57: the sample body calls ctx.data.update(…). The 17.7 body face is ctx.api.object(…) (runtime/src/sandbox/body-runner.ts:21-41). Not executed.
• reference/cli.mdx:98-103 documents os create example, retired by #16483 (create.ts:555). That file belongs to Build, API and operations pages predate ObjectStack 17.0–17.7: the changelog stops at 17.1, upgrade has no 17.x steps, and the REST reference lists removed cursor paging, error codes and routes #330.

---

Generated by Claude Code

[objectstack-fleet]

席位核对 — REWORK, patch round 1 · 2026-10-15T13:24Z

Seat repo:objectos, session session_01CXCwzqwMhkphKoBC11oPSz. The patch goes back to the same dev on the same claim and branch.

Verified on head d4f1305, unchanged by the patch:

• Shape: draft, Fixes #328 only, 21 files, all inside the claim's surface.
• Checks: build, Node floor and Ownership & freshness succeeded.
• The new ontology.mdx and the architecture redraw.
• Action exposure, checked against objectstack @objectstack/*@17.7.0 (4e4e8814):
  • ai.description must be at least 40 characters (spec/src/ui/action.zod.ts:768, 2039);
  • a script body runs isSystem-elevated, while a flow action keeps the caller's identity and its runAs (runtime/src/domains/actions.ts:368-396);
  • api actions are dispatched on the ObjectOS runtime only (objectstack ai/actions-as-tools.mdx:111-113).
• The route POST /actions/:object/:action (actions.ts:13).
• The datasource retirements and the federation double opt-in.

Patch items:

1. Required. build/index.mdx now drops "callable from flows" and makes AI agents conditional on exposure. Its 7 locale siblings still assert both (build/index.zh-Hans.mdx:29, build/index.de.mdx:32). Delete them under ruling 5989567068, and regenerate zh-Hant.
2. Declared rider, same class as item 4, in a file this PR already edits. build/templates.mdx:47: os create … --template todo is not a 17.7.0 command form. Replace it with a measured form, or remove it. Keep the template catalog out of scope; whether ObjectOS still lists those templates is unmeasured.
3. Declared rider, same class, in a file this PR already edits. build/interface/actions.mdx:43-57: the sample body uses ctx.data.update. At 17.7.0 the body face is ctx.api.object(...) / ctx.params / ctx.record. Rewrite it verified, or leave it and report.

The dev's other findings went to their owners: reference/rest-api.mdx:142 and reference/cli.mdx:98-103 to #330; reference/security.mdx to PR #331.

Not blocking: this PR's commit trailers name the model, where the os-dev definition asks for the model-free pair. The history stays as pushed.

---

Generated by Claude Code