docs: checkpoint the docs-accuracy audit pass over 18 hand-written docs

WIP checkpoint — the adversarial verification pass is still running and will
add repairs on top of this commit. Recorded now so the work survives.

An audit agent read each doc, located the backing implementation under
packages/, and applied evidence-backed fixes in place (158 across 18 docs).
Every fix carries file:line evidence in the run's fix log. The heaviest:

- kernel/cluster.mdx (22): documented an `eventBus.emit(...)` API that exists
  nowhere in the codebase, a `ctx.cluster` PluginContext property that does
  not exist, `defineStack({ cluster })` that stack.zod.ts silently strips,
  fabricated `postgres`/`nats` drivers, the wrong env var (real one is
  OS_CLUSTER_DRIVER), and an at-least-once delivery promise neither shipped
  driver provides.
- protocol/kernel/plugin-spec.mdx (20): `plugin.manifest.ts` as the manifest
  filename — grep-empty across the implementation, the real one is
  objectstack.plugin.json; `context.plugins.isInstalled()` which does not
  exist; compound semver ranges ('>=1.0.0 <2.0.0') that make the resolver's
  anchored parse throw; init described as registration order when bootstrap()
  runs the dependency-topological order.
- data-modeling/external-datasources.mdx (3): credentialsRef samples used a
  `secret:` prefix the shipped SecretBinder cannot dereference (`sys_secret:`),
  so copying the sample fails closed at connect.
- deployment/migration-from-objectql.mdx (2): a `^3.1.0` pin that can never
  resolve to the current 16.1.0 line.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh

Author: claude

content/docs/concepts/metadata-lifecycle.mdx

