@skillcdn/console 0.1.21 → 0.1.22

package/src/cli/help.ts

@@ -31,15 +31,21 @@ import {
 import { COLOR_NAMES } from "../vocabulary.js";
 
 // What the command says about itself: for an agent that meets it for the first time, and for a
-// person. One table for every command, from which the usage and each command's help are made:
-// the overview says what each command does, and a command's own help adds the limits the
-// console holds it to and the refusals it may meet, so that an agent learns them before it
-// runs into them.
+// person. One table for every command, from which two layers are made. The overview is a map:
+// every command in a line, what it does in a sentence, and what holds everywhere, short enough
+// to be read once at the start. A command's own help is the reference: every form and flag, what
+// each does, the limits the console holds it to and the refusals it may meet, read when the
+// command is about to be used. How the work goes is the skill working-the-board, and what the
+// organization asks is the rules of the board: neither is repeated here.
 
 export interface CommandHelp {
-  /** The command and its arguments, after `console`. */
+  /** The command and its arguments, after `console`, every form and flag. */
   readonly usage: string;
-  /** What it does, in a sentence. */
+  /** The usage as the overview shows it, for a command whose forms are many; `usage` has them all. */
+  readonly overview?: string;
+  /** What it does, in one line, for the overview. */
+  readonly synopsis: string;
+  /** What it does in full, for the command's own help. */
   readonly about: string;
   /** What the console holds the arguments to. */
   readonly limits?: readonly string[];
@@ -85,6 +91,8 @@ const TASK_FIELD_REFUSALS = [
 export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   login: {
     usage: "login --url <origin> [--agent <name>] [--token-stdin] [--default]",
+    synopsis:
+      "Connects this agent to the console with a code a person approves; keeps the token, never shows it.",
     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 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: [
@@ -94,42 +102,54 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   logins: {
     usage: "logins",
+    synopsis: "The consoles this machine is signed in to, and which is the default.",
     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 [--url <origin>] [--account <login>]",
+    synopsis: "Gives this agent's token up at one console and forgets it here.",
     about:
       "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",
+    synopsis: "Who the token acts as, at which console, and in which project this directory works.",
     about:
       "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",
+    synopsis: "The projects you may work in, with what you are in each.",
     about:
       "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> [--url <origin>] [--account <login>]",
+    synopsis: "Binds this directory to a project: writes .skillcdn-console.json here.",
     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 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: {
     usage: "work [--person <login>]",
+    synopsis:
+      "What is on your plate across your projects: your open tasks, and the decisions waiting.",
     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. --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:
       "tasks [--state <state>] [--open] [--mine] [--category <key>] [--goal <id>] [--due <day|today|week|overdue>] [--unassigned] [--archived] [--limit <n>] [--offset <n>]",
+    synopsis:
+      "The tasks on the board, newest first, narrowed by state, owner, category, goal or due day.",
     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}  |  task archive <number|id>  |  task archive --goal <id>  |  task restore <number|id>`,
+    overview:
+      "task <number|id>  |  task new <title> [flags]  |  task edit <number|id> [flags]  |  task archive <number|id>|--goal <id>  |  task restore <number|id>",
+    synopsis: "One task in full; or a task written, changed, put away or brought back.",
     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, 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 task away, whatever its state (ADR-0029, ADR-0030): 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: [
@@ -141,12 +161,16 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   goals: {
     usage: "goals [--category <key>] [--state <state>]",
+    synopsis: "The roadmap: the project's goals, with their state, their days and how far each is.",
     about:
       "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>] [--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>]',
+    overview: "goal <id>  |  goal new <title> [flags]  |  goal edit <id> [flags]",
+    synopsis:
+      "One goal with the tasks that work towards it; or a goal set or changed, for an owner.",
     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, 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: [
@@ -163,17 +187,21 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   categories: {
     usage: "categories",
+    synopsis: "The categories tasks are sorted into, by key.",
     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: console category, or the Categories page.",
   },
   people: {
     usage: "people",
+    synopsis: "Everyone of the workspace, by login, with what each is in it.",
     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; 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>  |  person add <login> [--host gh|google]  |  person remove <login>  |  person deactivate <login>  |  person reactivate <login>",
+    synopsis:
+      "Says what a person is in the workspace, lets a login in or takes one out; for an administrator.",
     about:
       "For an administrator: the person themselves on the People page, or their agent here, named on it. role says what a person is in the workspace; the board keeps at least one administrator in. add lets a login in: whoever signs in with that account at that host is a person from then on; the host is read off the login (an address is Google's, anything else GitHub's) unless --host says. remove takes a login away that nobody has signed in with yet. deactivate takes a person out: refused on every request at once, their agents with them, kept with everything they did, and listed nowhere; reactivate takes them back in. A person the organization let in comes and goes with it, and is neither.",
     refusals: [
@@ -187,6 +215,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 pack-token <key> --stdin  |  project pack-token <key> --remove',
+    overview:
+      "project <key>  |  project new <key> <name> [flags]  |  project edit <key> [flags]  |  project icon <key> <file>|--remove  |  project pack-token <key> --stdin|--remove",
+    synopsis: "One project in full; or a project made, changed, given its mark or its pack token.",
     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; 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: [
@@ -206,12 +237,15 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   members: {
     usage: "members",
+    synopsis: "Those listed in the project, with what each is in it.",
     about:
       "Those listed in the project, by login, with what each is in it (owner, who configures it; member, who works on it) and since when. A project open to the workspace has everyone of it as a member besides, and an administrator owns every project.",
   },
   member: {
     usage:
       "member add <login> [--role owner|member] [--project <key>[,<key>...]]  |  member role <login> <owner|member>  |  member remove <login>",
+    synopsis:
+      "Lists a person in the project, changes what they are in it, or takes them off; for an owner.",
     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. 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: [
@@ -224,6 +258,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   category: {
     usage:
       'category new <key> "<name>" [--color <name>]  |  category edit <key> [--name "<name>"] [--color <name>]  |  category remove <key>',
+    synopsis: "Makes, changes or removes a category; for an administrator.",
     about:
       "Makes a category tasks are sorted into, the same in every project; changes its name or its colour; or removes one no task is sorted into. For an administrator.",
     limits: [
@@ -240,14 +275,23 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     ],
   },
   skills: {
-    usage: "skills",
+    usage: "skills  |  skills <folder>  |  skills --search <words> [<folder>] [--limit <n>]",
+    synopsis:
+      "The project's pack: its skills; what a folder of it holds; or what words find in it.",
     about:
-      "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.",
+      "The project's pack, as SkillCDN serves it at the project's address, read by the console with the pack token the project holds where the pack is private (ADR-0028). Alone: the pack by name with how many skills and documents it has, and its skills, 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. With a folder (/ for the root): what it holds, as browse_repo lays it out: its skills, its folders with how many skills and documents each holds and the README that introduces it, its files; whole, page after page. With --search: the skills and the documents the words find, in relevance order, a skill with the files of it that matched; words, not meaning, in the language the pack is written in; within the folder when one is named; 10 unless --limit says otherwise, up to 25, and a last line says when more matched. --json answers with the console's own JSON, the page of each skill included.",
+    limits: ["search: 1 to 500 characters; limit: 1 to 25"],
+    refusals: [
+      "status not_found: the pack is not served to the console; private, with no pack token on the project",
+      "status token_invalid: the pack token the project holds no longer works; an owner sets a new one",
+    ],
   },
   skill: {
-    usage: "skill <path> [--file <path>]",
+    usage: "skill <path>  |  skill --file <path>",
+    synopsis:
+      "One skill of the pack whole, its rules first; or with --file a file of the pack, or what a folder holds.",
     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.",
+      "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, and takes no skill's path beside it; console skills <folder> shows a folder with more.",
     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",
@@ -257,8 +301,10 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   rules: {
     usage:
       "rules  |  rules write --body <markdown>|--file <path>|-|none [--workspace] [--base <version>]",
+    synopsis:
+      "What this organization and this project ask of agents; rules write writes them, for an owner or an administrator.",
     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.",
+      "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. 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`,
     ],
@@ -269,8 +315,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   take: {
     usage: "take <number|id> [--agent <name>]",
+    synopsis: "Takes a task: a run begins, and the task is in progress and the person's.",
     about:
-      "Takes a task: a run begins, and the task is in progress and the person's. A run still open on the task is taken over, since the board cannot know whether its agent still runs: it ends as abandoned, the feed says who took over, and that agent is refused on its next command. Look before taking (console task <number> lists the runs, with when each was last heard from), and take a task another agent was heard from on lately only when told to. --agent is what people see at work; left out, it is what the person called the token.",
+      "Takes a task: a run begins, and the task is in progress and the person's; the rules of the board are printed with the task. A run still open on the task is taken over, since the board cannot know whether its agent still runs: it ends as abandoned, the feed says who took over, and that agent is refused on its next command; console task <number> shows the runs on a task, with when each was last heard from, before it is taken. --agent is what people see at work; left out, it is what the person called the token.",
     limits: [`agent: one line, up to ${MAX_AGENT_LENGTH} characters`],
     refusals: [
       "task.not_found: no task has that number or id",
@@ -279,8 +326,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   report: {
     usage: "report <markdown>  |  report --file <path>  |  report -",
+    synopsis: "Says how the work goes, in Markdown, on the open run.",
     about:
-      "Says how the work goes, in Markdown: what was found, what was done, what is next. A milestone at a time, not every step. With - the report is read from standard input.",
+      "Says how the work goes, in Markdown: what was found, what was done, what is next. With - the report is read from standard input.",
     limits: [
       `the report: ${MARKDOWN}, not blank`,
       `at most ${MAX_REPORTS_PER_RUN} reports on one run`,
@@ -289,6 +337,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   "hand-in": {
     usage: "hand-in <https url | file path> [--label <words>]",
+    synopsis: "Hands in what was made: an https link, or a file from this machine.",
     about:
       "Hands in what was made: a link (a branch, a pull request, a document, a page), or a file from this machine, which the console keeps and shows on the task; a picture is shown there small and large, and a report that names it as ![words](its name) shows it where the words are.",
     limits: [
@@ -306,8 +355,10 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   ask: {
     usage:
       'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--wait <seconds>]',
+    synopsis:
+      "Raises a decision a person must make, with options, and waits a while for the answer.",
     about:
-      "Raises a decision a person must make: the question, the options to choose from, and what they need to know. The run waits for the answer. The command waits 60 seconds for it unless --wait says otherwise, and exits with 3 if it is still to come: keep waiting with `console decision <id> --wait 100`, within what your shell gives one command, and go on meanwhile only with work that does not depend on the answer. The decision's id is printed as soon as it is raised.",
+      "Raises a decision a person must make: the question, the options to choose from, and what they need to know. The run waits for the answer. The command waits 60 seconds for it unless --wait says otherwise, and exits with 3 if it is still to come: keep waiting with `console decision <id> --wait 100`, within what your shell gives one command. The decision's id is printed as soon as it is raised.",
     limits: [
       `question: one line, up to ${MAX_QUESTION_LENGTH} characters`,
       `options: ${MIN_OPTIONS} to ${MAX_OPTIONS}, each one line up to ${MAX_OPTION_LABEL_LENGTH} characters`,
@@ -317,6 +368,8 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   decision: {
     usage: "decision <id> [--wait <seconds>]  |  decision <id> --outcome <markdown>|--file <path>",
+    synopsis:
+      "One decision in full; waits for its answer with --wait; writes what followed with --outcome.",
     about:
       "One decision, with its context, its options, its answer and what followed. With --wait, holds on for the answer that long, and exits with 3 if it is still to come. With --outcome, writes down what followed the decision, so that it reads as a record.",
     limits: [`outcome: ${MARKDOWN}`],
@@ -324,10 +377,12 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   decisions: {
     usage: "decisions [--open] [--limit <n>] [--offset <n>]",
+    synopsis: "The decisions on the board, the waiting first.",
     about: `The decisions on the board, the waiting first; --open keeps only those. A page at a time: ${DEFAULT_PAGE_LIMIT} unless --limit says otherwise, from --offset on.`,
   },
   finish: {
     usage: 'finish [--summary "<markdown>"|--file <path>]',
+    synopsis: "Ends the run: done and handed in; the task goes up for review.",
     about:
       "Ends the run: the work is done and handed in, and the task goes up for review. The summary says what was done and what is left; the result itself goes in a last report before, which may be much longer.",
     limits: [`summary: ${`Markdown, up to ${MAX_SUMMARY_LENGTH} characters`}`],
@@ -335,12 +390,14 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   fail: {
     usage: 'fail [--summary "<markdown>"|--file <path>]',
+    synopsis: "Ends the run: the work could not be done.",
     about: "Ends the run: the work could not be done. The summary says why, and what is left.",
     limits: [`summary: Markdown, up to ${MAX_SUMMARY_LENGTH} characters`],
     refusals: RUN_REFUSALS,
   },
   abandon: {
     usage: 'abandon [<run id>] [--summary "<markdown>"]',
+    synopsis: "Leaves a run; the task stays as it is.",
     about:
       "Leaves a run; the task stays as it is. A person gives up this way on a run of theirs that will not come back.",
     limits: [`summary: Markdown, up to ${MAX_SUMMARY_LENGTH} characters`],
@@ -348,16 +405,19 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   runs: {
     usage: "runs [--task <number|id>] [--open] [--mine] [--limit <n>] [--offset <n>]",
+    synopsis: "The runs, newest first, each with when its agent was last heard from.",
     about: `The runs, newest first, each with when its agent was last heard from: --open keeps the ones not over, --mine those begun with this token. A page at a time: ${DEFAULT_PAGE_LIMIT} unless --limit says otherwise, from --offset on.`,
   },
   run: {
     usage: "run <id>",
+    synopsis: "One run in full: its reports, what it handed in, how it ended.",
     about: "One run in full: its reports, what it handed in, what it waits for, how it ended.",
     refusals: ["run.not_found: no run has that id"],
   },
   comment: {
     usage:
       'comment <number|id> "<markdown>" [--attach <path>]...  |  comment <number|id> --file <path>  |  comment <number|id> -',
+    synopsis: "Says something in the discussion on a task, with files; needs no run.",
     about:
       "Says something in the discussion on a task, for its people: an answer to what they asked there, a question that is not a decision, a remark; with files from this machine put in it, which the console keeps and shows on the task, pictures in place. Needs no run. A report is the run's record; a comment is a word to people. Never rewritten: a mistake is corrected in the next one.",
     limits: [
@@ -375,23 +435,27 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   file: {
     usage: "file <id> [--out <path>]",
+    synopsis: "Reads a file of the project to this machine, by its id.",
     about:
       "Reads a file of the project from the console and writes it on this machine: one a run handed in, one put in a comment, or one attached to a page, by the id the task, the run or the page shows. Written under its own name in the working directory, at --out <path>, or into --out <directory>. Then look at it with your own tools.",
     refusals: ["file.not_found: no file of this project has that id"],
   },
   docs: {
     usage: "docs [<folder>] [--search <words>] [--archived]",
+    synopsis: "The pages of the project's documents: a folder, or those found by words.",
     about:
       "The pages of the project's documents: those in a folder, with the folders in it (the root when none is named), or those found by words in their title or body. Archived pages are left out unless --archived.",
   },
   doc: {
     usage: "doc <path> [--version <n>|--versions]",
+    synopsis: "One page in full, or one of its versions.",
     about:
       "One page in full: its title, its body in Markdown, what it links to, what refers to it (pages, tasks, decisions), and its files. --versions lists its versions, who wrote each and when; --version <n> prints one as it was.",
     refusals: [...DOCUMENT_REFUSALS, "document.version_not_found: the page has no such version"],
   },
   write: {
     usage: 'write <path> [--title "<title>"] --body <markdown>|--file <path> [--base <version>]',
+    synopsis: "Writes a page: a new one at a path, or a new version of the page there.",
     about:
       "Writes a page: the first version at a new path, or a new version of the page there. A link in the body whose destination is a page's path (guides/onboarding) refers to that page, and the page says what refers to it. Without --title the page keeps its title. With --base, the write is refused if the page has moved on since that version.",
     limits: [
@@ -409,6 +473,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   attach: {
     usage: "attach <path> <file> [--label <words>]",
+    synopsis: "Attaches a file from this machine to a page.",
     about:
       "Attaches a file from this machine to a page: the console keeps it, and the page lists it; a picture is shown where the body names it as ![words](its name).",
     limits: [
@@ -424,17 +489,21 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   archive: {
     usage: "archive <path>",
+    synopsis: "Puts a page away; nothing is deleted.",
     about:
       "Puts a page away: out of the folders and the search, still readable at its path, not written to until restored. Nothing is deleted.",
     refusals: DOCUMENT_REFUSALS,
   },
   restore: {
     usage: "restore <path>",
+    synopsis: "Brings an archived page back.",
     about: "Brings an archived page back.",
     refusals: DOCUMENT_REFUSALS,
   },
   serve: {
     usage: "serve [<dir>] [--port <n>]",
+    synopsis:
+      "For a person: serves a console of your own from this machine, its /api/ carried to the console with your token.",
     about:
       "For a person: serves a console of your own from this machine, for you. The build in <dir> (its index.html and files) is served at http://127.0.0.1:11197/, and everything under /api/ is carried to the console you are signed in to with your token, which the pages never see. Without a directory only the API is served there, for a development server to send its /api/ requests to. The loopback only; a request from another site's page is refused. Stop it with Ctrl+C.",
     refusals: ["not a build to serve: the directory holds no index.html"],
@@ -450,6 +519,8 @@ How the board is worked is the skill working-the-board, installed with this comm
 where it is; read it before the first command of a run.
 
 Usage: console <command> [arguments] [--json] [--url <origin>] [--project <key>]
+A command in full, every form and flag ([flags] below), the limits the console holds it to and what
+it may refuse: console help <command>. Read a command there when you are about to use it.
 `;
 
 const CLOSING = `Options everywhere: --json answers with the console's own JSON; --url names another console;
@@ -458,8 +529,7 @@ A listing (tasks, decisions, runs) is a page at a time: --limit <n> and --offset
 says when there is more, so that nothing is read that is not needed.
 Commands on a run (report, hand-in, ask, finish, fail) act on your one open run in the project;
 with several open, say which with --run <id>. A Markdown body given as - is read from standard input.
-console help <command> says what each command takes, the limits the console holds it to, and
-what it may refuse. console --version says which version of the command this is.
+console --version says which version of the command this is.
 
 Exit codes: 0 done; 1 the console refused, or could not be reached (the reason is on stderr);
 2 the command was not understood; 3 the decision still waits for a person.
@@ -512,7 +582,7 @@ const SECTIONS: readonly { readonly title: string; readonly commands: readonly s
   },
 ];
 
-/** The whole usage, as `console help` prints it, naming the version when it is known. */
+/** The overview, as `console help` prints it: every command in a line, naming the version when it is known. */
 export function usage(version?: string): string {
   const parts = [preamble(version)];
   for (const section of SECTIONS) {
@@ -520,7 +590,7 @@ export function usage(version?: string): string {
     for (const name of section.commands) {
       const help = COMMAND_HELP[name];
       if (help !== undefined) {
-        parts.push(`  console ${help.usage}\n      ${help.about}`);
+        parts.push(`  console ${help.overview ?? help.usage}\n      ${help.synopsis}`);
       }
     }
     parts.push("");
@@ -529,7 +599,7 @@ export function usage(version?: string): string {
   return parts.join("\n");
 }
 
-/** What `console help <command>` prints, or nothing for a command that is not one. */
+/** What `console help <command>` prints, the command in full; or nothing for a command that is not one. */
 export function helpFor(name: string): string | undefined {
   const help = COMMAND_HELP[name];
   if (help === undefined) {

package/src/client.ts

@@ -61,7 +61,9 @@ import {
   type RestRunEndInput,
   type RestRunInput,
   type RestRuns,
+  type RestSkillBrowse,
   type RestSkillFile,
+  type RestSkillFind,
   type RestSkillLoad,
   type RestSkills,
   type RestTask,
@@ -103,7 +105,9 @@ import {
   restRulesSchema,
   restRunSchema,
   restRunsSchema,
+  restSkillBrowseSchema,
   restSkillFileSchema,
+  restSkillFindSchema,
   restSkillLoadSchema,
   restSkillsSchema,
   restTaskSchema,
@@ -318,6 +322,25 @@ export interface ProjectClient {
     page?: { readonly offset?: number | undefined; readonly limit?: number | undefined },
     signal?: AbortSignal,
   ): Promise<RestSkillFile>;
+  /** What a folder of the pack holds, a page of it (`browse_repo`): the mounted folder when `path` is left out. */
+  skillBrowse(
+    page?: {
+      readonly path?: string | undefined;
+      readonly cursor?: string | undefined;
+      readonly limit?: number | undefined;
+    },
+    signal?: AbortSignal,
+  ): Promise<RestSkillBrowse>;
+  /** The skills and the documents of the pack that words find, a page of them in relevance order (`search_repo`), within `path` when given. */
+  skillFind(
+    query: string,
+    options?: {
+      readonly path?: string | undefined;
+      readonly cursor?: string | undefined;
+      readonly limit?: number | undefined;
+    },
+    signal?: AbortSignal,
+  ): Promise<RestSkillFind>;
   /** 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. */
@@ -714,6 +737,31 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
           restSkillFileSchema,
           signal,
         ),
+      skillBrowse: (page = {}, signal) =>
+        request(
+          "GET",
+          withQuery(`${at("skills")}/browse`, {
+            path: page.path,
+            cursor: page.cursor,
+            limit: page.limit === undefined ? undefined : String(page.limit),
+          }),
+          undefined,
+          restSkillBrowseSchema,
+          signal,
+        ),
+      skillFind: (query, options = {}, signal) =>
+        request(
+          "GET",
+          withQuery(`${at("skills")}/find`, {
+            query,
+            path: options.path,
+            cursor: options.cursor,
+            limit: options.limit === undefined ? undefined : String(options.limit),
+          }),
+          undefined,
+          restSkillFindSchema,
+          signal,
+        ),
       setPackToken: (input) =>
         request("PUT", `${base}${at()}/pack-token`, input, restProjectSchema),
       removePackToken: () =>

package/src/rules.ts

@@ -29,7 +29,7 @@ export const REFERENCE_RULES = [
   "",
   "## The organization's skills",
   "",
-  "`console skills` lists the skills of this project's pack: each with its name, what it does, and the path of its SKILL.md. `console skill <path>` reads one whole, its rules first, as the console reads it from the SkillCDN deployment for you, a private pack with the pack token the project holds; `console skill <path> --file <file>` reads a file of the pack. Where your host lists skills through a connection of your own to the address, the URI `skill://gh/<owner>/<repo>/<path>` is the skill there, followed until its context is complete. Either way, never fetch a skill another way. Load the skill the task names before anything is made; with none named, the one whose description fits the work. The rules those skills share arrive with each of them, from their repository's SKILLCDN.md, and hold within that work. What you read of a private pack is the project's: it stays in your work, and is not copied into a report, a page or a comment beyond what the work needs.",
+  "`console skills` lists the skills of this project's pack: each with its name, what it does, and the path of its SKILL.md; `console skills <folder>` shows what a folder of the pack holds, and `console skills --search <words>` finds its skills and documents by words. `console skill <path>` reads one whole, its rules first, as the console reads it from the SkillCDN deployment for you, a private pack with the pack token the project holds; `console skill --file <file>` reads a file of the pack. Where your host lists skills through a connection of your own to the address, the URI `skill://gh/<owner>/<repo>/<path>` is the skill there, followed until its context is complete. Either way, never fetch a skill another way. Load the skill the task names before anything is made; with none named, the one whose description fits the work. The rules those skills share arrive with each of them, from their repository's SKILLCDN.md, and hold within that work. What you read of a private pack is the project's: it stays in your work, and is not copied into a report, a page or a comment beyond what the work needs.",
   "",
   "## Where the work lives",
   "",

package/src/schemas.ts

@@ -915,6 +915,16 @@ export const restSkillsSchema = z.object({
   /** Where a person browses the address, or `null` without one. */
   page: z.nullable(z.string()),
   status: z.enum(SKILLS_STATUSES),
+  /** The pack as its manifest or its README names it, when `ready`: what it is called, what it is for, the language it is written in. */
+  pack: z.optional(
+    z.object({
+      name: z.nullable(z.string()),
+      description: z.nullable(z.string()),
+      language: z.nullable(z.string()),
+    }),
+  ),
+  /** How many skills and documents the deployment indexed at the address, when `ready`. */
+  counts: z.optional(z.object({ skills: count, documents: count })),
   /** The skills, when `ready`; empty otherwise. */
   items: z.array(restSkillSchema),
 });
@@ -1006,6 +1016,106 @@ export const restSkillFileSchema = z.object({
 });
 export type RestSkillFile = z.infer<typeof restSkillFileSchema>;
 
+/** An entry of a folder of the pack, as the deployment browses it: a skill, a folder with what it holds, or a file. */
+export const restSkillBrowseEntrySchema = z.object({
+  kind: z.enum(["skill", "directory", "file"]),
+  /** The path from the repository's root: of the `SKILL.md` for a skill, of the folder, of the file. */
+  path: z.string(),
+  name: z.nullable(z.string()),
+  description: z.nullable(z.string()),
+  /** For a folder: the skills and the documents under it. */
+  skillCount: count,
+  documentCount: count,
+  /** For a file: its size in bytes. */
+  size: z.nullable(count),
+  /** For a folder: the README that introduces it, read with the file route. */
+  overviewPath: z.nullable(z.string()),
+  /** For a skill: its license, and whether the address only describes it. */
+  license: z.nullable(z.string()),
+  describedOnly: z.boolean(),
+});
+export type RestSkillBrowseEntry = z.infer<typeof restSkillBrowseEntrySchema>;
+
+/** `GET .../skills/browse?path=&cursor=&limit=`: what a folder of the pack holds, a page of it (`browse_repo`); `folder` is `null` unless `ready`. */
+export const restSkillBrowseSchema = z.object({
+  address: z.nullable(z.string()),
+  source: z.string(),
+  page: z.nullable(z.string()),
+  status: z.enum(SKILLS_STATUSES),
+  folder: z.nullable(
+    z.object({
+      path: z.string(),
+      /** The README that introduces the folder, or `null`. */
+      overview: z.nullable(
+        z.object({
+          path: z.string(),
+          title: z.nullable(z.string()),
+          description: z.nullable(z.string()),
+        }),
+      ),
+      entries: z.array(restSkillBrowseEntrySchema),
+      /** Where the listing goes on, or `null` at its end. */
+      nextCursor: z.nullable(z.string()),
+    }),
+  ),
+});
+export type RestSkillBrowse = z.infer<typeof restSkillBrowseSchema>;
+
+/** What a search of the pack found: a skill, as the listing has it, with the files of it that matched; or a document on its own. */
+export const restSkillFindItemSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("skill"),
+    name: z.string(),
+    description: z.string(),
+    directory: z.string(),
+    path: z.string(),
+    page: z.string(),
+    uri: z.nullable(z.string()),
+    translations: z.record(
+      z.string(),
+      z.object({ title: z.nullable(z.string()), description: z.nullable(z.string()) }),
+    ),
+    /** The files of the skill that matched, a few, and how many more did. */
+    files: z.array(
+      z.object({
+        path: z.string(),
+        title: z.nullable(z.string()),
+        summary: z.nullable(z.string()),
+      }),
+    ),
+    moreFiles: count,
+    license: z.nullable(z.string()),
+    describedOnly: z.boolean(),
+  }),
+  z.object({
+    kind: z.literal("document"),
+    path: z.string(),
+    title: z.nullable(z.string()),
+    summary: z.nullable(z.string()),
+    /** The folder of the skill the document belongs to, or `null` for one on its own. */
+    skillDirectory: z.nullable(z.string()),
+  }),
+]);
+export type RestSkillFindItem = z.infer<typeof restSkillFindItemSchema>;
+
+/** `GET .../skills/find?query=&path=&cursor=&limit=`: what words find in the pack, a page of it in relevance order (`search_repo`); `found` is `null` unless `ready`. */
+export const restSkillFindSchema = z.object({
+  address: z.nullable(z.string()),
+  source: z.string(),
+  page: z.nullable(z.string()),
+  status: z.enum(SKILLS_STATUSES),
+  found: z.nullable(
+    z.object({
+      query: z.string(),
+      /** The folder the search was kept to, or `null` for the whole pack. */
+      path: z.nullable(z.string()),
+      items: z.array(restSkillFindItemSchema),
+      nextCursor: z.nullable(z.string()),
+    }),
+  ),
+});
+export type RestSkillFind = z.infer<typeof restSkillFindSchema>;
+
 /**
  * A document's path (ADR-0009): segments of lowercase letters, digits and hyphens, separated
  * by slashes, as a repository keeps files; the document's address, which does not change.