babavoss 0.12.5 → 0.13.0

package/src/ecs/baba.ts

@@ -9,7 +9,7 @@ import type { Context } from "../kernel/context.ts";
 import { keyFields, keyField } from "./handles.ts";
 import { State, type Component, type Ask, type Resource, type Effect, type Model, type Entity, type Args, type Result, type MirrorEvent } from "./state.ts";
 import { checkPositional } from "../shell/positional.ts";
-import { render, type InterpretationSuite, type Prompt } from "../prompt/index.ts";
+import { render, type InterpretationSuite, type Prompt } from "../instructions/index.ts";
 import { routesError } from "../desktop/routes.ts";
 
 // ---- shapes --------------------------------------------------------------
@@ -105,7 +105,7 @@ export function query<const S extends Shape = {}, R = unknown, X = any>(def: { s
 /** A skill as the manifest carries it, rendered: what an agent reads when it opens it, and the calls it uses, by name. */
 export interface SkillDef { description: string; body: string; uses?: string[]; eval?: InterpretationSuite }
 /** What the baba tells agents, as the manifest carries it: its section of the context file, its skills, its hooks; the Markdown rendered. */
-export interface Promptware { context: string | null; contextEval?: InterpretationSuite; skills: Record<string, SkillDef>; hooks: HookDef[] }
+export interface Instructions { context: string | null; contextEval?: InterpretationSuite; skills: Record<string, SkillDef>; hooks: HookDef[] }
 
 /** Which harnesses get the baba's files, and Claude Code's permissions; `table` renders the contract as a table of calls; `auto` writes the files on every change. */
 export interface Harness { claude: { enabled: boolean; permissions: string[] }; codex: { enabled: boolean }; table: boolean; auto: boolean }
@@ -197,7 +197,7 @@ export const nameOf = (v: unknown): string => dataOf(v).name;
 const NAME = /^[a-z][a-zA-Z0-9-]*$/;
 const SYSTEM_NAME = /^[a-z][a-z0-9-]*$/;
 /** Words the shell keeps for itself: an action or a query may not take them. */
-export const RESERVED = new Set(["start", "stop", "status", "state", "follow", "run", "raw", "secret", "help", "mcp", "check", "install", "add-system", "serve", "promptware", "init", "babas", "service", "gui"]);
+export const RESERVED = new Set(["start", "stop", "status", "state", "follow", "run", "raw", "secret", "help", "mcp", "check", "install", "add-system", "serve", "agents", "init", "babas", "service", "gui"]);
 
 /** What a declaration makes: its handles by name, on an object with no prototype, and the model they form. */
 export interface Declared { readonly name: string; readonly refs: Readonly<Record<string, Component | Resource | Effect>>; readonly model: Model }
@@ -313,8 +313,8 @@ export interface Baba<Ss extends readonly System[] = readonly System[], K extend
   readonly $app: K;
   /** The routes of each app, as a type: what `compose<typeof baba>` asks a table of components for. */
   readonly $routes: R;
-  /** What the baba tells agents: `context(...)`, `skill(...)` and `hook(...)` from babavoss/prompt, in order. */
-  readonly promptware: readonly Prompt[];
+  /** What the baba tells agents: `context(...)`, `skill(...)` and `hook(...)` from babavoss/instructions, in order. */
+  readonly instructions: readonly Prompt[];
   /** Which harnesses get the files, and how. */
   readonly harness: Harness;
   /** Milliseconds between rounds the runtime causes on its own, for steps that need time to pass; null for a baba moved by actions and jobs. */
@@ -324,7 +324,8 @@ export interface Baba<Ss extends readonly System[] = readonly System[], K extend
   readonly queries: Record<string, QueryDef & { owner: string }>;
 }
 
-export function baba<const Ss extends readonly System[], const Sc extends readonly AppSpec[] = readonly []>(def: { systems: Ss; apps?: Sc; tick?: number; promptware?: readonly Prompt[]; harness?: HarnessInput }): Baba<Ss, Sc[number]["key"], RoutesOf<Sc>> {
+export function baba<const Ss extends readonly System[], const Sc extends readonly AppSpec[] = readonly []>(def: { systems: Ss; apps?: Sc; tick?: number; instructions?: readonly Prompt[]; harness?: HarnessInput }): Baba<Ss, Sc[number]["key"], RoutesOf<Sc>> {
+  if ("promptware" in def) throw new Error("baba({ promptware }) is gone: the agentic instructions are the .mdx files under .baba/agents/, which voss reads on its own; see the write-agentic-instructions skill");
   const harness = harnessOf(def.harness);
   if (def.tick !== undefined && !(Number.isInteger(def.tick) && def.tick > 0)) throw new Error("baba: tick is whole milliseconds, above zero");
   const model: Model = { components: [], resources: [], effects: [] };
@@ -367,7 +368,7 @@ export function baba<const Ss extends readonly System[], const Sc extends readon
   if (new Set(apps.map((v) => v.key)).size !== apps.length || apps.some((v) => !/^[a-z][a-z0-9-]*$/.test(v.key))) throw new Error("baba: app keys must be unique lowercase names");
   for (const v of apps) for (const n of v.systems ?? []) if (!systemNames.has(n)) throw new Error(`app ${v.key} shows ${n}, which is not one of the baba's systems`);
   for (const v of apps) { const e = v.routes && routesError(v.routes); if (e) throw new Error(`app ${v.key}: ${e}`); }
-  return Object.freeze({ kind: "baba", systems: def.systems, apps: apps.map((v) => ({ ...v, ...(v.systems ? { systems: [...v.systems] } : {}), ...(v.routes ? { routes: [...v.routes] } : {}) })), $app: undefined as never, $routes: undefined as never, tick: def.tick ?? null, promptware: [...(def.promptware ?? [])], harness, model, actions, queries });
+  return Object.freeze({ kind: "baba", systems: def.systems, apps: apps.map((v) => ({ ...v, ...(v.systems ? { systems: [...v.systems] } : {}), ...(v.routes ? { routes: [...v.routes] } : {}) })), $app: undefined as never, $routes: undefined as never, tick: def.tick ?? null, instructions: [...(def.instructions ?? [])], harness, model, actions, queries });
 }
 
 export function isBaba(v: unknown): v is Baba {
@@ -387,7 +388,7 @@ export function ofSystem(c: System): Baba { return baba({ systems: closureOf([c]
 export interface Manifest {
   systems: { name: string }[];
   /** What the baba tells agents, rendered: its context, its skills, its hooks; voss's own skills after the baba's. */
-  promptware: Promptware;
+  instructions: Instructions;
   harness: Harness;
   components: Record<string, { owner: string; schema: Json; accept?: true }>;
   resources: Record<string, { owner: string; schema: Json }>;
@@ -403,29 +404,38 @@ export interface Manifest {
 export interface Call { owner: string; summary: string; args: Json; positional?: string[]; result: Json }
 
 export function manifestOf(v: Baba, program = "voss baba"): Manifest {
-  const m: Manifest = { systems: v.systems.map((c) => ({ name: nameOf(c) })), promptware: { context: null, skills: {}, hooks: [] }, harness: v.harness, components: {}, resources: {}, effects: {}, actions: {}, queries: {}, tick: v.tick, apps: v.apps.map((x) => ({ ...x })) };
+  const m: Manifest = { systems: v.systems.map((c) => ({ name: nameOf(c) })), instructions: { context: null, skills: {}, hooks: [] }, harness: v.harness, components: {}, resources: {}, effects: {}, actions: {}, queries: {}, tick: v.tick, apps: v.apps.map((x) => ({ ...x })) };
   for (const c of v.model.components) m.components[c.name] = { owner: c.owner, schema: c.schema.json, ...(c.accept ? { accept: true as const } : {}) };
   for (const r of v.model.resources) m.resources[r.name] = { owner: r.owner, schema: r.schema.json };
   for (const e of v.model.effects) m.effects[e.name] = { owner: e.owner, summary: e.summary, args: e.args.json, result: e.result.json, retry: e.retry, every: e.every, repeat: e.repeat, shape: e.shape, ...(e.mirror ? { mirror: e.mirror } : {}), ...(e.event ? { event: e.event.json } : {}) };
   const call = (d: (ActionDef | QueryDef) & { owner: string }): Call => ({ owner: d.owner, summary: d.summary, args: d.args.json, ...(d.positional ? { positional: d.positional } : {}), result: d.result.json });
   for (const [n, a] of Object.entries(v.actions)) m.actions[n] = call(a);
   for (const [n, q] of Object.entries(v.queries)) m.queries[n] = call(q);
-  // The promptware renders once the contract is in the manifest, since it may refer to it.
+  // The agentic instructions renders once the contract is in the manifest, since it may refer to it.
   const refs: string[] = [];
-  m.promptware = renderPromptware(v.promptware, { manifest: m, program, refs });
-  for (const r of refs) if (!(r in m.promptware.skills)) throw new Error(`a skill says "see ${r}", which is not a skill of the baba`);
-  for (const [n, sk] of Object.entries(m.promptware.skills)) for (const u of sk.uses ?? []) if (!(u in m.actions) && !(u in m.queries)) throw new Error(`skill ${n} uses ${u}, which is not an action or query of the baba`);
-  for (const h of m.promptware.hooks) if (!(h.action in m.actions)) throw new Error(`hook on ${h.on} calls ${h.action}, which is not an action of the baba`);
+  m.instructions = renderInstructions(v.instructions, { manifest: m, program, refs });
+  for (const r of refs) if (!(r in m.instructions.skills)) throw new Error(`a skill says "see ${r}", which is not a skill of the baba`);
+  for (const [n, sk] of Object.entries(m.instructions.skills)) for (const u of sk.uses ?? []) if (!(u in m.actions) && !(u in m.queries)) throw new Error(`skill ${n} uses ${u}, which is not an action or query of the baba`);
+  for (const h of m.instructions.hooks) if (!(h.action in m.actions)) throw new Error(`hook on ${h.on} calls ${h.action}, which is not an action of the baba`);
   return m;
 }
 
-/** The baba's promptware as Markdown: the one context, each skill by name, the hooks. */
-export function renderPromptware(ps: readonly Prompt[], context: { manifest: Manifest; program: string; refs?: string[] }): Promptware {
+/** The baba with the documents voss found under .baba/agents/, after any it declares itself: what the builder hands the runtime. */
+export function instructed(v: Baba, docs: readonly Prompt[]): Baba {
+  if (!docs.length) return v;
+  return Object.freeze({ ...v, instructions: [...v.instructions, ...docs] }) as Baba;
+}
+
+/** The baba's agentic instructions as Markdown: the one context, each skill by name, the hooks. */
+export function renderInstructions(ps: readonly Prompt[], context: { manifest: Manifest; program: string; refs?: string[] }): Instructions {
   const contexts = ps.filter((p) => p.kind === "context");
   if (contexts.length > 1) throw new Error("a baba has one context(...); put every paragraph in it");
   const text = contexts[0] ? render(contexts[0].body, context) : "";
   const skills: Record<string, SkillDef> = {};
   for (const p of ps) if (p.kind === "skill") { if (p.name in skills) throw new Error(`two skills are named ${p.name}`); skills[p.name] = { description: p.description, body: render(p.body, context), uses: p.uses, ...(p.eval ? { eval: p.eval } : {}) }; }
-  const hooks = ps.filter((p) => p.kind === "hook").map((p) => ({ on: p.on, match: p.match, action: p.action, strict: p.strict }));
+  const hooks = [
+    ...(contexts[0]?.hooks ?? []).map((h) => ({ on: h.on, match: h.match ?? null, action: h.action, strict: h.strict === true })),
+    ...ps.filter((p) => p.kind === "hook").map((p) => ({ on: p.on, match: p.match, action: p.action, strict: p.strict })),
+  ];
   return { context: text || null, skills, hooks, ...(contexts[0]?.eval ? { contextEval: contexts[0].eval } : {}) };
 }

package/src/generated/build.ts

@@ -1,4 +1,4 @@
 // The commit and the moment a package was built from, stamped by the pack
 // of a release (tools/release/pack.ts) and restored after it. From a
 // checkout both are empty: the tree is the build.
-export const build = { sha: "", at: "" };
+export const build = {"sha":"ff74ab0","at":"2026-10-08T22:02:34.371Z"};

package/src/gui/gui.tsx

@@ -1,7 +1,7 @@
 // voss's GUI: voss's shell at every level. At the root, over page state: the
 // babas and the New baba wizard. At /NAME/ over the baba,
 // its apps and voss's own, the Maker, the state, the contract, the
-// promptware and the settings, as windows. One bundle, one React, served by the
+// agentic instructions and the settings, as windows. One bundle, one React, served by the
 // kernel's server child.
 import "./theme.css";
 import { Component, StrictMode, useEffect, useMemo, useState, type ComponentType, type ReactNode } from "react";
@@ -13,7 +13,7 @@ import type { AppSpec } from "../ecs/baba.ts";
 import type { Described } from "../baba/node.ts";
 import { Inspector } from "./inspector.tsx";
 import { Runner } from "./runner.tsx";
-import { Promptware } from "./promptware.tsx";
+import { Instructions } from "./instructions.tsx";
 import { Button } from "../web/ui.tsx";
 import { Root } from "./levels.tsx";
 import type { Voss } from "../server/messages.ts";
@@ -188,7 +188,7 @@ function ShellPage({ d }: { d: Described }) {
       maker: ({ path, navigate, setTitle }) => <Maker specs={[]} title={d.title} path={path} navigate={navigate} setTitle={setTitle} />,
       state: () => <section className="gui-app">{d.error && <p className="bv-error">The code did not load; the last generation serves: {d.error}</p>}<Inspector manifest={manifest} /></section>,
       contract: () => <section className="gui-app"><Runner manifest={manifest} /></section>,
-      promptware: () => <section className="gui-app"><Promptware manifest={manifest} /></section>,
+      instructions: () => <section className="gui-app"><Instructions manifest={manifest} /></section>,
       settings: Settings,
     };
     for (const sc of manifest.apps ?? []) {

package/src/gui/{promptware.tsx → instructions.tsx}

@@ -1,6 +1,6 @@
-// The promptware drawer: the baba's know-how for agents as it declares it,
+// The agentic instructions drawer: the baba's know-how for agents as it declares it,
 // the harness as the baba declares it, the plan of each output, and a sync.
-// Read from the state by the promptware system's names.
+// Read from the state by the agents system's names.
 import { useEffect, useState } from "react";
 import type { Manifest } from "../ecs/baba.ts";
 import { useBabaState } from "../web/state.tsx";
@@ -9,12 +9,12 @@ import { ErrorText } from "./runner.tsx";
 
 interface Plan { auto: boolean; lastSync: number | null; pending: number; error: string | null; outputs: { path: string; harness: string; status: string; action: string | null; reason: string }[] }
 
-export function Promptware({ manifest }: { manifest: Manifest }) {
+export function Instructions({ manifest }: { manifest: Manifest }) {
   const { fire, read, ready, round } = useBabaState();
   const [plan, setPlan] = useState<Plan | null>(null);
   const [error, setError] = useState<unknown>(null);
-  useEffect(() => { if (ready) read("promptware-plan").then((p) => setPlan(p as Plan), setError); }, [ready, round]);
-  if (!("pwStatus" in manifest.resources)) return <p className="bv-muted">This baba has no promptware system.</p>;
+  useEffect(() => { if (ready) read("agents-plan").then((p) => setPlan(p as Plan), setError); }, [ready, round]);
+  if (!("pwStatus" in manifest.resources)) return <p className="bv-muted">This baba has no agents system.</p>;
   if (!ready) return <p className="bv-muted">Reading the state…</p>;
   const act = (name: string, args: unknown) => { setError(null); return fire(name, args as never).catch((e: unknown) => { setError(e); throw e; }); };
   return (
@@ -24,7 +24,7 @@ export function Promptware({ manifest }: { manifest: Manifest }) {
       <section className="gui-section">
         <h2>Outputs</h2>
         <div className="bv-form-actions">
-          <Button variant="primary" onClick={() => void act("promptware-sync", {}).catch(() => {})}>Sync now</Button>
+          <Button variant="primary" onClick={() => void act("agents-sync", {}).catch(() => {})}>Sync now</Button>
           {plan && <span className="bv-muted">{plan.pending ? `${plan.pending} to write` : "up to date"} · {plan.auto ? "writes on every change" : "writes on sync"}{plan.lastSync ? ` · synced ${new Date(plan.lastSync).toLocaleTimeString()}` : ""}</span>}
         </div>
         {plan?.error && <p className="bv-error">{plan.error}</p>}
@@ -35,18 +35,18 @@ export function Promptware({ manifest }: { manifest: Manifest }) {
   );
 }
 
-/** What the baba tells agents, read-only here: it is code under .baba/promptware/. */
+/** What the baba tells agents, read-only here: it is code under .baba/agents/. */
 function Declared({ manifest }: { manifest: Manifest }) {
-  const pw = manifest.promptware;
+  const pw = manifest.instructions;
   const skills = Object.entries(pw.skills);
   return (
     <section className="gui-section">
-      <h2>Promptware</h2>
-      {!pw.context && skills.length === 0 && pw.hooks.length === 0 && <p className="bv-muted">Nothing declared yet: give the baba a `context(...)`, a `skill(...)` or a `hook(...)` under `promptware`.</p>}
+      <h2>Instructions</h2>
+      {!pw.context && skills.length === 0 && pw.hooks.length === 0 && <p className="bv-muted">Nothing declared yet: give the baba a `context(...)`, a `skill(...)` or a `hook(...)` under `.baba/agents/`.</p>}
       {pw.context && <p className="bv-muted">{pw.context.length} characters of context, {pw.hooks.length} hook{pw.hooks.length === 1 ? "" : "s"}.</p>}
       {pw.hooks.length > 0 && <Rows>{pw.hooks.map((h, i) => <Row key={i} hint={`${h.on}${h.match ? ` on ${h.match}` : ""}${h.strict ? " · strict" : ""}`}><code>{h.action}</code></Row>)}</Rows>}
       {skills.length > 0 && <Rows>{skills.map(([k, sk]) => <Row key={k} hint={sk.description}><code>{k}</code></Row>)}</Rows>}
-      <p className="bv-muted">The promptware is the baba's code: edit it under .baba/promptware/; the files below follow.</p>
+      <p className="bv-muted">The agentic instructions is the baba's code: edit it under .baba/agents/; the files below follow.</p>
     </section>
   );
 }
@@ -62,7 +62,7 @@ function Harness({ manifest }: { manifest: Manifest }) {
         <Row hint={h.codex.enabled ? "on" : "off"}><code>codex</code></Row>
         <Row hint={`${h.auto ? "writes on every change" : "writes on sync"}${h.table ? " · the contract as a table" : ""}`}><code>files</code></Row>
       </Rows>
-      <p className="bv-muted">Declared in .baba/index.ts: <code>{"baba({ systems, promptware, harness })"}</code>.</p>
+      <p className="bv-muted">The .mdx files under .baba/agents/, each <code>{'export const prompt = { kind: "context" | "skill", … }'}</code>; voss reads them on its own.</p>
     </section>
   );
 }

package/src/gui/theme.css

@@ -295,7 +295,7 @@ button.pk-crumb:hover { background: var(--accent); color: var(--foreground); }
 @keyframes gui-appear { from { opacity: 0 } to { opacity: 1 } }
 @media (prefers-reduced-motion: reduce) { .gui-fade { animation: none; } }
 
-/* ---- voss's apps, in the shell's windows: the state, the contract, the promptware, the settings, with a page's gutters; the Maker edge to edge ---- */
+/* ---- voss's apps, in the shell's windows: the state, the contract, the agentic instructions, the settings, with a page's gutters; the Maker edge to edge ---- */
 .gui-app { max-width: 1100px; padding: 16px 20px 32px; }
 .gui-app > h2 { margin: 16px 0 4px; font-size: 13px; }
 .gui-choices { display: flex; gap: 6px; margin-top: 8px; }

package/src/guide/add-a-desktop.mdx

@@ -2,7 +2,7 @@ export const prompt = { kind: "skill", name: "add-a-desktop", description: "Give
 
 # Add a desktop
 
-Every baba runs voss's shell: the desktop system, which voss adds to every baba as it adds `maker` and `promptware`, over the apps the baba declares in `baba({ apps })`. The interface gives each app its component; the page is voss's. Three nouns and one verb: a **app** is a kind the baba registers; a **window** is one instance of it in a session, at a path; the **session** shows one window, or nothing. The verb is `desktop-open`: it brings the window at that path to the front, else the app's current window, else makes one; asked for a `fresh` window, an app declared `many` gets another, any other app gives the one it has. The launcher, a link in an app, the page's address, the CLI and another system's ask all go through it.
+Every baba runs voss's shell: the desktop system, which voss adds to every baba as it adds `maker` and `agents`, over the apps the baba declares in `baba({ apps })`. The interface gives each app its component; the page is voss's. Three nouns and one verb: a **app** is a kind the baba registers; a **window** is one instance of it in a session, at a path; the **session** shows one window, or nothing. The verb is `desktop-open`: it brings the window at that path to the front, else the app's current window, else makes one; asked for a `fresh` window, an app declared `many` gets another, any other app gives the one it has. The launcher, a link in an app, the page's address, the CLI and another system's ask all go through it.
 
 The page is a bar over one app. At the bar's far left the mark, the two eyes, opens the launcher; then a pill per open window, its icon at the left and the one in front filled; pointing at a pill turns its icon into the × that closes it, and a middle click closes it too, as it closes a browser tab; closing the one in front brings the pill to its left forward, else the one to its right. The launcher is the page's, not the state's: it shows while its search has focus, and while nothing is in front, since there is nothing else to show. The mark or Cmd/Ctrl K gives the search focus; a click on the launcher's empty space keeps it; choosing a row, Escape or the mark again takes it, and the launcher goes. It covers the page and changes nothing beneath: the bar's row becomes the search, and below it one column of rows, a palette: the icon, beginning where the search begins, then the label; what is open first, then every app under its group. One dot under the mark says which row is chosen, by the keys or the pointer, and glides between them. Typing ranks both by the words, a word at the start of a name first, and drops the groups. An app's row opens a fresh window of it, or brings the one it has to the front; a window's row brings it to the front, and pointing at it turns its icon into its ×. A browser tab shows one window at a time: a pill on the bar brings an open one to the front, the mark then a row opens another. Below the apps, under Sessions, the tab's other sessions and New session. A page inside a baba is that baba only; the last row, Leave, and the `voss` link before the title on the bar go back to the picker, voss's root page, which has no state: it lists the babas voss knows, one inside another under its parent, and New baba, the wizard that makes a baba in a folder or remembers one already there.
 
@@ -30,7 +30,7 @@ import { Tasks } from "./apps/tasks.tsx";
 export default compose<typeof baba>({ apps: { tasks: Tasks } });
 ```
 
-An app missing from `compose`, or a component for an app the baba does not declare, is a type error. After the baba's apps come voss's own, under Voss: `maker` the specs run live, `state` the entities and resources, `contract` the actions and queries as forms, `promptware` the know-how, `settings` the theme. A baba never declares them; its interface may give one a component of its own to draw it otherwise, `compose<typeof baba>({ apps: { …, promptware: Mine } })`. A baba that declares no apps has one, `view`, which draws its interface whole. A baba whose interface fails to build or load still has its shell: its apps say why, voss's work. The old addresses, `/NAME/run`, `/inspect`, `/proofs`, open the app they became, unless the baba has an app by that name. The old form, `compose({ shell })`, still loads for one release, in the `view` app; a baba cannot declare apps and keep a desktop system of its own.
+An app missing from `compose`, or a component for an app the baba does not declare, is a type error. After the baba's apps come voss's own, under Voss: `maker` the specs run live, `state` the entities and resources, `contract` the actions and queries as forms, `agentic instructions` the know-how, `settings` the theme. A baba never declares them; its interface may give one a component of its own to draw it otherwise, `compose<typeof baba>({ apps: { …, agentic instructions: Mine } })`. A baba that declares no apps has one, `view`, which draws its interface whole. A baba whose interface fails to build or load still has its shell: its apps say why, voss's work. The old addresses, `/NAME/run`, `/inspect`, `/proofs`, open the app they became, unless the baba has an app by that name. The old form, `compose({ shell })`, still loads for one release, in the `view` app; a baba cannot declare apps and keep a desktop system of its own.
 
 An app's component receives `AppProps`: `{ session, window, path, route, params, active, memory, navigate, open, setTitle, remember }`. It never names an action: `navigate(path)` moves its own window, `open(app, path)` opens any app by the one rule, `setTitle(title)` names its window after what it shows, the pill's tooltip, `remember(key, value)` keeps a filter, a selection or a fold on its window, in the state, and `memory` reads it back. Windows stay mounted when hidden. A path begins with one `/`.
 

package/src/guide/index.ts

@@ -1,13 +1,13 @@
 // voss's own know-how for agents, given to every baba after its own: how to
 // write, prove and compose systems, how to draw the page as apps and give it
-// a desktop, and how to write promptware.
-import type { Prompt } from "../prompt/index.ts";
+// a desktop, and how to write agentic instructions.
+import type { Prompt } from "../instructions/index.ts";
 import writeASystem from "./write-a-system.mdx";
 import reachOutside from "./reach-outside.mdx";
 import systemsTogether from "./systems-together.mdx";
 import composeAnInterface from "./compose-an-interface.mdx";
 import addADesktop from "./add-a-desktop.mdx";
-import writePromptware from "./write-promptware.mdx";
+import writeInstructions from "./write-agentic-instructions.mdx";
 import specASystem from "./spec-a-system.mdx";
 
-export const guide: readonly Prompt[] = [writeASystem, reachOutside, systemsTogether, specASystem, composeAnInterface, addADesktop, writePromptware];
+export const guide: readonly Prompt[] = [writeASystem, reachOutside, systemsTogether, specASystem, composeAnInterface, addADesktop, writeInstructions];

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

@@ -164,11 +164,11 @@ p.query("pond", {
 - 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.
+- Reserved names, not for actions or queries: start, stop, status, state, follow, run, raw, secret, help, mcp, check, install, add-system, serve, agents, 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.
+`.baba/index.ts` lists every system, in the order their steps run: `baba({ systems: [tasks, pond], apps, harness, tick })`. A system that reads another goes after it, so it sees this round's writes.
 
 ## Schemas
 
@@ -179,5 +179,5 @@ p.query("pond", {
 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`).
+4. The baba's context, an `.mdx` under `.baba/agents/`, says in a line what the system is for (see `write-agentic-instructions`); 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 → write-agentic-instructions.mdx}

@@ -1,10 +1,10 @@
-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.",
+export const prompt = { kind: "skill", name: "write-agentic-instructions",
+  description: "Write or change what a baba tells agents: its context, skills and hooks, each an .mdx file under .baba/agents/. Use before writing any agentic instructions, in any baba, including skills like this one.",
 };
 
-# Write promptware
+# Write agentic instructions
 
-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.
+An instruction file an agent can act on at first read: one trigger, steps in order, one example, claims it can check, rules it cannot break. The agentic instructions of a baba are the `.mdx` files under `.baba/agents/`; voss reads every one of them, in name order, and there is no list to keep.
 
 ## When
 
@@ -14,17 +14,17 @@ A promptware file an agent can act on at first read: one trigger, steps in order
 
 ## 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.
+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, `export const prompt = { kind: "context" }`. `skill`: a file read when its description fits; how to do one thing; `export const prompt = { kind: "skill", name, description, uses }`, one `.mdx` per skill. A hook, a harness moment handed to an action, is `hooks: [{ on, match, action }]` on the context's `prompt`.
 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.
+3. Write Markdown in the `.mdx` file; `import { Call } from "babavoss/instructions"` for the tags below. Export the `prompt` metadata object with `kind: "skill"`, name, description, and optional uses/eval; for the context, `kind: "context"` with optional hooks/eval. 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.
+5. Save it under `.baba/agents/`: voss finds it there. `baba({ 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";
+import { Call, See } from "babavoss/instructions";
 
 export const prompt = {
   kind: "skill",
@@ -48,22 +48,15 @@ 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";
+```mdx
+{/* .baba/agents/context.mdx */}
+export const prompt = { kind: "context", hooks: [{ on: "PreToolUse", match: "Bash", action: "guard-raw" }] };
 
-export default [
-  context(md\`
-    The demo: an example baba. It shows what a baba is; it is not a product.
+The demo: an example baba. It shows what a baba is; it is not a product.
 
-    ## Rules
+## Rules
 
-    - Keep each system small and proved by its scenarios.
-  \`),
-  feedThePond,
-  hook({ on: "PreToolUse", match: "Bash", action: "guard-raw" }),
-];
+- Keep each system small and proved by its scenarios.
 ```
 
 ## Check
@@ -76,15 +69,15 @@ export default [
 
 ## Never
 
-- Read the state in promptware: it is static, rendered from the manifest once per generation.
+- Read the state in agentic instructions: 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`, a `SKILL.md` or `.claude/settings.local.json`: they are outputs. Git keeps none of them: voss writes its lines of the project's `.gitignore`, and a checkout makes its own with `voss baba promptware sync`.
+- Edit `CLAUDE.md`, `AGENTS.md`, a `SKILL.md` or `.claude/settings.local.json`: they are outputs. Git keeps none of them: voss writes its lines of the project's `.gitignore`, and a checkout makes its own with `voss baba agents sync`.
 - Commit an output. A hand-written `.claude/settings.json` beside the made `settings.local.json` is the place for what the repository itself tells Claude Code, a `SessionStart` hook that runs the sync, say.
 
 ## 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.local.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.
+A hook hands a harness moment to an action: `{ on, match?, action, strict? }` in the context's `hooks`, 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.local.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
 

package/src/{prompt → instructions}/evals.ts

@@ -1,4 +1,4 @@
-// The golden interpretation of a piece of promptware: situations a fresh
+// The golden interpretation of a piece of agentic instructions: situations a fresh
 // reader must decide from the text alone. Authored as givens, each with the
 // cases under it: when (the moment of decision) and then (the right move, a
 // few words). A situation the text never mentions, decided by what the text

package/src/{prompt → instructions}/index.ts

@@ -1,4 +1,4 @@
-// babavoss/prompt: promptware as code. What a baba tells agents, written in
+// babavoss/instructions: agentic instructions as code. What a baba tells agents, written in
 // MDX (or TSX) that renders to Markdown: `context(...)` for the baba's section of the
 // context file, `skill({ name, description }, ...)` for a skill file,
 // `hook(...)` for a moment of the harness; `md` for raw Markdown; `<Call
@@ -15,9 +15,9 @@ import { isElement, jsx, Fragment, type PromptNode, type PromptElement, type Pro
 
 export { Fragment, type PromptNode, type PromptElement, type PromptComponent, type JSX } from "./jsx-runtime.ts";
 
-/** What a baba declares under `promptware`. */
+/** What a baba declares under `.baba/agents/`. */
 export type Prompt =
-  | { kind: "context"; body: PromptNode; eval?: InterpretationSuite }
+  | { kind: "context"; body: PromptNode; eval?: InterpretationSuite; hooks?: HookDef[] }
   | { kind: "skill"; name: string; description: string; uses: string[]; body: PromptNode; eval?: InterpretationSuite }
   | { kind: "hook"; on: HookEvent; match: string | null; action: string; strict: boolean };
 
@@ -33,7 +33,8 @@ export type HookEvent = (typeof HOOK_EVENTS)[number];
  * PostToolUse to tool names, a regex. With `strict`, a baba that does not
  * answer blocks; otherwise it lets through.
  */
-export function hook(def: { on: HookEvent; match?: string; action: string; strict?: boolean }): Prompt {
+export interface HookDef { on: HookEvent; match?: string; action: string; strict?: boolean }
+export function hook(def: HookDef): Prompt {
   if (!HOOK_EVENTS.includes(def.on)) throw new Error(`hook: on is one of ${HOOK_EVENTS.join(", ")}, not ${JSON.stringify(def.on)}`);
   if (def.match !== undefined && def.on !== "PreToolUse" && def.on !== "PostToolUse") throw new Error(`hook on ${def.on}: match is for PreToolUse and PostToolUse`);
   return { kind: "hook", on: def.on, match: def.match ?? null, action: def.action, strict: def.strict === true };
@@ -72,7 +73,7 @@ export const hookResult = (): Schema<HookAnswer> => s.object({ decision: s.optio
 const WORD = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 
 /** The baba's section of the context file, CLAUDE.md and AGENTS.md: what the project is and how it is worked on, in any Markdown; one per baba. Voss wraps it with the doors and the skills. */
-export const context = (body: PromptNode, options?: { eval?: InterpretationSuite }): Prompt => ({ kind: "context", body, ...(options?.eval ? { eval: options.eval } : {}) });
+export const context = (body: PromptNode, options?: { eval?: InterpretationSuite; hooks?: HookDef[] }): Prompt => ({ kind: "context", body, ...(options?.eval ? { eval: options.eval } : {}), ...(options?.hooks?.length ? { hooks: options.hooks.map((h) => { hook(h); return h; }) } : {}) });
 
 /** A skill: a file an agent opens when the description fits what it is doing. `uses` names the calls it is about, checked against the contract. The body is any Markdown node. */
 export function skill(head: { name: string; description: string; uses?: string[]; eval?: InterpretationSuite }, body: PromptNode): Prompt {
@@ -82,11 +83,11 @@ export function skill(head: { name: string; description: string; uses?: string[]
 }
 
 /** MDX's metadata and lazy document component become the same prompt as TSX. */
-export function mdxDocument(meta: { kind: "context"; eval?: InterpretationSuite } | { kind: "skill"; name: string; description: string; uses?: string[]; eval?: InterpretationSuite }, Content: PromptComponent): Prompt {
+export function mdxDocument(meta: { kind: "context"; eval?: InterpretationSuite; hooks?: HookDef[] } | { kind: "skill"; name: string; description: string; uses?: string[]; eval?: InterpretationSuite }, Content: PromptComponent): Prompt {
   const body = jsx(Content, {});
   if (meta?.kind === "context") return context(body, meta);
   if (meta?.kind === "skill") return skill(meta, body);
-  throw new Error('MDX promptware needs export const prompt = { kind: "context" | "skill", ... }');
+  throw new Error('an MDX instruction file needs export const prompt = { kind: "context" | "skill", ... }');
 }
 
 /** Raw Markdown, verbatim, with the common indentation removed: for prose longer than a line. */
@@ -172,7 +173,7 @@ function block(node: PromptNode): string {
     case "table": return table(kids) + "\n";
     case "strong": case "em": case "del": case "img": case "input": case "code": case "b": case "i": case "a": case "br": return inline(node) + "\n\n";
     case "tr": case "th": case "td": return inline(kids);
-    default: throw new Error(`promptware: no such tag <${String(type)}>`);
+    default: throw new Error(`instructions: no such tag <${String(type)}>`);
   }
 }
 

package/src/{prompt → instructions}/jsx-runtime.ts

@@ -1,5 +1,5 @@
-// The JSX runtime for promptware: elements that render to Markdown, not to
-// the DOM. A file says `/** @jsxImportSource babavoss/prompt */` and writes
+// The JSX runtime for agentic instructions: elements that render to Markdown, not to
+// the DOM. A file says `/** @jsxImportSource babavoss/instructions */` and writes
 // `<p>`, `<ul>`, `<pre lang="ts">`, `<Call of="feed" />`; `render` turns the
 // tree into text. Pure, no React.
 export interface PromptElement { readonly $prompt: true; type: string | PromptComponent; props: Record<string, unknown> }
@@ -18,7 +18,7 @@ export const isElement = (v: unknown): v is PromptElement => typeof v === "objec
 
 type Children = { children?: PromptNode };
 
-// What TypeScript admits in a promptware file: the Markdown tags, each with the props it renders.
+// What TypeScript admits in an instruction file: the Markdown tags, each with the props it renders.
 export namespace JSX {
   export type Element = PromptElement;
   /** What a tag may be: a Markdown tag, or a component answering any node, text and lists included, not only an element. */

package/src/mcp/main.ts

@@ -17,7 +17,7 @@ import { toolsOf, callName, promptsOf, promptText, type Tools } from "./tools.ts
 import { BUDGET, DoorError, budget, errorOf, index, schemaOf, followEntity, watchQuery, stateOf, untilOf, byKey, isTruncated, type Outcome } from "../door/core.ts";
 
 const VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
-const empty: Manifest = { systems: [], promptware: { context: null, skills: {}, hooks: [] }, harness: defaultHarness, components: {}, resources: {}, effects: {}, actions: {}, queries: {}, tick: null };
+const empty: Manifest = { systems: [], instructions: { context: null, skills: {}, hooks: [] }, harness: defaultHarness, components: {}, resources: {}, effects: {}, actions: {}, queries: {}, tick: null };
 
 const log = (l: string) => process.stderr.write(`voss mcp: ${l}\n`);
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
@@ -159,13 +159,13 @@ export async function runMcp(project: Project, rootDir: string): Promise<number>
       }
       case "resources/list": return {
         resources: [
-          ...(m.promptware.context ? [{ uri: "baba://context", name: "context", description: "what the baba tells agents", mimeType: "text/markdown" }] : []),
+          ...(m.instructions.context ? [{ uri: "baba://context", name: "context", description: "what the baba tells agents", mimeType: "text/markdown" }] : []),
           ...[...outs.keys()].map((f) => ({ uri: `baba://out/${f}`, name: f, description: "an answer over the output budget", mimeType: "application/json" })),
         ],
       };
       case "resources/read": {
         const uri = String(p.uri ?? "");
-        const context = uri === "baba://context" ? m.promptware.context : null;
+        const context = uri === "baba://context" ? m.instructions.context : null;
         if (context) return { contents: [{ uri, mimeType: "text/markdown", text: context }] };
         const out = uri.startsWith("baba://out/") ? outs.get(basename(uri.slice(11))) : undefined;
         if (out) return { contents: [{ uri, mimeType: "application/json", text: await readFile(out, "utf8") }] };

package/src/mcp/tools.ts

@@ -16,12 +16,12 @@ export interface Target { kind: "action" | "query"; name: string; system: string
 
 export interface Tools { tools: Tool[]; targets: Map<string, Target>; generic: boolean }
 
-/** The promptware's threshold for describing the contract as `call`/`read`; the server itself is generic unless VOSS_MCP_TOOLS=1. */
+/** The agentic instructions's threshold for describing the contract as `call`/`read`; the server itself is generic unless VOSS_MCP_TOOLS=1. */
 
 /** How an agent learns the contract: said in every tool that takes a call's name. */
 const LEARN = "`manifest` lists every call with an example; `manifest` with a name gives its schemas.";
 
-/** `<system>_<name>`; a name that already starts with its system's, as voss's own do (`promptware-sync`), is not prefixed twice: `promptware_sync`. */
+/** `<system>_<name>`; a name that already starts with its system's, as voss's own do (`agents-sync`), is not prefixed twice: `agents_sync`. */
 export const toolName = (system: string, name: string) => name.startsWith(`${system}-`) ? `${system}_${name.slice(system.length + 1)}` : `${system}_${name}`;
 
 const isObj = (v: unknown): v is Obj => typeof v === "object" && v !== null && !Array.isArray(v);
@@ -107,12 +107,12 @@ export function callName(m: Manifest, n: string): { kind: "action" | "query"; na
 
 /** One prompt per skill, by its name. */
 export function promptsOf(m: Manifest): { name: string; description: string; skill: string }[] {
-  return Object.entries(m.promptware.skills).map(([k, sk]) => ({ name: k, description: sk.description, skill: k }));
+  return Object.entries(m.instructions.skills).map(([k, sk]) => ({ name: k, description: sk.description, skill: k }));
 }
 
 /** A skill's prompt text: its body, then the tools it uses. */
 export function promptText(m: Manifest, skill: string, generic: boolean): string | null {
-  const sk = m.promptware.skills[skill];
+  const sk = m.instructions.skills[skill];
   if (!sk) return null;
   const uses = (sk.uses ?? []).map((n) => {
     const c = m.actions[n] ?? m.queries[n];

package/src/runtime/harness.ts

@@ -6,7 +6,7 @@ import { manifestOf, type Baba } from "../ecs/baba.ts";
 import { Runtime, ContractError } from "../ecs/runtime.ts";
 import { StateError, type Snapshot } from "../ecs/state.ts";
 import { makeBridge, portOver } from "./bridge.ts";
-import { withPromptware } from "../promptware/system.ts";
+import { withInstructions } from "../agents/system.ts";
 
 /** How long a `state` read waits for the round past `since` before answering the state as it is. */
 export const STATE_WAIT_MS = 25_000;
@@ -23,7 +23,7 @@ export class Harness {
   /** Loads the baba over the snapshot given; answers `loaded`, or throws for `failed`. */
   load(own: Baba, project: { name: string; dir: string; baba: string }, env: Record<string, string>, snapshot: Snapshot | null, prepare = false): void {
     // Voss's own systems join every baba after its own.
-    const v = withPromptware(own);
+    const v = withInstructions(own);
     const manifest = manifestOf(v);
     const make = (snapshot: Snapshot | null, auto: boolean) => new Runtime(v, {
       auto,