okengine 0.18.5 → 0.19.0

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

@@ -1,220 +0,0 @@
----
-title: Installation
-description: Install okengine, scaffold an app with create-oke, and open the Console.
-source: README.md
-icon: Download
----
-
-This page gets you from zero to a running app on Bun. The engine targets
-**Bun ≥ 1.4.0** — prefer it for install, scaffold, and `oke dev`.
-
-<Callout title="The one rule">
-  The npm package is `okengine`; the CLI binary is `oke`. Use `bun add` in a project or `bun install
-  -g okengine` for a global `oke` on PATH. JSR is the library API only.
-</Callout>
-
-## Quick start
-
-<Steps>
-
-<Step>
-### Prerequisites
-
-- [Bun](https://bun.sh) ≥ 1.4.0 (`bun --version`)
-- [Docker](https://docs.docker.com/get-docker/) with a running daemon (`docker info`)
-- A terminal and a code editor
-
-`oke dev` always starts Docker Compose for Postgres / Redis / S3 / SMTP (and other pinned images). Use `oke test` for PGLite tests without Compose.
-
-</Step>
-
-<Step>
-### Install the package
-
-Project dependency (framework + local `oke`):
-
-```bash title="Terminal"
-bun add okengine
-```
-
-Global CLI (`oke` on PATH):
-
-```bash title="Terminal"
-bun install -g okengine
-```
-
-Library-only via JSR:
-
-```bash title="Terminal"
-bunx jsr add @omqkhafi/okengine
-```
-
-</Step>
-
-<Step>
-### Scaffold with create-oke
-
-```bash title="Terminal"
-bunx create-oke@latest my-app
-bunx create-oke@latest my-app --template standard
-bunx create-oke@latest my-app --template advanced
-bunx create-oke@latest my-app --sql postgres
-bunx create-oke@latest my-app --yes
-```
-
-Two Notes starters: **standard** and **advanced** (adds `store.index` + optional AI).
-Both are Docker-first; `test` uses PGLite / memory.
-
-The okengine repo also ships `examples/keel` — a work-management app, not a template.
-Run it with `bun run dev:keel` against Compose (Postgres, PgDog, Redis, RustFS, Mailpit,
-Meilisearch, llama.cpp). Wipe with `bun run dev:keel:reset`.
-
-On a TTY: pick a template, then **recommended defaults**, **customize**, or
-**reuse** (`~/.oke/create-defaults.json`). Reuse applies saved locales / PgDog /
-proxy without re-asking; recommended and customize ask and persist those answers.
-
-Customize walks Docker-first facets (including `store.index` with `none`), then
-**AI setup** (Recommended / Customize / Off). Project name rejects a non-empty
-existing path.
-
-Non-TTY / `--yes` stay scriptable. `--sql postgres` pins SQL; `--ai` runs the
-model wizard before install.
-
-</Step>
-
-<Step>
-### Run and verify
-
-```bash title="Terminal"
-cd my-app
-oke dev
-```
-
-Four ports come up together (mnemonic: **O·K·E = 6·5·3**):
-
-<Surfaces />
-
-Open `http://localhost:6533`. Paste the **claim code** from the `oke dev` board
-(or `oke console claim-code`). Password: **≥ 12** with upper, lower, number, and
-special, or **Generate** (copies it).
-
-Flows listed means the install worked — **derived, not configured.**
-`bun run web` starts the Vite Notes UI (proxies Flows to the app).
-
-</Step>
-
-</Steps>
-
-## Database sync in `oke dev`
-
-`oke dev` 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`.
-
-A broken `schema.decl.ts` prints a red ● `schema.decl.ts has an error — …` and
-keeps the session up — never a quiet `skipped`. Missing `oke.config.ts` / images
-still soft-skip.
-
-For production, generate and apply migrations deliberately — never automatic on
-boot:
-
-```bash title="Terminal"
-oke db generate   # write drizzle/*.sql
-oke db migrate    # apply
-```
-
-## Docker Compose under `oke dev`
-
-`oke dev` always brings up Compose under `docker/` and runs the app on host Bun
-with the `dev` driver profile (filled from `prod` when omitted). Credentials and
-host ports are unique per project.
-
-```bash title="Terminal"
-oke dev                      # full Compose set from images
-oke dev -d store.sql,signal  # optional: only these roles
-oke test                     # PGLite tests — no Compose
-```
-
-| 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`                  |
-
-Uncommented supported controls in the generated compose env are preserved when
-`oke dev` regenerates the file.
-
-Migrating from `local` / `docker` maps or `oke mode`?
-Rename the env keys in `oke.config.ts` to `dev` / `test` / `prod`.
-
-## Troubleshooting
-
-<Accordions>
-
-<Accordion title="oke: command not found after install">
-  Install the npm package `okengine` (not JSR alone): `bun add okengine` in the project, or `bun
-  install -g okengine` for a global binary. Or invoke via `bunx oke dev`. There is no separate `oke`
-  package name — only `okengine`.
-</Accordion>
-
-<Accordion title="Docker daemon not running">
-  `oke dev` requires Docker. Start Docker Desktop (or your engine), confirm with `docker info`, then
-  retry. For tests without Compose, use `oke test`.
-</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="Create first operator fails (password / claim code)">
-  Password: ≥ 12 with upper, lower, number, and special — or **Generate**. Copy the claim code from
-  the `oke dev` board (30 min TTL) or `oke console claim-code`. The form never gets the code over
-  HTTP; the log shows the reason, not a bare `500`.
-</Accordion>
-
-<Accordion title="Database out of sync after editing schema">
-  `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>
-
-<Accordion title="Docker containers left after deleting a project">
-  Each project gets its own `oke-dev-<id>` compose project; `oke dev` stop keeps volumes. Run
-  `oke docker clean` (TTY picker) or `oke docker clean --all --yes` from anywhere to remove
-  leftover containers, networks, and volumes.
-</Accordion>
-
-<Accordion title="Want a clean keel stack?">
-  Stop `bun run dev:keel`, then `bun run dev:keel:reset`. That wipes Compose, `.oke/`, and writes
-  `.env.local` from `.env.example`. Next `dev:keel` regenerates stack keys; seed copies them into
-  the built-in vault.
-</Accordion>
-
-</Accordions>
-
-## Learn more
-
-- [CLI Reference](/docs/reference/cli) — `oke`, `create-oke`, `oke test`, 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="Health Flow, typed client, and bun:test."
-    href="/docs/get-started/basic-usage"
-  />
-  <Card
-    title="Introduction"
-    description="The one law, eight elements, one contract."
-    href="/docs/get-started/introduction"
-  />
-  <Card
-    title="CLI Reference"
-    description="oke and create-oke commands."
-    href="/docs/reference/cli"
-  />
-</Cards>

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

@@ -1,144 +0,0 @@
----
-title: Introduction
-description: The Law, the eight elements, the fx rule, and the compiled Manifest contract.
-source: docs/spec/unified-theory.md
-icon: BookOpen
----
-
-## The One Law
-
-Every backend behavior is a Flow: `on(Trigger) → Effects`.
-
-```typescript
-import { on, flow, http } from "okengine/http";
-
-export const health = on(http.get().public(), flow({ do: () => ({ ok: true }) }));
-```
-
-An endpoint, a nightly cleanup cron, a queue consumer, a row-change CDC hook — these are not four frameworks. They are **one species** with one shape. Only the trigger changes.
-
-## Changing Only the Trigger
-
-Triggers determine what starts the flow while preserving identical anatomy and effect tracking:
-
-| Trigger                            | Starts when        | Replaces           |
-| ---------------------------------- | ------------------ | ------------------ |
-| `http.post("/bookings")`           | A request arrives  | Endpoint · handler |
-| `every("10m")`                     | Time passes        | Cron job           |
-| `orderPlaced` (a signal)           | Another flow emits | Queue consumer     |
-| `db.table(users).changed("email")` | A row changes      | CDC pipeline       |
-
-```typescript
-import { on, flow, http } from "okengine";
-
-on(http.post("/bookings"), createBooking);
-on(every("10m"), expireStale);
-on(orderPlaced, sendReceipt);
-on(db.table(users).changed("email"), reverify);
-```
-
-## Anatomy of a Flow
-
-Every Flow consists of four clear sections:
-
-| Piece         | Role                                                           |
-| ------------- | -------------------------------------------------------------- |
-| **Trigger**   | How work starts — `http`, a signal, `every`, a row change      |
-| **Contracts** | `in`, `out`, typed `errors` — validated before and after `do`  |
-| **`do`**      | The body — every read, write, emit, and call goes through `fx` |
-| **Effects**   | Inferred from those `fx` calls — not hand-annotated            |
-
-```typescript
-export const createOrder = on(
-  http.post("/orders"),
-  flow("orders.create", {
-    in: OrderInput,
-    out: OrderResult,
-    do: async (input, fx) => {
-      const order = await fx.store(db).insert(orders).values(input);
-      await fx.emit(orderPlaced, { orderId: order.id });
-      return order;
-    },
-  }),
-);
-```
-
-## The `fx` Rule
-
-**All world access goes through `fx`.**
-
-<Callout title="Single door to the world">
-  Nothing in user flows imports `node:fs`, calls global `fetch`, or calls `Date.now()`. Every effect
-  is recorded on the effect ledger.
-</Callout>
-
-| Inferred from `fx`      | What it powers                       |
-| ----------------------- | ------------------------------------ |
-| Cache invalidation keys | Invalidation follows the flow writes |
-| Live queries            | Realtime CDC subscriptions           |
-| Least-privilege tokens  | Compiler-derived capability matrix   |
-| Deterministic tests     | Injected time, clock, and stores     |
-| Manifest Diff           | Blast-radius checks on every save    |
-
-## The Compiled Manifest
-
-The source of truth is the backend model expressed in code. The **Manifest** is the compiled, versioned contract representing that model.
-
-| Surface                           | Port               | You Maintain?                 |
-| --------------------------------- | ------------------ | ----------------------------- |
-| Typed client (`okengine/client`)  | your app code      | No — derived from Manifest    |
-| Console panels, traces, explorers | `:6533`            | No — reads the Manifest       |
-| MCP for agents                    | `:6535`            | No — reads the Manifest       |
-| Architecture diagram              | Console            | No — it _is_ the effect graph |
-| Capability matrix + cache keys    | compiler / runtime | No — inferred from `fx`       |
-
-## The Eight Elements
-
-An element earns its place only if it has **irreducible physics**.
-
-| Element     | Essence                       | Replaces the Zoo                                          |
-| ----------- | ----------------------------- | --------------------------------------------------------- |
-| **Flow**    | Behavior                      | endpoint · handler · consumer · job · workflow · webhook  |
-| **Signal**  | Data in motion                | queue · pub/sub · stream · websocket · SSE · event bus    |
-| **Store**   | Data at rest                  | database · cache · KV · file storage · search index       |
-| **Clock**   | Time                          | cron · delay · timeout · durable sleep · TTL              |
-| **Gate**    | Permission to act             | auth · session · ABAC · rate limit · quota · feature flag |
-| **Vault**   | Protected knowledge           | secrets · config · environment                            |
-| **Channel** | Reaching humans               | email · SMS · WhatsApp · push                             |
-| **AI**      | Reaching machine intelligence | model calls · prompts · embeddings · agents · RAG         |
-
-New infrastructure becomes a **driver** for an existing element, never a ninth.
-
-## Core Programming Vocabulary
-
-The core programming vocabulary is ten exported names:
-
-```typescript
-import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
-```
-
-For HTTP runtime essentials, use the slim entry `okengine/http`:
-
-```typescript
-import { on, flow, http, gate, oke, createBunRuntime } from "okengine/http";
-```
-
-## Next Steps
-
-<Cards>
-  <Card
-    title="Why OKE"
-    description="Explore the problem of seams and the smaller model."
-    href="/docs/get-started/why"
-  />
-  <Card
-    title="Installation"
-    description="Scaffold a new OKEngine project with create-oke."
-    href="/docs/get-started/installation"
-  />
-  <Card
-    title="Basic Usage"
-    description="Write your first flow and verify it with bun test."
-    href="/docs/get-started/basic-usage"
-  />
-</Cards>

package/site/content/docs/get-started/meta.json

@@ -1,13 +0,0 @@
-{
-  "title": "Get Started",
-  "icon": "Rocket",
-  "pages": [
-    "index",
-    "why",
-    "introduction",
-    "installation",
-    "basic-usage",
-    "testing",
-    "project-structure"
-  ]
-}