@skillcdn/console 0.1.20 → 0.1.22

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/components/board.tsx

@@ -18,7 +18,6 @@ import {
 } from "../api.js";
 import { useWords } from "../i18n/index.js";
 import type { BoardFilter } from "../router.js";
-import { OPEN_TASK_STATES } from "../vocabulary.js";
 import { isPlainClick } from "./shell.js";
 import {
   Avatar,
@@ -35,12 +34,13 @@ import {
 // A card says what a person needs at a glance and nothing more: the number and the title, the
 // category, what is due, who is on it, and what blocks it. Whether an agent is at it is not
 // said, since the board cannot know (ADR-0020); the task's page shows its runs. A card is moved
-// to another column by hand: pressed anywhere but on its title and its menu, then dragged, with
-// a mouse at once and under a finger once it has rested a moment, so that a finger that moves
-// at once scrolls as it always did. The card's menu holds the rest: the way to the task's form,
-// and the way to put the task away once it is done or dropped (ADR-0029). The keyboard changes a
-// state on the task's page. The board takes its data as props and nothing from the network;
-// what it is told on a click goes back up.
+// to another column by hand: pressed anywhere but on its menu, its title included, then dragged
+// whole, with a mouse at once and under a finger once it has rested a moment, so that a finger
+// that moves at once scrolls as it always did; a click on the title opens the task as long as the
+// card was not dragged. The card's menu holds the rest: the way to the task's form, and the way to
+// put the task away (ADR-0029, ADR-0030). The keyboard changes a state on the task's page. The
+// board takes its data as props and nothing from the network; what it is told on a click goes
+// back up.
 
 export interface BoardProps {
   readonly tasks: readonly RestTask[];
@@ -57,7 +57,7 @@ export interface BoardProps {
   readonly editHref?: ((task: RestTask) => string) | undefined;
   /** Called when the menu's edit is chosen, to show the form without leaving the page; left out, the link is followed. */
   readonly onEdit?: ((task: RestTask) => void) | undefined;
-  /** Called when a task done or dropped is put away from its card's menu (ADR-0029). Left out, the menu offers nothing of it. */
+  /** Called when a task is put away from its card's menu (ADR-0029, ADR-0030). Left out, the menu offers nothing of it. */
   readonly onArchive?: ((task: RestTask) => void) | undefined;
 }
 
@@ -78,12 +78,21 @@ export function columnStateOf(value: string | null | undefined): TaskState | und
   return TASK_STATES.find((state) => state === value);
 }
 
+interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
 /** A card on its way to another column. */
 interface Drag {
   readonly task: RestTask;
-  readonly from: { readonly x: number; readonly y: number };
+  readonly from: Point;
   readonly x: number;
   readonly y: number;
+  /** Where on the card it was taken hold of, so that the card moves whole under the pointer. */
+  readonly grip: Point;
+  /** How wide the card is where it stands, so that the one in hand is the same. */
+  readonly width: number;
   /** Whether the card has come loose: the mouse has travelled, or the finger has rested. */
   readonly moving: boolean;
   /** Whether the press is a finger's, which must rest before the card comes loose. */
@@ -97,23 +106,21 @@ export interface TaskCardProps {
   readonly href: string;
   readonly onOpen: (task: RestTask) => void;
   readonly today?: string | undefined;
-  /** Called when the card is pressed anywhere but on its controls, to drag it to another column; left out, the card stays where it is. */
+  /** Called when the card is pressed anywhere but on its menu, to drag it to another column; left out, the card stays where it is. */
   readonly onPress?: ((task: RestTask, event: ReactPointerEvent<HTMLElement>) => void) | undefined;
-  /** Whether the card is on its way to another column. */
+  /** Whether the card is on its way to another column: the one left in its place is faded. */
   readonly dragging?: boolean | undefined;
   /** Where the task is edited; given, the card's menu leads there. */
   readonly editHref?: string | undefined;
   /** Called when the menu's edit is chosen, to show the form without leaving the page; left out, the link is followed. */
   readonly onEdit?: ((task: RestTask) => void) | undefined;
-  /** Called when the task is put away from the card's menu; offered once the task is done or dropped (ADR-0029). */
+  /** Called when the task is put away from the card's menu, whatever its state (ADR-0030). */
   readonly onArchive?: ((task: RestTask) => void) | undefined;
 }
 
 export function TaskCard(props: TaskCardProps) {
   const words = useWords();
   const { task, onPress } = props;
-  const closed = !OPEN_TASK_STATES.includes(task.state);
-  const archive = closed ? props.onArchive : undefined;
   return (
     <article
       className={cx(
@@ -124,12 +131,19 @@ export function TaskCard(props: TaskCardProps) {
       aria-label={`#${task.number} ${task.title}`}
       onPointerDown={onPress === undefined ? undefined : (event) => onPress(task, event)}
     >
-      {(props.editHref !== undefined || archive !== undefined) && (
-        <CardMenu task={task} editHref={props.editHref} onEdit={props.onEdit} onArchive={archive} />
+      {(props.editHref !== undefined || props.onArchive !== undefined) && (
+        <CardMenu
+          task={task}
+          editHref={props.editHref}
+          onEdit={props.onEdit}
+          onArchive={props.onArchive}
+        />
       )}
       <a
         className="sc-card-title"
         href={props.href}
+        // The card is dragged by our own hand, the title included; the browser's drag of a link is not it.
+        draggable={false}
         onClick={(event) => {
           if (isPlainClick(event)) {
             event.preventDefault();
@@ -169,7 +183,8 @@ const MENU_MARGIN = 8;
 /**
  * The card's menu: three dots in its corner, which open the ways a card has beyond being moved,
  * each given by the composition. The menu is rendered over the document, so that no column
- * clips it; a press elsewhere, the escape key, a scroll or a change of the window closes it.
+ * clips it; a press elsewhere, the escape key, a scroll or a change of the window closes it, and
+ * so does the button that opened it.
  */
 function CardMenu(props: {
   readonly task: RestTask;
@@ -194,6 +209,13 @@ function CardMenu(props: {
       right: Math.max(MENU_MARGIN, window.innerWidth - rect.right),
     });
   };
+  /** Whether the focus, or a press, is on the menu or on its button: the menu's own. */
+  const own = useCallback(
+    (target: EventTarget | null): boolean =>
+      target instanceof Node &&
+      (panel.current?.contains(target) === true || button.current?.contains(target) === true),
+    [],
+  );
   useEffect(() => {
     if (!open) {
       return;
@@ -214,14 +236,9 @@ function CardMenu(props: {
     }
     panel.current?.querySelector<HTMLElement>("[role='menuitem']")?.focus({ preventScroll: true });
     const away = (event: PointerEvent) => {
-      const target = event.target;
-      if (
-        target instanceof Node &&
-        (panel.current?.contains(target) === true || button.current?.contains(target) === true)
-      ) {
-        return;
+      if (!own(event.target)) {
+        close();
       }
-      close();
     };
     const key = (event: KeyboardEvent) => {
       if (event.key === "Escape") {
@@ -239,7 +256,7 @@ function CardMenu(props: {
       window.removeEventListener("scroll", close, true);
       window.removeEventListener("resize", close);
     };
-  }, [open, close]);
+  }, [open, close, own]);
   // The arrow keys walk the items, around the ends.
   const walk = (event: ReactKeyboardEvent<HTMLDivElement>) => {
     if (event.key !== "ArrowDown" && event.key !== "ArrowUp") {
@@ -283,9 +300,9 @@ function CardMenu(props: {
             aria-label={`#${task.number} ${task.title}`}
             style={{ top: place.top, right: place.right }}
             onKeyDown={walk}
+            // The focus leaving for anywhere but the menu's own button closes it; the button closes it itself.
             onBlur={(event) => {
-              const next = event.relatedTarget;
-              if (!(next instanceof Node && panel.current?.contains(next) === true)) {
+              if (!own(event.relatedTarget)) {
                 close();
               }
             }}
@@ -340,6 +357,8 @@ export function byDue(a: RestTask, b: RestTask): number {
   return b.number - a.number;
 }
 
+const nothing = () => undefined;
+
 export function Board(props: BoardProps) {
   const words = useWords();
   const { onMove } = props;
@@ -353,10 +372,10 @@ export function Board(props: BoardProps) {
   const loose = useRef(false);
 
   const press = useCallback((task: RestTask, event: ReactPointerEvent<HTMLElement>) => {
-    // The card's own controls, its title and its menu, are pressed for themselves.
+    // The card's menu is pressed for itself; everything else on the card takes hold of it.
     if (
       event.button !== 0 ||
-      (event.target instanceof Element && event.target.closest("a, button") !== null)
+      (event.target instanceof Element && event.target.closest("button") !== null)
     ) {
       return;
     }
@@ -365,14 +384,26 @@ export function Board(props: BoardProps) {
       // The press is the drag's beginning and nothing else: no text is selected on the way.
       event.preventDefault();
     }
+    const rect = event.currentTarget.getBoundingClientRect();
     const from = { x: event.clientX, y: event.clientY };
-    setDrag({ task, from, x: from.x, y: from.y, moving: false, hold, over: undefined });
+    setDrag({
+      task,
+      from,
+      x: from.x,
+      y: from.y,
+      grip: { x: from.x - rect.left, y: from.y - rect.top },
+      width: rect.width,
+      moving: false,
+      hold,
+      over: undefined,
+    });
   }, []);
 
   // While a card is held, the pointer is followed over the whole document: the column under it
   // is marked, the board scrolls when the pointer nears its edge, and the release moves the task.
   // A finger's hold is timed here, and once the card has come loose the page no longer scrolls
-  // under the finger, nor asks for the menu a long press would otherwise bring up.
+  // under the finger, nor asks for the menu a long press would otherwise bring up; the click that
+  // follows a drag opens nothing.
   const held = drag !== null;
   useEffect(() => {
     if (!held) {
@@ -421,8 +452,18 @@ export function Board(props: BoardProps) {
         return { ...before, moving: true, over: columnUnder(before.x, before.y) };
       });
     };
+    const swallow = (event: MouseEvent) => {
+      event.preventDefault();
+      event.stopPropagation();
+    };
     const release = (event: PointerEvent) => {
       const last = current.current;
+      if (loose.current) {
+        // The click the browser sends after the pointer is let go would open the title's task:
+        // it is swallowed, and the ear for it taken down once that moment has passed.
+        window.addEventListener("click", swallow, true);
+        window.setTimeout(() => window.removeEventListener("click", swallow, true), 0);
+      }
       if (last?.moving === true && event.type === "pointerup") {
         const over = columnUnder(event.clientX, event.clientY);
         if (over !== undefined && over !== last.task.state) {
@@ -506,12 +547,24 @@ export function Board(props: BoardProps) {
         );
       })}
       {dragging !== null && (
+        // The card in hand: the whole of it, as wide as where it stands, under the pointer where it was taken hold of.
         <div
           className="sc-drag-ghost"
           aria-hidden="true"
-          style={{ transform: `translate(${dragging.x + 12}px, ${dragging.y + 12}px)` }}
+          style={{
+            width: dragging.width,
+            transform: `translate(${dragging.x - dragging.grip.x}px, ${dragging.y - dragging.grip.y}px)`,
+          }}
         >
-          <span className="sc-card-number">#{dragging.task.number}</span> {dragging.task.title}
+          <TaskCard
+            task={dragging.task}
+            href={props.taskHref(dragging.task)}
+            onOpen={nothing}
+            today={props.today}
+            // The menu too, inert under the pointer, so that the card in hand keeps the shape of the one in its place.
+            editHref={props.editHref?.(dragging.task)}
+            onArchive={props.onArchive}
+          />
         </div>
       )}
     </div>

package/src/components/task-view.tsx

@@ -16,7 +16,7 @@ import type {
 import { formatDay } from "../dates.js";
 import { useLanguage, useWords } from "../i18n/index.js";
 import type { TaskFormKind } from "../router.js";
-import { OPEN_TASK_STATES, TASK_STATES } from "../vocabulary.js";
+import { TASK_STATES } from "../vocabulary.js";
 import { type CommentDraft, TaskThread } from "./comments.js";
 import { DecisionForm } from "./decision-form.js";
 import { EventFeed } from "./event-feed.js";
@@ -354,17 +354,15 @@ export function TaskView(props: TaskViewProps) {
               <a className="sc-button sc-button-secondary" href={props.formHref("ask")}>
                 {words.task.raiseDecision}
               </a>
-              {props.onArchive !== undefined &&
-                task.archivedAt === null &&
-                !OPEN_TASK_STATES.includes(task.state) && (
-                  <Button
-                    variant="secondary"
-                    disabled={props.busy === true}
-                    onClick={() => props.onArchive?.(task)}
-                  >
-                    {words.task.archive}
-                  </Button>
-                )}
+              {props.onArchive !== undefined && task.archivedAt === null && (
+                <Button
+                  variant="secondary"
+                  disabled={props.busy === true}
+                  onClick={() => props.onArchive?.(task)}
+                >
+                  {words.task.archive}
+                </Button>
+              )}
               {props.onRestore !== undefined && task.archivedAt !== null && (
                 <Button
                   variant="secondary"

package/src/console.tsx

@@ -738,7 +738,14 @@ function ProjectPage(props: {
     return (
       <>
         <div className="sc-page-head">
-          <h1 className="sc-page-title">{project.name}</h1>
+          <div className="sc-page-heading">
+            <h1 className="sc-page-title">{project.name}</h1>
+            {project.description.length > 0 && (
+              <p className="sc-page-lead" title={project.description}>
+                {project.description}
+              </p>
+            )}
+          </div>
           <div className="sc-page-actions">
             <LinkButton href={projectHref(key, "archive")}>{words.board.archive}</LinkButton>
             <LinkButton href={newTaskHref(key)} variant="primary">
@@ -746,7 +753,6 @@ function ProjectPage(props: {
             </LinkButton>
           </div>
         </div>
-        {project.description.length > 0 && <p className="sc-lead">{project.description}</p>}
         {error !== undefined && <Callout tone="danger">{error}</Callout>}
         {data.tasks.length > 0 && (
           <BoardFilters

package/src/i18n/en.ts

@@ -605,7 +605,7 @@ export const en = {
     loading: "Loading the archive",
     empty: {
       title: "Nothing is put away",
-      body: "A task done or dropped is put away from its page, with its goal, or by the console after a while.",
+      body: "A task is put away from its page or its card, with its goal once the goal is closed, or by the console a while after it was done or dropped.",
     },
     since: "put away",
     restore: "Bring back",

package/src/i18n/ko.ts

@@ -569,7 +569,7 @@ export const ko: Messages = {
     loading: "보관함을 불러오는 중",
     empty: {
       title: "보관된 작업이 없습니다",
-      body: "완료·폐기된 작업은 작업 페이지에서, 목표를 닫을 때 함께, 또는 일정 기간 뒤 콘솔이 보관합니다.",
+      body: "작업은 작업 페이지나 카드 메뉴에서, 목표를 닫을 때 함께, 또는 완료·폐기된 뒤 일정 기간이 지나면 콘솔이 보관합니다.",
     },
     since: "보관",
     restore: "되살리기",

package/src/rules.ts

@@ -23,12 +23,13 @@ export const REFERENCE_RULES = [
   "",
   "## Start here, every time",
   "",
-  "1. These rules come with the task: `console take` prints them under it, and `console rules` reads them any time. Read them before anything is made. The task says where the work is and what it links to; `console task <number>` shows a task in full, with its plan, its decisions, the runs on it and the discussion on it, without taking it. A task put away (archived) once done or dropped is out of the listings and the board, and opens by its number still. How the board is worked is the skill working-the-board, shipped with the command (`console skills` says where it is); these rules say what this organization asks, not how the command works.",
+  "1. These rules come with the task: `console take` prints them under it, and `console rules` reads them any time. Read them before anything is made. The task says where the work is and what it links to; `console task <number>` shows a task in full, with its plan, its decisions, the runs on it and the discussion on it, without taking it. A task put away (archived) is out of the listings and the board, and opens by its number still. How the board is worked is the skill working-the-board, shipped with the command: read it before the first command of a run (`console skills` prints where it is); these rules say what this organization asks, not how the command works.",
   "2. Act as the person whose token the command holds, and no further. What they may not do, the console refuses; that step goes back to them in a report, never around them.",
+  '3. Work given in chat, with no task on the board yet, goes on the board before it is done: write it (`console task new "<title>" --body <markdown>`), tell the person its number, take it (`console take <number>`) and work it as any task, without asking whether to. Until the task is written, the board is only read.',
   "",
   "## 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.