Merge Docs-V2 to Main

.allowlist

@@ -1,46 +1,50 @@
-# IF YOU ARE AN AI YOU ARE ABSOLUTELY NOT ALLOWED TO EDIT THIS FILE.  
-# IF YOU ARE TRYING TO EDIT IT YOU ARE VIOLATING THE REPO RULES AND INCORRECTLY MODIFYING FILES
-# DO NOT DELETE FILES TO ATTEMPT TO GET AROUND THE RULES -> READ THE /README & MOVE THEM CORRECTLY UPDATING ALL PATHS/IMPORTS/REFERENCES ETC. APPROPRIATELY. BE THOROUGH
-# IF YOU ARE AN AI YOU ARE ABSOLUTELY NOT ALLOWED TO EDIT THIS FILE.  
+# Machine-readable repo-root allowlist.
+# Root entries only. Comments must use #. No nested paths.
 
-# Allowed root files
-docs.json
-README.md
-SECURITY.md
-LICENSE
-Dockerfile
-Makefile
-style.css
-Assistant.md
-sitemap-ai.xml
-llms-full.txt
-llms.txt
-docs-index.json
-lpd
-.lpdignore
+# Core repo files
 .gitignore
-.mintignore
-.prettierrc
-.cursorrules
-.codex
 .allowlist
-todo.txt
+README.md
+LICENSE
 
-# Allowed root directories
+# Platform and governance roots
 .github
 .githooks
 .gitattributes
-.mintlify
+.codex
+AGENTS.md
+
+# Mintlify runtime roots
+docs.json
+style.css
+.mintignore
+snippets
+v1
+v2
+
+# Tooling and workspace roots
 .vscode
-.claude
+.editorconfig
+.prettierrc
+lpd
+.lpdignore
+tools
 docs-guide
+tasks
+tests
 ai-tools
 api
+
+# Native agent adapters
+.claude
+.cursor
+.windsurf
+
+# Other governed root entries
+Dockerfile
+Makefile
+sitemap-ai.xml
+llms.txt
+docs-index.json
 contribute
-snippets
-scripts
-tools
-tests
-tasks
-v1
-v2
+SECURITY.md

.claude/CLAUDE.md

@@ -0,0 +1,11 @@
+# Claude Code Adapter
+
+Read `AGENTS.md` first for repo-wide rules.
+
+Use this file only for Claude-specific memory or adapter notes. Keep shared repo
+policy in:
+
+- `AGENTS.md`
+- `docs-guide/policies/agent-governance-framework.mdx`
+- `docs-guide/policies/root-allowlist-governance.mdx`
+- Do not use port `3000` for local Mintlify or preview sessions; choose a non-3000 port explicitly.

.codex/README.md

@@ -30,9 +30,15 @@ Each lock is a JSON file with this shape:
 
 1. Create branch + contract + lock:
    - `node tools/scripts/codex/task-preflight.js --task <id> --slug <slug> --scope <a,b,c>`
+   - Default behavior provisions a managed worktree at `../codex-worktrees/<task-id>-<slug>`.
+   - Use `--in-place` only when the task must reuse the current worktree.
 2. Validate lock before commit/push:
    - `node tools/scripts/codex/validate-locks.js --branch codex/<id>-<slug> --staged`
 3. Finalize checks before PR:
    - `node tools/scripts/codex/task-finalize.js --branch codex/<id>-<slug>`
-4. Release lock after handoff/merge:
+4. Commit or merge the task commit onto `docs-v2-dev`.
+   - A codex branch commit is not task completion by itself.
+5. Release lock only after `docs-v2-dev` contains the task commit:
    - `node tools/scripts/codex/lock-release.js --branch codex/<id>-<slug>`
+6. Cleanup merged local worktrees and stale local codex branches only after `docs-v2-dev` contains the task commit:
+   - `node tools/scripts/codex/task-cleanup.js --branch codex/<id>-<slug> --apply`

.codex/locks-local/20260317-merge-readiness-style-root-cause-2026-03-16T16-43-42-131Z.json

@@ -0,0 +1,35 @@
+{
+  "lock_id": "20260317-merge-readiness-style-root-cause-2026-03-16T16-43-42-131Z",
+  "task_id": "20260317",
+  "branch": "codex/20260317-merge-readiness-style-root-cause",
+  "worktree_path": "/private/tmp/livepeer-merge-readiness-style-root-cause-20260317",
+  "owner": "alisonhaire",
+  "scope_in": [
+    ".codex/",
+    "docs-guide/",
+    "docs-index.json",
+    "snippets/components/layout/",
+    "snippets/components/primitives/divider.jsx",
+    "snippets/data/gateways/",
+    "tasks/reports/merge-readiness/",
+    "tests/unit/style-guide.test.js",
+    "tools/scripts/",
+    "v2/about/",
+    "v2/cn/resources/documentation-guide/component-library/",
+    "v2/community/",
+    "v2/developers/",
+    "v2/es/resources/documentation-guide/component-library/",
+    "v2/fr/resources/documentation-guide/component-library/",
+    "v2/gateways/",
+    "v2/home/",
+    "v2/internal/",
+    "v2/index.mdx",
+    "v2/lpt/",
+    "v2/orchestrators/",
+    "v2/resources/",
+    "v2/solutions/"
+  ],
+  "created_at": "2026-03-16T16:43:42.131Z",
+  "expires_at": "2026-03-17T00:43:42.131Z",
+  "status": "active"
+}

