docs: replace the unmeasured ~1% claim with the measurement we can actually make

README.md

@@ -8,12 +8,13 @@
 >
 > The open target format and runtime for AI-written business apps. Your coding
 > agent writes models, UI, workflows, and permissions as compact typed metadata —
-> often around 1% of a traditional codebase — and strict TypeScript, Zod schemas,
-> and a validation gate catch its mistakes at authoring time. The runtime derives
-> the database, REST API, UI, and MCP server, and enforces permissions and audit
-> on every call.
+> [a complete CRM is under 2,000 lines](#why-the-mistakes-dont-ship), so the whole
+> app fits in the agent's context — and strict TypeScript, Zod schemas, and a
+> validation gate catch its mistakes at authoring time. The runtime derives the
+> database, REST API, UI, and MCP server, and enforces permissions and audit on
+> every call.
 
-`~1% code surface` · `Typed, validated, governed` · `Self-host anywhere` · Apache-2.0
+`Fits in an agent's context` · `Typed, validated, governed` · `Self-host anywhere` · Apache-2.0
 
 <p align="center">
   <img src="docs/screenshots/architecture.png" width="940" alt="ObjectStack architecture: author typed Zod metadata (objects, flows, views, policies); the microkernel compiles it into a versioned JSON artifact and loads plugins, drivers, and services; it generates a REST API, client SDK, Console and Studio UI, and MCP tools used by developers and AI agents, governed by Auth, RBAC, RLS, FLS, and audit, over PostgreSQL, MySQL, SQLite, or MongoDB">
@@ -121,11 +122,20 @@ The reason this works is the same reason TypeScript was the right host language:
 **an agent's errors become located, corrective text it can read and fix itself**,
 in seconds — instead of a silent runtime failure nobody traces back.
 
-And because the whole business system is a few hundred lines of typed metadata
-rather than tens of thousands of lines of CRUD and glue, it **fits in an agent's
-context window** — so the agent can load it end-to-end, reason about every
-dependency, and refactor across data, API, UI, and permissions in one change.
-That's the difference between AI as autocomplete and AI as a co-maintainer.
+The other half is size. The CRM in this repo — [`examples/app-crm`](./examples/app-crm):
+six objects, views, a dashboard, a lead-conversion flow, permission sets, actions,
+translations — is **31 files, 1,792 lines, roughly 16k tokens**. That's the whole
+business system, in about 8% of a 200k-token context window. Count it yourself:
+
+```bash
+find examples/app-crm/src -name '*.ts' -not -name '*.test.ts' | xargs cat | wc -l
+```
+
+Because it **fits in an agent's context window**, the agent can load it
+end-to-end, reason about every dependency, and refactor across data, API, UI, and
+permissions in one change — it can answer *"what breaks if I change this?"*
+instead of grepping and hoping. That's the difference between AI as autocomplete
+and AI as a co-maintainer.
 
 > Your objects, permissions, and flows are your business ontology — and the
 > definition layer of the AI era should be an open protocol you own.

apps/docs/app/[lang]/page.tsx

@@ -21,7 +21,7 @@ export const metadata: Metadata = {
     absolute: 'ObjectStack — AI writes the app. ObjectStack is what it writes.',
   },
   description:
-    'The open target format and runtime for AI-written business apps. Agents write compact typed metadata — often ~1% of a traditional codebase — strict TypeScript, Zod, and a validation gate catch mistakes at authoring time, and the runtime derives the database, REST API, UI, and MCP server. Your business ontology as an open protocol.',
+    'The open target format and runtime for AI-written business apps. Agents write compact typed metadata — a complete CRM is under 2,000 lines, so the whole app fits in an agent\'s context — strict TypeScript, Zod, and a validation gate catch mistakes at authoring time, and the runtime derives the database, REST API, UI, and MCP server. Your business ontology as an open protocol.',
 };
 
 const VOCABULARY: { tag: string; title: string; copy: string }[] = [
@@ -121,11 +121,11 @@ export default function HomePage() {
             </h1>
             <p className="mt-6 max-w-xl text-lg text-fd-muted-foreground text-pretty">
               The open target format and runtime for AI-written business apps. Your coding agent
-              writes models, UI, workflows, and permissions as compact typed metadata — often
-              around 1% of a traditional codebase — and strict TypeScript, Zod schemas, and a
-              validation gate catch its mistakes at authoring time. The runtime derives the
-              database, REST API, UI, and MCP server, and enforces permissions and audit on
-              every call.
+              writes models, UI, workflows, and permissions as compact typed metadata — a
+              complete CRM is under 2,000 lines, so the whole app fits in the agent's context —
+              and strict TypeScript, Zod schemas, and a validation gate catch its mistakes at
+              authoring time. The runtime derives the database, REST API, UI, and MCP server,
+              and enforces permissions and audit on every call.
             </p>
             <div className="mt-8 flex flex-wrap items-center gap-3">
               <Link
@@ -154,7 +154,7 @@ export default function HomePage() {
               className="mt-8 flex flex-wrap items-center gap-x-3 gap-y-2 text-[13px] text-fd-muted-foreground"
               style={{ fontFamily: 'var(--l-mono)' }}
             >
-              <span>~1% code surface</span>
+              <span>Fits in an agent's context</span>
               <span aria-hidden className="text-fd-border">|</span>
               <span>Typed, validated, governed</span>
               <span aria-hidden className="text-fd-border">|</span>

content/docs/concepts/metadata-driven.mdx

@@ -205,14 +205,34 @@ Node.js         Python
 React           Flutter
 ```
 
-### 4. ~100× Less Code — Sized for AI Agents
+### 4. Small Enough to Fit in an Agent's Context
 
-**Traditional:** ~300 lines of code for a simple CRUD feature
-**ObjectStack:** ~30 lines of metadata
+A simple CRUD feature that takes ~300 lines of hand-written code is ~30 lines of
+metadata. But per-feature ratios are the least interesting part. Here is the
+measurement that matters — the CRM bundled in this repo
+([`examples/app-crm`](https://github.com/objectstack-ai/framework/tree/main/examples/app-crm):
+six objects, views, a dashboard, a lead-conversion flow, permission sets,
+actions, translations):
 
-For a complete enterprise module (CRM, ticketing, approvals, …) the gap typically widens to **roughly two orders of magnitude** — tens of thousands of lines of hand-written CRUD, forms, validation, and API glue collapse into a few hundred lines of typed metadata.
+| | |
+| :--- | :--- |
+| Files | 31 |
+| Lines | 1,792 |
+| Approximate tokens | ~16,000 |
 
-The point isn't lines of code. The point is **fit in an agent's context window.** When the entire business system is small, typed, and declarative, an AI agent can load it end-to-end, reason about every dependency, and safely refactor across data, API, UI, and permissions in a single change. That turns AI from an autocomplete tool into a real co-maintainer.
+That's the **whole business system** — about 8% of a 200k-token context window.
+Count it yourself:
+
+```bash
+find examples/app-crm/src -name '*.ts' -not -name '*.test.ts' | xargs cat | wc -l
+```
+
+The point isn't lines of code. The point is **fit in an agent's context window.**
+When the entire business system is small, typed, and declarative, an AI agent can
+load it end-to-end, reason about every dependency, and safely refactor across
+data, API, UI, and permissions in a single change — it can answer *"what breaks
+if I change this?"* instead of grepping and hoping. That turns AI from an
+autocomplete tool into a real co-maintainer.
 
 ```typescript
 // All you need:

content/docs/getting-started/how-ai-development-works.mdx

@@ -25,10 +25,11 @@ build the thing I actually meant?*
 
 ## Why it's fast
 
-A typical enterprise app is tens of thousands of lines of CRUD, forms, queries,
-permissions, and API glue spread across dozens of files. ObjectStack collapses the
-same surface into **a few hundred lines of typed metadata** — roughly two orders
-of magnitude less code to read, write, and maintain.
+A typical enterprise app spreads CRUD, forms, queries, permissions, and API glue
+across dozens of files. ObjectStack keeps only the part that's yours: the CRM
+bundled in this repo — six objects, views, a dashboard, a lead-conversion flow,
+permission sets, actions, translations — is **1,792 lines across 31 files, about
+16k tokens**. That's the entire business system, not a module of it.
 
 The point isn't lines of code; it's **fit in an agent's context window.** When the
 entire business system is small, typed, and declarative, an agent can load it