docs: P0 audit fixes — resolve contradictions, hand over the keys

Fixes the highest-leverage findings from the full docs audit (110 guide
pages reviewed against a customer-comprehension rubric).

Contradiction fixes (docs said two different things, or taught dead APIs):
- OWD: permissions-matrix table/example/callout now use the canonical four
  sharingModel values (ADR-0090 D4) instead of removed legacy aliases
- referenceFilters taught as a positive example while relationships.mdx
  documents it as schema-accepted-but-inert — fields.mdx now teaches
  structured lookupFilters + dependsOn; property tables mark it Legacy
- percent semantics unified to fraction storage (0.85 = 85%) across
  fields/decision-tree (validation-rules already had it right)
- hook input shape unified to the `{ doc }` contract (plugins tutorial
  handler + test now match kernel/events.mdx)
- libsql:// removed from self-hosting env table (driver ships in Cloud,
  not the open framework); backup page Turso section qualified
- api/index MCP row: actions require the author's ai.exposed opt-in
- permission-metadata: `positions` (not `roles`) is the canonical field
- common-patterns: all pattern objects now declare sharingModel and the
  page warns about namespace prefixes — examples pass the gate they teach

Key handovers (previously undocumented dead-ends):
- build-with-claude-code: seeded dev admin credentials at the verify step,
  npx os invocations, localhost MCP connect example
- api/index: new Authentication section (session sign-in + API keys)
- self-hosting: "First boot: create the admin" section (first signup =
  bootstrap admin); fixed dead examples/docker links (also docker/README)
- vercel: warn that InMemoryDriver loses data on every cold start
- getting-started prerequisites: Node 18+ only for the scaffold path
- kernel/services-checklist: stale-status warning banner
- quick-reference: unlink two non-existent reference pages

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

content/docs/api/index.mdx

@@ -15,7 +15,7 @@ ObjectStack exposes a fully typed REST API. All endpoints use JSON request/respo
 | :--- | :--- |
 | **REST** | ✅ Auto-generated from the protocol (`@objectstack/rest`) — CRUD, query, batch, metadata, packages |
 | **Realtime** | ⚠️ In-process pub/sub service (`@objectstack/service-realtime`, single-instance); the `/realtime/*` REST routes and WebSocket/SSE transport are plugin-provided — none ships in the open framework |
-| **MCP** | ✅ Non-system objects and their actions exposed as Model Context Protocol tools, gated by the caller's permissions/RLS rather than a per-action opt-in flag ([AI module](/docs/ai)) |
+| **MCP** | ✅ Non-system objects exposed automatically as Model Context Protocol tools; actions additionally require the author's `ai.exposed` opt-in — every call is gated by the caller's permissions/RLS ([AI module](/docs/ai)) |
 | **GraphQL** | ⚠️ Route is wired but **bring-your-own service**: `/graphql` returns 501 unless an implementation of the `IGraphQLService` contract is registered — none ships in the open framework |
 | **OData** | ⚠️ Vocabulary only: REST list endpoints accept OData-style operators (e.g. `$top`), but there is no standalone OData endpoint |
 
@@ -58,6 +58,23 @@ sequenceDiagram
 See [Actions as Tools](/docs/ai/actions-as-tools) for the `run_action` bridge and the
 [MCP reference](/docs/references/ai/mcp) for binding external MCP servers into your agents.
 
+## Authentication
+
+Every REST call runs as a principal — anonymous requests only see what your
+permission model grants anonymous users. Two ways to authenticate:
+
+- **Session cookie** (browsers, quick local tests): `POST /api/v1/auth/sign-in/email`
+  with `{ "email": "…", "password": "…" }` sets the session cookie — reuse it with
+  `curl -c cookies.txt` / `-b cookies.txt`. On a fresh dev database the seeded
+  admin is `admin@objectos.ai` / `admin123`.
+- **API key** (scripts, CI, headless agents): mint one with `POST /api/v1/keys`
+  (the key is shown once), or from **Setup → Connect an Agent** in the Console.
+  Send it as `x-api-key: osk_…` or `Authorization: Bearer osk_…`.
+
+See [Authentication](/docs/permissions/authentication) for the full identity
+surface (OAuth flows, sessions, providers) and
+[Plugin Endpoints](/docs/api/plugin-endpoints) for the auth route catalog.
+
 ## What's in this module
 
 - [Data API](/docs/api/data-api) — CRUD, batch operations, record cloning, and analytics queries

