tumwater 0.1.2 → 0.2.0

package/dist/src/inbox/prompt-commands.js

@@ -1,38 +1,58 @@
+// vocabulary: plain
 /** The CLI layer of `tumwater prompt` — the steering-prompt command: submit a prompt to the
  * director (default) or one role's queue, `--list` what is queued with per-loop position
  * numbering, or `--cancel <n>` a queued prompt by position. Split out of
- * operator/operator-commands.ts because this command is not a fleet-control marker: its
+ * operator/operator-commands.ts because this command is not a team-control marker: its
  * sibling commands there ride the operator-intent marker protocol, while this command drives
  * the durable per-loop queues (src/inbox/inbox.ts) through the inbox-cancel, inbox-edit, and
  * operator-intent helpers, each with its own broken-config policy — so the command lives
- * beside the queue module it drives. The fleet-side half — the dequeue and requeue a loop
+ * beside the queue module it drives. The team-side half — the dequeue and requeue a loop
  * performs — is inbox.ts and pending-prompt.ts. */
 import { fail, say, sayJson } from "../cli/cli-output.js";
-import fs from "node:fs";
 import path from "node:path";
 import { parsePromptArgs } from "../cli/cli-command-args.js";
-import { cancelListedPrompt, cancelRolePrompt, } from "./inbox-cancel.js";
-import { editListedPrompt, editRolePrompt, } from "./inbox-edit.js";
-import { listWideScope, promptPreview, queuedListRows, renderQueuedList } from "./inbox.js";
+import { cancelListedPrompt, cancelRolePrompt, resolveListedQueue, } from "./inbox-cancel.js";
+import { editListedPrompt, editQueuedFile, editRolePrompt, readQueuedPromptBody, } from "./inbox-edit.js";
+import { movePromptToTop } from "./inbox-top.js";
+import { editInEditor } from "../cli/cli-editor.js";
+import { listWideScope, queuedFileAtPosition, promptPreview, queuedListRows, renderQueuedList } from "./inbox.js";
 import { durationLabel } from "../cli/cli-args.js";
 import { knownRoleIds, knownRoleIdsCached, loadConfig } from "../config/config.js";
 import { errorMessage } from "../text/text.js";
-import { promptImageExtensionProblem, promptImageSizeProblem, promptImagesCountProblem, promptImagesProblem, } from "./inbox-attachments.js";
+import { readPromptImageFiles } from "./inbox-attachments.js";
 import { DIRECTOR_ROLE, unknownRoleMessage } from "../roles/roles.js";
 import { submitRolePromptAndWake } from "../operator/operator-intent.js";
