okengine 0.18.4 → 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,132 +0,0 @@
----
-title: Introduction
-description: Learn the one idea behind okengine — then the eight elements and core programming vocabulary you will use everywhere.
-source: docs/spec/unified-theory.md
-icon: BookOpen
----
-
-## The One Idea
-
-A booking API, a nightly cleanup job, a receipt email, a row-change hook — in most stacks those are four frameworks. In OKE they are **one species** with one shape. Learn the shape once; only the trigger changes.
-
-> **The one rule**
-> Every backend behavior is a **Flow**: `on(Trigger) → Effects`. There are no separate species called endpoints, handlers, consumers, jobs, or workflows.
-
-## Quick Start
-
-### Write One Flow
-
-Four contracts plus a `do`. This is the standard starter's health check:
-
-```typescript
-import { on, flow, http } from "okengine/http";
-
-export const health = on(http.get().public(), flow({ do: () => ({ ok: true }) }));
-```
-
-`main` omits the URL prefix, so this file is `GET /health` named `main.health`. See [Project structure](/docs/get-started/project-structure). Explicit `http.get("/health")` and `flow("main.health")` still win.
-
-### Change Only the Trigger
-
-Triggers define what starts the flow. Changing the trigger replaces the entire behavior while keeping the same structure:
-
-| 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
-
-One pipeline. Only the trigger changes between an endpoint, a job, a consumer, and a row hook.
-
-| 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            |
-
-Consequence: One documentation path, one trace shape, one Flow model, one thing for an AI agent to learn.
-
-## The `fx` Rule
-
-**All world access goes through `fx`.** A Flow that imports `node:fs`, calls `fetch` directly, or uses `Date.now()` is a defect.
-
-| Inferred From           | With `fx` |
-| ----------------------- | --------- |
-| Cache invalidation keys | Yes       |
-| Live queries            | Yes       |
-| Least-privilege tokens  | Yes       |
-| Deterministic tests     | Yes       |
-| Manifest Diff           | Yes       |
-
-## What the Manifest Derives
-
-At build time OKE extracts a **Manifest** — a machine-readable description of your system. You do not maintain a second source of truth.
-
-| Surface                           | Port / Place       | You Maintain?                 |
-| --------------------------------- | ------------------ | ----------------------------- |
-| Typed client (`okengine/client`)  | your app code      | No separate codegen           |
-| Console panels, traces, explorers | `:6533`            | No                            |
-| MCP for agents                    | `:6535`            | No                            |
-| Architecture diagram              | Console            | No — it _is_ the effect graph |
-| Capability matrix + cache keys    | compiler / runtime | No — from `fx`                |
-
-## The Eight Elements
-
-An element earns its place only if it has **irreducible physics**. New infrastructure becomes a new **driver** — never a ninth element.
-
-| 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         |
-
-## Core Programming Vocabulary
-
-The core programming vocabulary fits in one import. Everything else in the docs is derived from these names:
-
-```ts
-import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
-```
-
-For HTTP-only apps, prefer the slim entry so the cold graph stays on the edge:
-
-```ts
-import { on, flow, http, gate, oke, createBunRuntime } from "okengine/http";
-```
-
-Heavy surfaces (runs, journal factories, compiler extract, the legacy mega-barrel) live on `okengine/runs`, `okengine/journal`, `okengine/compiler`, and `okengine/full`.
-
-## Learn More
-
-| Topic   | Page                                                                            |
-| ------- | ------------------------------------------------------------------------------- |
-| Why OKE | [Why OKE](/docs/get-started/why)                                                |
-| Folders | [Project structure](/docs/get-started/project-structure)                        |
-| Flow    | [Flow](/docs/elements/flow)                                                     |
-| `fx`    | [fx](/docs/reference/fx)                                                        |
-| Agents  | [MCP](/docs/ai/mcp) · [Skills](/docs/ai/skills) · [llms.txt](/docs/ai/llms-txt) |
-
-## Next Steps
-
-- [Why OKE](/docs/get-started/why)
-- [Installation](/docs/get-started/installation)
-- [Basic Usage](/docs/get-started/basic-usage)
-- [Project Structure](/docs/get-started/project-structure)

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"
-  ]
-}