@skillcdn/console 0.1.24 → 0.3.1

package/src/cli/help.ts

@@ -136,9 +136,10 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   use: {
     usage: "use <key> [--url <origin>] [--account <login>]",
-    synopsis: "Binds this directory to a project: writes .skillcdn-console.json here.",
+    synopsis:
+      "Binds this directory to a project: writes .skillcdn-console.json here, and prints the sentence for the checkout's agreement.",
     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.",
+      "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. Then prints the sentence for the checkout's agreement (AGENTS.md, or CLAUDE.md where that is the file agents read), to be copied as it is, since nothing sends an agent to the console until the checkout says so.",
     refusals: ["project.not_found: no project has the key, or it is not yours to see"],
   },
   work: {
@@ -203,9 +204,26 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   people: {
     usage: "people",
-    synopsis: "Everyone of the workspace, by login, with what each is in it.",
+    synopsis: "The people you see, by login, with what each is in the workspace.",
+    about:
+      "The people of the workspace you see, 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. Everyone, unless the workspace shows a member only the people they share a project with (console workspace says which; an administrator sees everyone). Then, where you see everyone, the logins an administrator let in that nobody has signed in with yet. The logins are what --assignee, member and person take; a login is found exactly, so an owner lists someone the list does not show.",
+  },
+  workspace: {
+    usage:
+      "workspace  |  workspace edit [--people-visibility <everyone|shared-projects>] [--week-start <auto|monday|sunday>] [--time-zone <zone|none>]  |  workspace pack-token --connect  |  workspace pack-token --stdin  |  workspace pack-token --remove",
+    overview:
+      "workspace  |  workspace edit [flags]  |  workspace pack-token --connect|--stdin|--remove",
+    synopsis:
+      "The workspace's settings; or some changed, or its SkillCDN token set, for an administrator.",
     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.",
+      "What the workspace is called; who sees whom on the People page and in the pickers (everyone; or shared-projects: a member sees only the people they share a project with, an administrator everyone; a project open to the workspace has everyone in it, so a member of one sees everyone); the day the calendars begin a week on (auto: the system default, as each device has it); the workspace's time zone, an IANA name such as Asia/Seoul, in which this command prints moments as ISO 8601 with its offset, as the login kept it at login or whoami, or none, which leaves them as the API gives them, in UTC; where the organization's skills come from; and the most days a token may last. edit changes any of the first three, for an administrator; --json leaves moments as the API gives them. pack-token is the SkillCDN token the organization's pack is read with, by every project that names no address of its own and holds no token of its own (ADR-0036), for an administrator: with --connect, the console asks SkillCDN for a code, this command prints the page and the code, a person who may open the repository approves there, signed in at SkillCDN, and the console receives the token, shown to nobody; with --stdin, a token made by hand at SkillCDN is read from standard input and never an argument; --remove takes the token away.",
+    refusals: [
+      "auth.forbidden: only an administrator changes the workspace's settings or its token",
+      "request.invalid: the time zone is not a name the console knows",
+      "workspace.pack_token_refused: SkillCDN does not serve the organization's pack to the token, or the console names no address for the organization's skills",
+      "workspace.pack_connect_refused: the console names no address for the organization's skills, the pack is on the console's machine, or SkillCDN refused to begin",
+      "workspace.pack_token_unsupported, workspace.pack_connect_unsupported: the console keeps no secret to seal a token with (AUTH_SECRET), or reaches no deployment",
+    ],
   },
   person: {
     usage:
@@ -224,12 +242,13 @@ 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',
+      '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> --connect  |  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.",
+      "project <key>  |  project new <key> <name> [flags]  |  project edit <key> [flags]  |  project icon <key> <file>|--remove  |  project pack-token <key> --connect|--stdin|--remove",
+    synopsis:
+      "One project in full; or a project made, changed, given its mark or its SkillCDN 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.",
+      "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 SkillCDN token (pack-token, ADR-0028), which the console keeps sealed to read a private pack with, and which a project that reads the organization's pack may leave to the workspace's (console workspace pack-token): with --connect, the console asks SkillCDN for a code, this command prints the page and the code, a person who may open the repository approves there, signed in at SkillCDN, and the console receives the token, shown to nobody (ADR-0036); with --stdin, a token a person made by hand at SkillCDN is read from standard input and never an argument; --remove takes the token 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}`,
@@ -243,13 +262,16 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       "project.invalid_address: the skills address is not one as SkillCDN spells it",
       "project.invalid_icon: the file is not an image of those kinds, by its bytes",
       "request.too_large: the image is over the limit",
+      "project.pack_connect_unsupported: the console reaches no deployment, or keeps no secret to seal a token with",
+      "project.pack_connect_refused: the project names no pack, the pack is on the console's machine, or SkillCDN refused to begin",
+      "skills.unavailable: SkillCDN could not be reached; try again later",
     ],
   },
   members: {
     usage: "members",
-    synopsis: "Those listed in the project, with what each is in it.",
+    synopsis: "The members of 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.",
+      "The members of the project, by login, with what each is in it (owner, who configures it; member, who works on it) and since when. In a private project, those listed; in one open to the workspace, everyone of it, an owner where listed as one or an administrator, a member otherwise. An administrator owns every project.",
   },
   member: {
     usage:
@@ -257,11 +279,12 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     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.",
+      "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. In a project open to the workspace everyone is a member already: only an owner is listed (member add --role owner, or member role <login> owner), and an owner made a member again stays the member everyone is. 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",
       "member.exists: the person is listed already; member role changes what they are",
+      "member.open_project: the project is open to the workspace, so everyone is a member already; list an owner with --role owner",
       "member.not_found: the person is not listed in the project",
     ],
   },
