okengine 0.3.6 → 0.5.0

package/AGENTS.md

@@ -96,3 +96,5 @@ Engine: Bun `>=1.3`.
 ## After every implementation
 
 Before claiming work done: run [`.agents/skills/oke-ship`](.agents/skills/oke-ship/SKILL.md) — append notes to `changelog.md` under `## Unreleased` (never under a shipped `## v…` section), and update site docs via [`.agents/skills/oke-docs`](.agents/skills/oke-docs/SKILL.md) for any user-facing surface. Version bump is separate: `bun run bump` promotes Unreleased into the next `## vX.Y.Z`.
+
+Dependency bumps (one package, one `package.json`, or all): [`.agents/skills/oke-deps`](.agents/skills/oke-deps/SKILL.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.3.6",
+  "version": "0.5.0",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -26,6 +26,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./client": "./src/client/index.ts",
+    "./client/auth": "./src/client/auth.ts",
+    "./client-react": "./src/client-react/index.ts",
     "./test": "./src/test/index.ts",
     "./config": "./src/config/index.ts",
     "./auth": "./src/auth/index.ts",
@@ -56,7 +58,7 @@
     "prepack": "bun run build",
     "bench": "bun test ./src/runtime/cold-start.bench.ts src/client/budget.test.ts src/console/budget.test.ts src/kernel/budget.test.ts src/kernel/routing-budget.test.ts src/runs/bench.test.ts",
     "budgets": "bun src/release/publish.ts",
-    "gate": "bun test src/cli/doc-staleness.test.ts src/drivers/vault-driver-removal.test.ts src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts",
+    "gate": "bun test src/cli/doc-staleness.test.ts src/cli/competitor-mention-removal.test.ts src/drivers/vault-driver-removal.test.ts src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts",
     "dev": "bun run --cwd site dev",
     "site:build": "bun run --cwd site build",
     "ci": "bun scripts/ci.ts",
@@ -66,10 +68,10 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@duckdb/node-api": "^1.5.5-r.1",
+    "@duckdb/node-api": "^1.5.5-r.2",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "oxc-parser": "^0.141.0",
+    "oxc-parser": "^0.142.0",
     "sently": "^0.8.0"
   },
   "devDependencies": {
@@ -78,20 +80,20 @@
     "@codemirror/lang-json": "^6.0.2",
     "@codemirror/state": "^6.7.1",
     "@codemirror/theme-one-dark": "^6.1.3",
-    "@codemirror/view": "^6.43.6",
+    "@codemirror/view": "^6.43.7",
     "@electric-sql/pglite": "^0.5.4",
     "@electric-sql/pglite-pgvector": "^0.0.5",
     "@libsql/client": "^0.17.4",
-    "@oxc-project/types": "^0.141.0",
-    "@playwright/test": "^1.62.0",
+    "@oxc-project/types": "^0.142.0",
+    "@playwright/test": "^1.62.1",
     "@sinclair/typebox": "^0.34.52",
     "@tailwindcss/vite": "^4.3.3",
     "@tanstack/react-query": "^5.101.4",
     "@tanstack/react-router": "^1.170.18",
     "@types/bun": "latest",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.4",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@vitejs/plugin-react": "^6.0.5",
     "arktype": "^2.2.3",
     "axe-core": "^4.12.1",
     "clsx": "^2.1.1",
@@ -105,13 +107,13 @@
     "oxfmt": "^0.61.0",
     "oxlint": "^1.76.0",
     "oxlint-tsgolint": "^7.0.2001",
-    "playwright": "^1.62.0",
+    "playwright": "^1.62.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.3.3",
     "typescript": "^7.0.2",
     "valibot": "^1.4.2",
-    "vite": "^8.1.5",
+    "vite": "^8.2.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/site/content/docs/ai/index.mdx

@@ -0,0 +1,24 @@
+---
+title: "AI Resources"
+description: "Machine-facing surfaces — MCP on :6535/:6536, agent skills, and /llms.txt."
+icon: "Bot"
+source: "docs/spec/unified-theory.md"
+---
+
+Resources for AI agents that read or operate an OKE app — not the `ai` element itself.
+
+## Pages
+
+<Cards>
+  <Card title="MCP" description="Runtime MCP on :6535; docs MCP on :6536." href="/docs/ai/mcp" />
+  <Card
+    title="Skills"
+    description="AGENTS.md contract and installable skills."
+    href="/docs/ai/skills"
+  />
+  <Card
+    title="llms.txt"
+    description="Machine-readable docs index and pages."
+    href="/docs/ai/llms-txt"
+  />
+</Cards>

package/site/content/docs/ai/llms-txt.mdx

@@ -31,6 +31,9 @@ curl https://oke.omqkhafi.dev/llms.mdx/docs/elements/vault
   only when breadth matters more than tokens; per-page `/llms.mdx` is the precise instrument.
 </Callout>
 
+The homepage **Onboard AI** button copies a one-line prompt that points an agent at
+`/llms.txt` plus the repo-root `AGENTS.md` — project-wide context, not a single docs page.
+
 ## How it pairs with the docs MCP
 
 These endpoints serve the _published_ docs of the framework. During `oke dev`, the [docs MCP server](/docs/ai/mcp) also runs on :6536 (`oke.docs.search` / `oke.docs.get`), answering from the same content over the MCP protocol — pick the plain HTTP endpoints for one-shot context, the MCP tools when the agent is already connected as a client.

package/site/content/docs/ai/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "AI Resources",
   "icon": "Bot",
-  "pages": ["mcp", "skills", "llms-txt"]
+  "pages": ["index", "mcp", "skills", "llms-txt"]
 }

