@g3nomaly/g3n-skills 0.1.0 → 0.1.2

package/skills/task-manager/task-manager/src/filetree/ensure.ts

@@ -7,15 +7,22 @@ import { listEntryNames } from "./entries";
 import { generateIndex } from "./generate";
 
 /**
- * Creates every folder and index file the tree under `root` is missing, and
+ * @brief Creates every folder and index file the tree under `root` is missing, and
  * leaves everything that already exists untouched. A hook can call this on
  * every run.
+ *
+ * @param root - Folder of the tree, made absolute before use.
  */
 export async function ensureTree(root: string): Promise<void> {
   await ensureFrom(resolve(root), "root");
 }
 
-/** `dir` is absolute; `childDirFor` keeps it that way down the walk. */
+/**
+ * @brief Creates the folders and index files of one folder and of every folder below it.
+ *
+ * @param dir - Absolute folder; `childDirFor` keeps it absolute down the walk.
+ * @param level - Level of `dir` in the tree.
+ */
 async function ensureFrom(dir: string, level: TreeLevel): Promise<void> {
   await mkdir(dir, { recursive: true });
   if (level === "phase") await mkdir(tasksDirFor(dir), { recursive: true });
@@ -30,7 +37,12 @@ async function ensureFrom(dir: string, level: TreeLevel): Promise<void> {
   }
 }
 
