docs: improve and clean up contributor docs for barebones merge (#5840)

* chore: rename COPYRIGHT to HEADER

* docs: add minimalistic README and CONTRIBUTING docs

* docs: reorganize contributor docs

* docs: complete reorganization

* docs: move docs from 1st-gen

* docs: cleanup

* docs: incremental reorg

* docs: move style guide back to top level

* docs: refactor getting involved and PR docs

* docs: add working-in-the-repo doc, make minor edits

* chore: fix links, improve link-validation

* docs: restore original root README within 1st-gen

* docs: link to code of conduct

* docs: link to CLA

* chore: add comma

Co-authored-by: Najika Halsema Yoo <[email protected]>

* chore: add link to Stackblitz for repros

Co-authored-by: Najika Halsema Yoo <[email protected]>

* chore: add link to Stackblitz

Co-authored-by: Najika Halsema Yoo <[email protected]>

* docs: apply suggestions from review

* docs: minor copy edit

* docs: fix list formatting

Co-authored-by: Najika Halsema Yoo <[email protected]>

---------

Co-authored-by: Najika Halsema Yoo <[email protected]>

Author: graynorton

.cursor/rules/contributor-doc-update.mdc

@@ -1,7 +1,52 @@
 ---
-description: Useful for updating auto-generated content in the contributor docs
+description: Useful for updating auto-generated navigation and validating links in the contributor docs
 alwaysApply: false
 ---
-If the user requests an update to the contributor docs (located in the CONTRIBUTOR_DOCS folder at the repository root), run the update process as described in the agent instructions within that folder.
 
-To locate the instructions, search for "ai-agent-instructions", or fall back to a recursive directory search if needed.
+# Contributor docs navigation and link validation
+
+## When to apply this rule
+
+Recognize and apply this rule when the user requests any of the following:
+- Update contributor docs navigation
+- Update nav / TOC / breadcrumbs in contributor docs
+- Regenerate contributor docs
+- Validate/verify links in contributor docs
+- Fix broken links in contributor docs
+- Any mention of "CONTRIBUTOR-DOCS" or "contributor docs" with "update", "nav", "links", or "verify"
+
+## Instructions location
+
+**Primary path:** `CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/01_ai-agent-instructions.md`
+
+## What to do
+
+1. **Verify the instructions file exists** at the path above
+   - If the file exists, read it and follow the instructions for "Role 1: Operator"
+   - If the file does NOT exist, see "Self-correction procedure" below
+
+2. **Follow the AI agent instructions** to:
+   - Run the nav update script (which automatically validates links)
+   - Handle any broken links that are reported
+   - Report results to the user
+
+## Self-correction procedure
+
+If the instructions file is not found at the expected path:
+
+1. Search for the file using: `glob_file_search` with pattern `**/ai-agent-instructions.md`
+2. Filter results to find the one in `CONTRIBUTOR-DOCS/` folder
+3. Read the found file to confirm it contains the nav update instructions
+4. **Update this rule file** with the new path by modifying the "Primary path" line above
+5. Inform the user that you've updated the rule with the new location
+6. Continue with the nav update process
+
+## Quick reference
+
+The nav update process typically involves:
+- Running a Node.js script in the authoring-contributor-docs folder
+- The script automatically updates breadcrumbs, TOC, and validates all links
+- If broken links are found, fix straightforward issues automatically
+- Only consult the user for ambiguous cases
+
+Execution time is typically 20-200ms for the entire CONTRIBUTOR-DOCS tree.

.eslintrc.json

@@ -9,6 +9,7 @@
         "plugin:@typescript-eslint/recommended",
         "plugin:prettier/recommended"
     ],
+    "ignorePatterns": ["CONTRIBUTOR-DOCS/**/*"],
     "overrides": [
         {
             "extends": ["plugin:jsonc/recommended-with-jsonc"],

.prettierignore

@@ -0,0 +1,3 @@
+# Documentation infrastructure scripts maintained by AI agents
+CONTRIBUTOR-DOCS/
+

.stylelintignore

@@ -1,5 +1,5 @@
 node_modules
-COPYRIGHT
+HEADER
 1st-gen/node_modules
 2nd-gen/node_modules
 1st-gen/task

.stylelintrc.json

@@ -7,7 +7,7 @@
             "files": ["**/*.css"],
             "extends": ["stylelint-config-standard"],
             "rules": {
-                "header/header": ["./COPYRIGHT", {}],
+                "header/header": ["./HEADER", {}],
                 "length-zero-no-unit": [
                     true,
                     { "ignore": "custom-properties" }