okengine 0.3.6 → 0.4.3

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.4.3",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -56,7 +56,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 +66,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 +78,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 +105,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/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/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));
   },
 });
 ```

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

@@ -72,6 +72,8 @@ A denied request never reaches `do`. It returns one of three typed failures, lik
 
 </Steps>
 
+<GatePipeline />
+
 ## Two kinds of gates
 
 | Declaration                           | Question it answers                    | Evaluated against                  |

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

@@ -76,11 +76,7 @@ That's the loop: declare → `fx.emit` → `on(signal, flow)`. The runtime handl
 
 ## The three delivery physics
 
-| `delivery`    | Semantics                                              | Use for                                                    |
-| ------------- | ------------------------------------------------------ | ---------------------------------------------------------- |
-| `"once"`      | Queue: competing consumers, retries, dead-letter queue | Jobs that must happen exactly once — emails, payments sync |
-| `"broadcast"` | Pub/sub: **every** subscriber receives a copy          | Cache invalidation, cross-service events                   |
-| `"live"`      | Stream: client-subscribable and replayable             | Live feeds, dashboards, progress updates                   |
+<SignalDelivery />
 
 The declaration is identical in shape for all three — switching physics later is a one-word change, not a migration to another library.
 

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

@@ -90,12 +90,7 @@ export const createNote = on(
 
 Pick the facet that matches the physics of your data. Each declaration is one line; the runtime handle shows what flows can do with it.
 
-| Facet                      | Declares          | Best for                              | `fx.store(…)` handle                                   |
-| -------------------------- | ----------------- | ------------------------------------- | ------------------------------------------------------ |
-| `store.sql(name, opts)`    | a SQL database    | domain tables, relations, constraints | `select` · `insert` · `update` · `delete` · `findById` |
-| `store.kv(name, opts?)`    | a key-value space | cache, sessions, rate limits          | `get` · `set(key, value, ttl?)` · `delete` · `list`    |
-| `store.files(name, opts?)` | a blob bucket     | uploads, exports, attachments         | `put` · `get` · `delete` · `list(prefix?)`             |
-| `store.index(name, opts)`  | a vector index    | semantic search / RAG (`dims`)        | `upsert` · `search(vector, topK?)` · `delete`          |
+<StoreFacets />
 
 Every facet accepts optional `description` — a human title in the Console
 (falls back to the store name). `store.index` also takes `dims`.
@@ -282,6 +277,32 @@ drivers: {
 
 **Consequence:** a configured SQL-backed index that cannot reach its engine — missing peer, missing `vector` extension, wrong sql driver — fails loudly at first use. It never silently falls back to `memory`.
 
+### Full-text search — `meilisearch` (opt-in)
+
+`meilisearch` is a fourth `store.index` backend, opt-in only — `memory` stays the default. It is a genuinely different capability from the vector ANN drivers: typo-tolerant, faceted full-text relevance, not cosine similarity. The two models are kept apart by a **discriminated union** on `driverId`, so TypeScript rejects a vector query against a text index (and vice versa) at compile time — never at runtime:
+
+| `driverId`                       | `upsert`              | `search`                                 | `score` means               |
+| -------------------------------- | --------------------- | ---------------------------------------- | --------------------------- |
+| `memory` / `pgvector` / `libsql` | `(id, vector, meta?)` | `search(vector, topK?)` → `IndexHit[]`   | cosine similarity           |
+| `meilisearch`                    | `(id, document)`      | `search(q, opts?)` → `{ hits, facets? }` | relevance (`_rankingScore`) |
+
+```typescript title="oke.config.ts"
+drivers: {
+  store: {
+    index: { local: "meilisearch", docker: "meilisearch", prod: "meilisearch" },
+  },
+},
+images: {
+  "store.index": "getmeili/meilisearch:v1.37",
+},
+```
+
+- **Local mode** needs the `meilisearch` binary on `PATH` (a documented prerequisite, like Docker for `--docker` — OKE never auto-downloads binaries). `oke dev` spawns it with a generated master key persisted under `.oke/meilisearch/` (`0700`/`0600`).
+- **Docker / prod** uses the image recipe; the app gets `OKE_STORE_INDEX_URL` + `OKE_STORE_INDEX_KEY` from Compose — a standalone HTTP service, never the shared `sqlUrl`.
+- **Fail-loud:** a configured meilisearch that is unreachable or unhealthy throws `MeilisearchUnavailableError` — never a silent memory fallback.
+- **Not for vectors:** `ai.embed` / `fx.search` stay vector-only; pointing an embed `into` a meilisearch index fails loud (embeddings don't apply).
+- **Alpine caveat:** the raw glibc binary fails on Alpine/musl _hosts_; the official image is musl-clean. Install the binary for your platform (e.g. Homebrew / install script), or use `--docker`.
+
 ## Privacy built in
 
 Columns tagged `.pii()` or `.sensitive()` are masked at the store boundary — flows, logs, and the Console see a mask, not the value. Revealing cleartext PII requires an explicit `pii:reveal` gate on the flow, so access is a permission, not a convention.

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

@@ -55,7 +55,9 @@ oke vault set STRIPE_KEY sk_test_your_key_here
 <Step>
 ### Read it in a Flow
 
-Flows read secrets through `fx.vault` — never through `process.env`:
+Flows read secrets through `fx.vault` — never through `process.env`. `fx.vault` returns a
+`Redacted<string>`: printing, logging, or serializing it yields a placeholder, never the value.
+Call `.reveal()` once at the boundary that needs the real credential:
 
 ```typescript title="src/flows/billing/charge.ts"
 export const charge = on(
@@ -64,14 +66,17 @@ export const charge = on(
     in: ChargeInput,
     out: z.object({ id: z.string() }),
     do: async (input, fx) => {
-      const key = fx.vault(stripeKey); // cleartext, inside this flow only
-      const intent = await stripe(key).create(input);
+      const key = fx.vault(stripeKey); // Redacted — safe to pass to fx.log
+      const intent = await stripe(key.reveal()).create(input);
       return { id: intent.id };
     },
   }),
 );
 ```
 
+`fx.log` masks any `Redacted` found in the logged data (nested included). A revealed string that
+still reaches `fx.log` is scrubbed by the boot redactor as before.
+
 </Step>
 
 </Steps>
@@ -111,13 +116,7 @@ export const dbUrl = vault.secret("DATABASE_URL", {
 
 At boot, each contract is resolved through this chain — **first hit wins**:
 
-| #   | Source               | Typical content                                   |
-| --- | -------------------- | ------------------------------------------------- |
-| 1   | `process.env`        | Real environment (CI, hosting platform)           |
-| 2   | `.env.local`         | Your machine's local overrides (gitignored)       |
-| 3   | `docker/.env.docker` | Generated compose stack credentials               |
-| 4   | vault driver         | OpenBao in docker/prod mode                       |
-| 5   | `dev` fallback       | The `dev:` option on the contract (never in prod) |
+<VaultResolution />
 
 If every layer misses a contract, boot **fails** before any request is served:
 
@@ -167,7 +166,7 @@ vault: {
 | `openbao` | OpenBao (KV v2) | Docker + prod — durable, access-controlled |
 | `memory`  | in-process map  | Tests                                      |
 
-Other drivers (`infisical`, `managed`) implement the same `VaultDriver` interface — adding one is a driver exercise, not an architecture change.
+Other drivers (`managed`) implement the same `VaultDriver` interface — adding one is a driver exercise, not an architecture change.
 
 ## OpenBao in docker and prod
 

package/site/content/docs/get-started/basic-usage.mdx

@@ -1,11 +1,24 @@
 ---
 title: Basic Usage
-description: Scaffold the standard starter, write a Flow, and inspect it in the Console.
+description: Scaffold the standard starter, call the health Flow, and inspect it in the Console.
 source: packages/create-oke/template
 icon: SquareTerminal
 ---
 
-## Scaffold an app
+Write your first Flow, call it from a typed client, and prove it with
+`bun:test` — using the same standard starter `create-oke` scaffolds.
+
+<Callout title="The one rule">
+  All reads, writes, emits, sends, and external calls belong behind `fx`. That is what makes effects
+  inspectable and tests deterministic.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Scaffold and run
 
 ```bash title="Terminal"
 bunx create-oke@latest my-app
