@skillcdn/console 0.1.21 → 0.1.22

package/docs/specs/cli.md

@@ -52,8 +52,8 @@ The board is a project's ([ADR-0008](../adr/0008-a-workspace-holds-projects-and-
 | `members` | `GET .../members` | one line per member: login, role, since when |
 | `member add <login> [--role owner\|member] [--project <key>[,<key>...]]`, `member role <login> <owner\|member>`, `member remove <login>` | `GET /api/v1/people` for the id, then `POST .../members` (once per project when `--project` names several with commas), `PATCH .../members/<id>`, `DELETE .../members/<id>` | the member as they are now, or that they are no longer listed; with several projects, one line per project, a person listed already said so; for an owner |
 | `category new <key> <name> [--color <name>]`, `category edit <key> [--name <name>] [--color <name>]`, `category remove <key>` | `POST /api/v1/categories`, `PATCH .../categories/<key>`, `DELETE .../categories/<key>` | the category as it is now, or that it is gone; for an administrator |
-| `skills` | `GET .../skills` | the project's pack, or the organization's: each skill with its description, the path `skill` reads it by and the URI an agent loads it by through its own SkillCDN connection; or why there are none to show; 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 |
-| `skill <path> [--file <path>]` | `GET .../skills/one?path=&cursor=`, page after page until `complete`; with `--file`, `GET .../skills/file?path=&offset=` until the end | the skill whole, as `load_skill` lays it out: the rules of the repository from its root to the nearest manifest, the body and the included files, each under a line that names its path, then the files it has and what it refers to; or the file whole, or what a folder holds; a private pack through the pack token the project holds ([ADR-0028](../adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md)) |
+| `skills`, `skills <folder>`, `skills --search <words> [<folder>] [--limit <n>]` | `GET .../skills`; `GET .../skills/browse?path=&cursor=`, page after page to the end; `GET .../skills/find?query=&path=&limit=`, one page | the project's pack, or the organization's: the pack by name with how many skills and documents it has, and each skill with its description, the path `skill` reads it by and the URI an agent loads it by through its own SkillCDN connection; or why there are none to show; 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. With a folder (`/` for the root), what it holds as `browse_repo` lays it out: its skills, its folders with what each holds and the README that introduces it, its files. With `--search`, what the words find as `search_repo` does, in relevance order, a skill with the files of it that matched, within the folder when one is named, ten unless `--limit` says otherwise (up to 25), and a last line when more matched |
+| `skill <path>`, `skill --file <path>` | `GET .../skills/one?path=&cursor=`, page after page until `complete`; with `--file`, `GET .../skills/file?path=&offset=` until the end | the skill whole, as `load_skill` lays it out: the rules of the repository from its root to the nearest manifest, the body and the included files, each under a line that names its path, then the files it has and what it refers to; or the file whole, or what a folder holds; a private pack through the pack token the project holds ([ADR-0028](../adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md)). `--file` takes no skill's path beside it: the two given together are not understood |
 | `rules` | `GET .../rules`, or `GET /api/v1/rules` without a project named, and `GET /api/v1/me` | the rules that hold, as they read for the person (`{language}` is the language they chose, or the task's) ([ADR-0023](../adr/0023-the-rules-of-a-board-are-pages-the-workspace-and-its-projects-keep-read-first-by-every-agent.md)): the workspace's, the console's own until an administrator writes the organization's, with its version and who wrote it when written; then this project's own, or that it adds none |
 | `rules write --body <markdown>\|--file <path>\|-\|none [--workspace] [--base <version>]` | `PUT .../docs/rules` or `POST .../docs/rules/archive`; with `--workspace`, `PUT /api/v1/rules` or `POST /api/v1/rules/archive` | the version written, that the console's own rules sent as they are wrote nothing, or that the rules are put away; for an owner of the project, or an administrator for the workspace's |
 | `take <number\|id> [--agent <name>]` | `GET .../tasks/<ref>`, then `POST .../runs`, then `GET .../rules`, `GET /api/v1/me`, `GET .../tasks/<ref>` again and `GET .../tasks/<id>/comments` | the run that began, the task in full as it stands taken with the discussion on it, the rules that hold as they read for the person, and what to do next; a run open on the task is taken over, and that is said when it happened ([ADR-0020](../adr/0020-the-console-does-not-claim-an-agent-is-at-work-a-run-says-when-it-was-last-heard-from-and-a-new-run-takes-over.md)) |
@@ -116,7 +116,7 @@ Plain text on standard output: one line per thing in a list, a few lines for one
 
 ## What an agent is told
 
-`console help` says what the board is, that the agent acts as the person whose token it holds and that everything it sends is shown to people as text, which project the commands work in and how it is named, what each command does (take a task, report at the milestones of the work, hand in what was made, say something in the discussion on a task and read what people put in it, ask when a person must decide, finish when done, write and read the project's pages, set up a project, its members and the categories when told to), and the refusals any command may meet. `console help <command>` adds what the command takes, the limits the console holds it to (how long a report, a summary, a question or an option may be; how many options, reports and links) and the refusals it may meet, by code, so that an agent learns them before it runs into them. The skill `working-the-board` ([skills/working-the-board/SKILL.md](../../skills/working-the-board/SKILL.md), [ADR-0015](../adr/0015-the-consoles-skills-live-in-this-repository-in-the-skillcdn-format-and-the-package-carries-them.md)) says how the work goes: reading, taking, reporting at the milestones, asking and waiting, handing in, writing down, finishing. The rules of the board say what the organization and the project ask of agents ([ADR-0023](../adr/0023-the-rules-of-a-board-are-pages-the-workspace-and-its-projects-keep-read-first-by-every-agent.md)): which tasks to take, which skills to load first, what to report, when to ask; `take` prints them with the task, so that they are read once, there, and `console rules` reads them any time, as when a task is still to be chosen.
+The command's help has two layers. `console help` is the map, read once at the start: what the board is, that the agent acts as the person whose token it holds and that everything it sends is shown to people as text, which project the commands work in and how it is named; then every command in a line, by section (signing in, the board, working, the documents, configuring), each with what it does in a sentence, a many-formed command (`task`, `goal`, `project`) listing its forms without their flags; then what holds everywhere, the exit codes and the refusals any command may meet. `console help <command>` is the reference, read when the command is about to be used: the command in full, every form and flag, what each does, the limits the console holds it to (how long a report, a summary, a question or an option may be; how many options, reports and links) and the refusals it may meet, by code, so that an agent learns them before it runs into them. The help says what the command does; how the work goes and what the organization asks are the skill's and the rules', and are not repeated in it. The skill `working-the-board` ([skills/working-the-board/SKILL.md](../../skills/working-the-board/SKILL.md), [ADR-0015](../adr/0015-the-consoles-skills-live-in-this-repository-in-the-skillcdn-format-and-the-package-carries-them.md)) says how the work goes: reading, taking, reporting at the milestones, asking and waiting, handing in, writing down, finishing. The rules of the board say what the organization and the project ask of agents ([ADR-0023](../adr/0023-the-rules-of-a-board-are-pages-the-workspace-and-its-projects-keep-read-first-by-every-agent.md)): which tasks to take, which skills to load first, what to report, when to ask; `take` prints them with the task, so that they are read once, there, and `console rules` reads them any time, as when a task is still to be chosen.
 
 ## Running an agent on a task
 

package/docs/specs/rest.md

@@ -245,7 +245,7 @@ Takes `status` (`finished`, `failed` or `abandoned`) and optionally a `summary`
 
 ### `GET /api/v1/projects/<key>/skills`
 
-The project's pack, as the SkillCDN deployment serves it at the project's address, or at the organization's (`SKILLS_ADDRESS`) when the project names none, read through `SKILLCDN_URL` ([ADR-0028](../adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md)): `{ "address", "source", "page", "status", "items" }`. `address` is canonical, or `null` with `status: "none"` when neither names one; `source` is the deployment's origin and `page` where a person browses the address. `status` is `ready`, or why `items` is empty: `indexing` and `failed` as the deployment says of the repository, `not_found` when it does not serve the address to the console (a private pack is read with the project's pack token; without one the console asks as nobody, so a private repository is not read), `token_invalid` when the deployment refuses the pack token the project holds (expired, removed, or its maker lost the repository), `unavailable` when it could not be reached or read. An item is one skill: `name`, `description`, `directory` and `path` (of its `SKILL.md`, from the repository's root, which the routes below take), `page` (the skill at the deployment, for a person), `uri` (what an agent loads it by through its own SkillCDN connection, `skill://gh/<owner>/<repo>/<path>`, or `null`), and `translations` (the title and the description by language tag, as the repository gives them). The console keeps nothing of the skills: a public answer per address stands for a minute, then the deployment is asked again; what is read with a pack token is asked every time, and held for nobody.
+The project's pack, as the SkillCDN deployment serves it at the project's address, or at the organization's (`SKILLS_ADDRESS`) when the project names none, read through `SKILLCDN_URL` ([ADR-0028](../adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md)): `{ "address", "source", "page", "status", "items" }`. `address` is canonical, or `null` with `status: "none"` when neither names one; `source` is the deployment's origin and `page` where a person browses the address. When `ready`, `pack` names the pack as its manifest does, else its README, else the host (`name`, `description` and `language`, each or `null`), and `counts` says how many `skills` and `documents` the deployment indexed at the address; neither is there otherwise. `status` is `ready`, or why `items` is empty: `indexing` and `failed` as the deployment says of the repository, `not_found` when it does not serve the address to the console (a private pack is read with the project's pack token; without one the console asks as nobody, so a private repository is not read), `token_invalid` when the deployment refuses the pack token the project holds (expired, removed, or its maker lost the repository), `unavailable` when it could not be reached or read. An item is one skill: `name`, `description`, `directory` and `path` (of its `SKILL.md`, from the repository's root, which the routes below take), `page` (the skill at the deployment, for a person), `uri` (what an agent loads it by through its own SkillCDN connection, `skill://gh/<owner>/<repo>/<path>`, or `null`), and `translations` (the title and the description by language tag, as the repository gives them). The console keeps nothing of the skills: a public answer per address stands for a minute, then the deployment is asked again; what is read with a pack token is asked every time, and held for nobody.
 
 ### `GET /api/v1/projects/<key>/skills/one?path=&cursor=` and `GET .../skills/file?path=&offset=&limit=`
 
@@ -253,6 +253,12 @@ One skill of the pack, and a file of it, read by the console from the deployment
 
 `skills/one` is the deployment's `load_skill`, in the console's shape: `{ "address", "source", "page", "status", "skill" }`, `skill` being `null` unless `status` is `ready`, else `path`, `directory`, `name`, `description`, `rules` (the manifests that hold for the skill, from the repository's root to the nearest, each `path`, `body` and `truncated`), `body`, `included` (the files the skill includes, the same way), `files` (the paths of the skill's own files), `references` (each `path` and `status`: `available`, `blocked`, `missing` or `outside_mount`), `complete` and `nextCursor` (a page may end inside a rule or a file; the next page continues it, and the skill is whole only when `complete`), `serving` (`full`, whether the skill is served whole or described only under its license; `license`; `sourceUrl`, where it is read at its host) and `warnings`. `skills/file` is `read_repo_file`: `{ "address", "source", "status", "file", "folder" }`, `file` being the page (`path`, `content`, `offset`, `nextOffset` or `null` at the end, `totalLength`, in characters; `limit` 1 to 100,000) or `folder` what a folder holds (`path`, `entries` of `path`, `kind` and `size`, `truncated`), both `null` unless `ready`; `failed` here is a file the deployment will not carry, too large or not text.
 
+### `GET /api/v1/projects/<key>/skills/browse?path=&cursor=&limit=` and `GET .../skills/find?query=&path=&cursor=&limit=`
+
+What a folder of the pack holds, and what words find in it, read the same way: the deployment's `browse_repo` and `search_repo` in the console's shape, for whoever may see the project, with the pack token where the project holds one ([ADR-0028](../adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md)); each read is logged with who read which folder, never with the words searched for. `path` is a folder's path from the repository's root, up to 500 characters, the mounted folder when left out; `cursor` continues one listing; a query out of bounds is `request.invalid`.
+
+`skills/browse` answers `{ "address", "source", "page", "status", "folder" }`, `folder` being `null` unless `ready`, else the folder's `path`, its `overview` (the README that introduces it: `path`, `title` and `description`, or `null`), its `entries`, each with `kind` (`skill`, `directory` or `file`), `path` (of the `SKILL.md` for a skill), `name` and `description` (or `null`), `skillCount` and `documentCount` (what a folder holds), `size` (a file's, in bytes, or `null`), `overviewPath` (a folder's README, or `null`), `license` and `describedOnly` (a skill's: whether the address only describes it under its license), and `nextCursor` (or `null` at the end; `limit` 1 to 200, 50 unless given). `skills/find` answers `{ "address", "source", "page", "status", "found" }`, `found` being `null` unless `ready`, else the `query` (1 to 500 characters, required), the `path` the search was kept to (or `null`), `items` in relevance order, a `skill` as the listing's item with the `files` of it that matched (each `path`, `title` and `summary`), `moreFiles`, `license` and `describedOnly`, or a `document` with its `path`, `title`, `summary` and `skillDirectory` (or `null`), and `nextCursor` (`limit` 1 to 25, 10 unless given). Words are matched, not meaning, in the language the pack is written in; the deployment's listing of a mount is bounded, and these two are how the rest of a large pack is reached.
+
 ### `PUT /api/v1/projects/<key>/pack-token` and `DELETE .../pack-token`
 
 The pack token ([ADR-0028](../adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md)), for an owner, signed in from the console's own pages or through their agent's token. `PUT` takes `{ "token" }`, a token a person made at the deployment for the pack's repository (8 to 1024 characters, no whitespace), tries it against the deployment once (`project.pack_token_refused` when the pack is not served to it or the project names no pack; `skills.unavailable` when the deployment could not be reached), seals it with the console's secret (`project.pack_token_unsupported` where the console has none) and keeps it, answering the project with `packToken: { setAt }` and writing a `project.updated` event naming the field `packToken`. The token is answered nowhere and logged nowhere. `DELETE` takes it away the same way; taking away what is not there writes nothing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillcdn/console",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "What a custom SkillCDN console is built from: the API client and schemas, the components, the composition of the default console, and the console command agents work the board with.",
   "license": "MIT",
   "homepage": "https://github.com/skillcdn/console#readme",

package/skills/working-the-board/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Needs a shell with the console command on the PATH (npm install -g @skillcdn/console, Node.js 24 or newer), signed in by a person. Nothing else; the command needs no key of its own and the agent never sees a token.
 metadata:
   author: skillcdn
-  version: "1.14"
+  version: "1.16"
 skillcdn:
   translations:
     ko:
@@ -32,7 +32,7 @@ A task of the board goes in, named by its number; a run comes out: the task take
 |---|---|---|
 | The `console` command, signed in | `console whoami` says as whom, at which console, and in which project this directory works; and whether the command and the console go together. `console logins` lists the consoles this machine is signed in to; a directory bound to another console (`.skillcdn-console.json`) needs a login there, and a token never goes to a console it was not made at ([ADR-0027](/docs/adr/0027-the-command-keeps-a-login-per-console-and-a-token-goes-only-to-the-console-that-issued-it.md)). | Stop and tell the person what to do: `npm install -g @skillcdn/console`; `console login --url <the console's address>`, which shows an address and a code the person approves on the console's own pages; `console use <key>` once in the directory, to name the project. Never look for a token. |
 | The command at a version the console takes | A command the console refuses as outdated, or as too new, exits with `4` and prints the command that updates it where it is installed ([ADR-0025](/docs/adr/0025-the-command-names-its-version-on-every-request-and-the-console-holds-it-to-the-range-it-takes.md)). | Run the update command it printed, then go on; where the machine refuses the update, stop and tell the person. A line on stderr that a newer command exists, while the console still answers, is read and left for later. |
-| The command's own words | `console help`, and `console help <command>`: what each command takes, the limits the console holds it to, and the refusals it may meet, by code. | They are the reference at run time. This skill says how the work goes, not what each flag means. |
+| The command's own words | `console help` lists every command in a line, read once; `console help <command>` says one in full, every form and flag, the limits the console holds it to, and the refusals it may meet, by code, read when the command is about to be used. | They are the reference at run time. This skill says how the work goes, not what each flag means. |
 
 The full contract is the [specification of the command line](/docs/specs/cli.md); the command is a thin client of the [REST API](/docs/specs/rest.md), which a script may use directly.
 
@@ -41,7 +41,7 @@ The full contract is the [specification of the command line](/docs/specs/cli.md)
 | Input | Source |
 |---|---|
 | The task | Its number (`#7`) or its id, from what the person said. Told to pick one, `console work` lists what is on the person's plate across their projects, the sooner due first (`--person <login>` another person's, for an administrator or an owner of a project they are in), and `console tasks --state ready --mine` what is ready and theirs in this one (`--due overdue`, `--due week`, `--category <key>` and `--goal <id>` narrow it further); a task is never taken without being told which, or that any ready one may be. |
