anbaric 1.20.0 → 1.21.0

package/README.md

@@ -1,208 +1,380 @@
-# anbaric
+# Anbaric
 
-Anbaric is a TypeScript framework for building stateful applications. An
-application is expressed as one or more state machines: long-lived jobs move
-through named states, driven by actions and transitions, with their data
-validated against a schema and every change recorded in an audit trail.
-Alongside the state machine the framework provides schema-validated document
-storage and secret storage.
+Anbaric is a TypeScript framework for building stateful enterprise applications. Anbaric is designed to help vibe-coded applications go the last mile, by providing persistence, state management, authentication and auditing.
 
-Anbaric also provides a platform for deploying the applications built on it. The
-same application runs unchanged on a developer's machine, on a server you
-operate, or on Anbaric Cloud, where a single CLI command deploys it. Application
-code depends only on the interfaces in this package; the framework selects
-in-memory or platform-backed implementations from the environment, so no
-deployment detail appears in the code.
+We believe that fully bespoke software is the future, and this project was created to help a wider range of people build their own solutions, without compromising enterprise IT standards.
 
-This package (`anbaric`) is the umbrella install for writing an application. It
-re-exports the app-facing surface of the underlying packages.
+## Getting started
+
+Install the Anbaric package and the CLI:
 
 ```bash
+npm init
 npm install anbaric
+npm install -g anbaric-cli
 ```
 
-An Anbaric application is a standard Node.js ESM program written in TypeScript:
-set `"type": "module"` in `package.json`, point `main` at the TypeScript entry
-file, and run it with `tsx`.
-
-## State machines
-
-A **`StateMachine`** defines a workflow. It is constructed with an identifier, a
-list of states, the name of the start state, and the property schema for its
-jobs.
-
-- A **`State`** is a named step. It holds a list of **actions** to run while a
-  job sits in that state, and a list of **transitions** to the next state.
-- An **`Action`** is a unit of work. Its `run` function receives the job and
-  returns a `Map` of property changes: `run(job) => Promise<Map<string, any>>`.
-  An action does not mutate the job directly; the returned properties are
-  validated and applied by the machine. Each action declares the **actor** that
-  performs it.
-- A **`Transition`** names a target state and carries a predicate over the job.
-  When a job is processed, the first transition whose predicate holds moves the
-  job to that state.
-- A **`Job`** is one instance moving through the machine. It carries an
-  identifier, its current `state`, a `Map` of `properties`, and provenance
-  (`workflowId`, `startedBy`, `startedAt`, `lastUpdated`). Jobs are immutable;
-  each change produces a new version.
-- A **`PropertyDefinition`** describes one property a job may carry: whether it
-  is required and how its value is validated. Every property a job holds —
-  including properties set by actions — must have a definition, or the change is
-  rejected.
-- An **`Actor`** identifies who performs an operation, for authorization and
-  auditing. The actor types are `Code`, `Human`, `Agent` and `System`. `Code`
-  actions run automatically as jobs are processed; a `Human` or `Agent` actor
-  represents work performed by a person or an autonomous agent.
-
-A job progresses automatically as it is processed: matching actions run, their
-properties are applied, and the first satisfied transition advances the state.
-This repeats until the job reaches a state from which nothing more applies.
+Prompt your agent:
 
-There are three ways to influence a job:
+```
+Use Anbaric to build me a CRM.
+```
+
+Run locally as usual (`npm run start`) or deploy to the Anbaric Cloud (`anbaric app deploy`).
+
+Anbaric is open source and you can self-host the platform or sign up at https://cloud.anbaric.ai to use the hosted version.
 
-- `startJob(properties?, actor?)` creates a job in the start state.
-- `updateJob(jobId, properties, actor)` applies an explicit property change.
-- `executeAction(jobId, action)` runs a single action immediately.
-- Actions subscribed to a state run automatically whenever a job in that state
-  is processed.
+## Documentation
 
-Every operation is validated against the schema and written to the audit trail,
-which records the resource, the actor, the interactions (create, update, state
-change, delete, read), and a description of what changed.
+A full user guide — split into **features**, **patterns** and **API reference**
+(TypeScript and web) — lives in [`anbaric/docs`](anbaric/docs/README.md). Start
+with [Core concepts](anbaric/docs/features/core-concepts.md), then the
+[Build your first app](anbaric/docs/patterns/first-app.md) walkthrough.
 