@@ -37,8 +37,8 @@ export const Warehouse = defineDatasource({
   schemaMode: 'external',          // ObjectStack never runs DDL here
   config: { host: 'db.internal', port: 5432, database: 'analytics', user: 'readonly' },
   external: {
-    allowWrites: false,            // read-only (the default)
-    credentialsRef: 'secret:warehouse/password', // resolved from the secret store
+    allowWrites: false,                 // read-only (the default)
+    credentialsRef: 'sys_secret:9f2c…', // opaque handle minted by the secret store
     validation: { onMismatch: 'fail', checkOnBoot: true },
   },
   active: true,
@@ -90,11 +90,12 @@ That's it. `GET /api/v1/data/ext_customer` now returns live rows from the remote
 `customers` table; filters (`?region=EU`) push down to the remote query.
 
 <Callout type="warn">
-**Do not set `field.columnName` on an external object.** For federated objects the
-driver's query pipeline ignores `field.columnName`; `external.columnMap`
-(`remoteColumn → localField`) is the single, authoritative column mapping.
-`os build` / `os validate` rejects `field.columnName` on an external object with a
-clear error (ADR-0062 D7). Managed objects are unaffected.
+**`field.columnName` no longer exists.** It was removed from `FieldSchema` in the
+16.x line (#2377, ADR-0049) — the SQL driver always used the field key as the
+physical column, so a custom column name was silently ignored — and the
+ADR-0062 D7 lint that rejected it on external objects was removed with it.
+`external.columnMap` (`remoteColumn → localField`) is the single, authoritative
+column mapping for a federated object.
 </Callout>
 
 ## 3. Auto-connect — no `onEnable` needed
@@ -217,6 +218,12 @@ secret in the secret store (the same `SecretBinder` / `ICryptoProvider` the
 runtime-admin "Add Datasource" wizard uses). The credential is resolved to
 cleartext **at connect, before the driver is built**.
 
+The shipped binder encrypts the cleartext into a `sys_secret` row and mints an
+**opaque** handle — `sys_secret:<id>` — as the `credentialsRef`; that is the only
+form it resolves, so a hand-written path like `secret:warehouse/password` will
+not dereference. A host that wants a different scheme (a vault path, say)
+injects its own resolver via `new DatasourceAdminServicePlugin({ secrets })`.
+
 Resolution is **fail-closed**: if a `credentialsRef` is declared but no secret store
 is configured, or the secret cannot be resolved/decrypted, the datasource is left
 **unconnected with a clear error** — never connected without the credential. An

content/docs/data-modeling/external-datasources.mdx

@@ -39,7 +39,7 @@ Every expression in metadata is persisted as the same envelope:
 type Expression = {
   dialect: 'cel' | 'cron' | 'template';
   source?: string;          // surface syntax
-  ast?: unknown;            // parsed AST (filled by `objectstack compile`)
+  ast?: unknown;            // parsed AST (filled by `os compile`)
   meta?: { rationale?: string; generatedBy?: string };
 };
 ```
@@ -66,11 +66,11 @@ to relearn the syntax across surfaces.
 most common mistake (and the root cause of issue #1491) is a condition like
 `{record.rating} >= 4`: in CEL, `{…}` is a **map literal**, so it is a parse
 error. Write bare CEL: `record.rating >= 4`. Braces belong only in `{{ … }}`
-text templates. As of 7.6 a malformed expression no longer silently does
-nothing — it fails `objectstack build` and throws at runtime.
+text templates. A malformed expression does not silently do nothing — it fails
+`os build` and throws at runtime.
 </Callout>
 
-**Template formatting (7.6).** A `template` hole is a field path with an optional
+**Template formatting.** A `template` hole is a field path with an optional
 whitelisted formatter — `{{ path | formatter[:arg] }}` — with defined value→string
 semantics (no arbitrary logic; put logic in a CEL field):
 
@@ -121,9 +121,12 @@ evaluates (`objectql` computes a formula virtual field from its `expression`
 only). Do **not** pass `type: 'currency' | 'number' | …` to `Field.formula` — it
 is rejected by the typed `FieldInput` and, untyped, would override `type:'formula'`
 so the field silently never computes. To declare what the formula returns, set
-**`returnType`** (`'number' | 'text' | 'boolean' | 'date'`); it is inferred and
-stamped automatically by the AI build path, and consumers (dashboard measures,
-formatting) read it instead of re-parsing the expression. The CEL source is the
+**`returnType`** (`'number' | 'text' | 'boolean' | 'date'`). You declare it
+yourself — nothing back-fills it — but the agent-callable `validate_expression`
+tool reports the type it infers from the expression (`inferredType`) so an AI
+author can stamp the matching value. Consumers read the declared `returnType`
+instead of re-parsing the expression (record-title eligibility, for one: only a
+`returnType: 'text'` formula may be a `nameField`). The CEL source is the
 **`expression`** key — it is the only key the schema and runtime read for a
 formula's source; there is no separate `formula` source key.
 </Callout>
@@ -161,7 +164,7 @@ Cheat-sheet of what you'll write daily:
 
 Registered automatically into every `Environment` by `@objectstack/formula`.
 All functions are pure given a pinned `now`, which is what makes
-`objectstack build` artifacts byte-stable across runs.
+`os build` artifacts byte-stable across runs.
 
 | Function | Returns | Description |
 |:---|:---|:---|
@@ -197,20 +200,21 @@ Keep them pure, dependency-free, and AI-readable.
 | `record` | the row being evaluated | formulas, validation, sharing, visibility |
 | `previous` | row before update | hooks, validation on update |
 | `input` | hook payload | hooks |
-| `os.user` | install / request user | seed, predicates with identity |
+| `current_user` | the authenticated subject — the canonical binding (ADR-0068). `user`, `ctx.user` and `os.user` are aliases of the **same** object | predicates with identity |
+| `os.user` | alias of `current_user` | seed, predicates with identity |
 | `os.org` | active organization | seed, predicates |
 | `os.env` | install env (`prod`, `dev`, `test`) | seed, predicates |
 
 ---
 
 ## Build-time validation
 
-`objectstack build` type-checks every expression against the object schema, so
+`os build` type-checks every expression against the object schema, so
 a mistake that would silently evaluate to `null` at runtime is caught before it
 ships. The same shared validator also runs when a flow is registered
 (`registerFlow`), so a flow authored dynamically gets the same verdict. Findings
 come at two severities: **errors** fail the build; **warnings** are advisory
-(surfaced, not fatal — `objectstack validate --strict` promotes them to errors).
+(surfaced, not fatal — `os validate --strict` promotes them to errors).
 
 | Check | Example | Severity |
 |:---|:---|:---|
@@ -330,10 +334,19 @@ invert the test (here `amount <= 0` rejects non-positive amounts).
   object: 'case',
   events: ['afterUpdate'],
   condition: P`previous.status != 'escalated' && record.status == 'escalated'`,
-  body: { language: 'js', source: 'await ctx.notifyOpsTeam(record)' },
+  body: {
+    language: 'js',
+    source: "ctx.log.warn('case escalated', { id: ctx.input.id });",
+    capabilities: ['log'],
+  },
 }
 ```
 
+The `condition` is the CEL part — it binds `record` / `previous` directly. The
+JS `body` is a different surface: it is wrapped as `new AsyncFunction('ctx', source)`,
+so inside it the record is `ctx.input` (there is no bare `record`), and every
+`ctx` API it touches must be covered by a declared capability.
+
 ---
 
 ## Formula patterns
@@ -375,24 +388,32 @@ Field.formula({
 Field.formula({
   label: 'Days to Close',
   returnType: 'number',
-  expression: 'daysBetween(record.close_date, today())',
+  expression: 'daysBetween(today(), record.close_date)',
 })
 
 // Contract end in 30 days
 Field.formula({
   label: 'Expiring Soon',
   returnType: 'boolean',
-  expression: 'record.status == "active" && daysBetween(record.end_date, today()) <= 30',
+  expression: 'record.status == "active" && daysBetween(today(), record.end_date) <= 30',
 })
 
 // Age in days
 Field.formula({
   label: 'Age (Days)',
   returnType: 'number',
-  expression: 'daysBetween(today(), record.created_date)',
+  expression: 'daysBetween(record.created_date, today())',
 })
 ```
 
+<Callout type="warn">
+**Argument order matters.** `daysBetween(a, b)` is `b − a`, so it counts
+*forward from `a` to `b`* and goes negative when `b` is earlier. "Days
+remaining" is `daysBetween(today(), record.due_date)`; "age so far" is
+`daysBetween(record.created_date, today())`. Swapping the two operands is the
+easiest way to ship a formula whose sign is inverted on every row.
+</Callout>
+
 <Callout type="info">
 **`dateField == today()` now matches (#3183).** A `date` field reads back as a
 `YYYY-MM-DD` string, and CEL treats a string and a timestamp as unequal — so the
@@ -479,18 +500,20 @@ Field.formula({
 ❌ **DON'T:**
 - Create circular references
 - Use formulas for frequently changing data
-- Nest too many IF statements
+- Nest ternaries so deeply the expression stops being readable
 - Ignore null handling
 
 ---
 
 ## Determinism contract
 
-Two consecutive `objectstack build` runs with no source changes must produce
+Two consecutive `os build` runs with no source changes must produce
 **byte-identical** `dist/objectstack.json`. CEL plus pinned `now` is what
 makes this possible — there are zero compile-time-evaluated `Date.now()`
-calls in seed metadata. CI enforces this via SHA-1 comparison; if you add a
-new dialect or stdlib helper, ensure it preserves determinism.
+calls in seed metadata: a CEL seed value travels into the artifact as
+unevaluated source and only resolves at install. This is a design contract
+held by review, not a gate — no CI job currently diffs two builds — so if you
+add a new dialect or stdlib helper, ensure it preserves determinism.
 
 ---
 
@@ -524,7 +547,7 @@ Salesforce semantics rewrite their formulas in CEL.
 ```ts
 import { ExpressionEngine } from '@objectstack/formula';
 
-// Compile + cache
+// Compile — parse + type-check, returning the engine-native AST as `value`
 const compiled = ExpressionEngine.compile({ dialect: 'cel', source: 'record.x * 2' });
 
 // Evaluate
@@ -536,11 +559,11 @@ const result = ExpressionEngine.evaluate(
 ```
 
 The low-level engine never throws — `evaluate()` returns `{ ok: false, error }`.
-But **call sites must not silently swallow that** (ADR-0032): `objectstack build`
+But **call sites must not silently swallow that** (ADR-0032): `os build`
 **fails** on an invalid expression (with a located, schema-aware message), and at
 runtime the flow/rule engines **throw** a loud, attributed error instead of
 treating a bad expression as `false`/`null`. The same `validateExpression`
-validator backs `objectstack build` and metadata registration (and the
+validator backs `os build` and metadata registration (and the
 agent-callable `validate_expression` tool), so an expression is checked before it ships.
 
 ---

content/docs/data-modeling/formulas.mdx

@@ -5,7 +5,7 @@ description: Step-by-step guide for migrating from @objectql/core to @objectstac
 
 # Migrating from `@objectql/core` to `@objectstack/objectql`
 
-Starting with `@objectstack/objectql` v3.1, all core functionality previously provided by `@objectql/core` is now available upstream. This guide walks you through migrating your project so that `@objectql/core` can be removed.
+The core functionality previously provided by `@objectql/core` — the introspection types, the utility functions, and the kernel factory — was upstreamed into `@objectstack/objectql` in **v3.0.4** and has shipped in every release since (the current release line is **v16.x**). This guide walks you through migrating your project so that `@objectql/core` can be removed.
 
 ## Why Migrate?
 
@@ -26,7 +26,7 @@ Starting with `@objectstack/objectql` v3.1, all core functionality previously pr
     "dependencies": {
 -     "@objectql/core": "^4.x",
 -     "@objectql/types": "^4.x",
-+     "@objectstack/objectql": "^3.1.0"
++     "@objectstack/objectql": "^16.1.0"
     }
   }
 ```

content/docs/deployment/migration-from-objectql.mdx

@@ -5,7 +5,7 @@ description: Deploy ObjectStack applications to Vercel with the Hono server adap
 
 # Deploy to Vercel
 
-ObjectStack 11 deploys to Vercel in **server mode** — serverless functions running the **Hono** adapter (`@objectstack/hono`). The published ObjectStack Studio/console ships as a static Vite SPA that points at a separate ObjectStack server (via `VITE_SERVER_URL`).
+ObjectStack deploys to Vercel in **server mode** — serverless functions running the **Hono** adapter (`@objectstack/hono`). The Console SPA can also be deployed on its own as a static Vite build that points at a separate ObjectStack server (via `VITE_SERVER_URL`) — but that build comes from the Console source repo ([objectui](https://github.com/objectstack-ai/objectui)), not from the prebuilt `@objectstack/console` package.
 
 <Callout type="warn">
 **Removed in 11.** The in-browser MSW mode (`@objectstack/plugin-msw`) and the Next.js adapter (`@objectstack/nextjs`) are no longer published — use the Hono server path below.
@@ -43,7 +43,7 @@ In Server mode, ObjectStack runs inside Vercel Serverless Functions. API request
 This is a valid self-contained pattern when you want to ship a Vite SPA *and* its API from a single Vercel project: the SPA is served as static assets, and a Hono-based serverless function handles `/api/*` requests.
 
 <Callout type="info">
-The published ObjectStack Studio/console (`@objectstack/console`) does **not** use this topology. It deploys as a pure static SPA with no `api/` function — it is meant to be embedded in, or pointed at, a separate ObjectStack server via `VITE_SERVER_URL`. For that separate server, prefer the CLI (`objectstack serve`) over a hand-rolled Hono function.
+The framework-vendored Console (`@objectstack/console`) does **not** use this topology. It is a **prebuilt, dist-only** package — no source and no build step, just static assets — that an ObjectStack server mounts at `/_console` (`os serve --ui`, on by default). Its bundle is baked same-origin, and `VITE_SERVER_URL` is a build-time Vite flag, so aiming a Console at a *different* origin means building it yourself from the Console source repo ([objectui](https://github.com/objectstack-ai/objectui)). For the server itself, prefer the CLI (`os serve`) over a hand-rolled Hono function.
 </Callout>
 
 **1. Create the kernel singleton** (`api/_kernel.ts` — prefixed with `_` to prevent Vercel from creating a route):
@@ -82,7 +82,10 @@ export async function ensureApp(): Promise<Hono> {
 `InMemoryDriver` keeps this snippet self-contained, but on serverless **all data
 is lost on every cold start** — fine for a demo, wrong for anything real. Before
 going past a proof of concept, swap the driver for a real database (see
-[Database Drivers](/docs/data-modeling/drivers)) and point `OS_DATABASE_URL` at it.
+[Database Drivers](/docs/data-modeling/drivers)). A hand-built kernel does **not**
+resolve `OS_DATABASE_URL` on its own — that precedence lives in the CLI and in
+`createStandaloneStack()` — so read the connection string yourself, e.g.
+`new SqlDriver({ client: 'pg', connection: process.env.OS_DATABASE_URL })`.
 </Callout>
 
 **2. Create the API entrypoint** (`api/index.ts`):
@@ -134,7 +137,7 @@ Setting `VITE_SERVER_URL` to empty string tells the client SDK to use same-origi
 
 Configure these in Vercel Project Settings → Environment Variables:
 
-### Studio / SPA build
+### Console / SPA build
 
 | Variable | Description |
 | :--- | :--- |
@@ -179,7 +182,7 @@ storage for artifacts.
 - [ ] `api/_kernel.ts` boots the kernel with the correct driver
 - [ ] `vercel.json` sets `VITE_USE_MOCK_SERVER=false` and `VITE_SERVER_URL=` (empty)
 - [ ] Rewrite rule routes `/api/*` to `/api` and excludes `/api/` from SPA rewrite
-- [ ] `OS_DATABASE_URL` is configured in Vercel environment variables (for production drivers)
+- [ ] The production connection string is set in Vercel environment variables **and** read explicitly by the driver you construct in `api/_kernel.ts` (`OS_DATABASE_URL` is resolved by the CLI / `createStandaloneStack()`, not by a hand-built kernel)
 - [ ] CORS is configured if frontend and API are on different origins
 
 ---