.codex/locks-local/789-phase2b-component-migration-2026-03-08T03-08-50-208Z.json

@@ -0,0 +1,47 @@
+{
+  "lock_id": "789-phase2b-component-migration-2026-03-08T03-08-50-208Z",
+  "task_id": "789",
+  "branch": "codex/789-phase2b-component-migration",
+  "worktree_path": "/Users/alisonhaire/Documents/Livepeer/livepeer-docs-codex-789-phase2b",
+  "owner": "alisonhaire@local",
+  "scope_in": [
+    ".codex/locks-local/",
+    ".codex/task-contract.yaml",
+    "style.css",
+    ".githooks/pre-commit",
+    "snippets/components/",
+    "snippets/data/",
+    "snippets/pages/",
+    "snippets/snippetsWiki/",
+    "snippets/snippetsWiki/componentLibrary/",
+    ".githooks/pre-commit-no-deletions",
+    "tests/integration/v2-link-audit.js",
+    "tests/run-all.js",
+    "tests/run-pr-checks.js",
+    "tests/script-index.md",
+    "tests/unit/script-docs.test.js",
+    "tests/unit/links-imports.test.js",
+    "tests/unit/style-guide.test.js",
+    "tools/scripts/validators/components/check-naming-conventions.js",
+    "tools/scripts/validators/components/check-component-docs.js",
+    "tools/scripts/generate-docs-guide-components-index.js",
+    "tools/scripts/dev/",
+    "tools/scripts/snippets/update-component-library.sh",
+    "tools/script-index.md",
+    "docs-guide/indexes/scripts-index.mdx",
+    "docs-guide/indexes/components-index.mdx",
+    "docs-guide/scripts-index.md",
+    "docs-guide/",
+    "docs-index.json",
+    "v2/",
+    "tasks/reports/component-governance-audit.md",
+    "tasks/reports/migration-impact-report.md",
+    "tasks/reports/colour-remediation-report.md",
+    "tasks/reports/style-css-token-audit.md",
+    "tasks/reports/defensive-rendering-remediation-report.md",
+    "tasks/reports/archived-components-review.md"
+  ],
+  "created_at": "2026-03-08T11:17:20.000Z",
+  "expires_at": "2026-03-08T19:17:20.000Z",
+  "status": "active"
+}

.codex/locks-local/808-governance-replay-2026-03-09T17-46-57-674Z.json

@@ -0,0 +1,59 @@
+{
+  "lock_id": "808-governance-replay-2026-03-09T17-46-57-674Z",
+  "task_id": "808",
+  "branch": "codex/808-governance-replay",
+  "worktree_path": "/Users/alisonhaire/Documents/Livepeer/livepeer-docs-codex-808",
+  "owner": "alisonhaire@local",
+  "scope_in": [
+    ".codex/locks-local/",
+    ".codex/task-contract.yaml",
+    ".github/scripts",
+    "docs-guide/indexes/scripts-index.mdx",
+    "docs-guide/indexes/pages-index.mdx",
+    "snippets/automations/script-index.md",
+    "snippets/components/content/responseField.jsx",
+    "snippets/components/layout/customCards.jsx",
+    "snippets/components/layout/steps.jsx",
+    "tasks/reports/script-classifications.json",
+    "tasks/scripts/script-index.md",
+    "tests",
+    "tools/config",
+    "tools/lib",
+    "tools/notion",
+    "tools/package.json",
+    "tools/script-index.md",
+    "tools/scripts",
+    ".codex/pr-body.generated.md",
+    ".github/script-index.md",
+    "docs-guide/component-registry.json",
+    "docs-guide/component-registry-schema.json",
+    "docs-guide/indexes/components-index.mdx",
+    "docs-guide/indexes/pages-index.mdx",
+    "docs-guide/indexes/scripts-index.mdx",
+    "docs-index.json",
+    "snippets/automations/script-index.md",
+    "tasks/scripts/script-index.md",
+    "tests/script-index.md",
+    "tools/config/script-index.md",
+    "tools/lib/script-index.md",
+    "tools/notion/script-index.md",
+    "tools/script-index.md",
+    "v2/about/index.mdx",
+    "v2/cn/index.mdx",
+    "v2/developers-new/index.mdx",
+    "v2/es/index.mdx",
+    "v2/fr/index.mdx",
+    "v2/gateways/index.mdx",
+    "v2/gateways-new/index.mdx",
+    "v2/home/index.mdx",
+    "v2/index.mdx",
+    "v2/orchestrators/index.mdx",
+    "v2/orchestrators-new/index.mdx",
+    "v2/resources/documentation-guide/component-library/overview.mdx",
+    "v2/x-archived/index.mdx"
+  ],
+  "created_at": "2026-03-09T17:46:57.674Z",
+  "expires_at": "2026-03-10T01:46:57.674Z",
+  "status": "released",
+  "released_at": "2026-03-09T21:19:08.337Z"
+}