package/site/content/docs/ai/skills.mdx

@@ -7,14 +7,15 @@ source: "docs/spec/unified-theory.md"
 
 Tools alone don't make a good operator — an agent also needs to know the _vocabulary_: what a Flow is, why `fx` is the only door, which driver ids are legal. OKE ships that knowledge as contracts and skills that agents load automatically, so sessions start aligned instead of drifting and getting corrected.
 
-## The four layers
+## The layers
 
 | Layer              | Path                       | Loaded when                                       | Teaches                                                               |
 | ------------------ | -------------------------- | ------------------------------------------------- | --------------------------------------------------------------------- |
 | **Agent contract** | `AGENTS.md` (repo root)    | Every agent session, automatically                | The one law, eight elements, ten exports, the fx rule, ports, budgets |
 | **Element skill**  | `.agents/skills/oke/`      | Building or changing an okengine app              | The element contract in depth — declaration patterns per element      |
 | **Docs skill**     | `.agents/skills/oke-docs/` | Writing or editing docs under `site/content/docs` | The documentation information-architecture standard and its gates     |
-| **Ship skill**     | `.agents/skills/oke-ship/` | After any implementation, before claiming done    | Changelog under the current version + docs sync via `oke-docs`        |
+| **Ship skill**     | `.agents/skills/oke-ship/` | After any implementation, before claiming done    | Changelog under `## Unreleased` + docs sync via `oke-docs`            |
+| **Deps skill**     | `.agents/skills/oke-deps/` | Updating `package.json` dependencies              | Scoped bumps, Bun install, pins (Drizzle RC, fumadocs alias, …)       |
 
 ## AGENTS.md — the root contract
 
@@ -22,13 +23,14 @@ Every OKE app's repo carries an `AGENTS.md` that agents (Cursor, Claude Code, an
 
 ## Skills — installable know-how
 
-Skills are `SKILL.md` packages an agent loads when the work matches their description. The three OKE ships:
+Skills are `SKILL.md` packages an agent loads when the work matches their description. OKE ships:
 
 | Skill      | Use it for                                   | Inside                                                                    |
 | ---------- | -------------------------------------------- | ------------------------------------------------------------------------- |
 | `oke`      | App work — flows, elements, drivers          | The agent contract, element patterns, the fx invariants                   |
 | `oke-docs` | Docs work — new pages, rewrites              | The page skeleton, verification sources, the density gate                 |
 | `oke-ship` | Closing an implementation — changelog + docs | Append under `## Unreleased`; `bun run bump` promotes it into `## vX.Y.Z` |
+| `oke-deps` | Dependency updates — one package or all      | Scope map, `ncu` + Bun, reject downgrades / protect RC and aliases        |
 
 All live in the repo under `.agents/skills/`, so they travel with the code and stay versioned with what they describe.
 

package/site/content/docs/console/gates.mdx

@@ -1,13 +1,15 @@
 ---
 title: "Gates"
-description: "Permission matrix, rate counters, MFA map."
+description: "Permission inquiry, rate counters, and continuous audit of unguarded vs explicitly public flows."
 icon: "Shield"
 source: "docs/spec/console.md"
 ---
 
-Answers: **permission matrix, rate counters, MFA map**
+The Gates panel answers **who may do what** without dumping a giant roles×permissions matrix as
+the home screen. Inquire from a principal or from a flow; the simulator shows the chain in
+evaluation order.
 
