okengine 0.3.6 → 0.5.0

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,31 +26,21 @@ 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
-import { on, flow, http } from "okengine";
+```typescript title="flows/main"
+import { on, flow, http, gate } from "okengine";
 import { z } from "zod";
 
 export const health = on(
-  http.get("/health"),
+  http.get("/health").gate(gate.public),
   flow({
     out: z.object({ ok: z.literal(true) }),
     do: () => ({ ok: true as const }),
@@ -45,57 +48,66 @@ 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. Bearer: `auth: { getToken, refresh }` (`okengine/client/auth` helpers;
+`useSession` in `okengine/client-react`). Full options: [Client](/docs/reference/client).
+
+</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 +115,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>

package/site/content/docs/get-started/index.mdx

@@ -0,0 +1,33 @@
+---
+title: "Get Started"
+description: "From the one law to a running app — introduction, why OKE, install, and first flows."
+icon: "Rocket"
+source: "docs/spec/unified-theory.md"
+---
+
+Learn the shape once, install on Bun, then write your first Flow from the standard starter.
+
+## Pages
+
+<Cards>
+  <Card
+    title="Introduction"
+    description="One law, eight elements, ten exports."
+    href="/docs/get-started/introduction"
+  />
+  <Card
+    title="Why OKE"
+    description="Six seams every backend maintains by hand."
+    href="/docs/get-started/why"
+  />
+  <Card
+    title="Installation"
+    description="Scaffold with create-oke and open the Console."
+    href="/docs/get-started/installation"
+  />
+  <Card
+    title="Basic Usage"
+    description="Health Flow, typed client, Console proof."
+    href="/docs/get-started/basic-usage"
+  />
+</Cards>

package/site/content/docs/get-started/installation.mdx

@@ -5,31 +5,43 @@ source: README.md
 icon: Download
 ---
 
-This page gets you from zero to a running app. Prefer Bun throughout — the engine targets **Bun ≥ 1.3**.
+This page gets you from zero to a running app on Bun. The engine targets
+**Bun ≥ 1.3** — prefer it for install, scaffold, and `oke dev`.
+
+<Callout title="The one rule">
+  Prefer `bun add okengine` when you want the `oke` CLI on your PATH. JSR (`@omqkhafi/okengine`) is
+  the library API only.
+</Callout>
+
+## Quick start
 
 <Steps>
 
+<Step>
 ### Prerequisites
 
 - [Bun](https://bun.sh) ≥ 1.3 (`bun --version`)
 - A terminal and a code editor
 
-### Install the package
+</Step>
 
-Add the framework (ships the `oke` CLI):
+<Step>
+### Install the package
 
 ```bash title="Terminal"
 bun add okengine
 ```
 
-<Callout title="JSR">
-  Library API only: `bunx jsr add @omqkhafi/okengine`. Prefer npm / `bun add` when you want the
-  `oke` CLI on your PATH via the package.
-</Callout>
+Library-only via JSR:
 
-### Scaffold with create-oke
+```bash title="Terminal"
+bunx jsr add @omqkhafi/okengine
+```
+
+</Step>
 
-Create the standard recommended project layout:
+<Step>
+### Scaffold with create-oke
 
 ```bash title="Terminal"
 bunx create-oke@latest my-app
@@ -37,74 +49,114 @@ bunx create-oke@latest my-app --template standard
 bunx create-oke@latest my-app --sql postgres
 ```
 
-The standard template is the only starter. `--sql postgres` opts into a
-`pgTable` schema and pins local, Docker, and production to Postgres; the default
-keeps local SQLite with Docker and production on Postgres.
+`standard` is the only starter. Default: local SQLite, Docker/production
+Postgres. `--sql postgres` pins `store.sql` for **local, Docker, and
+production** — schema stays dialect-agnostic (`store.schema.table`).
+
+</Step>
 
-### Run the app
+<Step>
+### Run and verify
 
 ```bash title="Terminal"
 cd my-app
 oke dev
 ```
 
-Local mode watches domain schema paths (`schema.ts` / `schema.decl.ts` / `app.ts`)
-and auto-runs `oke db push` (drizzle-kit) so the database stays in sync. Opt out
-with `oke dev --no-db-push` or `db: { autoPush: false }` in `oke.config.ts`. For
-production, generate and apply migrations deliberately:
+Three ports come up together (mnemonic: **O·K·E = 6·5·3**):
+
+<Surfaces />
+
+Open `http://localhost:6533`. If the Console lists your flows, the install
+worked — **derived, not configured.**
+
+</Step>
+
+</Steps>
+
+## Local database sync
+
+Local mode watches schema paths and auto-runs `oke db push` so the database
+stays in sync. Opt out with `oke dev --no-db-push` or
+`db: { autoPush: false }` in `oke.config.ts`.
+
+For production, generate and apply migrations deliberately — never automatic on
+boot:
 
 ```bash title="Terminal"
 oke db generate   # write drizzle/*.sql
-oke db migrate    # apply — never automatic on boot
+oke db migrate    # apply
 ```
 
