babavoss 0.13.1 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babavoss",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "license": "Apache-2.0",
   "repository": "github:alanremarc/babavoss",
   "homepage": "https://babavoss.org",

package/src/agents/compile.ts

@@ -131,25 +131,32 @@ 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 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.
- */
+/** 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 skills = skillsOf(m).map((sk) => sk.name);
   const lines = [
     `<!-- 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}`,
-    "", "## 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.",
+  ];
+  const context = m.instructions.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.",
     "",
-    `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(", ")}.`,
+    `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.`,
     "",
-    `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.`,
-  ];
+    `- 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;
@@ -165,8 +172,9 @@ 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)} |`),
     );
   }
-  const context = m.instructions.context?.trim();
-  if (context) lines.push("", context);
+  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/generated/build.ts

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