@astrosheep/keiyaku 2.9.11 → 2.9.13

package/build/cli/commands/task/note/handler.js

@@ -0,0 +1,6 @@
+import { appendTaskNote, resolveTaskCreator } from "../../../../core/task/index.js";
+import { runTaskMutationCommand } from "../shared.js";
+export const handler = async (stdin, flags, _signal, positional) => runTaskMutationCommand(flags, async (repository, cwd) => appendTaskNote(repository, positional[0], {
+    actor: await resolveTaskCreator(cwd),
+    text: stdin,
+}));

package/build/cli/commands/task/note/meta.js

@@ -0,0 +1,11 @@
+export const meta = {
+    command: "task note",
+    summary: "Append an immutable task note",
+    usage: ["keiyaku task note [-C|--cwd DIR] [--contract ADDR] COORDINATE TEXT|-"],
+    stdin: {
+        mode: "argument",
+        selector: { kind: "positional", index: 1, required: true, rejectBlank: true },
+    },
+    flags: ["cwd", "contract"],
+    purpose: "Record an append-only task journal fact.",
+};

package/build/cli/commands/task/resume/meta.js

@@ -1,8 +1,8 @@
 export const meta = {
     command: "task resume",
     summary: "Resume a task on hold",
-    usage: ["keiyaku task resume [-C|--cwd DIR] COORDINATE"],
+    usage: ["keiyaku task resume [-C|--cwd DIR] [--contract ADDR] COORDINATE"],
     stdin: { mode: "argument" },
-    flags: ["cwd"],
+    flags: ["cwd", "contract"],
     purpose: "Return an on-hold task to open.",
 };

package/build/cli/commands/task/shared.js

@@ -1,30 +1,44 @@
 import { FlowError } from "../../../flow-error.js";
+import { attachAddressCarrier, resolveExplicitContractAddressFromRead } from "../../../core/addressing.js";
+import { readRepositoryLifecycle } from "../../../core/repository-ledger/read-model.js";
+import { findRegisteredContractWorktreePathFromModel, stableRepoRoot } from "../../../core/worktree-path.js";
 import { openTaskCommandRepository, parseTaskDocument, readTaskDoctor, taskCoordinateFromSourcePath, } from "../../../core/task/index.js";
 import { deriveTaskDisplay, renderTaskList, renderTaskMutationRow, } from "../../render/task.js";
 import { textResponse } from "../../render/shared.js";
 import { effectiveDirectory } from "../shared.js";
