babavoss 0.12.6 → 0.13.1

package/index.ts

@@ -1,5 +1,5 @@
 // babavoss: the framework. What a baba imports.
-export { baba, effect, source, accept, resource, shape, manifestOf, isBaba, isSystem, nameOf, SYSTEM } from "./src/ecs/baba.ts";
+export { baba, instructed, effect, source, accept, resource, shape, manifestOf, isBaba, isSystem, nameOf, SYSTEM } from "./src/ecs/baba.ts";
 export { system, declare, part } from "./src/ecs/system.ts";
 export type { Decl, Entry, Handles, HandlesOf, Building, Maker, Part, Piece, Maybe, StepPiece, OnPiece, ActionPiece, QueryPiece, BindingOf, Scope, Reader, StateOf, ReaderOf, Act, Read } from "./src/ecs/system.ts";
 export { not, added, changed, removed, select } from "./src/ecs/state.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babavoss",
-  "version": "0.12.6",
+  "version": "0.13.1",
   "license": "Apache-2.0",
   "repository": "github:alanremarc/babavoss",
   "homepage": "https://babavoss.org",
@@ -14,13 +14,13 @@
     "./web": "./src/web/index.tsx",
     "./test": "./src/test/index.ts",
     "./bench": "./src/bench/index.ts",
-    "./prompt": "./src/prompt/index.ts",
-    "./prompt/jsx-runtime": "./src/prompt/jsx-runtime.ts",
-    "./prompt/jsx-dev-runtime": "./src/prompt/jsx-dev-runtime.ts",
+    "./instructions": "./src/instructions/index.ts",
+    "./instructions/jsx-runtime": "./src/instructions/jsx-runtime.ts",
+    "./instructions/jsx-dev-runtime": "./src/instructions/jsx-dev-runtime.ts",
     "./desktop": "./src/desktop/index.ts",
     "./kit": "./src/kit/index.ts",
     "./spec": "./src/spec/index.ts",