-| The work | The task's body, read with `console task <number>`: what to make, where, the milestones, what to ask; the comments on it, which are the discussion so far, printed with the task, their pictures saved with `console file <id>`; with its plan, the category, the goal it works towards (`console goal <id>` says what reaching it means, its category and the days it starts and is meant to be reached by) and the days it starts and is due, which the reports and the summary keep to. The pages it links to (`console doc <path>`) and the project's pack (`console skills` lists its skills; `console skill <path>` reads one whole through the console, its rules first, a private pack through the pack token the project holds, [ADR-0028](/docs/adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md); `console skill <path> --file <file>` a file of it; a host that lists skills through a connection of its own loads them by their URI) say the rest. |
+| The work | The task's body, read with `console task <number>`: what to make, where, the milestones, what to ask; the comments on it, which are the discussion so far, printed with the task, their pictures saved with `console file <id>`; with its plan, the category, the goal it works towards (`console goal <id>` says what reaching it means, its category and the days it starts and is meant to be reached by) and the days it starts and is due, which the reports and the summary keep to. The pages it links to (`console doc <path>`) and the project's pack (`console skills` lists its skills and says how many skills and documents it has; `console skills <folder>` shows what a folder of it holds, `console skills --search <words>` what the words find in it; `console skill <path>` reads one whole through the console, its rules first, a private pack through the pack token the project holds, [ADR-0028](/docs/adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md); `console skill --file <file>` a file of it; a host that lists skills through a connection of its own loads them by their URI) say the rest. |
 | The rules | The workspace's, the console's own until an administrator writes the organization's, and this project's own when it has them: which skills to load first, where the work lives, the pages, what may be decided alone, how to report ([ADR-0023](/docs/adr/0023-the-rules-of-a-board-are-pages-the-workspace-and-its-projects-keep-read-first-by-every-agent.md)). `console take` prints them with the task, so they are read once, there; `console rules` reads them without taking, as when a task is still to be chosen. They hold over this skill's defaults where they differ. |
 
 ## Workflow

