@skillcdn/console 0.1.13 → 0.1.15

package/src/cli/cli.ts

@@ -9,7 +9,14 @@ import {
 } from "../client.js";
 import { addDays, dayOf as dayOfDate, isDay } from "../dates.js";
 import { DEFAULT_PAGE_LIMIT, LIST_LIMIT, MAX_OPTIONS, MIN_OPTIONS } from "../limits.js";
-import type { RestClaim, RestDecision, RestPerson, RestTaskPatch } from "../schemas.js";
+import { fillRules, RULES_PATH, RULES_TITLE } from "../rules.js";
+import {
+  hostOfLogin,
+  type RestClaim,
+  type RestDecision,
+  type RestPerson,
+  type RestTaskPatch,
+} from "../schemas.js";
 import {
   COLOR_NAMES,
   type ColorName,
@@ -19,8 +26,10 @@ import {
   type PersonRole,
   PROJECT_ROLES,
   PROJECT_VISIBILITIES,
+  PROVIDER_KEYS,
   type ProjectRole,
   type ProjectVisibility,
+  type ProviderKey,
   TASK_PRIORITIES,
   TASK_STATES,
   type TaskPriority,
@@ -38,12 +47,15 @@ import {
   formatDocuments,
   formatGoal,
   formatGoalLine,
+  formatListingLine,
   formatMemberLine,
   formatMore,
   formatOptions,
   formatPersonLine,
+  formatPersonWork,
   formatProject,
   formatProjectLine,
+  formatRules,
   formatRun,
   formatRunLine,
   formatSkills,
@@ -102,6 +114,8 @@ export interface CliIo {
   readonly now: () => number;
   /** The version of the package the command runs from, when the entry point knows it. */
   readonly version?: string | undefined;
+  /** Where the console's own skills are on this machine, shipped with the package; nothing when they are not there. */
+  readonly skillsDir?: string | undefined;
   /** How `serve` listens on the loopback (ADR-0014); left out, the command cannot serve. */
   readonly listen?: Listen | undefined;
 }
@@ -368,6 +382,8 @@ function wordOf<T extends string>(value: string, words: readonly T[], what: stri
 
 const personRoleOf = (value: string): PersonRole =>
   wordOf(value, PERSON_ROLES, "a role in the workspace");
+const providerOf = (value: string): ProviderKey =>
+  wordOf(value, PROVIDER_KEYS, "a provider people sign in through");
 const projectRoleOf = (value: string): ProjectRole =>
   wordOf(value, PROJECT_ROLES, "a role in a project");
 const visibilityOf = (value: string): ProjectVisibility =>
@@ -522,7 +538,8 @@ const login: Command = async (args, io) => {
   // A connection (ADR-0011): a code a person approves on the console's own pages, and the token
   // handed over here once, never shown.
   const client = createClient({ baseUrl: url, fetch: io.fetch });
-  const agent = text(values, "agent") ?? "The console command";
+  // "<agent> on <machine>": the pages say the agent and keep the machine for a hover.
+  const agent = text(values, "agent") ?? agentOf(io.env) ?? "An agent";
   const begun = await client.connect({
     agent: io.hostname === undefined ? agent : `${agent} on ${io.hostname}`,
   });
@@ -550,11 +567,47 @@ const login: Command = async (args, io) => {
 
 const logout: Command = async (args, io) => {
   parse(args, {}, false);
+  const stored = await io.store.load();
+  const url = io.env.CONSOLE_URL ?? stored?.url;
+  const token = io.env.CONSOLE_TOKEN ?? stored?.token;
+  if (url === undefined || token === undefined) {
+    io.stdout("Not signed in here: nothing to forget.\n");
+    return EXIT.ok;
+  }
+  // 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;
+  try {
+    await createClient({ baseUrl: url, token, fetch: io.fetch }).giveUpToken();
+  } catch (error) {
+    if (!(error instanceof ApiError && error.code === "auth.required")) {
+      gone = false;
+    }
+  }
   await io.store.clear();
-  io.stdout("Signed out here. The token itself is removed on your Agents page.\n");
+  io.stdout(
+    gone
+      ? "Signed out: the token is given up at the console and forgotten here.\n"
+      : `Signed out here, but the console at ${url} could not be reached to give the token up: a person removes it on the Agents page.\n`,
+  );
+  if (io.env.CONSOLE_TOKEN !== undefined) {
+    io.stdout("CONSOLE_TOKEN in the environment still holds it: unset it.\n");
+  }
   return EXIT.ok;
 };
 
+/** The agent the command runs under, where its environment says so: what a connection is named by default. */
+function agentOf(env: CliIo["env"]): string | undefined {
+  if (env.CLAUDECODE !== undefined) {
+    return "Claude Code";
+  }
+  if (Object.keys(env).some((key) => key.startsWith("CODEX_"))) {
+    return "Codex";
+  }
+  return undefined;
+}
+
 const whoami: Command = async (args, io) => {
   const { values } = parse(args, {}, false);
   const session = await open(io, values);
@@ -597,7 +650,7 @@ const use: Command = async (args, io) => {
     session,
     project,
     () =>
-      `Working in ${project.name} (${project.key}) from this directory on: kept in ${kept}, which is meant to be committed.`,
+      `Working in ${project.name} (${project.key}) from this directory on: kept in ${kept}, which is meant to be committed. What its people ask of agents: console rules.`,
   );
   return EXIT.ok;
 };
@@ -653,10 +706,18 @@ const tasks: Command = async (args, io) => {
 };
 
 const work: Command = async (args, io) => {
-  const { values } = parse(args, {}, false);
+  const { values } = parse(args, { person: { type: "string" } }, false);
   const session = await open(io, values);
-  const found = await session.client.work();
-  answer(io, session, found, () => formatWork(found));
+  const login = text(values, "person");
+  if (login === undefined) {
+    const found = await session.client.work();
+    answer(io, session, found, () => formatWork(found));
+    return EXIT.ok;
+  }
+  // Another person's plate: the console decides whether it is the asker's to see.
+  const whose = await personOf(session, login);
+  const found = await session.client.personWork(whose.id);
+  answer(io, session, found, () => formatPersonWork(whose, found));
   return EXIT.ok;
 };
 
@@ -675,10 +736,118 @@ const skills: Command = async (args, io) => {
   const session = await open(io, values);
   const project = await session.project();
   const found = await project.skills();
-  answer(io, session, found, () => formatSkills(found));
+  answer(io, session, found, () => formatSkills(found, io.skillsDir));
+  return EXIT.ok;
+};
+
+/** A version number given as a flag, or nothing; anything else is not understood. */
+function versionOf(given: string | undefined): number | undefined {
+  if (given === undefined) {
+    return undefined;
+  }
+  const version = Number(given);
+  if (!Number.isInteger(version) || version < 1) {
+    throw misuse(`Not a version number: ${given}`);
+  }
+  return version;
+}
+
+// The rules of the board (ADR-0023): read before a task is taken, written by an owner for the
+// project and by an administrator for the workspace, through the same page the console keeps.
+const rules: Command = async (args, io) => {
+  const [verb, ...rest] = args;
+  if (verb === "write") {
+    const { values, positionals } = parse(rest, {
+      body: { type: "string" },
+      file: { type: "string" },
+      workspace: { type: "boolean" },
+      base: { type: "string" },
+    });
+    if (positionals.length > 1) {
+      throw misuse("Say the rules as one argument: console rules write --body <markdown>");
+    }
+    const given = positionals[0] ?? text(values, "body");
+    const none = given === "none";
+    const body = none ? undefined : await bodyOf(io, values, given);
+    if (!none && body === undefined) {
+      throw misuse(
+        "Say what the rules are to say: --body <markdown>, --file <path>, - to read standard input, or none to put the written rules away.",
+      );
+    }
+    const baseVersion = versionOf(text(values, "base"));
+    const session = await open(io, values);
+    if (on(values, "workspace")) {
+      if (none) {
+        const put = await session.client.archiveRules();
+        answer(
+          io,
+          session,
+          put,
+          () => "The organization's rules are put away: the console's own hold.",
+        );
+        return EXIT.ok;
+      }
+      const written = await session.client.writeRules({
+        body: body ?? "",
+        ...(baseVersion === undefined ? {} : { baseVersion }),
+      });
+      answer(io, session, written, () =>
+        written.page === null
+          ? "Nothing written: these are the console's own rules as they stand, and they hold already."
+          : `Wrote the workspace's rules, version ${written.page.version}.`,
+      );
+      return EXIT.ok;
+    }
+    const project = await session.project();
+    if (none) {
+      try {
+        const put = await project.archiveDocument(RULES_PATH);
+        answer(io, session, put, () => "This project's rules are put away: it adds none now.");
+      } catch (error) {
+        if (!(error instanceof ApiError) || error.code !== "document.not_found") {
+          throw error;
+        }
+        answer(io, session, null, () => "This project has no rules of its own to put away.");
+      }
+      return EXIT.ok;
+    }
+    const written = await project.writeDocument(RULES_PATH, {
+      title: RULES_TITLE,
+      body: body ?? "",
+      ...(baseVersion === undefined ? {} : { baseVersion }),
+    });
+    answer(io, session, written, () => `Wrote this project's rules, version ${written.version}.`);
+    return EXIT.ok;
+  }
+  const { values } = parse(args, {}, false);
+  const session = await open(io, values);
+  const key = await session.projectKey();
+  const [found, me] = await Promise.all([
+    key === undefined ? session.client.rules() : session.client.project(key).rules(),
+    session.client.me(),
+  ]);
+  const read =
+    "workspace" in found
+      ? {
+          workspace: forPerson(found.workspace, me.language),
+          project: forPerson(found.project, me.language),
+        }
+      : forPerson(found, me.language);
+  answer(io, session, read, () => formatRules(read));
   return EXIT.ok;
 };
 
+/**
+ * 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.
+ */
+function forPerson<T extends { readonly body: string | null }>(
+  half: T,
+  language: string | null,
+): T {
+  return half.body === null ? half : { ...half, body: fillRules(half.body, language) };
+}
+
 /** The flags that set a task's fields, shared by writing one and changing one. */
 const TASK_FIELDS: OptionSpec = {
   state: { type: "string" },
@@ -804,12 +973,21 @@ const take: Command = async (args, io) => {
     taskId: found.id,
     ...(agent === undefined ? {} : { agent }),
   });
-  answer(io, session, { run, task: found }, () =>
+  // The rules come with the run, as they read for the person: everything from here acts
+  // within them (ADR-0023).
+  const [ruling, me] = await Promise.all([project.rules(), session.client.me()]);
+  const rules = {
+    workspace: forPerson(ruling.workspace, me.language),
+    project: forPerson(ruling.project, me.language),
+  };
+  answer(io, session, { run, task: found, rules }, () =>
     [
       `Run ${run.id} began on #${found.number} ${found.title}, as "${run.agent}" for ${run.person.login}. The task is in progress and theirs. A run that was open on it is over now: the board cannot know whether its agent still ran, so taking it was deciding.`,
       "",
       formatTask(found),
       "",
+      formatRules(rules),
+      "",
       'Say how it goes: console report "<what you found or did>". Hand in what you make: console hand-in <https url | file path>.',
       'Ask when a person must decide: console ask "<question>" --option "..." --option "...". End with: console finish --summary "<what was done, what is left>".',
     ].join("\n"),
@@ -1403,25 +1581,67 @@ const people: Command = async (args, io) => {
   const { values } = parse(args, {}, false);
   const session = await open(io, values);
   const found = await session.client.people();
-  answer(io, session, found, () => found.items.map(formatPersonLine).join("\n"));
+  answer(io, session, found, () =>
+    [...found.items.map(formatPersonLine), ...found.listed.map(formatListingLine)].join("\n"),
+  );
   return EXIT.ok;
 };
 
+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>";
+
 const person: Command = async (args, io) => {
-  if (args[0] !== "role") {
-    throw misuse("Say what to do: console person role <login> <admin|member>");
+  const what = args[0];
+  if (what === "role") {
+    const { values, positionals } = parse(args.slice(1), {});
+    const [login, role] = theTwo(
+      positionals,
+      "Say whom and what: console person role <login> <admin|member>",
+    );
+    const wanted = personRoleOf(role);
+    const session = await open(io, values);
+    const found = await personOf(session, login);
+    const changed = await session.client.updatePerson(found.id, { role: wanted });
+    answer(io, session, changed, () => formatPersonLine(changed));
+    return EXIT.ok;
   }
-  const { values, positionals } = parse(args.slice(1), {});
-  const [login, role] = theTwo(
-    positionals,
-    "Say whom and what: console person role <login> <admin|member>",
-  );
-  const wanted = personRoleOf(role);
-  const session = await open(io, values);
-  const found = await personOf(session, login);
-  const changed = await session.client.updatePerson(found.id, { role: wanted });
-  answer(io, session, changed, () => formatPersonLine(changed));
-  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]");
+    const chosen = text(values, "host");
+    const host = chosen === undefined ? hostOfLogin(login) : providerOf(chosen);
+    const session = await open(io, values);
+    const made = await session.client.createListing({ host, login });
+    answer(io, session, made, () => formatListingLine(made));
+    return EXIT.ok;
+  }
+  if (what === "remove") {
+    const { values, positionals } = parse(args.slice(1), {});
+    const login = theOne(positionals, "Say whom: console person remove <login>");
+    const session = await open(io, values);
+    const { listed } = await session.client.people();
+    const found = listed.find((listing) => listing.login.toLowerCase() === login.toLowerCase());
+    if (found === undefined) {
+      throw misuse(
+        `Nobody called ${login} is let in and not signed in yet. console people lists them; a person who signed in is taken out with console person deactivate <login>.`,
+      );
+    }
+    await session.client.removeListing(found.id);
+    answer(io, session, { removed: found }, () => `${found.login} is no longer let in.`);
+    return EXIT.ok;
+  }
+  if (what === "deactivate" || what === "reactivate") {
+    const { values, positionals } = parse(args.slice(1), {});
+    const login = theOne(positionals, `Say whom: console person ${what} <login>`);
+    const session = await open(io, values);
+    const found = await personOf(session, login);
+    const changed = await session.client.updatePerson(found.id, {
+      status: what === "deactivate" ? "deactivated" : "active",
+    });
+    answer(io, session, changed, () => formatPersonLine(changed));
+    return EXIT.ok;
+  }
+  throw misuse(PERSON_USAGE);
 };
 
 /** The flags that set what a project is, shared by making one and changing one. */
@@ -1665,6 +1885,7 @@ const COMMANDS: Readonly<Record<string, Command>> = {
   goal,
   categories,
   skills,
+  rules,
   people,
   person,
   project,
@@ -1743,7 +1964,15 @@ function hintFor(error: ApiError): string {
     case "category.in_use":
       return "Tasks are sorted into the category. Move them out first: console task edit <number> --category <other|none>\n";
     case "person.last_admin":
-      return "The board keeps at least one administrator. Make another one first.\n";
+      return "The board keeps at least one administrator in. Make another one first.\n";
+    case "person.of_organization":
+      return "The organization says who is in: a person it let in comes and goes with it, and is listed by login to stay.\n";
+    case "listing.exists":
+      return "The login is let in already, or is a person's who is in. console people lists both.\n";
+    case "listing.not_found":
+      return "No login let in and not signed in yet has that id. console people lists them.\n";
+    case "listing.unknown_host":
+      return "Nobody signs in through that provider here. console whoami --json names the ways in.\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

@@ -6,9 +6,13 @@ import type {
   RestDocumentSummary,
   RestDocuments,
   RestGoal,
+  RestListing,
   RestMember,
   RestPerson,
+  RestPersonWork,
   RestProject,
+  RestProjectRules,
+  RestRules,
   RestRun,
   RestSkills,
   RestTask,
@@ -57,11 +61,20 @@ export function formatProject(project: RestProject): string {
   return lines.join("\n");
 }
 
-/** One person: their login, their name where the host gives one, and what they are in the workspace. */
+/** 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 {
+  const standing = person.status === "active" ? person.role : `${person.role}, deactivated`;
   return person.name === null
-    ? `${person.login}  (${person.role})`
-    : `${person.login}  ${person.name}  (${person.role})`;
+    ? `${person.login}  (${standing})`
+    : `${person.login}  ${person.name}  (${standing})`;
+}
+
+/** The provider a listing names, as people call it. */
+const HOST_NAMES = { gh: "GitHub", google: "Google" } as const;
+
+/** One login let in that nobody has signed in with yet (ADR-0022). */
+export function formatListingLine(listing: RestListing): string {
+  return `${listing.login}  (let in at ${HOST_NAMES[listing.host]}, not signed in yet)`;
 }
 
 /** One member of a project: their login, what they are in it, and since when. */
@@ -203,17 +216,27 @@ const SKILLS_WORDS: Readonly<Record<Exclude<RestSkills["status"], "none" | "read
   unavailable: "SkillCDN could not be reached; ask again later.",
 };
 
-/** The organization's skills: where they are, and each with what an agent loads it by. */
-export function formatSkills(skills: RestSkills): string {
-  if (skills.status === "none" || skills.address === null) {
-    return "No skills address: neither this project nor the console names one.";
+/**
+ * The organization's skills: where they are, each with what an agent loads it by, where a
+ * person connects an agent that has no connection to the address, and where the console's own
+ * skills are on this machine, when the command knows.
+ */
+export function formatSkills(skills: RestSkills, ownSkills?: string): string {
+  const own =
+    ownSkills === undefined
+      ? []
+      : ["", `The console's own skills, for working the board: ${ownSkills}`];
+  if (skills.status === "none" || skills.address === null || skills.page === null) {
+    return ["No skills address: neither this project nor the console names one.", ...own].join(
+      "\n",
+    );
   }
   const head = `skills at ${skills.address}, served by ${skills.source}: ${skills.status}`;
   if (skills.status !== "ready") {
-    return `${head}\n${SKILLS_WORDS[skills.status]}`;
+    return [head, SKILLS_WORDS[skills.status], ...own].join("\n");
   }
   if (skills.items.length === 0) {
-    return `${head}\nNo skills at this address.`;
+    return [head, "No skills at this address.", ...own].join("\n");
   }
   const lines = [head];
   for (const skill of skills.items) {
@@ -221,11 +244,41 @@ export function formatSkills(skills: RestSkills): string {
   }
   lines.push(
     "",
-    "Load a skill by its URI through your SkillCDN connection. --json adds the page of each, for a person.",
+    `Load a skill by its URI through your SkillCDN connection to this address; an agent without one is connected by a person at ${skills.page}. --json adds the page of each, for a person.`,
+    ...own,
   );
   return lines.join("\n");
 }
 
+/** One half of the rules: where it comes from, and the text as it stands. */
+function formatRulesHalf(where: "the workspace" | "this project", rules: RestRules): string {
+  const page = rules.page;
+  const facts =
+    page === null
+      ? undefined
+      : `v${page.version}, by ${writer(page.updatedBy, page.agent)}; ${page.updatedAt}`;
+  if (rules.source === "none" || rules.body === null) {
+    return `Rules of ${where}: none of its own; the workspace's hold.`;
+  }
+  const head =
+    rules.source === "reference"
+      ? `Rules of ${where}: the console's own, until an administrator writes the organization's (console rules write --workspace).`
+      : `Rules of ${where} (${facts ?? "written"}):`;
+  return `${head}\n\n${rules.body.trimEnd()}`;
+}
+
+/** The rules that hold: the workspace's, and what the project adds when the command works in one. */
+export function formatRules(rules: RestProjectRules | RestRules): string {
+  if ("workspace" in rules) {
+    return [
+      formatRulesHalf("the workspace", rules.workspace),
+      "",
+      formatRulesHalf("this project", rules.project),
+    ].join("\n");
+  }
+  return formatRulesHalf("the workspace", rules);
+}
+
 /** 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;
@@ -282,6 +335,17 @@ export function formatWork(work: RestWork): string {
   return lines.join("\n");
 }
 
+/** Another person's plate: their open tasks, each with its project; no decisions, which wait for anyone. */
+export function formatPersonWork(person: RestPerson, work: RestPersonWork): string {
+  if (work.tasks.length === 0) {
+    return `No open task is assigned to ${person.login}.`;
+  }
+  return [
+    `tasks assigned to ${person.login}:`,
+    ...work.tasks.map(({ project, task }) => `  ${project.key}  ${formatTaskLine(task)}`),
+  ].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

@@ -20,6 +20,7 @@ import {
   MAX_PROJECT_SYMBOL_LENGTH,
   MAX_QUESTION_LENGTH,
   MAX_REPORTS_PER_RUN,
+  MAX_RULES_LENGTH,
   MAX_SUMMARY_LENGTH,
   MAX_TITLE_LENGTH,
   MAX_VERSIONS_PER_DOCUMENT,
@@ -83,7 +84,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   login: {
     usage: "login --url <origin> [--agent <name>] [--token-stdin]",
     about:
-      "Connects this agent to the console: shows an address and a code, which a person opens signed in, names the agent and approves; the command then receives a token of its own and keeps it, with the console's address, in your home directory, never showing it. An agent running the command relays the address and the code to its person and waits. --agent says what the agent calls itself. --token-stdin reads a token made by hand from standard input instead, for a script or a job.",
+      "Connects this agent to the console: shows an address and a code, which a person opens signed in, names the agent and approves; the command then receives a token of its own and keeps it, with the console's address, in your home directory, never showing it. An agent running the command relays the address and the code to its person and waits. --agent says what the agent calls itself; left out, the command names the agent it runs under where its environment says so (Claude Code, Codex), else An agent; the machine's name follows, and the pages show the name before 'on' with the whole on hover. --token-stdin reads a token made by hand from standard input instead, for a script or a job.",
     refusals: [
       "connect.not_found: the code was not approved in time, or the person said it was not theirs; run login again",
       "the console does not know the token given: make one on the Agents page and try again",
@@ -92,7 +93,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   logout: {
     usage: "logout",
     about:
-      "Forgets the address and the token kept here. The token itself is removed on the Agents page.",
+      "Signs this agent out: gives the token up at the console, so that it is good for nothing from now on, and forgets it with the address kept here. A console out of reach leaves the token to the Agents page.",
   },
   whoami: {
     usage: "whoami",
@@ -111,9 +112,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     refusals: ["project.not_found: no project has the key, or it is not yours to see"],
   },
   work: {
-    usage: "work",
+    usage: "work [--person <login>]",
     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.",
+      "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. --person <login> shows another person's plate, for an administrator or for an owner of a project they are in: their open tasks within the projects you may see, without the decisions, which wait for anyone.",
   },
   tasks: {
     usage:
@@ -159,15 +160,19 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   people: {
     usage: "people",
     about:
-      "Everyone of the workspace, by login, with their name where the host gives one and what they are in it: admin, who configures the workspace, or member, who works in the projects they are in. The logins are what --assignee, member and person role take.",
+      "Everyone of the workspace, by login, with their name where the host gives one and what they are in it: admin, who configures the workspace, or member, who works in the projects they are in; a person taken out is marked deactivated. Then the logins an administrator let in that nobody has signed in with yet. The logins are what --assignee, member and person take.",
   },
   person: {
-    usage: "person role <login> <admin|member>",
+    usage:
+      "person role <login> <admin|member>  |  person add <login> [--host gh|google]  |  person remove <login>  |  person deactivate <login>  |  person reactivate <login>",
     about:
-      "Says what a person is in the workspace, for an administrator: the person themselves on the People page, or their agent here, named on it. The board keeps at least one administrator.",
+      "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.",
     refusals: [
-      "auth.forbidden: only an administrator says what a person is",
-      "person.last_admin: the board keeps at least one administrator; make another one first",
+      "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.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",
     ],
   },
   project: {
@@ -228,7 +233,20 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   skills: {
     usage: "skills",
     about:
-      "The organization's skills, as SkillCDN serves them at the console's address: each with its description and the URI you load it by through your own SkillCDN connection. --json adds the page of each, for a person.",
+      "The organization's skills, as SkillCDN serves them at the project's address: each with its description and the URI you load it by through your own SkillCDN connection, which a person makes at the address's page when you have none; and where the console's own skills are on this machine. --json adds the page of each, for a person.",
+  },
+  rules: {
+    usage:
+      "rules  |  rules write --body <markdown>|--file <path>|-|none [--workspace] [--base <version>]",
+    about:
+      "What this organization asks of agents (ADR-0023): the workspace's rules, the console's own until an administrator writes the organization's, and this project's own when it has them. Read them before taking a task; take prints them again. rules write writes this project's rules, for an owner, or with --workspace the workspace's, for an administrator; none puts the written rules away, so that the console's own hold again, or the project adds none. Without a project named, rules shows the workspace's alone.",
+    limits: [
+      `body: Markdown, up to ${MAX_RULES_LENGTH} characters; the console's own rules, written as they are, write nothing`,
+    ],
+    refusals: [
+      "auth.forbidden: an owner writes a project's rules, an administrator the workspace's",
+      "document.conflict: the rules have moved on since --base; read them again",
+    ],
   },
   take: {
     usage: "take <number|id> [--agent <name>]",
@@ -384,6 +402,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
 const preamble = (version: string | undefined): string =>
   `console${version === undefined ? "" : ` ${version}`}: the board of your organization's work with AI agents, from the command line.
 You act as the person whose token you hold; everything you send is shown to people as text.
+The rules of this organization come with the task: console take prints them; console rules reads them any time.
 
 Usage: console <command> [arguments] [--json] [--url <origin>] [--project <key>]
 `;
@@ -425,6 +444,7 @@ const SECTIONS: readonly { readonly title: string; readonly commands: readonly s
       "runs",
       "run",
       "skills",
+      "rules",
     ],
   },
   { title: "Working", commands: ["take", "report", "hand-in", "ask", "finish", "fail", "abandon"] },

package/src/cli/main.ts

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
+import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { hostname } from "node:os";
 import process from "node:process";
+import { fileURLToPath } from "node:url";
 import * as z from "zod/mini";
 import { runCli } from "./cli.js";
 import { createFileStore, defaultConfigDir } from "./credentials.js";
@@ -16,6 +18,8 @@ import { readBytesAt, readFileAt, readStdin } from "./terminal.js";
 const manifest = z
   .object({ version: z.string() })
   .safeParse(createRequire(import.meta.url)("../../package.json"));
+/** The console's own skills, shipped with the package beside dist/ (ADR-0015); not there in a checkout before packing. */
+const skillsDir = fileURLToPath(new URL("../../skills/", import.meta.url));
 
 process.exitCode = await runCli(process.argv.slice(2), {
   env: process.env,
@@ -35,5 +39,6 @@ process.exitCode = await runCli(process.argv.slice(2), {
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
   now: () => Date.now(),
   version: manifest.success ? manifest.data.version : undefined,
+  skillsDir: existsSync(skillsDir) ? skillsDir : undefined,
   listen: listenOn,
 });