okengine 0.2.6 → 0.3.2

package/AGENTS.md

@@ -1,6 +1,6 @@
 # OKE — Agent Contract
 
-This file is loaded by every later session. It prevents drift. Specs live in `docs/spec/`. **If the spec is silent, stop and ask.**
+This file is loaded by every later session. It prevents drift. Product documentation lives in `site/content/docs/`. **If the documentation is silent, stop and ask.**
 
 ## The one law
 
@@ -14,16 +14,16 @@ There are no separate species called endpoints, handlers, consumers, jobs, subsc
 
 ## The eight elements
 
-| Element | Essence |
-|---|---|
-| **Flow** | behavior |
-| **Signal** | data in motion |
-| **Store** | data at rest (`sql` · `kv` · `files` · `index`) |
-| **Clock** | time |
-| **Gate** | permission to act |
-| **Vault** | protected knowledge |
-| **Channel** | reaching humans |
-| **AI** | reaching machine intelligence |
+| Element     | Essence                                         |
+| ----------- | ----------------------------------------------- |
+| **Flow**    | behavior                                        |
+| **Signal**  | data in motion                                  |
+| **Store**   | data at rest (`sql` · `kv` · `files` · `index`) |
+| **Clock**   | time                                            |
+| **Gate**    | permission to act                               |
+| **Vault**   | protected knowledge                             |
+| **Channel** | reaching humans                                 |
+| **AI**      | reaching machine intelligence                   |
 
 An element earns its place only if it has irreducible physics. New infrastructure becomes a new **driver** for an existing element — never a ninth element.
 
@@ -53,39 +53,42 @@ A direct `node:` import (or any other side-channel I/O) in element or flow code
 
 ## Ports
 
-| Port | Surface |
-|---|---|
-| **6530** | App |
-| **6533** | Console |
-| **6535** | MCP |
+| Port     | Surface              |
+| -------- | -------------------- |
+| **6530** | App                  |
+| **6533** | Console              |
+| **6535** | MCP                  |
+| **6536** | Docs MCP (read-only) |
 
 Mnemonic: O·K·E = 6·5·3.
 
 ## Budgets
 
-| Budget | Limit |
-|---|---|
+| Budget                | Limit   |
+| --------------------- | ------- |
 | Kernel (edge profile) | < 15 kB |
-| Client runtime | < 3 kB |
-| Cold start on Bun | < 75 ms |
-| p99 routing overhead | < 1 ms |
+| Client runtime        | < 3 kB  |
+| Cold start on Bun     | < 75 ms |
+| p99 routing overhead  | < 1 ms  |
 
 A regression fails the build. Claims we cannot measure, we do not make.
 
 ## Package shape
 
 Published packages:
-- `okengine` — framework. Subpath exports: `.`, `./client`, `./test`, `./config`, `./auth`, `./drivers/*`. `"sideEffects": false`. CLI binary: `oke`.
-- `create-oke` — scaffold CLI (`bunx create-oke@latest <name>`). Lives in `packages/create-oke`; clean starters are `templates/*`, teaching apps stay in `examples/*` (`--from-example`).
+
+- `okengine` — framework. Subpath exports: `.`, `./client`, `./test`, `./config`, `./auth`, `./plugins`, `./drivers/*`. `"sideEffects": false`. CLI binary: `oke`.
+- `create-oke` — scaffold CLI (`bunx create-oke@latest <name>`). Lives in `packages/create-oke` and ships one standard starter from `packages/create-oke/template`.
 
 Engine: Bun `>=1.3`.
 
-## Spec authority
+## Documentation authority
 
-| Spec | Path |
-|---|---|
-| Unified theory | `docs/spec/unified-theory.md` |
-| Four applications | `docs/spec/four-applications.md` |
-| Console | `docs/spec/console.md` |
+| Surface  | Path                                 |
+| -------- | ------------------------------------ |
+| Theory   | `site/content/docs/elements/`        |
+| Console  | `site/content/docs/console/`         |
+| CLI      | `site/content/docs/reference/cli.md` |
+| Manifest | `manifest.v1.schema.json`            |
 
-**If the spec is silent, stop and ask.**
+**If the documentation is silent, stop and ask.**

package/README.md

@@ -7,7 +7,7 @@
 
 # okengine
 
