agents.yaml 0.1.0 → 0.2.0

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

@@ -20,11 +20,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 +44,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 +177,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 +198,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 +231,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 +266,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 +362,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,7 +429,7 @@ 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({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents.yaml",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A CLI for discovering and curating agent-readable documentation in agents.yaml.",
   "repository": {
     "type": "git",
@@ -16,12 +16,6 @@
     "AGENTS.md"
   ],
   "type": "module",
-  "scripts": {
-    "build": "tsdown",
-    "dev": "src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "check": "tsc --noEmit && tsdown"
-  },
   "dependencies": {
     "@clack/prompts": "1.5.1",
     "yaml": "2.9.0",
@@ -29,12 +23,15 @@
   },
   "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

@@ -6,6 +6,7 @@ import { resolveFromRoot } from './paths.ts'
 
 export type AgentsDocumentEntry = {
   path: string
+  description?: string | undefined
 }
 
 export type AgentsFile = {
@@ -24,13 +25,12 @@ const fileSchema = z.object({
   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)
@@ -57,7 +57,10 @@ export async function loadAgentsFile(root: string): Promise<AgentsFile> {
 export async function saveAgentsFile(root: string, file: AgentsFile): Promise<void> {
   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')
@@ -71,7 +74,12 @@ export async function addDocuments(
   const byPath = new Map(file.documents.map((doc) => [doc.path, doc]))
 
   for (const document of documents) {
-    byPath.set(document.path, document)
+    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 = {

package/src/discover.test.ts

@@ -17,21 +17,42 @@ describe('agents.yaml dependency discovery', () => {
     const dependencyAgentsPath = path.join(root, 'node_modules', 'direct-lib', 'AGENTS.md')
     await mkdir(path.dirname(dependencyAgentsPath), { recursive: true })
     await writeFile(dependencyAgentsPath, '# Direct dependency guidance\n', 'utf8')
+    await writeFile(
+      path.join(root, 'node_modules', 'direct-lib', 'package.json'),
+      JSON.stringify({
+        name: 'direct-lib',
+        description: 'Direct fixtures for testing agent guidance.',
+      }),
+      'utf8',
+    )
 
     const discovered = await discoverAgentDocuments(root)
-    expect(discovered).toEqual([{ path: './node_modules/direct-lib/AGENTS.md' }])
-
-    await addDocuments(root, [
+    expect(discovered).toEqual([
       {
-        path: discovered[0]!.path,
+        path: './node_modules/direct-lib/AGENTS.md',
+        description: 'Direct fixtures for testing agent guidance.',
       },
     ])
 
+    await addDocuments(root, [discovered[0]!])
+
     await expect(loadAgentsFile(root)).resolves.toEqual({
       version: 1,
       documents: [
         {
           path: './node_modules/direct-lib/AGENTS.md',
+          description: 'Direct fixtures for testing agent guidance.',
+        },
+      ],
+    })
+
+    await addDocuments(root, [{ path: './node_modules/direct-lib/AGENTS.md' }])
+    await expect(loadAgentsFile(root)).resolves.toEqual({
+      version: 1,
+      documents: [
+        {
+          path: './node_modules/direct-lib/AGENTS.md',
+          description: 'Direct fixtures for testing agent guidance.',
         },
       ],
     })
@@ -58,6 +79,28 @@ describe('agents.yaml dependency discovery', () => {
       { path: './node_modules/direct-lib/AGENTS.md' },
     ])
   })
+
+  it('includes scoped package descriptions when present', async () => {
+    const root = await createTempProject()
+    const dependencyPath = path.join(root, 'node_modules', '@scope', 'direct-lib')
+    await mkdir(dependencyPath, { recursive: true })
+    await writeFile(path.join(dependencyPath, 'AGENTS.md'), '# Scoped guidance\n', 'utf8')
+    await writeFile(
+      path.join(dependencyPath, 'package.json'),
+      JSON.stringify({
+        name: '@scope/direct-lib',
+        description: 'Scoped package guidance breadcrumbs.',
+      }),
+      'utf8',
+    )
+
+    await expect(discoverAgentDocuments(root)).resolves.toEqual([
+      {
+        path: './node_modules/@scope/direct-lib/AGENTS.md',
+        description: 'Scoped package guidance breadcrumbs.',
+      },
+    ])
+  })
 })
 
 async function createTempProject(): Promise<string> {

package/src/discover.ts

@@ -1,9 +1,10 @@
-import { access, opendir } from 'node:fs/promises'
+import { access, opendir, readFile } from 'node:fs/promises'
 import path from 'node:path'
-import { formatProjectPath } from './paths.ts'
+import { formatProjectPath, resolveFromRoot } from './paths.ts'
 
 export type DiscoveredDocument = {
   path: string
+  description?: string
 }
 
 const skippedDirectories = new Set([
@@ -25,6 +26,14 @@ export async function discoverAgentDocuments(root: string): Promise<DiscoveredDo
     .sort((left, right) => left.path.localeCompare(right.path))
 }
 
+export async function describeAgentDocument(
+  root: string,
+  agentsDocumentPath: string,
+): Promise<DiscoveredDocument> {
+  const absolutePath = resolveFromRoot(root, agentsDocumentPath)
+  return documentEntry(root, absolutePath, await readPackageDescription(path.dirname(absolutePath)))
+}
+
 async function walk(root: string, directory: string, found: DiscoveredDocument[]): Promise<void> {
   let handle
   try {
@@ -49,7 +58,13 @@ async function walk(root: string, directory: string, found: DiscoveredDocument[]
     }
 
     if (entry.isFile() && entry.name === 'AGENTS.md') {
-      found.push({ path: formatProjectPath(root, absolutePath) })
+      found.push(
+        await documentEntry(
+          root,
+          absolutePath,
+          await readPackageDescription(path.dirname(absolutePath)),
+        ),
+      )
     }
   }
 }
@@ -108,8 +123,36 @@ async function addPackageAgentsDocument(
   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 {
     // Packages without AGENTS.md are simply not candidates.
   }
 }
+
+async function documentEntry(
+  root: string,
+  agentsPath: string,
+  description: string | undefined,
+): Promise<DiscoveredDocument> {
+  return {
+    path: formatProjectPath(root, agentsPath),
+    ...(description ? { description } : {}),
+  }
+}
+
+async function readPackageDescription(packagePath: string): Promise<string | undefined> {
+  try {
+    const source = await readFile(path.join(packagePath, 'package.json'), 'utf8')
+    const parsed = JSON.parse(source) as unknown
+    if (!isPackageJson(parsed) || typeof parsed.description !== 'string') return undefined
+
+    const description = parsed.description.trim()
+    return description && description.length > 0 ? description : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function isPackageJson(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}

package/src/run.ts

@@ -6,7 +6,7 @@ import {
   removeDocuments,
   validateAgentsFile,
 } from './agents-file.ts'
-import { discoverAgentDocuments } from './discover.ts'
+import { describeAgentDocument, discoverAgentDocuments } from './discover.ts'
 import { cwd, formatProjectPath, resolveFromRoot } from './paths.ts'
 
 type Command = 'add' | 'discover' | 'help' | 'init' | 'remove' | 'validate' | 'version'
@@ -27,7 +27,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.`
 
 export async function run(argv: string[]): Promise<void> {
   const parsed = parseArgs(argv)
@@ -127,7 +127,7 @@ async function commandDiscover(root: string, json: boolean): Promise<void> {
     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.')
 }
 
@@ -136,16 +136,26 @@ async function commandAdd(root: string, paths: string[]): Promise<void> {
     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: { path: string; description?: string | undefined }[],
+): string {
+  return documents
+    .map((doc) => (doc.description ? `${doc.path}\n  ${doc.description}` : doc.path))
+    .join('\n')
+}
+
 async function commandRemove(root: string, paths: string[]): Promise<void> {
   if (paths.length === 0) {
     throw new Error('remove requires at least one path')
@@ -154,9 +164,9 @@ async function commandRemove(root: string, paths: string[]): Promise<void> {
   const normalizedPaths = paths.map((path) => formatProjectPath(root, resolveFromRoot(root, path)))
   const result = await removeDocuments(root, normalizedPaths)
   clack.intro('agents remove')
-  clack.note(result.removed.join('\n') || 'No matching documents were active.', 'Removed')
+  clack.note(result.removed.join('\n') || 'No matching documents were listed.', 'Removed')
   clack.outro(
-    `agents.yaml now has ${result.file.documents.length} active document${result.file.documents.length === 1 ? '' : 's'}.`,
+    `agents.yaml now has ${result.file.documents.length} promoted document${result.file.documents.length === 1 ? '' : 's'}.`,
   )
 }
 
@@ -214,7 +224,7 @@ async function interactive(root: string): Promise<void> {
   )
 
   if (candidates.length === 0) {
-    clack.outro('No inactive supplemental AGENTS.md files found.')
+    clack.outro('No unlisted supplemental AGENTS.md files found.')
     return
   }