-/** Open the task command repository for flags.cwd and run the verb. */
-export async function withTaskCommandRepository(flags, run) {
+/** Resolve --contract to its one ledger-owned checkout before task access. */
+export async function taskCommandDirectory(flags) {
     const cwd = effectiveDirectory(flags);
+    if (flags.contractId === undefined)
+        return cwd;
+    const stableRoot = await stableRepoRoot(cwd);
+    const admitted = resolveExplicitContractAddressFromRead({
+        read: await readRepositoryLifecycle(stableRoot),
+        stableRoot,
+        workdir: cwd,
+        raw: flags.contractId,
+        source: flags.contractAddressSource ?? "explicit-flag",
+    });
+    const worktree = admitted.model.resources.worktree;
+    const lifecycle = admitted.model.phase;
+    if (!worktree || worktree.state !== "held") {
+        throw attachAddressCarrier(new FlowError("CONTRACT_WORKSPACE_UNAVAILABLE", `contract ${admitted.model.contract} has no materialized workspace for task commands (${lifecycle})`, { facts: { kind: "task_contract_workspace", contractId: admitted.model.contract, lifecycle, reason: "not-materialized" } }), admitted.address);
+    }
+    const registered = await findRegisteredContractWorktreePathFromModel(stableRoot, admitted.model);
+    if (!registered) {
+        throw attachAddressCarrier(new FlowError("CONTRACT_WORKSPACE_UNAVAILABLE", `contract ${admitted.model.contract} worktree is not a verified ledger-owned materialized checkout`, { facts: { kind: "task_contract_workspace", contractId: admitted.model.contract, lifecycle, reason: "unregistered" } }), admitted.address);
+    }
+    return registered;
+}
+/** Open the selected task command repository and run the verb. */
+export async function withTaskCommandRepository(flags, run) {
+    const cwd = await taskCommandDirectory(flags);
     return run(await openTaskCommandRepository(cwd), cwd);
 }
 /** Shared shell: open repository → mutate → renderTaskMutationRow receipt. */
 export async function runTaskMutationCommand(flags, mutate) {
     return textResponse(renderTaskMutationRow(await withTaskCommandRepository(flags, mutate)));
 }
-export function parseTaskAddInput(input) {
-    if (!input.trim())
-        throw new FlowError("EMPTY_PARAM", "task add input cannot be blank");
-    const lines = input.split(/\r?\n/);
-    const firstLine = lines[0]?.startsWith("# ") ? lines[0].slice(2) : lines[0];
-    const title = firstLine?.trim() ?? "";
-    if (!title)
-        throw new FlowError("EMPTY_PARAM", "task title cannot be blank");
-    if (lines.length > 1 && lines[1].trim() !== "") {
-        throw new FlowError("EMPTY_PARAM", "task add body must follow the title after a blank line");
-    }
-    return { title, body: lines.slice(2).join("\n") };
-}
 export function taskSelection(flags) {
     return flags.all ? "all" : flags.done ? "done" : "default";
 }

package/build/cli/commands/task/show/meta.js

@@ -1,8 +1,8 @@
 export const meta = {
     command: "task show",
     summary: "Show one task and its children tree",
-    usage: ["keiyaku task show [-C|--cwd DIR] COORDINATE [--json]"],
+    usage: ["keiyaku task show [-C|--cwd DIR] [--contract ADDR] COORDINATE [--json]"],
     stdin: { mode: "argument" },
-    flags: ["cwd", "json"],
+    flags: ["cwd", "contract", "json"],
     purpose: "Read one task and every descendant linked by parent edges.",
 };

package/build/cli/commands/task/start/meta.js

@@ -1,8 +1,8 @@
 export const meta = {
     command: "task start",
     summary: "Start a task",
-    usage: ["keiyaku task start [-C|--cwd DIR] COORDINATE"],
+    usage: ["keiyaku task start [-C|--cwd DIR] [--contract ADDR] COORDINATE"],
     stdin: { mode: "argument" },
-    flags: ["cwd"],
+    flags: ["cwd", "contract"],
     purpose: "Move an open task to in_progress.",
 };

package/build/cli/commands/task/stop/meta.js

@@ -1,8 +1,8 @@
 export const meta = {
     command: "task stop",
     summary: "Stop a task",
-    usage: ["keiyaku task stop [-C|--cwd DIR] [COORDINATE]"],
+    usage: ["keiyaku task stop [-C|--cwd DIR] [--contract ADDR] [COORDINATE]"],
     stdin: { mode: "argument" },
-    flags: ["cwd"],
+    flags: ["cwd", "contract"],
     purpose: "Return an in-progress task to open.",
 };

package/build/cli/commands/task/update/meta.js

@@ -1,11 +1,12 @@
+export const TASK_UPDATE_EXPLICIT_CHANGE_ERROR = "task update requires an explicit change: --title, --body TEXT or --body -, --append TEXT|-, --pri, --needs/--drop-needs, --parent/--no-parent, --from, --supersedes/--drop-supersedes, or --relates-to/--drop-relates-to";
 export const meta = {
     command: "task update",
     summary: "Update task facts",
-    usage: ["keiyaku task update [-C|--cwd DIR] COORDINATE [--title TEXT] [--body TEXT|-|--append TEXT|-] [--pri 0-3] [--needs COORDINATE] [--drop-needs COORDINATE] [--parent COORDINATE|--no-parent] [--from COORDINATE] [--supersedes COORDINATE] [--drop-supersedes COORDINATE] [--relates-to COORDINATE] [--drop-relates-to COORDINATE] [--json]"],
+    usage: ["keiyaku task update [-C|--cwd DIR] [--contract ADDR] COORDINATE [--title TEXT] [--body TEXT|-|--append TEXT|-] [--pri 0-3] [--needs COORDINATE] [--drop-needs COORDINATE] [--parent COORDINATE|--no-parent] [--from COORDINATE] [--supersedes COORDINATE] [--drop-supersedes COORDINATE] [--relates-to COORDINATE] [--drop-relates-to COORDINATE] [--json]"],
     stdin: {
         mode: "argument",
         selector: { kind: "flag", names: ["taskBody", "taskAppend"], required: false, rejectBlank: false },
     },
-    flags: ["cwd", "title", "body", "append", "pri", "needs", "drop-needs", "parent", "no-parent", "from", "supersedes", "drop-supersedes", "relates-to", "drop-relates-to", "json"],
+    flags: ["cwd", "contract", "title", "body", "append", "pri", "needs", "drop-needs", "parent", "no-parent", "from", "supersedes", "drop-supersedes", "relates-to", "drop-relates-to", "json"],
     purpose: "Change mutable task facts.",
 };

package/build/cli/commands/verification/handler.js

@@ -0,0 +1,43 @@
+import { readVerificationRun, requestVerificationRunCancellation, VerificationRunUnknownError, VerificationRunWaitTimeoutError, waitForVerificationRun, } from "../../../core/settlement/verification.js";
+import { FlowError } from "../../../flow-error.js";
+import { renderVerificationCli, verificationCancelModel, verificationStatusModel, verificationWaitModel, verificationWaitTimeoutModel, } from "../../render/verification.js";
+import { projectDirectory } from "../shared.js";
+export const handler = async (_stdin, flags, signal, positional) => {
+    const [operation, runId, ...extra] = positional;
+    if (!operation || !runId || extra.length > 0) {
+        throw new FlowError("EMPTY_PARAM", "verification requires wait, status, or cancel followed by one VerificationRun id");
+    }
+    // Honor --repo through the shared repository-resolution primitive.
+    const root = await projectDirectory(flags, "verification");
+    const json = flags.json === true;
+    if (operation === "wait") {
+        try {
+            // Observation only: timeout/abort end wait without requesting cancellation.
+            const terminal = await waitForVerificationRun({ root, runId, timeoutMs: flags.timeoutMs, signal });
+            return renderVerificationCli(verificationWaitModel(runId, terminal), json);
+        }
+        catch (error) {
+            if (error instanceof VerificationRunUnknownError) {
+                throw new FlowError("UNKNOWN_ADDRESS", error.message);
+            }
+            if (!(error instanceof VerificationRunWaitTimeoutError))
+                throw error;
+            return renderVerificationCli(verificationWaitTimeoutModel(runId), json);
+        }
+    }
+    if (operation === "status") {
+        const run = readVerificationRun(root, runId);
+        if (!run)
+            throw new FlowError("UNKNOWN_ADDRESS", `verification run '${runId}' does not exist`);
+        return renderVerificationCli(verificationStatusModel(run), json);
+    }
+    if (operation === "cancel") {
+        // Explicit cancel is the only mutating verification CLI path.
+        if (!readVerificationRun(root, runId)) {
+            throw new FlowError("UNKNOWN_ADDRESS", `verification run '${runId}' does not exist`);
+        }
+        const accepted = requestVerificationRunCancellation(root, runId);
+        return renderVerificationCli(verificationCancelModel(runId, accepted), json);
+    }
+    throw new FlowError("INVALID_USAGE", "verification operation must be wait, status, or cancel");
+};

package/build/cli/commands/verification/meta.js

@@ -0,0 +1,13 @@
+export const meta = {
+    command: "verification",
+    summary: "Observe or cancel one durable VerificationRun",
+    usage: [
+        "keiyaku verification wait RUN_ID [-C|--cwd DIR] [--repo DIR] [--timeout DURATION] [--json]",
+        "keiyaku verification cancel RUN_ID [-C|--cwd DIR] [--repo DIR] [--json]",
+        "keiyaku verification status RUN_ID [-C|--cwd DIR] [--repo DIR] [--json]",
+    ],
+    stdin: { mode: "argument" },
+    flags: ["cwd", "repo", "timeout", "json"],
+    purpose: "Rejoin, inspect, or request cancellation of an addressable VerificationRun without inspecting runtime SQLite directly.",
+    completionRank: 11,
+};

package/build/cli/completion.js

@@ -19,8 +19,8 @@ function topLevelCommands() {
 function subcommandsFor(parent) {
     return [...(getCommandMetadata(parent).subcommands ?? [])];
 }
-function topLevelOptionsFor(command) {
-    const metadata = allCommandMetadata().find((meta) => meta.command === command && !command.includes(" "));
+function optionsForCommandContext(context) {
+    const metadata = allCommandMetadata().find((meta) => meta.command === context);
     return metadata ? metadata.flags.map((flag) => `--${flag}`) : [];
 }
 function filterPrefix(items, word) {
@@ -40,22 +40,24 @@ export async function renderCompletionCandidates(input) {
     if (word.startsWith("@")) {
         return (await contractAddressCandidates(input.cwd, word)).join("\n");
     }
-    if (input.previous === "call") {
+    const previous = input.previous ?? "";
+    const previousWord = previous.split(/\s+/).at(-1) ?? "";
+    if (previous === "call") {
         return filterPrefix([...(await akumaCandidates(input.cwd, word)), "--alias"], word).join("\n");
     }
-    if (input.previous === "akuma") {
+    if (previous === "akuma") {
         return filterPrefix(subcommandsFor("akuma"), word).join("\n");
     }
-    if (input.previous === "skills") {
+    if (previous === "skills") {
         return filterPrefix(subcommandsFor("skills"), word).join("\n");
     }
-    if (input.previous === "task") {
+    if (previous === "task") {
         return filterPrefix(subcommandsFor("task"), word).join("\n");
     }
-    if (input.previous === "--filter") {
+    if (previousWord === "--filter") {
         return filterPrefix([TASK_FILTER_COMPLETION], word).join("\n");
     }
-    const options = input.previous ? topLevelOptionsFor(input.previous) : [];
+    const options = previous ? optionsForCommandContext(previous) : [];
     if (options.length > 0) {
         return filterPrefix(options, word).join("\n");
     }
@@ -66,8 +68,9 @@ export function renderCompletionScript(shell = "bash") {
         return [
             "#compdef keiyaku",
             "_keiyaku() {",
-            "  local -a candidates",
-            "  candidates=(${(f)\"$(keiyaku completion --complete --word=\"${words[CURRENT]}\" --previous=\"${words[CURRENT-1]}\" 2>/dev/null)\"})",
+            "  local -a candidates context",
+            "  context=\"${(j: :)words[2,CURRENT-1]}\"",
+            "  candidates=(${(f)\"$(keiyaku completion --complete --word=\"${words[CURRENT]}\" --previous=\"${context}\" 2>/dev/null)\"})",
             "  compadd -- $candidates",
             "}",
             "_keiyaku \"$@\"",
@@ -75,13 +78,13 @@ export function renderCompletionScript(shell = "bash") {
     }
     return [
         "_keiyaku_completion() {",
-        "  local cur prev",
+        "  local cur context",
         "  cur=\"${COMP_WORDS[COMP_CWORD]}\"",
-        "  prev=\"${COMP_WORDS[COMP_CWORD-1]}\"",
+        "  context=\"${COMP_WORDS[*]:1:$((COMP_CWORD - 1))}\"",
         "  COMPREPLY=()",
         "  while IFS= read -r candidate; do",
         "    COMPREPLY+=(\"$candidate\")",
-        "  done < <(keiyaku completion --complete --word=\"$cur\" --previous=\"$prev\" 2>/dev/null)",
+        "  done < <(keiyaku completion --complete --word=\"$cur\" --previous=\"$context\" 2>/dev/null)",
         "}",
         "complete -F _keiyaku_completion keiyaku",
     ].join("\n");

package/build/cli/flags.js

@@ -47,6 +47,11 @@ export const FLAG_SPECS = {
         placeholder: "DURATION",
         description: "Wait at most a positive duration such as 45s, 5m, or 2h (maximum 24h).",
     },
+    entry: {
+        kind: "value",
+        placeholder: "N",
+        description: "Select one zero-based retained history entry from an addressed projection.",
+    },
     any: {
         kind: "boolean",
         description: "For a projection set, return when the first observed member reaches a terminal state.",
@@ -58,7 +63,7 @@ export const FLAG_SPECS = {
     },
     incognito: {
         kind: "boolean",
-        description: "Do not persist response history and do not allow revive.",
+        description: "Do not persist response history and do not allow fork.",
     },
     bare: {
         kind: "boolean",
@@ -103,7 +108,7 @@ export const FLAG_SPECS = {
     scope: {
         kind: "value",
         placeholder: "GLOB",
-        description: "Set the single scope pattern for flag-generated bind Markdown.",
+        description: "Add an ordered scope pattern to flag-generated bind Markdown. May be repeated.",
     },
     criteria: {
         kind: "value",
@@ -138,6 +143,10 @@ export const FLAG_SPECS = {
         kind: "boolean",
         description: "Preview bind input or petition preflight without mutation.",
     },
+    check: {
+        kind: "boolean",
+        description: "Derive and render the task composition without changing the board or Git state.",
+    },
     "append-scope": {
         kind: "value",
         placeholder: "PATTERN",
@@ -147,6 +156,10 @@ export const FLAG_SPECS = {
         kind: "boolean",
         description: "Renew onto the current target before petitioning.",
     },
+    audit: {
+        kind: "boolean",
+        description: "Run the ordinary read-only audit after a completed renew.",
+    },
     continue: {
         kind: "boolean",
         description: "Continue from the derived renew conflict scratch.",
@@ -187,11 +200,29 @@ export const FLAG_SPECS = {
         kind: "boolean",
         description: "Render structured data as JSON.",
     },
+    limit: {
+        kind: "value",
+        placeholder: "COUNT",
+        description: "Limit terminal rows in the Akuma roster.",
+    },
+    offset: {
+        kind: "value",
+        placeholder: "COUNT",
+        description: "Skip terminal rows in the Akuma roster.",
+    },
+    raw: {
+        kind: "boolean",
+        description: "Include retained raw event bodies when inspecting one history entry.",
+    },
     "diff-budget": {
         kind: "value",
         placeholder: "BYTES",
         description: "Set the audit raw-diff presentation budget in bytes.",
     },
+    "skip-diff-body": {
+        kind: "boolean",
+        description: "Suppress raw diff hunk bodies from the human audit presentation without changing audit evidence or checks.",
+    },
     done: {
         kind: "boolean",
         description: "Show terminal tasks.",
@@ -209,51 +240,51 @@ export const FLAG_SPECS = {
     pri: {
         kind: "value",
         placeholder: "0-3",
-        description: "Set task priority from 0 through 3.",
+        description: "Set task priority: 0 (highest) through 3 (lowest).",
     },
     needs: {
         kind: "value",
         placeholder: "ID",
-        description: "Add a task dependency. May be repeated.",
+        description: "Order execution: this task needs another task first. May be repeated.",
     },
     "drop-needs": {
         kind: "value",
         placeholder: "ID",
-        description: "Remove a task dependency. May be repeated.",
+        description: "Remove an execution-ordering dependency. May be repeated.",
     },
     parent: {
         kind: "value",
         placeholder: "ID",
-        description: "Set the parent task.",
+        description: "Organize task hierarchy under a parent task.",
     },
     "no-parent": {
         kind: "boolean",
-        description: "Clear the parent task.",
+        description: "Clear the hierarchy parent task.",
     },
     from: {
         kind: "value",
         placeholder: "ID",
-        description: "Add a discovery-lineage task. May be repeated.",
+        description: "Record work discovered while doing another task. May be repeated.",
     },
     supersedes: {
         kind: "value",
         placeholder: "ID",
-        description: "Record that this task supersedes another task. May be repeated.",
+        description: "Record that this task replaces another task. May be repeated.",
     },
     "drop-supersedes": {
         kind: "value",
         placeholder: "ID",
-        description: "Remove a supersedes relation. May be repeated.",
+        description: "Remove a replacement relation. May be repeated.",
     },
     "relates-to": {
         kind: "value",
         placeholder: "ID",
-        description: "Record related work. May be repeated.",
+        description: "Record a thematic relation without ordering or replacement. May be repeated.",
     },
     "drop-relates-to": {
         kind: "value",
         placeholder: "ID",
-        description: "Remove a related-work relation. May be repeated.",
+        description: "Remove a thematic relation. May be repeated.",
     },
     title: {
         kind: "value",
@@ -270,6 +301,11 @@ export const FLAG_SPECS = {
         placeholder: "TEXT|-",
         description: "Append a Markdown paragraph to the task body; literal - reads stdin.",
     },
+    note: {
+        kind: "value",
+        placeholder: "TEXT|-",
+        description: "Append an immutable task note; literal - reads stdin.",
+    },
 };
 export const CONTROL_FLAGS = new Set(Object.keys(FLAG_SPECS));
 export const VALUE_FLAGS = new Set(Object.entries(FLAG_SPECS)

package/build/cli/help.js

@@ -25,7 +25,7 @@ export function renderCliCommandHelp(_command, spec, flagSpecs) {
     section(lines, "Purpose:", [spec.purpose]);
     section(lines, "Subcommands:", spec.subcommands);
     section(lines, "Input:", spec.input);
-    section(lines, "Options:", spec.flags.map((name) => `${flagUsage(name, flagSpecs)}  ${spec.flagDescriptions?.[name] ?? flagSpecs[name]?.description ?? ""}`));
+    section(lines, "Options:", spec.flags.map((name) => `${spec.flagUsages?.[name] ?? flagUsage(name, flagSpecs)}  ${spec.flagDescriptions?.[name] ?? flagSpecs[name]?.description ?? ""}`));
     section(lines, "Notes:", spec.notes);
     section(lines, "Examples:", spec.examples);
     return lines.join("\n").trimEnd();
@@ -39,27 +39,27 @@ export function renderCliHelp(version) {
         "  keiyaku @<commission> <command> [flags]",
         "",
         "Flow:",
-        "  bind -> delivery work -> petition",
-        "  optional: arc -> delivery work -> arc; renew on base drift",
+        "  bind -> make and commit changes -> petition",
+        "  optional: arc -> make and commit changes -> arc; renew when the target moves",
         "",
         "Commands:",
-        "  bind       Create a contract ledger and workspace files.",
-        "  arc        Optional iteration; seals current intent first.",
-        "  renew      Rewrite delivery onto the current base and seal it.",
-        "  call       Start an Akuma helper session.",
-        "  wait       Wait for an akuma projection.",
-        "  revive     Revive an Akuma helper session.",
-        "  tell       Send intent to an Akuma projection.",
-        "  kill       Stop the current Akuma generation.",
-        "  log        Render a contract ledger.",
-        "  akuma      Inspect helper profiles.",
+        "  bind       Create a contract and its workspace.",
+        "  arc        Seal the current stage and begin another.",
+        "  renew      Refresh committed changes onto the contract target.",
+        "  call       Start an Akuma projection.",
+        "  wait       Wait for a projection.",
+        "  fork       Start a projection from a response artifact.",
+        "  tell       Send a message to a projection.",
+        "  kill       Stop a projection's active run.",
+        "  log        Show a contract history.",
+        "  akuma      Inspect available Akuma definitions.",
         "  skills     Install bundled official skills.",
         "  amend      Record an amendment.",
-        "  petition   Run settlement processing.",
-        "  forfeit    Forfeit an addressed contract.",
+        "  petition   Ask Keiyaku to settle a contract.",
+        "  forfeit    End a contract without claiming it.",
         "  guide      Print workflow guidance.",
         "  completion Print shell completion.",
-        "  status     Render the Kanshi board.",
+        "  status     Show contracts, tasks, and projections that need attention.",
         "  task       Manage lightweight repository tasks.",
         "  dump-env   Print the environment template.",
         "",
@@ -67,12 +67,12 @@ export function renderCliHelp(version) {
         "  <> means required; [] means optional.",
         "  bind, arc, amend, and petition read document stdin only when literal `-` selects it.",
         "  call and tell require literal BODY or `-`; literal `-` selects stdin.",
-        "  revive accepts an artifact plus optional BODY or `-`; unselected stdin is ignored.",
+        "  fork accepts an artifact plus optional BODY or `-`; unselected stdin is ignored.",
         "",
         "Configuration:",
-        "  Akuma profiles  <KEIYAKU_HOME>/akuma/*.md or .keiyaku/akuma/*.md",
+        "  Akuma definitions  <KEIYAKU_HOME>/akuma/*.md or .keiyaku/akuma/*.md",
         "  Settings        <KEIYAKU_HOME>/settings.json or .keiyaku/settings.json",
-        "  Inspect         keiyaku akuma ls | keiyaku akuma show NAME",
+        "  Inspect         keiyaku akuma list | keiyaku akuma show NAME",
         "  Environment     keiyaku dump-env",
         "  Full format     README Configuration",
     ].join("\n");
@@ -81,18 +81,17 @@ export function buildKeiyakuGuide(version) {
     return [
         `# Keiyaku Guide (v${version})`,
         "",
-        "## Workflow",
-        "`bind -> delivery work -> petition`",
-        "optional: `arc -> delivery work -> arc`; renew on base drift",
+        "A task is a planning item: it does not create a workspace or start work.",
+        "A contract is one bounded delivery with its own workspace. It begins bound and ends claimed when settlement lands it, or forfeited when it is ended without a claim.",
+        "An Akuma is a callable worker definition. A projection is one run of an Akuma.",
         "",
-        "- `bind` supplies derived default intent a0.",
-        "- `arc` is an optional iteration boundary, not admission; the first explicit arc seals a0, and later arcs seal the previous open explicit arc.",
-        "- `renew` seals the current a0 or open explicit arc after a successful refresh onto the default branch.",
-        "- `petition` seals the current a0 or open explicit arc and starts settlement.",
-        "- After an explicit arc closes, loose commits require another arc before renew or petition.",
-        "- `call` and `revive` provide helper execution without changing the ledger lifecycle.",
-        "- `skills install` installs the bundled official Keiyaku skills into supported agent skill directories; force permits replacement of foreign collisions.",
-        "- `status` is read-only and reports next actions, drift, queue state, and projections.",
+        "`bind -> make and commit changes -> petition`",
+        "",
+        "Binding a contract establishes its first delivery stage. A `seal` records that stage's committed changes and scope at a lifecycle boundary.",
+        "`arc` is an optional boundary: it seals the current stage and opens the next. Use arcs only for successive stages of one contract and one final settlement; they do not create separately claimable work.",
+        "When the contract target moves, `renew` refreshes the committed changes onto it and seals the refreshed current stage.",
+        "`petition` seals the current stage, runs the contract's settlement checks, and claims the contract only when they pass. If a settlement gate fails, the contract is not claimed; address the reported problem and petition again.",
+        "Use separate tasks and contracts for work with separate acceptance, ownership, or waiting needs. `status` shows the work that needs attention.",
     ].join("\n");
 }
 export function commandMetadata(command) {

package/build/cli/index.js

@@ -37,10 +37,10 @@ function prepareBindInput(stdin, flags, selectsStdin) {
     const nonblankStdin = stdin.trim().length > 0;
     const domainFlags = hasBindDomainFlags(flags);
     if (flags.dryRun && flags.draftOnly) {
-        throw new FlowError("EMPTY_PARAM", "--dry-run cannot be combined with --draft-only");
+        throw new FlowError("INVALID_USAGE", "--dry-run cannot be combined with --draft-only");
     }
     if (selectsStdin && domainFlags) {
-        throw new FlowError("EMPTY_PARAM", "bind accepts either stdin Markdown or domain flags, not both");
+        throw new FlowError("INVALID_USAGE", "bind accepts either stdin Markdown or domain flags, not both");
     }
     if (domainFlags) {
         const missing = [];
@@ -74,7 +74,10 @@ function prepareBindInput(stdin, flags, selectsStdin) {
         if (flags.bindTaskIds !== undefined && flags.bindTaskIds.length > 0) {
             return "";
         }
-        throw new FlowError("EMPTY_PARAM", `No Markdown input received on stdin.\n\nExample:\n  ${usageExample("bind")}`);
+        const message = selectsStdin
+            ? `No Markdown input received on stdin.\n\nExample:\n  ${usageExample("bind")}`
+            : "bind requires literal '-' for Markdown input or the required domain flags";
+        throw new FlowError(selectsStdin ? "STDIN_EMPTY" : "EMPTY_PARAM", message);
     }
     return stdin;
 }
@@ -217,9 +220,6 @@ async function resolveCliInput(parsed) {
     const selected = selectedArgument(parsed);
     const token = selected?.token;
     const selectsStdin = token === "-";
-    if (selectsStdin && process.stdin.isTTY) {
-        throw new FlowError("EMPTY_PARAM", `${parsed.command} literal '-' requires piped stdin`);
-    }
     const piped = selectsStdin ? await readStdin() : "";
     const input = selectsStdin ? piped : token ?? "";
     if (stdinMeta.selector?.required && token === undefined) {
@@ -231,8 +231,14 @@ async function resolveCliInput(parsed) {
     if (token !== undefined && stdinMeta.selector?.rejectBlank && !input.trim()) {
         const message = stdinMeta.mode === "document"
             ? `No Markdown input received on stdin.\n\nExample:\n  ${usageExample(parsed.command)}`
-            : `${parsed.command} body cannot be empty`;
-        throw new FlowError("EMPTY_PARAM", message);
+            : selectsStdin
+                ? parsed.command === "task add"
+                    ? "task add received no task document on stdin"
+                    : `${parsed.command} received no body on stdin`
+                : parsed.command === "task add"
+                    ? "task add title cannot be empty"
+                    : `${parsed.command} body cannot be empty`;
+        throw new FlowError(selectsStdin ? "STDIN_EMPTY" : "EMPTY_PARAM", message);
     }
     return { stdin: input, flags: selected?.replace(input) ?? parsed.flags, selectsStdin };
 }