content/docs/data-modeling/field-type-decision-tree.mdx

@@ -146,7 +146,7 @@ flowchart TD
 |:---|:---|:---|
 | `number` | Any numeric value (set `precision`/`scale` for decimals) | `price`, `weight`, `quantity` |
 | `currency` | Money amounts with currency code | `amount`, `total_price` |
-| `percent` | Percentage values (0–100 or 0–1) | `completion`, `discount` |
+| `percent` | Percentage values, stored as fractions 0–1 (`0.85` = 85%) | `completion`, `discount` |
 | `rating` | Star ratings (typically 1–5) | `satisfaction`, `difficulty` |
 | `slider` | Numeric value via slider UI | `volume`, `priority_level` |
 

content/docs/data-modeling/field-types.mdx

@@ -301,7 +301,7 @@ Reference to a record in another object (foreign key).
 | Property | Type | Default | Description |
 |:---|:---|:---|:---|
 | `reference` | `string` | **required** | Target object name (snake_case) |
-| `referenceFilters` | `string[]` | — | Filters applied to lookup dialogs (e.g. `"active = true"`) |
+| `referenceFilters` | `string[]` | — | **Legacy** — accepted by the schema but not read by the record-picker (filters nothing). Use structured `lookupFilters` + `dependsOn` instead; see [Relationships](/docs/data-modeling/relationships) |
 | `deleteBehavior` | `'restrict' \| 'cascade' \| 'set_null'` | `'set_null'` | Behavior when referenced record is deleted (a *required* lookup left at the default `set_null` is escalated to `restrict`, since a NOT NULL foreign key cannot be cleared) |
 
 ```typescript
@@ -323,7 +323,7 @@ Parent-child relationship (cascading delete by default).
 | Property | Type | Default | Description |
 |:---|:---|:---|:---|
 | `reference` | `string` | **required** | Target (master) object name |
-| `referenceFilters` | `string[]` | — | Filters applied to lookup dialogs (e.g. `"active = true"`) |
+| `referenceFilters` | `string[]` | — | **Legacy** — accepted by the schema but not read by the record-picker (filters nothing). Use structured `lookupFilters` + `dependsOn` instead; see [Relationships](/docs/data-modeling/relationships) |
 | `deleteBehavior` | `'restrict' \| 'cascade' \| 'set_null'` | `'cascade'` | Behavior when parent is deleted (master-detail cascades unless set to `restrict`) |
 | `inlineEdit` | `boolean \| 'grid' \| 'form'` | — | Edit child records inline on the parent create/edit form (`true` = auto-pick, `'grid'`, or `'form'`) |
 | `inlineColumns` | `array` | — | Optional explicit inline grid columns |

content/docs/data-modeling/fields.mdx

@@ -63,7 +63,8 @@ notes: Field.markdown({ label: 'Notes' }),
 ```typescript
 quantity: Field.number({ label: 'Quantity', min: 0, max: 10000, step: 1 }),
 price: Field.currency({ label: 'Price', scale: 2, min: 0 }),
-discount: Field.percent({ label: 'Discount', scale: 2, min: 0, max: 100 }),
+// percent stores a fraction: 0.15 = 15% (the UI renders it as a percentage)
+discount: Field.percent({ label: 'Discount', scale: 2, min: 0, max: 1 }),
 ```
 
 **Currency Configuration:**
@@ -145,10 +146,13 @@ account: Field.lookup('account', {
   required: true,
 }),
 
-// Filtered lookup
+// Filtered lookup — structured filters, cascading from another field
 primary_contact: Field.lookup('contact', {
   label: 'Primary Contact',
-  referenceFilters: ['account = {account}', 'is_active = true'],
+  dependsOn: ['account'],
+  lookupFilters: [
+    { field: 'is_active', operator: 'eq', value: true },
+  ],
 }),
 
 // Master-detail (cascade delete)

content/docs/data-modeling/validation-rules.mdx

@@ -244,7 +244,7 @@ These properties apply to **all** field types and are validated by the base `Fie
 | Property | Type | Default | Validation Behavior |
 |:---|:---|:---|:---|
 | `reference` | `string` | — | **Required.** Target object name |