@@ -285,11 +308,12 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     ],
   },
   skills: {
-    usage: "skills  |  skills <folder>  |  skills --search <words> [<folder>] [--limit <n>]",
+    usage:
+      "skills  |  skills <folder>  |  skills --search <words> [<folder>] [--limit <n>] [--cursor <cursor>]",
     synopsis:
       "The project's pack: its skills; what a folder of it holds; or what words find in it.",
     about:
-      "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.",
+      "The project's pack, read by the console at the project's address, or the organization's: at a SkillCDN deployment, with the pack token the project holds where the pack is private (ADR-0028), or from a directory on the console's machine for a local address (ADR-0031). Alone: where the pack is and what a client is told of it on connect, then every skill with the path of its SKILL.md and every document, as a connection of your own would list them, and where the console's own skills are on this machine. With a folder (. for the root): what it holds, whole, as browse_repo lays it out for a model: 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: skills first, with the files of theirs that matched, then documents, in relevance order; 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 nextCursor line says when more matched, which --cursor continues. The text is the one an MCP client's model is given, with the reads named as these commands. --json answers with the console's own JSON: what the pack answered, in the shapes of the main repository's REST API, the pages of a folder joined.",
     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",
@@ -301,11 +325,11 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     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, or the URI it lists beside the path (skill://gh/<owner>/<repo>/<path>). --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.",
+      "One skill of the project's pack, whole, as load_skill lays it out for a model: the rules of the repository from its root to the nearest manifest, the skill's instructions, the files it includes, then its supporting files and what it refers to; the pages it came in are joined. Read by the console from the pack, 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, or the URI the pack names it by (skill://<host>/<owner>/<name>/<path>). --file <path> reads a file of the pack instead, whole, as read_repo_file does, or what a folder holds, and takes no skill's path beside it; console skills <folder> shows a folder with more. --json answers with what the pack answered, in the shapes of the main repository's REST API, the pages joined.",
     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",
+      "status failed, for a file: the pack will not carry it, too large or not text",
     ],
   },
   rules: {
@@ -327,7 +351,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     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; 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.",
+      "Takes a task: a run begins, and the task is in progress and the person's; the run's id and the task's id are printed on a line of their own, then the task, then the rules of the board. 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",
@@ -370,7 +394,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       '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. The decision's id is printed as soon as it is raised. ${ON_THE_RUN}`,
+    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. The decision's id is printed as soon as it is raised. The person chooses one of the options, or answers in their own words: the answer then names one more option, their words, marked own; act on it as given. ${ON_THE_RUN}`,
     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`,
@@ -383,7 +407,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     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.",
+      "One decision, with its context, its options, its answer (one of the options, or the person's own words as one more, marked own) 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}`],
     refusals: ["decision.not_found: no decision has that id"],
   },
@@ -603,7 +627,7 @@ const SECTIONS: readonly { readonly title: string; readonly commands: readonly s
   {
     title:
       "Configuring, as the person: what an administrator or an owner does on the pages, their agent does here, named on it",
-    commands: ["people", "person", "project", "members", "member", "category"],
+    commands: ["workspace", "people", "person", "project", "members", "member", "category"],
   },
 ];
 

package/src/cli/pack.ts

