feat: Add directive that index.md files are auto-generated

AGENTS.md now warns agents not to manually create or edit
ai/**/index.md files since they are generated from frontmatter
and overwritten by the pre-commit hook.

Author: claude

lib/agents-md.js

@@ -18,6 +18,7 @@ const REQUIRED_DIRECTIVES = [
   "root index", // Progressive discovery starting from root
   "vision", // Vision document requirement
   "conflict", // Conflict resolution
+  "generated", // Auto-generated files warning
 ];
 
 // The content for AGENTS.md
@@ -33,6 +34,8 @@ Agents should examine the \`ai/*\` directory listings to understand the availabl
 
 Each folder contains an \`index.md\` file that describes the purpose and contents of that folder. Agents can read these index files to learn the function of files in each folder without needing to read every file.
 
+**Important:** The \`ai/**/index.md\` files are auto-generated from frontmatter. Do not create or edit these files manually—they will be overwritten by the pre-commit hook.
+
 ## Progressive Discovery
 
 Agents should only consume the root index until they need subfolder contents. For example:
@@ -144,6 +147,8 @@ Agents should examine the \`ai/*\` directory listings to understand the availabl
 
 Each folder contains an \`index.md\` file that describes the purpose and contents of that folder. Agents can read these index files to learn the function of files in each folder.
 
+**Important:** The \`ai/**/index.md\` files are auto-generated from frontmatter. Do not create or edit these files manually—they will be overwritten by the pre-commit hook.
+
 ### Progressive Discovery
 
 Agents should only consume the root index until they need subfolder contents. For example:

lib/agents-md.test.js

@@ -51,7 +51,7 @@ describe("agents-md", () => {
     test("is case insensitive", () => {
       const mixedCaseContent = `
         Check AI/ directory listings
-        INDEX.MD files
+        INDEX.MD files are auto-GENERATED
         Root Index from base
         VISION document requirement
         CONFLICT resolution
@@ -204,7 +204,7 @@ describe("agents-md", () => {
       const customContent = `# Custom AGENTS.md
 
 Look at ai/ directory listings.
-Read index.md files.
+Read index.md files (auto-generated).
 Only use root index until you need more.
 Always read the vision document first.
 Report conflict resolution to the user.