@skillcdn/console 0.3.2 → 0.4.1

package/src/cli/cli.ts

@@ -801,13 +801,19 @@ const logout: Command = async (args, io) => {
   }
   // The token is given up at the console first, so that it is good for nothing from now on;
   // one the console no longer knows is gone already. A console out of reach leaves it to the
-  // Agents page, and the person is told so.
-  let gone = true;
+  // Agents page, and the person is told so. A console that keeps it because the person is out
+  // (ADR-0044) is told so too: the token is theirs again when they are back in.
+  let outcome: "gone" | "kept" | "left" = "gone";
   try {
     await clientOf(io, url, login.token).giveUpToken();
   } catch (error) {
-    if (!(error instanceof ApiError && error.code === "auth.required")) {
-      gone = false;
+    if (
+      error instanceof ApiError &&
+      (error.code === "auth.deactivated" || error.code === "auth.not_admitted")
+    ) {
+      outcome = "kept";
+    } else if (!(error instanceof ApiError && error.code === "auth.required")) {
+      outcome = "left";
     }
   }
   const next = withoutLogin(credentials, url, login.account);
@@ -818,9 +824,11 @@ const logout: Command = async (args, io) => {
   }
   const whom = login.account === undefined ? "" : ` as ${login.account}`;
   io.stdout(
-    gone
+    outcome === "gone"
       ? `Signed out of ${url}${whom}: the token is given up at the console and forgotten here.\n`
-      : `Signed out of ${url}${whom} here, but the console could not be reached to give the token up: a person removes it on the Agents page.\n`,
+      : outcome === "kept"
+        ? `Signed out of ${url}${whom} here: the console keeps the token while the person is out, for when they are back in.\n`
+        : `Signed out of ${url}${whom} here, but the console could not be reached to give the token up: a person removes it on the Agents page.\n`,
   );
   envNote();
   return EXIT.ok;
@@ -1172,8 +1180,37 @@ const skills: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+/** The most characters one read of a file asks for: what the console's API allows on one page. */
+const MAX_FILE_LIMIT = 100_000;
+
+/** A count given as a flag, within its bounds, or nothing; anything else is not understood. */
+function countOf(
+  given: string | undefined,
+  name: string,
+  bounds: { readonly least: number; readonly most?: number },
+): number | undefined {
+  if (given === undefined) {
+    return undefined;
+  }
+  const count = Number(given);
+  if (
+    !Number.isInteger(count) ||
+    count < bounds.least ||
+    (bounds.most !== undefined && count > bounds.most)
+  ) {
+    const range =
+      bounds.most === undefined ? `${bounds.least} or more` : `${bounds.least} to ${bounds.most}`;
+    throw misuse(`Not a number for --${name}, ${range}: ${given}`);
+  }
+  return count;
+}
+
 const skill: Command = async (args, io) => {
-  const { values, positionals } = parse(args, { file: { type: "string" } });
+  const { values, positionals } = parse(args, {
+    file: { type: "string" },
+    offset: { type: "string" },
+    limit: { type: "string" },
+  });
   const file = text(values, "file");
   // A file is read by its own path from the repository's root; a skill's path beside it would be
   // ignored, which reads as if it mattered, so the two together are not understood.
@@ -1182,6 +1219,17 @@ const skill: Command = async (args, io) => {
       "Say one: console skill <path of its SKILL.md> for a skill, or console skill --file <path> for a file of the pack.",
     );
   }
+  // A section is a page of a file read as asked (SkillCDN 0.4): the flags mean nothing without one.
+  if (
+    file === undefined &&
+    (text(values, "offset") !== undefined || text(values, "limit") !== undefined)
+  ) {
+    throw misuse(
+      "--offset and --limit go with --file: console skill --file <path> [--offset <n>] [--limit <n>]",
+    );
+  }
+  const offset = countOf(text(values, "offset"), "offset", { least: 0 });
+  const limit = countOf(text(values, "limit"), "limit", { least: 1, most: MAX_FILE_LIMIT });
   const session = await open(io, values);
   const project = await session.project();
   const { listing, summary } = await packOf(project);
@@ -1189,6 +1237,16 @@ const skill: Command = async (args, io) => {
     answer(io, session, listing, () => formatSkills(listing, io.skillsDir));
     return EXIT.ok;
   }
+  if (file !== undefined && (offset !== undefined || limit !== undefined)) {
+    // One page as asked, the section a search or an outline named; the result says where the
+    // file continues, and asks for nothing.
+    const page = await project.skillFile(file, { offset, limit });
+    const section = page.read === null ? undefined : joinFile([page], summary, limit);
+    answer(io, session, { ...page, read: section === undefined ? null : bodyOfFile(section) }, () =>
+      formatSkillFile(page, section),
+    );
+    return EXIT.ok;
+  }
   if (file !== undefined) {
     // The file whole, page after page, as the console reads it from the pack.
     const pages: RestSkillFile[] = [];
@@ -1800,11 +1858,16 @@ const ask: Command = async (args, io) => {
     file: { type: "string" },
     run: { type: "string" },
     wait: { type: "string" },
+    to: { type: "string" },
   });
   const question = theOne(
     positionals,
     'Say the question: console ask "<question>" --option "<label>" --option "<label>"',
   );
+  const to = text(values, "to");
+  if (to === "none") {
+    throw misuse("Say whom the decision is for: --to <login|me>.");
+  }
   const options = texts(values, "option");
   if (options.length < MIN_OPTIONS || options.length > MAX_OPTIONS) {
     throw misuse(`Give ${MIN_OPTIONS} to ${MAX_OPTIONS} options, one --option each.`);
@@ -1814,21 +1877,58 @@ const ask: Command = async (args, io) => {
   const session = await open(io, values);
   const project = await session.project();
   const runId = await currentRun(project, values);
+  // Whom the decision is for (ADR-0042): the person the agent works for, unless --to names another.
+  const deciderId = await personIdOf(session, to);
   const raised = await project.raiseDecision({
     question,
     options: options.map((label) => ({ label })),
     runId,
     ...(body === undefined ? {} : { body }),
+    ...(typeof deciderId === "string" ? { deciderId } : {}),
   });
   // The id is printed before any waiting, so that a wait cut short loses nothing.
   io.stdout(
     session.json
       ? `${JSON.stringify(raised, null, 2)}\n`
-      : `Decision ${raised.id} raised on run ${runId}; the run waits for a person.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`,
+      : `Decision ${raised.id} raised on run ${runId}; the run waits for ${raised.decider.login}.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`,
   );
   return settle(io, session, project, raised, seconds, true);
 };
 
+/**
+ * Writes a person's answer on a decision, in their name through the agent (ADR-0021): the
+ * option they chose, or their own words, and a note about it, so that a choice made in chat
+ * or in passing reaches the record the run waits on.
+ */
+const answering: Command = async (args, io) => {
+  const { values, positionals } = parse(args, {
+    option: { type: "string" },
+    own: { type: "string" },
+    note: { type: "string" },
+    file: { type: "string" },
+  });
+  const id = theOne(
+    positionals,
+    'Say which decision: console answer <id> --option <n>|--own "<answer>" [--note <markdown>|--file <path>]',
+  );
+  const option = text(values, "option");
+  const own = text(values, "own");
+  if ((option === undefined) === (own === undefined)) {
+    throw misuse(
+      'Say the option chosen, --option <n>, or the person\'s own answer, --own "<words>": one of the two.',
+    );
+  }
+  const note = await bodyOf(io, values, text(values, "note"));
+  const session = await open(io, values);
+  const project = await session.project();
+  const answered = await project.answerDecision(id, {
+    ...(own === undefined ? { option } : { own }),
+    ...(note === undefined ? {} : { note }),
+  });
+  answer(io, session, answered, () => formatDecision(answered));
+  return EXIT.ok;
+};
+
 const decision: Command = async (args, io) => {
   const { values, positionals } = parse(args, {
     wait: { type: "string" },
@@ -2139,14 +2239,37 @@ const goal: Command = async (args, io) => {
 };
 
 const decisions: Command = async (args, io) => {
-  const { values } = parse(args, { open: { type: "boolean" }, ...PAGE_OPTIONS }, false);
+  const { values } = parse(
+    args,
+    {
+      open: { type: "boolean" },
+      mine: { type: "boolean" },
+      raised: { type: "boolean" },
+      ...PAGE_OPTIONS,
+    },
+    false,
+  );
   const page = pageOf(values);
   const session = await open(io, values);
+  const open_ = on(values, "open") ? { open: true } : {};
+  if (on(values, "mine") || on(values, "raised")) {
+    // One's own across the projects (ADR-0042), addressed to the person or raised by them for
+    // someone else: the waiting first, each with its project's key.
+    const raised = on(values, "raised");
+    const found = await session.client.myDecisions({ ...open_, raised, ...page });
+    answer(io, session, found, () =>
+      found.items.length === 0
+        ? raised
+          ? "No decisions you asked of others."
+          : "No decisions of yours."
+        : found.items
+            .map(({ project, decision }) => `${project.key}  ${formatDecisionLine(decision)}`)
+            .join("\n") + formatMore(found.more, page.limit, page.offset),
+    );
+    return EXIT.ok;
+  }
   const project = await session.project();
-  const found = await project.decisions({
-    ...(on(values, "open") ? { open: true } : {}),
-    ...page,
-  });
+  const found = await project.decisions({ ...open_, ...page });
   answer(io, session, found, () =>
     found.items.length === 0
       ? "No decisions."
@@ -2384,8 +2507,8 @@ const workspace: Command = async (args, io) => {
         set: (token) => client.setWorkspacePackToken({ token }),
         remove: () => client.removeWorkspacePackToken(),
         connect: () => client.connectWorkspacePackToken(),
-        async standing() {
-          const state = await client.workspacePackTokenConnection();
+        async claim() {
+          const state = await client.claimWorkspacePackTokenConnection();
           return state.status === "connected"
             ? { status: "connected", held: state.workspace }
             : state;
@@ -2545,7 +2668,8 @@ interface TokenHolder<T> {
   set(token: string): Promise<T>;
   remove(): Promise<T>;
   connect(): Promise<RestPackConnectStarted>;
-  standing(): Promise<
+  /** Asks the console to claim the token at the deployment (ADR-0046), and answers how it stands. */
+  claim(): Promise<
     | { readonly status: "none" }
     | { readonly status: "pending" }
     | { readonly status: "ended"; readonly reason: keyof typeof PACK_CONNECT_ENDED }
@@ -2577,7 +2701,7 @@ async function packToken<T>(
     );
     for (;;) {
       await io.sleep(started.intervalSeconds * 1000);
-      const state = await holder.standing();
+      const state = await holder.claim();
       if (state.status === "pending") {
         continue;
       }
@@ -2625,8 +2749,8 @@ const projectPackToken: Command = async (args, io) => {
       set: (token) => project.setPackToken({ token }),
       remove: () => project.removePackToken(),
       connect: () => project.connectPackToken(),
-      async standing() {
-        const state = await project.packTokenConnection();
+      async claim() {
+        const state = await project.claimPackTokenConnection();
         return state.status === "connected" ? { status: "connected", held: state.project } : state;
       },
     },
@@ -2869,6 +2993,7 @@ const COMMANDS: Readonly<Record<string, Command>> = {
   comment,
   file,
   ask,
+  answer: answering,
   decision,
   decisions,
   finish: ending("finished"),
@@ -3006,6 +3131,10 @@ function hintFor(error: ApiError, io: CliIo, seen: ConsoleSeen): string {
       return `Install the console's version: ${updateWords(io, seen.version)}; or ask the console's operator to update the console.\n`;
     case "auth.required":
       return "The token is not one the console knows, any more or at all. A person signs the command in again: console login\n";
+    case "auth.deactivated":
+      return "Tell the person: they are taken back in on the People page, by an administrator or by their organization, and this token works again then. console logout forgets it here meanwhile.\n";
+    case "auth.not_admitted":
+      return "Tell the person: they are back in when what let them in is named again, or when an administrator lists their login and they sign in again, and this token works again then. console logout forgets it here meanwhile.\n";
     case "project.not_found":
       return "No project has this key, or it is not yours to see. console projects lists the projects you may work in.\n";
     case "document.not_found":
@@ -3030,6 +3159,20 @@ function hintFor(error: ApiError, io: CliIo, seen: ConsoleSeen): string {
       return "What was asked is an administrator's, or an owner's of the project, and the person this token acts as is not one here. Hand the step to them.\n";
     case "project.key_taken":
       return "A project has that key already. console projects lists them.\n";
+    case "project.too_many":
+      return "The workspace holds as many projects as one may. Work goes on in a project there is.\n";
+    case "project.too_many_bytes":
+      return "The project's files hold as many bytes together as this console allows. Hand in a link to where the file is instead, and say so in the report.\n";
+    case "task.too_many":
+      return "The project holds as many tasks as one may, those put away counted. The work goes on in another project; ask the person which.\n";
+    case "goal.too_many":
+      return "The project holds as many goals as one may. console goals lists them; one done or dropped is still a goal.\n";
+    case "decision.too_many":
+      return "The project holds as many decisions as one may. Ask the person in the report instead.\n";
+    case "document.too_many":
+      return "The project holds as many pages as one may. Write on a page there is: console docs lists them.\n";
+    case "run.too_many":
+      return "The task has been taken as many times as one may. Write a new task for what is left, and take that.\n";
     case "project.invalid_address":
       return "The skills address is not one as SkillCDN spells it; none makes the organization's skills the project's.\n";
     case "project.invalid_icon":

package/src/cli/format.ts

@@ -386,7 +386,10 @@ export function formatWork(work: RestWork): string {
       lines.push(`  ${project.key}  ${formatTaskLine(task)}`);
     }
   }
-  lines.push("", work.decisions.length === 0 ? "decisions waiting: none" : "decisions waiting:");
+  lines.push(
+    "",
+    work.decisions.length === 0 ? "decisions waiting for you: none" : "decisions waiting for you:",
+  );
   for (const { project, decision } of work.decisions) {
     lines.push(`  ${project.key}  ${formatDecisionLine(decision)}`);
   }
@@ -404,9 +407,13 @@ export function formatPersonWork(person: RestPerson, work: RestPersonWork): stri
   ].join("\n");
 }
 
+/** Whom a decision is for, where that is not the one who asked (ADR-0042). */
+const addressed = (decision: RestDecision): string =>
+  decision.decider.id === decision.raisedBy.id ? "" : `, for ${decision.decider.login}`;
+
 export function formatDecisionLine(decision: RestDecision): string {
   const state = decision.answer === null ? "waiting" : `answered ${decision.answer.option}`;
-  return `${decision.id}  ${state}  ${decision.question}  (asked by ${asker(decision)})`;
+  return `${decision.id}  ${state}  ${decision.question}  (asked by ${asker(decision)}${addressed(decision)})`;
 }
 
 /** The options, one a line; the person's own answer, when they wrote one, is the last and says so. */
@@ -423,7 +430,7 @@ export function formatOptions(decision: RestDecision): string {
 export function formatAnswer(decision: RestDecision): string {
   const { answer } = decision;
   if (answer === null) {
-    return "waits for a person.";
+    return `waits for ${decision.decider.login}.`;
   }
   const chosen = decision.options.find((option) => option.id === answer.option);
   const lines = [
@@ -438,7 +445,7 @@ export function formatAnswer(decision: RestDecision): string {
 export function formatDecision(decision: RestDecision): string {
   const lines = [
     `decision ${decision.id}: ${decision.question}`,
-    `asked by ${asker(decision)}${decision.taskNumber === null ? "" : `, about task #${decision.taskNumber}`}`,
+    `asked by ${asker(decision)}${addressed(decision)}${decision.taskNumber === null ? "" : `, about task #${decision.taskNumber}`}`,
   ];
   if (decision.body.trim().length > 0) {
     lines.push("", decision.body.trimEnd());

package/src/cli/help.ts

@@ -7,12 +7,16 @@ import {
   MAX_CATEGORY_KEY_LENGTH,
   MAX_CATEGORY_NAME_LENGTH,
   MAX_COMMENTS_PER_TASK,
+  MAX_DECISIONS_PER_PROJECT,
   MAX_DOCUMENT_LENGTH,
   MAX_DOCUMENT_PATH_LENGTH,
+  MAX_DOCUMENTS_PER_PROJECT,
   MAX_FILE_BYTES,
   MAX_FILES_PER_COMMENT,
   MAX_FILES_PER_DOCUMENT,
+  MAX_GOALS_PER_PROJECT,
   MAX_LINK_LABEL_LENGTH,
+  MAX_NOTE_LENGTH,
   MAX_OPTION_LABEL_LENGTH,
   MAX_OPTIONS,
   MAX_PROJECT_DESCRIPTION_LENGTH,
@@ -20,11 +24,14 @@ import {
   MAX_PROJECT_KEY_LENGTH,
   MAX_PROJECT_NAME_LENGTH,
   MAX_PROJECT_SYMBOL_LENGTH,
+  MAX_PROJECTS_PER_WORKSPACE,
   MAX_QUESTION_LENGTH,
   MAX_REPORTS_PER_RUN,
   MAX_RULES_LENGTH,
+  MAX_RUNS_PER_TASK,
   MAX_SEARCH_LENGTH,
   MAX_SUMMARY_LENGTH,
+  MAX_TASKS_PER_PROJECT,
   MAX_TITLE_LENGTH,
   MAX_VERSIONS_PER_DOCUMENT,
   MAX_WORKERS,
@@ -58,6 +65,7 @@ export interface CommandHelp {
 /** The refusals any command may meet, said once in the overview. */
 const COMMON_REFUSALS = [
   "auth.required: the token is not one the console knows, any more or at all; a person signs the command in again",
+  "auth.deactivated, auth.not_admitted: the person this token acts as is out, deactivated or no longer let in; the console keeps the token, and it works again when they are back in",
   "request.invalid: what was sent is over a limit or malformed; the message names the field",
   "network: the console could not be reached at its address",
 ];
@@ -147,9 +155,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   work: {
     usage: "work [--person <login>]",
     synopsis:
-      "What is on your plate across your projects: your open tasks, and the decisions waiting.",
+      "What is on your plate across your projects: your open tasks, and the decisions waiting for you.",
     about:
-      "What is on your plate across the projects you may see: the open tasks you work on, the sooner due first, each with its project; and the decisions waiting for a person. Needs no project. --person <login> shows another person's plate, for an administrator or for an owner of a project they are in: the open tasks they work on within the projects you may see, without the decisions, which wait for anyone.",
+      "What is on your plate across the projects you may see: the open tasks you work on, the sooner due first, each with its project; and the decisions waiting for your answer (ADR-0042). Needs no project. --person <login> shows another person's plate, for an administrator or for an owner of a project they are in: the open tasks they work on within the projects you may see, without the decisions.",
   },
   tasks: {
     usage:
@@ -170,8 +178,13 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       `title: one line, up to ${MAX_TITLE_LENGTH} characters, saying what is to be done on its own; what it refers to goes in the body`,
       `body: ${MARKDOWN}`,
       ...TASK_FIELD_LIMITS,
+      `at most ${MAX_TASKS_PER_PROJECT} tasks in one project, those put away counted`,
+    ],
+    refusals: [
+      "task.not_found: no task has that number or id",
+      ...TASK_FIELD_REFUSALS,
+      "task.too_many: the project holds as many tasks as one may; the work goes on in another project",
     ],
-    refusals: ["task.not_found: no task has that number or id", ...TASK_FIELD_REFUSALS],
   },
   goals: {
     usage:
@@ -192,11 +205,13 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       `title: one line, up to ${MAX_TITLE_LENGTH} characters`,
       `body: ${MARKDOWN}`,
       `starts, due: ${DAY}`,
+      `at most ${MAX_GOALS_PER_PROJECT} goals in one project`,
     ],
     refusals: [
       "goal.not_found: no goal of this project has that id",
       "goal.invalid_category: no category of the workspace has that key",
       "goal.invalid_dates: the target day is before the start",
+      "goal.too_many: the project holds as many goals as one may",
       "auth.forbidden: only an owner of the project sets its roadmap",
     ],
   },
@@ -258,11 +273,13 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       `name: one line, up to ${MAX_PROJECT_NAME_LENGTH} characters; description: up to ${MAX_PROJECT_DESCRIPTION_LENGTH}`,
       `color: ${COLORS}; symbol: up to ${MAX_PROJECT_SYMBOL_LENGTH} characters without spaces, shown on the colour; left out, the pages choose both from the key and the name`,
       `image: a PNG, a JPEG, a GIF or a WebP of at most ${MAX_PROJECT_ICON_BYTES} bytes`,
+      `at most ${MAX_PROJECTS_PER_WORKSPACE} projects in the workspace`,
     ],
     refusals: [
       "project.not_found: no project has that key, or it is not yours to see",
-      "auth.forbidden: only an owner of the project changes it",
+      "auth.forbidden: only an administrator makes a project, and only an owner changes it",
       "project.key_taken: a project has that key already",
+      "project.too_many: the workspace holds as many projects as one may",
       "project.invalid_address: the skills address is not one as SkillCDN spells it",
       "project.invalid_icon: the file is not an image of those kinds, by its bytes",
       "request.too_large: the image is over the limit",
@@ -313,11 +330,11 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   skills: {
     usage:
-      "skills  |  skills <folder>  |  skills --search <words> [<folder>] [--limit <n>] [--cursor <cursor>]",
+      "skills  |  skills <folder|file>  |  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.",
+      "The project's pack: its skills; what a folder of it holds, or a document's outline; or what words find in it.",
     about:
-      "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.",
+      "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 a file's path: the file's outline, every heading with its level and the offset and limit that read its section with console skill --file, whole; a file that is not Markdown has none. With --search: what the words find, as search_repo does: skills first, with the files of theirs that matched, then documents, each with the sections of it that matched and what reads each, in relevance order; words in the language the pack is written in, and meaning too where the deployment searches by it, which the result then says; 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 or an outline 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",
@@ -325,11 +342,12 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     ],
   },
   skill: {
-    usage: "skill <path>  |  skill --file <path>",
+    usage: "skill <path>  |  skill --file <path> [--offset <n>] [--limit <n>]",
     synopsis:
-      "One skill of the pack whole, its rules first; or with --file a file of the pack, or what a folder holds.",
+      "One skill of the pack whole, its rules first; or with --file a file of the pack, one section of it, or what a folder holds.",
     about:
-      "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.",
+      "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. --offset <n> and --limit <n>, with --file, read one page of the file as asked, from that character on and at most that many characters, as a search or an outline (console skills <file>) names a section, instead of the file whole; the result says where the file continues. --json answers with what the pack answered, in the shapes of the main repository's REST API, the pages joined.",
+    limits: ["offset: 0 or more; limit: 1 to 100000 characters; both with --file"],
     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",
@@ -356,10 +374,14 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     synopsis: "Takes a task: a run begins, and the task is in progress and the person's.",
     about:
       "Takes a task: a run begins, and the task is in progress and the person's; the run's id and the task's id are printed on a line of their own, then the task, then the rules of the board. A run still open on the task is taken over, since the board cannot know whether its agent still runs: it ends as abandoned, the feed says who took over, and that agent is refused on its next command; console task <number> shows the runs on a task, with when each was last heard from, before it is taken. --agent is what people see at work; left out, it is what the person called the token.",
-    limits: [`agent: one line, up to ${MAX_AGENT_LENGTH} characters`],
+    limits: [
+      `agent: one line, up to ${MAX_AGENT_LENGTH} characters`,
+      `at most ${MAX_RUNS_PER_TASK} runs on one task`,
+    ],
     refusals: [
       "task.not_found: no task has that number or id",
       "run.task_closed: the task is done or dropped",
+      "run.too_many: the task has been taken as many times as one may; write a new task for what is left",
     ],
   },
   report: {
@@ -389,22 +411,45 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       ...RUN_REFUSALS,
       "run.too_many_artifacts: the run carries as many as one may",
       "request.too_large: the file is over the limit",
+      "project.too_many_bytes: the project's files hold as many bytes together as this console allows; hand in a link instead",
     ],
   },
   ask: {
     usage:
-      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--wait <seconds>] [--run <id>]',
+      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--to <login|me>] [--wait <seconds>] [--run <id>]',
     overview:
-      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--wait <seconds>]',
+      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--to <login|me>] [--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. 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}`,
+    about: `Raises a decision a person must make: the question, the options to choose from, and what they need to know. It is for the person you work for unless --to names another of the project, who then finds it among their decisions (ADR-0042); anyone of the project may still answer. 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}`,
+      "to: a login of the project, or me",
+      `at most ${MAX_DECISIONS_PER_PROJECT} decisions in one project`,
+    ],
+    refusals: [
+      ...RUN_CHOICE,
+      "decision.invalid_run: the run is not yours, or is over",
+      "decision.invalid_decider: the person named may not work in the project",
+      "decision.too_many: the project holds as many decisions as one may",
+    ],
+  },
+  answer: {
+    usage: 'answer <id> --option <n>|--own "<answer>" [--note <markdown>|--file <path>]',
+    synopsis: "Writes a person's answer on a decision: the option they chose, or their own words.",
+    about:
+      "Writes on the board the answer a person gave: one of the decision's options by its number, or their own words, which become one more option of the decision marked as theirs; and a note about it. The answer is the person's, written in their name through you (ADR-0021): a choice they made in chat, in a meeting or by changing the task is written here, with where and when they made it in the note, so that the record is whole and a run that waited goes on. A decision is answered once; what followed is written with console decision <id> --outcome.",
+    limits: [
+      `own: one line, up to ${MAX_OPTION_LABEL_LENGTH} characters`,
+      `note: Markdown, up to ${MAX_NOTE_LENGTH} characters`,
+    ],
+    refusals: [
+      "decision.not_found: no decision has that id",
+      "decision.answered: the decision has an answer already",
+      "decision.no_such_option: the option is not one of the decision's",
     ],
-    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>",
@@ -416,9 +461,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     refusals: ["decision.not_found: no decision has that id"],
   },
   decisions: {
-    usage: "decisions [--open] [--limit <n>] [--offset <n>]",
-    synopsis: "The decisions on the board, the waiting first.",
-    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.`,
+    usage: "decisions [--open] [--mine|--raised] [--limit <n>] [--offset <n>]",
+    synopsis: "The decisions on the board, the waiting first; or your own across the projects.",
+    about: `The decisions on the board, the waiting first; --open keeps only those. --mine lists the decisions addressed to you instead (ADR-0042), and --raised those you asked of someone else, through your agent or yourself, each across the projects you may see with its project's key; neither needs a project. A page at a time: ${DEFAULT_PAGE_LIMIT} unless --limit says otherwise, from --offset on.`,
   },
   finish: {
     usage: 'finish [--summary "<markdown>"|--file <path>] [--run <id>]',
@@ -472,6 +517,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       "comment.too_many: the task carries as many comments as one may",
       "comment.too_many_files: more files than one comment may carry",
       "request.too_large: the files are over the limit together",
+      "project.too_many_bytes: the project's files hold as many bytes together as this console allows; say where the file is instead",
     ],
   },
   file: {
@@ -503,13 +549,14 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       `path: ${DOCUMENT_PATH}`,
       `title: one line, up to ${MAX_TITLE_LENGTH} characters`,
       `body: Markdown, up to ${MAX_DOCUMENT_LENGTH} characters`,
-      `at most ${MAX_VERSIONS_PER_DOCUMENT} versions of one page`,
+      `at most ${MAX_VERSIONS_PER_DOCUMENT} versions of one page, and ${MAX_DOCUMENTS_PER_PROJECT} pages in one project`,
     ],
     refusals: [
       "document.invalid_path: the path is not one",
       "document.conflict: the page has moved on since --base; read it again",
       "document.archived: the page is archived; restore it first",
       "document.too_many_versions: the page carries as many versions as one may; write a new page",
+      "document.too_many: the project holds as many pages as one may; write on a page there is",
     ],
   },
   attach: {
@@ -526,6 +573,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       "document.archived: the page is archived; restore it first",
       "document.too_many_files: the page carries as many files as one may",
       "request.too_large: the file is over the limit",
+      "project.too_many_bytes: the project's files hold as many bytes together as this console allows; link to where the file is instead",
     ],
   },
   archive: {
@@ -622,7 +670,18 @@ const SECTIONS: readonly { readonly title: string; readonly commands: readonly s
   },
   {
     title: "Working",
-    commands: ["take", "report", "hand-in", "comment", "file", "ask", "finish", "fail", "abandon"],
+    commands: [
+      "take",
+      "report",
+      "hand-in",
+      "comment",
+      "file",
+      "ask",
+      "answer",
+      "finish",
+      "fail",
+      "abandon",
+    ],
   },
   {
     title: "The documents: the project's pages of Markdown, in folders, by path",