okengine 0.1.6 → 0.2.2

package/AGENTS.md

@@ -76,7 +76,7 @@ A regression fails the build. Claims we cannot measure, we do not make.
 
 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`; templates are the `examples/*` trees.
+- `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`).
 
 Engine: Bun `>=1.3`.
 

package/README.md

@@ -8,32 +8,15 @@
 [![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) · **License:** MIT
+**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
 
 ### Install
 
 ```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    # scaffold from npm
+bunx create-oke@latest my-app --template hello   # scaffold from npm
 ```
-
-| Package | npm | JSR |
-|---|---|---|
-| Framework | [`okengine`](https://www.npmjs.com/package/okengine) | [`@omqkhafi/okengine`](https://jsr.io/@omqkhafi/okengine) |
-| Scaffold | [`create-oke`](https://www.npmjs.com/package/create-oke) | [`@omqkhafi/create-oke`](https://jsr.io/@omqkhafi/create-oke) |
-
-### npm vs JSR
-
-| Surface | npm | JSR |
-|---|---|---|
-| Library imports (`okengine`, `/client`, `/drivers`, …) | yes | yes |
-| Deep drivers (`okengine/drivers/postgres`, …) | yes | no — use `okengine/drivers`, or install from npm |
-| `oke` CLI | yes | no |
-| `create-oke` binary | yes | no — prefer `bunx create-oke@latest` from npm |
-
-JSR cannot rewrite the CLI’s dynamic imports of your app entry (`oke dev` / `oke start` / config load). Install `okengine` from npm when you need the binary. Deep driver subpaths use npm `exports` wildcards, which JSR does not support.
-
 ---
 
 ## Start here
@@ -52,14 +35,14 @@ Eight elements cover what a backend needs. Ten exports are the whole public voca
 import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
 ```
 
-Batteries included for the Bun era: contract-first APIs, typed client, infrastructure primitives, Console, auth — pure TypeScript, MIT, self-hostable, no cloud lock-in. Detail and comparisons live in [`docs/spec/unified-theory.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md).
+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
 
 ```bash
-bunx create-oke@latest my-app
+bunx create-oke@latest my-app --template hello
 cd my-app
 oke dev
 ```
@@ -68,9 +51,13 @@ oke dev
 |---|---|
 | `:6530` | your app |
 | `:6533` | Console |
-| `:6535` | MCP |
+| `: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.
 
-That scaffolds the **Notes** app (same tree as [`examples/notes`](https://github.com/omqkhafi/okengine/tree/main/examples/notes)). Open the Console — flows, contracts, effects, and an architecture diagram are already there. Derived, not configured.
+Prefer a worked teaching app (business logic + comments)? Use `--from-example notes|linkly|provisions|skyport` instead.
 
 ### The idea, in one file
 
@@ -144,7 +131,9 @@ The rest of the scaffold is small and ordinary: `oke.config.ts` (drivers by prot
 
 ## How to learn (read in order)
 
-Each app adds the smallest next set of ideas. Do not skip ahead.
+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)
@@ -158,7 +147,17 @@ Each app adds the smallest next set of ideas. Do not skip ahead.
 4. **Skyport** — `ai`, multi-tenancy, SLOs, distributed topology, scaling axes  
    → [`examples/skyport`](examples/skyport)
 
-Spec that teaches the same path: [`docs/spec/four-applications.md`](docs/spec/four-applications.md).
+Same path in the spec: [`docs/spec/four-applications.md`](docs/spec/four-applications.md).
+
+---
+
+## 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)
 
 ---
 
@@ -205,7 +204,7 @@ flowchart TD
 
 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. → [`docs/spec/console.md`](docs/spec/console.md)
+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).
 
 ---
 
@@ -327,7 +326,7 @@ Long form is canonical in docs; short form is convenience only. Shared letters f
 
 `.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.
+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).
 
 ---
 
@@ -341,13 +340,21 @@ The Console is treated as internet-facing even on localhost. Host header validat
 
 ---
 
+## Budgets
+
+Measured size and latency caps — see [`BUDGETS.md`](BUDGETS.md). Refresh with `bun run budgets`.
+
+---
+
 ## Status
 
-Pre-1.0. Published on [npm](https://www.npmjs.com/package/okengine) and [JSR](https://jsr.io/@omqkhafi/okengine) (`okengine` + `create-oke`, lockstep). MIT. No `CONTRIBUTING` yet — issues and PRs welcome.
+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.
 
-| Spec | Path |
+| 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) |