babavoss 0.12.6 → 0.13.1

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

@@ -2,9 +2,9 @@ export const prompt = { kind: "skill", name: "add-a-desktop", description: "Give
 
 # Add a desktop
 
-Every baba runs voss's shell: the desktop system, which voss adds to every baba as it adds `maker` and `promptware`, over the apps the baba declares in `baba({ apps })`. The interface gives each app its component; the page is voss's. Three nouns and one verb: a **app** is a kind the baba registers; a **window** is one instance of it in a session, at a path; the **session** shows one window, or nothing. The verb is `desktop-open`: it brings the window at that path to the front, else the app's current window, else makes one; asked for a `fresh` window, an app declared `many` gets another, any other app gives the one it has. The launcher, a link in an app, the page's address, the CLI and another system's ask all go through it.
+Every baba runs voss's shell: the desktop system, which voss adds to every baba as it adds `maker` and `agents`, over the apps the baba declares in `baba({ apps })`. The interface gives each app its component; the page is voss's. Three nouns and one verb: a **app** is a kind the baba registers; a **window** is one instance of it in a session, at a path; the **session** shows one window, or nothing. The verb is `desktop-open`: it brings the window at that path to the front, else the app's current window, else makes one; asked for a `fresh` window, an app declared `many` gets another, any other app gives the one it has. The launcher, a link in an app, the page's address, the CLI and another system's ask all go through it.
 
-The page is a bar over one app. At the bar's far left the mark, the two eyes, opens the launcher; then a pill per open window, its icon at the left and the one in front filled; pointing at a pill turns its icon into the × that closes it, and a middle click closes it too, as it closes a browser tab; closing the one in front brings the pill to its left forward, else the one to its right. The launcher is the page's, not the state's: it shows while its search has focus, and while nothing is in front, since there is nothing else to show. The mark or Cmd/Ctrl K gives the search focus; a click on the launcher's empty space keeps it; choosing a row, Escape or the mark again takes it, and the launcher goes. It covers the page and changes nothing beneath: the bar's row becomes the search, and below it one column of rows, a palette: the icon, beginning where the search begins, then the label; what is open first, then every app under its group. One dot under the mark says which row is chosen, by the keys or the pointer, and glides between them. Typing ranks both by the words, a word at the start of a name first, and drops the groups. An app's row opens a fresh window of it, or brings the one it has to the front; a window's row brings it to the front, and pointing at it turns its icon into its ×. A browser tab shows one window at a time: a pill on the bar brings an open one to the front, the mark then a row opens another. Below the apps, under Sessions, the tab's other sessions and New session. A page inside a baba is that baba only; the last row, Leave, and the `voss` link before the title on the bar go back to the picker, voss's root page, which has no state: it lists the babas voss knows, one inside another under its parent, and New baba, the wizard that makes a baba in a folder or remembers one already there.
+The page is a bar of tabs over one app, nothing else on it. At the bar's far left the mark, the two eyes and the baba's name, is the launcher's tab, a pill like the others, which never closes: pointing at it turns its eyes into the way out, which leaves the baba for voss's picker and keeps the session to come back to; then a pill per open window, its icon at the left and the one in front filled; pointing at a pill turns its icon into the × that closes it, and a middle click closes it too, as it closes a browser tab; closing the one in front brings the pill to its left forward, else the one to its right. The launcher is the page's, not the state's, and shows two ways. The mark chooses the launcher's tab, a place: it takes the app's place, the mark filled, at the baba's own address, `/NAME/`, so Back returns to the app it was chosen over; it is also all there is while nothing is in front. Cmd/Ctrl P opens it quick, over the app in front, which stays its tab and shows dimmed behind, the address untouched; Escape, Cmd/Ctrl P again or a press around it goes back to the app as it was, focus included. Choosing a row or a pill on the bar leaves either; Escape in the tab goes back to the app it was chosen over; Cmd/Ctrl or a middle click on the mark opens the launcher in a new browser tab. Either way it changes nothing beneath, the pills staying on the bar: a palette in the middle of the page, the search, then one column of rows, each the icon then the label, the chosen one filled: every app under its group; what is open is on the bar, not here. Typing ranks them by the words, a word at the start of a name first, and drops the groups. An app's row opens a fresh window of it, or brings the one it has to the front. A browser tab shows one window at a time: a pill on the bar, or Cmd/Ctrl J and K, the tab to the left and to the right, the mark's among them, bring an open one to the front; the launcher opens another. Below the apps, under Sessions, the tab's other sessions and New session. A page inside a baba is that baba only; the launcher's last row, Leave, goes back to the picker, voss's root page, which has no state: the Baba Voss lockup and voss's version over the babas voss knows, one inside another under its parent. A folder is added by its path, typed with completion or browsed, and forgotten with its ×, its files kept, with a moment to undo. voss requires some properties of every baba, for now its name; a folder whose baba lacks one, or that has no baba yet, is listed to be set up and does not run, and opening it opens the setup wizard at `/?setup=FOLDER`, a card of steps, one per property missing, then the one that writes them, making its `.baba` when there is none; then it opens as any other. A folder with a baba that has them all just joins the list.
 
 ```ts
 // .baba/index.ts: the apps, as data, in launcher order
@@ -30,7 +30,7 @@ import { Tasks } from "./apps/tasks.tsx";
 export default compose<typeof baba>({ apps: { tasks: Tasks } });
 ```
 
-An app missing from `compose`, or a component for an app the baba does not declare, is a type error. After the baba's apps come voss's own, under Voss: `maker` the specs run live, `state` the entities and resources, `contract` the actions and queries as forms, `promptware` the know-how, `settings` the theme. A baba never declares them; its interface may give one a component of its own to draw it otherwise, `compose<typeof baba>({ apps: { …, promptware: Mine } })`. A baba that declares no apps has one, `view`, which draws its interface whole. A baba whose interface fails to build or load still has its shell: its apps say why, voss's work. The old addresses, `/NAME/run`, `/inspect`, `/proofs`, open the app they became, unless the baba has an app by that name. The old form, `compose({ shell })`, still loads for one release, in the `view` app; a baba cannot declare apps and keep a desktop system of its own.
+An app missing from `compose`, or a component for an app the baba does not declare, is a type error. After the baba's apps come voss's own, under Voss: `maker` the specs run live, `state` the entities and resources, `contract` the actions and queries as forms, `agentic instructions` the know-how, `settings` the theme. A baba never declares them; its interface may give one a component of its own to draw it otherwise, `compose<typeof baba>({ apps: { …, agentic instructions: Mine } })`. A baba that declares no apps has one, `view`, which draws its interface whole. A baba whose interface fails to build or load still has its shell: its apps say why, voss's work. The old addresses, `/NAME/run`, `/inspect`, `/proofs`, open the app they became, unless the baba has an app by that name. The old form, `compose({ shell })`, still loads for one release, in the `view` app; a baba cannot declare apps and keep a desktop system of its own.
 
 An app's component receives `AppProps`: `{ session, window, path, route, params, active, memory, navigate, open, setTitle, remember }`. It never names an action: `navigate(path)` moves its own window, `open(app, path)` opens any app by the one rule, `setTitle(title)` names its window after what it shows, the pill's tooltip, `remember(key, value)` keeps a filter, a selection or a fold on its window, in the state, and `memory` reads it back. Windows stay mounted when hidden. A path begins with one `/`.
 
@@ -56,7 +56,7 @@ An app's `systems` names the systems it shows, so the Maker offers it as a view
 - `desktopWindow`, one per instance, in the order opened: its session, its app, its path, its title, its `memory`.
 - `desktopSession`, one per session: the selected window and when it was last touched. A browser tab owns one: on load it takes the address's `?session=KEY`, else the one the tab had (its `sessionStorage`), else enters a new one, which the system names after a tree, `oak`, `ash`, `elm`. A link with `?session=KEY` joins a session, and two tabs on one key move together; the launcher lists the other sessions, to go to one or end it, and New session. A session with nothing open goes after a day untouched. The launcher and what is typed into it are the page's.
 - A call that names no session reaches the current session, the one last touched: a tab touches its session on load and on focus, so `voss baba desktop-open '{"app":"tasks","path":"/task/7"}'` lands in the tab last used. Name one to reach another.
-- `desktopSettings`, one resource: the theme, the same on every page.
+- `desktopSettings`, one resource: the baba's own theme, which its frames in the Maker show; voss's pages wear the person's, from voss's settings.
 - Its contract, the same at the CLI, by MCP and in the page: `desktop-open`, `desktop-select`, `desktop-close`, `desktop-title`, `desktop-remember`, `desktop-enter`, `desktop-leave`, `desktop-settings` and the query `desktop-state`, which also lists every session. Read them with `voss baba`.
 
 ## Opening an app from a system
@@ -91,10 +91,10 @@ The ask takes `{ app, path?, fresh?, session? }`; an unknown app, a bad path or
 
 ## Rules
 
-- The address records the window in front, `/NAME/APP/PATH`, with Back and Forward; opening the launcher from the page leaves no entry; pass `address={false}` for a desktop embedded in another page.
+- The address records the window in front, `/NAME/APP/PATH`, with Back and Forward; the launcher's tab is an entry, `/NAME/`, and the quick launcher none; pass `address={false}` for a desktop embedded in another page.
 - A baba's name is the first segment of its address, so `api`, `assets`, `view` and `ws`, the page's own, are not names a baba can take.
-- Cmd/Ctrl K opens the launcher; Cmd/Ctrl W or the front pill's × closes the window in front; Escape clears the search, then leaves the launcher; arrows move down the rows, Enter opens. The theme is `desktop-settings`, with no control in the launcher yet.
-- The shell inherits voss's theme tokens; the session's theme applies inside the desktop.
+- Cmd/Ctrl P opens the quick launcher, the mark the launcher's tab; Cmd/Ctrl J and K go to the tab on the left and on the right; the front pill's ×, or a middle click on a pill, closes its window, and Close tab, which has no key until one is given it, since Cmd/Ctrl W closes the browser tab or the app around the page; Escape clears the search, then leaves the launcher; arrows move down the rows, Enter opens. These are defaults, and the keys are the person's, not a baba's: voss keeps them in its own settings, `settings.json` in its root, with the theme every page of every baba wears; `POST /api/settings` with `keys`, `{"launcher": "Mod+Shift+L"}`, remaps one, `Mod` being Cmd on a Mac and Ctrl elsewhere, `null` gives the default back, and a binding two commands would share is refused; the launcher's arrows, Enter and Escape are fixed. voss's Settings app shows them under two levels: the baba's first, Profile at `/`, its name, which renamed moves its address and opens it again there; then voss's, Appearance at `/appearance`, Keyboard at `/keyboard` and About at `/about`, which voss runs, its runtime and the paths it keeps. `desktop-settings` sets a baba's own theme, which only its frames in the Maker show.
+- The shell inherits voss's theme tokens; voss's settings choose light, dark or the system's for every page.
 - Reload keeps compatible desktop state and drops apps no longer declared; stopping the baba ends it with the rest of the state.
 - Prove an app's navigation like any system: a scenario that fires `desktop-open` and checks `desktop-state`.
 - The old spellings, `surfaces` and `SurfaceProps`, still work for one release; `dock` in the options is accepted and ignored.

package/src/guide/index.ts

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

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

@@ -164,11 +164,11 @@ p.query("pond", {
 - A fire may carry an idempotency key (`--key K` at the shell, `key` by MCP): the baba remembers the answer for a day, so a retry answers the same without running again. Make actions safe to repeat anyway.
 - `w.transaction(fn)` gives any code what an action has: a throw undoes every write inside it.
 - Validation is at the boundary: args and results are checked; your writes inside are trusted, so write what the schema says.
-- Reserved names, not for actions or queries: start, stop, status, state, follow, run, raw, secret, help, mcp, check, install, add-system, serve, promptware, init, babas, service, gui.
+- Reserved names, not for actions or queries: start, stop, status, state, follow, run, raw, secret, help, mcp, check, install, add-system, serve, agents, init, babas, service, gui.
 
 ## The baba
 
-`.baba/index.ts` lists every system, in the order their steps run: `baba({ systems: [tasks, pond], apps, promptware, harness, tick })`. A system that reads another goes after it, so it sees this round's writes.
+`.baba/index.ts` lists every system, in the order their steps run: `baba({ systems: [tasks, pond], apps, harness, tick })`. A system that reads another goes after it, so it sees this round's writes.
 
 ## Schemas
 
@@ -179,5 +179,5 @@ p.query("pond", {
 1. Every component and resource the system writes is in its `model`; every other system it reads or asks of is in its `reads`, and none of those reads it back.
 2. Steps are ordered on purpose; the hot ones use `w.each`; the reactive ones use change terms.
 3. Every piece is made with this system's `p` and listed once; actions answer data; queries change nothing; names are flat and not reserved.
-4. The baba's promptware says in a line what the system is for (see `write-promptware`); its `spec.ts` beside it proves it, a scenario for each thing it must do (see `spec-a-system`); an app in `.baba/apps/` that names it in `systems` shows it, live and in the Maker (see `compose-an-interface`).
+4. The baba's context, an `.mdx` under `.baba/agents/`, says in a line what the system is for (see `write-agentic-instructions`); its `spec.ts` beside it proves it, a scenario for each thing it must do (see `spec-a-system`); an app in `.baba/apps/` that names it in `systems` shows it, live and in the Maker (see `compose-an-interface`).
 5. `bun test` (the runner `.baba/spec.test.ts` proves every spec) and the type-check are green; the running baba reloads on save and `voss baba` shows the new contract.

package/src/guide/{write-promptware.mdx → write-agentic-instructions.mdx}

@@ -1,10 +1,10 @@
-export const prompt = { kind: "skill", name: "write-promptware",
-  description: "Write or change what a baba tells agents: its context, skills and hooks, as code under .baba/promptware/. Use before writing any promptware, in any baba, including skills like this one.",
+export const prompt = { kind: "skill", name: "write-agentic-instructions",
+  description: "Write or change what a baba tells agents: its context, skills and hooks, each an .mdx file under .baba/agents/. Use before writing any agentic instructions, in any baba, including skills like this one.",
 };
 
-# Write promptware
+# Write agentic instructions
 
-A promptware file an agent can act on at first read: one trigger, steps in order, one example, claims it can check, rules it cannot break.
+An instruction file an agent can act on at first read: one trigger, steps in order, one example, claims it can check, rules it cannot break. The agentic instructions of a baba are the `.mdx` files under `.baba/agents/`; voss reads every one of them, in name order, and there is no list to keep.
 
 ## When
 
@@ -14,17 +14,17 @@ A promptware file an agent can act on at first read: one trigger, steps in order
 
 ## Do
 
-1. Pick the kind. `context`: the baba's section of the context file, read by every session; what the project is, how it is worked on, its rules; one per baba, in `promptware/index.ts`. `skill`: a file read when its description fits; how to do one thing; one `.mdx` per skill beside it. `hook`: a harness moment handed to an action; what the harness may not do.
+1. Pick the kind. `context`: the baba's section of the context file, read by every session; what the project is, how it is worked on, its rules; one per baba, `export const prompt = { kind: "context" }`. `skill`: a file read when its description fits; how to do one thing; `export const prompt = { kind: "skill", name, description, uses }`, one `.mdx` per skill. A hook, a harness moment handed to an action, is `hooks: [{ on, match, action }]` on the context's `prompt`.
 2. Write the description as the trigger: `Use when …`, the situations, the files, the words an agent would be thinking. The description decides whether the skill is read; the body decides whether it works.
-3. Write Markdown directly in an MDX file. Export a `prompt` metadata object with `kind: "skill"`, name, description, and optional uses/eval; for context use `kind: "context"`. An `eval` is the owner's golden interpretation, run on demand from the Trials app to score readers of the text; it gates nothing. Changing a skill, leave its eval alone unless the owner asks. Import contract components and embed them as JSX. MDX expressions are JavaScript; keep typed helpers in imported .ts files. Existing TSX and `md` templates remain supported.
+3. Write Markdown in the `.mdx` file; `import { Call } from "babavoss/instructions"` for the tags below. Export the `prompt` metadata object with `kind: "skill"`, name, description, and optional uses/eval; for the context, `kind: "context"` with optional hooks/eval. An `eval` is the owner's golden interpretation, run on demand from the Trials app to score readers of the text; it gates nothing. Changing a skill, leave its eval alone unless the owner asks. Import contract components and embed them as JSX. MDX expressions are JavaScript; keep typed helpers in imported .ts files. Existing TSX and `md` templates remain supported.
 4. Reference the contract, never restate it: `<Call of="feed" />` for a call with its example and summary, `<Calls of="pond" />` for a system's calls, `<Schema of>` for args, `<Usage of>` for the shell's spelling, `<See skills={[…]} />` for the skills to read next. A name that does not exist refuses to load.
-5. List the file in `promptware/index.ts`, which `baba({ systems, promptware, harness })` declares; `harness` says which harnesses get the files and Claude Code's permissions.
+5. Save it under `.baba/agents/`: voss finds it there. `baba({ harness })` says which harnesses get the files and Claude Code's permissions.
 6. Read the output: `CLAUDE.md` and `.claude/skills/NAME/SKILL.md` after the sync. Cut every sentence that does not change what an agent does.
 
 ## Example
 
 ```mdx
-import { Call, See } from "babavoss/prompt";
+import { Call, See } from "babavoss/instructions";
 
 export const prompt = {
   kind: "skill",
@@ -48,22 +48,15 @@ Do not add or remove fish with raw writes.
 <See skills={["write-a-system"]} />
 ```
 
-```ts
-// .baba/promptware/index.ts
-import { context, hook, md } from "babavoss/prompt";
-import feedThePond from "./feed-the-pond.mdx";
+```mdx
+{/* .baba/agents/context.mdx */}
+export const prompt = { kind: "context", hooks: [{ on: "PreToolUse", match: "Bash", action: "guard-raw" }] };
 
-export default [
-  context(md\`
-    The demo: an example baba. It shows what a baba is; it is not a product.
+The demo: an example baba. It shows what a baba is; it is not a product.
 
-    ## Rules
+## Rules
 
-    - Keep each system small and proved by its scenarios.
-  \`),
-  feedThePond,
-  hook({ on: "PreToolUse", match: "Bash", action: "guard-raw" }),
-];
+- Keep each system small and proved by its scenarios.
 ```
 
 ## Check
@@ -76,15 +69,15 @@ export default [
 
 ## Never
 
-- Read the state in promptware: it is static, rendered from the manifest once per generation.
+- Read the state in agentic instructions: it is static, rendered from the manifest once per generation.
 - Explain why in a step; put reasons in the context if they are needed at all.
 - Write `simply`, `just`, `easily`, `should`, or a synonym for a term that has one name: system, app, spec, step, state, round, action, query, effect, source, mirror, context, skill, hook, baba, voss.
-- Edit `CLAUDE.md`, `AGENTS.md`, a `SKILL.md` or `.claude/settings.local.json`: they are outputs. Git keeps none of them: voss writes its lines of the project's `.gitignore`, and a checkout makes its own with `voss baba promptware sync`.
+- Edit `CLAUDE.md`, `AGENTS.md`, a `SKILL.md` or `.claude/settings.local.json`: they are outputs. Git keeps none of them: voss writes its lines of the project's `.gitignore`, and a checkout makes its own with `voss baba agents sync`.
 - Commit an output. A hand-written `.claude/settings.json` beside the made `settings.local.json` is the place for what the repository itself tells Claude Code, a `SessionStart` hook that runs the sync, say.
 
 ## Hooks
 
-A hook hands a harness moment to an action: `hook({ on, match?, action, strict? })` with `on` one of PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, SessionStart, PreCompact, Notification, and `match` a tool-name regex for the two tool events. The action takes `hookArgs(EVENT)` and answers `hookResult()`: `{ decision: "block", reason }` stops the tool call and the agent reads the reason; `{ context }` is told to the agent; `{}` lets it through. Voss compiles it into `.claude/settings.local.json` as `voss baba ACTION @- --hook EVENT`; a baba that is down lets through with a note, `strict: true` blocks. Prove a hook with a scenario: `fire` the action with an event, `check` the decision.
+A hook hands a harness moment to an action: `{ on, match?, action, strict? }` in the context's `hooks`, with `on` one of PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, SessionStart, PreCompact, Notification, and `match` a tool-name regex for the two tool events. The action takes `hookArgs(EVENT)` and answers `hookResult()`: `{ decision: "block", reason }` stops the tool call and the agent reads the reason; `{ context }` is told to the agent; `{}` lets it through. Voss compiles it into `.claude/settings.local.json` as `voss baba ACTION @- --hook EVENT`; a baba that is down lets through with a note, `strict: true` blocks. Prove a hook with a scenario: `fire` the action with an event, `check` the decision.
 
 ## Voice
 

package/src/http/server.ts

@@ -7,6 +7,10 @@ import { mkdir, writeFile, chmod } from "node:fs/promises";
 import { dirname } from "node:path";
 import { readFileSync, unlinkSync } from "node:fs";
 import { openProject, exists } from "../baba/project.ts";
+import { requirementError, requirements, type RequirementValues } from "../baba/requirements.ts";
+import { setupOf, writeRequirements } from "../baba/setup.ts";
+import { themes } from "../desktop/index.ts";
+import { applyKeyChanges } from "../desktop/keys.ts";
 import { init } from "../baba/init.ts";
 import { homedir } from "node:os";
 import { readdir } from "node:fs/promises";
@@ -15,12 +19,13 @@ import type { BuildOutput } from "../build/builder.ts";
 import type { Registry } from "../baba/registry.ts";
 import { page, buildGui } from "../gui/index.ts";
 import type { Transport } from "../transport/transport.ts";
-import type { ViewIndex, Asset, Failure, FromServer, ProjectEntry, ToServer, Refreshed, Browsed } from "../server/messages.ts";
+import type { ViewIndex, Asset, Failure, FromServer, ProjectEntry, PendingEntry, ToServer, Refreshed, Browsed, VossSettings } from "../server/messages.ts";
 import { connectFor, builderFor, serverSpawn } from "../kernel/children.ts";
 import { dev, framework } from "../kernel/where.ts";
 import { takeLock, LockError } from "../kernel/lock.ts";
 import { thisBuild, buildOf, buildName, tellApart, type Build } from "../kernel/build.ts";
-import type { Voss } from "../server/messages.ts";
+import type { About, Voss } from "../server/messages.ts";
+import { agentPath, logPath, unitPath } from "../shell/service.ts";
 import { stat } from "node:fs/promises";
 
 export type ServerTransport = Transport<ToServer, FromServer>;
@@ -101,6 +106,35 @@ function failure(err: unknown): Failure {
   return { ok: false, code: err instanceof NodeError ? err.code : "failed", message: err instanceof Error ? err.message : String(err) };
 }
 
+/** voss's settings, the person's, as ROOT/settings.json keeps them: what does not read, or no longer fits, is left out and the default stands. */
+async function readSettings(path: string, log: (l: string) => void): Promise<VossSettings> {
+  const out: VossSettings = { theme: "system" };
+  try {
+    const f = Bun.file(path);
+    if (!(await f.exists())) return out;
+    const j = await f.json() as { theme?: unknown; keys?: unknown };
+    if (themes.includes(j.theme as never)) out.theme = j.theme as VossSettings["theme"];
+    if (j.keys && typeof j.keys === "object") {
+      try { const keys = applyKeyChanges(undefined, j.keys as Record<string, string>); if (Object.keys(keys).length) out.keys = keys; }
+      catch (err) { log(`${path}: keys left out: ${err instanceof Error ? err.message : String(err)}`); }
+    }
+  } catch (err) { log(`${path}: ${err instanceof Error ? err.message : String(err)}; the defaults stand`); }
+  return out;
+}
+
+/** Where this voss is and what it runs on, as the settings' About page shows it. */
+async function aboutOf(root: string): Promise<About> {
+  const home = homedir();
+  const file = process.platform === "darwin" ? agentPath(home) : process.platform === "linux" ? unitPath(home) : null;
+  return {
+    started: new Date().toISOString(),
+    runtime: { bun: Bun.version, platform: process.platform, arch: process.arch, executable: process.execPath },
+    framework, cli: process.argv[1] ?? "",
+    root, registry: join(root, "projects.json"), token: join(root, "http-token"),
+    service: file && await exists(file) ? { file, log: logPath(home) } : null,
+  };
+}
+
 /** Where a root's daemon says it listens: DIR/address, written on listen and removed on stop. */
 export const addressPath = (rootDir: string) => join(rootDir, "address");
 export interface Address { hostname: string; port: number; pid: number }
@@ -124,10 +158,14 @@ export async function serve(reg: Registry, hostname: string, port: number, log =
   }
 
   // The registry is the list of what runs: a refresh opens what it gained and retires what it lost, one at a time.
+  // A folder that lacks something voss requires is kept and not run, to be set up; one that has it all and fails is kept with its error.
   let refreshing: Promise<unknown> = Promise.resolve();
+  let pending: Omit<PendingEntry, "parent">[] = [];
   const reread = async (): Promise<Refreshed> => {
     const dirs = (await reg.list()).map((d) => resolve(d));
     const errors: Refreshed["errors"] = [];
+    // Gathered here and kept whole at the end: a page that asks meanwhile gets the last list, never a half one.
+    const waiting: typeof pending = [];
     for (const [name, n] of nodes) {
       if (dirs.includes(n.project.dir)) continue;
       nodes.delete(name);
@@ -137,6 +175,12 @@ export async function serve(reg: Registry, hostname: string, port: number, log =
     for (const dir of dirs) {
       if ([...nodes.values()].some((n) => n.project.dir === dir)) continue;
       try {
+        if (!(await exists(dir))) throw new Error(`${dir} is gone`);
+        const setup = await setupOf(dir);
+        if (setup.missing.length) { waiting.push({ dir, baba: setup.baba, missing: setup.missing, error: null }); continue; }
+        // A name another running baba has is as good as none: the folder waits for one of its own, which its wizard asks for.
+        const clash = setup.values.name !== undefined ? nodes.get(setup.values.name) : undefined;
+        if (clash && clash.project.dir !== dir) { log(`${dir}: its name ${setup.values.name} is ${clash.project.dir}'s; it waits for another`); waiting.push({ dir, baba: true, missing: ["name"], error: null }); continue; }
         if (voss.stale) throw new Error(`not opened: voss ${buildName(voss.installed!)} is installed and this one is stale; restart to update`);
         const p = await openProject(dir);
         const other = nodes.get(p.name);
@@ -150,16 +194,20 @@ export async function serve(reg: Registry, hostname: string, port: number, log =
         const error = err instanceof Error ? err.message : String(err);
         log(`${dir}: ${error}`);
         errors.push({ dir, error });
+        waiting.push({ dir, baba: await exists(join(dir, ".baba")), missing: [], error });
       }
     }
-    return { projects: listing(), errors };
+    pending = waiting;
+    return { projects: listing(), pending: pendingListing(), errors };
   };
-  const refresh = (): Promise<Refreshed> => { const r = refreshing.then(reread); refreshing = r.catch(() => {}); return r; };
+  /** Runs after whatever changes the running babas is already running, and before the next: refreshes, and the rename that retires a baba to open it again. */
+  const queued = <T,>(fn: () => Promise<T>): Promise<T> => { const r = refreshing.then(fn); refreshing = r.catch(() => {}); return r; };
+  const refresh = (): Promise<Refreshed> => queued(reread);
   const stopNodes = async () => { await refreshing; await Promise.all([...nodes.values()].map((n) => n.stop())); };
 
   // Which voss this is. A newer package installed over it makes this one stale: it serves what it has,
   // loads no change and opens no project, until the restart brings the new one up.
-  const voss: Voss = { ...thisBuild, pid: process.pid, kept: options.kept ?? false, stale: false, installed: null };
+  const voss: Voss = { ...thisBuild, pid: process.pid, kept: options.kept ?? false, stale: false, installed: null, about: await aboutOf(reg.dir) };
   const stale = (b: Build) => {
     voss.stale = true;
     voss.installed = { version: b.version, sha: b.sha, at: b.at };
@@ -198,6 +246,9 @@ export async function serve(reg: Registry, hostname: string, port: number, log =
   if (!built) { built = join(reg.dir, "gui"); await buildGui(built); }
   const assets = await readTree(built);
   const token = await pageToken(reg.dir, log);
+  const settingsPath = join(reg.dir, "settings.json");
+  let settings = await readSettings(settingsPath, log);
+  let settingsTurn: Promise<void> = Promise.resolve();
   function listing(): ProjectEntry[] {
     const all = [...nodes.values()];
     const parentOf = (n: Node) => all
@@ -205,6 +256,29 @@ export async function serve(reg: Registry, hostname: string, port: number, log =
       .sort((a, b) => b.project.dir.length - a.project.dir.length)[0]?.name ?? null;
     return all.map((n) => ({ name: n.name, title: n.project.title, dir: n.project.dir, parent: parentOf(n) }));
   }
+  /** The folders remembered and not run, each under the nearest running baba that holds it. */
+  function pendingListing(): PendingEntry[] {
+    const all = [...nodes.values()];
+    return pending.map((x) => ({ ...x, parent: all.filter((o) => x.dir.startsWith(o.project.dir + "/")).sort((a, b) => b.project.dir.length - a.project.dir.length)[0]?.name ?? null }));
+  }
+  /** Sets a folder's required properties: refused when one will not do, its .baba made first when there is none. `fresh` asks for a new .baba and refuses one already there. */
+  async function setUp(dir: string, values: RequirementValues, title: string | undefined, fresh: boolean): Promise<void> {
+    const now = await setupOf(dir);
+    if (fresh && now.baba) throw new NodeError("failed", `${dir} already has a .baba`);
+    const taken = [...nodes.values()].filter((n) => n.project.dir !== dir).map((n) => n.name);
+    // Each value as sent, else, for one the folder lacks, the suggestion, not the value that made it lacking; else the one it has.
+    const merged = Object.fromEntries(requirements.map((r) => [r.key, values[r.key] ?? (now.missing.includes(r.key) ? now.suggested[r.key] : now.values[r.key])])) as RequirementValues;
+    // What is written is what is checked: every requirement the folder lacks, and every one asked for, each as it will be written.
+    const set = requirements.map((r) => r.key).filter((k) => now.missing.includes(k) || values[k] !== undefined);
+    for (const k of set) {
+      const why = requirementError(k, merged[k] ?? "", taken);
+      if (why) throw new NodeError("args", `${k}: ${why}`);
+    }
+    if (!now.baba) {
+      if (!options.init) throw new NodeError("failed", "this voss cannot make a baba; `voss init` does");
+      await init(dir, { name: merged.name, title, framework: options.init.framework, extra: options.init.extra, install: options.init.install });
+    } else if (set.length) await writeRequirements(dir, Object.fromEntries(set.map((k) => [k, merged[k]])));
+  }
   const pagesOf = () => {
     const pages: Record<string, string> = { "": withToken(page(null), token) };
     for (const name of nodes.keys()) pages[name] = withToken(page(name), token);
@@ -232,7 +306,7 @@ export async function serve(reg: Registry, hostname: string, port: number, log =
     if (m.type === "refresh") {
       try {
         const value = await refresh();
-        child?.send({ type: "projects", projects: value.projects, pages: pagesOf() });
+        child?.send({ type: "projects", projects: value.projects, pending: value.pending, pages: pagesOf() });
         return { type: "refresh-answer", id: m.id, ok: true, value };
       } catch (err) { return { type: "refresh-answer", id: m.id, ...failure(err) }; }
     }
@@ -240,20 +314,69 @@ export async function serve(reg: Registry, hostname: string, port: number, log =
       try { return { type: "browse-answer", id: m.id, ok: true, value: await browse(m.path || homedir(), await reg.list()) }; }
       catch (err) { return { type: "browse-answer", id: m.id, ...failure(err) }; }
     }
-    if (m.type === "add") {
+    // voss's settings: changed whole, written, and the edge told; a theme not known, a key that is not one or that two commands would share, is refused.
+    if (m.type === "set-settings") {
+      // One change at a time, each over the last one written: two quick changes both stand.
+      const turn = settingsTurn;
+      let done!: () => void;
+      settingsTurn = new Promise((r) => { done = r; });
+      await turn;
+      try {
+        if (m.theme !== undefined && !themes.includes(m.theme)) throw new NodeError("args", `theme: one of ${themes.join(", ")}`);
+        let keys: VossSettings["keys"];
+        try { keys = m.keys ? applyKeyChanges(settings.keys, m.keys) : settings.keys; } catch (err) { throw new NodeError("args", err instanceof Error ? err.message : String(err)); }
+        const next: VossSettings = { theme: m.theme ?? settings.theme, ...(keys && Object.keys(keys).length ? { keys } : {}) };
+        await writeFile(settingsPath, JSON.stringify(next, null, 2) + "\n");
+        settings = next;
+        child?.send({ type: "settings", settings });
+        return { type: "settings-answer", id: m.id, ok: true, value: settings };
+      } catch (err) { return { type: "settings-answer", id: m.id, ...failure(err) }; }
+      finally { done(); }
+    }
+    // A rename writes the name into the baba's package.json and opens it again under it; its state is its folder's, and stays.
+    if (m.type === "rename") {
+      try {
+        // Retired in the queue that opens and retires babas, so no refresh under way reopens it while it stops; refused while voss is stale, which opens nothing.
+        const dir = await queued(async () => {
+          const n = nodes.get(m.name);
+          if (!n) throw new NodeError("nokey", `no baba ${m.name}`);
+          if (m.to === m.name) return n.project.dir;
+          if (voss.stale) throw new NodeError("failed", `not renamed: voss ${buildName(voss.installed!)} is installed and this one is stale; restart to update first`);
+          const why = requirementError("name", m.to, [...nodes.keys()].filter((k) => k !== m.name));
+          if (why) throw new NodeError("args", `name: ${why}`);
+          await writeRequirements(n.project.dir, { name: m.to });
+          nodes.delete(m.name);
+          await n.stop();
+          log(`${m.name}: renamed ${m.to}`);
+          return n.project.dir;
+        });
+        const value = await refresh();
+        child?.send({ type: "projects", projects: value.projects, pending: value.pending, pages: pagesOf() });
+        const failed = value.errors.find((e) => e.dir === dir);
+        if (failed) throw new NodeError("failed", failed.error);
+        return { type: "add-answer", id: m.id, ok: true, value: { ...value, name: value.projects.find((p) => p.dir === dir)?.name ?? null, dir } };
+      } catch (err) { return { type: "add-answer", id: m.id, ...failure(err) }; }
+    }
+    // Adding remembers a folder: its baba runs when it has what voss requires, else it waits to be set up. With `init`, its .baba is made first.
+    // Setting up writes the requirements, making the .baba when there is none; removing forgets the folder, and its files stay.
+    if (m.type === "add" || m.type === "setup" || m.type === "remove") {
       try {
         const dir = resolve(m.dir);
-        if (m.init) {
-          if (!options.init) throw new NodeError("failed", "this voss cannot make a baba; `voss init` does");
-          await init(dir, { name: m.name, title: m.title, framework: options.init.framework, extra: options.init.extra, install: options.init.install });
+        if (m.type === "remove") {
+          if (!(await reg.remove(dir))) throw new NodeError("nokey", `voss does not remember ${dir}`);
+        } else {
+          const st = await stat(dir).catch(() => null);
+          if (!st?.isDirectory()) throw new NodeError("args", `${dir} is not a folder`);
+          if (m.type === "setup" || m.init) await setUp(dir, m.type === "setup" ? m.values : { ...(m.name ? { name: m.name } : {}) }, m.type === "add" ? m.title : undefined, m.type === "add");
+          await reg.add(dir);
         }
-        const p = await openProject(dir);
-        await reg.add(p.dir);
         const value = await refresh();
-        child?.send({ type: "projects", projects: value.projects, pages: pagesOf() });
-        const own = value.errors.find((e) => e.dir === p.dir);
-        if (own) throw new NodeError("failed", own.error);
-        return { type: "add-answer", id: m.id, ok: true, value: { ...value, name: p.name, dir: p.dir } };
+        child?.send({ type: "projects", projects: value.projects, pending: value.pending, pages: pagesOf() });
+        const own = value.projects.find((p) => p.dir === dir);
+        // Made or set up, it has to run: a failure is the answer's.
+        const failed = value.errors.find((e) => e.dir === dir);
+        if (m.type !== "remove" && (m.type === "setup" || m.init) && failed) throw new NodeError("failed", failed.error);
+        return { type: "add-answer", id: m.id, ok: true, value: { ...value, name: own?.name ?? null, dir } };
       } catch (err) { return { type: "add-answer", id: m.id, ...failure(err) }; }
     }
     const n = nodes.get(m.name);
@@ -289,7 +412,7 @@ export async function serve(reg: Registry, hostname: string, port: number, log =
     });
     child.onMessage((m) => {
       if (m.type === "ready") {
-        child.send({ type: "serve", hostname, port, token, voss, projects: listing(), home: homedir(), pages: pagesOf(), assets });
+        child.send({ type: "serve", hostname, port, token, voss, projects: listing(), pending: pendingListing(), settings, home: homedir(), pages: pagesOf(), assets });
       } else if (m.type === "listening") {
         up = true;
         // The address goes next to the token, for the CLI to find the daemon by; it goes when the daemon does.

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

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

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

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

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

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

package/src/mcp/main.ts

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

package/src/mcp/tools.ts

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