babavoss 0.0.1 → 0.0.2

package/src/prompt/index.ts

@@ -0,0 +1,242 @@
+// babavoss/prompt: promptware 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
+// of="feed" />` and its kin for the parts that come from the contract, so a
+// skill never says what the contract does not. Static: rendered once per
+// generation, from the manifest alone.
+import type { InterpretationSuite } from "./evals.ts";
+export { interpretation, givensOf, type InterpretationSuite, type InterpretationQuestion, type InterpretationGiven, type InterpretationCase } from "./evals.ts";
+import type { Manifest, Call as CallEntry } from "../ecs/baba.ts";
+import { s, type Json, type Schema } from "../kernel/schema.ts";
+import { exampleOf } from "../ecs/handles.ts";
+import { usage } from "../shell/args.ts";
+import { isElement, jsx, Fragment, type PromptNode, type PromptElement, type PromptComponent } from "./jsx-runtime.ts";
+
+export { Fragment, type PromptNode, type PromptElement, type PromptComponent, type JSX } from "./jsx-runtime.ts";
+
+/** What a baba declares under `promptware`. */
+export type Prompt =
+  | { kind: "context"; body: PromptNode; eval?: InterpretationSuite }
+  | { kind: "skill"; name: string; description: string; uses: string[]; body: PromptNode; eval?: InterpretationSuite }
+  | { kind: "hook"; on: HookEvent; match: string | null; action: string; strict: boolean };
+
+/** The moments a harness can hand to the baba: Claude Code's hook events. */
+export const HOOK_EVENTS = ["PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop", "SubagentStop", "SessionStart", "PreCompact", "Notification"] as const;
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+
+/**
+ * A hook: at `on`, the harness calls the baba's action `action` with the
+ * event as its args, `voss baba ACTION @- --hook EVENT`, and does what the
+ * answer says: `{ decision: "block", reason }` stops it, `{ context }` is
+ * told to the agent, `{}` lets it through. `match` narrows PreToolUse and
+ * 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 {
+  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 };
+}
+
+/** A hook's event as Claude Code sends it: the fields any event may carry, typed; anything else let through. */
+export interface HookArgs {
+  session_id?: string; transcript_path?: string; cwd?: string; hook_event_name?: string;
+  tool_name?: string; tool_input?: unknown; tool_response?: unknown;
+  prompt?: string; message?: string; trigger?: string; custom_instructions?: string; source?: string; stop_hook_active?: boolean;
+  [field: string]: unknown;
+}
+/** What a hook's action answers: block with a reason, or let through, with context for the agent when there is some. */
+export interface HookAnswer { decision?: "allow" | "block"; reason?: string; context?: string }
+
+/** The args a hook's action takes: the event as Claude Code sends it, the common fields typed, the rest let through. */
+export function hookArgs(on: HookEvent): Schema<HookArgs> {
+  const common = { session_id: s.optional(s.string()), transcript_path: s.optional(s.string()), cwd: s.optional(s.string()), hook_event_name: s.optional(s.string()) };
+  const tool = { tool_name: s.optional(s.string()), tool_input: s.optional(s.unknown()) };
+  const shape = (() => {
+    switch (on) {
+      case "PreToolUse": return { ...common, ...tool };
+      case "PostToolUse": return { ...common, ...tool, tool_response: s.optional(s.unknown()) };
+      case "UserPromptSubmit": return { ...common, prompt: s.optional(s.string()) };
+      case "Notification": return { ...common, message: s.optional(s.string()) };
+      case "PreCompact": return { ...common, trigger: s.optional(s.string()), custom_instructions: s.optional(s.string()) };
+      case "SessionStart": return { ...common, source: s.optional(s.string()) };
+      default: return { ...common, stop_hook_active: s.optional(s.boolean()) };
+    }
+  })();
+  return s.object(shape, { open: true }) as unknown as Schema<HookArgs>;
+}
+/** What a hook's action answers: block with a reason, or let through, with context for the agent when there is some. */
+export const hookResult = (): Schema<HookAnswer> => s.object({ decision: s.optional(s.enum("allow", "block")), reason: s.optional(s.string()), context: s.optional(s.string()) }) as Schema<HookAnswer>;
+
+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 } : {}) });
+
+/** 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 {
+  if (!WORD.test(head.name)) throw new Error(`skill ${JSON.stringify(head.name)}: lowercase words joined by single dashes`);
+  if (!head.description.trim() || head.description.includes("\n") || head.description.length > 1024) throw new Error(`skill ${head.name}: a one-line description, at most 1024 characters`);
+  return { kind: "skill", name: head.name, description: head.description.trim(), uses: [...(head.uses ?? [])], body, ...(head.eval ? { eval: head.eval } : {}) };
+}
+
+/** 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 {
+  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", ... }');
+}
+
+/** Raw Markdown, verbatim, with the common indentation removed: for prose longer than a line. */
+export function md(strings: TemplateStringsArray, ...values: unknown[]): string {
+  // Raw, so a backslash before a backtick or a dollar is the author's escape; the bundler may have escaped a non-ASCII character as \uXXXX, which is put back.
+  const text = strings.raw.map((s, i) => s.replace(/\\u([0-9a-fA-F]{4})/g, (_, h) => String.fromCharCode(parseInt(h, 16))).replace(/\\`/g, "`").replace(/\\\$/g, "$").replace(/\\\\/g, "\\") + (i < values.length ? String(values[i]) : "")).join("");
+  return dedent(text);
+}
+
+function dedent(text: string): string {
+  const lines = text.replace(/^\n/, "").replace(/\n[ \t]*$/, "").split("\n");
+  const indents = lines.filter((l) => l.trim()).map((l) => /^[ \t]*/.exec(l)![0].length);
+  const cut = indents.length ? Math.min(...indents) : 0;
+  return lines.map((l) => l.slice(Math.min(cut, /^[ \t]*/.exec(l)![0].length))).join("\n").trim();
+}
+
+// ---- rendering --------------------------------------------------------------
+
+/** What the contract components render from; `refs` collects the skills a `See` named, for the manifest to check. */
+export interface Context { manifest: Manifest; program: string; refs?: string[] }
+
+let current: Context | null = null;
+const ctx = (what: string): Context => { if (!current) throw new Error(`<${what}> renders from the contract, and no manifest is in scope`); return current; };
+
+/** The tree as Markdown, with `context` in scope for the contract components. */
+export function render(node: PromptNode, context: Context | null = null): string {
+  const was = current;
+  current = context;
+  try { return block(node).trim(); } finally { current = was; }
+}
+
+const text = (v: unknown): string => (typeof v === "string" ? v : typeof v === "number" ? String(v) : "");
+
+/** Inline content: text and inline tags joined as they come. */
+function inline(node: PromptNode): string {
+  if (node === null || node === undefined || typeof node === "boolean") return "";
+  if (Array.isArray(node)) return node.map(inline).join("");
+  if (!isElement(node)) return text(node);
+  const { type, props } = node;
+  const kids = props.children as PromptNode;
+  if (typeof type === "function") return inline(type(props));
+  switch (type) {
+    case "code": {
+      const value = inline(kids);
+      const fence = "`".repeat(Math.max(1, ...Array.from(value.matchAll(/`+/g), m => m[0].length + 1)));
+      const pad = value.startsWith("`") || value.endsWith("`") ? " " : "";
+      return `${fence}${pad}${value}${pad}${fence}`;
+    }
+    case "strong": case "b": return `**${inline(kids)}**`;
+    case "em": case "i": return `*${inline(kids)}*`;
+    case "a": return `[${inline(kids)}](${String(props.href)})`;
+    case "del": return `~~${inline(kids)}~~`;
+    case "img": return `![${String(props.alt ?? "")}](${String(props.src)})`;
+    case "input": return props.type === "checkbox" ? `[${props.checked ? "x" : " "}] ` : "";
+    case "br": return "  \n";
+    default: return block(node);
+  }
+}
+
+/** Block content: paragraphs, lists, code, tables, each followed by a blank line. */
+function block(node: PromptNode): string {
+  if (node === null || node === undefined || typeof node === "boolean") return "";
+  if (Array.isArray(node)) return joinBlocks(node.map(block));
+  if (!isElement(node)) return text(node) + "\n\n";
+  const { type, props } = node;
+  const kids = props.children as PromptNode;
+  if (typeof type === "function") return block(type(props));
+  switch (type) {
+    case "h1": case "h2": case "h3": case "h4": case "h5": case "h6": return `${"#".repeat(Number(type.slice(1)))} ${inline(kids).trim()}\n\n`;
+    case "h": return `${"#".repeat(Number(props.level ?? 2))} ${inline(kids).trim()}\n\n`;
+    case "p": return `${inline(kids).trim()}\n\n`;
+    case "ul": case "ol": return items(kids, type === "ol") + "\n";
+    case "li": return `- ${inline(kids).trim()}\n`;
+    case "pre": {
+      const code = isElement(kids) && kids.type === "code" ? kids : null;
+      const content = code ? text(code.props.children).replace(/\n$/, "") : dedent(inline(kids));
+      const lang = code ? String(code.props.className ?? "").replace(/^language-/, "") : String(props.lang ?? "");
+      const fence = "`".repeat(Math.max(3, ...Array.from(content.matchAll(/`+/g), m => m[0].length + 1)));
+      return `${fence}${lang}\n${content}\n${fence}\n\n`;
+    }
+    case "blockquote": return block(kids).trim().split("\n").map((l) => `> ${l}`).join("\n") + "\n\n";
+    case "hr": return "---\n\n";
+    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)}>`);
+  }
+}
+
+const joinBlocks = (parts: string[]): string => parts.filter((p) => p.trim()).map((p) => p.replace(/\n+$/, "")).join("\n\n") + "\n\n";
+
+function items(kids: PromptNode, ordered: boolean): string {
+  const list = (Array.isArray(kids) ? kids : [kids]).flat().filter((k) => isElement(k) && k.type === "li") as PromptElement[];
+  return list.map((li, i) => {
+    // An item is a line: text and inline parts joined; a block inside it stands on its own lines, indented.
+    const body = inline(li.props.children as PromptNode).trim().split("\n").join("\n  ");
+    return `${ordered ? `${i + 1}.` : "-"} ${body}`;
+  }).join("\n") + "\n";
+}
+
+function table(kids: PromptNode): string {
+  const flattened = (Array.isArray(kids) ? kids : [kids]).flat().flatMap(k => isElement(k) && ["thead", "tbody"].includes(String(k.type)) ? (Array.isArray(k.props.children) ? k.props.children : [k.props.children]) : [k]);
+  const rows = (Array.isArray(flattened) ? flattened : [flattened]).flat().filter((k) => isElement(k) && k.type === "tr") as PromptElement[];
+  const cellsOf = (tr: PromptElement) => ((Array.isArray(tr.props.children) ? tr.props.children : [tr.props.children]) as PromptNode[]).flat().filter(isElement) as PromptElement[];
+  const line = (tr: PromptElement) => `| ${cellsOf(tr).map((c) => inline(c.props.children as PromptNode).trim().replaceAll("|", "\\|")).join(" | ")} |`;
+  const out: string[] = [];
+  rows.forEach((tr, i) => {
+    out.push(line(tr));
+    if (i === 0) out.push(`| ${cellsOf(tr).map(() => "---").join(" | ")} |`);
+  });
+  return out.join("\n") + "\n";
+}
+
+// ---- the contract's components ----------------------------------------------
+
+const quoted = (v: unknown) => `'${JSON.stringify(v).replaceAll("'", `'\\''`)}'`;
+const entry = (name: string, what: string): { d: CallEntry; kind: "action" | "query" } => {
+  const c = ctx(what);
+  const d = c.manifest.actions[name] ?? c.manifest.queries[name];
+  if (!d) throw new Error(`<${what} of="${name}">: no action or query ${name}; the baba has: ${[...Object.keys(c.manifest.actions), ...Object.keys(c.manifest.queries)].join(", ")}`);
+  return { d, kind: name in c.manifest.actions ? "action" : "query" };
+};
+
+/** The CLI line of a call with a literal example of its args, then its summary: `voss baba feed '{"x":0}'`: drop food. */
+export function Call({ of }: { of: string }): PromptNode {
+  const { d, kind } = entry(of, "Call");
+  return `\`${ctx("Call").program} ${of} ${quoted(exampleOf(d.args))}\`: ${d.summary || `${kind} of ${d.owner}`}`;
+}
+/** The usage line of a call as people write it: `voss baba feed <x> [--y]`. */
+export function Usage({ of }: { of: string }): PromptNode {
+  const { d } = entry(of, "Usage");
+  return `\`${ctx("Usage").program} ${[of, ...usage(d.args, d.positional)].join(" ")}\``;
+}
+/** A call's args schema, and its result's, as JSON blocks. */
+export function Schema({ of, result = false }: { of: string; result?: boolean }): PromptNode {
+  const { d } = entry(of, "Schema");
+  const show = (j: Json) => ({ $prompt: true, type: "pre", props: { lang: "json", children: JSON.stringify(j, null, 2) } } as PromptElement);
+  return [show(d.args), ...(result ? [show(d.result)] : [])];
+}
+/** The skills to read next: "See also: a, b." The names are checked to exist once every skill is rendered. */
+export function See({ skills }: { skills: string[] }): PromptNode {
+  const c = ctx("See");
+  for (const name of skills) { if (!WORD.test(name)) throw new Error(`<See>: ${JSON.stringify(name)} is not a skill name`); c.refs?.push(name); }
+  return `See also: ${skills.join(", ")}.`;
+}
+
+/** Every call of a system, one `Call` line each, as a list. */
+export function Calls({ of }: { of: string }): PromptNode {
+  const c = ctx("Calls");
+  const names = [...Object.entries(c.manifest.actions), ...Object.entries(c.manifest.queries)].filter(([, d]) => d.owner === of).map(([n]) => n);
+  if (!names.length) throw new Error(`<Calls of="${of}">: the system ${of} has no actions or queries`);
+  return { $prompt: true, type: "ul", props: { children: names.map((n) => ({ $prompt: true, type: "li", props: { children: Call({ of: n }) } })) } } as PromptElement;
+}

package/src/prompt/jsx-dev-runtime.ts

@@ -0,0 +1 @@
+export { jsx, jsxs, jsxDEV, Fragment, type JSX } from "./jsx-runtime.ts";

package/src/prompt/jsx-runtime.ts

@@ -0,0 +1,49 @@
+// The JSX runtime for promptware: elements that render to Markdown, not to
+// the DOM. A file says `/** @jsxImportSource babavoss/prompt */` 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> }
+export type PromptNode = PromptElement | string | number | boolean | null | undefined | PromptNode[];
+export type PromptComponent<P = any> = (props: P) => PromptNode;
+
+export const Fragment: PromptComponent<{ children?: PromptNode }> = (p) => p.children ?? null;
+
+export function jsx(type: string | PromptComponent, props: Record<string, unknown>, key?: unknown): PromptElement {
+  return { $prompt: true, type, props: key === undefined ? props : { ...props, key } };
+}
+export const jsxs = jsx;
+export const jsxDEV = (type: string | PromptComponent, props: Record<string, unknown>, key?: unknown) => jsx(type, props, key);
+
+export const isElement = (v: unknown): v is PromptElement => typeof v === "object" && v !== null && (v as PromptElement).$prompt === true;
+
+type Children = { children?: PromptNode };
+
+// What TypeScript admits in a promptware 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. */
+  export type ElementType = keyof IntrinsicElements | PromptComponent;
+  export interface ElementChildrenAttribute { children: {} }
+  export interface IntrinsicElements {
+    /** A heading; `level` 1 to 4, 2 by default. */
+    h: Children & { level?: 1 | 2 | 3 | 4 };
+    p: Children;
+    ul: Children;
+    ol: Children;
+    li: Children;
+    /** Inline code. */
+    code: Children;
+    /** A code block; `lang` is the fence's language. */
+    pre: Children & { lang?: string };
+    b: Children;
+    i: Children;
+    a: Children & { href: string };
+    br: {};
+    hr: {};
+    blockquote: Children;
+    table: Children;
+    tr: Children;
+    th: Children;
+    td: Children;
+  }
+}

package/src/prompt/mdx.d.ts

@@ -0,0 +1 @@
+declare module "*.mdx" { const prompt: import("./index.ts").Prompt; export default prompt; }

package/src/promptware/compile.ts

@@ -0,0 +1,183 @@
+// Promptware 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.json
+//   Codex         AGENTS.md   .agents/skills/NAME/SKILL.md
+//
+// Promptware 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
+// 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";
+import { usage } from "../shell/args.ts";
+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 type Harness = "claude" | "codex";
+export const harnesses: Harness[] = ["claude", "codex"];
+
+const files: Record<Harness, { instructions: string; skills: string }> = {
+  claude: { instructions: "CLAUDE.md", skills: ".claude/skills" },
+  codex: { instructions: "AGENTS.md", skills: ".agents/skills" },
+};
+
+/** 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";
+
+// ---- merges ------------------------------------------------------------
+
+/**
+ * A part of a file voss shares with others: an entry at a key of a JSON
+ * file, entries of a JSON list, or one table of a TOML file. sync.ts owns
+ * only the part, and holds the whole file when the part was edited by hand.
+ * The compiler asks only for the permissions' list now; the other kinds are
+ * what an older voss recorded, the MCP registration, and sync.ts still
+ * takes them out of the files once no longer wanted.
+ */
+export type Merge =
+  | { kind: "json-key"; at: string[]; value: unknown }
+  | { kind: "json-list"; at: string[]; values: unknown[] }
+  | { kind: "json-lists"; lists: { at: string[]; values: unknown[] }[] }
+  | { kind: "toml-table"; table: string; body: string };
+
+/** Output path to text, sorted by path. */
+export type Outputs = Record<string, string>;
+/** What the compiler wants: whole files, and the parts of shared ones. */
+export interface Compiled { files: Outputs; merges: Record<string, Merge> }
+
+// ---- the compiler --------------------------------------------------------
+
+export interface CompileInput {
+  /** The words that reach the project, the first of every call: "voss baba". */
+  program: string;
+  /** Heads the instruction file; the program when absent. */
+  title?: string;
+  manifest: Manifest;
+}
+
+
+const byPath = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+const sorted = <T>(r: Record<string, T>) => Object.fromEntries(Object.entries(r).sort(([a], [b]) => byPath(a, b)));
+
+/** Every output of every enabled harness. */
+export function compile(input: CompileInput): Compiled {
+  const out: Outputs = {};
+  const merges: Record<string, Merge> = {};
+  const st = input.manifest.harness;
+  const systemSkills = skillsOf(input.manifest);
+  const put = (path: string, text: string) => {
+    if (path in out) throw new Error(`two skills render to ${path}`);
+    out[path] = text;
+  };
+  for (const h of harnesses) {
+    const hs = st[h];
+    if (!hs.enabled) continue;
+    out[files[h].instructions] = instructionFile(input);
+    for (const sk of systemSkills) {
+      put(`${files[h].skills}/${sk.name}/SKILL.md`, skillFile(input.program, sk, input.manifest));
+    }
+    // A golden interpretation stays in the manifest, for the trials its owner runs when they choose; it is not written
+    // beside the skill, so an agent reading the skill reads the skill, and nothing asks it to keep a suite in step.
+    if (h === "claude") {
+      // Voss's parts of the shared settings: the permissions, and one list per hook event, each entry by content beside anyone else's.
+      const lists: { at: string[]; values: unknown[] }[] = [];
+      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) {
+        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, []);
+        byEvent.get(hk.on)!.push(entry);
+      }
+      for (const [on, values] of byEvent) lists.push({ at: ["hooks", on], values });
+      if (lists.length === 1 && lists[0]!.at[0] === "permissions") merges[".claude/settings.json"] = { kind: "json-list", at: lists[0]!.at, values: lists[0]!.values };
+      else if (lists.length) merges[".claude/settings.json"] = { kind: "json-lists", lists };
+    }
+  }
+  return { files: sorted(out), merges: sorted(merges) };
+}
+
+const system = (s: string) => s.replaceAll("|", "\\|").replaceAll("\n", " ");
+
+/** JSON as one word of a POSIX shell: single-quoted. */
+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. */
+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. -->`,
+    `# ${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.",
+    "",
+    `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.`,
+    "",
+    `- 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.",
+  );
+  const first = Object.entries(m.actions).find(([, d]) => !VOSS.has(d.owner));
+  if (first) {
+    const [name, d] = first;
+    lines.push("", "For example, at the shell and by MCP:", "", "```", cliLine(prog, name, d.args), `call ${JSON.stringify({ name, args: exampleOf(d.args) })}`, "```");
+  }
+  const calls = Object.keys(m.actions).length + Object.keys(m.queries).length;
+  if (m.harness.table && calls) {
+    lines.push(
+      "",
+      "| Call | Kind | Of | What |",
+      "| --- | --- | --- | --- |",
+      ...Object.entries(m.actions).filter(([, d]) => !VOSS.has(d.owner)).map(([n, d]) => `| \`${prog} ${[n, ...usage(d.args, d.positional)].join(" ")}\` | action | ${d.owner} | ${system(d.summary)} |`),
+      ...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(", ")}.`);
+  return lines.join("\n") + "\n";
+}
+
+function yamlString(s: string): string {
+  const plain = /^[A-Za-z0-9(][^\n]*$/.test(s) && !/: |:$| #|^(true|false|null|yes|no|on|off|~)$/i.test(s);
+  return plain ? s : JSON.stringify(s);
+}
+
+/** A skill: frontmatter, the body, and the calls it uses, each as a CLI line with an example and its summary. */
+function skillFile(prog: string, sk: SkillManifest, m: Manifest): string {
+  const lines = ["---", `name: ${sk.name}`, `description: ${yamlString(sk.description)}`, "---", "", sk.body.trim()];
+  if (sk.uses.length > 0) {
+    lines.push("", "## Calls", "");
+    for (const u of new Set(sk.uses)) {
+      const d = m.actions[u] ?? m.queries[u]!;
+      lines.push(`- \`${cliLine(prog, u, d.args)}\`: ${d.summary || `${u in m.actions ? "action" : "query"} of ${d.owner}`}`);
+    }
+    lines.push("", `Every answer is one line of JSON; \`${prog} NAME --schema\` gives a call's schemas.`);
+  }
+  return lines.join("\n") + "\n";
+}

