agents.yaml 0.1.0 → 0.2.1

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 This package provides the `agents` CLI for maintaining an `agents.yaml` file.
 
-`agents.yaml` is a curated table of contents for active agent-readable documentation. It does not define a new instruction language, replace `AGENTS.md`, or automatically load every dependency document.
+`agents.yaml` is a curated table of contents for promoted agent-readable documentation. It does not define a new instruction language, replace `AGENTS.md`, or automatically load every dependency document.
 
 The file format is intentionally small:
 
@@ -11,9 +11,10 @@ version: 1
 
 documents:
   - path: ./node_modules/example-package/AGENTS.md
+    description: Useful package context from example-package's package.json.
 ```
 
-Agents should treat only the paths listed in `documents` as active supplemental guidance for the project.
+Agents should treat paths listed in `documents` as promoted supplemental guidance for the project. Descriptions are human-readable breadcrumbs that explain why the package guidance may be relevant; they are not additional instructions.
 
 The CLI can help discover package and local `AGENTS.md` files, add selected paths to `agents.yaml`, remove paths, initialize the root breadcrumb, and validate that referenced files still exist.
 

package/README.md

@@ -30,12 +30,13 @@ version: 1
 
 documents:
   - path: ./node_modules/react/AGENTS.md
+    description: React is a JavaScript library for building user interfaces.
 ```
 
+Descriptions are optional breadcrumbs, usually copied from the package's `package.json`, that make lesser-known package guidance easier to recognize at a glance. Only `path` activates a supplemental guidance document.
+
 Add this breadcrumb to your root `AGENTS.md`:
 
 ```md
-For dependency-specific and supplemental guidance, consult `./agents.yaml`.
-
-Only the documents listed there should be considered active external guidance for this project.
+Consult `./agents.yaml` when working with outside dependencies.
 ```

package/dist/index.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
+import { MultiSelectPrompt } from "@clack/core";
 import * as clack from "@clack/prompts";