-<Callout title="Governing rule">
+<Callout title="The one rule">
   Refuse the giant roles×permissions matrix as the entry point — inquire from principal or from
   flow.
 </Callout>
@@ -15,10 +17,10 @@ Answers: **permission matrix, rate counters, MFA map**
 ## What this panel shows
 
 <Cards>
-  <Card title="Simulator" description="Gate chain in evaluation order — where a 403 stopped." />
+  <Card title="Simulator" description="Gate chain in evaluation order — where a denial stopped." />
   <Card
-    title="Unguarded flows"
-    description="Continuous audit: public user-plane flows after deploy."
+    title="Unguarded vs public"
+    description="Empty chain (missing posture) vs gate.public (intentional)."
   />
   <Card title="Deploy diff" description="Permission widening caught from Manifest Diff." />
   <Card
@@ -27,9 +29,45 @@ Answers: **permission matrix, rate counters, MFA map**
   />
 </Cards>
 
+## Unguarded vs explicit public
+
+| Flag            | Meaning                                                                      |
+| --------------- | ---------------------------------------------------------------------------- |
+| Unguarded       | User-plane flow with an **empty** gate chain — missing auth posture          |
+| Explicit public | Chain includes the reserved `public` sentinel (`gate.public` on the trigger) |
+
+App boot fails on unguarded HTTP triggers (`GateBootError`) unless `env === "test"` and
+`gate: { unguardedHttp: "allow" }`. Prefer fixing the flow: attach a policy, or attach
+`gate.public` when the surface is intentionally open.
+
+App authors configure Gate under `oke({ gate: { policies, auth, unguardedHttp } })` — see
+[Gate](/docs/elements/gate). Builtin `/auth/*` Flows from `gate.auth` are audited the same way.
+
 ## Catalog
 
+Policies, rates, and `/auth/*` Bindings from the Manifest — inquire and audit, not a live
+rate editor. Rate `overridable` is a catalog flag; schedule edits live under
+[Clock](/docs/console/clock).
+
 <Cards>
-  <Card title="Dev" description="full" />
-  <Card title="Prod" description="limits if `overridable`" />
+  <Card title="Dev" description="full catalog + simulator" />
+  <Card title="Prod" description="same inquire surface; no silent ungated HTTP" />
+</Cards>
+
+## Learn more
+
+- [Gate](/docs/elements/gate) — policies, rate limits, `gate.auth`, posture
+- [Plugins](/docs/plugins) — plugged sign-in method plugins
+- [Access](/docs/console/access) — roles and API keys
+
+## Next
+
+<Cards>
+  <Card title="Gate" description="Declare policies and auth." href="/docs/elements/gate" />
+  <Card title="Access" description="Roles and API keys." href="/docs/console/access" />
+  <Card
+    title="Overview"
+    description="Console panels from the Manifest."
+    href="/docs/console/overview"
+  />
 </Cards>

package/site/content/docs/console/index.mdx

@@ -0,0 +1,54 @@
+---
+title: "Console"
+description: "Manifest-derived operator panels on :6533 — health, elements, traces, access, and more."
+icon: "LayoutDashboard"
+source: "docs/spec/console.md"
+---
+
+The Console is derived from your Manifest. Each panel answers one operator question.
+
+## Pages
+
+<Cards>
+  <Card
+    title="Overview"
+    description="Is the system healthy right now?"
+    href="/docs/console/overview"
+  />
+  <Card
+    title="Flows"
+    description="What exists; call it; read its contract."
+    href="/docs/console/flows"
+  />
+  <Card title="Signals" description="Queue depth, in-flight, DLQ." href="/docs/console/signals" />
+  <Card title="Store" description="Browse sql/kv/files/index." href="/docs/console/store" />
+  <Card title="Clock" description="Crons, sleeps, journal." href="/docs/console/clock" />
+  <Card
+    title="Gates"
+    description="Permission matrix and rate counters."
+    href="/docs/console/gates"
+  />
+  <Card title="Vault" description="Secret contracts and rotation." href="/docs/console/vault" />
+  <Card
+    title="Channels"
+    description="Templates, receipts, opt-outs."
+    href="/docs/console/channels"
+  />
+  <Card title="AI" description="Prompts, evals, cost, agents." href="/docs/console/ai" />
+  <Card title="Architecture" description="How it all connects." href="/docs/console/architecture" />
+  <Card title="Traces" description="One timeline across effects." href="/docs/console/traces" />
+  <Card title="Runs" description="Wide events per execution." href="/docs/console/runs" />
+  <Card
+    title="Manifest Diff"
+    description="Blast radius of a deploy."
+    href="/docs/console/manifest-diff"
+  />
+  <Card title="Access" description="Identities, roles, API keys." href="/docs/console/access" />
+  <Card title="Plugins" description="Installed plugins and panels." href="/docs/console/plugins" />
+  <Card title="Privacy" description="Where PII lives (conditional)." href="/docs/console/privacy" />
+  <Card
+    title="Tenancy"
+    description="Per-tenant usage (conditional)."
+    href="/docs/console/tenancy"
+  />
+</Cards>

