@skillcdn/console 0.4.2 → 0.4.4

package/src/cli/cli.ts

@@ -5,6 +5,7 @@ import {
   type ConsoleClient,
   createClient,
   type FetchLike,
+  type FileUpload,
   type PluginClient,
   type ProjectClient,
 } from "../client.js";
@@ -20,7 +21,13 @@ import {
   formatVersion as versionText,
 } from "../compat.js";
 import { addDays, dayOf as dayOfDate, firstDayOfWeek, isDay, weekOf } from "../dates.js";
-import { DEFAULT_PAGE_LIMIT, LIST_LIMIT, MAX_OPTIONS, MIN_OPTIONS } from "../limits.js";
+import {
+  DEFAULT_PAGE_LIMIT,
+  LIST_LIMIT,
+  MAX_DECIDERS,
+  MAX_OPTIONS,
+  MIN_OPTIONS,
+} from "../limits.js";
 import { capabilityWords } from "../plugin/capabilities.js";
 import { PLUGIN_LIST_LIMIT } from "../plugin/limits.js";
 import { fillRules, RULES_PATH, RULES_TITLE } from "../rules.js";
@@ -76,6 +83,7 @@ import {
 } from "./credentials.js";
 import { type DirectorySettings, type DirectoryStore, THE_SENTENCE } from "./directory.js";
 import {
+  deciderLogins,
   formatAnswer,
   formatCategoryLine,
   formatComment,
@@ -1525,6 +1533,8 @@ const plugin: Command = async (args, io) => {
       );
       return EXIT.ok;
     }
+    case "capabilities":
+      return pluginCapabilities(io, session, client, rest);
     case "settings":
       return pluginSettings(io, session, client, rest);
     case "secret":
@@ -1786,7 +1796,60 @@ function capabilityLines(capabilities: readonly string[]): string[] {
   });
 }
 