-| `referenceFilters` | `string[]` | — | Filter expressions for lookup dialogs |
+| `referenceFilters` | `string[]` | — | **Legacy** — schema-accepted but not read by the record-picker; use `lookupFilters` + `dependsOn` |
 | `deleteBehavior` | `enum` | `set_null` | `set_null`, `cascade`, or `restrict` |
 | `multiple` | `boolean` | `false` | Allow multiple references |
 

content/docs/deployment/backup-restore.mdx

@@ -57,10 +57,11 @@ sqlite3 /srv/data/app.db ".backup '/backups/app-$(date +%F).db'"
 The default location when `OS_DATABASE_URL` is unset is
 `<home>/data/objectstack.db` under the ObjectStack home directory.
 
-### Turso / libSQL and managed databases
+### Managed databases (hosted Postgres, MongoDB Atlas, …)
 
 Use the provider's snapshot, branching, or point-in-time-restore facilities.
-Nothing ObjectStack-specific applies.
+Nothing ObjectStack-specific applies. (Turso/libSQL applies only to ObjectStack
+Cloud-managed environments — the open framework does not ship that driver.)
 
 ## Backing up uploaded files
 

content/docs/deployment/self-hosting.mdx

@@ -32,7 +32,7 @@ workable default:
 
 | Variable | Why it must be set |
 |:---|:---|
-| `OS_DATABASE_URL` | Without it, data lands in a SQLite file under the ObjectStack home directory (`~/.objectstack`, or `<cwd>/.objectstack` next to a project config) — fine for one box, wrong for containers. Use `postgres://…`, `libsql://…`, or a mounted `file:…` path. |
+| `OS_DATABASE_URL` | Without it, data lands in a SQLite file under the ObjectStack home directory (`~/.objectstack`, or `<cwd>/.objectstack` next to a project config) — fine for one box, wrong for containers. Use `postgres://…`, `mongodb://…`, or a mounted `file:…` path (`libsql://` / Turso is **not** supported by the open framework — that driver ships in ObjectStack Cloud). |
 | `OS_AUTH_SECRET` | Session secret for the auth plugin (`AUTH_SECRET` is the legacy alias). Without it, `/api/v1/auth/*` is **silently skipped** — the server runs unauthenticated. |
 | `OS_SECRET_KEY` | 32-byte master key encrypting every stored secret (`openssl rand -hex 32`). On a container's ephemeral filesystem the auto-minted key is **lost on restart**, making previously-encrypted secrets undecryptable. |
 | `OS_PORT` | `os start` **fails loudly** if the port is busy (it never auto-shifts like `os dev`). Pin it and keep your reverse-proxy upstream in sync. |
@@ -117,7 +117,7 @@ straight from release storage instead of a mount.)
 For a self-contained deployable image, extend it. The Dockerfile below (plus
 the compose stack in the next section and a `.dockerignore`) ships
 ready-to-copy in