+import { styleText } from "node:util";
 import { access, opendir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import * as YAML from "yaml";
@@ -20,11 +22,12 @@ function formatProjectPath(root, target) {
 //#region src/agents-file.ts
 const fileSchema = z.object({
 	version: z.literal(1),
-	documents: z.array(z.object({ path: z.string().min(1) }))
+	documents: z.array(z.object({
+		path: z.string().min(1),
+		description: z.string().min(1).optional()
+	}))
 });
-const breadcrumb = `For dependency-specific and supplemental guidance, consult \`./agents.yaml\`.
-
-Only the documents listed there should be considered active external guidance for this project.`;
+const breadcrumb = `Consult \`./agents.yaml\` when working with outside dependencies.`;
 async function loadAgentsFile(root) {
 	const filePath = agentsPath(root);
 	try {
@@ -43,14 +46,24 @@ async function loadAgentsFile(root) {
 async function saveAgentsFile(root, file) {
 	const normalized = {
 		version: file.version,
-		documents: file.documents.map((doc) => ({ path: doc.path }))
+		documents: file.documents.map((doc) => ({
+			path: doc.path,
+			...doc.description ? { description: doc.description } : {}
+		}))
 	};
 	await writeFile(agentsPath(root), YAML.stringify(normalized, { lineWidth: 0 }), "utf8");
 }
 async function addDocuments(root, documents) {
 	const file = await loadAgentsFile(root);
 	const byPath = new Map(file.documents.map((doc) => [doc.path, doc]));
-	for (const document of documents) byPath.set(document.path, document);
+	for (const document of documents) {
+		const existing = byPath.get(document.path);
+		byPath.set(document.path, {
+			path: document.path,
+			...existing?.description ? { description: existing.description } : {},
+			...document.description ? { description: document.description } : {}
+		});
+	}
 	const next = {
 		version: 1,
 		documents: [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path))
@@ -166,6 +179,10 @@ async function discoverAgentDocuments(root) {
 	await walk(root, root, found);
 	return found.filter((document) => document.path !== "./AGENTS.md").sort((left, right) => left.path.localeCompare(right.path));
 }
+async function describeAgentDocument(root, agentsDocumentPath) {
+	const absolutePath = resolveFromRoot(root, agentsDocumentPath);
+	return documentEntry(root, absolutePath, await readPackageDescription(path.dirname(absolutePath)));
+}
 async function walk(root, directory, found) {
 	let handle;
 	try {
@@ -183,7 +200,7 @@ async function walk(root, directory, found) {
 			if (!skippedDirectories.has(entry.name)) await walk(root, absolutePath, found);
 			continue;
 		}
-		if (entry.isFile() && entry.name === "AGENTS.md") found.push({ path: formatProjectPath(root, absolutePath) });
+		if (entry.isFile() && entry.name === "AGENTS.md") found.push(await documentEntry(root, absolutePath, await readPackageDescription(path.dirname(absolutePath))));
 	}
 }
 async function scanDirectNodeModules(root, nodeModulesPath, found) {
@@ -216,9 +233,29 @@ async function addPackageAgentsDocument(root, packagePath, found) {
 	const agentsPath = path.join(packagePath, "AGENTS.md");
 	try {
 		await access(agentsPath);
-		found.push({ path: formatProjectPath(root, agentsPath) });
+		found.push(await documentEntry(root, agentsPath, await readPackageDescription(packagePath)));
 	} catch {}
 }
+async function documentEntry(root, agentsPath, description) {
+	return {
+		path: formatProjectPath(root, agentsPath),
+		...description ? { description } : {}
+	};
+}
+async function readPackageDescription(packagePath) {
+	try {
+		const source = await readFile(path.join(packagePath, "package.json"), "utf8");
+		const parsed = JSON.parse(source);
+		if (!isPackageJson(parsed) || typeof parsed.description !== "string") return void 0;
+		const description = parsed.description.trim();
+		return description && description.length > 0 ? description : void 0;
+	} catch {
+		return;
+	}
+}
+function isPackageJson(value) {
+	return typeof value === "object" && value !== null;
+}
 //#endregion
 //#region src/run.ts
 const helpText = `agents
@@ -231,7 +268,7 @@ Usage:
   agents remove <path...>
   agents validate [--json]
 
-agents.yaml is a curated table of contents for active external AGENTS.md guidance.`;
+agents.yaml is a curated table of contents for promoted AGENTS.md guidance.`;
 async function run(argv) {
 	const parsed = parseArgs(argv);
 	const root = cwd();
@@ -327,23 +364,26 @@ async function commandDiscover(root, json) {
 		clack.outro("No supplemental AGENTS.md files found.");
 		return;
 	}
-	clack.note(documents.map((doc) => doc.path).join("\n"), `Found ${documents.length}`);
+	clack.note(formatDocumentList(documents), `Found ${documents.length}`);
 	clack.outro("Use agents add <path> to enable one.");
 }
 async function commandAdd(root, paths) {
 	if (paths.length === 0) throw new Error("add requires at least one AGENTS.md path");
-	const documents = paths.map((path) => ({ path: formatProjectPath(root, resolveFromRoot(root, path)) }));
+	const documents = await Promise.all(paths.map((path) => describeAgentDocument(root, formatProjectPath(root, resolveFromRoot(root, path)))));
 	const file = await addDocuments(root, documents);
 	clack.intro("agents add");
-	clack.note(file.documents.map((doc) => doc.path).join("\n"), "Active documents");
+	clack.note(formatDocumentList(file.documents), "Promoted documents");
 	clack.outro(`Added ${documents.length} document${documents.length === 1 ? "" : "s"}.`);
 }
+function formatDocumentList(documents) {
+	return documents.map((doc) => doc.description ? `${doc.path}\n  ${doc.description}` : doc.path).join("\n");
+}
 async function commandRemove(root, paths) {
 	if (paths.length === 0) throw new Error("remove requires at least one path");
 	const result = await removeDocuments(root, paths.map((path) => formatProjectPath(root, resolveFromRoot(root, path))));
 	clack.intro("agents remove");
-	clack.note(result.removed.join("\n") || "No matching documents were active.", "Removed");
-	clack.outro(`agents.yaml now has ${result.file.documents.length} active document${result.file.documents.length === 1 ? "" : "s"}.`);
+	clack.note(result.removed.join("\n") || "No matching documents were listed.", "Removed");
+	clack.outro(`agents.yaml now has ${result.file.documents.length} promoted document${result.file.documents.length === 1 ? "" : "s"}.`);
 }
 async function commandValidate(root, json) {
 	const result = await validateAgentsFile(root);
@@ -391,23 +431,48 @@ async function interactive(root) {
 	const existing = await loadAgentsFile(root);
 	const candidates = (await discoverAgentDocuments(root)).filter((doc) => !existing.documents.some((active) => active.path === doc.path));
 	if (candidates.length === 0) {
-		clack.outro("No inactive supplemental AGENTS.md files found.");
+		clack.outro("No unlisted supplemental AGENTS.md files found.");
 		return;
 	}
-	const selected = await clack.multiselect({
-		message: "Choose documents to enable",
-		options: candidates.map((doc) => ({
-			value: doc.path,
-			label: doc.path
-		})),
-		required: false
-	});
-	if (clack.isCancel(selected) || selected.length === 0) {
+	const selected = await chooseDocumentsToEnable(candidates.map((doc) => ({
+		value: doc.path,
+		label: doc.path
+	})));
+	if (clack.isCancel(selected) || selected === void 0 || selected.length === 0) {
 		clack.cancel("No documents selected.");
 		return;
 	}
 	await commandAdd(root, selected);
 }
+function chooseDocumentsToEnable(options) {
+	return new MultiSelectPrompt({
+		options,
+		required: false,
+		render() {
+			const prefix = `${styleText("cyan", clack.S_BAR)}  `;
+			const selected = this.value ?? [];
+			return `${styleText("gray", clack.S_BAR)}
+${clack.symbol(this.state)}  Choose documents to enable
+${prefix}${clack.limitOptions({
+				options: this.options,
+				cursor: this.cursor,
+				columnPadding: prefix.length,
+				style: (option, active) => styleDocumentOption(option, {
+					active,
+					selected: selected.includes(option.value)
+				})
+			}).join(`
+${prefix}`)}
+${styleText("cyan", clack.S_BAR_END)}
+`;
+		}
+	}).prompt();
+}
+function styleDocumentOption(option, state) {
+	if (option.disabled) return `${styleText("gray", clack.S_CHECKBOX_INACTIVE)} ${styleText(["strikethrough", "gray"], option.label)}`;
+	const checkbox = state.selected ? styleText("green", clack.S_CHECKBOX_SELECTED) : state.active ? styleText("cyan", clack.S_CHECKBOX_ACTIVE) : styleText("dim", clack.S_CHECKBOX_INACTIVE);
+	return `${state.active ? styleText("cyan", ">") : " "} ${checkbox} ${state.active ? option.label : styleText("dim", option.label)}`;
+}
 //#endregion
 //#region src/index.ts
 run(process.argv.slice(2)).catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents.yaml",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A CLI for discovering and curating agent-readable documentation in agents.yaml.",
   "repository": {
     "type": "git",
@@ -16,25 +16,23 @@
     "AGENTS.md"
   ],
   "type": "module",
-  "scripts": {
-    "build": "tsdown",
-    "dev": "src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "check": "tsc --noEmit && tsdown"
-  },
   "dependencies": {
+    "@clack/core": "1.4.1",
     "@clack/prompts": "1.5.1",
     "yaml": "2.9.0",
     "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/node": "25.9.2",
-    "tsdown": "0.22.2",
     "typescript": "6.0.3"
   },
   "engines": {
     "node": "26.3.0",
     "pnpm": "11.5.2"
   },
-  "packageManager": "pnpm@11.5.2"
-}
+  "scripts": {
+    "build": "vp pack",
+    "dev": "src/index.ts",
+    "test": "vp test"
+  }
+}

package/src/agents-file.ts

@@ -1,201 +1,224 @@
-import { access, readFile, writeFile } from 'node:fs/promises'
-import path from 'node:path'
-import * as YAML from 'yaml'
-import { z } from 'zod'
-import { resolveFromRoot } from './paths.ts'
+import { access, readFile, writeFile } from "node:fs/promises"
+import path from "node:path"
+import * as YAML from "yaml"
+import { z } from "zod"
+import { resolveFromRoot } from "./paths.ts"
 
 export type AgentsDocumentEntry = {
-  path: string
+	path: string
+	description?: string | undefined
 }
 
 export type AgentsFile = {
-  version: 1
-  documents: AgentsDocumentEntry[]
+	version: 1
+	documents: AgentsDocumentEntry[]
 }
 
 export type ValidationResult = {
-  ok: boolean
-  errors: string[]
-  warnings: string[]
+	ok: boolean
+	errors: string[]
+	warnings: string[]
 }
 
 const fileSchema = z.object({
-  version: z.literal(1),
-  documents: z.array(
-    z.object({
-      path: z.string().min(1),
-    }),
-  ),
+	version: z.literal(1),
+	documents: z.array(
+		z.object({
+			path: z.string().min(1),
+			description: z.string().min(1).optional(),
+		}),
+	),
 })
 
-const breadcrumb = `For dependency-specific and supplemental guidance, consult \`./agents.yaml\`.
-
-Only the documents listed there should be considered active external guidance for this project.`
+const breadcrumb = `Consult \`./agents.yaml\` when working with outside dependencies.`
 
 export async function loadAgentsFile(root: string): Promise<AgentsFile> {
-  const filePath = agentsPath(root)
-
-  try {
-    const source = await readFile(filePath, 'utf8')
-    const parsed = YAML.parse(source) as unknown
-    return fileSchema.parse(parsed)
-  } catch (error) {
-    if (isNotFound(error)) {
-      return { version: 1, documents: [] }
-    }
-
-    if (error instanceof z.ZodError) {
-      throw new Error(
-        `Invalid agents.yaml: ${error.issues.map((issue) => issue.message).join(', ')}`,
-      )
-    }
-
-    throw error
-  }
+	const filePath = agentsPath(root)
+
+	try {
+		const source = await readFile(filePath, "utf8")
+		const parsed = YAML.parse(source) as unknown
+		return fileSchema.parse(parsed)
+	} catch (error) {
+		if (isNotFound(error)) {
+			return { version: 1, documents: [] }
+		}
+
+		if (error instanceof z.ZodError) {
+			throw new Error(
+				`Invalid agents.yaml: ${error.issues.map((issue) => issue.message).join(", ")}`,
+			)
+		}
+
+		throw error
+	}
 }
 
-export async function saveAgentsFile(root: string, file: AgentsFile): Promise<void> {
-  const normalized = {
-    version: file.version,
-    documents: file.documents.map((doc) => ({ path: doc.path })),
-  }
-
-  await writeFile(agentsPath(root), YAML.stringify(normalized, { lineWidth: 0 }), 'utf8')
+export async function saveAgentsFile(
+	root: string,
+	file: AgentsFile,
+): Promise<void> {
+	const normalized = {
+		version: file.version,
+		documents: file.documents.map((doc) => ({
+			path: doc.path,
+			...(doc.description ? { description: doc.description } : {}),
+		})),
+	}
+
+	await writeFile(
+		agentsPath(root),
+		YAML.stringify(normalized, { lineWidth: 0 }),
+		"utf8",
+	)
 }
 
 export async function addDocuments(
-  root: string,
-  documents: AgentsDocumentEntry[],
+	root: string,
+	documents: AgentsDocumentEntry[],
 ): Promise<AgentsFile> {
-  const file = await loadAgentsFile(root)
-  const byPath = new Map(file.documents.map((doc) => [doc.path, doc]))
-
-  for (const document of documents) {
-    byPath.set(document.path, document)
-  }
-
-  const next = {
-    version: 1 as const,
-    documents: [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path)),
-  }
-
-  await saveAgentsFile(root, next)
-  return next
+	const file = await loadAgentsFile(root)
+	const byPath = new Map(file.documents.map((doc) => [doc.path, doc]))
+
+	for (const document of documents) {
+		const existing = byPath.get(document.path)
+		byPath.set(document.path, {
+			path: document.path,
+			...(existing?.description ? { description: existing.description } : {}),
+			...(document.description ? { description: document.description } : {}),
+		})
+	}
+
+	const next = {
+		version: 1 as const,
+		documents: [...byPath.values()].sort((left, right) =>
+			left.path.localeCompare(right.path),
+		),
+	}
+
+	await saveAgentsFile(root, next)
+	return next
 }
 
 export async function removeDocuments(
-  root: string,
-  paths: string[],
+	root: string,
+	paths: string[],
 ): Promise<{ file: AgentsFile; removed: string[] }> {
-  const file = await loadAgentsFile(root)
-  const pathSet = new Set(paths)
-  const removed: string[] = []
-  const documents = file.documents.filter((doc) => {
-    if (pathSet.has(doc.path)) {
-      removed.push(doc.path)
-      return false
-    }
-
-    return true
-  })
-
-  const next = { version: 1 as const, documents }
-  await saveAgentsFile(root, next)
-  return { file: next, removed }
+	const file = await loadAgentsFile(root)
+	const pathSet = new Set(paths)
+	const removed: string[] = []
+	const documents = file.documents.filter((doc) => {
+		if (pathSet.has(doc.path)) {
+			removed.push(doc.path)
+			return false
+		}
+
+		return true
+	})
+
+	const next = { version: 1 as const, documents }
+	await saveAgentsFile(root, next)
+	return { file: next, removed }
 }
 
-export async function validateAgentsFile(root: string): Promise<ValidationResult> {
-  const errors: string[] = []
-  const warnings: string[] = []
-  let file: AgentsFile
-
-  try {
-    file = await loadAgentsFile(root)
-  } catch (error) {
-    return {
-      ok: false,
-      errors: [error instanceof Error ? error.message : String(error)],
-      warnings,
-    }
-  }
-
-  const seen = new Set<string>()
-  for (const [index, document] of file.documents.entries()) {
-    const label = `documents[${index}] ${document.path}`
-
-    if (seen.has(document.path)) {
-      errors.push(`${label}: duplicate path`)
-    }
-    seen.add(document.path)
-
-    if (path.basename(document.path) !== 'AGENTS.md') {
-      warnings.push(`${label}: path does not end with AGENTS.md`)
-    }
-
-    try {
-      await access(resolveFromRoot(root, document.path))
-    } catch {
-      errors.push(`${label}: file does not exist`)
-    }
-  }
-
-  try {
-    const source = await readFile(path.join(root, 'AGENTS.md'), 'utf8')
-    if (!source.includes('./agents.yaml') && !source.includes('agents.yaml')) {
-      warnings.push('AGENTS.md does not mention agents.yaml')
-    }
-  } catch {
-    warnings.push('AGENTS.md is missing the agents.yaml breadcrumb')
-  }
-
-  return {
-    ok: errors.length === 0,
-    errors,
-    warnings,
-  }
+export async function validateAgentsFile(
+	root: string,
+): Promise<ValidationResult> {
+	const errors: string[] = []
+	const warnings: string[] = []
+	let file: AgentsFile
+
+	try {
+		file = await loadAgentsFile(root)
+	} catch (error) {
+		return {
+			ok: false,
+			errors: [error instanceof Error ? error.message : String(error)],
+			warnings,
+		}
+	}
+
+	const seen = new Set<string>()
+	for (const [index, document] of file.documents.entries()) {
+		const label = `documents[${index}] ${document.path}`
+
+		if (seen.has(document.path)) {
+			errors.push(`${label}: duplicate path`)
+		}
+		seen.add(document.path)
+
+		if (path.basename(document.path) !== "AGENTS.md") {
+			warnings.push(`${label}: path does not end with AGENTS.md`)
+		}
+
+		try {
+			await access(resolveFromRoot(root, document.path))
+		} catch {
+			errors.push(`${label}: file does not exist`)
+		}
+	}
+
+	try {
+		const source = await readFile(path.join(root, "AGENTS.md"), "utf8")
+		if (!source.includes("./agents.yaml") && !source.includes("agents.yaml")) {
+			warnings.push("AGENTS.md does not mention agents.yaml")
+		}
+	} catch {
+		warnings.push("AGENTS.md is missing the agents.yaml breadcrumb")
+	}
+
+	return {
+		ok: errors.length === 0,
+		errors,
+		warnings,
+	}
 }
 
 export async function initProject(
-  root: string,
-  options: { force: boolean },
+	root: string,
+	options: { force: boolean },
 ): Promise<{ messages: string[] }> {
-  const messages: string[] = []
-
-  try {
-    await access(agentsPath(root))
-    messages.push('agents.yaml already exists')
-  } catch {
-    await saveAgentsFile(root, { version: 1, documents: [] })
-    messages.push('created agents.yaml')
-  }
-
-  const projectAgentsPath = path.join(root, 'AGENTS.md')
-  try {
-    const source = await readFile(projectAgentsPath, 'utf8')
-    if (source.includes('agents.yaml') && !options.force) {
-      messages.push('AGENTS.md already mentions agents.yaml')
-      return { messages }
-    }
-
-    const next =
-      source.trimEnd().length === 0
-        ? `# Project Instructions\n\n${breadcrumb}\n`
-        : `${source.trimEnd()}\n\n${breadcrumb}\n`
-    await writeFile(projectAgentsPath, next, 'utf8')
-    messages.push('updated AGENTS.md')
-  } catch (error) {
-    if (!isNotFound(error)) throw error
-    await writeFile(projectAgentsPath, `# Project Instructions\n\n${breadcrumb}\n`, 'utf8')
-    messages.push('created AGENTS.md')
-  }
-
-  return { messages }
+	const messages: string[] = []
+
+	try {
+		await access(agentsPath(root))
+		messages.push("agents.yaml already exists")
+	} catch {
+		await saveAgentsFile(root, { version: 1, documents: [] })
+		messages.push("created agents.yaml")
+	}
+
+	const projectAgentsPath = path.join(root, "AGENTS.md")
+	try {
+		const source = await readFile(projectAgentsPath, "utf8")
+		if (source.includes("agents.yaml") && !options.force) {
+			messages.push("AGENTS.md already mentions agents.yaml")
+			return { messages }
+		}
+
+		const next =
+			source.trimEnd().length === 0
+				? `# Project Instructions\n\n${breadcrumb}\n`
+				: `${source.trimEnd()}\n\n${breadcrumb}\n`
+		await writeFile(projectAgentsPath, next, "utf8")
+		messages.push("updated AGENTS.md")
+	} catch (error) {
+		if (!isNotFound(error)) throw error
+		await writeFile(
+			projectAgentsPath,
+			`# Project Instructions\n\n${breadcrumb}\n`,
+			"utf8",
+		)
+		messages.push("created AGENTS.md")
+	}
+
+	return { messages }
 }
 
 function agentsPath(root: string): string {
-  return path.join(root, 'agents.yaml')
+	return path.join(root, "agents.yaml")
 }
 
 function isNotFound(error: unknown): boolean {
-  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+	return error instanceof Error && "code" in error && error.code === "ENOENT"
 }