-## Documents and secrets
+## What the code looks like
 
-For data that does not belong to a job, the framework provides two stores,
-obtained from factories and used with an actor for auditing.
+Anbaric has a collection of features that can be used in your application. Here are some examples:
 
-- **`JsonStore`** stores JSON documents in named collections, optionally
-  validated against a JSON Schema.
-- **`SecretStore`** stores named secret strings, encrypted at rest, and never
-  records secret values in the audit trail.
+### Persist JSON
+
+In this example we will store a customer's details in a JSON document. Every change that is made in Anbaric requires an `Actor` to be specified, which is used to ensure a complete audit trail exists for any application built using Anbaric. In general, an actor will be either a "human" actor, an AI agent or code being executed by the system.
+
+When your app serves a page to a signed-in user, `Human.fromSession` turns that request into the human actor behind it — it resolves the browser's platform session (the `anbaric_session` cookie) against the platform, so the audit trail names the real user. Pass it the incoming request (or the session token directly). Outside a request — a seed script or system code — construct the actor yourself, e.g. `new Human("ada", ["admin"])` or a `Code` actor.
 
 ```ts
-import {Human, JsonStoreFactory, SecretStoreFactory} from "anbaric";
+import {Human, JsonStoreFactory} from "anbaric";
 
-const actor = new Human("ada", "admin");
+// inside your app's HTTP handler, `request` is the incoming browser request
+const actor = await Human.fromSession(request);
+const customers = JsonStoreFactory.instance("customers");
+
+await customers.create(actor, "ada", { name: "Ada Lovelace", email: "ada@example.com" });
+const ada = await customers.retrieve("ada", actor);
+```
 