-    "./prompt/register": "./src/build/mdx-register.ts"
+    "./instructions/register": "./src/build/mdx-register.ts"
   },
   "files": [
     "bin",

package/src/{promptware → agents}/compile.ts

@@ -1,15 +1,15 @@
-// Promptware to harness files, as text. Pure: the manifest, with the baba's
+// Instructions to harness files, as text. Pure: the manifest, with the baba's
 // context and skills rendered and its harness declaration, becomes what
 // each output path, relative to the project, should hold.
 //
 //   Claude Code   CLAUDE.md   .claude/skills/NAME/SKILL.md   .claude/settings.local.json
 //   Codex         AGENTS.md   .agents/skills/NAME/SKILL.md
 //
-// Promptware is know-how; the contract teaches itself at the doors, the
+// Instructions is know-how; the contract teaches itself at the doors, the
 // CLI's index and schemas and the MCP server's tools. The instruction file
 // teaches the doors, true whatever the contract becomes; the table of calls
 // is rendered only when the baba asks for it. The MCP registration is
-// not promptware's: it is the machine's. The permissions, in a file the
+// not agentic instructions's: it is the machine's. The permissions, in a file the
 // project shares with others, are a merge: voss owns only its entries.
 import type { Json } from "../kernel/schema.ts";
 import type { Manifest } from "../ecs/baba.ts";
@@ -18,7 +18,7 @@ import { exampleOf } from "../ecs/handles.ts";
 import { skillsOf, type SkillManifest } from "./define.ts";
 
 /** The systems voss gives every baba: their calls are not the project's contract. */
-export const VOSS = new Set(["promptware", "maker"]);
+export const VOSS = new Set(["agents", "maker"]);
 
 export type Harness = "claude" | "codex";
 export const harnesses: Harness[] = ["claude", "codex"];
@@ -31,8 +31,8 @@ const files: Record<Harness, { instructions: string; skills: string }> = {
 /** Which harness an output path belongs to. */
 export const harnessOf = (path: string): Harness => (path === "AGENTS.md" || path.startsWith(".agents/") || path.startsWith(".codex/") ? "codex" : "claude");
 
-/** Where the promptware lives, relative to the project. */
-export const SOURCE = ".baba/promptware";
+/** Where the agentic instructions lives, relative to the project. */
+export const SOURCE = ".baba/agents";
 
 // ---- merges ------------------------------------------------------------
 
@@ -55,11 +55,11 @@ export type Merge =
 export const CLAUDE_SETTINGS = ".claude/settings.local.json";
 
 /**
- * The outputs are made from the promptware: a checkout makes its own with `voss baba promptware sync` (a landing does),
+ * The outputs are made from the agentic instructions: a checkout makes its own with `voss baba agents sync` (a landing does),
  * and git keeps none of them. Voss's lines of the project's .gitignore say so.
  */
 export const ignoreLines = (): string[] => [
-  "# voss makes these from .baba/promptware: `voss baba promptware sync` writes them, git keeps none",
+  "# voss makes these from .baba/agents: `voss baba agents sync` writes them, git keeps none",
   ...harnesses.flatMap((h) => [`/${files[h].instructions}`, `/${files[h].skills}/`]),
   `/${CLAUDE_SETTINGS}`,
 ];
@@ -108,7 +108,7 @@ export function compile(input: CompileInput): Compiled {
       const perms = st.claude.permissions;
       if (perms.length) lists.push({ at: ["permissions", "allow"], values: [...new Set(perms)] });
       const byEvent = new Map<string, unknown[]>();
-      for (const hk of input.manifest.promptware.hooks) {
+      for (const hk of input.manifest.instructions.hooks) {
         const command = `${input.program} ${hk.action} @- --hook ${hk.on}${hk.strict ? " --strict=true" : ""}`;
         const entry = { ...(hk.match ? { matcher: hk.match } : {}), hooks: [{ type: "command", command }] };
         if (!byEvent.has(hk.on)) byEvent.set(hk.on, []);
@@ -131,32 +131,25 @@ const quoted = (v: unknown) => `'${JSON.stringify(v).replaceAll("'", `'\\''`)}'`
 /** The CLI line of a call with a literal example of its args. */
 const cliLine = (prog: string, name: string, args: Json) => `${prog} ${name} ${quoted(exampleOf(args))}`;
 
-/** The shell around the baba's context: the header, the context, what a baba is and how to reach it at its doors, an example, the two systems voss adds, the skills by name. */
+/**
+ * The instruction file: the title, then voss's own section, short, what a baba is, that the agent is its author and
+ * which skills say how, and how the baba is reached by MCP and at the shell, with one real example; then the baba's
+ * own context, as it wrote it.
+ */
 function instructionFile(input: CompileInput): string {
   const prog = input.program;
   const m = input.manifest;
+  const skills = skillsOf(m).map((sk) => sk.name);
   const lines = [
-    `<!-- Generated by ${prog} from the baba's promptware. Do not edit: a hand edit is held and never overwritten. Edit the promptware; it syncs. -->`,
+    `<!-- Generated by ${prog} from the baba's agentic instructions. Do not edit: a hand edit is held and never overwritten. Edit the agentic instructions under .baba/agents/; they sync. -->`,
     `# ${input.title ?? prog}`,
-  ];
-  const context = m.promptware.context?.trim();
-  if (context) lines.push("", context);
-  lines.push(
-    "", "## This baba", "",
-    "A baba is this project's own program: systems and apps over one state of entities and resources, moved by the actions its systems declare and read by their queries; the apps show it to people. Its code is under `.baba/`, and voss runs it.",
+    "", "## Baba Voss", "",
+    "This project has a baba: its own program, under `.baba/`, run by voss. A baba is systems over one state of entities and resources, and apps that show it to people. Each system declares the components it owns, the actions that move it and the queries that read it, and reaches outside only through effects; a spec beside it proves it. Voss serves the baba from a service on loopback, `http://localhost:47802/` by default; `voss service status` gives the configured URL.",
     "",
-    `The contract is live: \`${prog}\` answers the index, every action and query with its system, kind, summary and an example, and \`${prog} NAME --schema\` one call's args and result schemas. Never rely on a copied list: a system added or changed shows up there within seconds.`,
+    `You are this baba's author. Use it through its contract, and change it when it falls short: a capability it lacks is a system to write, a mistake an agent made is a sentence for its instructions. The skills say how, read each when its description fits: ${skills.join(", ")}.`,
     "",
-    `- Call one with JSON: \`${prog} NAME '{"arg": value}'\` (flags exist for people). Every answer is one line of JSON; an error is one line on stderr, \`{"error":{"code","message","retry"}}\`, and the exit code says whose: 2 your arguments, 1 it failed, 3 time ran out, 4 gone.`,
-    `- An entity in an answer is a number: \`${prog} state N\` reads it, \`${prog} follow N [--until COMPONENT]\` waits on it.`,
-    `- \`${prog} run\` sends several calls in one turn: lines of \`{"NAME": args}\`, \`"$0.entity"\` to reference an earlier answer.`,
-    `- \`${prog} state\` reads the state; \`${prog} raw …\` writes it, only when no action does it. \`--help\` after any word explains it.`,
-    `- \`--key K\` on an action makes a retry safe: the baba remembers the answer for a day and answers it again without running. A secret is never on the command line: \`--token @-\` reads it from stdin. An answer over 20 000 characters goes to \`.baba/.voss/out/\` and the line says where.`,
-    "",
-    "If your harness has this baba's MCP server (`voss baba mcp`), its `manifest`, `call`, `read`, `follow`, `watch` and `state` tools are the same six operations: prefer them.",
-    "",
-    "Voss serves this baba from a service on loopback, `http://localhost:47802/` by default. `voss baba start` opens it there, installing the service if need be; `voss service status` gives the configured URL and whether it runs. Never guess another port: read the status.",
-  );
+    `The contract is live; never rely on a copied list. By MCP, when your harness has this baba's server (\`voss baba mcp\`): \`manifest\`, \`call\`, \`read\`, \`follow\`, \`watch\` and \`state\`; prefer them. At the shell: \`${prog}\` lists every action and query with an example, \`${prog} NAME '{"arg": value}'\` calls one, \`${prog} NAME --schema\` gives its schemas, \`${prog} state N\` reads an entity an answer named and \`${prog} follow N [--until COMPONENT]\` waits on it, \`${prog} run\` sends several calls, \`${prog} state\` reads the state and \`${prog} raw …\` writes it, only when no action does. Every answer is one line of JSON; an error is one line on stderr, \`{"error":{"code","message","retry"}}\`, and the exit code says whose: 2 your arguments, 1 it failed, 3 time ran out, 4 gone. \`--key K\` on an action makes a retry safe; a secret is never on the command line, \`--token @-\` reads it from stdin; an answer over 20 000 characters goes to \`.baba/.voss/out/\` and the line says where.`,
+  ];
   const first = Object.entries(m.actions).find(([, d]) => !VOSS.has(d.owner));
   if (first) {
     const [name, d] = first;
@@ -172,9 +165,8 @@ function instructionFile(input: CompileInput): string {
       ...Object.entries(m.queries).filter(([, q]) => !VOSS.has(q.owner)).map(([n, q]) => `| \`${prog} ${[n, ...usage(q.args, q.positional)].join(" ")}\` | query | ${q.owner} | ${system(q.summary)} |`),
     );
   }
-  lines.push("", "Voss adds two systems to this baba. `promptware` compiles what the baba tells agents, its context, skills and hooks written as code under `.baba/promptware/`, into each harness's files: `CLAUDE.md`, `AGENTS.md`, the skills, Claude Code's permissions and hooks. Those are generated: edit the promptware, never the outputs. `maker` keeps the specs, each system's `systems/NAME/spec.ts` beside it and the whole baba's `.baba/spec.ts`, each a seeded state with its scenarios and the adapters that play its outside, proved under `bun test` by `.baba/spec.test.ts`; `spec` lists them with their verdicts, `spec-run` runs a state's scenarios headless so the verdicts are remade, and the Maker app runs them live, where `spec-step` and `spec-read` reach the state a person has open.");
-  const skills = skillsOf(m).map((sk) => sk.name);
-  if (skills.length) lines.push("", `Skills: ${skills.join(", ")}.`);
+  const context = m.instructions.context?.trim();
+  if (context) lines.push("", context);
   return lines.join("\n") + "\n";
 }
 

package/src/{promptware → agents}/define.ts

@@ -1,4 +1,4 @@
-// What a baba tells agent harnesses, as data: its promptware rendered into
+// What a baba tells agent harnesses, as data: its agentic instructions rendered into
 // the manifest; the kernel renders the files from it.
 import type { Manifest } from "../ecs/baba.ts";
 
@@ -8,7 +8,7 @@ export interface SkillManifest { name: string; description: string; body: string
 /** The skills of a manifest, by name, each checked to name actions and queries that exist. */
 export function skillsOf(m: Manifest): SkillManifest[] {
   const out: SkillManifest[] = [];
-  for (const [name, s] of Object.entries(m.promptware.skills).sort(([a], [b]) => a.localeCompare(b))) {
+  for (const [name, s] of Object.entries(m.instructions.skills).sort(([a], [b]) => a.localeCompare(b))) {
     for (const u of s.uses ?? []) if (!(u in m.actions) && !(u in m.queries)) throw new Error(`skill ${name} uses ${u}, which is not an action or query of the baba`);
     out.push({ name, description: s.description, body: s.body, uses: [...(s.uses ?? [])] });
   }

package/src/{promptware → agents}/disk.ts

@@ -1,5 +1,5 @@
-// Promptware with the baba down: the shell reads the manifest the last load
-// wrote, which carries the baba's promptware rendered and its harness, and
+// Instructions with the baba down: the shell reads the manifest the last load
+// wrote, which carries the baba's agentic instructions rendered and its harness, and
 // runs the same compiler and the same plan the system runs.
 import { join, dirname } from "node:path";
 import { lstat, mkdir, rename, rm, rmdir } from "node:fs/promises";
@@ -32,7 +32,7 @@ async function look(root: string, path: string): Promise<Seen> {
 
 async function writeAtomic(path: string, text: string): Promise<void> {
   await mkdir(dirname(path), { recursive: true });
-  const tmp = join(dirname(path), `.promptware-${crypto.randomUUID()}`);
+  const tmp = join(dirname(path), `.agents-${crypto.randomUUID()}`);
   try {
     await Bun.write(tmp, text);
     await rename(tmp, path);
@@ -44,7 +44,10 @@ async function writeAtomic(path: string, text: string): Promise<void> {
 
 /** What the compiler takes for the project at root. */
 export function sources(_root: string, manifest: Manifest, title?: string): CompileInput {
-  return { program: "voss baba", ...(title !== undefined ? { title } : {}), manifest };
+  // A manifest an older voss wrote names the instructions `promptware`: read as they are.
+  const older = (manifest as unknown as { promptware?: Manifest["instructions"] }).promptware;
+  const m = manifest.instructions || !older ? manifest : { ...manifest, instructions: older };
+  return { program: "voss baba", ...(title !== undefined ? { title } : {}), manifest: m };
 }
 
 /** Compiles and plans against the project at root. Writes nothing. */

package/src/{promptware → agents}/sync.ts

@@ -1,4 +1,4 @@
-// Compiled promptware onto disk, owning only what it wrote. The state file
+// Compiled agentic instructions onto disk, owning only what it wrote. The state file
 // records the sha256 of every output the compiler last wrote, and of its
 // part of a shared file; comparing it with the files gives each output a
 // status:
@@ -25,7 +25,7 @@ export type Status = "current" | "stale" | "missing" | "held" | "foreign";
 export type Action = "write" | "remove";
 
 /** Relative to the project root. */
-export const statePath = ".baba/.voss/promptware.json";
+export const statePath = ".baba/.voss/agents.json";
 
 /** What the compiler last wrote: output path to the hash of its text, or of its part of a shared file, and those parts. */
 export interface Written {

package/src/{promptware → agents}/system.ts

@@ -1,5 +1,5 @@
-// The promptware system: voss gives it to every baba. The know-how is the
-// baba's promptware, rendered into the manifest with its harness
+// The agents system: voss gives it to every baba. The know-how is the
+// baba's agentic instructions, rendered into the manifest with its harness
 // declaration; this system's state is the outputs' hashes; its effects
 // compile the know-how for each harness and write the files through the
 // kernel. The system is made per baba, given the manifest of the
@@ -7,7 +7,7 @@
 import { effect, manifestOf, resource, baba, nameOf, type Manifest, type Baba } from "../ecs/baba.ts";
 import { system, type StateOf } from "../ecs/system.ts";
 import { s } from "../kernel/schema.ts";
-import type { Prompt } from "../prompt/index.ts";
+import type { Prompt } from "../instructions/index.ts";
 import type { Fs } from "../kernel/context.ts";
 import type { Value } from "../ecs/state.ts";
 import maker from "../maker/system.ts";
@@ -65,9 +65,9 @@ const writtenRow = s.object({ path: s.string(), hash: s.string(), harness: s.str
  * nothing. Its rows are resources, not entities: voss's own system takes no
  * ids from the baba's sequence and adds nothing to its entities.
  */
-export const promptwareSystem = (manifest: () => Manifest | null) => system({
-  // promptware, declared: the same for every baba; what it compiles is the manifest each implementation is given.
-  name: "promptware",
+export const agentsSystem = (manifest: () => Manifest | null) => system({
+  // agentic instructions, declared: the same for every baba; what it compiles is the manifest each implementation is given.
+  name: "agents",
   model: {
     /** One row per output of the last plan: its hash on disk then, its harness, its status and what a sync does there. */
     pwWritten: resource(s.array(writtenRow), []),
@@ -105,9 +105,9 @@ export const promptwareSystem = (manifest: () => Manifest | null) => system({
       },
     }),
   },
-}, (promptware, p) => {
-  type W = StateOf<typeof promptware>;
-  const { pwWritten, pwStatus, pwScan, pwWrite } = promptware;
+}, (agents, p) => {
+  type W = StateOf<typeof agents>;
+  const { pwWritten, pwStatus, pwScan, pwWrite } = agents;
   const setIf = <K extends typeof pwWritten | typeof pwStatus>(w: W, r: K, v: Value<K>) => { if (!same(w.get(r), v)) w.set(r, v); };
 
   /** The outputs the state compiles to and their key; null before the baba has a manifest. */
@@ -148,7 +148,7 @@ export const promptwareSystem = (manifest: () => Manifest | null) => system({
       },
     }),
 
-    // What the baba's promptware compiles to, planned when it changed, written when the harness says auto or a sync asked.
+    // What the baba's agentic instructions compiles to, planned when it changed, written when the harness says auto or a sync asked.
     p.step("plan", (w) => {
       const st = w.get(pwStatus);
       if (w.running(pwWrite) || !st.scanned) return;
@@ -167,7 +167,7 @@ export const promptwareSystem = (manifest: () => Manifest | null) => system({
       });
     }),
 
-    p.action("promptware-sync", {
+    p.action("agents-sync", {
       summary: "compile the know-how for each harness and write the files now",
       result: s.object({ asked: s.boolean(), outputs: s.array(writtenRow) }),
       run: (w) => {
@@ -176,7 +176,7 @@ export const promptwareSystem = (manifest: () => Manifest | null) => system({
       },
     }),
 
-    p.query("promptware-plan", {
+    p.query("agents-plan", {
       summary: "each output of each harness: its status and what a sync does there",
       result: s.object({ auto: s.boolean(), lastSync: s.nullable(s.integer()), syncs: s.integer(), pending: s.integer(), error: s.nullable(s.string()), outputs: s.array(writtenRow) }),
       read: (w) => {
@@ -187,7 +187,7 @@ export const promptwareSystem = (manifest: () => Manifest | null) => system({
   ];
 });
 
-/** What voss tells agents in every baba, after the baba's own promptware: its skills. The word on the two systems it adds is the compiler's, in the shell of the context file. */
+/** What voss tells agents in every baba, after the baba's own agentic instructions: its skills. The word on the two systems it adds is the compiler's, in the shell of the context file. */
 const voss: readonly Prompt[] = guide;
 
 /** Voss's own systems, by identity: filtered from what a project's docs and tables show. */
@@ -195,20 +195,20 @@ export const ours = new WeakSet<object>();
 export const isOurs = (c: object) => ours.has(c);
 
 /** The baba with voss's own systems after its own: what the runtime runs. Every baba gets the shell, the desktop system, over the apps it declares. */
-export function withPromptware(v: Baba): Baba {
+export function withInstructions(v: Baba): Baba {
   if (v.systems.some((c) => ours.has(c))) return v;
-  for (const name of ["promptware", "maker"]) if (v.systems.some((c) => nameOf(c) === name)) throw new Error(`a system of this baba is named ${name}, which voss gives every baba; name it otherwise`);
+  for (const name of ["agents", "maker"]) if (v.systems.some((c) => nameOf(c) === name)) throw new Error(`a system of this baba is named ${name}, which voss gives every baba; name it otherwise`);
   // A baba from before the shell was voss's brings its own desktop system, and keeps it; one system or the other, never both.
   const own = v.systems.find((c) => nameOf(c) === "desktop");
   if (own && v.apps.length) throw new Error("this baba declares apps and also has a system named desktop; the shell is voss's now: drop the system and keep baba({ apps })");
   let m: Manifest | null = null;
-  const pw = promptwareSystem(() => m);
+  const pw = agentsSystem(() => m);
   const catalog = own ? v.apps : catalogOf(v.apps);
   const shell = own ? null : desktop({ apps: catalog });
   ours.add(pw);
   ours.add(maker);
   if (shell) ours.add(shell);
-  const composed = baba({ systems: [...v.systems, ...(shell ? [shell] : []), pw, maker], apps: catalog, promptware: [...v.promptware, ...voss], harness: v.harness, ...(v.tick !== null ? { tick: v.tick } : {}) });
+  const composed = baba({ systems: [...v.systems, ...(shell ? [shell] : []), pw, maker], apps: catalog, instructions: [...v.instructions, ...voss], harness: v.harness, ...(v.tick !== null ? { tick: v.tick } : {}) });
   m = manifestOf(composed);
   return composed;
 }

package/src/baba/check.ts

@@ -81,10 +81,10 @@ export async function check(p: Project, stdout: (s: string) => void, stderr: (s:
     }
     if (err) stderr(err);
   }
-  const mdx = [...new Bun.Glob("promptware/**/*.mdx").scanSync({ cwd: p.baba })];
+  const mdx = [...new Bun.Glob("agents/**/*.mdx").scanSync({ cwd: p.baba })];
   if (mdx.length) {
-    try { await bundleProject(p); stdout("promptware MDX: clean\n"); }
-    catch (error) { failed = true; stderr(`promptware MDX: ${String(error)}\n`); }
+    try { await bundleProject(p); stdout("agentic instructions MDX: clean\n"); }
+    catch (error) { failed = true; stderr(`agentic instructions MDX: ${String(error)}\n`); }
   }
   return failed ? 1 : 0;
 }

package/src/baba/config.ts

@@ -38,7 +38,7 @@ const note = "Written by voss on every load. Edit .baba/tsconfig.json to extend
 export function editorConfig(): string {
   return JSON.stringify({
     "//": note,
-    // JSX is React's unless a file says otherwise: promptware, TSX that renders to Markdown, names its runtime with a pragma.
+    // JSX is React's unless a file says otherwise: agentic instructions, TSX that renders to Markdown, names its runtime with a pragma.
     // No alias here: the project's tsconfig.json, which extends this, states `@/` relative to itself, and tools that read it resolve it there.
     compilerOptions: { lib: ["ESNext"], ...options, jsx: "react-jsx", jsxImportSource: "react" },
     include: ["guard.d.ts", "assets.d.ts", "../**/*.ts"],
@@ -205,7 +205,7 @@ export function assetDeclarations(): string {
     "// Written by voss on every load: what a baba imports besides code.",
     "// Text: `import guide from \"./guide.md\" with { type: \"text\" }`.",
     ...["md", "txt"].map((ext) => `declare module "*.${ext}" {\n  const text: string;\n  export default text;\n}`),
-    `declare module "*.mdx" { const prompt: import("babavoss/prompt").Prompt; export default prompt; }`,
+    `declare module "*.mdx" { const prompt: import("babavoss/instructions").Prompt; export default prompt; }`,
     "// Every spec of the baba, found where it lives (systems/NAME/spec.ts, spec.ts): what the Maker's page runs.",
     `declare module "babavoss:specs" { const specs: import("babavoss/spec").Spec<any, any>[]; export default specs; }`,
     "// A stylesheet, bundled with the view and attached to its windows: `import \"./view.css\"`.",
@@ -242,6 +242,9 @@ export async function writeEditorConfig(p: Project): Promise<string> {
  * tsconfig.json and .gitignore that pointed there follow.
  */
 export async function moveOldDir(p: Project): Promise<void> {
+  // The agentic instructions lived in .baba/promptware, their record in .voss/promptware.json: moved once, by name.
+  if (existsSync(join(p.baba, "promptware")) && !existsSync(join(p.baba, "agents"))) await rename(join(p.baba, "promptware"), join(p.baba, "agents"));
+  if (existsSync(join(p.baba, VOSS, "promptware.json")) && !existsSync(join(p.baba, VOSS, "agents.json"))) await rename(join(p.baba, VOSS, "promptware.json"), join(p.baba, VOSS, "agents.json"));
   const old = join(p.baba, "state");
   if (!existsSync(old) || existsSync(join(p.baba, VOSS))) return;
   await rename(old, join(p.baba, VOSS));

package/src/baba/init.ts

@@ -1,5 +1,5 @@
 // voss init: a .baba in a directory, its dependencies installed. One entry,
-// one interface, one system to start from, and the promptware: what the baba tells
+// one interface, one system to start from, and the agentic instructions: what the baba tells
 // agents, as code, versioned with the project.
 import { basename, join, resolve } from "node:path";
 import { mkdir } from "node:fs/promises";
@@ -42,7 +42,7 @@ export async function init(dir: string, o: InitOptions): Promise<{ name: string;
   await Bun.write(join(baba, "systems", "hello", "index.ts"), systemFile("hello"));
   await Bun.write(join(baba, "systems", "hello", "spec.ts"), systemSpecFile("hello"));
   await Bun.write(join(baba, "spec.test.ts"), specRunnerFile);
-  await Bun.write(join(baba, "promptware", "index.ts"), promptwareFile(o.title ?? name));
+  await Bun.write(join(baba, "agents", "context.mdx"), contextFile(o.title ?? name));
   if (o.install !== false) await install(baba);
   return { name, dir };
 }
@@ -55,34 +55,29 @@ export async function install(baba: string): Promise<void> {
   if (code !== 0) throw new Error(`bun install failed in ${baba}: ${(err || out).trim().split("\n").slice(-5).join("; ")}`);
 }
 
-/** The promptware: what the baba tells agents, as code. The contract is not here: agents get it at `voss baba`. */
-export const promptwareFile = (title: string) => `import { context, md } from "babavoss/prompt";
+/** The agentic instructions: what the baba tells agents, one .mdx per document under .baba/agents/. The contract is not here: agents get it at `voss baba`. */
+export const contextFile = (title: string) => `export const prompt = { kind: "context" };
 
-// What this baba tells agents: its section of the context file, its skills
-// (one skill(...) per .tsx beside this file), its hooks. Code, rendered to
-// Markdown and compiled by voss into CLAUDE.md and the skills.
-export default [
-  context(md\`
-    ${title.replaceAll("\\", "\\\\").replaceAll("`", "\\`").replaceAll("$", "\\$")}: say here what this project is, in a sentence or two.
+{/* What this baba tells agents: its section of the context file. A skill is another .mdx beside this one,
+    with export const prompt = { kind: "skill", name, description, uses }. A hook is hooks: [{ on, match, action }] here. */}
 
-    How to work on it: the conventions, the checks to run before a commit, what not to touch.
+${title.replaceAll("{", "\\{").replaceAll("}", "\\}").replaceAll("<", "\\<")}: say here what this project is, in a sentence or two.
 
-    ## Rules
+How to work on it: the conventions, the checks to run before a commit, what not to touch.
 
-    - Keep the tests green on every commit.
-  \`),
-];
+## Rules
+
+- Keep the tests green on every commit.
 `;
 
-/** The entry: the baba, its systems listed, its promptware; `harness` for which harnesses get the files. */
+/** The entry: the baba, its systems listed; `harness` for which harnesses get the files. The agentic instructions are the .mdx files under agents/, read by voss. */
 export const entry = `import { baba } from "babavoss";
 import { kit } from "babavoss/kit";
 import hello from "./systems/hello/index.ts";
-import promptware from "./promptware/index.ts";
 
 // kit keeps the baba's components, under ui/, as objects: \`voss baba ui\` lists them, \`ui-add\` brings more from shadcn.
 // The apps voss's shell offers; interface.tsx gives each its component.
-export default baba({ systems: [hello, kit], apps: [{ key: "hello", title: "Hello", icon: "hand" }], promptware });
+export default baba({ systems: [hello, kit], apps: [{ key: "hello", title: "Hello", icon: "hand" }] });
 `;
 
 /** A system: a data model, one action, one query, written as one expression: the declaration, then its pieces made from it. */

package/src/baba/node.ts

@@ -60,7 +60,7 @@ const ACTIVATE_MS = 10_000;
 const QUIET_MS = 300;
 /** How often a reload that waits for a job asks again. */
 const WAIT_MS = 500;
-// What changes under .baba without changing the code: voss's own files and the dependencies. Promptware is code: a change there reloads.
+// What changes under .baba without changing the code: voss's own files and the dependencies. Instructions is code: a change there reloads.
 const IGNORED = [".voss", "node_modules"];
 
 /** Makes the transport a Node loads a project over. The worker is the first; a runtime process is next. */
@@ -188,7 +188,7 @@ export class Node {
       throw err;
     });
     fresh.manifest = loaded.manifest;
-    // The contract outlives the run: discovery and promptware read it with the baba down.
+    // The contract outlives the run: discovery and agentic instructions read it with the baba down.
     await mkdir(join(this.project.baba, ".voss"), { recursive: true })
       .then(() => Bun.write(manifestPath(this.project), JSON.stringify(loaded.manifest, null, 2) + "\n"))
       .catch((err) => this.log(`${this.name}: the manifest was not written: ${err instanceof Error ? err.message : String(err)}`));

package/src/baba/project.ts

@@ -21,8 +21,8 @@ export interface Project {
 }
 
 const NAME = /^[a-z][a-z0-9-]*$/;
-/** The page's own first segments: a baba's address is `/NAME/…`, so no baba is named one of them. */
-export const PAGE_WORDS = new Set(["api", "assets", "view", "ws"]);
+import { PAGE_WORDS } from "./requirements.ts";
+export { PAGE_WORDS };
 
 interface Pkg { name?: unknown; baba?: unknown; dependencies?: unknown; devDependencies?: unknown }
 

package/src/baba/requirements.ts

@@ -0,0 +1,39 @@
+// What voss needs of a baba before it runs it: a set of properties, each read
+// from the baba's .baba/package.json and written back there by the setup
+// wizard. A folder voss remembers is ready when every one is set and valid;
+// until then it is set up, not run, and the picker opens its wizard in place
+// of its page. A folder with no .baba lacks them all, and setting them up
+// makes its .baba first. For now there is one: the name.
+// Pure, so the page checks a name as the kernel will; reading and writing a
+// folder is setup.ts's.
+
+/** The page's own first segments: a baba's address is `/NAME/…`, so no baba is named one of them. */
+export const PAGE_WORDS = new Set(["api", "assets", "view", "ws"]);
+
+/** The properties voss needs of every baba, in the order the wizard asks for them. */
+export const requirements = [
+  {
+    key: "name", title: "Name",
+    summary: "The baba's address and its name at the shell: voss serves it at /NAME/, and the CLI reaches it as voss NAME from anywhere.",
+  },
+] as const;
+export type Requirement = typeof requirements[number]["key"];
+/** What the wizard has to set: each requirement's value. */
+export type RequirementValues = Partial<Record<Requirement, string>>;
+
+const NAME = /^[a-z][a-z0-9-]*$/;
+
+/** Why a value will not do for a requirement, or null when it does; `taken` are the names other babas already have. */
+export function requirementError(key: Requirement, value: string, taken: readonly string[] = []): string | null {
+  if (key === "name") {
+    if (!value) return "A baba needs a name.";
+    if (!NAME.test(value)) return "Lowercase letters, digits and dashes, starting with a letter.";
+    if (PAGE_WORDS.has(value)) return `/${value}/ is the page's own address; choose another.`;
+    if (taken.includes(value)) return `Another baba is already called ${value}.`;
+  }
+  return null;
+}
+
+/** A folder's name as a baba's name: what the wizard offers first. */
+export const nameFrom = (dir: string) => (dir.split("/").filter(Boolean).pop() ?? "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").replace(/^[^a-z]+/, "");
+

package/src/baba/setup.ts

@@ -0,0 +1,30 @@
+// A folder's standing against what voss requires of a baba, read from its
+// .baba/package.json, and the requirements written back there.
+import { join, resolve } from "node:path";
+import { exists } from "./project.ts";
+import { nameFrom, requirementError, requirements, type Requirement, type RequirementValues } from "./requirements.ts";
+
+/** Where a folder stands: whether it has a .baba, the requirements it lacks, and the values it already has. */
+export interface Setup { dir: string; baba: boolean; missing: Requirement[]; values: RequirementValues; suggested: RequirementValues }
+
+/** Reads a folder's .baba/package.json for the requirements; a package.json that does not parse is an error, not a missing value. */
+export async function setupOf(dir: string): Promise<Setup> {
+  dir = resolve(dir);
+  const file = join(dir, ".baba", "package.json");
+  const suggested = { name: nameFrom(dir) };
+  if (!(await exists(file))) return { dir, baba: false, missing: requirements.map((r) => r.key), values: {}, suggested };
+  const pkg = await Bun.file(file).json() as { name?: unknown; baba?: { name?: unknown } };
+  const name = typeof pkg.baba?.name === "string" ? pkg.baba.name : typeof pkg.name === "string" ? pkg.name : undefined;
+  const values: RequirementValues = name === undefined ? {} : { name };
+  const missing = requirements.map((r) => r.key).filter((k) => values[k] === undefined || requirementError(k, values[k]!) !== null);
+  return { dir, baba: true, missing, values, suggested };
+}
+
+/** Writes the requirements into a .baba that exists, leaving everything else in its package.json as it was. */
+export async function writeRequirements(dir: string, values: RequirementValues): Promise<void> {
+  const file = join(resolve(dir), ".baba", "package.json");
+  const pkg = await Bun.file(file).json() as Record<string, unknown> & { baba?: Record<string, unknown> };
+  const baba = { ...(typeof pkg.baba === "object" && pkg.baba ? pkg.baba : {}) };
+  if (values.name !== undefined) baba.name = values.name;
+  await Bun.write(file, JSON.stringify({ ...pkg, baba }, null, 2) + "\n");
+}

package/src/baba/worker.ts

@@ -5,7 +5,8 @@ import { plugin as bunPlugin } from "bun";
 import { dirname, join } from "node:path";
 import type { ToRuntime, FromRuntime } from "../transport/messages.ts";
 import type { Snapshot } from "../ecs/state.ts";
-import { isBaba } from "../ecs/baba.ts";
+import { isBaba, instructed } from "../ecs/baba.ts";
+import type { Prompt } from "../instructions/index.ts";
 import { openProject } from "./project.ts";
 import { readEnv } from "../runtime/env.ts";
 import { Harness } from "../runtime/harness.ts";
@@ -20,9 +21,9 @@ const names: Record<string, string> = {
   "babavoss": join(root, "index.ts"),
   "babavoss/desktop": join(root, "src/desktop/index.ts"),
   "babavoss/kit": join(root, "src/kit/index.ts"),
-  "babavoss/prompt": join(root, "src/prompt/index.ts"),
-  "babavoss/prompt/jsx-runtime": join(root, "src/prompt/jsx-runtime.ts"),
-  "babavoss/prompt/jsx-dev-runtime": join(root, "src/prompt/jsx-dev-runtime.ts"),
+  "babavoss/instructions": join(root, "src/instructions/index.ts"),
+  "babavoss/instructions/jsx-runtime": join(root, "src/instructions/jsx-runtime.ts"),
+  "babavoss/instructions/jsx-dev-runtime": join(root, "src/instructions/jsx-dev-runtime.ts"),
   "babavoss/test": join(root, "src/test/index.ts"),
   "babavoss/bench": join(root, "src/bench/index.ts"),
 };
@@ -45,7 +46,14 @@ self.onmessage = async (e: MessageEvent<ToWorker>) => {
       const project = await openProject(m.dir);
       const mod = (await import(`${project.entry}?t=${Date.now()}`)) as { default?: unknown };
       if (!isBaba(mod.default)) throw new Error(`${project.entry}: the default export is not a baba(); export default baba({ systems: [...] })`);
-      h.load(mod.default, { name: project.name, dir: project.dir, baba: project.baba }, await readEnv(project.baba), m.snapshot, m.prepare);
+      // The agentic instructions: every .mdx under .baba/agents/, in name order, as the builder's bundle has them.
+      const docs: Prompt[] = [];
+      for (const f of [...new Bun.Glob("agents/*.mdx").scanSync({ cwd: project.baba })].sort()) {
+        const d = (await import(join(project.baba, f))) as { default?: Prompt };   // the plugin reads .mdx by its suffix: no query here
+        if (!d.default || typeof d.default !== "object" || !("kind" in d.default)) throw new Error(`${f}: not an instruction document; export const prompt = { kind: "context" | "skill", … }`);
+        docs.push(d.default);
+      }
+      h.load(instructed(mod.default, docs), { name: project.name, dir: project.dir, baba: project.baba }, await readEnv(project.baba), m.snapshot, m.prepare);
     } catch (err) {
       post({ type: "failed", error: err instanceof Error ? err.message : String(err) });
     }

package/src/build/mdx.ts

@@ -6,28 +6,28 @@ import { forbiddenModules, advice } from "./guard.ts";
 function promptExport() {
   return (tree: any) => {
     const metadata = tree.body.some((n: any) => n.type === "ExportNamedDeclaration" && n.declaration?.type === "VariableDeclaration" && n.declaration.declarations.some((d: any) => d.id.name === "prompt"));
-    if (!metadata) throw new Error('MDX promptware needs an exported prompt metadata object');
+    if (!metadata) throw new Error('an MDX instruction file needs an exported prompt metadata object');
     const exported = tree.body.find((n: any) => n.type === "ExportDefaultDeclaration");
     if (!exported || exported.declaration.type !== "FunctionDeclaration") throw new Error("MDX must export a document component");
     const component = exported.declaration;
     const id = (name: string) => ({ type: "Identifier", name });
     const literal = (value: string) => ({ type: "Literal", value });
     tree.body[tree.body.indexOf(exported)] = component;
-    tree.body.push({ type: "ImportDeclaration", source: literal("babavoss/prompt"), specifiers: [{ type: "ImportSpecifier", imported: id("mdxDocument"), local: id("$promptDocument") }] });
+    tree.body.push({ type: "ImportDeclaration", source: literal("babavoss/instructions"), specifiers: [{ type: "ImportSpecifier", imported: id("mdxDocument"), local: id("$promptDocument") }] });
     tree.body.push({ type: "ExportDefaultDeclaration", declaration: { type: "CallExpression", callee: id("$promptDocument"), arguments: [id("prompt"), id(component.id.name)], optional: false } });
   };
 }
 
 export async function compilePromptMdx(value: string, path: string): Promise<string> {
   const result = String(await compile({ value, path }, {
-    jsxImportSource: "babavoss/prompt", format: "mdx", development: false,
+    jsxImportSource: "babavoss/instructions", format: "mdx", development: false,
     remarkPlugins: [gfm], recmaPlugins: [promptExport],
   }));
   // Bun's bun-target builtin imports can bypass onResolve: apply the same guard after MDX compilation.
   for (const item of new Bun.Transpiler({ loader: "js" }).scanImports(result)) {
     if (forbiddenModules[item.path]) throw new Error(`${path} imports ${item.path}; ${advice(forbiddenModules[item.path]!)}`);
   }
-  if (/\b(?:with|assert)\s*\{\s*type\s*:\s*["']macro["']\s*\}/.test(result)) throw new Error(`${path}: macros are not allowed in promptware`);
+  if (/\b(?:with|assert)\s*\{\s*type\s*:\s*["']macro["']\s*\}/.test(result)) throw new Error(`${path}: macros are not allowed in agentic instructions`);
   return result;
 }