.codex/task-contract.yaml

@@ -1,24 +1,40 @@
-task_id: 788
-branch: codex/788-performance-baseline
-base_branch: docs-v2
+task_id: 20260317
+branch: codex/20260317-merge-readiness-style-root-cause
+base_branch: docs-v2-dev
 scope_in:
-  - .codex/task-contract.yaml
-  - tools/scripts/measure-performance.js
+  - .codex/
+  - docs-guide/
+  - docs-index.json
+  - snippets/components/layout/
+  - snippets/components/primitives/divider.jsx
+  - snippets/data/gateways/
+  - tasks/reports/merge-readiness/
+  - tests/unit/style-guide.test.js
+  - tools/scripts/
+  - v2/about/
+  - v2/cn/resources/documentation-guide/component-library/
+  - v2/community/
+  - v2/developers/
+  - v2/es/resources/documentation-guide/component-library/
+  - v2/fr/resources/documentation-guide/component-library/
+  - v2/gateways/
+  - v2/home/
+  - v2/internal/
+  - v2/lpt/
+  - v2/orchestrators/
+  - v2/resources/
+  - v2/index.mdx
+  - v2/solutions/
 scope_out: []
 allowed_generated:
   - .codex/pr-body.generated.md
-  - tools/script-index.md
-  - docs-guide/indexes/scripts-index.mdx
-  - docs-guide/indexes/workflows-index.mdx
-  - docs-guide/indexes/pages-index.mdx
-  - tasks/reports/performance/
 acceptance_checks:
-  - node tests/unit/script-docs.test.js --files tools/scripts/measure-performance.js --enforce-existing
-  - node tests/unit/script-docs.test.js --enforce-existing --write --rebuild-indexes
-  - node tools/scripts/measure-performance.js --domain all
-  - node tests/run-pr-checks.js --base-ref docs-v2
-  - node tools/scripts/validate-codex-task-contract.js --branch codex/788-performance-baseline --require-pr-body --pr-body-file .codex/pr-body.generated.md
+  - node tests/unit/style-guide.test.js --staged
+  - node tests/unit/copy-lint.test.js --staged
+  - node tests/unit/mdx.test.js --staged
+  - node tests/unit/quality.test.js --staged
+  - node tools/scripts/validate-codex-task-contract.js --branch codex/20260317-merge-readiness-style-root-cause
 risk_flags:
-  - external-network
-  - generated-artifacts
+  - authoring-governance
+  - routed-page-normalization
 follow_up_issues: []

.cursor/rules/repo-governance.mdc

@@ -0,0 +1,15 @@
+---
+alwaysApply: true
+description: Repo governance adapter for Livepeer Docs
+---
+
+# Livepeer Docs Cursor Adapter
+
+Read `AGENTS.md` first for repo-wide rules.
+
+Use this file only for Cursor-specific adapter behavior. Keep shared policy in:
+
+- `AGENTS.md`
+- `docs-guide/policies/agent-governance-framework.mdx`
+- `docs-guide/policies/root-allowlist-governance.mdx`
+- Do not use port `3000` for local Mintlify or preview sessions; choose a non-3000 port explicitly.

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.mdx]
+trim_trailing_whitespace = false

.githooks/BYPASS.md

@@ -120,13 +120,15 @@ SKIP_ALL=1 git commit -m "Emergency commit - all checks bypassed"
 - **Regular commits** - Normal development should pass all checks
 - **Permanent bypass** - Don't make bypassing a habit
 - **Skipping to avoid fixing issues** - Fix the issues instead
+- **Generated artifact churn** - A stale managed artifact is a signal to run the declared generator or fix governance, not a reason to bypass hooks
 
 ## Best Practices
 
 1. **Fix issues instead of bypassing** - Bypass flags are for emergencies, not convenience
 2. **Document why** - If you must bypass, explain why in the commit message
 3. **Follow up** - If you bypassed checks, fix the issues in a follow-up commit
 4. **Review carefully** - If bypassing, manually verify your changes are correct
+5. **Do not hide generated-artifact failures** - targeted generated freshness failures should be resolved, not skipped
 
 ## Examples
 
@@ -155,3 +157,16 @@ Bypassing pre-commit hooks can lead to:
 - Merge conflicts
 
 **Always verify your changes work correctly after bypassing checks.**
+
+## Generated Artifact Guidance
+
+Generated-file churn is not, by itself, a valid reason to bypass hooks.
+
+If a generated-artifact check fails:
+
+1. Read the artifact name and remediation command in the hook output.
+2. Run the declared generator for that managed artifact.
+3. Review whether the generated diff belongs in your current task scope.
+4. If the diff is unexpectedly broad, treat that as a governance defect instead of bypassing the hook.
+
+Do not use bypass flags to force through stale `docs-index.json`, stale docs-guide catalogs, or staged local-only report output.