docs(concepts): add How ObjectStack compares and When to use ObjectStack

content/docs/concepts/compare.mdx

@@ -0,0 +1,125 @@
+---
+title: How ObjectStack compares — ontologies, semantic layers, low-code
+navTitle: How It Compares
+description: "ObjectStack beside knowledge ontologies, semantic layers, operational ontologies, metadata platforms and AI codegen: what each does well, where it differs."
+---
+
+The word *ontology* covers several different kinds of thing in 2026, and the products
+that use it solve different problems. This page sets ObjectStack beside the five kinds
+of thing a reader is most likely to weigh it against — three that use the word and two
+that answer the same question without it. For each: what it is, what it is good at, and
+the one difference that matters. ObjectStack is none of the five; what it is instead,
+an executable business ontology, is defined on [Business Ontology](/docs/concepts/ontology).
+
+## Knowledge ontologies
+
+**What it is.** RDF and OWL, the W3C standards for describing a domain as statements,
+classes, properties and axioms, and the tools built on them, such as the Protégé editor. A
+reasoner infers facts nobody stored and checks that the whole description is
+consistent.
+
+**What it is good at.** Shared vocabularies across organisations, integrating data that
+was never designed to fit together, and answering questions by inference.
+
+**The difference.** A knowledge ontology describes a domain; nothing runs it as an
+application. ObjectStack's ontology has no axioms and no reasoner. It is validated, then
+run.
+
+## Semantic and context layers over existing data
+
+**What it is.** A layer that makes data living elsewhere legible to agents and
+analysts: business names, metrics, relationships and context over warehouses,
+lakehouses and operational databases. As of late 2026 the category includes the ontology
+item in Microsoft Fabric IQ (in preview), Databricks Genie with Unity Catalog metric
+views, Snowflake semantic views, AWS Context and Google Cloud Knowledge Catalog; in open
+source, metric semantic layers and agent memory graphs.
+
+**What it is good at.** Consistent meaning over a large existing data estate, without
+moving the data. These layers are read-mostly; some add rules and actions on top.
+
+**The difference.** The system of record stays where it was. ObjectStack's ontology is
+the system: the database, API, UI and agent tools are derived from it.
+
+## Operational ontologies over existing systems
+
+**What it is.** Objects, links, actions and permissions defined over data integrated
+from other systems, with edits written back. The Palantir Ontology is the reference: an
+action type packages edits to objects and links with its validation and side effects,
+and writeback keeps those edits in sync with the underlying data.
+
+**What it is good at.** One governed model of objects and actions across many large
+systems that stay where they are, so people and agents can act on operational decisions
+in one place.
+
+**The difference.** It is still a layer over systems that live elsewhere and, in
+Palantir's case, a proprietary platform. ObjectStack derives the database schema, API,
+UI and MCP tools from the definition, and it is Apache-2.0.
+
+## Metadata-driven application platforms
+
+**What it is.** Platforms where metadata generates tables, APIs and UI — the closest
+relatives. Salesforce's metadata is the ancestor; open-source cousins include Frappe
+Framework with ERPNext, Odoo, NocoBase, Payload and Twenty. Several of them now offer MCP
+servers, so agents can reach them too.
+
+**What it is good at.** Building business applications quickly on a proven runtime, with
+packaged apps, modules and integrations to start from.
+
+**The difference.** Where the definition lives, and who it is written for. In most of
+these platforms metadata is configuration stored in the platform's database and edited
+through its UI; where it is code, as with the Payload Config or Odoo's modules, it is
+framework code. ObjectStack's definition is typed, declarative TypeScript in your
+repository — versioned and reviewed as a diff, checked by `os validate` before it runs,
+and shaped for an AI to write.
+
+## AI code generation
+
+**What it is.** An agent writes a conventional codebase from a prompt: a schema,
+handlers, components, the glue between them.
+
+**What it is good at.** It has no runtime ceiling. Anything code can do, it can produce.
+
+**The difference.** The output is still code. It grows, its layers drift apart, and
+past a certain size no agent can hold it whole. Tests and type-checkers check the code
+against itself; nothing checks it against a definition of the business, because there is
+none. ObjectStack keeps the definition and moves the code into the runtime, and its gate
+rejects a wrong definition when it is written, not when it fails in production.
+
+## Side by side
+
+Each cell reads a category as a whole; individual products vary.
+
+| | Executable | AI-writable | Agent-operable | You own it | Is the system itself |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Knowledge ontologies** | No — reasoned over | Possible | Query only | Yes — open standards | No |
+| **Semantic and context layers** | No — queried | Possible | Read-mostly | Varies | No — a layer |
+| **Operational ontologies** | Actions only | Possible | Yes | Mostly vendor-held | No — a layer |
+| **Metadata-driven platforms** | Yes | Varies | Often, via MCP | Varies | Yes |
+| **AI code generation** | Yes | Yes | If you build it | Yes | Yes |
+| **ObjectStack** | Yes | Yes — gated | Yes — by default | Yes — Apache-2.0 | Yes |
+
+## Where the others are stronger
+
+- **Existing data and legacy systems — semantic and context layers, operational
+  ontologies.** When the data already lives in a warehouse, a lakehouse and a dozen
+  operational systems, these start where you are. ObjectStack's
+  [federation](/docs/data-modeling/external-datasources) is early and read-only by
+  default; it is not a way to put one model over an existing estate.
+- **Reasoning over heterogeneous data — knowledge ontologies.** Inferring facts nobody
+  stored, classifying by axioms, checking consistency, aligning vocabularies across
+  organisations: a reasoner does this, and ObjectStack has none.
+- **Algorithm-heavy work and unusual interfaces — code.** An optimiser, a simulation, a
+  canvas editor, a game: write code. ObjectStack can wrap an algorithm as an
+  [action](/docs/ai/actions-as-tools), but its interface is server-driven from metadata,
+  and an interface unlike any business app is easier to build directly.
+- **Ecosystem maturity and integrations — the metadata platforms.** Salesforce, Odoo and
+  ERPNext bring years of production use, packaged applications, app marketplaces and
+  implementation partners. ObjectStack is younger; expect to build more of it yourself.
+
+## In one sentence
+
+**One executable business ontology. AI writes it, the runtime runs it, agents operate
+it, you own it.** What that means, and what it does not, is on
+[Business Ontology](/docs/concepts/ontology); the argument is the essay
+[The Ontology Is the Software](/blog/the-ontology-is-the-software). Whether it fits your
+case is on [When to use ObjectStack](/docs/concepts/when-to-use).