-[`examples/docker`](https://github.com/objectstack-ai/framework/tree/main/examples/docker)
+[`docker/`](https://github.com/objectstack-ai/framework/tree/main/docker)
 — drop the files into your scaffolded project.
 
 ```dockerfile title="Dockerfile"
@@ -314,6 +314,20 @@ decrypt each other's secrets. All replicas must share the same
 `OS_SECRET_KEY`, `OS_AUTH_SECRET`, and database. See
 [Cluster](/docs/kernel/cluster).
 
+## First boot: create the admin
+
+On a fresh production database there are no users yet. Open the deployment's
+root URL and **sign up — the very first account to register becomes the
+bootstrap admin** (this works even with `OS_DISABLE_SIGNUP=true`, which only
+blocks sign-ups after that first account exists). Do this immediately after
+the first deploy, before sharing the URL; then create your real user accounts
+and lock sign-up down via `OS_AUTH_SIGNUP_ENABLED` /
+[SSO](/docs/permissions/sso) as policy dictates.
+
+Note the production server seeds **no** dev credentials — the
+`admin@objectos.ai` / `admin123` account you may know from `os dev` exists only
+on empty development databases.
+
 ## Go-live
 
 Before pointing real users at the deployment, walk the

content/docs/deployment/vercel.mdx

@@ -78,6 +78,13 @@ export async function ensureApp(): Promise<Hono> {
 }
 ```
 
+<Callout type="warn">
+`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.
+</Callout>
+
 **2. Create the API entrypoint** (`api/index.ts`):
 
 ```typescript

content/docs/getting-started/build-with-claude-code.mdx

@@ -257,11 +257,12 @@ Validation proves the metadata is *well-formed*. It can't prove the app does wha
 *you* meant. That's the human half of the loop: **run it and look.**
 
 ```bash
-os dev --ui
+npx os dev --ui
 ```
 
-Open [http://localhost:3000/_console/](http://localhost:3000/_console/) and drive
-the app like a user:
+Open [http://localhost:3000/_console/](http://localhost:3000/_console/) and sign in
+as the dev admin the server seeds on an empty database
+(`admin@objectos.ai` / `admin123`). Then drive the app like a user:
 
 - Create a ticket. Confirm the fields, labels, and picklist colors match intent.
 - Check the **Resolve** action shows on an open ticket — and **disappears** once
@@ -316,7 +317,12 @@ its own OAuth 2.1 authorization server, so interactive clients just open a
 browser login (you connect as yourself, no admin-minted credentials):
 
 ```bash
+# the dev server you just booted in step 5
+claude mcp add --transport http support-desk http://localhost:3000/api/v1/mcp
+
+# or a deployed instance
 claude mcp add --transport http support-desk https://your-deployment.example.com/api/v1/mcp
+
 # first tool use opens a browser login — you're connected as yourself
 ```
 

content/docs/getting-started/common-patterns.mdx

@@ -11,6 +11,15 @@ This guide covers the most common patterns you will use when building applicatio
 **Import:** `import { defineStack, defineView, defineApp, defineFlow, defineAgent } from '@objectstack/spec'`
 </Callout>
 
+<Callout type="warn">
+**Before you copy:** the examples use short object names (`project`, `order`) for
+readability. In a real project, `os validate` additionally enforces your project's
+**namespace prefix** on every object name (`my_app_project`) and an explicit
+**`sharingModel`** on every custom object (ADR-0090) — the patterns below include
+`sharingModel`; remember to add your prefix. See
+[Validating Metadata](/docs/getting-started/validating-metadata).
+</Callout>
+
 ---
 
 ## 1. CRUD Object Definition
@@ -27,6 +36,7 @@ export default defineStack({
     {
       name: 'project',
       label: 'Project',
+      sharingModel: 'public_read_write',
       fields: {
         title: { label: 'Title', type: 'text', required: true, maxLength: 200 },
         description: { label: 'Description', type: 'textarea' },
@@ -53,6 +63,7 @@ export default defineStack({
   objects: {
     project: {
       label: 'Project',
+      sharingModel: 'public_read_write',
       fields: {
         title: { label: 'Title', type: 'text', required: true, maxLength: 200 },
         description: { label: 'Description', type: 'textarea' },
@@ -85,6 +96,7 @@ Create a parent-child relationship between a master and its detail records. Note
     {
       name: 'order',
       label: 'Order',
+      sharingModel: 'public_read',
       fields: {
         order_number: { label: 'Order #', type: 'autonumber', autonumberFormat: 'ORD-{0000}' },
         customer: { label: 'Customer', type: 'lookup', reference: 'contact' },
@@ -106,8 +118,10 @@ Create a parent-child relationship between a master and its detail records. Note
       }
     },
     {
+      // Master-detail child: access is derived from the parent order record
       name: 'order_line',
       label: 'Order Line',
+      sharingModel: 'controlled_by_parent',
       fields: {
         order: {
           label: 'Order',
@@ -265,6 +279,7 @@ Define a multi-step approval flow for records.
   objects: [{
     name: 'expense_report',
     label: 'Expense Report',
+    sharingModel: 'private',
     fields: {
       title: { label: 'Title', type: 'text', required: true },
       amount: { label: 'Amount', type: 'currency' },
@@ -402,6 +417,7 @@ Restrict field visibility and editability based on user profiles.
   objects: [{
     name: 'employee',
     label: 'Employee',
+    sharingModel: 'private',
     fields: {
       name: { label: 'Name', type: 'text', required: true },
       email: { label: 'Email', type: 'email', required: true },