@astrosheep/keiyaku 1.0.0 → 1.0.2

package/build/cli/commands/akuma.js

@@ -1,5 +1,4 @@
 import { resolveDefaultAgentName, resolveReviewerAgentName, } from "../../config/settings.js";
-import { normalizeAkumaProfile } from "../../config/akuma-loader.js";
 import { FlowError } from "../../flow-error.js";
 function formatRoleMarkers(settings, name) {
     const markers = [];
@@ -9,29 +8,59 @@ function formatRoleMarkers(settings, name) {
         markers.push("reviewer");
     return markers.length > 0 ? ` (${markers.join(", ")})` : "";
 }
-function formatProfileSummary(profile) {
-    const model = profile.model ? `, model ${profile.model}` : "";
-    return `provider ${profile.provider}, executable ${profile.executable}${model}`;
+function sourceBadge(source) {
+    return `[${source}]`;
 }
-function sourceBadge(definition) {
-    return `[${definition.source}]`;
+function isValidAkumaCandidate(candidate) {
+    return candidate.profile !== undefined && candidate.reason === undefined;
 }
-export function renderAkumaList(catalog, settings) {
-    const lines = ["Available Akumas:", ""];
-    for (const definition of Object.values(catalog.definitions).sort((a, b) => a.name.localeCompare(b.name))) {
-        const profile = normalizeAkumaProfile(definition.profile);
-        lines.push(`- ${definition.name}${formatRoleMarkers(settings, definition.name)} ${sourceBadge(definition)}: ${formatProfileSummary(profile)}`);
-        if (profile.description) {
-            lines.push(`  ${profile.description}`);
-        }
+function isValidProviderCandidate(candidate) {
+    return candidate.instance !== undefined && candidate.reason === undefined;
+}
+function resolveAkumaInspection(candidate, providerInstances) {
+    if (!isValidAkumaCandidate(candidate)) {
+        return {
+            status: "invalid",
+            name: candidate.name,
+            source: candidate.source,
+            path: candidate.path,
+            reason: candidate.reason,
+        };
     }
-    for (const shadow of catalog.shadows) {
-        lines.push(`- ${shadow.name} [${shadow.source}] (shadowed by ${shadow.shadowedBy})`);
+    const instanceName = candidate.profile.provider;
+    const providerCandidate = providerInstances.selected[instanceName];
+    if (providerCandidate === undefined) {
+        return {
+            status: "invalid",
+            name: candidate.name,
+            source: candidate.source,
+            path: candidate.path,
+            reason: `missing provider instance '${instanceName}'`,
+        };
     }
-    for (const invalid of catalog.invalid) {
-        lines.push(`- ${invalid.name} (invalid: ${invalid.reason})`);
+    if (!isValidProviderCandidate(providerCandidate)) {
+        return {
+            status: "invalid",
+            name: candidate.name,
+            source: candidate.source,
+            path: candidate.path,
+            reason: `invalid provider instance '${instanceName}': ${providerCandidate.reason}`,
+        };
     }
-    return lines.join("\n");
+    const providerShadows = providerInstances.shadows.filter((shadow) => shadow.name === instanceName);
+    return {
+        status: "valid",
+        name: candidate.name,
+        source: candidate.source,
+        path: candidate.path,
+        profile: candidate.profile,
+        body: candidate.body,
+        instanceName,
+        instance: providerCandidate.instance,
+        kind: providerCandidate.instance.kind,
+        providerSource: providerCandidate.source,
+        providerShadows,
+    };
 }
 function appendOptionalLine(lines, label, value) {
     if (value === undefined)
@@ -46,34 +75,83 @@ function appendOptionalLine(lines, label, value) {
     }
     lines.push(`${label}: ${String(value)}`);
 }
-export function renderAkumaShow(catalog, settings, name) {
-    const definition = catalog.definitions[name];
-    if (definition === undefined) {
+function appendPromptPreview(lines, body) {
+    const promptLines = body === "" ? [] : body.split(/\r?\n/);
+    lines.push("prompt:");
+    lines.push(...promptLines.slice(0, 8).map((line) => `  ${line}`));
+    lines.push(`(${promptLines.length} lines total)`);
+}
+function chooseCallHintName(validNames, settings) {
+    if (validNames.length === 0)
+        return null;
+    const configuredDefault = resolveDefaultAgentName(settings);
+    if (validNames.includes(configuredDefault))
+        return configuredDefault;
+    return validNames[0] ?? null;
+}
+export function renderAkumaList(catalog, providerInstances, settings) {
+    const lines = ["Available Akumas:", ""];
+    const validNames = [];
+    for (const name of Object.keys(catalog.selected).sort((a, b) => a.localeCompare(b))) {
+        const candidate = catalog.selected[name];
+        if (candidate === undefined)
+            continue;
+        const resolved = resolveAkumaInspection(candidate, providerInstances);
+        const markers = formatRoleMarkers(settings, resolved.name);
+        if (resolved.status === "invalid") {
+            lines.push(`- ${resolved.name}${markers} ${sourceBadge(resolved.source)} (invalid: ${resolved.reason})`);
+            continue;
+        }
+        validNames.push(resolved.name);
+        const model = resolved.profile.model ? `, model ${resolved.profile.model}` : "";
+        lines.push(`- ${resolved.name}${markers} ${sourceBadge(resolved.source)}: instance ${resolved.instanceName} (${resolved.kind}, ${resolved.providerSource})${model}`);
+        if (resolved.profile.description) {
+            lines.push(`  ${resolved.profile.description}`);
+        }
+    }
+    for (const shadow of catalog.shadows) {
+        lines.push(`- ${shadow.name} [${shadow.source}] (shadowed by ${shadow.shadowedBy})`);
+    }
+    const hintName = chooseCallHintName(validNames, settings);
+    if (hintName !== null) {
+        lines.push("");
+        lines.push("Call one:");
+        lines.push(`  » keiyaku call ${hintName} "your task"`);
+    }
+    return lines.join("\n");
+}
+export function renderAkumaShow(catalog, providerInstances, settings, name) {
+    const candidate = catalog.selected[name];
+    if (candidate === undefined) {
         throw new FlowError("UNKNOWN_SUBAGENT", `Unknown agent '${name}'.`);
     }
-    const profile = normalizeAkumaProfile(definition.profile);
-    const promptLines = definition.body === "" ? [] : definition.body.split(/\r?\n/);
+    const resolved = resolveAkumaInspection(candidate, providerInstances);
     const lines = [
-        `Akuma: ${name}`,
-        `source: ${sourceBadge(definition)}`,
-        `definition file: ${definition.path ?? "(built-in)"}`,
-        `roles: ${formatRoleMarkers(settings, name).replace(/^\s*\(|\)$/g, "") || "(none)"}`,
-        `provider: ${profile.provider}`,
-        `executable: ${profile.executable}`,
+        `Akuma: ${resolved.name}`,
+        `source: ${sourceBadge(resolved.source)}`,
+        `definition file: ${resolved.path ?? "(built-in)"}`,
+        `roles: ${formatRoleMarkers(settings, resolved.name).replace(/^\s*\(|\)$/g, "") || "(none)"}`,
+        `validity: ${resolved.status}`,
     ];
-    appendOptionalLine(lines, "description", profile.description);
-    appendOptionalLine(lines, "model", profile.model);
-    if (profile.provider === "codex-sdk") {
-        appendOptionalLine(lines, "profile", profile.profile);
-        appendOptionalLine(lines, "config", profile.config);
+    if (resolved.status === "invalid") {
+        lines.push(`reason: ${resolved.reason}`);
+        return lines.join("\n");
     }
-    if (profile.provider === "claude-agent-sdk") {
-        appendOptionalLine(lines, "effort", profile.effort);
-        appendOptionalLine(lines, "permissionMode", profile.permissionMode);
-        appendOptionalLine(lines, "settingSources", profile.settingSources);
+    lines.push(`provider instance: ${resolved.instanceName}`);
+    lines.push(`provider kind: ${resolved.kind}`);
+    lines.push(`provider source: ${sourceBadge(resolved.providerSource)}`);
+    lines.push("provider validity: valid");
+    lines.push(`provider fields: ${JSON.stringify(resolved.instance)}`);
+    for (const shadow of resolved.providerShadows) {
+        lines.push(`provider shadow: ${sourceBadge(shadow.source)} shadowed by ${shadow.shadowedBy}`);
     }
-    lines.push("prompt:");
-    lines.push(...promptLines.slice(0, 8).map((line) => `  ${line}`));
-    lines.push(`(${promptLines.length} lines total)`);
+    appendOptionalLine(lines, "description", resolved.profile.description);
+    appendOptionalLine(lines, "model", resolved.profile.model);
+    appendOptionalLine(lines, "effort", resolved.profile.effort);
+    appendOptionalLine(lines, "effortOptions", resolved.profile.effortOptions);
+    appendOptionalLine(lines, "access", resolved.profile.access);
+    appendOptionalLine(lines, "network", resolved.profile.network);
+    appendOptionalLine(lines, "webSearch", resolved.profile.webSearch);
+    appendPromptPreview(lines, resolved.body);
     return lines.join("\n");
 }

package/build/cli/completion.js

@@ -1,13 +1,12 @@
 import { assertSettingsKnobUsable, loadKeiyakuSettings } from "../config/settings.js";
-import { loadAkumaCatalog } from "../config/akuma-loader.js";
-import { listContractIds } from "../core/status.js";
+import { loadAkumaCatalogV2 } from "../config/akuma-loader_v2.js";
+import { listContractIds } from "../core/ledger.js";
 const TOP_LEVEL_COMMANDS = [
     "bind",
     "arc",
-    "summon",
-    "ask",
+    "call",
     "tell",
-    "resume",
+    "revive",
     "log",
     "akuma",
     "skills",
@@ -29,14 +28,14 @@ async function contractAddressCandidates(cwd, word) {
 async function akumaCandidates(cwd, word) {
     const loaded = await loadKeiyakuSettings(cwd);
     assertSettingsKnobUsable(loaded, "agents");
-    return filterPrefix(Object.keys((await loadAkumaCatalog(cwd)).definitions), word);
+    return filterPrefix(Object.keys((await loadAkumaCatalogV2(cwd)).selected), word);
 }
 export async function renderCompletionCandidates(input) {
     const word = input.word ?? "";
     if (word.startsWith("@")) {
         return (await contractAddressCandidates(input.cwd, word)).join("\n");
     }
-    if (input.previous === "summon" || input.previous === "ask" || input.previous === "show") {
+    if (input.previous === "call" || input.previous === "show") {
         return (await akumaCandidates(input.cwd, word)).join("\n");
     }
     if (input.previous === "akuma") {

package/build/cli/flags.js

@@ -4,9 +4,19 @@ export const FLAG_SPECS = {
     cwd: {
         kind: "value",
         placeholder: "DIR",
-        description: "Run against another repository. Defaults to the current working directory.",
+        description: "Select the effective command directory (-C/--cwd). Defaults to the process working directory.",
     },
-    agent: {
+    repo: {
+        kind: "value",
+        placeholder: "DIR",
+        description: "Select the repository that supplies contract ledgers.",
+    },
+    contract: {
+        kind: "value",
+        placeholder: "ADDR",
+        description: "Select a commission by place, slug, or full id (same namespace as @addr).",
+    },
+    akuma: {
         kind: "value",
         placeholder: "NAME",
         description: `Start a new ${ACTOR_IDENTITY} session with the configured agent name.`,
@@ -19,28 +29,33 @@ export const FLAG_SPECS = {
     effort: {
         kind: "value",
         placeholder: "LEVEL",
-        description: "Override effort for the generation being launched: low, medium, high, or max.",
+        description: "Override effort for the generation being launched with an opaque provider-native value.",
     },
     projection: {
         kind: "value",
         placeholder: "ID",
-        description: "Projection id for an explicit terminal recovery override.",
+        description: "Akuma projection id.",
+    },
+    timeout: {
+        kind: "value",
+        placeholder: "DURATION",
+        description: "Wait at most a positive duration such as 45s, 5m, or 2h (maximum 24h).",
     },
     incognito: {
         kind: "boolean",
-        description: "Do not persist response history and do not allow resume.",
+        description: "Do not persist response history and do not allow revive.",
     },
     bare: {
         kind: "boolean",
         description: "Skip contract attachment; Akuma, history, sandbox, credentials, projection, and repository policy remain active.",
     },
-    "draft-only": {
+    detach: {
         kind: "boolean",
-        description: "Write a draft artifact without creating a contract workspace.",
+        description: "Return after durable launch instead of waiting for completion.",
     },
-    worktree: {
+    "draft-only": {
         kind: "boolean",
-        description: "Bind the contract in a separate worktree instead of the current workspace.",
+        description: "Write a draft artifact without creating a contract workspace.",
     },
     exclusive: {
         kind: "boolean",
@@ -53,7 +68,7 @@ export const FLAG_SPECS = {
     },
     force: {
         kind: "boolean",
-        description: "Replace an existing installed Keiyaku skill link or directory.",
+        description: "Replace an existing installed Keiyaku skill link or directory for any bundled skill.",
     },
     reason: {
         kind: "value",
@@ -64,6 +79,11 @@ export const FLAG_SPECS = {
         kind: "boolean",
         description: "Preview claim effects without changing refs, ledgers, queue, registry, or worktrees.",
     },
+    waive: {
+        kind: "value",
+        placeholder: "PATH",
+        description: "Allow one explicit out-of-scope path for this seal. May be repeated.",
+    },
     shell: {
         kind: "value",
         placeholder: "SHELL",
@@ -83,6 +103,11 @@ export const FLAG_SPECS = {
         kind: "boolean",
         description: "Print completion candidates instead of a shell installation script.",
     },
+    target: {
+        kind: "value",
+        placeholder: "REF",
+        description: "Filter target-keyed status facts by branch name or full refs/heads/<name>.",
+    },
 };
 export const CONTROL_FLAGS = new Set(Object.keys(FLAG_SPECS));
 export const VALUE_FLAGS = new Set(Object.entries(FLAG_SPECS)
@@ -92,5 +117,6 @@ export const BOOLEAN_FLAGS = new Set(Object.entries(FLAG_SPECS)
     .filter(([, spec]) => spec.kind === "boolean")
     .map(([name]) => name));
 export const SHORT_FLAG_ALIASES = {
+    C: "cwd",
     f: "force",
 };

package/build/cli/help.js

@@ -3,30 +3,36 @@ function command(name, summary, usage, stdin, flags, purpose, extra = {}) {
     return { command: name, summary, usage, stdin, flags, purpose, ...extra };
 }
 export const CLI_COMMAND_METADATA = {
-    bind: command("bind", "Create a contract ledger and workspace files", ["keiyaku bind [--cwd DIR] [--worktree] < keiyaku.md"], "required", ["cwd", "worktree", "after", "exclusive", "draft-only"], "Bind a Keiyaku from a contract draft."),
-    arc: command("arc", "Open the next arc and seal the current arc", ["keiyaku arc [--cwd DIR] < arc.md"], "required", ["cwd"], "Record the next title, objective, and brief. An open arc is sealed first.", {
+    bind: command("bind", "Create a contract ledger and workspace files", ["keiyaku bind [-C|--cwd DIR] [--repo DIR] < keiyaku.md"], "required", ["cwd", "repo", "after", "exclusive", "draft-only"], "Bind a Keiyaku from a contract draft.", {
+        notes: ["bind creates a commission and does not accept @addr or --contract."],
+    }),
+    arc: command("arc", "Open the next arc and seal the current arc", ["keiyaku arc [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--waive PATH] < arc.md", "keiyaku @addr arc [-C|--cwd DIR] [--repo DIR] [--waive PATH] < arc.md"], "required", ["cwd", "repo", "contract", "waive"], "Record the next title, objective, and brief. An open arc is sealed first.", {
         input: ["# <arc title>", "", "## Objective", "<what this arc should accomplish>", "", "## Brief", "<scope, constraints, relevant files, instructions>"],
         notes: ["An empty seal is valid.", "The command does not create delivery commits."],
     }),
-    summon: command("summon", "Start an Akuma helper session", ["keiyaku summon NAME [prompt|-]"], "none", ["cwd", "agent", "model", "effort", "incognito", "bare"], "Run a scoped helper task."),
-    ask: command("ask", "Start an Akuma helper session", ["keiyaku ask NAME [prompt|-]"], "none", ["cwd", "agent", "model", "effort", "incognito", "bare"], "Run a scoped helper task."),
-    resume: command("resume", "Resume an Akuma helper session", ["keiyaku resume RESPONSE_PATH [prompt|-]", "keiyaku resume --projection ID [--effort LEVEL]"], "none", ["cwd", "model", "effort", "projection"], "Continue a persisted helper session."),
-    tell: command("tell", "Send intent to a projection mailbox", ["keiyaku tell [--effort LEVEL] PROJECTION MESSAGE"], "none", ["cwd", "effort"], "Write intent to the mailbox and wake only when eligible."),
-    log: command("log", "Render a contract ledger", ["keiyaku log [@id] [--cwd DIR]"], "none", ["cwd"], "Read a contract ledger."),
-    akuma: command("akuma", "Inspect Akuma profiles", ["keiyaku akuma list|show"], "none", [], "Inspect configured helper profiles.", { subcommands: ["list", "ls", "show"] }),
-    "akuma ls": command("akuma ls", "List Akuma profiles", ["keiyaku akuma ls [--cwd DIR]"], "none", ["cwd"], "List configured helper profiles."),
-    "akuma list": command("akuma list", "List Akuma profiles", ["keiyaku akuma list [--cwd DIR]"], "none", ["cwd"], "List configured helper profiles."),
-    "akuma show": command("akuma show", "Show an Akuma profile", ["keiyaku akuma show NAME [--cwd DIR]"], "none", ["cwd"], "Show one configured helper profile."),
+    call: command("call", "Start an Akuma helper session", ["keiyaku call NAME [prompt|-]", "keiyaku call NAME --detach [prompt|-]", "keiyaku @addr call NAME [prompt|-]", "keiyaku call NAME --contract ADDR [prompt|-]"], "none", ["cwd", "repo", "contract", "akuma", "model", "effort", "incognito", "bare", "detach"], "Run a scoped helper task."),
+    revive: command("revive", "Revive an Akuma helper session", ["keiyaku revive ARTIFACT_ID"], "none", ["cwd", "repo", "model", "effort"], "Continue a persisted helper session."),
+    wait: command("wait", "Wait for an akuma projection", ["keiyaku wait <short-id> [--timeout DURATION]", "keiyaku @addr wait <short-id> [--timeout DURATION]"], "none", ["cwd", "repo", "contract", "timeout"], "Read an akuma projection until its outcome is available, or show a timeout snapshot."),
+    tell: command("tell", "Send intent to a projection mailbox", ["keiyaku tell [--effort LEVEL] PROJECTION MESSAGE", "keiyaku @addr tell [--effort LEVEL] PROJECTION MESSAGE"], "none", ["cwd", "repo", "contract", "effort"], "Write intent to the mailbox and wake only when eligible."),
+    log: command("log", "Render a contract ledger", ["keiyaku log [-C|--cwd DIR] [--repo DIR] [--contract ADDR]", "keiyaku @addr log [-C|--cwd DIR] [--repo DIR]"], "none", ["cwd", "repo", "contract"], "Read a contract ledger."),
+    akuma: command("akuma", "Inspect Akuma profiles", ["keiyaku akuma list|show"], "none", [], "Inspect configured helper profiles.", {
+        subcommands: ["list", "ls", "show"],
+        notes: ["Define user profiles in <KEIYAKU_HOME>/akuma/<name>.md.", "Define project profiles in .keiyaku/akuma/<name>.md.", "See README Configuration for the Markdown frontmatter format."],
+        examples: ["keiyaku akuma list", "keiyaku akuma show akuma-codex"],
+    }),
+    "akuma ls": command("akuma ls", "List Akuma profiles", ["keiyaku akuma ls [-C|--cwd DIR] [--repo DIR]"], "none", ["cwd", "repo"], "List configured helper profiles.", { notes: ["Project profiles override user profiles, which override builtins."] }),
+    "akuma list": command("akuma list", "List Akuma profiles", ["keiyaku akuma list [-C|--cwd DIR] [--repo DIR]"], "none", ["cwd", "repo"], "List configured helper profiles.", { notes: ["Project profiles override user profiles, which override builtins."] }),
+    "akuma show": command("akuma show", "Show an Akuma profile", ["keiyaku akuma show NAME [-C|--cwd DIR] [--repo DIR]"], "none", ["cwd", "repo"], "Show one configured helper profile.", { notes: ["The output identifies the winning source and normalized provider configuration."] }),
     skills: command("skills", "Install official skills", ["keiyaku skills install"], "none", [], "Install bundled official Keiyaku skills into supported agent skill directories.", { subcommands: ["install"] }),
-    "skills install": command("skills install", "Install the official Keiyaku skill", ["keiyaku skills install [-f|--force]"], "none", ["force"], "Install the bundled official Keiyaku skill into supported agent skill directories.", { notes: ["Force permits replacement of foreign collisions."] }),
-    amend: command("amend", "Record an amendment", ["keiyaku amend [--cwd DIR] < amendment.md"], "required", ["cwd"], "Append a prose amendment and optional structured scope delta."),
-    renew: command("renew", "Rewrite delivery onto the current base", ["keiyaku renew [--cwd DIR]", "keiyaku @<id> renew [--cwd DIR]"], "none", ["cwd"], "Capture receipts, rewrite delivery onto the default branch, then seal and record the renewal.", { notes: ["Refuses loose commits without an open arc.", "Refuses while an Akuma is in flight.", "Conflicts restore the worktree without ledger writes."] }),
-    petition: command("petition", "Run the gated settlement pipeline", ["keiyaku petition [--cwd DIR]", "keiyaku @<id> petition [--cwd DIR]"], "none", ["cwd"], "Seal an open arc, queue the contract, and run verdict and claim processing.", { notes: ["Base drift requires explicit `keiyaku renew` before petition."] }),
-    forfeit: command("forfeit", "Forfeit an addressed contract", ["keiyaku forfeit [--cwd DIR] [--reason TEXT]"], "none", ["cwd", "reason"], "Record an abandoned contract without sealing it."),
+    "skills install": command("skills install", "Install the official Keiyaku skills", ["keiyaku skills install [-f|--force]"], "none", ["force"], "Install the bundled official Keiyaku skills into supported agent skill directories.", { notes: ["Force permits replacement of foreign collisions."] }),
+    amend: command("amend", "Record an amendment", ["keiyaku amend [-C|--cwd DIR] [--repo DIR] [--contract ADDR] < amendment.md", "keiyaku @addr amend [-C|--cwd DIR] [--repo DIR] < amendment.md"], "required", ["cwd", "repo", "contract"], "Append a prose amendment and optional structured scope delta."),
+    renew: command("renew", "Rewrite delivery onto the current base", ["keiyaku renew [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--waive PATH]", "keiyaku @<id> renew [-C|--cwd DIR] [--repo DIR] [--waive PATH]"], "none", ["cwd", "repo", "contract", "waive"], "Capture receipts, rewrite delivery onto the default branch, then seal and record the renewal.", { notes: ["Refuses loose commits without an open arc.", "Refuses while an Akuma is in flight.", "Conflicts restore the worktree without ledger writes."] }),
+    petition: command("petition", "Run the gated settlement pipeline", ["keiyaku petition [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--waive PATH]", "keiyaku @<id> petition [-C|--cwd DIR] [--repo DIR] [--waive PATH]"], "none", ["cwd", "repo", "contract", "waive"], "Seal an open arc, queue the contract, and run verdict and claim processing.", { notes: ["Base drift requires explicit `keiyaku renew` before petition."] }),
+    forfeit: command("forfeit", "Forfeit an addressed contract", ["keiyaku forfeit [-C|--cwd DIR] [--repo DIR] [--contract ADDR] [--reason TEXT]", "keiyaku @addr forfeit [-C|--cwd DIR] [--repo DIR] [--reason TEXT]"], "none", ["cwd", "repo", "contract", "reason"], "Record an abandoned contract without sealing it."),
     guide: command("guide", "Print the Keiyaku guide", ["keiyaku guide"], "none", [], "Print workflow guidance."),
-    completion: command("completion", "Print shell completion", ["keiyaku completion [--shell bash|zsh]"], "none", ["cwd", "shell", "word", "previous", "complete"], "Print command and address candidates."),
-    status: command("status", "Show the Kanshi board", ["keiyaku status [--cwd DIR]"], "none", ["cwd"], "Read contract, queue, and projection facts without mutation."),
-    "dump-env": command("dump-env", "Print the environment template", ["keiyaku dump-env"], "none", [], "Print supported environment keys."),
+    completion: command("completion", "Print shell completion", ["keiyaku completion [--shell bash|zsh]"], "none", ["cwd", "repo", "shell", "word", "previous", "complete"], "Print command and address candidates."),
+    status: command("status", "Show the Kanshi board", ["keiyaku status [-C|--cwd DIR] [--repo DIR] [--target REF]"], "none", ["cwd", "repo", "target"], "Read contract, queue, and projection facts without mutation."),
+    "dump-env": command("dump-env", "Print the environment template", ["keiyaku dump-env"], "none", [], "Print supported environment keys.", { notes: ["Keiyaku loads <KEIYAKU_HOME>/.env, then .keiyaku/.env; process environment values win."] }),
 };
 function indent(lines) {
     return lines.map((line) => line ? `  ${line}` : "");
@@ -38,6 +44,9 @@ function section(lines, title, body) {
 }
 function flagUsage(name, specs) {
     const spec = specs[name];
+    if (name === "cwd") {
+        return `-C, --cwd ${spec?.placeholder ?? "DIR"}`;
+    }
     return spec?.kind === "value" ? `--${name} ${spec.placeholder ?? "VALUE"}` : `--${name}`;
 }
 export function formatSubcommandList(subcommands) {
@@ -62,7 +71,7 @@ export function renderCliHelp(version) {
         "",
         "Usage:",
         "  keiyaku <command> [flags]",
-        "  keiyaku @<id-prefix> <command> [flags]",
+        "  keiyaku @<commission> <command> [flags]",
         "",
         "Flow:",
         "  bind -> arc -> delivery work -> arc | renew | petition",
@@ -71,9 +80,9 @@ export function renderCliHelp(version) {
         "  bind       Create a contract ledger and workspace files.",
         "  arc        Open the next arc; seals an open arc first.",
         "  renew      Rewrite delivery onto the current base and seal it.",
-        "  summon     Start an Akuma helper session.",
-        "  ask        Start an Akuma helper session.",
-        "  resume     Resume an Akuma helper session.",
+        "  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.",
         "  log        Render a contract ledger.",
         "  akuma      Inspect helper profiles.",
@@ -88,7 +97,14 @@ export function renderCliHelp(version) {
         "",
         "Input:",
         "  bind, arc, and amend read Markdown from stdin.",
-        "  summon, ask, and resume read a prompt argument or stdin.",
+        "  call and revive read a prompt argument or stdin.",
+        "",
+        "Configuration:",
+        "  Akuma profiles  <KEIYAKU_HOME>/akuma/*.md or .keiyaku/akuma/*.md",
+        "  Settings        <KEIYAKU_HOME>/settings.json or .keiyaku/settings.json",
+        "  Inspect         keiyaku akuma list | keiyaku akuma show NAME",
+        "  Environment     keiyaku dump-env",
+        "  Full format     README Configuration",
     ].join("\n");
 }
 export function buildKeiyakuGuide(version) {
@@ -101,8 +117,8 @@ export function buildKeiyakuGuide(version) {
         "- `arc` records intent and seals the prior open arc automatically.",
         "- `renew` captures old receipts before rewriting delivery onto the default branch.",
         "- `petition` seals an open arc, requires a fresh base, and starts settlement.",
-        "- `summon`, `ask`, and `resume` provide helper execution without changing the ledger lifecycle.",
-        "- `skills install` installs the bundled official Keiyaku skill into supported agent skill directories; force permits replacement of foreign collisions.",
+        "- `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.",
     ].join("\n");
 }