package/src/api.ts

@@ -209,7 +209,11 @@ export {
   type RestRunInput,
   type RestRuns,
   type RestSkill,
+  type RestSkillBrowse,
+  type RestSkillBrowseEntry,
   type RestSkillFile,
+  type RestSkillFind,
+  type RestSkillFindItem,
   type RestSkillLoad,
   type RestSkillPage,
   type RestSkills,
@@ -296,7 +300,11 @@ export {
   restRunInputSchema,
   restRunSchema,
   restRunsSchema,
+  restSkillBrowseEntrySchema,
+  restSkillBrowseSchema,
   restSkillFileSchema,
+  restSkillFindItemSchema,
+  restSkillFindSchema,
   restSkillLoadSchema,
   restSkillPageSchema,
   restSkillSchema,

package/src/cli/cli.ts

@@ -17,6 +17,7 @@ import {
   type RestDecision,
   type RestMember,
   type RestPerson,
+  type RestSkillBrowse,
   type RestSkillFile,
   type RestSkillLoad,
   type RestSkillPage,
@@ -74,7 +75,9 @@ import {
   formatRules,
   formatRun,
   formatRunLine,
+  formatSkillBrowse,
   formatSkillFile,
+  formatSkillFind,
   formatSkillLoad,
   formatSkills,
   formatTask,
@@ -995,27 +998,82 @@ const categories: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+/** How many pages of a skill, of a file or of a folder the command follows before it stops: far above what one holds. */
+const MAX_SKILL_PAGES = 64;
+/** How many results a search answers at most: what the deployment allows on one page. */
+const MAX_FIND_LIMIT = 25;
+
 const skills: Command = async (args, io) => {
-  const { values } = parse(args, {}, false);
+  const { values, positionals } = parse(args, {
+    search: { type: "string" },
+    limit: { type: "string" },
+  });
+  if (positionals.length > 1) {
+    throw misuse("Say one folder: console skills [<folder>] [--search <words>]");
+  }
+  // The root of the pack is the mounted folder, which the deployment reads as no path at all.
+  const given = positionals[0];
+  const folder = given === undefined || given === "/" || given === "." ? undefined : given;
+  const words = text(values, "search");
+  const limit = text(values, "limit");
+  if (words === undefined && limit !== undefined) {
+    throw misuse("--limit goes with --search: console skills --search <words> [--limit <n>]");
+  }
+  const atMost = limit === undefined ? undefined : Number(limit);
+  if (
+    atMost !== undefined &&
+    (!Number.isInteger(atMost) || atMost < 1 || atMost > MAX_FIND_LIMIT)
+  ) {
+    throw misuse(`Not a number of results, 1 to ${MAX_FIND_LIMIT}: ${limit}`);
+  }
   const session = await open(io, values);
   const project = await session.project();
+  if (words !== undefined) {
+    // One page of what the words find; more is said, and narrowed by the agent, not fetched.
+    const found = await project.skillFind(words, { path: folder, limit: atMost });
+    answer(io, session, found, () => formatSkillFind(found));
+    return EXIT.ok;
+  }
+  if (given !== undefined) {
+    // The folder whole: its pages until the end, as the deployment lists them.
+    const folders: NonNullable<RestSkillBrowse["folder"]>[] = [];
+    let cursor: string | undefined;
+    let last: RestSkillBrowse | undefined;
+    for (let n = 0; n < MAX_SKILL_PAGES; n += 1) {
+      last = await project.skillBrowse({ path: folder, cursor });
+      if (last.status !== "ready" || last.folder === null) {
+        break;
+      }
+      folders.push(last.folder);
+      if (last.folder.nextCursor === null) {
+        break;
+      }
+      cursor = last.folder.nextCursor;
+    }
+    if (last === undefined) {
+      throw failed("The folder could not be read.");
+    }
+    const browsed = last;
+    answer(io, session, { ...browsed, folders }, () => formatSkillBrowse(browsed, folders));
+    return EXIT.ok;
+  }
   const found = await project.skills();
   answer(io, session, found, () => formatSkills(found, io.skillsDir));
   return EXIT.ok;
 };
 
-/** How many pages of a skill, or of a file, the command follows before it stops: far above what one holds. */
-const MAX_SKILL_PAGES = 64;
-
 const skill: Command = async (args, io) => {
   const { values, positionals } = parse(args, { file: { type: "string" } });
-  const path = theOne(
-    positionals,
-    "Say which skill: console skill <path of its SKILL.md> [--file <path>]",
-  );
+  const file = text(values, "file");
+  // A file is read by its own path from the repository's root; a skill's path beside it would be
+  // ignored, which reads as if it mattered, so the two together are not understood.
+  if (file !== undefined && positionals.length > 0) {
+    throw misuse(
+      "Say one: console skill <path of its SKILL.md> for a skill, or console skill --file <path> for a file of the pack.",
+    );
+  }
   const session = await open(io, values);
   const project = await session.project();
-  const file = text(values, "file");
   if (file !== undefined) {
     // The file whole, page after page, as the console reads it from the deployment.
     const parts: string[] = [];
@@ -1040,6 +1098,10 @@ const skill: Command = async (args, io) => {
     answer(io, session, { ...read, content }, () => formatSkillFile(read, content));
     return EXIT.ok;
   }
+  const path = theOne(
+    positionals,
+    "Say which skill: console skill <path of its SKILL.md>, or console skill --file <path> for a file of the pack",
+  );
   // The skill whole: its pages until complete, the rules first, as load_skill lays them out.
   const pages: RestSkillPage[] = [];
   let cursor: string | undefined;

package/src/cli/format.ts

@@ -15,7 +15,10 @@ import type {
   RestProjectRules,
   RestRules,
   RestRun,
+  RestSkillBrowse,
+  RestSkillBrowseEntry,
   RestSkillFile,
+  RestSkillFind,
   RestSkillLoad,
   RestSkillPage,
   RestSkills,
@@ -254,10 +257,13 @@ const SKILLS_WORDS: Readonly<Record<Exclude<RestSkills["status"], "none" | "read
   unavailable: "SkillCDN could not be reached; ask again later.",
 };
 
+/** A count with its noun: `1 skill`, `2 skills`. */
+const counted = (n: number, noun: string): string => `${n} ${noun}${n === 1 ? "" : "s"}`;
+
 /**
- * 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.
+ * The organization's skills: where they are, the pack by name and by count, each skill 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 =
@@ -273,16 +279,29 @@ export function formatSkills(skills: RestSkills, ownSkills?: string): string {
   if (skills.status !== "ready") {
     return [head, SKILLS_WORDS[skills.status], ...own].join("\n");
   }
+  const lines = [head];
+  if (skills.pack !== undefined) {
+    const named = [skills.pack.name, skills.pack.description]
+      .filter((text): text is string => text !== null)
+      .join("  ");
+    if (named !== "") {
+      lines.push(named);
+    }
+  }
+  if (skills.counts !== undefined) {
+    lines.push(
+      `${counted(skills.counts.skills, "skill")}, ${counted(skills.counts.documents, "document")}: console skills <folder> shows what a folder holds (/ for the root), console skills --search <words> finds skills and documents by words.`,
+    );
+  }
   if (skills.items.length === 0) {
-    return [head, "No skills at this address.", ...own].join("\n");
+    lines.push("No skills at this address.");
   }
-  const lines = [head];
   for (const skill of skills.items) {
     lines.push(`${skill.name}  ${skill.description}`, `    ${skill.uri ?? skill.path}`);
   }
   lines.push(
     "",
-    `Read a skill whole with console skill <path>, its rules first, and a file of the pack with console skill <path> --file <file>; or load it by its URI through your own SkillCDN connection to this address, which a person makes at ${skills.page}. --json adds the page of each, for a person.`,
+    `Read a skill whole with console skill <path>, its rules first, and a file of the pack with console skill --file <path>; or load it by its URI through your own SkillCDN connection to this address, which a person makes at ${skills.page}. --json adds the page of each, for a person.`,
     ...own,
   );
   return lines.join("\n");
@@ -576,7 +595,7 @@ export function formatSkillLoad(loaded: RestSkillLoad, pages: readonly RestSkill
   if (last.files.length > 0) {
     lines.push(
       "",
-      `Files of the skill, read with console skill ${first.path} --file <path>: ${last.files.join(", ")}`,
+      `Files of the skill, read with console skill --file <path>: ${last.files.join(", ")}`,
     );
   }
   if (last.references.length > 0) {
@@ -621,6 +640,8 @@ export function formatSkillFile(read: RestSkillFile, content: string): string {
         (entry) =>
           `${entry.kind === "directory" ? "d" : "f"}  ${entry.path}${entry.size === null ? "" : `  ${entry.size}`}`,
       ),
+      "",
+      "console skills <folder> shows a folder with its skills marked, what each folder holds and the README that introduces it.",
     ].join("\n");
   }
   if (read.file === null) {
@@ -631,3 +652,131 @@ export function formatSkillFile(read: RestSkillFile, content: string): string {
     content.trimEnd(),
   ].join("\n");
 }
+
+/** One entry of a browsed folder: what it is, its path, its words, and the facts of its kind. */
+function formatBrowseEntry(entry: RestSkillBrowseEntry): string {
+  const facts: string[] = [];
+  if (entry.kind === "directory") {
+    if (entry.skillCount > 0) {
+      facts.push(counted(entry.skillCount, "skill"));
+    }
+    if (entry.documentCount > 0) {
+      facts.push(counted(entry.documentCount, "document"));
+    }
+    if (entry.overviewPath !== null) {
+      facts.push(`README ${entry.overviewPath}`);
+    }
+  }
+  if (entry.kind === "skill") {
+    if (entry.license !== null) {
+      facts.push(entry.license);
+    }
+    if (entry.describedOnly) {
+      facts.push("described only");
+    }
+  }
+  if (entry.kind === "file" && entry.size !== null) {
+    facts.push(`${entry.size} bytes`);
+  }
+  const words = [entry.name, entry.description]
+    .filter((text): text is string => text !== null && text !== "")
+    .join("  ");
+  const mark = entry.kind === "skill" ? "skill" : entry.kind === "directory" ? "d" : "f";
+  return `${mark}  ${entry.path}${words === "" ? "" : `  ${words}`}${facts.length === 0 ? "" : `  (${facts.join("; ")})`}`;
+}
+
+/**
+ * What a folder of the pack holds, as browse_repo lays it out: the README that introduces the
+ * folder, then its skills, its folders with what each holds, and its files, across the pages the
+ * listing came in.
+ */
+export function formatSkillBrowse(
+  browsed: RestSkillBrowse,
+  folders: readonly NonNullable<RestSkillBrowse["folder"]>[],
+): string {
+  if (browsed.status === "none" || browsed.address === null) {
+    return NO_ADDRESS;
+  }
+  const head = `folder at ${browsed.address}, served by ${browsed.source}: ${browsed.status}`;
+  if (browsed.status !== "ready") {
+    return [head, SKILLS_WORDS[browsed.status]].join("\n");
+  }
+  const [first] = folders;
+  if (first === undefined) {
+    return [head, "Nothing was read."].join("\n");
+  }
+  const last = folders[folders.length - 1] ?? first;
+  const lines = [`folder ${first.path === "" ? "/" : first.path} at ${browsed.address}`];
+  if (first.overview !== null) {
+    const words = [first.overview.title, first.overview.description]
+      .filter((text): text is string => text !== null && text !== "")
+      .join("  ");
+    lines.push(`    ${words === "" ? "" : `${words}  `}(README: ${first.overview.path})`);
+  }
+  const entries = folders.flatMap((folder) => folder.entries);
+  if (entries.length === 0) {
+    lines.push("Nothing in this folder.");
+  }
+  for (const entry of entries) {
+    lines.push(formatBrowseEntry(entry));
+  }
+  if (last.nextCursor !== null) {
+    lines.push("More entries: the listing stopped before the end of the folder.");
+  }
+  lines.push(
+    "",
+    "Read a skill with console skill <path>; a file, or a README named above, with console skill --file <path>; a folder with console skills <folder>.",
+  );
+  return lines.join("\n");
+}
+
+/**
+ * What words found in the pack, as search_repo lays it out: skills with the files of theirs that
+ * matched, documents on their own, in relevance order; words, not meaning.
+ */
+export function formatSkillFind(found: RestSkillFind): string {
+  if (found.status === "none" || found.address === null) {
+    return NO_ADDRESS;
+  }
+  const head = `search at ${found.address}, served by ${found.source}: ${found.status}`;
+  if (found.status !== "ready") {
+    return [head, SKILLS_WORDS[found.status]].join("\n");
+  }
+  if (found.found === null) {
+    return [head, "Nothing was read."].join("\n");
+  }
+  const { query, path, items, nextCursor } = found.found;
+  const where = path === null || path === "" ? "" : ` within ${path}`;
+  const lines = [
+    `found for "${query}"${where} at ${found.address}: ${counted(items.length, "result")}`,
+  ];
+  for (const item of items) {
+    if (item.kind === "skill") {
+      lines.push(
+        `skill  ${item.path}  ${item.name}  ${item.description}${item.describedOnly ? "  (described only)" : ""}`,
+      );
+      for (const file of item.files) {
+        lines.push(`    file  ${file.path}${file.title === null ? "" : `  ${file.title}`}`);
+      }
+      if (item.moreFiles > 0) {
+        lines.push(`    and ${counted(item.moreFiles, "more file")}`);
+      }
+    } else {
+      lines.push(
+        `document  ${item.path}${item.title === null ? "" : `  ${item.title}`}${item.summary === null ? "" : `  ${item.summary}`}`,
+      );
+    }
+  }
+  if (nextCursor !== null) {
+    lines.push(
+      "More matched: narrow the words, or search within a folder (console skills <folder> --search <words>).",
+    );
+  }
+  if (items.length > 0) {
+    lines.push(
+      "",
+      "Read a skill with console skill <path>, a file or a document with console skill --file <path>.",
+    );
+  }
+  return lines.join("\n");
+}