content/docs/concepts/index.mdx

@@ -98,6 +98,8 @@ In the enterprise-AI vocabulary, the ontology is the software: the core (objects
 relations, actions, permissions, flows, agent and tool definitions) is what the runtime
 executes, and views, dashboards, apps, and translations are projections of it. See
 [Business Ontology](/docs/getting-started/glossary#business-ontology).
+[How ObjectStack compares](/docs/concepts/compare) sets it beside the other things called
+an ontology, and [When to use ObjectStack](/docs/concepts/when-to-use) says where it fits.
 
 ### When to Use Metadata-Driven
 

content/docs/concepts/meta.json

@@ -4,6 +4,8 @@
     "architecture",
     "metadata-driven",
     "ontology",
+    "compare",
+    "when-to-use",
     "metadata-lifecycle",
     "design-principles",
     "north-star"

content/docs/concepts/ontology.mdx

@@ -56,6 +56,9 @@ bounds what an agent must hold to reason about the business: the core, not every
 - **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.
 
+For these and the other things ObjectStack is weighed against, side by side, see
+[How ObjectStack compares](/docs/concepts/compare).
+
 ## How the runtime executes it
 
 ```text
@@ -98,3 +101,6 @@ surface as a human — never raw SQL or scraped UI. See
 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.
+
+Whether that fits your business, and what to settle before you start, is on
+[When to use ObjectStack](/docs/concepts/when-to-use).

content/docs/concepts/when-to-use.mdx

@@ -0,0 +1,100 @@
+---
+title: When to use ObjectStack, and when not to
+navTitle: When to Use It
+description: "Where ObjectStack fits today and where it does not, the five questions to answer before you start, and what you get in the first weeks and after a year."
+---
+
+ObjectStack is for business applications whose definition you want to own, that AI
+writes and agents operate. This page says where that fits today, where it does not,
+and what to settle before you start. What the word means is on
+[Business Ontology](/docs/concepts/ontology); how this differs from other things called
+an ontology is on [How ObjectStack compares](/docs/concepts/compare).
+
+## A good fit
+
+- **New business applications.** CRM, ticketing, approvals, operations and internal
+  tools. Objects, relations, actions, permissions and flows are most of what these apps
+  are, and they are exactly what the ontology declares.
+- **Teams small enough that one person, or a few, can define the business.** An agent
+  writes the definition; someone still has to know what it should say. The fewer people
+  who must agree on it, the faster the loop runs.
+- **ISVs shipping many vertical apps.** Each vertical is a definition on the same
+  runtime. What differs between them is the definition, not the stack underneath it.
+- **The long tail of departmental apps around a core ERP.** The spreadsheets and
+  low-code forms that track what the ERP does not — vendor onboarding, inspections,
+  internal requests — are small, specific and change often. Each one becomes a typed
+  definition in a repository instead of a file that gets emailed around.
+- **Back offices meant to be operated by agents from day one.** Every deployment is an
+  MCP server, on by default: objects are tools, the actions an author exposes are tools,
+  and permissions decide what an agent may call. See
+  [Connect an MCP Client](/docs/ai/connect-mcp).
+
+## Not a fit today
+
+- **Replacing the core ERP or finance system of a large enterprise.** A general ledger,
+  consolidation, tax and payroll carry regulation and edge cases that packaged systems
+  already encode. Build around that core, not instead of it.
+- **Workloads whose value is integrating many existing systems.** ObjectStack can
+  federate an external database as a datasource, but federation is early and read-only
+  by default; writes need an explicit opt-in on both the datasource and the object. See
+  [External Datasources](/docs/data-modeling/external-datasources). When the job is
+  mostly making existing systems legible to agents, a layer over those systems fits
+  better.
+- **Analytics over data lakes.** The [analytics layer](/docs/data-modeling/analytics)
+  defines metrics over the app's own objects for its reports and dashboards. It is not
+  built to query a lake.
+- **Algorithm-heavy domains, such as pricing or scheduling — unless the algorithm is
+  wrapped as an action.** The ontology declares what can be done; it does not express an
+  optimiser. Write the algorithm as code behind an
+  [action](/docs/ai/actions-as-tools), and permissions, audit and agent access apply to
+  it like any other action.
+- **Workloads that require a certified platform.** ObjectStack is open-source software
+  you deploy and operate, and it carries no compliance certification of its own. Where a
+  workload must run on a certified platform, certifying your deployment is work you own.
+
+## Five questions before you start
+
+The ontology is one sentence with five parts. Answer them for your business:
+
+1. **What we have** — the objects and their fields.
+2. **How it relates** — the lookups and master-detail links between them.
+3. **What can be done** — the actions a user or an agent may take on a record.
+4. **Who may do it** — permission sets, row-level and field-level security, sharing.
+5. **What happens when** — record triggers, scheduled jobs, approvals, workflows.
+
+If the team can answer them, the ontology is a day's work, because an agent does the
+writing. If it cannot, no tool helps yet, this one included. The first investment is
+answering these five questions, not installing anything.
+
+## What you get and when
+
+**In the first weeks.** One definition instead of four copies: the database schema,
+the API, the UI and the agent tools are derived from it, so a requirement changes in one
+place. Apps in days: an agent writes the definition, `os validate` rejects what would
+fail at runtime, and you review a small diff in the Console. The MCP surface is on by
+default, so agents connect under the same permissions as the people who use the app.
+
+**After a year.** The ontology is an asset in your repository: ordinary TypeScript,
+versioned, reviewed as diffs, and run by an Apache-2.0 runtime. It does not depend on one
+model — any coding agent can write it and any MCP client can operate it. Every change
+passes the same gate before it runs.
+
+**Later.** Operations that grow without headcount growing with them, because agents
+act through the same governed surface as people. Cheap experiments, because a new object
+or flow is a reviewed diff rather than a project. Cheap replication across entities — a
+new subsidiary, region or brand starts from a copy of the definition, not a rebuild.
+
+All of this rests on the definition staying small enough for an agent to read whole;
+[the example CRM's measurement](/docs/concepts/metadata-driven#4-small-enough-to-fit-in-an-agents-context)
+shows what that looks like.
+
+## Next steps
+
+- **Try it** — [Build with Claude Code](/docs/getting-started/build-with-claude-code)
+  walks the loop end to end, and
+  [Anatomy of an ObjectStack App](/docs/getting-started/quick-start) shows how to read
+  what the agent writes.
+- [Example Apps](/docs/getting-started/examples) — run a CRM and a kitchen-sink app.
+- [Business Ontology](/docs/concepts/ontology) — what the definition is.
+- [How ObjectStack compares](/docs/concepts/compare) — the other things called an
+  ontology, and where they are stronger.

scripts/docs-audit/handwritten-docs.json

@@ -64,12 +64,14 @@
     "content/docs/capabilities/request-template.mdx",
     "content/docs/capabilities/views.mdx",
     "content/docs/concepts/architecture.mdx",
+    "content/docs/concepts/compare.mdx",
     "content/docs/concepts/design-principles.mdx",
     "content/docs/concepts/index.mdx",
     "content/docs/concepts/metadata-driven.mdx",
     "content/docs/concepts/metadata-lifecycle.mdx",
     "content/docs/concepts/north-star.mdx",
     "content/docs/concepts/ontology.mdx",
+    "content/docs/concepts/when-to-use.mdx",
     "content/docs/data-modeling/analytics.mdx",
     "content/docs/data-modeling/drivers.mdx",
     "content/docs/data-modeling/external-datasources.mdx",