@@ -13,26 +26,16 @@ cd my-app
 oke dev
 ```
 
-The app runs on `:6530`, the Console on `:6533`, and MCP on `:6535`.
+<Surfaces />
 
-## Mental model
+</Step>
 
-Every backend behavior has one shape:
+<Step>
+### Read the health Flow
 
-```text
-on(Trigger) → Effects
-```
+The standard starter already exports a health Flow:
 
-1. **Trigger** — how work starts (`http.post`, `every("10m")`, a signal, …)
-2. **Contracts** — `in`, `out`, and typed `errors`
-3. **`do`** — the body; world access goes only through `fx`
-4. **Effects** — inferred from the `fx` calls
-
-## Your first Flow
-
-The standard starter includes a health Flow:
-
-```typescript
+```typescript title="flows/main"
 import { on, flow, http } from "okengine";
 import { z } from "zod";
 
@@ -45,57 +48,65 @@ export const health = on(
 );
 ```
 
-Open `src/flows/main/index.ts`, change the route or output, and save. The app and
-Console update together from the same Manifest.
+Change the route or output and save. App and Console update together from the
+same Manifest.
 
-<Callout title="The invariant">
-  All reads, writes, emits, sends, and external calls belong behind `fx`. This is what makes effects
-  inspectable and tests deterministic.
-</Callout>
+</Step>
 