+import { imagePromptGuidance } from "./inbox-submit.js";
+import { roleLabel } from "../roles/role-labels.js";
+import { canonicalRoleId } from "../roles/legacy-role-ids.js";
+/** Fail with the ambiguity or miss message of a list-wide position resolution, else return
+ * the resolved value narrowed. Shared by sayListedOutcome and the editor form so the wordings
+ * cannot drift. */
+function failQueueMiss(listed, position) {
+    if (isQueueMiss(listed)) {
+        if (listed.status === "ambiguous") {
+            fail(`position ${position} is in more than one role's inbox (${listed.roles.join(", ")}) — name one with --role <id>`);
+        }
+        // `queued` is the longest queue's length — the highest position any loop's numbering can
+        // reach — so a miss names it as the valid range when at least one loop holds a prompt.
+        const range = listed.queued > 0 ? ` — valid: 1-${listed.queued}` : "";
+        fail(`no prompt at position ${position} (longest inbox holds ${listed.queued})${range}`);
+    }
+    return listed;
+}
+/** Whether a list-wide outcome is one of the two miss shapes — the guard that narrows the
+ * miss fields (`roles`, `queued`) without a cast. */
+function isQueueMiss(listed) {
+    return listed.status === "ambiguous" || listed.status === "missing";
+}
 /** The shared tail of the list-wide cancel/edit branches: report an ambiguity (naming the
  * rival loops, with the `--role` escape hatch) or a miss (carrying the length of the longest
  * queue, the highest position numbering any loop can hold), else render the resolved outcome
  * through sayPromptOutcome. One helper so the
  * two verbs' handling of the miss shapes cannot drift. */
 function sayListedOutcome(listed, position) {
-    if (listed.status === "ambiguous") {
-        fail(`position ${position} is queued for more than one loop (${listed.roles.join(", ")}) — name one with --role <id>`);
-    }
-    if (listed.status === "missing") {
-        fail(`no prompt at position ${position} (longest queue holds ${listed.queued})`);
-    }
-    sayPromptOutcome(position, listed.role, listed.outcome, true);
+    const found = failQueueMiss(listed, position);
+    sayPromptOutcome(position, found.role, found.outcome, true);
 }
 /** Run one loop-targeted queue verb (cancelRolePrompt/editRolePrompt) for a `--role`-scoped
  * command: a thrown failure (a broken config, an unwritable queue) exits through fail with
@@ -55,77 +75,56 @@ function runRolePromptCommand(root, role, position, verb) {
  * command. One helper so the cancel and edit wordings cannot drift. */
 function sayPromptOutcome(position, role, outcome, labelRole) {
     if (outcome.status === "gone") {
-        say(`prompt ${position} is no longer queued — ${role} already took it`);
+        sayPromptGone(position, role);
         return;
     }
     // A resolved cancel carries the removed text; a resolved edit carries what it wrote.
     const text = outcome.status === "cancelled" ? outcome.text : outcome.newText;
     say(labelRole ? `${outcome.status} (${role}): ${promptPreview(text)}` : `${outcome.status}: ${promptPreview(text)}`);
 }