-*"Encore's batteries and dashboard, Elysia's speed and DX, Hono's portability — without the Rust lock-in, the cloud gravity, or the source-available license."*
+_"Stop gluing APIs, jobs, and queues into one backend. One law collapses them — client, Console, and infra come free. Yours to host."_
 
 [![npm](https://img.shields.io/npm/v/okengine.svg)](https://www.npmjs.com/package/okengine)
 [![JSR](https://jsr.io/badges/@omqkhafi/okengine)](https://jsr.io/@omqkhafi/okengine)
@@ -15,372 +15,106 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Bun >=1.3](https://img.shields.io/badge/Bun-%3E%3D1.3-black.svg)](https://bun.sh)
 
-**Framework:** [`okengine`](https://www.npmjs.com/package/okengine) · **CLI:** `oke` · **Scaffold:** [`create-oke`](https://www.npmjs.com/package/create-oke) · **Docs:** [okengine.vercel.app](https://okengine.vercel.app) · **License:** MIT
+**Docs:** [oke.omqkhafi.dev](https://oke.omqkhafi.dev) · **Handbook:** [/docs](https://oke.omqkhafi.dev/docs) · **CLI:** `oke` · **Scaffold:** [`create-oke`](https://www.npmjs.com/package/create-oke)
 
-### Install
+> [!WARNING]
+> **Early development (`v0.x`) — not production-ready.**
+>
+> APIs, drivers, and tooling can change quickly, including **breaking changes**, until an initial stable release. Use for exploration and feedback — **not** production workloads yet.
 
-```bash
-bun add okengine                 # npm (recommended — ships the `oke` CLI)
-bunx jsr add @omqkhafi/okengine  # JSR — library API only
-bunx create-oke@latest my-app --template hello   # scaffold from npm
-```
----
-
-## Start here
-
-Most backends are a pile of separate tools under one logo: a router, a queue library, a cron library, websockets, tracing. The pieces ship together; they do not follow from one idea. That is why docs sprawl and concepts never get removed.
-
-OKE starts from one sentence instead:
-
-> **Every backend behavior is a Flow:** `on(Trigger) → Effects`
-
-An HTTP route, a cron job, a queue consumer, a CDC hook — same shape. Triggers are typed values. Side effects go through `fx` (the only door to the outside world), so the compiler can see them.
+## Install
 
-Eight elements cover what a backend needs. Ten exports are the whole public vocabulary. Everything else is derived.
-
-```typescript
-import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
+```bash
+bun add okengine                                   # framework + `oke` CLI
+bunx jsr add @omqkhafi/okengine                    # JSR — library API only
+bunx create-oke@latest my-app --template hello     # scaffold
 ```
 
-Batteries included for the Bun era: contract-first APIs, typed client, infrastructure primitives, Console, auth — pure TypeScript, MIT, self-hostable, no cloud lock-in. Handbook: [handbook](https://okengine.vercel.app/docs). Spec depth: [`docs/spec/unified-theory.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md).
-
----
-
-## Run something in two minutes
+## Quick start
 
 ```bash
 bunx create-oke@latest my-app --template hello
 cd my-app
 oke dev
+# or: oke mode docker && oke dev   # compose infra · app on host Bun
 ```
 
-| Port | What |
-|---|---|
-| `:6530` | your app |
-| `:6533` | Console |
-| `:6535` | MCP (your live Manifest, for agents) |
-
-Mnemonic: **O·K·E = 6·5·3**. Docs MCP for the handbook is a separate surface on `:6536` (search/fetch only — see [Documentation](#documentation)).
-
-That scaffolds the **hello** starter — one flow, no Store, the fastest true "it works" moment. Default without `--template` is **standard** (full recommended file layout, empty scaffolding). Open the Console — flows, contracts, effects, and an architecture diagram are already there. Derived, not configured.
+| Port    | Surface                                     |
+| ------- | ------------------------------------------- |
+| `:6530` | App                                         |
+| `:6533` | Console                                     |
+| `:6535` | MCP (live Manifest)                         |
+| `:6536` | Docs MCP (handbook search/fetch, read-only) |
 
-Prefer a worked teaching app (business logic + comments)? Use `--from-example notes|linkly|provisions|skyport` instead.
+Mnemonic: **O·K·E = 6·5·3**.
 
-### The idea, in one file
+Every backend behavior is a Flow: `on(Trigger) → Effects`. World access goes through `fx`.
 
-A flow is a trigger, contracts, and a `do` that only talks to the world through `fx`:
+Store apps sync schema with `oke db push|generate|migrate` (local `oke dev`
+auto-pushes). Prefer `store.schema.table` + `field.*` or keep a
+hand-written Drizzle `schema.ts`.
 
-### `examples/notes/src/flows/notes/index.ts`
+### Resource Flow
 
 ```typescript
-import { on, flow, http } from "okengine";
+import { on, http, store } from "okengine";
 import { createInsertSchema, createSelectSchema } from "drizzle-zod";
-import { z } from "zod";
 import { db } from "../../core";
-import { notes } from "../../schema";
-
-// Contracts derived from the schema — one source of truth, refined where the API is stricter
-const NewNote  = createInsertSchema(notes, { title: (s) => s.min(1).max(120) })
-                   .omit({ id: true, createdAt: true });
-const Note     = createSelectSchema(notes);
-const NoteId   = z.object({ id: z.string() });
-const NotFound = z.object({});
-
-export const create = on(http.post("/notes"), flow({
+import { notes as notesTable } from "../../schema";
+
+// Contracts derived from the schema — one source of truth.
+const NewNote = createInsertSchema(notesTable, { title: (s) => s.min(1).max(120) }).omit({
+  id: true,
+  createdAt: true,
+});
+const Note = createSelectSchema(notesTable);
+
+// One declarative resource: list (cursor + search + filters + order +
+// select), create (201), get / update / remove with typed NotFound.
+const notesR = store.resource(db, notesTable, {
   in: NewNote,
-  out: NoteId,
-  do: async (input, fx) => {
-    const [note] = await fx.store(db).insert(notes).values(input).returning();
-    return { id: note.id };
-  },
-}));
-// effects → writes[sql:notes]
-
-export const list = on(http.get("/notes"), flow({
-  out: Note.array(),
-  do: (_, fx) => fx.store(db).select().from(notes),
-}));
-// effects → reads[sql:notes]
-
-export const get = on(http.get("/notes/:id"), flow({
-  in: NoteId,
   out: Note,
-  errors: { NotFound },
-  do: async ({ id }, fx) => (await fx.store(db).findById(notes, id)) ?? fx.fail("NotFound", {}),
-}));
-
-export const remove = on(http.delete("/notes/:id"), flow({
-  in: NoteId,
-  errors: { NotFound },
-  do: async ({ id }, fx) => {
-    const deleted = await fx.store(db).delete(notes, id);
-    if (!deleted) return fx.fail("NotFound", {});
+  update: NewNote.partial(),
+  list: {
+    cursor: [notesTable.createdAt, notesTable.id],
+    direction: "desc",
+    limit: 20,
+    maxLimit: 100,
+    search: [notesTable.title],
+    filter: "all",
+    order: "all",
   },
-}));
-```
-
-Wire the unit into the app. The client needs only this type — no separate codegen:
-
-### `examples/notes/src/app.ts`
-
-```typescript
-import { oke } from "okengine";
-import * as notes from "./flows/notes";
-
-export const app = oke({ name: "notes" }).adopt({ notes });
-
-export type App = typeof app;   // ← the client needs nothing else
+  unit: "notes",
+  breaking: true,
+});
+
+// Mount all five verbs: list/create on /notes, get/update/remove on /notes/:id.
+// `on(http.resource(...))` returns the ops bag; spread it into named exports
+// so `adopt({ notes })` registers each flow under the unit.
+const mounted = on(http.resource("/notes", notesR.all()));
+
+export const list = mounted.list;
+export const create = mounted.create;
+export const get = mounted.get;
+export const update = mounted.update;
+export const remove = mounted.remove;
 ```
 
-The rest of the scaffold is small and ordinary: `oke.config.ts` (drivers by protocol), `src/schema.ts` (Drizzle table), `src/core.ts` (`store.sql`). Full walkthrough: [`docs/spec/four-applications.md`](docs/spec/four-applications.md) · §1 Notes.
-
----
-
-## How to learn (read in order)
-
-Start on the site if you want the handbook path: [Introduction](https://okengine.vercel.app/docs/get-started/introduction) → [Installation](https://okengine.vercel.app/docs/get-started/installation) → [Basic usage](https://okengine.vercel.app/docs/get-started/basic-usage).
-
-Each teaching app adds the smallest next set of ideas. Do not skip ahead.
-
-1. **Notes** — `oke`, `on`, `flow`, `http`, `store.sql`, `fx`, typed errors, typed client  
-   → [`examples/notes`](examples/notes)
-
-2. **Linkly** — `signal` (three delivery physics), `clock`, `gate`, triggers beyond HTTP, transactional emit  
-   → [`examples/linkly`](examples/linkly)
-
-3. **Provisions** — durable flows, `vault`, `channel`, live queries, plugins, CDC, cache tiers  
-   → [`examples/provisions`](examples/provisions)
-
-4. **Skyport** — `ai`, multi-tenancy, SLOs, distributed topology, scaling axes  
-   → [`examples/skyport`](examples/skyport)
-
-Same path in the spec: [`docs/spec/four-applications.md`](docs/spec/four-applications.md).
-
----
+Full walkthrough: [Basic usage](https://oke.omqkhafi.dev/docs/get-started/basic-usage).
 
 ## Documentation
 
-- **Site** — [okengine.vercel.app](https://okengine.vercel.app) (landing) · [handbook](https://okengine.vercel.app/docs) (handbook) · [changelog](https://okengine.vercel.app/changelog)
-- **Agents on the site** — [`/llms.txt`](https://okengine.vercel.app/llms.txt) index · [`/llms-full.txt`](https://okengine.vercel.app/llms-full.txt) full text · `/llms.mdx/docs/...` per-page markdown
-- **Docs MCP** — `:6536` · tools `oke.docs.search` / `oke.docs.get` (read-only; Host/Origin validated like the other surfaces)
-- **App MCP** — `:6535` · live Manifest, schemas, effects, traces, Console-safe actions (Bearer + confirmation for writes)
-- **Canonical specs in-repo** — [`docs/spec/`](docs/spec) (unified theory, four applications, Console)
-
----
-
-## The eight elements
-
-An element earns its place only if it has irreducible physics. New tech becomes a **driver**, never a ninth element.
-
-| Element | Essence | Replaces |
-|---|---|---|
-| **Flow** | behavior | endpoint, handler, consumer, job, workflow |
-| **Signal** | data in motion | queue, pub/sub, stream, websocket, SSE |
-| **Store** | data at rest | DB, cache, KV, files, search (`sql` · `kv` · `files` · `index`) |
-| **Clock** | time | cron, delay, timeout, durable sleep, TTL |
-| **Gate** | permission to act | auth, session, ABAC, rate limit, quota, flags |
-| **Vault** | protected knowledge | secrets, config, env |
-| **Channel** | reaching humans | email, SMS, WhatsApp, push |
-| **AI** | reaching machine intelligence | models, prompts, embeddings, agents, RAG |
-
----
-
-## What the Manifest is for
-
-Your TypeScript compiles to `manifest.oke.json`. From that one artifact the rest is derived — client, docs, Console, security matrix, Docker, bundle, tests ([unified theory §8](docs/spec/unified-theory.md#8-the-manifest--the-100-year-artifact)):
-
-```mermaid
-flowchart TD
-  code["your code"] -->|compile| manifest["manifest.oke.json"]
-  manifest --> client["typed client (+ live queries)"]
-  manifest --> docs["OpenAPI + AsyncAPI + documentation"]
-  manifest --> arch["architecture diagram (provably accurate — it IS the system)"]
-  manifest --> console["Console panels, traces, explorers"]
-  manifest --> mcp["MCP surface for AI agents"]
-  manifest --> caps["least-privilege capability matrix"]
-  manifest --> cache["cache invalidation keys"]
-  manifest --> replica["replica read-routing plan"]
-  manifest --> docker["Dockerfile + per-role compose files"]
-  manifest --> bundle["tree-shaken bundle contents"]
-  manifest --> harness["test harness wiring"]
-```
-
----
-
-## Console
-
-Seventeen panels on `:6533` (app `:6530`, MCP `:6535`): Overview, Flows, Signals, Store, Clock, Gates, Vault, Channels, AI, Architecture, Traces, Runs, Manifest Diff, Access, Plugins — plus Privacy and Tenancy when those plugins are plugged.
-
-Operator and user planes stay separate. Every Console action is a real flow through `fx`, so the audit log is the trace. Spec: [`docs/spec/console.md`](docs/spec/console.md) · handbook: [console handbook](https://okengine.vercel.app/docs/console/overview).
-
----
-
-## How to deploy
-
-OKE is self-host first — no cloud lock-in. Production artefacts are **derived from the Manifest**, not hand-written: Dockerfile, per-role compose files, and the same entry production actually runs ([unified theory §8](docs/spec/unified-theory.md#8-the-manifest--the-100-year-artifact), [§18](docs/spec/unified-theory.md#18-three-scaling-axes-never-conflated)).
-
-1. **Configure drivers and images** in `oke.config.ts` — drivers named after protocols; vendor images keyed by role (e.g. `store.sql`, `store.kv`).
-2. **Check the machine** before you ship:
-
-```bash
-oke doctor                       # secrets, ports, drivers, tenancy, schema drift
-oke doctor --json                # -j  agents / CI: JSON on stdout, hints on stderr
-oke stack                        # preview resolved images/tags/ports — writes nothing
-oke images list                  # recipe · image · tag · digest · size (writes nothing)
-```
-
-3. **Derive Docker / compose**, then pin digests so tags cannot drift:
-
-```bash
-oke docker                       # writes under docker/ (Dockerfile + compose.<role>.yml · …)
-oke docker --prod                # -p  healthchecks, volumes, limits, secret refs, deploy.replicas
-oke images pin                   # tags → digests in oke.images.lock
-```
-
-4. **Run what production runs.** `oke start` is the Docker `CMD` — the same process locally and in the container:
-
-```bash
-oke start                        # app on :6530 (Console :6533 stays on in prod, behind auth)
-```
-
-Horizontal scale is the **Clone** axis: run N instances; `oke docker --prod` emits `deploy.replicas`. Split into one container per unit is the **topology** axis — code unchanged (`monolith` vs `services`). For a tiny edge bundle: `oke build --target edge` (`-t`; < 15 kB kernel profile).
-
-There is no separate “deploy to our cloud” product. You take the derived Dockerfile/compose and run them on whatever host you choose.
-
----
-
-## CLI
-
-Everyday:
-
-```bash
-bun add okengine                 # ONE package
-
-oke dev                          # watch · hot reload · Console :6533 · app :6530 · MCP :6535
-                                 #   → also auto-syncs client types on every save
-oke dev --stack                  # -s  infra only under docker/ (Postgres/Redis/…); app stays on host Bun
-oke dev -s store.sql,store.kv    #     partial: only these roles get real backends
-
-oke start                        # runs exactly what production runs (this is the Docker CMD)
-oke doctor                       # verify secrets, ports, drivers, tenancy, schema drift
-oke doctor --diff                # -d  CI gate: undeclared Manifest contract breaks
-oke doctor --json                # -j  JSON on stdout; hints on stderr (agents / MCP)
-oke stack                        # preview resolved images/tags/ports — writes nothing
-oke stack --json                 # -j
-```
-
-Schema, vault, client, Docker, build, eval, branch, privacy, upgrade:
-
-```bash
-oke schema generate              # core + plugin tables → schema/oke.ts   (--check|-c in CI)
-oke vault set STRIPE_KEY         # also: list · import .env · key rotate
-oke client add <url>             # types for a separate frontend repo
-
-oke docker                       # artefacts under docker/ (Dockerfile + compose.<role>.yml · …)
-oke docker --prod                # -p  healthchecks, volumes, limits, secret refs, deploy.replicas
-oke images list                  # recipe · image · tag · digest · size (--json|-j)
-oke images pin                   # tags → digests in oke.images.lock
-
-oke build --target edge          # -t  < 15 kB kernel profile
-oke eval                         # run prompt eval sets; fails CI on regression
-oke branch prod --at "yesterday" # -a  fork journaled state into a sandbox
-oke privacy erase --subject <id> # -s  crypto-shredding: deletes the key, not the terabytes
-oke upgrade                      # dry-run codemods + diff; --apply|-a to write
-oke gates list                   # Module:Action catalogue (--json|-j)
-```
-
-Shell completion (generated from the command registry — not a hand-maintained script):
-
-```bash
-eval "$(oke completion bash)"
-eval "$(oke completion zsh)"
-oke completion fish | source
-```
-
-Long form is canonical in docs; short form is convenience only. Shared letters follow git’s pattern (different meanings on different subcommands — e.g. `-c` is `--check` on `schema generate`, `--config` on `stack` / `docker` / `images`).
-
-| Long | Short | Where |
-|------|-------|--------|
-| `--stack` | `-s` | `dev` |
-| `--prod` | `-p` | `docker` |
-| `--port` | `-p` | `start` |
-| `--check` | `-c` | `schema generate` |
-| `--config` | `-c` | `stack`, `docker`, `images` |
-| `--apply` | `-a` | `upgrade` |
-| `--at` | `-a` | `branch` |
-| `--after` | `-a` | `doctor --diff` |
-| `--target` | `-t` | `build` |
-| `--diff` | `-d` | `doctor` |
-| `--json` | `-j` | `doctor`, `stack`, `images list`, `gates list` |
-| `--manifest` | `-m` | most Manifest readers |
-| `--entry` | `-e` | `dev`, `start`, `build` |
-| `--out` / `--outdir` | `-o` | writers |
-| `--subject` | `-s` | `privacy erase` |
-| `--before` | `-b` | `doctor --diff` |
-| `--base` | `-B` | `doctor --diff` |
-
-| Exit | Meaning |
-|------|---------|
-| **0** | success |
-| **1** | usage / validation |
-| **2** | runtime / environment / check failure |
-
-`oke help` prints the same flag and exit-code tables.
-
----
-
-## Plugins and security
-
-`.plug()` attaches a plugin. Scope is the attachment point: `app.plug()` app-wide, `unit.plug()` one unit, `flow.plug()` one flow. No `global: true`, no inheritance rule — [unified theory §14](docs/spec/unified-theory.md#14-plugins--the-extensibility-law).
-
-The Console is treated as internet-facing even on localhost. Host header validation, Origin validation, and authentication are mandatory on `:6530`, `:6533`, and `:6535` ([console.md §10](docs/spec/console.md#10-security-posture)): two-plane auth (operator vs user), capability-scoped tokens. Docs MCP `:6536` uses the same Host/Origin checks and stays read-only (no Bearer writes).
-
----
-
-## Why Bun, one package, MIT
-
-**Bun-first** — toolchain stays on latest (TypeScript 7, Bun, oxc): greenfield, speed is part of the promise. User floor stays conservative; adopted infra pins stable digests ([§11](docs/spec/unified-theory.md#11-always-latest--in-three-tiers)).
-
-**One package** — `okengine` with subpath exports, not a monorepo of many packages to assemble. Small enough to be *finished* ([§27](docs/spec/unified-theory.md#27-package-structure-one-published-package), [§29](docs/spec/unified-theory.md#29-why-this-survives-a-hundred-years)).
-
-**MIT** — no BSL/SSPL; self-host first; drivers as the community surface. Adopt what exists; bind through Bun’s native clients ([§9](docs/spec/unified-theory.md#9-adopt-dont-reinvent--but-bind-natively), [§16](docs/spec/unified-theory.md#16-the-default-table), [§29](docs/spec/unified-theory.md#29-why-this-survives-a-hundred-years)).
-
----
-
-## Budgets
-
-Measured size and latency caps — see [`BUDGETS.md`](BUDGETS.md). Refresh with `bun run budgets`.
-
----
-
-## Local framework link (try changes without publishing)
-
-To exercise a local `okengine` checkout inside an app (e.g. `oke-1`) without npm publish:
-
-```bash
-# in the okengine repo
-bun link
-# if you changed the Console SPA:
-bun run build
-
-# in the app repo
-bun link okengine
-# edit okengine → restart `bun dev` in the app
-```
-
-Alternatively set `"okengine": "file:../okengine"` in the app `package.json` and run `bun install`.
-
----
-
-## Status
+Everything beyond this page lives in the site handbook:
 
-Pre-1.0. Published on [npm](https://www.npmjs.com/package/okengine) and [JSR](https://jsr.io/@omqkhafi/okengine) (`okengine` + `create-oke`, lockstep). Docs at [okengine.vercel.app](https://okengine.vercel.app). MIT. No `CONTRIBUTING` yet — issues and PRs welcome.
+| Resource      | Link                                                               |
+| ------------- | ------------------------------------------------------------------ |
+| Docs site     | [oke.omqkhafi.dev](https://oke.omqkhafi.dev)                       |
+| Handbook      | [/docs](https://oke.omqkhafi.dev/docs)                             |
+| Changelog     | [/changelog](https://oke.omqkhafi.dev/changelog)                   |
+| Agents index  | [/llms.txt](https://oke.omqkhafi.dev/llms.txt)                     |
+| CLI reference | [/docs/reference/cli](https://oke.omqkhafi.dev/docs/reference/cli) |
+| Manifest      | [`manifest.v1.schema.json`](manifest.v1.schema.json)               |
+| Budgets       | [`BUDGETS.md`](BUDGETS.md)                                         |
+| Contributing  | [`CONTRIBUTING.md`](CONTRIBUTING.md)                               |
 
-| Resource | Path |
-|---|---|
-| Docs site | [okengine.vercel.app](https://okengine.vercel.app) · [handbook](https://okengine.vercel.app/docs) · [changelog](https://okengine.vercel.app/changelog) |
-| Unified theory | [`docs/spec/unified-theory.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md) |
-| Four applications | [`docs/spec/four-applications.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/four-applications.md) |
-| Console | [`docs/spec/console.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/console.md) |
-| Scaffold | [`packages/create-oke`](https://github.com/omqkhafi/okengine/tree/main/packages/create-oke) |
-| Changelog source | [`docs/changelog.md`](docs/changelog.md) |
+Pre-1.0. Published on [npm](https://www.npmjs.com/package/okengine) and [JSR](https://jsr.io/@omqkhafi/okengine). MIT.

package/{spec/manifest.v1.schema.json → manifest.v1.schema.json}

@@ -104,10 +104,7 @@
   "$defs": {
     "JsonSchema": {
       "description": "A JSON Schema document, or an opaque string ref produced by extraction.",
-      "oneOf": [
-        { "type": "string", "minLength": 1 },
-        { "type": "object" }
-      ]
+      "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "object" }]
     },
     "ResourceRef": {
       "description": "Store resource: facet:name (sql:table, kv:namespace, files:bucket, index:name).",
@@ -289,10 +286,7 @@
         "durable": { "type": "boolean" },
         "live": { "type": "boolean" },
         "cache": {
-          "oneOf": [
-            { "type": "boolean" },
-            { "type": "string", "minLength": 1 }
-          ]
+          "oneOf": [{ "type": "boolean" }, { "type": "string", "minLength": 1 }]
         },
         "cacheKeys": {
           "description": "Computed invalidation key expression (derived or declared).",
@@ -342,6 +336,38 @@
         "retain": { "type": "string", "minLength": 1 }
       }
     },
+    "DeclaredColumn": {
+      "description": "Abstract schema column (DDL shape + optional classification). Bare ColumnClassification remains valid.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "enum": ["text", "integer"] },
+        "nullable": { "type": "boolean" },
+        "primaryKey": { "type": "boolean" },
+        "unique": { "type": "boolean" },
+        "default": {
+          "anyOf": [
+            { "type": "string" },
+            { "type": "number" },
+            { "type": "boolean" },
+            { "type": "null" }
+          ]
+        },
+        "sqlName": { "type": "string", "minLength": 1 },
+        "pii": { "type": "boolean" },
+        "sensitive": { "type": "boolean" },
+        "retain": { "type": "string", "minLength": 1 },
+        "references": {
+          "description": "Foreign key target from field.*.references().",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "table": { "type": "string", "minLength": 1 },
+            "column": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
     "Table": {
       "type": "object",
       "additionalProperties": false,
@@ -349,7 +375,12 @@
         "columns": {
           "type": "object",
           "propertyNames": { "type": "string", "minLength": 1 },
-          "additionalProperties": { "$ref": "#/$defs/ColumnClassification" }
+          "additionalProperties": {
+            "oneOf": [
+              { "$ref": "#/$defs/DeclaredColumn" },
+              { "$ref": "#/$defs/ColumnClassification" }
+            ]
+          }
         },
         "classifications": {
           "description": "Field → classification tags (pii, sensitive, retain duration).",