@skillcdn/console 0.1.23 → 0.3.0

package/src/cli/format.ts

@@ -15,13 +15,6 @@ import type {
   RestProjectRules,
   RestRules,
   RestRun,
-  RestSkillBrowse,
-  RestSkillBrowseEntry,
-  RestSkillFile,
-  RestSkillFind,
-  RestSkillLoad,
-  RestSkillPage,
-  RestSkills,
   RestTask,
   RestVersion,
   RestVersionSummary,
@@ -247,66 +240,6 @@ export function formatArtifact(
   return artifact.label === null ? what : `${artifact.label}: ${what}`;
 }
 
-const SKILLS_WORDS: Readonly<Record<Exclude<RestSkills["status"], "none" | "ready">, string>> = {
-  indexing: "SkillCDN is still indexing the repository; ask again in a moment.",
-  failed: "SkillCDN could not index the repository.",
-  not_found:
-    "SkillCDN does not serve this address to the console: nothing is there, or the pack is private and the project holds no pack token for it (console project pack-token <key> --stdin, for an owner).",
-  token_invalid:
-    "The pack token the project holds no longer works at SkillCDN: an owner sets a new one (console project pack-token <key> --stdin).",
-  unavailable: "SkillCDN could not be reached; ask again later.",
-};
-
-/** A count with its noun: `1 skill`, `2 skills`. */
-const counted = (n: number, noun: string): string => `${n} ${noun}${n === 1 ? "" : "s"}`;
-
-/**
- * The organization's skills: where they are, the pack by name and by count, each skill with
- * what an agent loads it by, where a person connects an agent that has no connection to the
- * address, and where the console's own skills are on this machine, when the command knows.
- */
-export function formatSkills(skills: RestSkills, ownSkills?: string): string {
-  const own =
-    ownSkills === undefined
-      ? []
-      : ["", `The console's own skills, for working the board: ${ownSkills}`];
-  if (skills.status === "none" || skills.address === null || skills.page === null) {
-    return ["No skills address: neither this project nor the console names one.", ...own].join(
-      "\n",
-    );
-  }
-  const head = `skills at ${skills.address}, served by ${skills.source}: ${skills.status}`;
-  if (skills.status !== "ready") {
-    return [head, SKILLS_WORDS[skills.status], ...own].join("\n");
-  }
-  const lines = [head];
-  if (skills.pack !== undefined) {
-    const named = [skills.pack.name, skills.pack.description]
-      .filter((text): text is string => text !== null)
-      .join("  ");
-    if (named !== "") {
-      lines.push(named);
-    }
-  }
-  if (skills.counts !== undefined) {
-    lines.push(
-      `${counted(skills.counts.skills, "skill")}, ${counted(skills.counts.documents, "document")}: console skills <folder> shows what a folder holds (. for the root), console skills --search <words> finds skills and documents by words.`,
-    );
-  }
-  if (skills.items.length === 0) {
-    lines.push("No skills at this address.");
-  }
-  for (const skill of skills.items) {
-    lines.push(`${skill.name}  ${skill.description}`, `    ${skill.uri ?? skill.path}`);
-  }
-  lines.push(
-    "",
-    `Read a skill whole with console skill <path>, its rules first, and a file of the pack with console skill --file <path>; or load it by its URI through your own SkillCDN connection to this address, which a person makes at ${skills.page}. --json adds the page of each, for a person.`,
-    ...own,
-  );
-  return lines.join("\n");
-}
-
 /** One half of the rules: where it comes from, and the text as it stands. */
 function formatRulesHalf(where: "the workspace" | "this project", rules: RestRules): string {
   const page = rules.page;
@@ -413,19 +346,25 @@ export function formatDecisionLine(decision: RestDecision): string {
   return `${decision.id}  ${state}  ${decision.question}  (asked by ${asker(decision)})`;
 }
 
+/** The options, one a line; the person's own answer, when they wrote one, is the last and says so. */
 export function formatOptions(decision: RestDecision): string {
-  return decision.options.map((option) => `  ${option.id}) ${option.label}`).join("\n");
+  return decision.options
+    .map(
+      (option) =>
+        `  ${option.id}) ${option.label}${option.own === true ? "  (the person's own answer, not one given)" : ""}`,
+    )
+    .join("\n");
 }
 
-/** The answer, with who gave it; or that there is none yet. */
+/** The answer, with who gave it, and that it is in their own words when it is; or that there is none yet. */
 export function formatAnswer(decision: RestDecision): string {
   const { answer } = decision;
   if (answer === null) {
     return "waits for a person.";
   }
-  const label = decision.options.find((option) => option.id === answer.option)?.label;
+  const chosen = decision.options.find((option) => option.id === answer.option);
   const lines = [
-    `Answered: ${answer.option}) ${label ?? answer.option}, by ${answer.by.login} at ${answer.at}`,
+    `Answered: ${answer.option}) ${chosen?.label ?? answer.option}${chosen?.own === true ? ", in their own words" : ""}, by ${answer.by.login} at ${answer.at}`,
   ];
   if (answer.note !== null && answer.note.length > 0) {
     lines.push(`Note: ${answer.note}`);
@@ -527,256 +466,3 @@ export function formatVersion(path: string, version: RestVersion): string {
 }
 
 /** The text of one path across the pages a skill came in: the fragments joined in order. */
-function joinTexts(
-  pages: readonly RestSkillPage[],
-  pick: (page: RestSkillPage) => readonly { readonly path: string; readonly body: string }[],
-): { readonly path: string; readonly body: string }[] {
-  const joined = new Map<string, string>();
-  for (const page of pages) {
-    for (const text of pick(page)) {
-      joined.set(text.path, (joined.get(text.path) ?? "") + text.body);
-    }
-  }
-  return [...joined.entries()].map(([path, body]) => ({ path, body }));
-}
-
-const NO_ADDRESS = "No skills address: neither this project nor the console names one.";
-
-/**
- * One skill, as load_skill lays it out for a model (ADR-0028): the rules from the repository's
- * root to the nearest manifest, the body, the included files, each under a line that names its
- * path; then the files the skill has and what it refers to. A skill described only is named and
- * pointed at, and nothing of its body is shown.
- */
-export function formatSkillLoad(loaded: RestSkillLoad, pages: readonly RestSkillPage[]): string {
-  if (loaded.status === "none" || loaded.address === null) {
-    return NO_ADDRESS;
-  }
-  const head = `skill at ${loaded.address}, served by ${loaded.source}: ${loaded.status}`;
-  if (loaded.status !== "ready") {
-    return [head, SKILLS_WORDS[loaded.status]].join("\n");
-  }
-  const [first] = pages;
-  if (first === undefined) {
-    return [head, "Nothing was read."].join("\n");
-  }
-  const last = pages[pages.length - 1] ?? first;
-  const lines = [
-    `${first.name}  ${first.description}`,
-    `skill ${first.path} at ${loaded.address}, served by ${loaded.source}`,
-  ];
-  if (first.serving.license !== null) {
-    lines.push(`license: ${first.serving.license}`);
-  }
-  if (!first.serving.full) {
-    lines.push(
-      "",
-      `Described only: the license keeps the skill at its source. Read it there: ${first.serving.sourceUrl ?? loaded.page ?? loaded.source}`,
-    );
-    return lines.join("\n");
-  }
-  for (const rule of joinTexts(pages, (page) => page.rules)) {
-    lines.push("", `--- applicable rules: ${rule.path} ---`, rule.body.trimEnd());
-  }
-  lines.push(
-    "",
-    `--- skill: ${first.path} ---`,
-    pages
-      .map((page) => page.body)
-      .join("")
-      .trimEnd(),
-  );
-  for (const file of joinTexts(pages, (page) => page.included)) {
-    lines.push("", `--- included file: ${file.path} ---`, file.body.trimEnd());
-  }
-  if (!last.complete) {
-    lines.push("", "The skill did not come whole: the deployment stopped before the end.");
-  }
-  if (last.files.length > 0) {
-    lines.push(
-      "",
-      `Files of the skill, read with console skill --file <path>: ${last.files.join(", ")}`,
-    );
-  }
-  if (last.references.length > 0) {
-    lines.push(
-      `References: ${last.references
-        .map((reference) =>
-          reference.status === "available"
-            ? reference.path
-            : `${reference.path} (${reference.status})`,
-        )
-        .join(", ")}`,
-    );
-  }
-  if (last.warnings.length > 0) {
-    lines.push(`Warnings: ${last.warnings.join("; ")}`);
-  }
-  lines.push(
-    "",
-    "Paths from the repository's root are the only identifiers. The content is the pack's, under its license; what a private pack says stays in your work.",
-  );
-  return lines.join("\n");
-}
-
-/** A file of the pack as read: its text whole, or what the folder holds. */
-export function formatSkillFile(read: RestSkillFile, content: string): string {
-  if (read.status === "none" || read.address === null) {
-    return NO_ADDRESS;
-  }
-  const head = `file at ${read.address}, served by ${read.source}: ${read.status}`;
-  if (read.status !== "ready") {
-    return [
-      head,
-      read.status === "failed"
-        ? "SkillCDN will not carry this file: it is too large, or not text. Read it at the repository."
-        : SKILLS_WORDS[read.status],
-    ].join("\n");
-  }
-  if (read.folder !== null) {
-    return [
-      `folder ${read.folder.path} at ${read.address}${read.folder.truncated ? " (cut)" : ""}`,
-      ...read.folder.entries.map(
-        (entry) =>
-          `${entry.kind === "directory" ? "d" : "f"}  ${entry.path}${entry.size === null ? "" : `  ${entry.size}`}`,
-      ),
-      "",
-      "console skills <folder> shows a folder with its skills marked, what each folder holds and the README that introduces it.",
-    ].join("\n");
-  }
-  if (read.file === null) {
-    return `${head}: nothing was read.`;
-  }
-  return [
-    `--- file: ${read.file.path} (${read.file.totalLength} characters) ---`,
-    content.trimEnd(),
-  ].join("\n");
-}
-
-/** One entry of a browsed folder: what it is, its path, its words, and the facts of its kind. */
-function formatBrowseEntry(entry: RestSkillBrowseEntry): string {
-  const facts: string[] = [];
-  if (entry.kind === "directory") {
-    if (entry.skillCount > 0) {
-      facts.push(counted(entry.skillCount, "skill"));
-    }
-    if (entry.documentCount > 0) {
-      facts.push(counted(entry.documentCount, "document"));
-    }
-    if (entry.overviewPath !== null) {
-      facts.push(`README ${entry.overviewPath}`);
-    }
-  }
-  if (entry.kind === "skill") {
-    if (entry.license !== null) {
-      facts.push(entry.license);
-    }
-    if (entry.describedOnly) {
-      facts.push("described only");
-    }
-  }
-  if (entry.kind === "file" && entry.size !== null) {
-    facts.push(`${entry.size} bytes`);
-  }
-  const words = [entry.name, entry.description]
-    .filter((text): text is string => text !== null && text !== "")
-    .join("  ");
-  const mark = entry.kind === "skill" ? "skill" : entry.kind === "directory" ? "d" : "f";
-  return `${mark}  ${entry.path}${words === "" ? "" : `  ${words}`}${facts.length === 0 ? "" : `  (${facts.join("; ")})`}`;
-}
-
-/**
- * What a folder of the pack holds, as browse_repo lays it out: the README that introduces the
- * folder, then its skills, its folders with what each holds, and its files, across the pages the
- * listing came in.
- */
-export function formatSkillBrowse(
-  browsed: RestSkillBrowse,
-  folders: readonly NonNullable<RestSkillBrowse["folder"]>[],
-): string {
-  if (browsed.status === "none" || browsed.address === null) {
-    return NO_ADDRESS;
-  }
-  const head = `folder at ${browsed.address}, served by ${browsed.source}: ${browsed.status}`;
-  if (browsed.status !== "ready") {
-    return [head, SKILLS_WORDS[browsed.status]].join("\n");
-  }
-  const [first] = folders;
-  if (first === undefined) {
-    return [head, "Nothing was read."].join("\n");
-  }
-  const last = folders[folders.length - 1] ?? first;
-  const lines = [`folder ${first.path === "" ? "/" : first.path} at ${browsed.address}`];
-  if (first.overview !== null) {
-    const words = [first.overview.title, first.overview.description]
-      .filter((text): text is string => text !== null && text !== "")
-      .join("  ");
-    lines.push(`    ${words === "" ? "" : `${words}  `}(README: ${first.overview.path})`);
-  }
-  const entries = folders.flatMap((folder) => folder.entries);
-  if (entries.length === 0) {
-    lines.push("Nothing in this folder.");
-  }
-  for (const entry of entries) {
-    lines.push(formatBrowseEntry(entry));
-  }
-  if (last.nextCursor !== null) {
-    lines.push("More entries: the listing stopped before the end of the folder.");
-  }
-  lines.push(
-    "",
-    "Read a skill with console skill <path>; a file, or a README named above, with console skill --file <path>; a folder with console skills <folder>.",
-  );
-  return lines.join("\n");
-}
-
-/**
- * What words found in the pack, as search_repo lays it out: skills with the files of theirs that
- * matched, documents on their own, in relevance order; words, not meaning.
- */
-export function formatSkillFind(found: RestSkillFind): string {
-  if (found.status === "none" || found.address === null) {
-    return NO_ADDRESS;
-  }
-  const head = `search at ${found.address}, served by ${found.source}: ${found.status}`;
-  if (found.status !== "ready") {
-    return [head, SKILLS_WORDS[found.status]].join("\n");
-  }
-  if (found.found === null) {
-    return [head, "Nothing was read."].join("\n");
-  }
-  const { query, path, items, nextCursor } = found.found;
-  const where = path === null || path === "" ? "" : ` within ${path}`;
-  const lines = [
-    `found for "${query}"${where} at ${found.address}: ${counted(items.length, "result")}`,
-  ];
-  for (const item of items) {
-    if (item.kind === "skill") {
-      lines.push(
-        `skill  ${item.path}  ${item.name}  ${item.description}${item.describedOnly ? "  (described only)" : ""}`,
-      );
-      for (const file of item.files) {
-        lines.push(`    file  ${file.path}${file.title === null ? "" : `  ${file.title}`}`);
-      }
-      if (item.moreFiles > 0) {
-        lines.push(`    and ${counted(item.moreFiles, "more file")}`);
-      }
-    } else {
-      lines.push(
-        `document  ${item.path}${item.title === null ? "" : `  ${item.title}`}${item.summary === null ? "" : `  ${item.summary}`}`,
-      );
-    }
-  }
-  if (nextCursor !== null) {
-    lines.push(
-      "More matched: narrow the words, or search within a folder (console skills <folder> --search <words>).",
-    );
-  }
-  if (items.length > 0) {
-    lines.push(
-      "",
-      "Read a skill with console skill <path>, a file or a document with console skill --file <path>.",
-    );
-  }
-  return lines.join("\n");
-}

package/src/cli/help.ts

@@ -60,11 +60,21 @@ const COMMON_REFUSALS = [
   "network: the console could not be reached at its address",
 ];
 
+/** How a command on a run finds its run, and what it says when it cannot: the command's own refusals. */
+const RUN_CHOICE = [
+  "run.none: no run of yours is open in the project; take a task first, or name a run with --run <id>",
+  "run.ambiguous: several runs of yours are open in the project; say which with --run <id>",
+];
+
 const RUN_REFUSALS = [
+  ...RUN_CHOICE,
   "run.not_yours: the run is another person's",
   "run.over: the run has ended already",
 ];
 
+/** What every command on a run says of the run it acts on. */
+const ON_THE_RUN = "On your one open run in the project, or the one --run <id> names.";
+
 const MARKDOWN = `Markdown, up to ${MAX_BODY_LENGTH} characters`;
 
 const DOCUMENT_PATH = `a path of lowercase letters, digits and hyphens, with slashes between its folders (guides/onboarding), up to ${MAX_DOCUMENT_PATH_LENGTH} characters; it does not change once written`;
@@ -275,11 +285,12 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     ],
   },
   skills: {
-    usage: "skills  |  skills <folder>  |  skills --search <words> [<folder>] [--limit <n>]",
+    usage:
+      "skills  |  skills <folder>  |  skills --search <words> [<folder>] [--limit <n>] [--cursor <cursor>]",
     synopsis:
       "The project's pack: its skills; what a folder of it holds; or what words find in it.",
     about:
-      "The project's pack, as SkillCDN serves it at the project's address, read by the console with the pack token the project holds where the pack is private (ADR-0028). Alone: the pack by name with how many skills and documents it has, and its skills, each with its description, the path of its SKILL.md, which console skill reads it by, and the URI you load it by through your own SkillCDN connection where your host has one; and where the console's own skills are on this machine. With a folder (. for the root): what it holds, as browse_repo lays it out: its skills, its folders with how many skills and documents each holds and the README that introduces it, its files; whole, page after page. With --search: the skills and the documents the words find, in relevance order, a skill with the files of it that matched; words, not meaning, in the language the pack is written in; within the folder when one is named; 10 unless --limit says otherwise, up to 25, and a last line says when more matched. --json answers with the console's own JSON, the page of each skill included.",
+      "The project's pack, read by the console at the project's address, or the organization's: at a SkillCDN deployment, with the pack token the project holds where the pack is private (ADR-0028), or from a directory on the console's machine for a local address (ADR-0031). Alone: where the pack is and what a client is told of it on connect, then every skill with the path of its SKILL.md and every document, as a connection of your own would list them, and where the console's own skills are on this machine. With a folder (. for the root): what it holds, whole, as browse_repo lays it out for a model: its skills, its folders with what each holds and the README that introduces it, its files. With --search: what the words find, as search_repo does: skills first, with the files of theirs that matched, then documents, in relevance order; words, not meaning, in the language the pack is written in; within the folder when one is named; 10 unless --limit says otherwise, up to 25, and a nextCursor line says when more matched, which --cursor continues. The text is the one an MCP client's model is given, with the reads named as these commands. --json answers with the console's own JSON: what the pack answered, in the shapes of the main repository's REST API, the pages of a folder joined.",
     limits: ["search: 1 to 500 characters; limit: 1 to 25"],
     refusals: [
       "status not_found: the pack is not served to the console; private, with no pack token on the project",
@@ -291,11 +302,11 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     synopsis:
       "One skill of the pack whole, its rules first; or with --file a file of the pack, or what a folder holds.",
     about:
-      "One skill of the project's pack, whole, as load_skill lays it out for you: the rules of the repository from its root to the nearest manifest, the skill's body, the files it includes, each under a line that names its path; then the files it has and what it refers to. Read by the console from the SkillCDN deployment, with the pack token the project holds where the pack is private, so you need no connection of your own. <path> is the path of the SKILL.md from the repository's root, as console skills lists it. --file <path> reads a file of the pack instead, whole, or what a folder holds, and takes no skill's path beside it; console skills <folder> shows a folder with more.",
+      "One skill of the project's pack, whole, as load_skill lays it out for a model: the rules of the repository from its root to the nearest manifest, the skill's instructions, the files it includes, then its supporting files and what it refers to; the pages it came in are joined. Read by the console from the pack, with the pack token the project holds where the pack is private, so you need no connection of your own. <path> is the path of the SKILL.md from the repository's root, as console skills lists it, or the URI the pack names it by (skill://<host>/<owner>/<name>/<path>). --file <path> reads a file of the pack instead, whole, as read_repo_file does, or what a folder holds, and takes no skill's path beside it; console skills <folder> shows a folder with more. --json answers with what the pack answered, in the shapes of the main repository's REST API, the pages joined.",
     refusals: [
       "status not_found: the pack is not served to the console; private, with no pack token on the project",
       "status token_invalid: the pack token the project holds no longer works; an owner sets a new one",
-      "status failed, for a file: SkillCDN will not carry it, too large or not text",
+      "status failed, for a file: the pack will not carry it, too large or not text",
     ],
   },
   rules: {
@@ -325,10 +336,11 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     ],
   },
   report: {
-    usage: "report <markdown>  |  report --file <path>  |  report -",
+    usage:
+      "report <markdown> [--run <id>]  |  report --file <path> [--run <id>]  |  report - [--run <id>]",
+    overview: "report <markdown>  |  report --file <path>  |  report -",
     synopsis: "Says how the work goes, in Markdown, on the open run.",
-    about:
-      "Says how the work goes, in Markdown: what was found, what was done, what is next. With - the report is read from standard input.",
+    about: `Says how the work goes, in Markdown: what was found, what was done, what is next. With - the report is read from standard input. ${ON_THE_RUN}`,
     limits: [
       `the report: ${MARKDOWN}, not blank`,
       `at most ${MAX_REPORTS_PER_RUN} reports on one run`,
@@ -336,10 +348,10 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     refusals: [...RUN_REFUSALS, "run.too_many_reports: the run carries as many as one may"],
   },
   "hand-in": {
-    usage: "hand-in <https url | file path> [--label <words>]",
+    usage: "hand-in <https url | file path> [--label <words>] [--run <id>]",
+    overview: "hand-in <https url | file path> [--label <words>]",
     synopsis: "Hands in what was made: an https link, or a file from this machine.",
-    about:
-      "Hands in what was made: a link (a branch, a pull request, a document, a page), or a file from this machine, which the console keeps and shows on the task; a picture is shown there small and large, and a report that names it as ![words](its name) shows it where the words are.",
+    about: `Hands in what was made: a link (a branch, a pull request, a document, a page), or a file from this machine, which the console keeps and shows on the task; a picture is shown there small and large, and a report that names it as ![words](its name) shows it where the words are. ${ON_THE_RUN}`,
     limits: [
       "a link: https only",
       `a file: up to ${MAX_FILE_BYTES} bytes, not empty; it is called by its name, without the path`,
@@ -354,24 +366,25 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   ask: {
     usage:
+      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--wait <seconds>] [--run <id>]',
+    overview:
       'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--wait <seconds>]',
     synopsis:
       "Raises a decision a person must make, with options, and waits a while for the answer.",
-    about:
-      "Raises a decision a person must make: the question, the options to choose from, and what they need to know. The run waits for the answer. The command waits 60 seconds for it unless --wait says otherwise, and exits with 3 if it is still to come: keep waiting with `console decision <id> --wait 100`, within what your shell gives one command. The decision's id is printed as soon as it is raised.",
+    about: `Raises a decision a person must make: the question, the options to choose from, and what they need to know. The run waits for the answer. The command waits 60 seconds for it unless --wait says otherwise, and exits with 3 if it is still to come: keep waiting with \`console decision <id> --wait 100\`, within what your shell gives one command. The decision's id is printed as soon as it is raised. The person chooses one of the options, or answers in their own words: the answer then names one more option, their words, marked own; act on it as given. ${ON_THE_RUN}`,
     limits: [
       `question: one line, up to ${MAX_QUESTION_LENGTH} characters`,
       `options: ${MIN_OPTIONS} to ${MAX_OPTIONS}, each one line up to ${MAX_OPTION_LABEL_LENGTH} characters`,
       `body: ${MARKDOWN}`,
     ],
-    refusals: ["decision.invalid_run: the run is not yours, or is over"],
+    refusals: [...RUN_CHOICE, "decision.invalid_run: the run is not yours, or is over"],
   },
   decision: {
     usage: "decision <id> [--wait <seconds>]  |  decision <id> --outcome <markdown>|--file <path>",
     synopsis:
       "One decision in full; waits for its answer with --wait; writes what followed with --outcome.",
     about:
-      "One decision, with its context, its options, its answer and what followed. With --wait, holds on for the answer that long, and exits with 3 if it is still to come. With --outcome, writes down what followed the decision, so that it reads as a record.",
+      "One decision, with its context, its options, its answer (one of the options, or the person's own words as one more, marked own) and what followed. With --wait, holds on for the answer that long, and exits with 3 if it is still to come. With --outcome, writes down what followed the decision, so that it reads as a record.",
     limits: [`outcome: ${MARKDOWN}`],
     refusals: ["decision.not_found: no decision has that id"],
   },
@@ -381,17 +394,18 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     about: `The decisions on the board, the waiting first; --open keeps only those. A page at a time: ${DEFAULT_PAGE_LIMIT} unless --limit says otherwise, from --offset on.`,
   },
   finish: {
-    usage: 'finish [--summary "<markdown>"|--file <path>]',
+    usage: 'finish [--summary "<markdown>"|--file <path>] [--run <id>]',
+    overview: 'finish [--summary "<markdown>"|--file <path>]',
     synopsis: "Ends the run: done and handed in; the task goes up for review.",
-    about:
-      "Ends the run: the work is done and handed in, and the task goes up for review. The summary says what was done and what is left; the result itself goes in a last report before, which may be much longer.",
+    about: `Ends the run: the work is done and handed in, and the task goes up for review. The summary says what was done and what is left; the result itself goes in a last report before, which may be much longer. ${ON_THE_RUN}`,
     limits: [`summary: ${`Markdown, up to ${MAX_SUMMARY_LENGTH} characters`}`],
     refusals: RUN_REFUSALS,
   },
   fail: {
-    usage: 'fail [--summary "<markdown>"|--file <path>]',
+    usage: 'fail [--summary "<markdown>"|--file <path>] [--run <id>]',
+    overview: 'fail [--summary "<markdown>"|--file <path>]',
     synopsis: "Ends the run: the work could not be done.",
-    about: "Ends the run: the work could not be done. The summary says why, and what is left.",
+    about: `Ends the run: the work could not be done. The summary says why, and what is left. ${ON_THE_RUN}`,
     limits: [`summary: Markdown, up to ${MAX_SUMMARY_LENGTH} characters`],
     refusals: RUN_REFUSALS,
   },
@@ -457,7 +471,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     usage: 'write <path> [--title "<title>"] --body <markdown>|--file <path> [--base <version>]',
     synopsis: "Writes a page: a new one at a path, or a new version of the page there.",
     about:
-      "Writes a page: the first version at a new path, or a new version of the page there. A link in the body whose destination is a page's path (guides/onboarding) refers to that page, and the page says what refers to it. Without --title the page keeps its title. With --base, the write is refused if the page has moved on since that version.",
+      "Writes a page: the first version at a new path, or a new version of the page there. The title is shown above the body, on the page and by console doc, so the body does not begin with it as a heading. A link in the body whose destination is a page's path (guides/onboarding) refers to that page, and the page says what refers to it. Without --title the page keeps its title. With --base, the write is refused if the page has moved on since that version.",
     limits: [
       `path: ${DOCUMENT_PATH}`,
       `title: one line, up to ${MAX_TITLE_LENGTH} characters`,
@@ -510,13 +524,24 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
 };
 
-/** The first lines of the usage, with the version of the command when it is known. */
-const preamble = (version: string | undefined): string =>
+/**
+ * Where the skill working-the-board is, among the console's own skills in `skillsDir`, with the
+ * separators the directory came with, so that the path reads as the machine writes paths.
+ */
+export function ownSkillPath(skillsDir: string): string {
+  const separator = skillsDir.includes("\\") ? "\\" : "/";
+  const base =
+    skillsDir.endsWith("/") || skillsDir.endsWith("\\") ? skillsDir : `${skillsDir}${separator}`;
+  return `${base}working-the-board${separator}SKILL.md`;
+}
+
+/** The first lines of the usage, with the version of the command and where its skill is, when known. */
+const preamble = (version: string | undefined, skillsDir: string | undefined): string =>
   `console${version === undefined ? "" : ` ${version}`}: the board of your organization's work with AI agents, from the command line.
 You act as the person whose token you hold; everything you send is shown to people as text.
 The rules of this organization come with the task: console take prints them; console rules reads them any time.
-How the board is worked is the skill working-the-board, installed with this command: console skills prints
-where it is; read it before the first command of a run.
+How the board is worked is the skill working-the-board, installed with this command; read it before the
+first command of a run${skillsDir === undefined ? " (console whoami says where it is)" : `:\n${ownSkillPath(skillsDir)}`}
 
 Usage: console <command> [arguments] [--json] [--url <origin>] [--project <key>]
 A command in full, every form and flag ([flags] below), the limits the console holds it to and what
@@ -532,7 +557,8 @@ with several open, say which with --run <id>. A Markdown body given as - is read
 console --version says which version of the command this is.
 
 Exit codes: 0 done; 1 the console refused, or could not be reached (the reason is on stderr);
-2 the command was not understood; 3 the decision still waits for a person.
+2 the command was not understood; 3 the decision still waits for a person; 4 the command and the
+console do not go together, and stderr says which to update and how.
 What the console refuses is printed as its code and its words. Everywhere:
 ${COMMON_REFUSALS.map((refusal) => `  ${refusal}`).join("\n")}
 
@@ -583,8 +609,8 @@ const SECTIONS: readonly { readonly title: string; readonly commands: readonly s
 ];
 
 /** The overview, as `console help` prints it: every command in a line, naming the version when it is known. */
-export function usage(version?: string): string {
-  const parts = [preamble(version)];
+export function usage(version?: string, skillsDir?: string): string {
+  const parts = [preamble(version, skillsDir)];
   for (const section of SECTIONS) {
     parts.push(`${section.title}`);
     for (const name of section.commands) {