babavoss 0.0.1 → 0.0.2

package/src/guide/spec-a-system.mdx

@@ -0,0 +1,93 @@
+export const prompt = { kind: "skill", name: "spec-a-system", description: "Read before testing a system: its spec in systems/NAME/spec.ts beside it (the system and what it reads), the adapters that play its outside, quiet effects, setup, params, scenarios and their script, saved scenarios, the one runner .baba/spec.test.ts under bun test, and the Maker that runs the same specs live." };
+
+# Spec a system
+
+There is one way to test a system: its spec, `systems/NAME/spec.ts`, beside its `index.ts`. The spec is the system and every system it reads, and what those read, seeded by a setup, with its outside played by adapters, and its scenarios: what must hold, as a script of steps and checks. The whole baba has one too, `.baba/spec.ts`, named `baba`. One program runs in two places: headless under `bun test`, which writes the verdicts, and live in the Maker, where a person watches every round and may act. `voss baba add-system NAME` writes the first spec beside the system.
+
+```ts
+// .baba/systems/digest/spec.ts
+import { spec, ok, fail, after, sequence } from "babavoss/spec";
+import digest from "./index.ts";
+import pagesSpec from "../pages/spec.ts";
+
+export default spec(digest, {
+  summary: "the day's pages, mailed once a day",                // the intent, as the person said it
+  also: [pagesSpec],                                           // digest reads pages: its adapters, setup and params come along
+  tick: 200,                                                    // rounds on their own every 200 ms, so the state moves while a person watches
+  now: 1_000,                                                   // the first time; `seed` the random seed, 1 by default
+  params: { to: "ada@example.test" },                           // knobs with defaults, for the setup and every scenario
+  setup: ({ tick }) => [tick({ after: 400 })],                  // an empty state to the initial one, after the setups of `also`
+  adapters: [
+    [digest.mail, sequence([fail("smtp: down"), after(100, ok({ id: "m1" }))])],   // the first job fails, the next lands 100 ms later
+  ],
+  scenarios: [
+    {
+      name: "a digest is mailed after one failure",
+      intent: "the first send fails, the retry lands, and the digest counts one sent",
+      script: ({ fire, ticks, check }, p) => [
+        check("the page from the setup is fetched", (t) => t.read("digest", {}).pages, 1),
+        fire("digest-send", { to: p.to as string }),
+        ticks(3, 1_000),
+        check("one sent", (t) => t.read("digest", {}).sent, 1),
+      ],
+    },
+  ],
+});
+```
+
+## The spec
+
+- `spec(system, { summary, also, adapters, setup, params, now, seed, tick, scenarios })`: a definition, not a run, the module's default export. Every field is optional; `spec(pond)` is a spec with no scenarios yet. The spec is named like the system's directory; its baba is the system and its reads, so `t.read`, `fire` and a handle in a check type-check against exactly those systems.
+- `spec(baba, { … })` in `.baba/spec.ts`: the whole baba's spec, named `baba`, for what only the systems together show.
+- `also` takes the specs of systems this one reads: their adapters, setups and params come along, so their outside is played here too. The spec's own adapters win for the same effect; its setup runs after theirs; its params lay over theirs.
+- `tick` is the baba's own by default; `null` leaves the rounds to the script.
+
+## The outside
+
+An adapter plays an effect, by the effect itself: `[pond.weather, after(300, ok({ temp: 20 }))]`.
+
+- Requests: `ok(value)`, `fail(error)`, `wait()`, `after(ms, a)`, `sequence([…])` (successive jobs in turn, the last for every job after), `match(where, a, otherwise)`, `model(initial, (state, args) => [state, answer])` for an outside with memory, `custom((args, ctx) => answer)`, `recorded(answer)`.
+- Sources: `listing(items)` (or a function of the args and the adapter's `ctx.state`) with optional `events` and `relist`, and `events([{ at, event }])` for a stream.
+- An adapter's state is the spec's: seeded with it, reset with it, shown in the Maker. Keep state in `model` or `ctx.state`, never in a closure.
+- An effect the spec plays no adapter for is **quiet**: its job is never started, so it waits, pending, like an outside that has not answered yet. A script answers it by hand: `done(effect, result, where?)`, `failed(effect, error, where?)`, `list(source, items)`, `watch(source, events)`; `where` picks the jobs by their args, or `{ entity }`; every job of the effect without it. A quiet effect is nothing faked: a quiet mirror keeps what was listed by hand. Waiting jobs are in `t.jobs` (`t.pending` stays empty in a spec). A verdict names the quiet effects a scenario's jobs asked of: what an adapter would have to play.
+
+## Scenarios
+
+A scenario is `{ name, intent, params?, script }`, run from the spec's setup. `script(words, params)` answers the lines, in the testbed's words:
+
+- `given(label, parts | (t) => …)`: a precondition the contract cannot express; parts by component name spawn one entity, `given("one fish", { fish: { x: 100, y: 100, hunger: 0 } })`.
+- `fire(action, args)`: an action, now; `answer(0, "entity")` is an earlier fire's answer in a later fire's args.
+- `tick({ after | at })`, `ticks(count, every)`: rounds on the spec's clock.
+- `done`, `failed`, `list`, `watch`: the outside answering, landing at the next tick.
+- `check(label, (t) => read, want?)`: deep-equal to `want`, or true. A failed check records and the run goes on; a step that throws stops it.
+
+Everything runs on the spec's own clock: an adapter's delay, a retry, a schedule and the baba's tick are due moments on it. Headless the clock jumps; live it follows real time at the speed chosen. The state lands the same either way; `w.random()` is seeded, so a run repeats.
+
+A scenario in a file of its own joins the spec beside it: `systems/NAME/scenarios/NAME.ts` (or `.baba/scenarios/` for the whole baba), `export default scenario({ name, intent, script })` from `babavoss/spec`. Its testbed is untyped; one written in the spec is typed by its spec. The Maker saves a take there (`spec-save`).
+
+## Running
+
+- `.baba/spec.test.ts` is the one runner, and `voss baba check` fails without it: `import { proveAll } from "babavoss/test"; await proveAll(import.meta.dir);`. It finds every `systems/*/spec.ts`, `.baba/spec.ts` and the saved scenarios; nothing is listed by hand.
+- Each scenario is one bun test named `SPEC: SCENARIO`. From `.baba/`: `bun test ./spec.test.ts` runs every spec, `bun test ./spec.test.ts -t "^pond: "` one spec, `-t "^pond: a fish goes for the food$"` one scenario.
+- Verdicts land in `.baba/.voss/spec/SPEC/verdicts.json`, written as the run goes: a scenario a finished run did not reach is unknown, never green.
+- `voss baba spec` lists every spec with its verdicts and whether code or spec changed since; `voss baba spec-run '{"spec":"pond"}'` reruns one headless (no spec: every one).
+- A system's other `*.test.ts` beside it (a pure helper), or an app's in `.baba/apps/` (its markup), is plain bun test; the system's behaviour is proved in its spec.
+
+## The Maker
+
+The Maker app shows the same specs live: its page imports them all, `import specs from "babavoss:specs"`, and the baba's apps, `<Maker specs={specs} apps={apps} />`. A spec open is drawn by one of those apps, one whose `systems` the spec holds, or by the desktop for a spec that has it; the person picks the app, and the pick is kept per spec (see `compose-an-interface`). A person opens a spec, plays, and your edits reach it live; the state carries across them, reseeding only when the fit dropped something the new code no longer declares. `voss baba spec-read '{"spec":"pond","query":"take"}'` then `voss baba follow N` answers what they did, noted and expected; `voss baba spec-step '{"spec":"pond","steps":[{"fire":"feed","args":{"x":1}},{"tick":300},{"read":"pond"}]}'` acts in that very spec and answers what changed. A run launched on the spec as seeded is canonical; after a hand moved it, a failed check is a warning. The truth is always the run from the setup.
+
+## The loop
+
+1. **Intent.** The person's sentence, as they said it: the spec's `summary`, later a scenario's `intent`.
+2. **Spec.** `systems/NAME/spec.ts`: the setup, adapters for what the sentence needs, `also` for the systems it reads; the rest stays quiet.
+3. **Look.** The person opens it in the Maker and plays; read their take.
+4. **Scenario.** The sentence as a script, in the spec or saved beside it; `bun test` or `spec-run`, and read the verdicts and the quiet effects.
+
+## Never
+
+- Reach the real outside from a spec: an adapter or a script answers every effect.
+- Keep an adapter's state in a closure: use `model` or `ctx.state`, so it resets with the spec.
+- Put a spec anywhere but beside its system, or list specs by hand: the convention finds them.
+- Write under `.baba/.voss/spec/`: the runner does.
+- Reset the person's state for them: say what changed and let them.

package/src/guide/systems-together.mdx

@@ -0,0 +1,72 @@
+export const prompt = { kind: "skill", name: "systems-together", description: "Make babavoss systems use each other without calling, messaging or modelling one another: reads, asks (accept), answers, chains on one entity, workflows. Read before making one system depend on another." };
+
+# Systems together
+
+Systems share one state and nothing else. There are no calls, no events, no messages between systems. A system names the systems it reads in `reads`; it reads their components there, and uses one by putting an **ask** on an entity; the provider answers it beside the ask. The provider never knows who asked.
+
+## The provider: say what you do for others
+
+```ts
+import { system, effect, accept, s, not } from "babavoss";
+
+export default system({
+  name: "images",
+  model: {
+    ask: accept({ prompt: s.string(), size: s.optional(s.string()) }),   // a reader may add it, once; only images replaces or removes it
+    image: { url: s.string() },                                          // the answer
+    failed: { error: s.string() },
+  },
+  effects: { generate: effect({ args: s.object({ prompt: s.string() }), result: s.object({ url: s.string() }), run: async ({ prompt }, ctx) => { /* ctx.http.fetch(...) */ } }) },
+}, (images, p) => [
+  // Asked and not yet answered: a job. The answer lands beside the ask, and the ask goes.
+  p.on(images.generate, {
+    for: (w) => w.query(images.ask, not(images.image, images.failed)).map((r) => [r.entity, { prompt: r.ask.prompt }] as const),
+    done: (w, e, r) => { w.add(e!, images.image, r); w.remove(e!, images.ask); },
+    failed: (w, e, error) => { w.add(e!, images.failed, { error }); w.remove(e!, images.ask); },
+  }),
+]);
+```
+
+A provider is a reconciler: open asks become jobs; answers land beside the ask; the ask is removed when answered. Policy is in `for`: yield one ask at a time to serialize, yield only `approved` ones to wait for a person, yield as many as a quota allows.
+
+## The asker: name the provider in `reads`, put the ask on your own entity, read the answer there
+
+```ts
+import images from "../images/index.ts";
+
+export default system({
+  name: "album",
+  model: { frame: { prompt: s.string() }, captioned: { url: s.string() } },
+  reads: [images],                                       // without this, images' handles do not type-check in album's pieces
+}, (album, p) => [
+  p.step("want", (w) => { for (const r of w.query(added(album.frame))) w.add(r.entity, images.ask, { prompt: r.frame.prompt }); }),
+  p.step("got",  (w) => { for (const r of w.query(album.frame, added(images.image))) w.add(r.entity, album.captioned, { url: r.image.url }); }),
+]);
+```
+
+- The entity is the correlation: no ids, no callbacks. Put the ask on an entity you made, beside your own component.
+- You cannot change or remove an ask once added. To withdraw it, despawn your entity: you made it, so you may, whatever it carries, and every job hanging off it is cancelled.
+- `reads` is your only dependency: you reach the provider's handles on the imported system, `images.ask`, and the state your pieces get reads its components and adds its asks, nothing more of it; a handle of a system you did not name does not type-check. The provider never reads you: two systems never read each other. When the provider needs something of you, the backward need is an ask: it declares an `accept` carrying what it needs, and you add it.
+- Order: systems run in the order the baba lists them in `baba({ systems })`. A later system sees an earlier system's writes this round; an earlier one sees them next round. Design for a one-round lag; never for same-round.
+
+## Chains and workflows
+
+A pipeline of systems is components arriving on one entity in order. There is no workflow engine: the entity is the workflow, and `state N` shows every step as what it carries.
+
+```ts
+// the release system, reads: [tests, build, deploy]: three steps, one entity per release
+}, (releases, p) => [
+  p.step("test",   (w) => { for (const r of w.query(added(releases.release))) w.add(r.entity, tests.suite, { name: "all" }); }),
+  p.step("pack",   (w) => { for (const r of w.query(releases.release, added(tests.outcome))) if (r.outcome.failed === 0) w.add(r.entity, build.bundle, { entry: "src/index.ts" }); }),
+  p.step("launch", (w) => { for (const r of w.query(releases.release, added(build.artifact))) w.add(r.entity, deploy.ship, { path: r.artifact.path }); }),
+]);
+```
+
+Branching is a condition in a step, parallel steps are two asks in one round and a join is a query for both answers, cancellation is despawning the entity. A plan composed at runtime, by an agent, is the same shape as data: a `plan` component with steps, and a runner system that adds the next ask when the previous answer lands.
+
+## Do not
+
+- Do not model another system inside yours and sync it with effects: its data is already in the state, name it in `reads` and query it.
+- Do not write another system's components to ask for something: declare an `accept` in the provider's `model`, or put your own component on the shared entity and let the provider react to it, if the provider agreed to: it names you in its `reads`.
+- Do not fire an action from inside a round: an action is a transaction of the outside; inside, write the state the action would have written.
+- Do not mirror another system of the same baba. Mirror another baba: a source over its query through `ctx.http`.

package/src/guide/write-a-system.mdx

@@ -0,0 +1,183 @@
+export const prompt = { kind: "skill", name: "write-a-system", description: "Write or change a babavoss system: declare its model, effects and reads, and make its pieces in one expression (steps in the order they run, effect bindings, actions and queries with their contract beside the body). Read before touching any file under .baba/systems/." };
+
+# Write a system
+
+A system is a unit of logic over one shared state. It declares what it owns and supplies pure functions over the state. It keeps nothing of its own between rounds: everything it knows is in the state. A system directory holds `index.ts` (the system) and `spec.ts` (its spec: the system and what it reads, its outside played and its scenarios; see `spec-a-system`), and nothing to look at: a view of it is an app in `.baba/apps/` (see `compose-an-interface`). The spec's intent comes first. `voss baba add-system NAME` scaffolds the system and its spec.
+
+A system is one expression: its declaration, data, and the function that makes its pieces from it and answers the list of them.
+
+```ts
+import { system, accept, resource, s, not, added, changed, removed, select, type StateOf, type ReaderOf } from "babavoss";
+import tasks from "../tasks/index.ts";
+
+export default system({
+  name: "pond",
+  model: {                                                       // components, asks and resources, together
+    fish: { x: s.number(), y: s.number(), hunger: s.number() },   // per entity
+    target: { food: s.entity("food") },                           // a reference is an entity id
+    food: { x: s.number(), y: s.number(), at: s.integer() },
+    tagged: s.tag(),                                              // a component with no value
+    named: { name: s.key(s.string()) },                           // one key field: w.find(pond.named, "nemo")
+    meal: accept({ size: s.integer() }),                          // an ask: a system that reads pond may add it
+    fed: resource(s.integer(), 0),                                // once per baba, always present
+  },
+  effects: { /* the outside, as jobs: see reach-outside */ },
+  reads: [tasks],                                                 // the systems this one reads, or asks of
+}, (pond, p) => {
+  // Helpers and selects first, above the list: they close over the system's handles.
+  const hungry = select(pond.fish, not(pond.target)).where((r) => r.fish.hunger > 10);
+  return [
+    p.step("swim", (w) => { /* every round, in list order */ }),
+    p.on(pond.fetch, { /* where an effect runs, how its answers land: see reach-outside */ }),
+    p.action("feed", { /* the contract, then run: (w, args) => … */ }),
+    p.query("pond", { /* the contract, then read: (w, args) => … */ }),
+  ];
+});
+```
+
+The first parameter is the system itself, named like it: a handle is always `system.handle`, `pond.fish`, everywhere, inside its pieces and out, in apps, specs and tests. A read system's handles come from the imported system, `tasks.task`, and type-check in a piece only because it is in `reads`. No `$`, no destructuring needed; a local `const { fish } = pond;` inside a long step is allowed, sparingly. `p` makes the pieces; everything the system does is a piece made with `p` and returned in the one list:
+
+- A piece made and not listed throws at load, and so does one listed twice, two steps of one name, two actions or two queries of one name, or another system's piece.
+- A piece made only when a condition holds: `flag && p.step("trace", …)`; `false`, `null` and `undefined` in the list are skipped.
+- `export default system(...)` when the module exports nothing else; `const pond = system(...)` and `export default pond` when it also exports helpers or constants that need the system.
+- A system object holds its handles by name and nothing else: no prototype, and it never stringifies. Never `String(pond)` or `` `${pond}` ``; its name is `nameOf(pond)`. The one name not allowed as a handle is `entity`.
+
+## Objects first
+
+Before steps and before any app, decide what the state is made of. An **object** is a component with a key, `s.key(…)`, plus whatever rides on the same entity: the issue is `issue` keyed by number with `thread` beside it; the worktree is `worktree` keyed by path with `work` and `outcome` beside it. A component spawned on its own entity, a window, a run, an opening, is an object known by its entity. Design in this order, OOUX's: the objects, then their relationships, entity fields `s.entity("x")` and what rides together, then their calls to action, the actions that take the object, then their attributes, the fields. The Maker reads all four off the manifest and shows every object with its instances under its **model** lens, so a system is designed and watched before it has an app. A system written for agents alone never needs one.
+
+## Rules the state enforces
+
+- The state a piece gets accepts only declared handles. It writes what the system owns, and asks of what it reads; it reads what it owns and what it reads; it runs its own effects. Anything else does not type-check, a handle imported directly included. A query reads only.
+- To read another system, name it in `reads`: `reads: [tasks]`, then `w.query(tasks.task)` in a piece. You import the system for its handles, never for its functions.
+- Reads go one way: two systems never read each other. When the one read also needs something back, the backward need is an ask: the reader adds the other's `accept` on an entity it made (see `systems-together`).
+- A value is immutable data. `w.add(e, pond.fish, value)` replaces the whole value; `w.update(e, pond.fish, (f) => ({ ...f, x: 1 }))` makes the new one from the old. Never mutate what a query gave you.
+- A component kept by a source (`mirror`) is written only by the outside, never by your steps. An ask (`accept`) is added by anyone who reads its system, once, and answered by its owner. See `systems-together`.
+- You despawn an entity you made, whatever it carries; any other only if it carries nothing but your components.
+- Names are flat across the baba: two systems cannot both declare `file`. Pick words specific to the system.
+
+## The round
+
+The runtime moves the state in rounds, each synchronous: the inbox first, where the actions fired and the raw writes run in order; then each system in declared order lands its sources' batches and its effects' answers, runs its steps, and is asked for its jobs; then the jobs start. What a system writes in a round is a function of the state before it and the inbox, nothing else. A round happens when there is a reason, an action, an answer, a batch, a schedule, the baba's `tick`; nothing runs while nothing is due. Values are checked where they enter from outside, action args, raw writes, job results, a state carried into new code; your own writes are trusted, and an audit at the round's end checks what changed.
+
+## Steps
+
+Pure, synchronous, run every round in the order they appear in the list. Order is the design: put `seek` above `swim` above `eat`, and say why in a comment above each.
+
+```ts
+}, (pond, p) => {
+  const hungry = select(pond.fish, not(pond.target)).where((r) => r.fish.hunger > 10);   // once, above the list
+  return [
+    // Hungry fish go for the first food. Seek before swim: a fish turns toward food before it moves.
+    p.step("seek", (w) => {
+      const f = w.query(pond.food)[0];
+      if (f) w.each(hungry, (e) => w.add(e, pond.target, { food: f.entity }));
+    }),
+    // Every round, for everything: time passes for all.
+    p.step("swim", (w) => {
+      const dt = w.elapsed / 1000;
+      w.each([pond.fish], (e, f) => w.add(e, pond.fish, { ...f, x: f.x + dt }));
+    }),
+    // Only for what changed since this system last ran: nothing on a quiet round.
+    p.step("eat", (w) => w.each([changed(pond.fish), pond.target], (e, f, t) => { /* ... */ })),
+    p.step("react", (w) => { for (const r of w.query(added(pond.food))) w.add(r.entity, pond.tagged); }),
+    p.step("clean", (w) => { for (const r of w.query(removed(pond.food))) { /* r.food is the last value it had */ } }),
+  ];
+});
+```
+
+- Each step is `p.step("name", (w) => …)`, with a comment above it saying what it does. Its name is how logs name it: "pond swim threw".
+- `w.query(a, not(b))` answers rows `{ entity, a }` in spawn order. `w.each([a, not(b)], (e, a) => …)` visits them without making rows: use it in steps.
+- `added(c)`, `changed(c)`, `removed(c)` measure from the moment this system's steps last ran, the same for every step of it. `changed` includes `added`. A removal includes a despawn.
+- `select(pond.fish, not(pond.target)).where(…)` made once, above the list, keeps its set live; pass it to `w.each` or `w.query`.
+- `w.now` is the round's time (ms since the epoch), `w.elapsed` the time since the last round, `w.round` the round. Do not keep a clock resource.
+- `w.count(c)`, `w.has(e, c)`, `w.get(e, c)`, `w.get(resource)`, `w.set(resource, v)`, `w.update(resource, fn)`, `w.find(c, key)`, `w.spawn(c, v)`, `w.remove(e, c)`, `w.despawn(e)`.
+- Each step is guarded on its own: a throw is logged, the next step runs, the state is not undone. Steps throw only for bugs.
+- `w.random()` is the baba's own seeded generator: use it, never `Math.random`, so a round can be reproduced and a scenario repeats.
+
+## Helpers
+
+A function shared by pieces takes the state as the system sees it: `StateOf<typeof pond>` when steps, bindings or actions share it, `ReaderOf<typeof pond>` when queries share it too. Write it above the list, where `pond` is in scope.
+
+```ts
+}, (pond, p) => {
+  const spawnFish = (w: StateOf<typeof pond>, x: number) => w.spawn(pond.fish, { x, y: 0, hunger: 0 });
+  const feedOne = (w: StateOf<typeof pond>) => w.update(pond.fed, (n) => n + 1);
+  const hungriest = (w: ReaderOf<typeof pond>) => w.query(pond.fish).sort((a, b) => b.fish.hunger - a.fish.hunger)[0];
+  return [ /* … */ ];
+});
+```
+
+A helper typed by `StateOf` refuses what the system may not touch, as a step would. `Act<typeof pond>` and `Read<typeof pond>` are its actions' and queries' args and results, as types; `HandlesOf<typeof pond>` its handles.
+
+## A big system: a declaration and parts
+
+When one file grows too long, split it so each helper sits beside the pieces that use it. `decl.ts` holds the declaration, checked at import; a part is pieces typed by it, in a file of its own; `index.ts` lists them all, the part's where its steps run.
+
+```ts
+// systems/trunk/decl.ts
+import { declare, s } from "babavoss";
+export default declare({ name: "trunk", model: { stage: { name: s.key(s.string()), up: s.boolean() } }, effects: { /* … */ }, reads: [] });
+
+// systems/trunk/stages.ts
+import { part, type StateOf } from "babavoss";
+import decl from "./decl.ts";
+const isUp = (w: StateOf<typeof decl>, name: string) => { /* … */ };   // a declaration types a helper too
+export const stages = part(decl, (trunk, p) => [
+  p.step("stage", (w) => { /* … */ }),
+  p.action("stage-start", { /* … */ }),
+]);
+
+// systems/trunk/index.ts
+import { system } from "babavoss";
+import decl from "./decl.ts";
+import { stages } from "./stages.ts";
+export default system(decl, (trunk, p) => [
+  ...stages(trunk, p),
+  p.query("trunk", { /* … */ }),
+]);
+```
+
+Split only where it reads better; a system of one file is the default. Keep the imports one way: `decl.ts` may import the helpers its effects run, so a part cannot live in that helpers' file, or the two import each other. Put a part in a file of its own, and helpers that pieces of two parts share in `index.ts` or a third file.
+
+## Actions and queries: the contract beside the body
+
+An action is `p.action("name", { … })`, a query `p.query("name", { … })`: the public name first, then the contract, summary, args, positional and result, then the body, `run` for an action, `read` for a query, typed by it: an arg the contract does not have, or an answer its `result` refuses, is a type error. An action with no args omits `args` and runs `(w) => …`; an action without a `result` answers nothing and need not return. An action runs inside the round as this system, all-or-nothing: a throw or a bad result undoes every write it made. A query reads between rounds and changes nothing. Both are flat and unique across the baba and reach the CLI, MCP, the GUI and the apps unchanged.
+
+```ts
+p.action("feed", {
+  summary: "drop food into the pond",                           // one line, imperative
+  args: { x: s.optional(s.number()), y: s.optional(s.number()) },
+  positional: ["x"],                                            // for people at the shell
+  result: s.object({ entity: s.entity("food") }),               // an entity made goes back as its id
+  run: (w, { x, y }) => ({ entity: w.spawn(pond.food, { x: x ?? 0, y: y ?? 0, at: w.now }) }),
+}),
+p.query("pond", {
+  summary: "every fish",
+  result: s.array(s.object({ entity: s.entity("fish"), x: s.number() })),
+  read: (w) => w.query(pond.fish).map((r) => ({ entity: r.entity, x: r.fish.x })),
+}),
+```
+
+- Return data, not conventions: the caller follows an entity with `state` or `follow`.
+- An arg `s.entity("food")` must carry `food`, and a caller may give the component's key in place of the id. A result's `s.entity()` is how an entity you made goes back.
+- A fire may carry an idempotency key (`--key K` at the shell, `key` by MCP): the baba remembers the answer for a day, so a retry answers the same without running again. Make actions safe to repeat anyway.
+- `w.transaction(fn)` gives any code what an action has: a throw undoes every write inside it.
+- Validation is at the boundary: args and results are checked; your writes inside are trusted, so write what the schema says.
+- Reserved names, not for actions or queries: start, stop, status, state, follow, run, raw, secret, help, mcp, check, install, add-system, serve, promptware, init, babas, service, gui.
+
+## The baba
+
+`.baba/index.ts` lists every system, in the order their steps run: `baba({ systems: [tasks, pond], apps, promptware, harness, tick })`. A system that reads another goes after it, so it sees this round's writes.
+
+## Schemas
+
+`s.string() number() integer() boolean() literal(v) enum([...]) tag() entity(component?) key(inner) secret() unknown() void() array(inner) nullable(inner) optional(inner) object({...})`. A bare object in `model` is `s.object`. `s.key` marks the one key field; `s.entity("food")` says which component the id carries; `s.secret()` is redacted from every snapshot that leaves the runtime.
+
+## Checklist before you are done
+
+1. Every component and resource the system writes is in its `model`; every other system it reads or asks of is in its `reads`, and none of those reads it back.
+2. Steps are ordered on purpose; the hot ones use `w.each`; the reactive ones use change terms.
+3. Every piece is made with this system's `p` and listed once; actions answer data; queries change nothing; names are flat and not reserved.
+4. The baba's promptware says in a line what the system is for (see `write-promptware`); its `spec.ts` beside it proves it, a scenario for each thing it must do (see `spec-a-system`); an app in `.baba/apps/` that names it in `systems` shows it, live and in the Maker (see `compose-an-interface`).
+5. `bun test` (the runner `.baba/spec.test.ts` proves every spec) and the type-check are green; the running baba reloads on save and `voss baba` shows the new contract.

package/src/guide/write-promptware.mdx

@@ -0,0 +1,90 @@
+export const prompt = { kind: "skill", name: "write-promptware",
+  description: "Write or change what a baba tells agents: its context, skills and hooks, as code under .baba/promptware/. Use before writing any promptware, in any baba, including skills like this one.",
+};
+
+# Write promptware
+
+A promptware file an agent can act on at first read: one trigger, steps in order, one example, claims it can check, rules it cannot break.
+
+## When
+
+- A baba gets a capability and agents must know how to use it.
+- An agent did something wrong that a sentence would have prevented.
+- The owner has a taste about how a thing is done, or a convention is repeated in chat.
+
+## Do
+
+1. Pick the kind. `context`: the baba's section of the context file, read by every session; what the project is, how it is worked on, its rules; one per baba, in `promptware/index.ts`. `skill`: a file read when its description fits; how to do one thing; one `.mdx` per skill beside it. `hook`: a harness moment handed to an action; what the harness may not do.
+2. Write the description as the trigger: `Use when …`, the situations, the files, the words an agent would be thinking. The description decides whether the skill is read; the body decides whether it works.
+3. Write Markdown directly in an MDX file. Export a `prompt` metadata object with `kind: "skill"`, name, description, and optional uses/eval; for context use `kind: "context"`. An `eval` is the owner's golden interpretation, run on demand from the Trials app to score readers of the text; it gates nothing. Changing a skill, leave its eval alone unless the owner asks. Import contract components and embed them as JSX. MDX expressions are JavaScript; keep typed helpers in imported .ts files. Existing TSX and `md` templates remain supported.
+4. Reference the contract, never restate it: `<Call of="feed" />` for a call with its example and summary, `<Calls of="pond" />` for a system's calls, `<Schema of>` for args, `<Usage of>` for the shell's spelling, `<See skills={[…]} />` for the skills to read next. A name that does not exist refuses to load.
+5. List the file in `promptware/index.ts`, which `baba({ systems, promptware, harness })` declares; `harness` says which harnesses get the files and Claude Code's permissions.
+6. Read the output: `CLAUDE.md` and `.claude/skills/NAME/SKILL.md` after the sync. Cut every sentence that does not change what an agent does.
+
+## Example
+
+```mdx
+import { Call, See } from "babavoss/prompt";
+
+export const prompt = {
+  kind: "skill",
+  name: "feed-the-pond",
+  description: "Use when asked to feed, stock or watch the fish.",
+  uses: ["feed", "pond"],
+};
+
+Feed the fish, then inspect the pond.
+
+## Do
+
+<Call of="feed" />
+
+Follow the returned entity, or read <Call of="pond" />.
+
+## Never
+
+Do not add or remove fish with raw writes.
+
+<See skills={["write-a-system"]} />
+```
+
+```ts
+// .baba/promptware/index.ts
+import { context, hook, md } from "babavoss/prompt";
+import feedThePond from "./feed-the-pond.mdx";
+
+export default [
+  context(md\`
+    The demo: an example baba. It shows what a baba is; it is not a product.
+
+    ## Rules
+
+    - Keep each system small and proved by its scenarios.
+  \`),
+  feedThePond,
+  hook({ on: "PreToolUse", match: "Bash", action: "guard-raw" }),
+];
+```
+
+## Check
+
+- The description starts with `Use when` and names a situation, not a topic.
+- Every step names the exact thing to type, open or call.
+- The example runs as written; nothing in it is elided.
+- No sentence restates the contract, the README or another skill: it references them.
+- The rendered file is shorter than the draft.
+
+## Never
+
+- Read the state in promptware: it is static, rendered from the manifest once per generation.
+- Explain why in a step; put reasons in the context if they are needed at all.
+- Write `simply`, `just`, `easily`, `should`, or a synonym for a term that has one name: system, app, spec, step, state, round, action, query, effect, source, mirror, context, skill, hook, baba, voss.
+- Edit `CLAUDE.md`, `AGENTS.md` or a `SKILL.md`: they are outputs.
+
+## Hooks
+
+A hook hands a harness moment to an action: `hook({ on, match?, action, strict? })` with `on` one of PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, SessionStart, PreCompact, Notification, and `match` a tool-name regex for the two tool events. The action takes `hookArgs(EVENT)` and answers `hookResult()`: `{ decision: "block", reason }` stops the tool call and the agent reads the reason; `{ context }` is told to the agent; `{}` lets it through. Voss compiles it into `.claude/settings.json` as `voss baba ACTION @- --hook EVENT`; a baba that is down lets through with a note, `strict: true` blocks. Prove a hook with a scenario: `fire` the action with an event, `check` the decision.
+
+## Voice
+
+Imperative, present, one fact per sentence, the name of the thing instead of a pronoun. Code first, then the sentence it needs. Numbers, paths and names exact. In MDX, use ordinary Markdown backticks and fenced code. Literal braces and angle brackets belong in code spans or must be escaped outside code.