-/** Enables a plugin, with consent to every capability it asks, named again; an administrator's. */
+/** The capabilities `--consent` names, given again or with commas between. */
+function capabilitiesNamed(values: Values): string[] {
+  return texts(values, "consent")
+    .flatMap((value) => value.split(","))
+    .map((capability) => capability.trim())
+    .filter((capability) => capability.length > 0);
+}
+
+/** What a plugin requires, and which of what it can go without it holds, as `capabilities` prints it. */
+function capabilitiesHeld(detail: RestPluginDetail): string {
+  const held = detail.consent ?? [];
+  const optional = detail.optionalCapabilities ?? [];
+  const named = (capabilities: readonly string[]) =>
+    capabilities.length === 0 ? "none" : capabilities.join(", ");
+  return [
+    `Capabilities of ${detail.key}:`,
+    `  required: ${named(detail.capabilities)}`,
+    `  optional, on: ${named(optional.filter((capability) => held.includes(capability)))}`,
+    `  optional, off: ${named(optional.filter((capability) => !held.includes(capability)))}`,
+  ].join("\n");
+}
+
+/**
+ * What a plugin holds; with `--consent`, which of the optional capabilities it holds from now on,
+ * `none` for none of them. An administrator's.
+ */
+async function pluginCapabilities(
+  io: CliIo,
+  session: Session,
+  client: PluginClient,
+  rest: readonly string[],
+): Promise<number> {
+  const { values, positionals } = parse(rest, { consent: { type: "string", multiple: true } });
+  if (positionals.length > 0) {
+    throw misuse(
+      `Nothing follows capabilities but --consent: console plugin ${client.key} capabilities [--consent <capability>,...|none]`,
+    );
+  }
+  const detail = await client.get();
+  const named = capabilitiesNamed(values);
+  if (named.length === 0) {
+    answer(io, session, detail, () => capabilitiesHeld(detail));
+    return EXIT.ok;
+  }
+  const chosen = named.filter((capability) => capability !== "none");
+  const changed = await client.updateConsent([
+    ...detail.capabilities,
+    ...chosen.filter((capability) => !detail.capabilities.includes(capability)),
+  ]);
+  answer(io, session, changed, () => capabilitiesHeld(changed));
+  return EXIT.ok;
+}
+
+/** Enables a plugin, with consent to every capability it requires, named again; an administrator's. */
 async function pluginEnable(
   io: CliIo,
   session: Session,
@@ -1806,19 +1869,22 @@ async function pluginEnable(
   }
   const [detail, me] = await Promise.all([client.get(), session.client.me()]);
   const asked = detail.capabilities;
-  const consent = texts(values, "consent")
-    .flatMap((value) => value.split(","))
-    .map((capability) => capability.trim())
-    .filter((capability) => capability.length > 0);
+  const optional = detail.optionalCapabilities ?? [];
+  const consent = capabilitiesNamed(values);
   if (asked.length > 0 && !session.json) {
     io.stdout(
-      `${detail.key} asks ${asked.length === 1 ? "one capability" : `${asked.length} capabilities`}:\n${capabilityLines(asked).join("\n")}\n`,
+      `${detail.key} requires ${asked.length === 1 ? "one capability" : `${asked.length} capabilities`}:\n${capabilityLines(asked).join("\n")}\n`,
+    );
+  }
+  if (optional.length > 0 && !session.json) {
+    io.stdout(
+      `It can go without these, which it holds if --consent names them too:\n${capabilityLines(optional).join("\n")}\n`,
     );
   }
   const missing = asked.filter((capability) => !consent.includes(capability));
   if (missing.length > 0) {
     throw misuse(
-      `Enabling ${detail.key} needs consent to every capability it asks, named again: --consent ${asked.join(",")}. Not named: ${missing.join(", ")}.`,
+      `Enabling ${detail.key} needs consent to every capability it requires, named again: --consent ${asked.join(",")}. Not named: ${missing.join(", ")}.`,
     );
   }
   const boardFlag = text(values, "board");
@@ -2069,7 +2135,7 @@ const rules: Command = async (args, io) => {
 
 /**
  * The rules as they read for the person whose token the command holds: `{language}` filled
- * with the language they chose for the pages, or with the task's when they chose none.
+ * with the language they read in, or with the task's while they have none.
  */
 function forPerson<T extends { readonly body: string | null }>(
   half: T,
@@ -2298,18 +2364,7 @@ const comment: Command = async (args, io) => {
   if (body.trim().length === 0 && paths.length === 0) {
     throw misuse(`Say something, or attach a file. ${ask}`);
   }
-  const files = [];
-  for (const path of paths) {
-    let bytes: Uint8Array;
-    try {
-      bytes = await io.readBytes(path);
-    } catch {
-      throw failed(`No file could be read at ${path}. Name the path of a file to attach.`);
-    }
-    const name = basename(path);
-    const contentType = CONTENT_TYPES[extname(name).toLowerCase()];
-    files.push({ name, bytes, ...(contentType === undefined ? {} : { contentType }) });
-  }
+  const files = await attachmentsOf(io, paths);
   const session = await open(io, values);
   const project = await session.project();
   const task = await project.task(ref);
@@ -2323,10 +2378,30 @@ const comment: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+/**
+ * The files named by --attach, read from this machine: each called by its name, without the
+ * path, and typed by its extension where the extension says.
+ */
+async function attachmentsOf(io: CliIo, paths: readonly string[]): Promise<FileUpload[]> {
+  const files: FileUpload[] = [];
+  for (const path of paths) {
+    let bytes: Uint8Array;
+    try {
+      bytes = await io.readBytes(path);
+    } catch {
+      throw failed(`No file could be read at ${path}. Name the path of a file to attach.`);
+    }
+    const name = basename(path);
+    const contentType = CONTENT_TYPES[extname(name).toLowerCase()];
+    files.push({ name, bytes, ...(contentType === undefined ? {} : { contentType }) });
+  }
+  return files;
+}
+
 /**
  * A file of the project, read from the console and written on this machine: one a run handed
- * in, one put in a comment, or one attached to a page, by its id, so that an agent can look at
- * a picture a person put on the board.
+ * in, one put in a comment or on a decision, or one attached to a page, by its id, so that an
+ * agent can look at a picture a person put on the board.
  */
 const file: Command = async (args, io) => {
   const { values, positionals } = parse(args, { out: { type: "string" } });
@@ -2520,15 +2595,19 @@ const ask: Command = async (args, io) => {
     file: { type: "string" },
     run: { type: "string" },
     wait: { type: "string" },
-    to: { type: "string" },
+    to: { type: "string", multiple: true },
+    attach: { type: "string", multiple: true },
   });
   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 tos = texts(values, "to");
+  if (tos.includes("none")) {
+    throw misuse("Say whom the decision is for: --to <login|me>, given again for several.");
+  }
+  if (tos.length > MAX_DECIDERS) {
+    throw misuse(`Name up to ${MAX_DECIDERS} people with --to.`);
   }
   const options = texts(values, "option");
   if (options.length < MIN_OPTIONS || options.length > MAX_OPTIONS) {
@@ -2536,23 +2615,41 @@ const ask: Command = async (args, io) => {
   }
   const seconds = secondsOf(text(values, "wait"), DEFAULT_ASK_WAIT_SECONDS);
   const body = await bodyOf(io, values, text(values, "body"));
+  // The files put on the decision (ADR-0055): a picture of what is to be chosen between, for one.
+  const files = await attachmentsOf(io, texts(values, "attach"));
   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 } : {}),
-  });
+  // Whom the decision is for (ADR-0042, ADR-0057): the person the agent works for, unless --to
+  // names others of the project, each once; several, and any of them may answer.
+  const deciderIds: string[] = [];
+  for (const to of tos) {
+    const id = await personIdOf(session, to);
+    if (typeof id === "string" && !deciderIds.includes(id)) {
+      deciderIds.push(id);
+    }
+  }
+  const raised = await project.raiseDecision(
+    {
+      question,
+      options: options.map((label) => ({ label })),
+      runId,
+      ...(body === undefined ? {} : { body }),
+      ...(deciderIds.length === 0
+        ? {}
+        : deciderIds.length === 1
+          ? { deciderId: deciderIds[0] }
+          : { deciderId: deciderIds[0], deciderIds }),
+    },
+    files,
+  );
+  const withFiles =
+    files.length === 0 ? "" : `, with ${files.length} file${files.length === 1 ? "" : "s"}`;
   // 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 ${raised.decider.login}.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`,
+      : `Decision ${raised.id} raised on run ${runId}${withFiles}; the run waits for ${deciderLogins(raised)}.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`,
   );
   return settle(io, session, project, raised, seconds, true);
 };
