babavoss 0.12.5 → 0.13.0

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.5",
+  "version": "0.13.0",
   "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",
@@ -37,7 +37,9 @@
     "test": "bun test",
     "test:kernel": "VOSS_KERNEL=1 bun test ./test/kernel.test.ts",
     "test:all": "VOSS_KERNEL=1 bun test",
-    "check": "bunx tsc --noEmit -p ../.."
+    "check": "bunx tsc --noEmit -p ../..",
+    "prepack": "bun ../../tools/release/pack.ts prepack",
+    "postpack": "bun ../../tools/release/pack.ts postpack"
   },
   "devDependencies": {
     "@types/react-dom": "19"

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, []);
@@ -136,10 +136,10 @@ function instructionFile(input: CompileInput): string {
   const prog = input.program;
   const m = input.manifest;
   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();
+  const context = m.instructions.context?.trim();
   if (context) lines.push("", context);
   lines.push(
     "", "## This baba", "",
@@ -172,7 +172,7 @@ 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.");
+  lines.push("", "Voss adds two systems to this baba. `agents` compiles what the baba tells agents, its context, skills and hooks, each an .mdx file under `.baba/agents/`, into each harness's files: `CLAUDE.md`, `AGENTS.md`, the skills, Claude Code's permissions and hooks. Those are generated: edit the agentic instructions, 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(", ")}.`);
   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/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;
 }
 

package/src/build/project.ts

@@ -12,9 +12,14 @@ const harness = join(framework, "src/runtime/worker.ts");
 const ENTRY = "/babavoss/entry.ts";
 
 export async function bundleProject(project: Project): Promise<string> {
+  // The agentic instructions: every .mdx under .baba/agents/, in name order, each a document the baba is given.
+  const docs = [...new Bun.Glob("agents/*.mdx").scanSync({ cwd: project.baba })].sort().map((f) => join(project.baba, f));
   const text = [
-    `import v from ${JSON.stringify(project.entry)};`,
+    `import entry from ${JSON.stringify(project.entry)};`,
+    `import { instructed } from "babavoss";`,
     `import { serve } from ${JSON.stringify(harness)};`,
+    ...docs.map((f, i) => `import doc${i} from ${JSON.stringify(f)};`),
+    `const v = instructed(entry, [${docs.map((_, i) => `doc${i}`).join(", ")}]);`,
     `export default v;`,
     `serve(v);`,
   ].join("\n") + "\n";

package/src/build/views.ts

@@ -27,9 +27,9 @@ export const names: Record<string, string> = {
   "babavoss/web": join(framework, "src/web/index.tsx"),
   "babavoss/test": join(framework, "src/test/index.ts"),
   "babavoss/bench": join(framework, "src/bench/index.ts"),
-  "babavoss/prompt": join(framework, "src/prompt/index.ts"),
-  "babavoss/prompt/jsx-runtime": join(framework, "src/prompt/jsx-runtime.ts"),
-  "babavoss/prompt/jsx-dev-runtime": join(framework, "src/prompt/jsx-dev-runtime.ts"),
+  "babavoss/instructions": join(framework, "src/instructions/index.ts"),
+  "babavoss/instructions/jsx-runtime": join(framework, "src/instructions/jsx-runtime.ts"),
+  "babavoss/instructions/jsx-dev-runtime": join(framework, "src/instructions/jsx-dev-runtime.ts"),
 };
 
 /**

package/src/desktop/index.ts

@@ -293,7 +293,7 @@ export const vossApps = [
   { key: "maker", title: "Maker", icon: "hammer", group: "Voss" },
   { key: "state", title: "State", icon: "database", group: "Voss" },
   { key: "contract", title: "Contract", icon: "square-terminal", group: "Voss" },
-  { key: "promptware", title: "Promptware", icon: "book-open-text", group: "Voss" },
+  { key: "instructions", title: "Instructions", icon: "book-open-text", group: "Voss" },
   { key: "settings", title: "Settings", icon: "settings", group: "Voss" },
 ] as const satisfies readonly AppSpec[];
 export type VossApp = typeof vossApps[number]["key"];

package/src/door/core.ts

@@ -73,7 +73,7 @@ export interface Index {
   error?: string;
   systems: { name: string }[];
   /** What the baba tells agents: whether it has a context, and its skills by name. */
-  promptware: { context: boolean; skills: string[] };
+  instructions: { context: boolean; skills: string[] };
   calls: IndexCall[];
   components: Record<string, { system: string; key?: string; accept?: true }>;
   resources: string[];
@@ -115,7 +115,7 @@ export function index(m: Manifest, extra: IndexExtra = {}): Index {
     ...(extra.gen !== undefined ? { gen: extra.gen } : {}),
     ...(extra.error ? { error: extra.error } : {}),
     systems: m.systems.map((c) => ({ name: c.name })),
-    promptware: { context: !!m.promptware.context, skills: Object.keys(m.promptware.skills) },
+    instructions: { context: !!m.instructions.context, skills: Object.keys(m.instructions.skills) },
     calls: entries(m).map(({ name, kind, c }) => ({ name, kind, system: c.owner, summary: c.summary, example: exampleCall(name, c, extra.prog) })),
     components: Object.fromEntries(Object.entries(m.components).map(([n, c]) => {
       const key = keyField(c.schema);