package/src/promptware/define.ts

@@ -0,0 +1,16 @@
+// What a baba tells agent harnesses, as data: its promptware rendered into
+// the manifest; the kernel renders the files from it.
+import type { Manifest } from "../ecs/baba.ts";
+
+/** One skill as rendered: plain data, the actions and queries it uses by name. */
+export interface SkillManifest { name: string; description: string; body: string; uses: 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 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 ?? [])] });
+  }
+  return out;
+}

package/src/promptware/disk.ts

@@ -0,0 +1,72 @@
+// 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
+// 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";
+import type { Manifest } from "../ecs/baba.ts";
+import { compile, type CompileInput } from "./compile.ts";
+import { plan, apply, report, type Files, type Plan, type Report, type Seen, type Status } from "./sync.ts";
+
+/** The project's files through Bun: a symlink at a path, or at a directory below the root, holds it. */
+export function diskFiles(root: string): Files {
+  return {
+    look: (path) => look(root, path),
+    write: (path, text) => writeAtomic(join(root, path), text),
+    remove: (path) => rm(join(root, path), { force: true }),
+    prune: (path) => rmdir(join(root, path)).catch(() => {}),
+  };
+}
+
+async function look(root: string, path: string): Promise<Seen> {
+  const parts = path.split("/");
+  for (let i = 1; i <= parts.length; i++) {
+    const sub = parts.slice(0, i).join("/");
+    let st;
+    try { st = await lstat(join(root, sub)); } catch { return { kind: "absent" }; }
+    if (st.isSymbolicLink()) return { kind: "blocked", reason: `symlink at ${sub}` };
+    if (i < parts.length && !st.isDirectory()) return { kind: "blocked", reason: `${sub} is not a directory` };
+    if (i === parts.length && !st.isFile()) return { kind: "blocked", reason: "not a regular file" };
+  }
+  return { kind: "file", text: await Bun.file(join(root, path)).text() };
+}
+
+async function writeAtomic(path: string, text: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = join(dirname(path), `.promptware-${crypto.randomUUID()}`);
+  try {
+    await Bun.write(tmp, text);
+    await rename(tmp, path);
+  } catch (e) {
+    await rm(tmp, { force: true });
+    throw e;
+  }
+}
+
+/** 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 };
+}
+
+/** Compiles and plans against the project at root. Writes nothing. */
+export async function planProject(root: string, input: CompileInput): Promise<Plan> {
+  return plan(diskFiles(root), compile(input), root);
+}
+
+/** Compiles and applies. */
+export async function syncProject(root: string, input: CompileInput): Promise<Report> {
+  return apply(await planProject(root, input));
+}
+
+/** One output as compiled, whether or not it is held, with its status. */
+export async function outputOf(root: string, input: CompileInput, path: string): Promise<{ path: string; status: Status; text: string }> {
+  const p = await planProject(root, input);
+  const text = p.wanted[path];
+  if (text === undefined) {
+    const e = p.entries.find((x) => x.path === path);
+    if (e) return { path, status: e.status, text: await Bun.file(join(root, path)).text().catch(() => "") };
+    throw new Error(`not an output of this project: ${path}; outputs: ${p.entries.map((x) => x.path).join(", ")}`);
+  }
+  return { path, status: p.entries.find((e) => e.path === path)!.status, text };
+}
+
+export { report };

package/src/promptware/markdown.d.ts

@@ -0,0 +1,6 @@
+// Markdown imported as text: `import guide from "./guide.md" with { type: "text" }`.
+// Bun inlines the file; this tells the checker it is a string.
+declare module "*.md" {
+  const text: string;
+  export default text;
+}