@skillcdn/console 0.1.17 → 0.1.19

package/src/cli/help.ts

@@ -84,23 +84,28 @@ const TASK_FIELD_REFUSALS = [
 
 export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   login: {
-    usage: "login --url <origin> [--agent <name>] [--token-stdin]",
+    usage: "login --url <origin> [--agent <name>] [--token-stdin] [--default]",
     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; 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.",
+      "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 and the account, in your home directory, never showing it. One login per console and account: a second console adds a login beside the first, the first is the default console a directory that names none works at, and --default makes this one that. A login repeated for the same console and account replaces its token, which is given up at the console. 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",
     ],
   },
+  logins: {
+    usage: "logins",
+    about:
+      "The consoles this machine is signed in to, each with the account, what the token is called there, since when, and which is the default; never a token.",
+  },
   logout: {
-    usage: "logout",
+    usage: "logout [--url <origin>] [--account <login>]",
     about:
-      "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.",
+      "Signs this agent out of one console: gives the token up there, so that it is good for nothing from now on, and forgets it here. Which console: --url, else the one this directory is bound to, else the default, else the one console signed in to; --account says which account where the console has several. A console out of reach leaves the token to the Agents page.",
   },
   whoami: {
     usage: "whoami",
     about:
-      "Who the token acts as, which console it is for, and which project this directory works in.",
+      "Who the token acts as, which console the command talks to from here and as which account, and which project this directory works in.",
   },
   projects: {
     usage: "projects",
@@ -108,9 +113,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       "The projects you may work in: each with its key, its name, what you are in it, and what waits in it. Every command on the board works in one project.",
   },
   use: {
-    usage: "use <key>",
+    usage: "use <key> [--url <origin>] [--account <login>]",
     about:
-      "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.",
+      "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 in a private repository and left out of a public one. The file names the project; and the console, where that is not the default login here or --url says so; and the account, where the console has several logins or --account says so. Never a token. --project <key> on any command, or CONSOLE_PROJECT in the environment, wins over the project it names.",
     refusals: ["project.not_found: no project has the key, or it is not yours to see"],
   },
   work: {
@@ -120,37 +125,43 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   tasks: {
     usage:
-      "tasks [--state <state>] [--open] [--mine] [--category <key>] [--goal <id>] [--due <day|today|week|overdue>] [--limit <n>] [--offset <n>]",
-    about: `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). A page at a time: ${DEFAULT_PAGE_LIMIT} unless --limit says otherwise, from --offset on; a last line says when there is more. States: idea, ready, in_progress, in_review, done, dropped.`,
+      "tasks [--state <state>] [--open] [--mine] [--category <key>] [--goal <id>] [--due <day|today|week|overdue>] [--unassigned] [--archived] [--limit <n>] [--offset <n>]",
+    about: `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, --unassigned those assigned to nobody (not with --mine), --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). The tasks put away (ADR-0029) are left out unless --archived asks for them alone. A page at a time: ${DEFAULT_PAGE_LIMIT} unless --limit says otherwise, from --offset on; a last line says when there is more. 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}`,
+    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}  |  task archive <number|id>  |  task archive --goal <id>  |  task restore <number|id>`,
     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, the runs on it and the discussion on it, each comment whole with its files; 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).",
+      "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, and when it was put away), the decisions about it, the runs on it and the discussion on it, each comment whole with its files; 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). archive puts a done or dropped task away (ADR-0029): out of the listings, the board and the calendar, open by its number still; with --goal, every done or dropped task of the goal at once, for an owner. restore brings one back.",
     limits: [
       `title: one line, up to ${MAX_TITLE_LENGTH} characters, saying what is to be done on its own; what it refers to goes in the body`,
       `body: ${MARKDOWN}`,
       ...TASK_FIELD_LIMITS,
     ],
-    refusals: ["task.not_found: no task has that number or id", ...TASK_FIELD_REFUSALS],
+    refusals: [
+      "task.not_found: no task has that number or id",
+      "task.open: an open task is not put away; one done or dropped is",
+      ...TASK_FIELD_REFUSALS,
+    ],
   },
   goals: {
-    usage: "goals",
+    usage: "goals [--category <key>] [--state <state>]",
     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.",
+      "The roadmap of the project: its goals, the active first, each with its id, its state (planned, active, done, dropped), its category, the days it starts and is meant to be reached by, and how far it is, counted from the tasks that work towards it. --category keeps those sorted into one, --state those in one state.",
   },
   goal: {
     usage:
-      '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>]',
+      'goal <id>  |  goal new "<title>" [--body <markdown>|--file <path>] [--state <state>] [--category <key>] [--starts <day>] [--due <day>]  |  goal edit <id> [--title <title>] [--body <markdown>|--file <path>] [--state <state>] [--category <key|none>] [--starts <day|none>] [--due <day|none>]',
     about:
-      "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.",
+      "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, where none clears a category or a day. A goal is planned in days as a task is, a start and a target, and sorted into a category of the workspace (console categories). A task works towards a goal through its --goal.",
     limits: [
       `title: one line, up to ${MAX_TITLE_LENGTH} characters`,
       `body: ${MARKDOWN}`,
-      `due: ${DAY}`,
+      `starts, due: ${DAY}`,
     ],
     refusals: [
       "goal.not_found: no goal of this project has that id",
+      "goal.invalid_category: no category of the workspace has that key",
+      "goal.invalid_dates: the target day is before the start",
       "auth.forbidden: only an owner of the project sets its roadmap",
     ],
   },
@@ -179,9 +190,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   project: {
     usage:
-      'project <key>  |  project new <key> "<name>" [--description <markdown>|--file <path>] [--visibility workspace|private] [--skills <address>|none] [--color <name>] [--symbol <text>]  |  project edit <key> [--name "<name>"] [the same flags; none clears]  |  project icon <key> <file>  |  project icon <key> --remove',
+      'project <key>  |  project new <key> "<name>" [--description <markdown>|--file <path>] [--visibility workspace|private] [--skills <address>|none] [--color <name>] [--symbol <text>]  |  project edit <key> [--name "<name>"] [the same flags; none clears]  |  project icon <key> <file>  |  project icon <key> --remove  |  project pack-token <key> --stdin  |  project pack-token <key> --remove',
     about:
-      "One project in full; or a project made, with you as its owner, private unless --visibility workspace says everyone of the workspace works in it; or one changed, only in what the flags say, for an owner; or its image for its mark, set from a file of this machine or taken away. The organization's skills are the project's unless --skills names an address of its own.",
+      "One project in full; or a project made, with you as its owner, private unless --visibility workspace says everyone of the workspace works in it; or one changed, only in what the flags say, for an owner; or its image for its mark, set from a file of this machine or taken away; or its pack token (ADR-0028), the token a person made at SkillCDN for a private pack, read from standard input and never an argument, which the console keeps sealed to read the pack with, or taken away. The organization's skills are the project's unless --skills names an address of its own.",
     limits: [
       `key: ${KEY}, up to ${MAX_PROJECT_KEY_LENGTH} characters; it does not change once made`,
       `name: one line, up to ${MAX_PROJECT_NAME_LENGTH} characters; description: up to ${MAX_PROJECT_DESCRIPTION_LENGTH}`,
@@ -204,9 +215,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   member: {
     usage:
-      "member add <login> [--role owner|member]  |  member role <login> <owner|member>  |  member remove <login>",
+      "member add <login> [--role owner|member] [--project <key>[,<key>...]]  |  member role <login> <owner|member>  |  member remove <login>",
     about:
-      "Lists a person of the workspace in the project, as a member unless --role says owner; changes what they are in it; or takes them off the list. For an owner of the project.",
+      "Lists a person of the workspace in the project, as a member unless --role says owner; changes what they are in it; or takes them off the list. For an owner of the project. With --project naming several keys with commas, member add lists the person in each of them in turn, one line per project; one listed already is said so, and the rest go on.",
     refusals: [
       "auth.forbidden: only an owner of the project lists its members",
       "member.invalid_person: the person is not of the workspace",
@@ -235,7 +246,17 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   skills: {
     usage: "skills",
     about:
-      "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.",
+      "The skills of the project's pack, as SkillCDN serves them at the project's address: each with its description, the path of its SKILL.md, which console skill reads it by, and the URI you load it by through your own SkillCDN connection where your host has one; and where the console's own skills are on this machine. A private pack is read with the pack token the project holds (ADR-0028). --json adds the page of each, for a person.",
+  },
+  skill: {
+    usage: "skill <path> [--file <path>]",
+    about:
+      "One skill of the project's pack, whole, as load_skill lays it out for you: the rules of the repository from its root to the nearest manifest, the skill's body, the files it includes, each under a line that names its path; then the files it has and what it refers to. Read by the console from the SkillCDN deployment, with the pack token the project holds where the pack is private, so you need no connection of your own. <path> is the path of the SKILL.md from the repository's root, as console skills lists it. --file <path> reads a file of the pack instead, whole, or what a folder holds. What you read is the pack's, under its license: what a private pack says stays in your work and is not copied into reports or pages beyond what the work needs.",
+    refusals: [
+      "status not_found: the pack is not served to the console; private, with no pack token on the project",
+      "status token_invalid: the pack token the project holds no longer works; an owner sets a new one",
+      "status failed, for a file: SkillCDN will not carry it, too large or not text",
+    ],
   },
   rules: {
     usage:
@@ -447,14 +468,18 @@ Exit codes: 0 done; 1 the console refused, or could not be reached (the reason i
 What the console refuses is printed as its code and its words. Everywhere:
 ${COMMON_REFUSALS.map((refusal) => `  ${refusal}`).join("\n")}
 
-Credentials: CONSOLE_URL and CONSOLE_TOKEN in the environment, else what login kept in
-$XDG_CONFIG_HOME/skillcdn-console/credentials.json (~/.config when XDG_CONFIG_HOME is unset).
+Which console a command talks to: --url, else CONSOLE_URL in the environment, else the console
+.skillcdn-console.json binds this directory to, else the default login. The token is then the one
+kept for that console alone (CONSOLE_TOKEN only together with CONSOLE_URL, for a hook or a job), in
+$XDG_CONFIG_HOME/skillcdn-console/credentials.json (~/.config when XDG_CONFIG_HOME is unset);
+a console nobody is signed in to here gets no request. --account <login> says which account where
+a console has several. console logins lists them.
 `;
 
 const SECTIONS: readonly { readonly title: string; readonly commands: readonly string[] }[] = [
   {
     title: "Signing in, once, as a person, and the project to work in",
-    commands: ["login", "logout", "whoami", "projects", "use"],
+    commands: ["login", "logins", "logout", "whoami", "projects", "use"],
   },
   {
     title: "The board",
@@ -470,6 +495,7 @@ const SECTIONS: readonly { readonly title: string; readonly commands: readonly s
       "runs",
       "run",
       "skills",
+      "skill",
       "rules",
     ],
   },

package/src/cli/install.ts

@@ -0,0 +1,111 @@
+// Where the command runs from, so that the update it is told to make is the one that takes
+// effect: installed for the machine, in a project, run once from a cache, or a checkout of the
+// repository. Read from the package's own path and the working directory; nothing is asked of
+// the system, so that a notice about versions costs a command nothing.
+
+export type InstallKind = "global" | "project" | "temporary" | "checkout";
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
+
+export interface Install {
+  readonly kind: InstallKind;
+  readonly manager: PackageManager;
+  /** The directory the package is installed in: a project's root, the machine's global one, a cache's; the checkout itself. */
+  readonly root: string;
+}
+
+export interface InstallClues {
+  /** The package's own directory, where its manifest is. */
+  readonly packageDir: string;
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly exists: (path: string) => boolean;
+}
+
+const PACKAGE = "@skillcdn/console";
+
+const slashes = (path: string): string => path.replaceAll("\\", "/").replace(/\/+$/, "");
+
+/** The package manager that ran this command, when one did: `pnpm exec`, `npx` and their kind say so. */
+function managerRunning(env: InstallClues["env"]): PackageManager | undefined {
+  const agent = env.npm_config_user_agent ?? "";
+  for (const manager of ["pnpm", "yarn", "bun", "npm"] as const) {
+    if (agent.startsWith(`${manager}/`)) {
+      return manager;
+    }
+  }
+  return undefined;
+}
+
+export function detectInstall(clues: InstallClues): Install {
+  const dir = slashes(clues.packageDir);
+  const cwd = slashes(clues.cwd);
+  const at = dir.indexOf("/node_modules/");
+  if (at < 0) {
+    return { kind: "checkout", manager: "pnpm", root: dir };
+  }
+  const root = dir.slice(0, at);
+  const lower = dir.toLowerCase();
+  const running = managerRunning(clues.env);
+  // What `npx`, `pnpm dlx`, `yarn dlx` and `bunx` fetch into a cache lives only for the run.
+  if (/\/(_npx|dlx|dlx-[^/]*)\//.test(lower) || lower.includes("/.bun/install/cache/")) {
+    const manager =
+      running ??
+      (lower.includes("/_npx/") ? "npm" : lower.includes("/.bun/install/cache/") ? "bun" : "pnpm");
+    return { kind: "temporary", manager, root };
+  }
+  if (cwd === root || cwd.startsWith(`${root}/`)) {
+    const manager: PackageManager = clues.exists(`${root}/pnpm-lock.yaml`)
+      ? "pnpm"
+      : clues.exists(`${root}/yarn.lock`)
+        ? "yarn"
+        : clues.exists(`${root}/bun.lock`) || clues.exists(`${root}/bun.lockb`)
+          ? "bun"
+          : (running ?? "npm");
+    return { kind: "project", manager, root };
+  }
+  const manager: PackageManager = /\/pnpm\/global\/|\/\.pnpm-global\//.test(lower)
+    ? "pnpm"
+    : lower.includes("/yarn/global/")
+      ? "yarn"
+      : lower.includes("/.bun/install/global/")
+        ? "bun"
+        : "npm";
+  return { kind: "global", manager, root };
+}
+
+/** The command that puts the version named where this command is installed. */
+export function updateCommandFor(install: Install, version: string): string {
+  const spec = `${PACKAGE}@${version}`;
+  switch (install.kind) {
+    case "global":
+      return install.manager === "npm"
+        ? `npm install -g ${spec}`
+        : install.manager === "yarn"
+          ? `yarn global add ${spec}`
+          : `${install.manager} add -g ${spec}`;
+    case "project":
+      return `${install.manager === "npm" ? "npm install" : `${install.manager} add`} ${spec}`;
+    case "temporary":
+      return install.manager === "npm"
+        ? `npx ${spec}`
+        : install.manager === "bun"
+          ? `bunx ${spec}`
+          : `${install.manager} dlx ${spec}`;
+    case "checkout":
+      return "git pull && pnpm install && pnpm build";
+  }
+}
+
+/** Where the command is installed, in words: what `whoami` and `--version` say. */
+export function describeInstall(install: Install): string {
+  switch (install.kind) {
+    case "global":
+      return `installed for the machine with ${install.manager} in ${install.root}`;
+    case "project":
+      return `installed in the project at ${install.root} with ${install.manager}`;
+    case "temporary":
+      return `fetched for this run by ${install.manager}`;
+    case "checkout":
+      return `built from the checkout at ${install.root}`;
+  }
+}

package/src/cli/main.ts

@@ -5,21 +5,28 @@ import { hostname } from "node:os";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import * as z from "zod/mini";
+import { userAgentOf } from "../compat.js";
 import { runCli } from "./cli.js";
 import { createFileStore, defaultConfigDir } from "./credentials.js";
 import { createDirectoryStore } from "./directory.js";
+import { detectInstall } from "./install.js";
+import { createNoticeStore } from "./notices.js";
 import { listenOn } from "./serve.js";
 import { readBytesAt, readFileAt, readStdin, writeBytesAt } from "./terminal.js";
 
 // The `console` command: the only place the command reads the process. Everything it does is in
 // cli.ts, which takes what it needs and is what the tests run.
 
-/** The version of the package this file runs from: its own manifest, two levels above dist/cli. */
+/** The package's own directory, two levels above dist/cli: where its manifest and its skills are. */
+const packageDir = fileURLToPath(new URL("../../", import.meta.url));
+/** The version of the package this file runs from: its own manifest. */
 const manifest = z
   .object({ version: z.string() })
   .safeParse(createRequire(import.meta.url)("../../package.json"));
+const version = manifest.success ? manifest.data.version : undefined;
 /** 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));
+const configDir = defaultConfigDir(process.env);
 
 process.exitCode = await runCli(process.argv.slice(2), {
   env: process.env,
@@ -35,11 +42,24 @@ process.exitCode = await runCli(process.argv.slice(2), {
   readFile: readFileAt,
   readBytes: readBytesAt,
   writeBytes: writeBytesAt,
-  store: createFileStore(defaultConfigDir(process.env)),
+  store: createFileStore(configDir),
   directory: createDirectoryStore(process.cwd()),
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
   now: () => Date.now(),
-  version: manifest.success ? manifest.data.version : undefined,
+  version,
+  // The command names itself on every request, and where it runs, so that the console holds it
+  // to the versions it takes and the access log says which commands are about (ADR-0025).
+  userAgent:
+    version === undefined
+      ? undefined
+      : userAgentOf(version, `cli; node ${process.versions.node}; ${process.platform}`),
+  install: detectInstall({
+    packageDir,
+    cwd: process.cwd(),
+    env: process.env,
+    exists: existsSync,
+  }),
+  notices: createNoticeStore(configDir),
   skillsDir: existsSync(skillsDir) ? skillsDir : undefined,
   listen: listenOn,
 });

package/src/cli/notices.ts

@@ -0,0 +1,48 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import * as z from "zod/mini";
+
+// What the command last said about the versions, kept beside the credentials, so that it says
+// it once a day for one pair of versions and not on every command an agent runs. A notice is
+// not worth failing a command for: a file that cannot be read or written is as good as none.
+
+export interface VersionNotice {
+  /** The version of the command that noticed. */
+  readonly command: string;
+  /** The version of the console it noticed. */
+  readonly console: string;
+  readonly shownAt: string;
+}
+
+export interface NoticeStore {
+  load(): Promise<VersionNotice | undefined>;
+  save(notice: VersionNotice): Promise<void>;
+}
+
+const noticesSchema = z.object({
+  versions: z.optional(z.object({ command: z.string(), console: z.string(), shownAt: z.string() })),
+});
+
+const FILE_NAME = "notices.json";
+
+export function createNoticeStore(directory: string): NoticeStore {
+  const path = join(directory, FILE_NAME);
+  return {
+    async load() {
+      try {
+        const parsed = noticesSchema.safeParse(JSON.parse(await readFile(path, "utf8")));
+        return parsed.success ? parsed.data.versions : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    async save(notice) {
+      try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await writeFile(path, `${JSON.stringify({ versions: notice }, null, 2)}\n`);
+      } catch {
+        // Said this time; said again next time.
+      }
+    },
+  };
+}

package/src/client.ts

@@ -12,6 +12,7 @@ import {
 } from "./routes.js";
 import {
   type RestAnswerInput,
+  type RestArchivedTasks,
   type RestArtifactInput,
   type RestCategories,
   type RestCategory,
@@ -43,6 +44,7 @@ import {
   type RestMemberPatch,
   type RestMembers,
   type RestMePatch,
+  type RestPackTokenInput,
   type RestPeople,
   type RestPerson,
   type RestPersonPatch,
@@ -59,6 +61,8 @@ import {
   type RestRunEndInput,
   type RestRunInput,
   type RestRuns,
+  type RestSkillFile,
+  type RestSkillLoad,
   type RestSkills,
   type RestTask,
   type RestTaskInput,
@@ -70,6 +74,7 @@ import {
   type RestVersion,
   type RestVersions,
   type RestWork,
+  restArchivedTasksSchema,
   restCategoriesSchema,
   restCategorySchema,
   restClaimSchema,
@@ -98,6 +103,8 @@ import {
   restRulesSchema,
   restRunSchema,
   restRunsSchema,
+  restSkillFileSchema,
+  restSkillLoadSchema,
   restSkillsSchema,
   restTaskSchema,
   restTasksSchema,
@@ -107,7 +114,7 @@ import {
   restVersionsSchema,
   restWorkSchema,
 } from "./schemas.js";
-import type { TaskState } from "./vocabulary.js";
+import type { GoalState, TaskState } from "./vocabulary.js";
 
 // The client of the console's REST API: what the default console and a custom one talk to the
 // server with, and what the command line, a script or a console of a person's own talks to it
@@ -154,6 +161,12 @@ export interface ClientOptions {
    * the page's own origin is what the console answers to.
    */
   readonly token?: string;
+  /**
+   * What the client calls itself, sent as `user-agent` where the platform lets a client say
+   * (Node; a browser keeps its own): the command sends its product token, by which the console
+   * holds it to the versions it takes (ADR-0025).
+   */
+  readonly userAgent?: string;
 }
 
 export class ApiError extends Error {
@@ -189,6 +202,13 @@ export interface Page {
 }
 
 /** What the board is narrowed to: one state, the open ones, a category, a goal, an assignee, or what is due by a day. */
+/** What the roadmap is narrowed by: the goals in one state, or sorted into one category (ADR-0026). */
+export interface GoalFilter {
+  readonly state?: GoalState | undefined;
+  /** The key of a category of the workspace. */
+  readonly category?: string | undefined;
+}
+
 export interface TaskFilter extends Page {
   readonly state?: TaskState | undefined;
   /** True for the tasks not done or dropped; false for the rest. */
@@ -199,8 +219,12 @@ export interface TaskFilter extends Page {
   readonly goal?: string | undefined;
   /** The id of the person the tasks are assigned to. */
   readonly assignee?: string | undefined;
+  /** True for the tasks assigned to nobody. */
+  readonly unassigned?: boolean | undefined;
   /** A day (`2026-10-20`): the tasks due on it or before it. */
   readonly dueBy?: string | undefined;
+  /** True for the tasks put away alone (ADR-0029); false, or left out, for the current ones. */
+  readonly archived?: boolean | undefined;
 }
 
 /** What a folder's listing, or a search, of the documents is narrowed to. */
@@ -236,6 +260,11 @@ export interface ProjectClient {
   task(ref: string, signal?: AbortSignal): Promise<RestTask>;
   createTask(input: RestTaskInput): Promise<RestTask>;
   updateTask(id: string, patch: RestTaskPatch): Promise<RestTask>;
+  /** Puts a done or dropped task away (ADR-0029), or brings one back. */
+  archiveTask(id: string): Promise<RestTask>;
+  restoreTask(id: string): Promise<RestTask>;
+  /** Puts every done or dropped task of a goal away at once; for an owner. Answers how many. */
+  archiveTasksOfGoal(goalId: string): Promise<RestArchivedTasks>;
   /** The decisions, or only those that wait, or only those about one task; a page of them. */
   decisions(
     filter?: { readonly open?: boolean; readonly task?: string } & Page,
@@ -281,6 +310,18 @@ export interface ProjectClient {
   eventStreamUrl(after: number): string;
   /** The project's skills, as SkillCDN serves them at its address, or the organization's. */
   skills(signal?: AbortSignal): Promise<RestSkills>;
+  /** One skill of the pack, a page of it (`load_skill`), read by the console with the pack token the project holds (ADR-0028). */
+  skill(path: string, cursor?: string, signal?: AbortSignal): Promise<RestSkillLoad>;
+  /** A file of the pack, a page of it, or what a folder holds (`read_repo_file`). */
+  skillFile(
+    path: string,
+    page?: { readonly offset?: number | undefined; readonly limit?: number | undefined },
+    signal?: AbortSignal,
+  ): Promise<RestSkillFile>;
+  /** Sets the pack token the project reads a private pack with; for an owner. The token travels once and is answered never. */
+  setPackToken(input: RestPackTokenInput): Promise<RestProject>;
+  /** Takes the pack token away; for an owner. */
+  removePackToken(): Promise<RestProject>;
   /** The rules that hold in the project (ADR-0023): the workspace's, and what the project adds. */
   rules(signal?: AbortSignal): Promise<RestProjectRules>;
   /** A folder's pages and folders, or the pages a search finds. */
@@ -302,7 +343,8 @@ export interface ProjectClient {
   /** Where the bytes of a file attached to a document are read, by the file's id. */
   documentFileUrl(path: string, fileId: string): string;
   /** The roadmap (ADR-0019): the goals, the active first, each with its tasks counted by state. */
-  goals(signal?: AbortSignal): Promise<RestGoals>;
+  /** The roadmap, or what the filter keeps of it: the active goals first. */
+  goals(filter?: GoalFilter, signal?: AbortSignal): Promise<RestGoals>;
   goal(id: string, signal?: AbortSignal): Promise<RestGoal>;
   /** Sets a goal; for an owner, with a session or a token. */
   createGoal(input: RestGoalInput): Promise<RestGoal>;
@@ -381,7 +423,8 @@ const INVALID = "The server answered unexpectedly.";
 export function createClient(options: ClientOptions = {}): ConsoleClient {
   const base = (options.baseUrl ?? "").replace(/\/+$/, "");
   const send = options.fetch ?? ((input, init) => fetch(input, init));
-  const { token } = options;
+  const { token, userAgent } = options;
+  const named: Record<string, string> = userAgent === undefined ? {} : { "user-agent": userAgent };
 
   const withQuery = (path: string, params: Record<string, string | undefined>): string => {
     const query = new URLSearchParams();
@@ -423,6 +466,7 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
           // A form names its own type, boundary included; everything else is JSON.
           ...(body === undefined || form ? {} : { "content-type": "application/json" }),
           ...(token === undefined ? {} : { authorization: `Bearer ${token}` }),
+          ...named,
         },
         ...(body === undefined ? {} : { body: form ? body : JSON.stringify(body) }),
       });
@@ -457,7 +501,10 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
         method: "GET",
         ...(signal === undefined ? {} : { signal }),
         credentials: token === undefined ? "same-origin" : "omit",
-        headers: token === undefined ? {} : { authorization: `Bearer ${token}` },
+        headers: {
+          ...(token === undefined ? {} : { authorization: `Bearer ${token}` }),
+          ...named,
+        },
       });
     } catch (error) {
       if (signal?.aborted === true) {
@@ -534,10 +581,12 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
           "GET",
           withQuery(at("tasks"), {
             state: filter.state,
+            archived: flag(filter.archived),
             open: flag(filter.open),
             category: filter.category,
             goal: filter.goal,
             assignee: filter.assignee,
+            unassigned: flag(filter.unassigned),
             dueBy: filter.dueBy,
             limit: number(filter.limit),
             offset: number(filter.offset),
@@ -551,6 +600,12 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
       createTask: (input) => request("POST", `${base}${at("tasks")}`, input, restTaskSchema),
       updateTask: (id, patch) =>
         request("PATCH", `${base}${at("tasks", id)}`, patch, restTaskSchema),
+      archiveTask: (id) =>
+        request("POST", `${base}${at("tasks", id)}/archive`, undefined, restTaskSchema),
+      restoreTask: (id) =>
+        request("POST", `${base}${at("tasks", id)}/restore`, undefined, restTaskSchema),
+      archiveTasksOfGoal: (goalId) =>
+        request("POST", `${base}${at("tasks")}/archive`, { goalId }, restArchivedTasksSchema),
       decisions: (filter = {}, signal) =>
         request(
           "GET",
@@ -639,6 +694,30 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
       eventStreamUrl: (after) => withQuery(`${at("events")}/stream`, { after: String(after) }),
       skills: (signal) =>
         request("GET", `${base}${at("skills")}`, undefined, restSkillsSchema, signal),
+      skill: (path, cursor, signal) =>
+        request(
+          "GET",
+          withQuery(`${at("skills")}/one`, { path, cursor }),
+          undefined,
+          restSkillLoadSchema,
+          signal,
+        ),
+      skillFile: (path, page = {}, signal) =>
+        request(
+          "GET",
+          withQuery(`${at("skills")}/file`, {
+            path,
+            offset: page.offset === undefined ? undefined : String(page.offset),
+            limit: page.limit === undefined ? undefined : String(page.limit),
+          }),
+          undefined,
+          restSkillFileSchema,
+          signal,
+        ),
+      setPackToken: (input) =>
+        request("PUT", `${base}${at()}/pack-token`, input, restProjectSchema),
+      removePackToken: () =>
+        request("DELETE", `${base}${at()}/pack-token`, undefined, restProjectSchema),
       rules: (signal) =>
         request("GET", `${base}${at("rules")}`, undefined, restProjectRulesSchema, signal),
       documents: (filter = {}, signal) =>
@@ -681,8 +760,14 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
         request("POST", `${base}${at("docs", path)}/files`, formOf(input), restDocumentSchema),
       documentFileUrl: (path, fileId) =>
         `${base}${at("docs", path)}/files/${encodeURIComponent(fileId)}`,
-      goals: (signal) =>
-        request("GET", `${base}${at("goals")}`, undefined, restGoalsSchema, signal),
+      goals: (filter = {}, signal) =>
+        request(
+          "GET",
+          withQuery(at("goals"), { state: filter.state, category: filter.category }),
+          undefined,
+          restGoalsSchema,
+          signal,
+        ),
       goal: (id, signal) =>
         request("GET", `${base}${at("goals", id)}`, undefined, restGoalSchema, signal),
       createGoal: (input) => request("POST", `${base}${at("goals")}`, input, restGoalSchema),