@@ -3101,8 +3198,19 @@ const people: Command = async (args, io) => {
   const { values } = parse(args, {}, false);
   const session = await open(io, values);
   const found = await session.client.people();
+  const loginOf = new Map(found.items.map((person) => [person.id, person.login]));
   answer(io, session, found, () =>
-    [...found.items.map(formatPersonLine), ...found.listed.map(formatListingLine)].join("\n"),
+    [
+      ...found.items.map((person) =>
+        formatPersonLine(
+          person,
+          person.managerId === null || person.managerId === undefined
+            ? undefined
+            : (loginOf.get(person.managerId) ?? person.managerId),
+        ),
+      ),
+      ...found.listed.map(formatListingLine),
+    ].join("\n"),
   );
   return EXIT.ok;
 };
@@ -3183,7 +3291,7 @@ const workspace: Command = async (args, io) => {
 };
 
 const PERSON_USAGE =
-  "Say what to do: console person role <login> <admin|member>  |  person add <login> [--host gh|google]  |  person remove <login>  |  person deactivate <login>  |  person reactivate <login>";
+  "Say what to do: console person role <login> <admin|member>  |  person manager <login> <manager login|none>  |  person add <login> [--host gh|google]  |  person remove <login>  |  person deactivate <login>  |  person reactivate <login>";
 
 const person: Command = async (args, io) => {
   const what = args[0];
@@ -3200,6 +3308,21 @@ const person: Command = async (args, io) => {
     answer(io, session, changed, () => formatPersonLine(changed));
     return EXIT.ok;
   }
+  if (what === "manager") {
+    const { values, positionals } = parse(args.slice(1), {});
+    const [login, manager] = theTwo(
+      positionals,
+      "Say whom and whom they report to: console person manager <login> <manager login|none>",
+    );
+    const session = await open(io, values);
+    const found = await personOf(session, login);
+    const managerId = manager === "none" ? null : (await personOf(session, manager)).id;
+    const changed = await session.client.updatePerson(found.id, { managerId });
+    answer(io, session, changed, () =>
+      formatPersonLine(changed, managerId === null ? undefined : manager),
+    );
+    return EXIT.ok;
+  }
   if (what === "add") {
     const { values, positionals } = parse(args.slice(1), { host: { type: "string" } });
     const login = theOne(positionals, "Say whom: console person add <login> [--host gh|google]");

package/src/cli/format.ts

@@ -119,12 +119,13 @@ export function formatProject(project: RestProject): string {
   return lines.join("\n");
 }
 
-/** One person: their login, their name where the host gives one, what they are in the workspace, and that they are out when they are. */
-export function formatPersonLine(person: RestPerson): string {
+/** One person: their login, their name where the host gives one, what they are in the workspace, that they are out when they are, and whom they report to where known. */
+export function formatPersonLine(person: RestPerson, reportsTo?: string | undefined): string {
   const standing = person.status === "active" ? person.role : `${person.role}, deactivated`;
+  const line = reportsTo === undefined ? "" : `, reports to ${reportsTo}`;
   return person.name === null
-    ? `${person.login}  (${standing})`
-    : `${person.login}  ${person.name}  (${standing})`;
+    ? `${person.login}  (${standing}${line})`
+    : `${person.login}  ${person.name}  (${standing}${line})`;
 }
 
 /** The provider a listing names, as people call it. */
@@ -219,6 +220,7 @@ export function formatTask(
     `#${task.number} ${task.title}`,
     `state: ${task.state}  priority: ${task.priority}  owner: ${task.owner.login}  workers: ${task.workers.length === 0 ? "nobody" : logins(task.workers)}`,
     `id: ${task.id}${task.parentId === null ? "" : `  part of: ${task.parentId}`}`,
+    ...(task.agent == null ? [] : [`written through: ${task.agent}`]),
     ...scheduleLines(task),
   ];
   if (task.links.length > 0) {
@@ -379,7 +381,7 @@ export function formatGoalLine(goal: RestGoal): string {
 export function formatGoal(goal: RestGoal, tasks?: readonly RestTask[]): string {
   const lines = [
     `goal ${goal.id}: ${goal.title}`,
-    `state: ${goal.state}  category: ${goal.category?.key ?? "none"}  starts: ${goal.startsOn ?? "none"}  due: ${goal.dueOn ?? "none"}  set by: ${goal.createdBy.login}`,
+    `state: ${goal.state}  category: ${goal.category?.key ?? "none"}  starts: ${goal.startsOn ?? "none"}  due: ${goal.dueOn ?? "none"}  set by: ${goal.createdBy.login}${through(goal.agent)}`,
     `progress: ${progressOf(goal)}`,
   ];
   if (goal.body.trim().length > 0) {
@@ -431,9 +433,27 @@ 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). */
+/** The agent a thing came through, beside the person (ADR-0056); nothing when they did it themselves. */
+const through = (agent: string | null | undefined): string =>
+  agent === null || agent === undefined ? "" : ` through ${agent}`;
+
+/** Everyone a decision is addressed to (ADR-0057): `deciders` where the console answers it, else the one decider. */
+const decidersOf = (decision: RestDecision): readonly RestPerson[] =>
+  decision.deciders !== undefined && decision.deciders.length > 0
+    ? decision.deciders
+    : [decision.decider];
+
+/** The logins of everyone a decision is addressed to, with commas between. */
+export const deciderLogins = (decision: RestDecision): string =>
+  decidersOf(decision)
+    .map((person) => person.login)
+    .join(", ");
+
+/** Whom a decision is for, where that is not the one who asked alone (ADR-0042, ADR-0057). */
 const addressed = (decision: RestDecision): string =>
-  decision.decider.id === decision.raisedBy.id ? "" : `, for ${decision.decider.login}`;
+  decidersOf(decision).every((person) => person.id === decision.raisedBy.id)
+    ? ""
+    : `, for ${deciderLogins(decision)}`;
 
 export function formatDecisionLine(decision: RestDecision): string {
   const state = decision.answer === null ? "waiting" : `answered ${decision.answer.option}`;
@@ -445,7 +465,7 @@ export function formatOptions(decision: RestDecision): string {
   return decision.options
     .map(
       (option) =>
-        `  ${option.id}) ${option.label}${option.own === true ? "  (the person's own answer, not one given)" : ""}`,
+        `  ${option.id}) ${option.label}${option.key === undefined ? "" : `  [${option.key}]`}${option.own === true ? "  (the person's own answer, not one given)" : ""}`,
     )
     .join("\n");
 }
@@ -454,11 +474,11 @@ export function formatOptions(decision: RestDecision): string {
 export function formatAnswer(decision: RestDecision): string {
   const { answer } = decision;
   if (answer === null) {
-    return `waits for ${decision.decider.login}.`;
+    return `waits for ${deciderLogins(decision)}.`;
   }
   const chosen = decision.options.find((option) => option.id === answer.option);
   const lines = [
-    `Answered: ${answer.option}) ${chosen?.label ?? answer.option}${chosen?.own === true ? ", in their own words" : ""}, 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}${through(answer.agent)} at ${answer.at}`,
   ];
   if (answer.note !== null && answer.note.length > 0) {
     lines.push(`Note: ${answer.note}`);
@@ -474,9 +494,27 @@ export function formatDecision(decision: RestDecision): string {
   if (decision.body.trim().length > 0) {
     lines.push("", decision.body.trimEnd());
   }
+  // The files put on it (ADR-0055), each with the command that reads it.
+  const files = decision.files ?? [];
+  if (files.length > 0) {
+    lines.push(
+      "",
+      ...files.map(
+        (attached) =>
+          `file: ${attached.file.name} (${attached.file.size} bytes, ${attached.file.contentType}): console file ${attached.id}`,
+      ),
+    );
+  }
   lines.push("", "options:", formatOptions(decision), "", formatAnswer(decision));
   if (decision.outcome !== null && decision.outcome.trim().length > 0) {
     lines.push("", "what followed:", indent(decision.outcome));
+    if (decision.outcomeBy != null && decision.outcomeAt != null) {
+      lines.push(
+        indent(
+          `written by ${decision.outcomeBy.login}${through(decision.outcomeAgent)} at ${decision.outcomeAt}`,
+        ),
+      );
+    }
   }
   return lines.join("\n");
 }
@@ -579,6 +617,9 @@ export function localized(
 export function formatPluginLine(plugin: RestPlugin, language: string | null | undefined): string {
   const notes = [
     plugin.roles.length === 0 ? undefined : `roles: ${plugin.roles.join(", ")}`,
+    plugin.console === null || plugin.console === undefined
+      ? undefined
+      : `console: ${plugin.console}`,
     plugin.problems.length === 0 ? undefined : `problems: ${plugin.problems.join("; ")}`,
   ].filter((note): note is string => note !== undefined);
   return `${plugin.key}  ${localized(plugin.name, language)} ${plugin.version}  ${plugin.state}${notes.length === 0 ? "" : `  ${notes.join("  ")}`}`;
@@ -750,6 +791,9 @@ export function formatPlugin(
   if (detail.problems.length > 0) {
     lines.push(`problems: ${detail.problems.join("; ")}`);
   }
+  if (detail.console !== null && detail.console !== undefined) {
+    lines.push(`Runs on consoles ${detail.console}.`);
+  }
   lines.push(
     detail.roles.length === 0
       ? "You hold no role in it."

package/src/cli/help.ts

@@ -7,12 +7,14 @@ import {
   MAX_CATEGORY_KEY_LENGTH,
   MAX_CATEGORY_NAME_LENGTH,
   MAX_COMMENTS_PER_TASK,
+  MAX_DECIDERS,
   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_DECISION,
   MAX_FILES_PER_DOCUMENT,
   MAX_GOALS_PER_PROJECT,
   MAX_LINK_LABEL_LENGTH,
@@ -246,14 +248,15 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   person: {
     usage:
-      "person role <login> <admin|member>  |  person add <login> [--host gh|google]  |  person remove <login>  |  person deactivate <login>  |  person reactivate <login>",
+      "person role <login> <admin|member>  |  person manager <login> <manager login|none>  |  person add <login> [--host gh|google]  |  person remove <login>  |  person deactivate <login>  |  person reactivate <login>",
     synopsis:
-      "Says what a person is in the workspace, lets a login in or takes one out; for an administrator.",
+      "Says what a person is in the workspace and whom they report to, lets a login in or takes one out; for an administrator.",
     about:
-      "For an administrator: the person themselves on the People page, or their agent here, named on it. role says what a person is in the workspace; the board keeps at least one administrator in. add lets a login in: whoever signs in with that account at that host is a person from then on; the host is read off the login (an address is Google's, anything else GitHub's) unless --host says. remove takes a login away that nobody has signed in with yet. deactivate takes a person out: refused on every request at once, their agents with them, kept with everything they did, and listed nowhere; reactivate takes them back in. A person the organization let in comes and goes with it, and is neither.",
+      "For an administrator: the person themselves on the People page, or their agent here, named on it. role says what a person is in the workspace; the board keeps at least one administrator in. manager says whom a person reports to, the reporting line of the directory, which the plugins read as a default (the approver of their leave, say) in place of a line of their own: another active person of the workspace who does not report to them, directly or through others, or none; console people shows it. add lets a login in: whoever signs in with that account at that host is a person from then on; the host is read off the login (an address is Google's, anything else GitHub's) unless --host says. remove takes a login away that nobody has signed in with yet. deactivate takes a person out: refused on every request at once, their agents with them, kept with everything they did, and listed nowhere; reactivate takes them back in. A person the organization let in comes and goes with it, and is neither.",
     refusals: [
       "auth.forbidden: only an administrator says who is in and what they are",
       "person.last_admin: the board keeps at least one administrator in; make another one first",
+      "person.invalid_manager: the manager is not another active person of the workspace, or reports to this person already",
       "person.of_organization: the organization says whether that person is in",
       "listing.exists: the login is let in already, or is a person's who is in",
       "listing.unknown_host: nobody signs in through that provider here",
@@ -377,9 +380,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   plugin: {
     usage:
-      "plugin <key>  |  plugin <key> help [<command>]  |  plugin <key> <command> [<args>] [--<name> <value>]... [--file <path> | -] [--run <id>]  |  plugin <key> records <collection> [<id>] [--where <field>=<value>]... [--search <words>] [--project <key>] [--order <field>[:desc]] [--limit <n>] [--after <cursor>] [--archived] [--versions]  |  plugin <key> skills [<folder>|<file>] [--search <words> [--limit <n>] [--cursor <cursor>]]  |  plugin <key> skill <path>  |  plugin <key> skill --file <path> [--offset <n>] [--limit <n>]  |  plugin <key> enable --consent <capability>,... [--board new|<key>] [--projects all|<key>,...] [--set <key>=<value>]...  |  plugin <key> disable  |  plugin <key> settings [--set <key>=<value>]...  |  plugin <key> secret <name> [--remove]  |  plugin <key> grant <role> --person <login>|--project <key>|--everyone  |  plugin <key> revoke <grant id>",
+      "plugin <key>  |  plugin <key> help [<command>]  |  plugin <key> <command> [<args>] [--<name> <value>]... [--file <path> | -] [--run <id>]  |  plugin <key> records <collection> [<id>] [--where <field>=<value>]... [--search <words>] [--project <key>] [--order <field>[:desc]] [--limit <n>] [--after <cursor>] [--archived] [--versions]  |  plugin <key> skills [<folder>|<file>] [--search <words> [--limit <n>] [--cursor <cursor>]]  |  plugin <key> skill <path>  |  plugin <key> skill --file <path> [--offset <n>] [--limit <n>]  |  plugin <key> enable --consent <capability>,... [--board new|<key>] [--projects all|<key>,...] [--set <key>=<value>]...  |  plugin <key> disable  |  plugin <key> capabilities [--consent <capability>,...|none]  |  plugin <key> settings [--set <key>=<value>]...  |  plugin <key> secret <name> [--remove]  |  plugin <key> grant <role> --person <login>|--project <key>|--everyone  |  plugin <key> revoke <grant id>",
     overview:
-      "plugin <key> [help [<command>] | <command> [<args>] | records <collection> | skills | skill <path> | enable | disable | settings | secret | grant | revoke]",
+      "plugin <key> [help [<command>] | <command> [<args>] | records <collection> | skills | skill <path> | enable | disable | capabilities | settings | secret | grant | revoke]",
     synopsis:
       "One plugin: what it is for and its commands; a command run as you; its records, its skills; its settings, for an administrator.",
     about:
@@ -387,7 +390,8 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     limits: [
       "a command line: up to 200 words of up to 50,000 characters each; one file, up to the file bound (console help hand-in), with the plugin's files capability",
       "records: a page of up to 200; where: a field the collection indexes",
-      "enable: consent names every capability the manifest asks; settings and secrets as the manifest bounds them",
+      "enable: consent names every capability the manifest requires, and the optional ones to turn on; settings and secrets as the manifest bounds them",
+      "capabilities: --consent names the optional capabilities the plugin holds from now on, none for none of them; those it requires stay",
     ],
     refusals: [
       "plugin.not_found: no plugin has that key, or you may not know of it; or the plugin has no such command or query",
@@ -450,31 +454,36 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   ask: {
     usage:
-      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--to <login|me>] [--wait <seconds>] [--run <id>]',
+      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--attach <path>]... [--to <login|me>]... [--wait <seconds>] [--run <id>]',
     overview:
-      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--to <login|me>] [--wait <seconds>]',
+      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--attach <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. 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}`,
+    about: `Raises a decision a person must make: the question, the options to choose from, and what they need to know. --attach puts a file on the decision, in the one request: a picture of what is to be chosen between, a screenshot of what was made; a picture the body names as ![words](its name) is shown there, the rest after the body, and the person reads each back with \`console file <id>\` (ADR-0055). It is for the person you work for unless --to names another of the project, who then finds it among their decisions (ADR-0042); --to given again names several, each of whom finds it among theirs, and the first answer ends it (ADR-0057); 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",
+      `attach: a file: up to ${MAX_FILE_BYTES} bytes, not empty; called by its name, without the path; a picture is placed in the body as ![words](its name)`,
+      `at most ${MAX_FILES_PER_DECISION} files on one decision, together up to ${MAX_FILE_BYTES} bytes`,
+      `to: a login of the project, or me; up to ${MAX_DECIDERS} of them`,
       `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.invalid_decider: a person named may not work in the project",
+      "decision.too_many_deciders: more people named than one decision takes",
       "decision.too_many: the project holds as many decisions as one may",
+      "decision.too_many_files: more files than one decision carries",
+      "request.too_large: a file, or the files together, over the bound",
     ],
   },
   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.",
+      "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), and the record says so: the decision names you beside them as the agent the answer came through, where an answer given on the pages names the person alone (ADR-0056). 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`,
@@ -490,7 +499,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     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 (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.",
+      "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; the record names who wrote it, you beside them, and when (ADR-0056).",
     limits: [`outcome: ${MARKDOWN}`],
     refusals: ["decision.not_found: no decision has that id"],
   },
@@ -558,7 +567,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     usage: "file <id> [--out <path>]",
     synopsis: "Reads a file of the project to this machine, by its id.",
     about:
-      "Reads a file of the project from the console and writes it on this machine: one a run handed in, one put in a comment, or one attached to a page, by the id the task, the run or the page shows. Written under its own name in the working directory, at --out <path>, or into --out <directory>. Then look at it with your own tools.",
+      "Reads a file of the project from the console and writes it on this machine: one a run handed in, one put in a comment or on a decision, or one attached to a page, by the id the task, the run, the decision or the page shows. Written under its own name in the working directory, at --out <path>, or into --out <directory>. Then look at it with your own tools.",
     refusals: ["file.not_found: no file of this project has that id"],
   },
   docs: {