-/** Refuse an `--attach` path list from what the paths alone reveal, before any file is read:
- * the shared image-count cap first (so a glob that expanded past it is rejected without
- * reading or base64-encoding dozens of files), then each path's extension, regular-file
- * shape, and on-disk size. The regular-file check is not just a nicer message for a
- * directory named `shot.png` (whose stat size is small enough to pass the cap): it also keeps
- * `readPromptImages` from calling readFileSync on a FIFO or device node that would block the
- * command indefinitely. A path that cannot be statted is left for the read below to report
- * with its own missing-file wording. Returns the first problem, or null when every path
- * survives. */
-function attachPathsProblem(paths) {
-    const countProblem = promptImagesCountProblem(paths.length);
-    if (countProblem !== null)
-        return countProblem;
-    for (const p of paths) {
-        const extProblem = promptImageExtensionProblem(p);
-        if (extProblem !== null)
-            return extProblem;
-        try {
-            const stat = fs.statSync(p);
-            if (!stat.isFile())
-                return `attached image ${JSON.stringify(p)} is not a regular file — pass a path to an image file`;
-            const sizeProblem = promptImageSizeProblem(path.basename(p), stat.size);
-            if (sizeProblem !== null)
-                return sizeProblem;
-        }
-        catch {
-            // Missing or unreadable: the read below names it.
-        }
+/** The gone-case tail shared by every resolved queue-verb reply: a concurrent dequeue is a
+ * normal race, not an error, so report it and exit clean, naming the loop that took the
+ * prompt. One helper so the cancel, edit and top verbs' gone wording cannot drift. */
+function sayPromptGone(position, role) {
+    say(`prompt ${position} is no longer in the inbox — ${roleLabel(role)} already took it`);
+}
+/** The user-facing reply for one resolved top — the two branches of cmdPrompt's top mode
+ * (list-wide and `--role`-scoped): a concurrent dequeue is a normal race, not an error, so it
+ * is reported and exited clean; a resolved one previews the moved prompt. When `labelRole` the
+ * line names the loop — the no-`--role` command resolves across every loop, so its output must
+ * say where the prompt moved — while a `--role`-scoped command already names it in the user's
+ * own command. The `sayPromptOutcome` contract, so the verbs cannot drift. */
+function sayTopOutcome(position, role, outcome, labelRole) {
+    if (outcome.status === "gone") {
+        sayPromptGone(position, role);
+        return;
     }
-    return null;
+    say(labelRole ? `topped (${role}): ${outcome.preview}` : `topped: ${outcome.preview}`);
 }
-/** Read and validate an `--attach <path>` list into the GUI's image input shape: refuse the
- * cheap path-only rules first (attachPathsProblem above — count, extension, on-disk size),
- * read each surviving file whole, and re-run the endpoint's validation client-side
- * (promptImagesProblem) so the CLI's error names the broken rule with the same wording the
- * dashboard answers 400 with. Fails through `fail` with the same messages the enqueue branch
- * always raised, so the enqueue and `--edit` forms share one definition and cannot drift. */
+/** Read and validate an `--attach <path>` list into the GUI's image input shape, through the
+ * shared throwing core both surfaces use (readPromptImageFiles in inbox-attachments.ts), with
+ * each failure exiting through `fail` with the same messages the enqueue branch always
+ * raised — so the enqueue and `--edit` forms share one definition and cannot drift from the
+ * TUI's prompt-line attach. */
 function readPromptImages(paths) {
-    const pathProblem = attachPathsProblem(paths);
-    if (pathProblem !== null)
-        fail(pathProblem);
-    const images = paths.map((p) => {
-        let bytes;
-        try {
-            bytes = fs.readFileSync(p);
-        }
-        catch (err) {
-            return fail(`cannot read attached image ${JSON.stringify(p)}: ${errorMessage(err)}`);
-        }
-        return { name: path.basename(p), dataBase64: bytes.toString("base64") };
-    });
-    const problem = promptImagesProblem(images);
-    if (problem !== null)
-        fail(problem);
-    return images;
+    try {
+        return readPromptImageFiles(paths);
+    }
+    catch (err) {
+        return fail(errorMessage(err));
+    }
 }
-/** `tumwater prompt [--role <id>] <text|list|cancel <n>>`: submit a steering prompt to the
+/** `tumwater prompt [--role <id>] <text|list|cancel <n>|top <n>>`: submit a steering prompt to the
  * director (default) or one role's queue, list what is queued with per-loop position
- * numbering, or cancel a queued prompt by position. The dispatcher in cli.ts gates on a ready
+ * numbering, cancel a queued prompt by position, or move one to the head of its
+ * queue. The dispatcher in cli.ts gates on a ready
  * repo and delegates here; list output is grouped by loop — the director first (its queue is
  * the shared one every pre-1/2 prompt landed in), then each role with queued prompts — so a
  * per-role queue's position numbering stays unambiguous. */
 export async function cmdPrompt(root, args) {
     const parsed = parsePromptArgs(args);
+    if (parsed.role !== null)
+        parsed.role = canonicalRoleId(parsed.role);
     // `--role <id>` scopes every mode to one loop's queue; the value is validated here, with
     // the same message every other --role consumer uses. The director is always valid: its
     // queue is the historical inbox (inbox.ts).
@@ -162,7 +161,7 @@ export async function cmdPrompt(root, args) {
             return;
         }
         if (prompts.length === 0) {
-            say(role !== null ? `nothing queued for ${role}` : "nothing queued");
+            say(role !== null ? `${roleLabel(role)}'s inbox is empty` : "every inbox is empty");
             return;
         }
         say(renderQueuedList(prompts, Date.now()));
@@ -189,12 +188,96 @@ export async function cmdPrompt(root, args) {
         // `--attach` list is read through the same helper the enqueue form uses and appended to
         // the prompt's images in place.
         const images = parsed.attachPaths.length > 0 ? readPromptImages(parsed.attachPaths) : undefined;
+        // Image-input gate, `--edit`'s twin of the submit branch below (plans/image-input.md
+        // "Attachments", part 5/5): editing an attachment into a queued prompt is the same
+        // tick-time discovery the submit gate prevents, so the refusal promise holds across every
+        // CLI attach surface — an image no configured model can read is refused before a byte is
+        // written, and a loop that reroutes a blind read is told where the prompt will run. The
+        // target loop is resolved first (the same resolution the verb below makes) so the gate can
+        // name it.
+        if (images !== undefined && images.length > 0) {
+            const loop = role ?? failQueueMiss(resolveListedQueue(root, listWideScope(root), parsed.position), parsed.position).role;
+            const guidance = imagePromptGuidance(root, loop);
+            if (guidance.refusal)
+                return fail(guidance.refusal);
+            if (guidance.notice)
+                say(guidance.notice);
+        }
+        const typed = parsed.text;
+        if (typed === null) {
+            // Bare `--edit <n>`: open the prompt's body in the editor. The loop is resolved first
+            // and the write goes by file name, so a dequeue while the editor is open reports gone
+            // instead of editing the neighbour that shifted into the position.
+            let target = role;
+            if (target === null) {
+                const resolved = resolveListedQueue(root, listWideScope(root), parsed.position);
+                target = failQueueMiss(resolved, parsed.position).role;
+            }
+            const loop = target;
+            let name;
+            let body;
+            try {
+                name = path.basename(queuedFileAtPosition(root, loop, parsed.position));
+                body = readQueuedPromptBody(root, loop, name);
+            }
+            catch (err) {
+                return fail(errorMessage(err));
+            }
+            if (body === null) {
+                sayPromptOutcome(parsed.position, loop, { status: "gone" }, role === null);
+                return;
+            }
+            const after = editInEditor(body, "prompt.md");
+            // An emptied buffer is an abort, not a blank prompt: the queue would otherwise hold a
+            // prompt with no text, which the enqueue forms refuse.
+            if (after.trim() === "" && body.trim() !== "")
+                fail("the edited prompt is empty; nothing changed (use --cancel <n> to drop it)");
+            if (after.trim() === body.trim() && images === undefined) {
+                say(`prompt ${parsed.position} unchanged`);
+                return;
+            }
+            try {
+                sayPromptOutcome(parsed.position, loop, editQueuedFile(root, loop, name, after, images), role === null);
+            }
+            catch (err) {
+                fail(errorMessage(err));
+            }
+            return;
+        }
+        if (role === null) {
+            sayListedOutcome(editListedPrompt(root, listWideScope(root), parsed.position, typed, images), parsed.position);
+            return;
+        }
+        const target = role ?? DIRECTOR_ROLE;
+        sayPromptOutcome(parsed.position, target, runRolePromptCommand(root, target, parsed.position, (r, role, position) => editRolePrompt(r, role, position, typed, images)), false);
+        return;
+    }
+    if (parsed.mode === "top") {
+        // The same list-wide resolution the cancel branch uses, one verb on: no --role resolves the
+        // position across `--list`'s per-loop sections and moves it in the resolved loop's queue;
+        // with --role it is the role-scoped call. A concurrent dequeue reports gone and exits
+        // clean; position 1 of the resolved loop is "already first".
         if (role === null) {
-            sayListedOutcome(editListedPrompt(root, listWideScope(root), parsed.position, parsed.text, images), parsed.position);
+            const loop = failQueueMiss(resolveListedQueue(root, listWideScope(root), parsed.position), parsed.position).role;
+            let outcome;
+            try {
+                outcome = movePromptToTop(root, loop, parsed.position);
+            }
+            catch (err) {
+                return fail(errorMessage(err));
+            }
+            sayTopOutcome(parsed.position, loop, outcome, true);
             return;
         }
         const target = role ?? DIRECTOR_ROLE;
-        sayPromptOutcome(parsed.position, target, runRolePromptCommand(root, target, parsed.position, (r, role, position) => editRolePrompt(r, role, position, parsed.text, images)), false);
+        let outcome;
+        try {
+            outcome = movePromptToTop(root, target, parsed.position);
+        }
+        catch (err) {
+            return fail(errorMessage(err));
+        }
+        sayTopOutcome(parsed.position, target, outcome, false);
         return;
     }
     const target = role ?? DIRECTOR_ROLE;
@@ -202,21 +285,28 @@ export async function cmdPrompt(root, args) {
     // parsed duration, computed at submit so the deferral starts when the operator queued it.
     const dueMs = parsed.atDelayMs !== null ? Date.now() + parsed.atDelayMs : undefined;
     // `--attach <path>`: read and validate through the shared helper (a bad path fails by name
-    // before anything is queued).
+    // before anything is queued). An attachment the target loop cannot read is refused here by
+    // name — the same gate submitRolePrompt enforces, surfaced early so the CLI exits non-zero
+    // with the fix before anything is written or queued; a loop that reroutes a blind read is
+    // not refused, but the operator is told where the prompt will actually run.
     const images = parsed.attachPaths.length > 0 ? readPromptImages(parsed.attachPaths) : undefined;
+    if (images && images.length > 0) {
+        const guidance = imagePromptGuidance(root, target);
+        if (guidance.refusal)
+            return fail(guidance.refusal);
+        if (guidance.notice)
+            say(guidance.notice);
+    }
     const wake = submitRolePromptAndWake(root, target, parsed.text, images, dueMs);
     const attached = images !== undefined ? ` with ${images.length} image(s)` : "";
+    const owner = target === DIRECTOR_ROLE ? "the director's" : `${roleLabel(target)}'s`;
     if (parsed.atDelayMs !== null) {
         // A deferred prompt's confirmation names the delivery delay, in the same duration
-        // vocabulary --at parsed (durationLabel), so the operator can re-type it.
-        const deferred = ` — delivers in ${durationLabel(parsed.atDelayMs)}`;
-        say(role === null ? `queued for the director loop${deferred}${attached}` : `queued for the ${role} loop${deferred}${attached}`);
-    }
-    else if (role === null) {
-        say(`queued for the director loop${attached}`);
+        // vocabulary --at parsed (durationLabel), so the user can re-type it.
+        say(`added to ${owner} inbox — delivers in ${durationLabel(parsed.atDelayMs)}${attached}`);
     }
     else {
-        say(`queued for the ${role} loop${attached}`);
+        say(`added to ${owner} inbox${attached}`);
     }
     say(wake);
 }

package/dist/src/init/init-templates.js

@@ -1,20 +1,21 @@
+// vocabulary: plain
 /** The bundled project templates for `tumwater init --template`
  * (docs/feature-project-templates.md). Static string data, no file reads and no runtime
  * dependencies: a template is a brief preamble (the operator's own words stay appended after
  * it) plus a seeded PLANS.md backlog and a starter directory layout — never code scaffolds,
- * since the fleet's own first ticks write any code.
+ * since the team's own first ticks write any code.
  * `blank` is the default and reproduces today's init output byte-identically. */
 import { typoSuffix } from "../text/suggest.js";
 const PYTHON_CLI_PREAMBLE = `This project is a Python command-line tool.
 The entry point is a \`main()\` function guarded by \`if __name__ == "__main__":\` in a single
 module at the project root; the CLI parses arguments with the standard library's argparse.
 Every behavior change ships with tests runnable by \`python -m pytest\` (or unittest, once a
-suite exists), and the fleet keeps a README documenting install and usage as the tool grows.
+suite exists), and the team keeps a README documenting install and usage as the tool grows.
 Prefer the standard library over third-party dependencies.`;
 const NODE_CLI_PREAMBLE = `This project is a Node.js command-line tool.
 The entry point is \`bin.js\` (or \`src/main.js\`) wired to a \`bin\` field in package.json;
 argument parsing uses the standard library's util.parseArgs. Every behavior change ships with
-tests runnable by \`npm test\`, and the fleet keeps a README documenting install and usage as
+tests runnable by \`npm test\`, and the team keeps a README documenting install and usage as
 the tool grows. Prefer node built-ins over third-party dependencies.`;
 const STATIC_SITE_PREAMBLE = `This project is a small static website: plain HTML, CSS, and
 minimal vanilla JavaScript served as-is, with no build step. Pages live at the project root
@@ -23,7 +24,7 @@ change keeps the site renderable by opening the files directly. Keep pages acces
 markup, alt text, and keyboard-navigable controls.`;
 const blank = {
     id: "blank",
-    description: "no preamble, no seeded backlog — the fleet self-plans from your brief",
+    description: "no preamble, no seeded backlog — the team plans itself from your brief",
     briefPreamble: "",
     starterPlans: [],
     starterDirs: [],
@@ -94,8 +95,9 @@ export function templateCatalog() {
  * into PLANS_TEMPLATE under `## Planned`; the other three files land byte-identically. */
 export const PLANS_TEMPLATE = `# Plans
 
-Planned features, written by the plan loop and implemented by the feature loop.
-Each plan: goal, approach, files touched, acceptance criteria. Move finished plans to Done.
+Planned features, written by the plan role and implemented by the feature role.
+Each plan: goal, approach, files touched, acceptance criteria. Move finished plans to Done;
+tumwater then archives them in PLANS-DONE.md, so this file holds only open work.
 
 ## Planned
 
@@ -107,11 +109,11 @@ _None yet._
 `;
 export const BUGS_TEMPLATE = `# Bugs
 
-Known bugs, recorded by any loop and fixed by the bugfix loop.
+Known bugs, recorded by any role and fixed by the bugfix role.
 Each bug: symptom, how to reproduce, suspected cause if known. Move fixed bugs to Fixed, with the
 required \`**Validation gap:** <tag> — <one sentence>\` line recording what made the bug hard to
 confirm (tag one of: none, no-repro, no-fake, real-run-needed, no-observability, slow-check,
-unclear-invariant).
+unclear-invariant); tumwater then archives them in BUGS-FIXED.md, so this file holds only open work.
 
 ## Open
 
@@ -123,9 +125,9 @@ _None yet._
 `;
 export const QUESTIONS_TEMPLATE = `# Questions
 
-Open questions loops have posted for a human decision — each with context, the options, and the
-loop's recommendation. Answer by moving an entry to ## Answered with your decision (or tell the
-director). Loops never block on their own questions; they check here at the start of each tick.
+Open questions roles have posted for a human decision — each with context, the options, and the
+role's recommendation. Answer by moving an entry to ## Answered with your decision (or tell the
+director). Roles never block on their own questions; they check here at the start of each run.
 
 ## Open
 
@@ -138,7 +140,7 @@ _None yet._
 export const PRINCIPLES_TEMPLATE = `# Principles
 
 Design principles this project holds — the codified answer to "what would a senior engineer on
-this team always do." Every loop's prompt carries these; uphold them in everything you produce.
+this team always do." Every role's instructions carry these; uphold them in everything you produce.
 Only the director and steward roles may edit this file. Phrase new principles positively: state
 what to do, not what to avoid. This list is a starting point: the director and steward own it
 and will tune it to this project.
@@ -146,7 +148,7 @@ and will tune it to this project.
 - Prefer the standard library over a new dependency.
 - Keep each file focused on one responsibility, and small enough to read in one sitting.
 - Every behavior change ships with a test.
-- Small, complete, and correct beats big and half-done: one focused change per tick. Focused
+- Small, complete, and correct beats big and half-done: one focused change per run. Focused
   means one theme, not one site: a kind of fix applied everywhere it holds is one change, and
-  the same fix landed one site per tick spends a review and a landing on each.
+  the same fix applied one site per run spends a review and a merge on each.
 `;

package/dist/src/init/init.js

@@ -1,3 +1,4 @@
+// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
 import { saveConfig } from "../config/config.js";
@@ -5,7 +6,7 @@ import { seedConfig } from "../config/config-example.js";
 import { findOnPath, writeTextAtomic } from "../files/files.js";
 import { COMMIT_IDENT, GIT_MISSING_MESSAGE, git, gitTry } from "../git/git-run.js";
 import { hasCommits, isGitRepo } from "../git/git.js";
-import { INITIAL_PROMPT_MAX_CHARS, PROMPT_END, PROMPT_START, briefFile, briefTemplate, readInitialPrompt, readmeTemplate, } from "../brief.js";
+import { INITIAL_PROMPT_MAX_CHARS, PROMPT_END, PROMPT_START, briefFile, briefTemplate, readInitialPrompt, readmeTemplate, } from "../brief/brief.js";
 import { CONFIG_BASENAME, STATE_DIR, configPath } from "../paths.js";
 import { projectName } from "../project-name.js";
 import { tooLongMessage } from "../text/text.js";
@@ -97,7 +98,7 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
         ? `${tpl.briefPreamble}\n\n${initialPrompt.trim()}`
         : initialPrompt.trim();
     if (combinedPrompt.length > INITIAL_PROMPT_MAX_CHARS) {
-        throw new Error(tooLongMessage(`the initial prompt with the ${tpl.id} template's preamble`, combinedPrompt.length, INITIAL_PROMPT_MAX_CHARS, PREFILL_REASON));
+        throw new Error(tooLongMessage(`the brief with the ${tpl.id} template's preamble`, combinedPrompt.length, INITIAL_PROMPT_MAX_CHARS, PREFILL_REASON));
     }
     if (!findOnPath("git"))
         throw new Error(GIT_MISSING_MESSAGE);
@@ -117,17 +118,17 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
         const readmeHint = fs.existsSync(path.join(root, "README.md"))
             ? ` (a bare \`tumwater init\` reads the prompt from README.md between ${PROMPT_START} and ${PROMPT_END}, but README.md carries none)`
             : "";
-        throw new Error(`an initial prompt is required: tumwater init <prompt | --file prompt.md>${readmeHint}`);
+        throw new Error(`a brief is required: tumwater init <prompt | --file prompt.md>${readmeHint}`);
     }
     // `--branch` seeds a NEW repository only: an existing repo's checked-out branch is the
-    // fleet's business (`tumwater run --branch` or baseBranch chooses it at runtime), so a
+    // team's business (`tumwater start --branch` or baseBranch chooses it at runtime), so a
     // --branch given here would otherwise be silently ignored — the exact failure mode
     // rejectUnknownArgs exists to prevent. Fail before any side effect, dry-run included.
     // Whether `root` already is a repo is asked once here; nothing below until the `git init`
     // can change it.
     const wasRepo = await isGitRepo(root);
     if (branch !== undefined && wasRepo) {
-        throw new Error(`--branch only seeds a new repository: this directory is already a git repository and init leaves its checked-out branch alone — drop --branch, or point the fleet at a branch with \`tumwater run --branch ${branch}\` (or baseBranch in tumwater.json)`);
+        throw new Error(`--branch only seeds a new repository: this directory is already a git repository and init leaves its checked-out branch alone — drop --branch, or point the team at a branch with \`tumwater start --branch ${branch}\` (or baseBranch in tumwater.json)`);
     }
     // The loops read the project's reason to exist back out of the project brief on every
     // tick (readInitialPrompt). A README.md without the managed section is the project's own
@@ -142,7 +143,7 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
     // untouched and the prompt silently dropped — every loop would then run blind. Fail before
     // creating anything so the user fixes it and re-runs.
     if (adopted && fs.existsSync(path.join(root, "TUMWATER.md"))) {
-        throw new Error(`TUMWATER.md already exists without an initial prompt between the tumwater:prompt markers, so your prompt would be lost — add it to TUMWATER.md between ${PROMPT_START} and ${PROMPT_END} (or delete TUMWATER.md so init creates one), then re-run \`tumwater init\``);
+        throw new Error(`TUMWATER.md already exists without a brief between the tumwater:prompt markers, so your prompt would be lost — add it to TUMWATER.md between ${PROMPT_START} and ${PROMPT_END} (or delete TUMWATER.md so init creates one), then re-run \`tumwater init\``);
     }
     // The same loss one step later: a brief that already owns the managed sections is never
     // rewritten (init only creates what is absent), so a DIFFERENT prompt given here would be
@@ -151,7 +152,7 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
     // so pointing at README.md would send the user to edit a file nobody reads. A re-run with the
     // same prompt, or a bare init, is the idempotent re-seed and passes.
     if (prompt && brief !== null && combinedPrompt !== readInitialPrompt(root)) {
-        throw new Error(`${brief} already carries a different initial prompt between the tumwater:prompt markers, and init never rewrites an existing project brief, so your prompt would be lost — to change the prompt, edit it in ${brief} between ${PROMPT_START} and ${PROMPT_END}; to re-seed with the current one, re-run a bare \`tumwater init\``);
+        throw new Error(`${brief} already carries a different brief between the tumwater:prompt markers, and init never rewrites an existing project brief, so your prompt would be lost — to change the prompt, edit it in ${brief} between ${PROMPT_START} and ${PROMPT_END}; to re-seed with the current one, re-run a bare \`tumwater init\``);
     }
     let repoInitialized = false;
     let createdBranch;
@@ -159,7 +160,7 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
         // Branch precedence: the caller's explicit --branch, else git's own init.defaultBranch
         // preference, else main. `git init -b` does not consult init.defaultBranch, so the
         // preference is read here: an operator who configured `init.defaultBranch=trunk`
-        // expects `git init`-compatible behavior, and the fleet then targets that branch.
+        // expects `git init`-compatible behavior, and the team then targets that branch.
         const preferred = branch ?? ((await gitTry(root, "config", "--get", "init.defaultBranch")) || "main");
         // A branch name git rejects (a space, a leading dash, "@{…}" history syntax, …) would
         // abort `git init -b` AFTER it has created .git — a half-initialized directory whose
@@ -219,7 +220,7 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
     else
         write("README.md", readmeTemplate(name, combinedPrompt));
     // A template with starter plans seeds the backlog with them, rendered as `### ` entries —
-    // the primary entry format every backlog reader parses — so the fleet's first ticks land on
+    // the primary entry format every backlog reader parses — so the team's first ticks land on
     // real work. blank keeps the `_None yet._` placeholder byte-identical to today.
     const plansContent = tpl.starterPlans.length > 0
         ? PLANS_TEMPLATE.replace("_None yet._", tpl.starterPlans.map((p) => `### ${p}`).join("\n\n"))
@@ -245,7 +246,7 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
         created.push(".gitignore");
     else if (fs.existsSync(path.join(root, ".gitignore")))
         leftAlone.push(".gitignore");
-    // The template's starter directories: empty ones only, before the first tick — the fleet's
+    // The template's starter directories: empty ones only, before the first tick — the team's
     // own ticks write any code. Existing directories are left alone, like existing files above.
     for (const dir of tpl.starterDirs) {
         claim(dir, path.join(root, dir), () => fs.mkdirSync(path.join(root, dir), { recursive: true }));
@@ -263,7 +264,7 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
         const staged = await gitTry(root, "diff", "--cached", "--quiet");
         if (staged === null) {
             // Non-zero exit = something is staged.
-            const message = withCommits ? "tumwater: init harness files" : "tumwater: init";
+            const message = withCommits ? "tumwater: init files" : "tumwater: init";
             await git(root, ...COMMIT_IDENT, "commit", "-m", message, "--", ...committable);
             committed = true;
         }