@@ -0,0 +1,356 @@
+import {
+  type BrowseResult,
+  browseBody,
+  browseResultOf,
+  catalogStateOf,
+  type DirectoryResult,
+  directoryBody,
+  directoryResultOf,
+  type FileResult,
+  type FindItem,
+  type FindResult,
+  fileBody,
+  fileResultOf,
+  findResultOf,
+  joinSkillPages,
+  type MountSummary,
+  mountSummaryOf,
+  parseAddress,
+  parseRepoPath,
+  parseSkillUri,
+  type RestBrowse,
+  type RestFile,
+  type RestMount,
+  type RestSkill,
+  renderBrowseResult,
+  renderDirectoryResult,
+  renderFileResult,
+  renderFindResult,
+  renderInstructions,
+  renderSkillResult,
+  type SkillResult,
+  skillOutcome,
+  skillResultOf,
+  type ToolWords,
+} from "@skillcdn/core";
+import type {
+  RestSkillBrowse,
+  RestSkillFile,
+  RestSkillFind,
+  RestSkillLoad,
+  RestSkills,
+} from "../schemas.js";
+import type { SkillsStatus } from "../vocabulary.js";
+
+// The pack of the project, as the command prints it (ADR-0028, ADR-0031): the console answers
+// what the pack's REST API answered, in the shapes of @skillcdn/core, and the command renders
+// it with the functions a deployment's own tools render for a model, naming the reads as its
+// own commands, so that an agent reads here what it would read over MCP, or with the skillcdn
+// command. The pages a read came in are joined first: a skill, a folder and a file arrive whole.
+
+/** How the results name the four reads, so that an agent is told the command and not a tool. */
+export const CONSOLE_WORDS: ToolWords = {
+  browse: "console skills <folder>",
+  search: "console skills --search",
+  load: "console skill",
+  read: "console skill --file",
+};
+
+/** Where the reads of a pack are rendered at: what the listing said the address serves. */
+export type PackSummary = MountSummary;
+
+export const NO_ADDRESS = "No skills address: neither this project nor the console names one.";
+
+/** The words of a read that did not happen, by status, with what to do about it. */
+const SKILLS_WORDS: Readonly<Record<Exclude<SkillsStatus, "none" | "ready">, string>> = {
+  indexing: "The pack is still being indexed; ask again in a moment.",
+  failed:
+    "The pack could not be indexed, or this is a file the pack will not carry: too large, or not text.",
+  not_found:
+    "Nothing is served to the console at this address or path: it is not there, or the pack is private and the project holds no pack token for it (console project pack-token <key> --stdin, for an owner).",
+  token_invalid:
+    "The pack token the project holds no longer works at the deployment: an owner sets a new one (console project pack-token <key> --stdin).",
+  unavailable: "The pack could not be reached; ask again later.",
+};
+
+type Envelope = Pick<RestSkills, "address" | "source" | "page" | "status" | "refusal">;
+
+/** The first line of an answer about the pack: what was read, where the pack is, and how it went. */
+function head(what: string, answer: Envelope): string {
+  const where =
+    answer.source === null ? "read from the console's machine" : `served by ${answer.source}`;
+  return `${what} at ${answer.address}, ${where}: ${answer.status}`;
+}
+
+/** A read that did not happen: the head, the words of its status, and the pack's own refusal when it gave one. */
+function refused(what: string, answer: Envelope): string {
+  const lines = [head(what, answer)];
+  if (answer.status !== "none" && answer.status !== "ready") {
+    lines.push(SKILLS_WORDS[answer.status]);
+  }
+  if (answer.refusal !== null) {
+    lines.push(answer.refusal.message);
+  }
+  return lines.join("\n");
+}
+
+/** What the listing said the address serves, for the reads to be rendered at; nothing when it did not answer. */
+export function summaryOf(listing: RestSkills): PackSummary | undefined {
+  return listing.mount === null ? undefined : mountSummaryOf(listing.mount);
+}
+
+/** Every skill and document the address serves, as one listing: what `search_repo` without words answers. */
+function listingOf(mount: RestMount, summary: PackSummary): FindResult | undefined {
+  if (mount.index.status !== "ready") {
+    return undefined;
+  }
+  const { index } = mount;
+  const items: FindItem[] = [];
+  for (const skill of index.skills) {
+    const directory = parseRepoPath(skill.directory);
+    if (!directory.ok) {
+      continue;
+    }
+    const path = parseRepoPath(
+      skill.path ?? (skill.directory === "" ? "SKILL.md" : `${skill.directory}/SKILL.md`),
+    );
+    items.push({
+      kind: "skill",
+      ...(path.ok ? { path: path.value } : {}),
+      name: skill.name,
+      directory: directory.value,
+      description: skill.description,
+      files: [],
+      moreFiles: 0,
+      // For people, and not rendered for a model.
+      translations: {},
+    });
+  }
+  for (const document of index.documents) {
+    const path = parseRepoPath(document.path);
+    if (path.ok) {
+      items.push({
+        kind: "document",
+        path: path.value,
+        title: document.title ?? undefined,
+        summary: document.summary ?? undefined,
+        skillDirectory: undefined,
+      });
+    }
+  }
+  const state = catalogStateOf(mount);
+  return {
+    mount: summary,
+    query: undefined,
+    items,
+    // The counts stand in the instructions above; without totals here, nothing suggests a cursor.
+    totals: undefined,
+    diagnostics: state.status === "ready" ? state.catalog.diagnostics : [],
+  };
+}
+
+/**
+ * The pack: where it is and how it answered; what a client is told on connect, as the
+ * deployment tells one; every skill and document; where a person connects an agent of its own;
+ * and where the console's own skills are on this machine.
+ */
+export function formatSkills(skills: RestSkills, ownSkills?: string): string {
+  const own =
+    ownSkills === undefined
+      ? []
+      : ["", `The console's own skills, for working the board: ${ownSkills}`];
+  if (skills.status === "none" || skills.address === null) {
+    return [NO_ADDRESS, ...own].join("\n");
+  }
+  const summary = summaryOf(skills);
+  if (skills.status !== "ready" || skills.mount === null || summary === undefined) {
+    return [refused("skills", skills), ...own].join("\n");
+  }
+  const lines = [
+    head("skills", skills),
+    "",
+    renderInstructions(catalogStateOf(skills.mount), CONSOLE_WORDS),
+  ];
+  const listing = listingOf(skills.mount, summary);
+  if (listing !== undefined) {
+    lines.push("", renderFindResult(listing, CONSOLE_WORDS));
+  }
+  if (skills.page !== null) {
+    lines.push(
+      "",
+      `A host with a SkillCDN connection of its own loads a skill by its URI, which a person makes at ${skills.page}; through the console, ${CONSOLE_WORDS.load} takes the URI too. --json adds the page of each skill, for a person.`,
+    );
+  }
+  lines.push(...own);
+  return lines.join("\n");
+}
+
+/**
+ * A skill's path as given, or taken out of the URI the listing names it by
+ * (`skill://<host>/<owner>/<name>/<path>`); a URI of another pack would read this pack's skill
+ * at the same path, or nothing, so it is said instead.
+ */
+export function skillPathIn(
+  given: string,
+  packAddress: string | null,
+): { readonly path: string } | { readonly error: string } {
+  const uri = parseSkillUri(given);
+  if (uri === undefined) {
+    return given.startsWith("skill://")
+      ? {
+          error: `Not a skill's URI the console knows: ${given}. Say the path of its SKILL.md from the repository's root, or the URI console skills lists.`,
+        }
+      : { path: given };
+  }
+  const pack = packAddress === null ? undefined : parseAddress(packAddress);
+  if (
+    pack?.ok === true &&
+    (uri.address.host !== pack.value.host ||
+      uri.address.owner !== pack.value.owner ||
+      uri.address.repo !== pack.value.repo)
+  ) {
+    return {
+      error: `That URI is of another pack, /${uri.address.host}/${uri.address.owner}/${uri.address.repo}; this project's pack is at ${packAddress}. Say the path of the SKILL.md, or a URI console skills lists.`,
+    };
+  }
+  return { path: uri.path };
+}
+
+/** The pages of a skill, as the console answered them, as the one skill they were cut from. */
+export function joinSkill(
+  pages: readonly RestSkillLoad[],
+  summary: PackSummary,
+): SkillResult | undefined {
+  return joinSkillPages(
+    pages.flatMap((page) =>
+      page.read?.status === "ready" ? (skillResultOf(page.read, summary) ?? []) : [],
+    ),
+  );
+}
+
+/** The skill whole, as the REST API answers one, for `--json`. */
+export function bodyOfSkill(skill: SkillResult): RestSkill {
+  const outcome = skillOutcome({ status: "ready", lookup: { kind: "found", skill } });
+  if ("failure" in outcome) {
+    throw new Error("a skill that was found has a body");
+  }
+  return outcome.body;
+}
+
+/** One skill as `load_skill` lays it out for a model: the rules, the body, the included files, its files and references. */
+export function formatSkillLoad(loaded: RestSkillLoad, whole: SkillResult | undefined): string {
+  if (loaded.status === "none" || loaded.address === null) {
+    return NO_ADDRESS;
+  }
+  if (loaded.status !== "ready") {
+    return refused("skill", loaded);
+  }
+  if (whole === undefined) {
+    return `${head("skill", loaded)}\nNothing was read.`;
+  }
+  return renderSkillResult(whole, CONSOLE_WORDS);
+}
+
+/** The pages of a folder, as the console answered them, as the one listing they were cut from. */
+export function joinFolder(
+  pages: readonly RestSkillBrowse[],
+  summary: PackSummary,
+): BrowseResult | undefined {
+  const results = pages.flatMap((page) =>
+    page.read?.status === "ready" ? (browseResultOf(page.read, summary) ?? []) : [],
+  );
+  const first = results[0];
+  const last = results[results.length - 1];
+  if (first === undefined || last === undefined) {
+    return undefined;
+  }
+  return {
+    ...first,
+    mount: last.mount,
+    entries: results.flatMap((result) => result.entries),
+    nextCursor: last.nextCursor,
+  };
+}
+
+/** A folder whole, as the REST API answers one page, for `--json`. */
+export const bodyOfFolder = (result: BrowseResult): RestBrowse =>
+  browseBody({ status: "ready", result });
+
+/** What a folder holds, as `browse_repo` lays it out for a model. */
+export function formatSkillBrowse(
+  browsed: RestSkillBrowse,
+  whole: BrowseResult | undefined,
+): string {
+  if (browsed.status === "none" || browsed.address === null) {
+    return NO_ADDRESS;
+  }
+  if (browsed.status !== "ready") {
+    return refused("folder", browsed);
+  }
+  if (whole === undefined) {
+    return `${head("folder", browsed)}\nNothing was read.`;
+  }
+  return renderBrowseResult(whole, CONSOLE_WORDS);
+}
+
+/** What words found, as `search_repo` lays it out for a model, one page of it. */
+export function formatSkillFind(found: RestSkillFind, summary: PackSummary | undefined): string {
+  if (found.status === "none" || found.address === null) {
+    return NO_ADDRESS;
+  }
+  if (found.status !== "ready" || found.read?.status !== "ready" || summary === undefined) {
+    return refused("search", found);
+  }
+  return renderFindResult(findResultOf(found.read, summary), CONSOLE_WORDS);
+}
+
+/** The pages of a file, as the console answered them, as the file whole; or the folder the path named. */
+export function joinFile(
+  pages: readonly RestSkillFile[],
+  summary: PackSummary,
+): FileResult | DirectoryResult | undefined {
+  const reads = pages.flatMap((page) => (page.read === null ? [] : [page.read]));
+  const first = reads[0];
+  if (first === undefined) {
+    return undefined;
+  }
+  if (first.kind === "directory") {
+    return directoryResultOf(first, summary);
+  }
+  const files = reads.flatMap((read) =>
+    read.kind === "file" ? (fileResultOf(read, summary) ?? []) : [],
+  );
+  const opening = files[0];
+  const closing = files[files.length - 1];
+  if (opening === undefined || closing === undefined) {
+    return undefined;
+  }
+  return {
+    ...opening,
+    mount: closing.mount,
+    content: files.map((file) => file.content).join(""),
+    nextOffset: closing.nextOffset,
+    totalLength: closing.totalLength,
+  };
+}
+
+/** A file whole, or a folder, as the REST API answers it, for `--json`. */
+export const bodyOfFile = (result: FileResult | DirectoryResult): RestFile =>
+  "entries" in result ? directoryBody(result) : fileBody(result);
+
+/** A file as `read_repo_file` lays it out for a model, whole; or what the folder holds. */
+export function formatSkillFile(
+  read: RestSkillFile,
+  whole: FileResult | DirectoryResult | undefined,
+): string {
+  if (read.status === "none" || read.address === null) {
+    return NO_ADDRESS;
+  }
+  if (read.status !== "ready") {
+    return refused("file", read);
+  }
+  if (whole === undefined) {
+    return `${head("file", read)}\nNothing was read.`;
+  }
+  return "entries" in whole ? renderDirectoryResult(whole) : renderFileResult(whole, CONSOLE_WORDS);
+}