package/site/content/docs/console/meta.json

@@ -2,6 +2,7 @@
   "title": "Console",
   "icon": "LayoutDashboard",
   "pages": [
+    "index",
     "overview",
     "flows",
     "signals",

package/site/content/docs/elements/ai.mdx

@@ -86,6 +86,8 @@ export const triage = smart.prompt("ticket-triage", {
 | `evals`      | string                | Path to a `.jsonl` eval set, regression-gated via `oke eval`   |
 | `budget`     | object                | `maxCostPerCall` — cost is a first-class dimension             |
 
+<AiGuardrails />
+
 ## Agents with real guardrails
 
 An agent's tools are your flows — each carrying its own gates, effects, and typed errors, so the agent can never do anything a flow couldn't:

package/site/content/docs/elements/channel.mdx

@@ -79,6 +79,8 @@ Locally the `console` driver captures mail into an inbox instead of sending; in
 
 ## The human physics
 
+<ChannelPhysics />
+
 ### Consent is checked before sending
 
 Opt-out is first-class: a subject who opted out of a medium is **suppressed** — the send resolves without contacting the provider, and the receipt says so. You never hand-roll "did they unsubscribe?" checks.

package/site/content/docs/elements/clock.mdx

@@ -83,10 +83,7 @@ do: async (input, fx) => {
 
 ## Two kinds of schedules
 
-| Declaration         | Shows in Console | Cron + timezone | Runtime-editable   | Use for                           |
-| ------------------- | ---------------- | --------------- | ------------------ | --------------------------------- |
-| `every("1h")`       | no               | no              | no                 | Simple fixed intervals            |
-| `clock(name, opts)` | yes              | yes             | when `overridable` | Business schedules operators tune |
+<ClockSchedules />
 
 Both are triggers consumed with the same `on(trigger, flow)` — the flow underneath does not know the difference.
 

package/site/content/docs/elements/flow.mdx

@@ -96,13 +96,7 @@ Every response follows one envelope — success `{ data, error: null }`, failure
 
 ## The five triggers
 
-| Trigger                      | Starts when                  | Replaces           |
-| ---------------------------- | ---------------------------- | ------------------ |
-| `http.post("/orders")`       | a request arrives            | endpoint · handler |
-| `orderPlaced` (a signal)     | another flow emits           | queue consumer     |
-| `every("1h")`                | time passes                  | cron job           |
-| `db.table(orders).changed()` | a row changes                | CDC pipeline       |
-| — none                       | another flow calls `fx.call` | "private" helper   |
+<FlowTriggers />
 
 ### http — a request arrives
 
@@ -192,7 +186,7 @@ Everything a flow may touch, on one object:
 | `fx.ask(prompt, input)`                 | ask             | Call a versioned AI prompt                   |
 | `fx.run(agent, input)`                  | ask             | Run a bounded agent                          |
 | `fx.call(flow, input)`                  | call            | Invoke another flow                          |
-| `fx.vault(contract)`                    | read            | Read a secret (redacted from logs)           |
+| `fx.vault(contract)`                    | read            | Read a secret (`Redacted`; logs masked)      |
 | `fx.clock.now()` / `.sleep(…)`          | —               | Injected time / durable sleep                |
 | `fx.cache.get/set`                      | —               | Shared cache with effect-aware invalidation  |
 | `fx.step(name, fn)`                     | —               | Named durable step — never re-runs on replay |
@@ -218,12 +212,12 @@ export const chargeOrder = flow({
   out: z.boolean(),
   do: async ({ orderId }, fx) => {
     const intent = await fx.step("create-intent", () =>
-      stripe(fx.vault(stripeKey)).create(orderId),
+      stripe(fx.vault(stripeKey).reveal()).create(orderId),
     );
 
     await fx.clock.sleep("verify-window", "2m"); // survives restart and deploy
 
-    return fx.step("confirm", () => stripe(fx.vault(stripeKey)).confirm(intent));
+    return fx.step("confirm", () => stripe(fx.vault(stripeKey).reveal()).confirm(intent));
   },
 });
 ```