-Three ports come up together (mnemonic: **O·K·E = 6·5·3**):
-
-| Port    | Surface  |
-| ------- | -------- |
-| `:6530` | Your app |
-| `:6533` | Console  |
-| `:6535` | MCP      |
-
-Open the Console — flows, contracts, effects, and an architecture diagram are already there. **Derived, not configured.**
+## Docker mode
 
 Want Postgres/Redis like production while the app stays on host Bun?
 
+<DevModes />
+
 ```bash title="Terminal"
 oke dev --docker   # or: oke dev -d
 # or set the saved default: oke mode docker
 ```
 
-That uses the `docker` driver profile in `oke.config.ts` (filled from `prod` when omitted). Compose files and credentials land under `docker/` (`.env.docker` beside compose). Host ports — including Mailpit UI / RustFS console extras — are unique per project so multiple apps can run at once. Bare `oke dev` prompts once on a TTY (saved in `.oke/mode`); non-TTY defaults to `local`.
+Uses the `docker` driver profile in `oke.config.ts` (filled from `prod` when
+omitted). Compose and credentials land under `docker/` (`.env.docker` beside
+compose); host ports are unique per project.
 
-The generated env follows each protocol instead of forcing one generic credential shape:
+Bare `oke dev` prompts once on a TTY (saved in `.oke/mode`); non-TTY defaults
+to `local`.
 
-- Postgres: `DATABASE_URL` plus `OKE_STORE_SQL_*`
-- Redis: `REDIS_URL` plus `OKE_STORE_KV_PASSWORD`
-- S3-compatible files: `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BUCKET`, `S3_URL`, `S3_REGION`, and `S3_CONSOLE_URL`
-- SMTP email: `SMTP_URL`, `SMTP_HOST`, `SMTP_PORT`, and `MAILPIT_UI_URL` with optional `SMTP_USER` / `SMTP_PASSWORD`
+| Protocol            | Env shape (generated)                                                                                           |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Postgres            | `DATABASE_URL` plus `OKE_STORE_SQL_*`                                                                           |
+| Redis               | `REDIS_URL` plus `OKE_STORE_KV_PASSWORD`                                                                        |
+| S3-compatible files | `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BUCKET`, `S3_URL`, `S3_REGION`, `S3_CONSOLE_URL` |
+| SMTP email          | `SMTP_URL`, `SMTP_HOST`, `SMTP_PORT`, `MAILPIT_UI_URL`, optional `SMTP_USER` / `SMTP_PASSWORD`                  |
 
-Each section also includes commented controls (for example Redis memory policy,
-Postgres init options, Bun S3 session tokens, and Mailpit limits). Uncommented
-supported controls are preserved when `oke dev --docker` regenerates the file.
+Each section also includes commented controls (Redis memory policy, Postgres
+init options, Bun S3 session tokens, Mailpit limits). Uncommented supported
+controls are preserved when `oke dev --docker` regenerates the file.
 
-### Verify the install
+## Troubleshooting
 
-Hit the app (path depends on the template) or open `http://localhost:6533`. If the Console lists your flows, the install worked.
+<Accordions>
 
-</Steps>
+<Accordion title="oke: command not found after install">
+  Use `bun add okengine` (npm package), not JSR alone — the CLI ships with the npm distribution. Or
+  invoke via `bunx oke dev` from the project.
+</Accordion>
+
+<Accordion title="Console is empty / no flows listed">
+  Confirm `oke dev` is running and you opened `:6533`, not `:6530`. Flows appear only after the app
+  boots and the Manifest is extracted — fix TypeScript errors in the terminal first.
+</Accordion>
+
+<Accordion title="Database out of sync after editing schema">
+  Local `oke dev` auto-pushes by default. If you passed `--no-db-push` or set `db.autoPush: false`,
+  run `oke db push` yourself, or re-enable auto-push.
+</Accordion>
 
-## Next steps
+</Accordions>
 
-Continue to [Basic Usage](/docs/get-started/basic-usage) for your first Flow,
-typed client, and test.
+## Learn more
+
+- [CLI Reference](/docs/reference/cli) — `oke`, `create-oke`, mode, and db commands
+- [Environment variables](/docs/reference/environment-variables) — protocol-shaped env
+- [Configuration](/docs/reference/configuration) — `oke.config.ts` drivers and `db.autoPush`
+
+## Next
 
 <Cards>
   <Card
     title="Basic Usage"
-    description="First flows, client, and tests."
+    description="Health Flow, typed client, and bun:test."
     href="/docs/get-started/basic-usage"
   />
+  <Card
+    title="Introduction"
+    description="The one law, eight elements, ten exports."
+    href="/docs/get-started/introduction"
+  />
   <Card
     title="CLI Reference"
     description="oke and create-oke commands."