-## Wire the app
+<Step>
+### Call it from a typed client
 
-The starter adopts the module in `src/app.ts`:
+Adopted modules become namespaces on the client:
 
-```typescript
+```typescript title="app"
 import { oke } from "okengine";
 import * as main from "./flows/main";
 
-export const app = oke({ name: "my-app" }).adopt({ main });
+export const app = oke({ name: "standard" }).adopt({ main });
 export type App = typeof app;
 ```
 
-The namespace becomes the typed-client namespace and each exported Flow becomes
-a method.
-
-## Typed client
-
-```typescript
+```typescript title="client"
 import { createClient } from "okengine/client";
-import type { App } from "../src/app";
+import type { App } from "./app";
 
 const api = createClient<App>("http://localhost:6530");
 const { data, error } = await api.main.health({});
 ```
 
-`data` and `error` are inferred from the Flow contracts; no separate client
-schema or code-generation project is required.
+`data` and `error` are inferred from the Flow contracts — no separate client
+schema or codegen project.
+
+</Step>
+
+</Steps>
+
+## Mental model
+
+Every backend behavior has one shape:
+
+<FlowShape />
+
+## From Flow to client
+
+Export → adopt → call or test. Same App type — no separate codegen project.
+
+<ClientLoop />
 
 ## Test
 
-Use `createTestApp` to boot the same app with test drivers:
+Boot the same app with test drivers:
 
-```typescript
+```typescript title="tests/standard.test.ts"
 import { expect, test } from "bun:test";
 import { createTestApp } from "okengine/test";
 import { app } from "../src/app";
 
-test("health", async () => {
+test("boots — health flow", async () => {
   const t = await createTestApp(app);
   const { data, error } = await t.api.main.health({});
   expect(error).toBeNull();
   expect(data).toEqual({ ok: true });
-  await app.stop();
 });
 ```
 
@@ -103,6 +114,30 @@ test("health", async () => {
 bun test
 ```
 
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="api.main.health is not a function / type error">
+  Confirm the Flow is `export`ed from the module you `.adopt({main})`, and that `createClient` is
+  typed with your `App` type. Restart `oke dev` after renaming exports so the Manifest refreshes.
+</Accordion>
+
+<Accordion title="createTestApp fails to boot">
+  The starter patches test env and stores on the app options. Keep the template's side-imports
+  (vault, gates, channels, core db) — removing them can leave Vault or Store unresolved under test
+  drivers.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Flow](/docs/elements/flow) — triggers, contracts, effects, and composition
+- [Store](/docs/elements/store) — SQL, KV, files, index
+- [fx](/docs/reference/fx) — the full effect surface
+- [Console · Overview](/docs/console/overview) — Manifest-derived panels
+
 ## Next
 
 <Cards>