@skillcdn/console 0.1.9 → 0.1.10

package/src/cli/cli.ts

@@ -7,18 +7,29 @@ import {
   type FetchLike,
   type ProjectClient,
 } from "../client.js";
+import { addDays, dayOf as dayOfDate, isDay } from "../dates.js";
 import { MAX_OPTIONS, MIN_OPTIONS } from "../limits.js";
-import type { RestClaim, RestDecision } from "../schemas.js";
-import { TASK_PRIORITIES, TASK_STATES, type TaskPriority, type TaskState } from "../vocabulary.js";
+import type { RestClaim, RestDecision, RestTaskPatch } from "../schemas.js";
+import {
+  GOAL_STATES,
+  type GoalState,
+  TASK_PRIORITIES,
+  TASK_STATES,
+  type TaskPriority,
+  type TaskState,
+} from "../vocabulary.js";
 import { loadWebRoot, type WebRoot, WebRootError } from "../web.js";
 import type { CredentialStore } from "./credentials.js";
 import type { DirectoryStore } from "./directory.js";
 import {
   formatAnswer,
+  formatCategoryLine,
   formatDecision,
   formatDecisionLine,
   formatDocument,
   formatDocuments,
+  formatGoal,
+  formatGoalLine,
   formatOptions,
   formatProjectLine,
   formatRun,
@@ -28,6 +39,7 @@ import {
   formatTaskLine,
   formatVersion,
   formatVersionLine,
+  formatWork,
 } from "./format.js";
 import { COMMAND_HELP, helpFor, usage } from "./help.js";
 import { createServeHandler, DEFAULT_SERVE_PORT, type Listen } from "./serve.js";
@@ -255,6 +267,79 @@ function priorityOf(value: string | undefined): TaskPriority | undefined {
   return found;
 }
 
+function goalStateOf(value: string | undefined): GoalState | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const found = GOAL_STATES.find((state) => state === value);
+  if (found === undefined) {
+    throw misuse(`Not a state of a goal: ${value}. One of ${GOAL_STATES.join(", ")}`);
+  }
+  return found;
+}
+
+/** Today by this machine's clock, as a day. */
+const todayOf = (io: CliIo): string => dayOfDate(new Date(io.now()));
+
+/**
+ * A day as a flag takes one: `2026-10-24`, `today`, `tomorrow`, or `+<n>` days from today; and
+ * `none` where a field may be cleared, which is `null` on the wire.
+ */
+function dayOf(io: CliIo, value: string | undefined, clearable = false): string | null | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (clearable && value === "none") {
+    return null;
+  }
+  if (value === "today") {
+    return todayOf(io);
+  }
+  if (value === "tomorrow") {
+    return addDays(todayOf(io), 1);
+  }
+  const ahead = /^\+(\d{1,3})$/.exec(value);
+  if (ahead !== null) {
+    return addDays(todayOf(io), Number(ahead[1]));
+  }
+  if (!isDay(value)) {
+    throw misuse(`Not a day: ${value}. Say it as 2026-10-24, today, tomorrow, or +7`);
+  }
+  return value;
+}
+
+/** A value a field is set to, or `none` to clear it, which is `null` on the wire. */
+const orNone = (value: string | undefined): string | null | undefined =>
+  value === "none" ? null : value;
+
+/** The id of the person a flag names: `me`, or a login of the workspace. */
+async function personIdOf(
+  session: Session,
+  value: string | undefined,
+): Promise<string | null | undefined> {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === "none") {
+    return null;
+  }
+  if (value === "me") {
+    const me = await session.client.me();
+    if (me.person === null) {
+      throw failed("The console does not know this token. Sign in again: console login");
+    }
+    return me.person.id;
+  }
+  const { items } = await session.client.people();
+  const found = items.find((person) => person.login.toLowerCase() === value.toLowerCase());
+  if (found === undefined) {
+    throw misuse(
+      `Nobody of the workspace is called ${value}. console people is not a command; the logins are as people sign in.`,
+    );
+  }
+  return found.id;
+}
+
 function secondsOf(value: string | undefined, fallback: number): number {
   if (value === undefined) {
     return fallback;
@@ -452,17 +537,67 @@ const use: Command = async (args, io) => {
 };
 
 const tasks: Command = async (args, io) => {
-  const { values } = parse(args, { state: { type: "string" } }, false);
+  const { values } = parse(
+    args,
+    {
+      state: { type: "string" },
+      open: { type: "boolean" },
+      mine: { type: "boolean" },
+      category: { type: "string" },
+      goal: { type: "string" },
+      due: { type: "string" },
+    },
+    false,
+  );
   const state = stateOf(text(values, "state"));
   const session = await open(io, values);
   const project = await session.project();
-  const found = await project.tasks(state === undefined ? {} : { state });
+  // What is due: a day, or the words for the usual windows; overdue keeps only the open ones.
+  const due = text(values, "due");
+  const today = todayOf(io);
+  const dueBy =
+    due === undefined
+      ? undefined
+      : due === "overdue"
+        ? addDays(today, -1)
+        : due === "week"
+          ? addDays(today, 6)
+          : (dayOf(io, due) ?? undefined);
+  const assignee = on(values, "mine")
+    ? ((await personIdOf(session, "me")) ?? undefined)
+    : undefined;
+  const found = await project.tasks({
+    ...(state === undefined ? {} : { state }),
+    ...(on(values, "open") || due === "overdue" ? { open: true } : {}),
+    ...(assignee === undefined ? {} : { assignee }),
+    ...(text(values, "category") === undefined ? {} : { category: text(values, "category") }),
+    ...(text(values, "goal") === undefined ? {} : { goal: text(values, "goal") }),
+    ...(dueBy === undefined ? {} : { dueBy }),
+  });
   answer(io, session, found, () =>
     found.items.length === 0 ? "No tasks." : found.items.map(formatTaskLine).join("\n"),
   );
   return EXIT.ok;
 };
 
+const work: Command = async (args, io) => {
+  const { values } = parse(args, {}, false);
+  const session = await open(io, values);
+  const found = await session.client.work();
+  answer(io, session, found, () => formatWork(found));
+  return EXIT.ok;
+};
+
+const categories: Command = async (args, io) => {
+  const { values } = parse(args, {}, false);
+  const session = await open(io, values);
+  const found = await session.client.categories();
+  answer(io, session, found, () =>
+    found.items.length === 0 ? "No categories." : found.items.map(formatCategoryLine).join("\n"),
+  );
+  return EXIT.ok;
+};
+
 const skills: Command = async (args, io) => {
   const { values } = parse(args, {}, false);
   const session = await open(io, values);
@@ -472,33 +607,105 @@ const skills: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+/** The flags that set a task's fields, shared by writing one and changing one. */
+const TASK_FIELDS: OptionSpec = {
+  state: { type: "string" },
+  priority: { type: "string" },
+  category: { type: "string" },
+  goal: { type: "string" },
+  starts: { type: "string" },
+  due: { type: "string" },
+  assignee: { type: "string" },
+  parent: { type: "string" },
+};
+
+/** What the flags say of a task's fields, as the API takes them; `none` clears a field. */
+async function taskFieldsOf(
+  io: CliIo,
+  session: Session,
+  project: ProjectClient,
+  values: Values,
+): Promise<RestTaskPatch> {
+  const state = stateOf(text(values, "state"));
+  const priority = priorityOf(text(values, "priority"));
+  const category = orNone(text(values, "category"));
+  const goalId = orNone(text(values, "goal"));
+  const startsOn = dayOf(io, text(values, "starts"), true);
+  const dueOn = dayOf(io, text(values, "due"), true);
+  const assigneeId = await personIdOf(session, text(values, "assignee"));
+  const parent = text(values, "parent");
+  const parentId =
+    parent === undefined ? undefined : parent === "none" ? null : (await project.task(parent)).id;
+  return {
+    ...(state === undefined ? {} : { state }),
+    ...(priority === undefined ? {} : { priority }),
+    ...(category === undefined ? {} : { category }),
+    ...(goalId === undefined ? {} : { goalId }),
+    ...(startsOn === undefined ? {} : { startsOn }),
+    ...(dueOn === undefined ? {} : { dueOn }),
+    ...(assigneeId === undefined ? {} : { assigneeId }),
+    ...(parentId === undefined ? {} : { parentId }),
+  };
+}
+
 const newTask: Command = async (args, io) => {
   const { values, positionals } = parse(args, {
+    ...TASK_FIELDS,
     body: { type: "string" },
     file: { type: "string" },
-    state: { type: "string" },
-    priority: { type: "string" },
   });
   const title = theOne(positionals, 'Say the title: console task new "<title>"');
-  const state = stateOf(text(values, "state"));
-  const priority = priorityOf(text(values, "priority"));
   const body = await bodyOf(io, values, text(values, "body"));
   const session = await open(io, values);
   const project = await session.project();
+  const fields = await taskFieldsOf(io, session, project, values);
   const made = await project.createTask({
     title,
     ...(body === undefined ? {} : { body }),
-    ...(state === undefined ? {} : { state }),
-    ...(priority === undefined ? {} : { priority }),
+    ...fields,
   });
   answer(io, session, made, () => `Task #${made.number} written: ${made.title}\nid: ${made.id}`);
   return EXIT.ok;
 };
 
+const editTask: Command = async (args, io) => {
+  const { values, positionals } = parse(args, {
+    ...TASK_FIELDS,
+    title: { type: "string" },
+    body: { type: "string" },
+    file: { type: "string" },
+  });
+  const ref = theOne(
+    positionals,
+    "Say which task: console task edit <number|id> --due <day> [--category <key>] ...",
+  );
+  const body = await bodyOf(io, values, text(values, "body"));
+  const session = await open(io, values);
+  const project = await session.project();
+  const title = text(values, "title");
+  const patch: RestTaskPatch = {
+    ...(title === undefined ? {} : { title }),
+    ...(body === undefined ? {} : { body }),
+    ...(await taskFieldsOf(io, session, project, values)),
+  };
+  if (Object.keys(patch).length === 0) {
+    throw misuse(
+      "Say what to change: --title, --body, --state, --priority, --category, --goal, --starts, --due, --assignee or --parent; none clears a field.",
+    );
+  }
+  const found = await project.task(ref);
+  const changed = await project.updateTask(found.id, patch);
+  answer(io, session, changed, () => formatTask(changed));
+  return EXIT.ok;
+};
+
 const task: Command = async (args, io) => {
   if (args[0] === "new") {
     return newTask(args.slice(1), io);
   }
+  if (args[0] === "edit") {
+    return editTask(args.slice(1), io);
+  }
   const { values, positionals } = parse(args, {});
   const ref = theOne(positionals, "Say which task: console task <number|id>");
   const session = await open(io, values);
@@ -864,6 +1071,88 @@ const restore: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+const goals: Command = async (args, io) => {
+  const { values } = parse(args, {}, false);
+  const session = await open(io, values);
+  const project = await session.project();
+  const found = await project.goals();
+  answer(io, session, found, () =>
+    found.items.length === 0
+      ? "No goals. An owner sets one: console goal new <title> --due <day>"
+      : found.items.map(formatGoalLine).join("\n"),
+  );
+  return EXIT.ok;
+};
+
+const GOAL_FIELDS: OptionSpec = {
+  state: { type: "string" },
+  due: { type: "string" },
+  body: { type: "string" },
+  file: { type: "string" },
+};
+
+const newGoal: Command = async (args, io) => {
+  const { values, positionals } = parse(args, GOAL_FIELDS);
+  const title = theOne(positionals, 'Say the title: console goal new "<title>" [--due <day>]');
+  const state = goalStateOf(text(values, "state"));
+  const dueOn = dayOf(io, text(values, "due"));
+  const body = await bodyOf(io, values, text(values, "body"));
+  const session = await open(io, values);
+  const project = await session.project();
+  const made = await project.createGoal({
+    title,
+    ...(body === undefined ? {} : { body }),
+    ...(state === undefined ? {} : { state }),
+    ...(dueOn === undefined ? {} : { dueOn }),
+  });
+  answer(io, session, made, () => `Goal set: ${made.title}\nid: ${made.id}`);
+  return EXIT.ok;
+};
+
+const editGoal: Command = async (args, io) => {
+  const { values, positionals } = parse(args, { ...GOAL_FIELDS, title: { type: "string" } });
+  const id = theOne(positionals, "Say which goal: console goal edit <id> --state <state> ...");
+  const title = text(values, "title");
+  const state = goalStateOf(text(values, "state"));
+  const dueOn = dayOf(io, text(values, "due"), true);
+  const body = await bodyOf(io, values, text(values, "body"));
+  const patch = {
+    ...(title === undefined ? {} : { title }),
+    ...(body === undefined ? {} : { body }),
+    ...(state === undefined ? {} : { state }),
+    ...(dueOn === undefined ? {} : { dueOn }),
+  };
+  if (Object.keys(patch).length === 0) {
+    throw misuse(
+      "Say what to change: --title, --body, --state or --due; --due none clears the day.",
+    );
+  }
+  const session = await open(io, values);
+  const project = await session.project();
+  const changed = await project.updateGoal(id, patch);
+  answer(io, session, changed, () => formatGoal(changed));
+  return EXIT.ok;
+};
+
+const goal: Command = async (args, io) => {
+  if (args[0] === "new") {
+    return newGoal(args.slice(1), io);
+  }
+  if (args[0] === "edit") {
+    return editGoal(args.slice(1), io);
+  }
+  const { values, positionals } = parse(args, {});
+  const id = theOne(positionals, "Say which goal: console goal <id>");
+  const session = await open(io, values);
+  const project = await session.project();
+  const found = await project.goal(id);
+  const towards = await project.tasks({ goal: found.id });
+  answer(io, session, { goal: found, tasks: towards.items }, () =>
+    formatGoal(found, towards.items),
+  );
+  return EXIT.ok;
+};
+
 const decisions: Command = async (args, io) => {
   const { values } = parse(args, { open: { type: "boolean" } }, false);
   const session = await open(io, values);
@@ -1024,8 +1313,12 @@ const COMMANDS: Readonly<Record<string, Command>> = {
   serve,
   projects,
   use,
+  work,
   tasks,
   task,
+  goals,
+  goal,
+  categories,
   skills,
   take,
   report,
@@ -1072,6 +1365,14 @@ function hintFor(error: ApiError): string {
       return "The page has moved on since the version you started from. Read it again, and write from there.\n";
     case "document.archived":
       return "The page is archived. console restore <path> brings it back first.\n";
+    case "task.invalid_category":
+      return "No category has that key. console categories lists them.\n";
+    case "task.invalid_goal":
+      return "No goal of this project has that id. console goals lists them.\n";
+    case "task.invalid_dates":
+      return "The due day is before the start. Say a due day on or after it.\n";
+    case "goal.not_found":
+      return "No goal of this project has that id. console goals lists them.\n";
     case "connect.too_many":
       return "The console holds as many connections as it may at once. Try again in a few minutes.\n";
     case "network":

package/src/cli/format.ts

@@ -1,15 +1,18 @@
 import type {
   RestArtifact,
+  RestCategory,
   RestDecision,
   RestDocument,
   RestDocumentSummary,
   RestDocuments,
+  RestGoal,
   RestProject,
   RestRun,
   RestSkills,
   RestTask,
   RestVersion,
   RestVersionSummary,
+  RestWork,
 } from "../schemas.js";
 
 // What the command prints: one line per thing in a list, a few lines for one thing in full.
@@ -47,6 +50,12 @@ export function formatTaskLine(task: RestTask): string {
   if (task.assignee !== null) {
     notes.push(`assigned to ${task.assignee.login}`);
   }
+  if (task.category !== null) {
+    notes.push(task.category.key);
+  }
+  if (task.dueOn !== null) {
+    notes.push(`due ${task.dueOn}`);
+  }
   if (task.openDecisions > 0) {
     notes.push(`${plural(task.openDecisions, "decision")} waiting`);
   }
@@ -56,6 +65,28 @@ export function formatTaskLine(task: RestTask): string {
   return `#${task.number}  ${task.state}  ${task.priority}  ${task.title}  (${notes.join("; ")})`;
 }
 
+/** The plan and what happened, as a line each, only where there is something to say. */
+function scheduleLines(task: RestTask): string[] {
+  const lines: string[] = [];
+  const plan = [
+    task.category === null ? undefined : `category: ${task.category.key}`,
+    task.goalId === null ? undefined : `goal: ${task.goalId}`,
+    task.startsOn === null ? undefined : `starts: ${task.startsOn}`,
+    task.dueOn === null ? undefined : `due: ${task.dueOn}`,
+  ].filter((part) => part !== undefined);
+  if (plan.length > 0) {
+    lines.push(plan.join("  "));
+  }
+  const happened = [
+    task.startedAt === null ? undefined : `started: ${task.startedAt}`,
+    task.doneAt === null ? undefined : `done: ${task.doneAt}`,
+  ].filter((part) => part !== undefined);
+  if (happened.length > 0) {
+    lines.push(happened.join("  "));
+  }
+  return lines;
+}
+
 /** One task in full; with the decisions about it and the runs on it, when given. */
 export function formatTask(
   task: RestTask,
@@ -66,6 +97,7 @@ export function formatTask(
     `#${task.number} ${task.title}`,
     `state: ${task.state}  priority: ${task.priority}  owner: ${task.owner.login}  assignee: ${task.assignee?.login ?? "nobody"}`,
     `id: ${task.id}${task.parentId === null ? "" : `  part of: ${task.parentId}`}`,
+    ...scheduleLines(task),
   ];
   if (task.links.length > 0) {
     lines.push("links:");
@@ -165,6 +197,62 @@ export function formatSkills(skills: RestSkills): string {
   return lines.join("\n");
 }
 
+/** How far a goal is, from its tasks: the done, the at work, and the rest, in one phrase. */
+function progressOf(goal: RestGoal): string {
+  const counts = goal.taskCounts;
+  const total = counts.idea + counts.ready + counts.in_progress + counts.in_review + counts.done;
+  const working = counts.in_progress + counts.in_review;
+  return `${counts.done}/${total} done${working === 0 ? "" : `, ${working} in progress`}${counts.dropped === 0 ? "" : `, ${counts.dropped} dropped`}`;
+}
+
+/** One goal: its id, its state, its title, when it is due, and how far it is. */
+export function formatGoalLine(goal: RestGoal): string {
+  const notes = [goal.dueOn === null ? "no target day" : `due ${goal.dueOn}`, progressOf(goal)];
+  return `${goal.id}  ${goal.state}  ${goal.title}  (${notes.join("; ")})`;
+}
+
+/** One goal in full; with the tasks that work towards it, when given. */
+export function formatGoal(goal: RestGoal, tasks?: readonly RestTask[]): string {
+  const lines = [
+    `goal ${goal.id}: ${goal.title}`,
+    `state: ${goal.state}  due: ${goal.dueOn ?? "none"}  set by: ${goal.createdBy.login}`,
+    `progress: ${progressOf(goal)}`,
+  ];
+  if (goal.body.trim().length > 0) {
+    lines.push("", goal.body.trimEnd());
+  }
+  if (tasks !== undefined) {
+    lines.push("", tasks.length === 0 ? "tasks: none" : "tasks:");
+    for (const task of tasks) {
+      lines.push(`  ${formatTaskLine(task)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/** One category: its key, what people call it, and its colour. */
+export function formatCategoryLine(category: RestCategory): string {
+  return `${category.key}  ${category.name}  (${category.color})`;
+}
+
+/** What is on a person's plate: their open tasks by project, and the decisions waiting. */
+export function formatWork(work: RestWork): string {
+  const lines: string[] = [];
+  if (work.tasks.length === 0) {
+    lines.push("No open task is assigned to you.");
+  } else {
+    lines.push("tasks assigned to you:");
+    for (const { project, task } of work.tasks) {
+      lines.push(`  ${project.key}  ${formatTaskLine(task)}`);
+    }
+  }
+  lines.push("", work.decisions.length === 0 ? "decisions waiting: none" : "decisions waiting:");
+  for (const { project, decision } of work.decisions) {
+    lines.push(`  ${project.key}  ${formatDecisionLine(decision)}`);
+  }
+  return lines.join("\n");
+}
+
 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)})`;

package/src/cli/help.ts

@@ -51,6 +51,22 @@ 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`;
 const DOCUMENT_REFUSALS = ["document.not_found: no page has that path in this project"];
 
+const DAY = "a day as 2026-10-24, today, tomorrow, or +7 for seven days from today";
+const TASK_FIELD_FLAGS =
+  "[--state <state>] [--priority <priority>] [--category <key>] [--goal <id>] [--starts <day>] [--due <day>] [--assignee <login|me>] [--parent <number|id>]";
+const TASK_FIELD_LIMITS = [
+  `starts, due: ${DAY}; the due day is not before the start`,
+  "category: the key of one of the workspace's categories (console categories); goal: the id of one of the project's goals (console goals)",
+  "assignee: a login of the workspace, or me; parent: a task of the project",
+];
+const TASK_FIELD_REFUSALS = [
+  "task.invalid_category: no category has that key",
+  "task.invalid_goal: the goal is not one of this project",
+  "task.invalid_dates: the due day is before the start",
+  "task.invalid_assignee: the person may not work in the project",
+  "task.invalid_parent: the parent is not a task of the project, or would make a loop",
+];
+
 export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   login: {
     usage: "login --url <origin> [--agent <name>] [--token-stdin]",
@@ -82,18 +98,52 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       "Says which project this directory works in: writes .skillcdn-console.json here, which the commands read from this directory or one above it, and which is meant to be committed. --project <key> on any command, or CONSOLE_PROJECT in the environment, wins over it.",
     refusals: ["project.not_found: no project has the key, or it is not yours to see"],
   },
+  work: {
+    usage: "work",
+    about:
+      "What is on your plate across the projects you may see: the open tasks assigned to you, the sooner due first, each with its project; and the decisions waiting for a person. Needs no project.",
+  },
   tasks: {
-    usage: "tasks [--state <state>]",
+    usage:
+      "tasks [--state <state>] [--open] [--mine] [--category <key>] [--goal <id>] [--due <day|today|week|overdue>]",
     about:
-      "The tasks on the board, newest first: number, state, priority, title, who owns and works on each, and what waits on it. States: idea, ready, in_progress, in_review, done, dropped.",
+      "The tasks on the board, newest first: number, state, priority, title, who owns and works on each, its category and its due day, and what waits on it. --open keeps the ones not done or dropped, --mine those assigned to you, --category and --goal those sorted into one, --due those due by a day: today, within the week, or overdue (the open ones past their day). States: idea, ready, in_progress, in_review, done, dropped.",
   },
   task: {
+    usage: `task <number|id>  |  task new <title> [--body <markdown>|--file <path>] ${TASK_FIELD_FLAGS}  |  task edit <number|id> [--title <title>] [--body <markdown>|--file <path>] ${TASK_FIELD_FLAGS}`,
+    about:
+      "One task in full, with its plan (category, goal, start and due days), what happened to it (when it was started and done, which the board keeps itself), the decisions about it and the runs on it; or a new task written down; or a task changed, only in what the flags say, where none clears a field (priorities: low, normal, high, urgent).",
+    limits: [
+      `title: one line, up to ${MAX_TITLE_LENGTH} characters`,
+      `body: ${MARKDOWN}`,
+      ...TASK_FIELD_LIMITS,
+    ],
+    refusals: ["task.not_found: no task has that number or id", ...TASK_FIELD_REFUSALS],
+  },
+  goals: {
+    usage: "goals",
+    about:
+      "The roadmap of the project: its goals, the active first, each with its id, its state (planned, active, done, dropped), its target day, and how far it is, counted from the tasks that work towards it.",
+  },
+  goal: {
     usage:
-      "task <number|id>  |  task new <title> [--body <markdown>|--file <path>] [--state <state>] [--priority <priority>]",
+      'goal <id>  |  goal new "<title>" [--body <markdown>|--file <path>] [--state <state>] [--due <day>]  |  goal edit <id> [--title <title>] [--body <markdown>|--file <path>] [--state <state>] [--due <day|none>]',
     about:
-      "One task in full, with the decisions about it and the runs on it; or a new task written down (priorities: low, normal, high, urgent).",
-    limits: [`title: one line, up to ${MAX_TITLE_LENGTH} characters`, `body: ${MARKDOWN}`],
-    refusals: ["task.not_found: no task has that number or id"],
+      "One goal in full, with the tasks that work towards it; or a goal set on the roadmap, for an owner of the project; or one changed, only in what the flags say. A task works towards a goal through its --goal.",
+    limits: [
+      `title: one line, up to ${MAX_TITLE_LENGTH} characters`,
+      `body: ${MARKDOWN}`,
+      `due: ${DAY}`,
+    ],
+    refusals: [
+      "goal.not_found: no goal of this project has that id",
+      "auth.forbidden: only an owner of the project sets its roadmap",
+    ],
+  },
+  categories: {
+    usage: "categories",
+    about:
+      "The categories tasks are sorted into, the same in every project: each with its key, which --category takes, its name and its colour. An administrator keeps them on the console's Categories page.",
   },
   skills: {
     usage: "skills",
@@ -283,7 +333,19 @@ const SECTIONS: readonly { readonly title: string; readonly commands: readonly s
   },
   {
     title: "The board",
-    commands: ["tasks", "task", "decisions", "decision", "runs", "run", "skills"],
+    commands: [
+      "work",
+      "tasks",
+      "task",
+      "goals",
+      "goal",
+      "categories",
+      "decisions",
+      "decision",
+      "runs",
+      "run",
+      "skills",
+    ],
   },
   { title: "Working", commands: ["take", "report", "hand-in", "ask", "finish", "fail", "abandon"] },
   {