-const customers = JsonStoreFactory.instance("customers", {
-    type: "object",
-    required: ["name"],
-    properties: { name: { type: "string" } },
+### Run a state machine
+
+A state machine models work as jobs moving through named states. Actions run while a job sits in a state, and transitions decide where it goes next. A state machine can combine steps using different types of actors, so humans can own some action, AI agents and code can automate others.
+
+```ts
+import {Action, Code, PropertyDefinition, State, StateMachine, Transition} from "anbaric";
+
+const sendWelcome = new Action("Send welcome email", new Code("welcome"));
+sendWelcome.run = async (job) => {
+    // Access properties stored against the job
+    const email = job.properties.get("email");
+    // Run some code
+    console.log(`Sending welcome email to ${email}`);
+    // Return new properties to add to the job
+    const newProperties = new Map();
+    newProperties.set("emailSent", true);
+    return newProperties;
+};
+
+const onboarding = new StateMachine("onboarding", [
+    new State("new", [sendWelcome], [new Transition("active", (job) => job.properties.get("emailSent") === true)]),
+    new State("active"),
+]);
+
+const customer = await onboarding.startJob(new Map([["email", "ada@example.com"]]));
+```
+
+The job starts in `new`; when it is processed the action runs, sets `emailSent`, and the transition advances it to `active`.
+
+### Using AI agents to automate states
+
+An **agent** is an actor whose properties are produced by a model rather than by
+hand-written code. A `RemoteLLMAgenticAction` gives the agent a prompt and a JSON
+Schema, and applies the properties it returns to the job. Here an OpenAI-backed
+agent triages a support ticket:
+
+```ts
+import {OpenAIAgent, RemoteLLMAgenticAction, State, StateMachine, Transition} from "anbaric";
+
+const triager = new OpenAIAgent("triager", "support", {
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: "gpt-5.4-mini",
 });
-await customers.create(actor, "ada", { name: "Ada" });
-const record = await customers.retrieve("ada", actor);
 
-const secrets = SecretStoreFactory.instance();
-await secrets.create(actor, "api-key", "s3cr3t");
+const triage = new RemoteLLMAgenticAction(
+    "Triage the ticket",
+    triager,
+    [{ role: "system", content: "Decide the priority of the support ticket from its subject." }],
+    { type: "object", properties: { priority: { type: "string", enum: ["low", "high"] } } },
+);
+
+const support = new StateMachine("support", [
+    new State("open", [triage], [new Transition("prioritised", (job) => job.properties.has("priority"))]),
+    new State("prioritised"),
+]);
 ```
 
-## Running and deploying
-
-Persistence, queueing and consumers are supplied by environment-driven
-factories, so the same application runs in several ways without code changes.
-
-- **Local.** With no environment configured, every store, queue and consumer is
-  in-memory and jobs progress automatically. Running the program with
-  `npx tsx src/main.ts` is a complete local run, suitable for development and
-  testing.
-- **Anbaric Cloud.** `anbaric app deploy` packages the application (source only, no
-  `node_modules`) and runs it on the hosted platform. The platform installs the
-  application's own dependencies as it builds the image, so any npm package the
-  application imports works when deployed. The platform injects the configuration
-  that points the factories at platform-backed persistence, queueing, documents
-  and secrets; application code is unchanged. Authentication, job inspection and
-  updates are available through the CLI.
-- **Self-hosted.** The [`anbaric-hosting`](https://npmjs.com/package/anbaric-hosting)
-  package runs the platform — the API, dispatcher, build layer and app proxy —
-  on infrastructure you operate, backed by Postgres.
+Because the agent is just another actor, its work is audited like any other —
+the triage decision is attributed to `triager`.
 
-Applications should not set the `ANBARIC_*` factory variables themselves; the
-platform sets them when the application is deployed.
+### Wait for human input
+
+Sometimes a job cannot progress by itself — it needs a person to approve
+something, fill in a form, or make a decision. An **`Await`** is a step in a
+state's action list that *pauses* the job instead of running: when a job reaches
+it, the job is parked in the **`Awaiting input`** status and is not processed
+again until its properties are updated. Point people at wherever they provide
+that input with a **`resolveUrl`** — a function of the job, so you can build a
+per-job link with the job id (and anything else) in the query string.
 
-## Example
+Here an order waits for a human to approve it. The app serves a small approval
+UI at `/approve` (any framework — the page itself is omitted here); it reads the
+job id from the query string, collects the decision, and calls
+`updateJob(jobId, { approved: true }, actor)`. The `Await` sends the reviewer
+there, and a transition moves the job on once `approved` is set:
 
 ```ts
-import {Action, Code, PropertyDefinition, State, StateMachine, Transition} from "anbaric";
+import {Await, State, StateMachine, Transition} from "anbaric";
 
-const name = new PropertyDefinition("name");
-name.required = true;
+const approve = new Await("Approve the order", "HUMAN");
+approve.fields = ["approved"];                                  // the input we expect back
+approve.resolveUrl = (job) => `/approve?job=${job.id}`;         // where the human provides it
 
-const email = new PropertyDefinition("email");
-email.required = true;
+const fulfilment = new StateMachine("fulfilment", [
+    new State("review", [approve], [new Transition("approved", (job) => job.properties.get("approved") === true)]),
+    new State("approved"),
+]);
 
-const welcomeSent = new PropertyDefinition("welcomeSent");
-welcomeSent.validation = (value) => typeof value === "boolean";
+const order = await fulfilment.startJob(new Map([["total", 4200]]));
+// The job reaches `approve`, parks in "Awaiting input", and waits.
+// When the approval UI calls updateJob(order.id, { approved: true }, actor),
+// the job resumes, the transition fires, and it advances to `approved`.
+```
 
-const sendWelcome = new Action("Send welcome email", new Code("send-welcome"));
-sendWelcome.run = async (job) => {
-    // ... send the email to job.properties.get("email") ...
-    return new Map([["welcomeSent", true]]);
-};
+The pause is recorded in the audit trail, and the [awaiting-input
+widget](#the-admin-console-and-widgets) lists every parked job — with a
+clickable `resolveUrl` for those awaiting a human. Pass `"EXTERNAL_SYSTEM"`
+instead of `"HUMAN"` when the input will come from another service rather than a
+person.
 
-const onboarding = new StateMachine(
-    "customer-onboarding",
-    [
-        new State("new", [sendWelcome], [
-            new Transition("active", (job) => job.properties.get("welcomeSent") === true),
-        ]),
-        new State("active"),
-    ],
-    "new",
-    [name, email, welcomeSent],
-);
+### Use an RDBMS
+
+A full relational store is available for structured data. Locally it is SQLite; deployed, it is the tenant's PostgreSQL.
+
+```ts
+import {Human, SqlStoreFactory} from "anbaric";
+
+const actor = new Human("ada", "admin");
+const sql = SqlStoreFactory.instance();
 
-const job = await onboarding.startJob(new Map([["name", "Ada"], ["email", "ada@example.com"]]));
+await sql.execute(actor, "CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT)");
+await sql.execute(actor, "INSERT INTO notes (body) VALUES (?)", ["hello"]);
+const rows = await sql.query(actor, "SELECT id, body FROM notes");
 ```
 
-The job starts in `new`. When it is processed the `sendWelcome` action runs and
-sets `welcomeSent`, and the transition then advances the job to `active`. Run
-locally this happens automatically in memory; deployed, it happens on the
-platform.
+### Serve a web UI
 
-## Command-line interface
+An app can serve its own HTTP frontend. Listen on `process.env.PORT` and the
+platform's app proxy serves it at `<platform>/app/<name>/*`, stripping the
+`/app/<name>` prefix before the request reaches your app — combine it with the
+persistence and state-machine APIs above to put your data on a page. See
+[Web APIs](anbaric/docs/api/web.md) for the full proxy contract (forwarded
+headers, the absolute-URL caveat).
 
-The [`anbaric`](https://npmjs.com/package/anbaric-cli) CLI authenticates a
-terminal, deploys applications, and inspects and drives jobs on a platform. The
-principal commands are:
+```ts
+import {createServer} from "node:http";
+
+createServer((request, response) => {
+    response.writeHead(200, { "content-type": "text/html" });
+    response.end("<h1>My Anbaric app</h1>");
+}).listen(Number(process.env.PORT ?? 3000));
+```
+
+Serve trivial pages directly like this; build richer UIs with React and the
+Anbaric design system (`anbaric-design-system`). `sample-apps/crm` is a complete
+worked example — an HTTP server that renders its customers as HTML and exposes a
+JSON API backed by a state machine.
+
+## Auditing
+
+Every write to a job, document, secret or the SQL store is recorded against the
+actor that made it — which is why the store methods take an actor. An audit
+record captures the actor, the resource, the interaction (create, update, state
+change, delete, kill…) and a short description. Locally the records print to the
+console; deployed, the platform persists them and they are browsable in the
+admin console. Reads and lists can be audited too, but the platform masks them
+by default to keep the volume down.
+
+## Using the CLI
+
+`anbaric-cli` authorizes your terminal against a platform, deploys apps, and
+inspects and drives their jobs. After a one-time `anbaric login` (a browser
+flow), a typical loop is:
+
+```bash
+anbaric app deploy            # deploy the current project and wait until it is live
+anbaric jobs list             # list jobs and their states
+anbaric jobs watch <job-id>   # follow a job as it progresses
+anbaric jobs stats            # counts per state and the queue depth
+```
+
+Every interactive prompt also has a flag, so the CLI runs unattended in scripts
+and CI. The full command list is in the [CLI reference](#cli-reference) below.
+
+## The Admin console and widgets
+
+The platform serves an admin console at its root — a dashboard assembled from
+**plugins**. The built-in `anbaric-plugins/state-machines` plugin lists your
+state machines and their jobs. You add your own pages and widgets by writing a
+small plugin — a `pages`/`widgets` object — and naming it in `ANBARIC_PLUGINS`.
+Widgets are React components, optionally backed by a server-side data function,
+rendered with the platform's design system. See
+[`anbaric-plugins`](anbaric-plugins/README.md).
+
+## State machine deep-dive
+
+A **`StateMachine`** is constructed from a workflow id, its `State`s, the start
+state, and the property schema for its jobs. A **`State`** holds the **actions**
+that run while a job sits in it and the **transitions** to other states. An
+**`Action`** has a `run` function returning the property changes to apply — it
+never mutates the job directly. A **`Transition`** names a target state and a
+predicate; the first transition whose predicate holds moves the job. A **`Job`**
+is one instance moving through the machine, carrying its `properties`, its
+current `state`, and its history. A state can be marked terminal (or use the
+`Terminal` helper, which carries a `SUCCESS`/`FAILURE` outcome); a job that
+reaches one stops and is not processed again.
+
+Every action also declares the **actor** it runs as (`Code`, `Human` or
+`Agent` — pure identity objects), recorded for auditing and authorization.
+There are three ways to influence a job:
+
+1. **Update it directly**, declaring who is acting:
+   `machine.updateJob(jobId, new Map([["approved", true]]), new Human("chris", "manager"))`.
+2. **Execute an action directly** — the actor is embedded in the action:
+   `machine.executeAction(jobId, approveAction)`.
+3. **Subscribe an action to a state** — pass it in the `State` constructor or
+   call `state.subscribe(action)`, and it runs (predicate permitting)
+   whenever a job is processed in that state.
+
+Whichever way, property changes are schema-validated and audited, and each
+job carries its history: who started it, every from→to transition and the
+actor that made it.
+
+A state's action list may also contain an **`Await`** — a pause point rather
+than an actor acting. When a job reaches one it stops running actions and is
+parked: its `status` becomes `Awaiting input` (distinct from its `state`), and
+it holds a **`WaitForInput`** describing what is expected — the `fields`, a
+resolved `resolveUrl`, whether a `HUMAN` or `EXTERNAL_SYSTEM` is expected, and
+any metadata the `Await` computed for the job. A parked job is not re-processed
+until an `updateJob` arrives; on resume it skips its actions and only
+re-evaluates its transitions, so the input drives it on and the wait clears once
+it moves to another state. Actions placed after an `Await` in the same state do
+not run when the job resumes.
+
+Everything is pluggable through env-driven factories: locally (no env vars)
+you get in-memory persistence and queueing; deployed, the same factories talk
+to the platform automatically. The same applies to `JsonStoreFactory`
+(schema-validated documents), `SecretStoreFactory` (encrypted secrets) and
+`SqlStoreFactory` (a relational store) from `anbaric-data-store`.
+
+The SQL store is backed by SQLite locally (in-memory by default) and, once
+deployed, by the tenant's PostgreSQL in a schema named after your app — its own,
+isolated from every other app in the tenant. Write portable SQL where you can — the two
+differ in a few places, notably parameter placeholders (`?` for SQLite, `$1`
+for PostgreSQL); see the [`anbaric-data-store`](anbaric-data-store/README.md)
+docs for the full list.
+
+If your app serves HTTP, listen on `process.env.PORT` and users reach it at
+`<platform>/app/<name>`. All front-end must be React and use the Anbaric
+design system (`anbaric-design-system`) — see the living style guide by
+opening `anbaric-design-system/dist/index.html`.
+
+## Run it locally
+
+With no `ANBARIC_*` variables set, the factories return the in-memory
+persistence, queue and stores, so the program runs entirely in-process — no
+database or platform involved. Run the TypeScript entry file directly with tsx;
+`npx` fetches it on demand if your project doesn't already depend on it:
+
+```bash
+npx tsx src/main.ts
+```
+
+Jobs are held in memory and progress as the in-memory consumer delivers them;
+the state is gone when the process exits. This is the mode for development and
+tests.
+
+## Deploy it
+
+```bash
+npm install -g anbaric-cli    # once; provides the anbaric command
+anbaric login                 # pick a platform; a browser authorizes this terminal
+anbaric app configure         # writes .anbaric/app-config.json (name + internal port)
+anbaric app deploy            # packs, uploads, bakes an image, waits until live
+```
+
+`app deploy` returns once the app is actually up — its built-in admin port
+answers the platform's liveness ping. Watch it
+work with `anbaric apps`, `anbaric jobs list [state-machine]`, and
+`anbaric jobs watch <job-id>`. The `app` commands run from anywhere inside the
+project — they walk up to the nearest `package.json`.
+
+### What deployment does (and expects)
+
+The platform unpacks your upload onto a pre-canned base image, installs the
+app's dependencies, bakes a Docker image and runs it as a container. One thing
+it does **not** do:
+
+- **No build step.** `npm run build` is never run — your TypeScript source is
+  executed directly (via tsx). Ship source, not `dist/`.
+
+Dependencies, though, *are* installed: the image runs `npm install` for the
+app's declared dependencies (the `anbaric-*` packages and any others), so
+ordinary npm dependencies work. Only source is uploaded — `node_modules` is
+not.
+
+An app must have:
+
+- `package.json` with `main` pointing at the entry file (e.g. `src/main.ts`)
+  and `"type": "module"`.
+- `.anbaric/app-config.json` with a `name` (lowercase letters, numbers, `-`,
+  `_`) and an `internalPort` — `anbaric app configure` creates it, and
+  `app deploy` prompts if it's missing.
+
+A built-in admin process answers the platform's liveness check, so an app needs
+no HTTP server of its own to deploy. If it does serve HTTP (reached through the
+app proxy), it listens on `process.env.PORT`. The platform injects all wiring as
+env vars (`ANBARIC_*_TYPE=cloud`, the platform URL, the consumer and admin
+ports) — never hardcode these.
+
+## CLI reference
 
 | Command | Purpose |
 | --- | --- |
-| `anbaric login` / `anbaric logout` | authorize this terminal against a platform, or revoke it |
-| `anbaric apps` | list deployed applications |
-| `anbaric app configure` | set an application's name and internal port |
-| `anbaric app deploy` | deploy an application and wait until it is live |
-| `anbaric app update` | deploy over a running application without prompting |
-| `anbaric app status <name>` | show an application's deploy state and whether it is up |
-| `anbaric app tail <name>` | stream an application's runtime logs |
-| `anbaric app tear-down <name>` | stop and remove a deployed application |
+| `anbaric login` | choose a platform and authorize this terminal (browser flow; keypair saved to `~/.anbaric/`) |
+| `anbaric apps` | list deployed apps |
+| `anbaric app configure` | create or update `.anbaric/app-config.json` |
+| `anbaric app deploy` | deploy the app (prompts before replacing a running one) |
+| `anbaric app update` | deploy, replacing without prompting |
+| `anbaric app status <name>` | show an app's deploy state and whether it is up |
+| `anbaric app tail <name>` | stream an app's runtime logs |
+| `anbaric app tear-down <name>` | stop and remove a deployed app |
 | `anbaric state-machines` | list registered state machines |
 | `anbaric jobs create <sm-id> <start-state> [k=v ...]` | create a job and queue it for processing |
 | `anbaric jobs list [state-machine-id]` | list jobs |
 | `anbaric jobs stats` | job counts per state and the queue size |
-| `anbaric jobs watch <job-id>` | follow a job's state as it changes |
-| `anbaric jobs set-state <job-id> <state>` | move a job to a state and re-queue it |
-| `anbaric jobs update <job-id> <key=value ...>` | change job properties and re-queue |
+| `anbaric jobs watch <job-id>` | follow a job's state live |
+| `anbaric jobs set-state <job-id> <state>` | move a job and re-queue it |
+| `anbaric jobs update <job-id> <key=value ...>` | update job properties and re-queue |
 | `anbaric jobs kill <job-id>` | kill a job so it stops progressing |
 | `anbaric jobs kill-old <age>` | kill jobs not updated within `<age>` (e.g. `24h`, `7d`) |
 
-The `app configure`/`deploy`/`update` commands act on the application for the
-current project, located by walking up to the nearest `package.json`, so they
-run from anywhere inside it.
-
-Every command accepts flags (such as `--environment`, `--tenant`, `--name`,
-`--port`, `--yes`) that supply the answers a prompt would otherwise ask for, so
-the CLI can be run non-interactively in scripts and CI. See the
-[`anbaric-cli`](https://npmjs.com/package/anbaric-cli) documentation for the
-full command and flag reference.
+All commands accept `--platform-url` and `--tenant`; `login` sets the
+defaults. Manage your CLI keys in the browser at `<platform>/manage-keys`.
 
 ## Packages
 
-`anbaric` re-exports these packages; install them individually for a narrower
-dependency.
+`anbaric` is the umbrella install for writing an application — it re-exports the
+app-facing surface of the packages below. Install them individually for a
+narrower dependency.
 
 - [`anbaric-tsapi`](https://npmjs.com/package/anbaric-tsapi) — the interfaces
-  and value classes: `Job`, `State`, `Action`, `Transition`, `Actor`,
+  and value classes: `Job`, `State`, `Action`, `Await`, `Transition`, `Actor`,
   `JobPersistence`, `JsonStore`, `SecretStore`, `Auditor`.
 - [`anbaric-state-machine`](https://npmjs.com/package/anbaric-state-machine) —
   the `StateMachine`, actors, and in-memory implementations.
@@ -213,3 +385,24 @@ dependency.
 - [`anbaric-cli`](https://npmjs.com/package/anbaric-cli) — the platform CLI.
 - [`anbaric-hosting`](https://npmjs.com/package/anbaric-hosting) — run a
   platform yourself.
+
+Applications should not set the `ANBARIC_*` factory variables themselves; the
+platform sets them when the application is deployed, so the same code runs
+in-memory locally and platform-backed once deployed.
+
+## Run your own platform
+
+`npm install -g anbaric-hosting` provides the full hosting service - API,
+dispatcher, build layers and proxy - bootable with the `anbaric-hosting`
+command and configured entirely through `ANBARIC_*` environment variables.
+
+## Run a platform locally
+
+```bash
+cd gitops/local
+tofu init && tofu apply       # Docker Desktop: Postgres + the platform on :8787
+```
+
+See `gitops/README.md` for staging/prod and for enabling Auth0 login.
+`sample-apps/crm` is a complete worked example — deploy it by running
+`anbaric app deploy` from inside `sample-apps/crm`.

package/docs/README.md

@@ -0,0 +1,59 @@
+# Anbaric user guide
+
+Everything you need to build a real application on Anbaric — from your first
+state machine to a deployed app with a human-in-the-loop workflow, a database, a
+web UI and an audit trail.
+
+Anbaric models an application as one or more **state machines**: long-lived
+**jobs** move through named **states**, driven by **actions** and **transitions**,
+with their data validated against a schema and every change recorded. The same
+code runs in-memory on your laptop and platform-backed once deployed — you never
+write deployment details into your app.
+
+New here? Read [Core concepts](features/core-concepts.md), then work through the
+[Build your first app](patterns/first-app.md) walkthrough.
+
+## Features
+
+What the framework gives you, one capability at a time.
+
+- [Core concepts](features/core-concepts.md) — jobs, states, actions, transitions, actors
+- [State machines](features/state-machines.md) — defining and running a workflow
+- [Actions and actors](features/actions-and-actors.md) — who does the work, and how
+- [Awaiting input](features/awaiting-input.md) — pausing a job for a human or external system
+- [AI agents](features/ai-agents.md) — letting a model drive a state
+- [Documents and secrets](features/documents-and-secrets.md) — the JSON and secret stores
+- [The SQL store](features/sql-store.md) — a relational database for structured data
+- [Auditing](features/auditing.md) — the record of who changed what
+- [Serving a web UI](features/serving-a-web-ui.md) — putting your data on a page
+- [The admin console and widgets](features/admin-console-and-widgets.md) — dashboards and plugins
+- [Deploying](features/deploying.md) — from laptop to Anbaric Cloud
+
+## Patterns
+
+How to put the features together to build something real.
+
+- [Build your first app](patterns/first-app.md) — an end-to-end walkthrough
+- [Structuring an application](patterns/app-structure.md) — files, entry point, wiring
+- [Modelling a workflow](patterns/modelling-workflows.md) — turning a process into states
+- [Human-in-the-loop](patterns/human-in-the-loop.md) — approvals, forms and hand-offs
+- [Integrating external systems](patterns/integrating-external-systems.md) — waiting on callbacks and webhooks
+- [Authorization with actors and roles](patterns/authorization.md) — who is allowed to do what
+- [Testing your app](patterns/testing.md) — driving a machine in memory
+
+## API reference
+
+The surface you build against.
+
+- [TypeScript API](api/typescript.md) — the full app-facing library
+  - [State machines](api/state-machine.md) — `StateMachine`, `State`, `Action`, `Await`, `Transition`, `Job`, `PropertyDefinition`
+  - [Actors and agents](api/actors-and-agents.md) — `Code`, `Human`, `Agent`, AI actions
+  - [Stores](api/stores.md) — `JsonStore`, `SecretStore`, `SqlStore` and their factories
+  - [Environment and factories](api/environment.md) — the `ANBARIC_*` variables
+- [Web APIs](api/web.md) — serving HTTP, the app proxy, and the platform endpoints you call
+- [CLI reference](api/cli.md) — the `anbaric` command
+
+---
+
+Everything in this guide is app-author-facing: the public library, the CLI and
+the web surface. You never need to know how the platform is built to build on it.