-/** Builds a missing index from the folder it belongs to; keeps an existing one. */
+/**
+ * @brief Builds a missing index from the folder it belongs to; keeps an existing one.
+ *
+ * @param dir - Folder the index belongs to.
+ * @param level - Level of `dir` in the tree.
+ */
 async function ensureIndexFile(dir: string, level: TreeLevel): Promise<void> {
   const exists = await Bun.file(indexPathFor(dir, level)).exists();
   if (exists) return;

package/skills/task-manager/task-manager/src/filetree/entries.ts

@@ -4,10 +4,14 @@ import { ENTRY_KIND, MARKDOWN, type TreeLevel } from "./levels";
 import { entryPathFor, tasksDirFor } from "./paths";
 
 /**
- * Names of the entries of a folder at `level`, alphabetical — the order the
- * queue runs in. A folder only counts as an entry once it holds its own
- * `<name>.md`, so a directory left behind by hand is skipped rather than
- * reported as a broken plan.
+ * @brief Lists the entries of a folder at `level`, alphabetical, which is the order the queue runs in.
+ *
+ * A folder only counts as an entry once it holds its own `<name>.md`, so a
+ * directory left behind by hand is skipped rather than reported as a broken plan.
+ *
+ * @param dir - Folder whose entries are listed.
+ * @param level - Level of `dir` in the tree.
+ * @returns Entry names, sorted.
  */
 export async function listEntryNames(dir: string, level: TreeLevel): Promise<string[]> {
   const names = ENTRY_KIND[level] === "folder"
@@ -17,6 +21,12 @@ export async function listEntryNames(dir: string, level: TreeLevel): Promise<str
   return names.sort((a, b) => a.localeCompare(b));
 }
 
+/**
+ * @brief Lists the subfolders of `dir` that hold their own `<name>.md`.
+ *
+ * @param dir - Folder whose subfolders are checked.
+ * @param level - Level of `dir`, which picks the file each subfolder must hold.
+ */
 async function listFolderEntries(dir: string, level: TreeLevel): Promise<string[]> {
   const names: string[] = [];
 
@@ -30,7 +40,13 @@ async function listFolderEntries(dir: string, level: TreeLevel): Promise<string[
   return names;
 }
 
-/** A phase with no `tasks/` folder yet has no tasks, which is not an error. */
+/**
+ * @brief Lists the task ids of a phase, from the `.md` files in its `tasks/` folder.
+ *
+ * A phase with no `tasks/` folder yet has no tasks, which is not an error.
+ *
+ * @param phaseDir - Phase folder.
+ */
 async function listTaskEntries(phaseDir: string): Promise<string[]> {
   let files;
 
@@ -46,6 +62,11 @@ async function listTaskEntries(phaseDir: string): Promise<string[]> {
     .map((entry) => entry.name.slice(0, -MARKDOWN.length));
 }
 
+/**
+ * @brief Checks whether an error is a missing file or folder (`ENOENT`).
+ *
+ * @param error - Caught value.
+ */
 function isMissing(error: unknown): boolean {
   return (
     typeof error === "object" &&

package/skills/task-manager/task-manager/src/filetree/frontmatter.ts

@@ -3,18 +3,24 @@ import { FileValidationError } from "../schemas/validation";
 
 const FENCE = "---";
 
-/** A `.md` file split at its closing fence. */
+/**
+ * @brief Holds a `.md` file split at its closing fence.
+ *
+ * @property frontmatter - Mapping read from the block between the fences, not yet validated.
+ * @property body - Everything after the closing fence, leading blank lines trimmed.
+ */
 export interface Document {
   frontmatter: unknown;
-  /** Everything after the closing fence, leading blank lines trimmed. */
   body: string;
 }
 
 /**
- * Reads a `.md` file as its frontmatter mapping plus the prose under it.
+ * @brief Reads a `.md` file as its frontmatter mapping plus the prose under it.
  *
- * @throws FileValidationError when the file has no frontmatter block or the
- *   block is not a YAML mapping
+ * @param file - Path of the `.md` file.
+ * @returns The frontmatter mapping and the body.
+ * @throws {FileValidationError} When the file has no frontmatter block or the
+ *   block is not a YAML mapping.
  */
 export async function readDocument(file: string): Promise<Document> {
   const text = await Bun.file(file).text();
@@ -37,12 +43,22 @@ export async function readDocument(file: string): Promise<Document> {
   return { frontmatter, body: split.body };
 }
 
-/** Reads only the frontmatter mapping of a `.md` file. */
+/**
+ * @brief Reads only the frontmatter mapping of a `.md` file.
+ *
+ * @param file - Path of the `.md` file.
+ * @returns The frontmatter mapping, not yet validated.
+ */
 export async function readFrontmatter(file: string): Promise<unknown> {
   return (await readDocument(file)).frontmatter;
 }
 
-/** Text inside the fences and text after them, or `null` when there are none. */
+/**
+ * @brief Splits a file's text at its closing fence.
+ *
+ * @param text - Whole file text.
+ * @returns The text between the fences and the text after them, or `null` when the fences are missing.
+ */
 function splitAtFences(text: string): { block: string; body: string } | null {
   const lines = text.split("\n");
 

package/skills/task-manager/task-manager/src/filetree/generate.ts

@@ -11,12 +11,14 @@ import { listEntryNames } from "./entries";
 import { readEntry, type EntryOf } from "./read";
 
 /**
- * Rebuilds one folder's index from the entries directly under it, replacing
+ * @brief Rebuilds one folder's index from the entries directly under it, replacing
  * whatever was there. Plans and phases are read from `<name>/<name>.md`, tasks
  * from `tasks/<id>.md`, so the result only depends on that one folder.
  *
- * @throws FileValidationError when an entry fails its schema or its identifier
- *   does not match the folder or file it was read from
+ * @param dir - Folder whose index is rebuilt.
+ * @param level - Level of `dir` in the tree.
+ * @throws {FileValidationError} When an entry fails its schema or its identifier
+ *   does not match the folder or file it was read from.
  */
 export async function generateIndex(dir: string, level: TreeLevel): Promise<void> {
   switch (level) {
@@ -33,14 +35,22 @@ export async function generateIndex(dir: string, level: TreeLevel): Promise<void
 }
 
 /**
- * Rebuilds every index in the tree, from the root folder down.
+ * @brief Rebuilds every index in the tree, from the root folder down.
+ *
  * Run `ensureTree` first — a plan or phase without its folder throws here.
+ *
+ * @param root - Tree root folder.
  */
 export async function generateTree(root: string): Promise<void> {
   await generateFrom(resolve(root), "root");
 }
 
-/** `dir` is absolute; `childDirFor` keeps it that way down the walk. */
+/**
+ * @brief Rebuilds the index of one folder and of every folder below it.
+ *
+ * @param dir - Absolute folder; `childDirFor` keeps it absolute down the walk.
+ * @param level - Level of `dir` in the tree.
+ */
 async function generateFrom(dir: string, level: TreeLevel): Promise<void> {
   await generateIndex(dir, level);
 
@@ -52,7 +62,13 @@ async function generateFrom(dir: string, level: TreeLevel): Promise<void> {
   }
 }
 
-/** Reads and validates every entry of `dir`, in queue order. */
+/**
+ * @brief Reads and validates every entry of `dir`, in queue order.
+ *
+ * @param dir - Folder whose entries are read.
+ * @param level - Level of `dir` in the tree.
+ * @returns The validated fields, one per entry.
+ */
 async function collect<L extends TreeLevel>(dir: string, level: L): Promise<EntryOf<L>[]> {
   const entries: EntryOf<L>[] = [];
 
@@ -63,6 +79,15 @@ async function collect<L extends TreeLevel>(dir: string, level: L): Promise<Entr
   return entries;
 }
 
+/**
+ * @brief Validates an index against its schema and writes it to the folder's index file.
+ *
+ * @param dir - Folder the index belongs to.
+ * @param level - Level of `dir` in the tree.
+ * @param schema - Zod schema the index must match.
+ * @param index - Index contents, before validation.
+ * @throws {FileValidationError} When the index fails `schema`.
+ */
 async function writeIndex<S extends z.ZodType>(
   dir: string,
   level: TreeLevel,

package/skills/task-manager/task-manager/src/filetree/levels.ts

@@ -7,6 +7,7 @@
  */
 export const LEVELS = ["root", "plan", "phase"] as const;
 
+/** Name of one depth of the tree, one of `LEVELS`. */
 export type TreeLevel = (typeof LEVELS)[number];
 
 /** Index file each level writes, in the folder whose entries it lists. */

package/skills/task-manager/task-manager/src/filetree/locate.ts

@@ -4,28 +4,42 @@ import { CHILD_LEVEL, ENTRY_TYPE, type TreeLevel } from "./levels";
 import { childDirFor, entryPathFor } from "./paths";
 import { listEntryNames } from "./entries";
 
-/** Where one entry sits, from the folder that lists it. */
+/**
+ * @brief Holds where one entry sits, from the folder that lists it.
+ *
+ * @property level - Level of `dir`, the folder whose index lists this entry.
+ * @property type - What this entry is: a `root` folder lists plans, a `phase` folder tasks.
+ * @property name - Folder name for a plan or phase, task id for a task.
+ * @property dir - Folder whose index lists this entry.
+ * @property file - Path of the entry's `.md` file.
+ * @property trail - Names from the tree root down to and including this entry.
+ */
 export interface EntryLocation {
-  /** Level of `dir` — the folder whose index lists this entry. */
   level: TreeLevel;
-  /** What this entry is: a `root` folder lists plans, a `phase` folder tasks. */
   type: "plan" | "phase" | "task";
   name: string;
   dir: string;
   file: string;
-  /** Names from the tree root down to and including this entry. */
   trail: string[];
 }
 
-/** Where a folder's entries are listed, and at which level. */
+/**
+ * @brief Holds where a folder's entries are listed, and at which level.
+ *
+ * @property dir - Folder holding the entries.
+ * @property level - Level of `dir` in the tree.
+ */
 export interface ParentFolder {
   dir: string;
   level: TreeLevel;
 }
 
 /**
- * Every entry in the tree, in the order the queue runs: each folder's entries
+ * @brief Lists every entry in the tree, in the order the queue runs: each folder's entries
  * alphabetically, and each entry's own entries directly after it.
+ *
+ * @param root - Tree root folder.
+ * @returns Every entry's location.
  */
 export async function listAllEntries(root: string): Promise<EntryLocation[]> {
   const found: EntryLocation[] = [];
@@ -33,6 +47,14 @@ export async function listAllEntries(root: string): Promise<EntryLocation[]> {
   return found;
 }
 
+/**
+ * @brief Adds the entries of one folder to `found`, each followed by its own entries.
+ *
+ * @param dir - Folder whose entries are added.
+ * @param level - Level of `dir` in the tree.
+ * @param trail - Names from the tree root down to `dir`.
+ * @param found - List the entries are appended to.
+ */
 async function collectFrom(
   dir: string,
   level: TreeLevel,
@@ -58,10 +80,13 @@ async function collectFrom(
 }
 
 /**
- * Finds the one entry named `name` anywhere in the tree.
+ * @brief Finds the one entry named `name` anywhere in the tree.
  *
- * @throws Error when nothing is named `name`, or when two entries are — a name
- *   the caller cannot act on is reported rather than resolved by guessing
+ * @param root - Tree root folder.
+ * @param name - Name to look for.
+ * @returns The entry's location.
+ * @throws {Error} When nothing is named `name`, or when two entries are — a name
+ *   the caller cannot act on is reported rather than resolved by guessing.
  */
 export async function locateEntry(root: string, name: string): Promise<EntryLocation> {
   const matches = (await listAllEntries(root)).filter((entry) => entry.name === name);
@@ -80,10 +105,14 @@ export async function locateEntry(root: string, name: string): Promise<EntryLoca
 }
 
 /**
- * `locateEntry` for a caller that only accepts one kind of entry, such as a
+ * @brief `locateEntry` for a caller that only accepts one kind of entry, such as a
  * hook whose `--in` must name a plan.
  *
- * @throws Error when the entry named `name` is of another type
+ * @param root - Tree root folder.
+ * @param name - Name of the entry.
+ * @param type - Kind the entry must be: `plan`, `phase` or `task`.
+ * @returns The entry's location.
+ * @throws {Error} When the entry named `name` is of another type.
  */
 export async function locateEntryOfType(
   root: string,
@@ -100,9 +129,12 @@ export async function locateEntryOfType(
 }
 
 /**
- * Folder whose entries `parent` holds, or the tree root when no parent is named.
+ * @brief Finds the folder whose entries `parent` holds, or the tree root when no parent is named.
  *
- * @param parent name of a plan or phase; a task holds nothing
+ * @param root - Tree root folder.
+ * @param parent - Name of a plan or phase; a task holds nothing.
+ * @returns The folder and the level of its entries.
+ * @throws {Error} When `parent` names no entry, or names a task.
  */
 export async function resolveParent(root: string, parent?: string): Promise<ParentFolder> {
   if (parent === undefined) return { dir: resolve(root), level: "root" };

package/skills/task-manager/task-manager/src/filetree/paths.ts

@@ -2,22 +2,42 @@
 import { join, relative, resolve, sep } from "node:path";
 import { ENTRY_KIND, INDEX_FILES, LEVELS, MARKDOWN, TASKS_DIR, type TreeLevel } from "./levels";
 
-/** Path of the index file a folder at `level` owns. */
+/**
+ * @brief Builds the path of the index file a folder at `level` owns.
+ *
+ * @param dir - Folder the index belongs to.
+ * @param level - Level of `dir` in the tree.
+ */
 export function indexPathFor(dir: string, level: TreeLevel): string {
   return join(dir, INDEX_FILES[level]);
 }
 
-/** Folder owned by a `folder` entry — holds its own file and the level below it. */
+/**
+ * @brief Finds the folder a `folder` entry owns, which holds its own file and the level below it.
+ *
+ * @param dir - Folder that lists the entry.
+ * @param entryName - Name of the entry.
+ */
 export function childDirFor(dir: string, entryName: string): string {
   return join(dir, entryName);
 }
 
-/** Folder holding a phase's task files. */
+/**
+ * @brief Finds the `tasks/` folder that holds a phase's task files.
+ *
+ * @param phaseDir - Phase folder.
+ */
 export function tasksDirFor(phaseDir: string): string {
   return join(phaseDir, TASKS_DIR);
 }
 
-/** Path of the `.md` file describing one entry of a folder at `level`. */
+/**
+ * @brief Builds the path of the `.md` file that describes one entry of a folder at `level`.
+ *
+ * @param dir - Folder that lists the entry.
+ * @param level - Level of `dir` in the tree.
+ * @param entryName - Name of the entry.
+ */
 export function entryPathFor(dir: string, level: TreeLevel, entryName: string): string {
   return ENTRY_KIND[level] === "folder"
     ? join(dir, entryName, `${entryName}${MARKDOWN}`)
@@ -25,8 +45,12 @@ export function entryPathFor(dir: string, level: TreeLevel, entryName: string):
 }
 
 /**
- * Level of `dir` given the tree it belongs to, from how deep it sits under
- * `root`. Throws when `dir` sits outside `root` or below a phase folder.
+ * @brief Finds the level of `dir` from how deep it sits under `root`.
+ *
+ * @param root - Tree root folder.
+ * @param dir - Folder whose level is found.
+ * @returns The level of `dir`.
+ * @throws {Error} When `dir` sits outside `root` or below a phase folder.
  */
 export function levelFor(root: string, dir: string): TreeLevel {
   const rel = relative(resolve(root), resolve(dir));

package/skills/task-manager/task-manager/src/filetree/read.ts

@@ -7,10 +7,16 @@ import { ID_FIELD, type TreeLevel } from "./levels";
 import { entryPathFor } from "./paths";
 import { readDocument } from "./frontmatter";
 
-/** Entry a folder at `L` holds — a root folder holds plans, a plan folder phases. */
+/** Names the entry type a folder at level `L` holds: `Plan` under the root, `Phase` under a plan, `Task` otherwise. */
 export type EntryOf<L extends TreeLevel> = L extends "root" ? Plan : L extends "plan" ? Phase : Task;
 
-/** One entry as it sits on disk: where it was read from, its fields, its prose. */
+/**
+ * @brief Holds one entry as it sits on disk: where it was read from, its fields, its prose.
+ *
+ * @property file - Path of the entry's `.md` file.
+ * @property meta - Fields from the frontmatter, checked against the schema of its level.
+ * @property body - Prose after the closing fence of the frontmatter.
+ */
 export interface EntryDocument<L extends TreeLevel> {
   file: string;
   meta: EntryOf<L>;
@@ -24,13 +30,15 @@ const SCHEMAS = {
 } as const;
 
 /**
- * Reads one entry of a folder at `level` and checks it against its schema.
+ * @brief Reads one entry of a folder at `level` and checks it against its schema.
  * Every read of a plan, phase or task file goes through here.
  *
- * @param dir folder whose index lists the entry
- * @param name folder name for a plan or phase, task id for a task
- * @throws FileValidationError when a field fails its schema, or when the
- *   identifier inside the file disagrees with the folder or file it was read from
+ * @param dir - Folder whose index lists the entry.
+ * @param level - Level of `dir` in the tree, which picks the schema.
+ * @param name - Folder name for a plan or phase, task id for a task.
+ * @returns The entry's path, its validated fields and its prose.
+ * @throws {FileValidationError} When a field fails its schema, or when the
+ *   identifier inside the file disagrees with the folder or file it was read from.
  */
 export async function readEntry<L extends TreeLevel>(
   dir: string,

package/skills/task-manager/task-manager/src/filetree/remove.ts

@@ -5,10 +5,13 @@ import { childDirFor } from "./paths";
 import type { EntryLocation } from "./locate";
 
 /**
- * Deletes an entry — a task's `.md` file, or a plan or phase folder with
- * everything under it. Removing something already gone is not an error, so a
- * plan and a phase inside it can both be handed in. Regenerate the tree
- * afterwards.
+ * @brief Deletes an entry — a task's `.md` file, or a plan or phase folder with
+ * everything under it.
+ *
+ * Removing something already gone is not an error, so a plan and a phase inside
+ * it can both be handed in. Regenerate the tree afterwards.
+ *
+ * @param entry - Location of the entry to delete.
  */
 export async function removeEntry(entry: EntryLocation): Promise<void> {
   const target = ENTRY_KIND[entry.level] === "folder"

package/skills/task-manager/task-manager/src/filetree/root.ts

@@ -4,12 +4,13 @@ import { CONFIG_FILE, FiletreeConfigSchema } from "../schemas/config";
 import { FileValidationError, parseFile } from "../schemas/validation";
 
 /**
- * Absolute path of the tree, from `skills.settings.filetreeRoot` in
+ * @brief Finds the absolute path of the tree, from `skills.settings.filetreeRoot` in
  * `.g3n.config.json`. Falls back to `docs/task-manager` when the project has
  * no config file or the file does not set it.
  *
- * @param projectRoot - Folder holding `.g3n.config.json`
- * @throws FileValidationError when the config file is not JSON or sets a root that is not a string
+ * @param projectRoot - Folder holding `.g3n.config.json`.
+ * @returns Absolute path of the tree.
+ * @throws {FileValidationError} When the config file is not JSON or sets a root that is not a string.
  */
 export async function resolveFiletreeRoot(projectRoot: string): Promise<string> {
   const path = join(projectRoot, CONFIG_FILE);

package/skills/task-manager/task-manager/src/filetree/status.ts

@@ -6,26 +6,40 @@ import { FileValidationError } from "../schemas/validation";
 const FENCE = "---";
 const STATUS_LINE = /^(status:\s*)(\S+)(\s*)$/;
 
-/** What a status change did, for a caller that reports it. */
+/**
+ * @brief Holds the status an entry moved from and to, for a caller that reports the change.
+ *
+ * @property from - Status before the change.
+ * @property to - Status after the change.
+ */
 export interface StatusChange<T extends string = TaskStatus> {
   from: T;
   to: T;
 }
 
-/** `setStatusLine` for a plan, phase or task file. */
+/**
+ * @brief Sets the status of a plan, phase or task file.
+ *
+ * @param file - Path of the entry's `.md` file.
+ * @param to - Status to write.
+ * @returns The status the file had and the one it has now.
+ */
 export async function setEntryStatus(file: string, to: TaskStatus): Promise<StatusChange> {
   return setStatusLine(file, to, StatusSchema);
 }
 
 /**
- * Rewrites the `status:` line in a file's frontmatter and leaves every other
+ * @brief Rewrites the `status:` line in a file's frontmatter and leaves every other
  * byte alone, so comments, key order and quoting survive the change. Regenerate
  * the owning index afterwards — this touches the `.md` file only.
  *
- * @param schema the set of statuses the file may hold
- * @throws FileValidationError when the frontmatter has no `status:` line, or
- *   holds a status outside `schema`
- * @throws Error when the file already has status `to`
+ * @param file - Path of the `.md` file.
+ * @param to - Status to write.
+ * @param schema - Zod schema of the statuses the file may hold.
+ * @returns The status the file had and the one it has now.
+ * @throws {FileValidationError} When the frontmatter has no `status:` line, or
+ *   holds a status outside `schema`.
+ * @throws {Error} When the file already has status `to`.
  */
 export async function setStatusLine<T extends string>(
   file: string,
@@ -58,6 +72,14 @@ export async function setStatusLine<T extends string>(
   ]);
 }
 
+/**
+ * @brief Finds the line of the closing fence of a file's frontmatter.
+ *
+ * @param lines - Lines of the file.
+ * @param file - Path of the file, reported in the error.
+ * @returns Index of the closing fence line.
+ * @throws {FileValidationError} When the file has no opening fence or no closing one.
+ */
 function closingFenceAt(lines: readonly string[], file: string): number {
   if (lines[0]?.trimEnd() !== FENCE) {
     throw new FileValidationError(file, [

package/skills/task-manager/task-manager/src/hooks/cli.ts

@@ -2,10 +2,17 @@
 import { resolve } from "node:path";
 import { resolveFiletreeRoot } from "../filetree/root";
 
-/** One hook as `g3n-skills hook <name>` runs it: the flags after the name, untouched. */
+/** Entry point of one hook, as `g3n-skills hook <name>` calls it; receives the flags after the name, untouched. */
 export type Hook = (argv: readonly string[]) => Promise<void>;
 
-/** Value of `--flag <value>`, or `undefined` when the flag is absent. */
+/**
+ * @brief Reads the value that follows a flag in the arguments.
+ *
+ * @param argv - Arguments of the hook, e.g. `["--term", "phase"]`.
+ * @param flag - Flag to look up, with its dashes, e.g. `--term`.
+ * @returns Value after the flag, or `undefined` when the flag is absent.
+ * @throws Error when the flag is last or followed by another flag.
+ */
 export function readFlag(argv: readonly string[], flag: string): string | undefined {
   const at = argv.indexOf(flag);
   if (at === -1) return undefined;
@@ -18,7 +25,15 @@ export function readFlag(argv: readonly string[], flag: string): string | undefi
   return value;
 }
 
-/** Value of `--flag <value>`, or a stated failure when it is missing. */
+/**
+ * @brief Reads the value of a required flag.
+ *
+ * @param argv - Arguments of the hook.
+ * @param flag - Flag to look up, with its dashes, e.g. `--term`.
+ * @param example - Value shown in the error when the flag is missing, e.g. `phase`.
+ * @returns Value after the flag.
+ * @throws Error naming the flag and the example when it is missing.
+ */
 export function requireFlag(argv: readonly string[], flag: string, example: string): string {
   const value = readFlag(argv, flag);
   if (value === undefined) {
@@ -28,14 +43,24 @@ export function requireFlag(argv: readonly string[], flag: string, example: stri
   return value;
 }
 
+/**
+ * @brief Tells whether a flag appears in the arguments.
+ *
+ * @param argv - Arguments of the hook.
+ * @param flag - Flag to look for, with its dashes.
+ */
 export function hasFlag(argv: readonly string[], flag: string): boolean {
   return argv.includes(flag);
 }
 
 /**
- * Narrows a flag value to one of a fixed set, naming the whole set when it is
- * not one of them. A schema would report the same rejection as parser output,
- * which is not what a caller reading stderr can act on.
+ * @brief Narrows a flag value to one of a fixed set.
+ *
+ * @param value - Raw flag value.
+ * @param allowed - Accepted values.
+ * @param flag - Flag name used in the error message.
+ * @returns The value, typed as one of `allowed`.
+ * @throws Error naming every allowed value when `value` is not one of them.
  */
 export function oneOf<T extends string>(value: string, allowed: readonly T[], flag: string): T {
   if ((allowed as readonly string[]).includes(value)) return value as T;
@@ -44,9 +69,14 @@ export function oneOf<T extends string>(value: string, allowed: readonly T[], fl
 }
 
 /**
- * Tree root the script works on: `--root` verbatim, otherwise the folder named
- * by `skills.settings.filetreeRoot` under `--project` (default: the working
+ * @brief Resolves the tree root the hook works on.
+ *
+ * Uses `--root` verbatim, otherwise the folder named by
+ * `skills.settings.filetreeRoot` under `--project` (default: the working
  * directory).
+ *
+ * @param argv - Arguments of the hook.
+ * @returns Absolute tree root.
  */
 export async function resolveRoot(argv: readonly string[]): Promise<string> {
   const override = readFlag(argv, "--root");
@@ -55,19 +85,27 @@ export async function resolveRoot(argv: readonly string[]): Promise<string> {
   return resolveFiletreeRoot(resolve(readFlag(argv, "--project") ?? process.cwd()));
 }
 
-/** Everything piped to the hook on stdin, or `""` when it was run from a terminal. */
+/** Reads everything piped to the hook on stdin, or returns `""` when run from a terminal. */
 export async function readStdin(): Promise<string> {
   return process.stdin.isTTY ? "" : Bun.stdin.text();
 }
 
-/** The only thing a script writes to stdout. */
+/**
+ * @brief Prints a value as JSON on stdout, indented when `--pretty` is given.
+ *
+ * @param value - Value to print; must be JSON-serializable.
+ * @param argv - Arguments of the hook, checked for `--pretty`.
+ */
 export function printJson(value: unknown, argv: readonly string[]): void {
   console.log(JSON.stringify(value, null, hasFlag(argv, "--pretty") ? 2 : 0));
 }
 
 /**
- * Runs a script's `main` and turns anything thrown into a message on stderr and
- * a non-zero exit, so no rejection escapes as a stack trace.
+ * @brief Runs a hook's `main` and reports anything it throws.
+ *
+ * Writes the error message to stderr and exits with code 1.
+ *
+ * @param main - Async entry point of the hook.
  */
 export function runHook(main: () => Promise<void>): void {
   main().catch((error: unknown) => {