chore(docs): merge docs-v2-dev-draft into docs-v2

.allowlist

@@ -1,7 +1,5 @@
 # Generated from operations/governance/config/root-governance.json
-
 # Do not edit manually. Regenerate with:
-
 # node operations/scripts/generators/governance/root/generate-root-governance-artifacts.js --write
 
 .allowlist
@@ -17,7 +15,6 @@
 .mintignore
 .mintlify
 .prettierrc
-jsconfig.json
 .vscode
 .windsurf
 AGENTS.md
@@ -26,6 +23,7 @@ api
 docs-guide
 docs-index.json
 docs.json
+jsconfig.json
 LICENSE
 llms.txt
 Makefile

.claude/CLAUDE.md

@@ -33,6 +33,9 @@ Alison Haire (Wonderland). Documentation lead. Decision authority.
 | Tracker | Master task list, backlog, Notion sync | Active | 2026-03-29 |
 | About | About tab — IA lock + content | Active | 2026-03-29 |
 | Cleanup | Repo cleanup | Active | 2026-03-29 |
+| Principal Engineer Audit | 5-category docs-as-infra audit (architecture, auto-doc pipeline, script quality, DX, security). 5 parallel agents → 24 ranked findings (4H/13M/7L). Report at `workspace/thread-outputs/audits/docs-as-infra-principal-engineer-audit-2026-05-26.md`. Top 3 fix recipes designed (SHA-pin Actions + gitleaks; discovery-based dispatch + registry validator + all-types catalog assertion; shared atomic-write + signal-handler lib) | Done — audit only, no code changes | 2026-05-26 |
+| Principal Engineer Audit — Sprint 1 implementation | **Phase A:** safe-io lib (`tools/lib/bootstrap/safe-io.js`); registry concern/type validator (`generate-script-registry.js`, report-only default, `--strict` env gate); catalog all-types drift assertion (`script-docs.test.js`); gitleaks workflow + pre-commit HARD GATE 6; allowlist-extended `.github/dependabot.yml`. **Phase B pilots:** discovery pattern on `dispatch-health-check.js` (same 6 pipelines, supports `@pipeline draft` opt-out); SHA-pinned both `peter-evans/create-pull-request@v7` occurrences to `271a8d03…` (only third-party Action in repo); migrated `remediate-us-spelling.js` to `atomicWrite`; new write-safety validator. **Phase C:** added pipeline-orphans validator as substitute for naive bulk discovery (audit recipe was wrong — most metas run curated subsets, not all siblings); bulk-migrated 135 `fs.writeFileSync` sites to `atomicWrite` via one-shot helper — write-safety violations now **135 → 0** (only 9 remaining unguarded headless-browser launches, deferred to next thread). All verification green: catalog test passes, registry generator runs, orphans clean, safe-io smoke OK. | Done | 2026-05-27 |
+| Principal Engineer Audit — Sprint 1 continuation (Items 1–4) | **Item 1:** Wired all 9 unguarded headless-browser launches to `registerCleanup` — write-safety violations now **9 → 0** across both categories. One template-literal child-process launch in `regression-bisect.js:203` left unmodified (separate process, short-lived, has its own try/finally). **Item 2:** Promoted four gates to blocking in `dispatch-governance.yml` pipeline-tests job: `CATALOG_STRICT=1`, `check-pipeline-orphans --strict`, `check-write-safety --strict`, script-logic unit tests. `REGISTRY_STRICT` deliberately NOT promoted — 72 pollution remains pending Item 3 backfill. **Item 3:** Categorised the 159 polluted registry entries (45 indirect-library + 115 operational). Sweep-patched 87 (4 `.githooks/*` manually + 85 via one-shot helper at `/tmp/sweep-pollution.js`) — pollution dropped **159 → 72 (55% reduction)**. Added `testing` + `dev-tools` to `LEGACY_CONCERN_MAP` in `script-governance-config.js`. **Hit edit-loop hook on `generate-script-registry.js`** after 5 edits — the deferred `deriveFromPath()` enhancement (5 new path-pattern branches for `.githooks/`/`operations/tests/`/`tools/dev/`/`tools/lib/`/`workspace/scripts/`) needs to land in a fresh-edit-counter session. **Item 4:** Scaffolded the unit-test framework: `tools/lib/bootstrap/test-helpers.js` (mkTmpDir, runScript, assertExit, suite/test mini-API) + `operations/tests/unit/script-tests/run-all.js` (walks `script-tests/**/*.test.js`). Wrote 5 representative tests (25 assertions) across libraries/validators/dispatch/generators — full suite runs in 1.6s. Wired the runner into the pipeline-tests CI job. **Residual:** 72 polluted registry entries + 27 operational-script JSDoc reclassifications + `deriveFromPath()` enhancement queued for next thread. | Done — Items 1–4 substantially shipped | 2026-05-27 |
 | MASTER CLEAN | Consolidate all frameworks, tab content, tasks into one folder | Active — audit done, awaiting approval to build | 2026-03-29 |
 | Contracts & Changelogs | Production audit complete (30 items, 20 fixes). OG images generated. Deprecated components removed. SEO/AEO surfaces corrected. Remaining: cherry-pick workflow to docs-v2 for dispatch test (BL-023, P0) | Active — audit done | 2026-03-31 |
 | Changelog Pipeline | 24 targets registered, 19 resource pages populated, nav grouped into 5 categories, script cleanForMdx + commit labels fixed. Remaining: changelog.mdx format fix, LLM commits-mode feature, managed:true activation | Active | 2026-03-30 |
@@ -55,6 +58,7 @@ Alison Haire (Wonderland). Documentation lead. Decision authority.
 | Agent Creation Skills | 3 skills (`/create-component`, `/create-script`, `/create-action`) + `generate-component-snippets.js`. Full governance compliance, self-documenting pipelines, VS Code tooling updates. Fills actions-audit.json and concurrency group gaps | Done | 2026-04-08 |
 | Styles Governance | Full pipeline: audit (6 categories), remediator (14 fix types + --verify regression check), self-documenting generator, GH Actions workflow with regression step. Style guide (10 new sections + pixel spacing + brand tokens). WCAG focus-visible + responsive CSS. CoinGecko exchanges + go-livepeer config flags pipelines. Badge reference + engineering guide. 0 non-mermaid violations (3,986 → 0). 68 mermaid dark-mode variants accepted | Done | 2026-04-09 |
 | UK Spelling + Em-Dash Sweep | remediate-em-dashes.js + remediate-us-spelling.js with --write --verify across v2/. First pass: 21 em-dash + 79 spelling. User flagged scope concern; investigation found two zone-detection bugs in the existing scripts: (1) em-dash script missed multi-line frontmatter block scalars (`description: >-`); (2) spelling script zoned ENTIRE frontmatter as skip, missing user-facing keys. Both scripts patched (block-scalar handling + per-key zoning of title/sidebarTitle/description/keywords). Second pass: +42 em-dash (38 files) + 20 spelling (13 files). Independent audit: 0 em-dashes remaining; 38 UK-spelling hits remain — all in technical identifier references (35 React prop name docs in component-library tables, 2 markdown link paths, 1 filename reference). Flags raised: program→programme rule unconditional; component-library prop-doc tables need rule exclusion or skip-zone | Done | 2026-05-04 |
+| Production Cleanup | Consolidate `docs-v2-dev-draft` into production-clean state for merge to `docs-v2`. Scope rule: internal-stays + `.mintignore`'d (one repo, two states). 5 registers scaffolded at `workspace/thread-outputs/production-cleanup/` (cleanup-ledger, gold-standard, feature-catalogue, future-upgrades, needs-collab). Phase 0 done. Phase 1: 5 read-only audit agents running in background (A root+generated, B v2-content, C workspaces — retried after BSD/GNU `find -printf` / `awk strftime` error, D docs-guide+ai-tools+configs, E cross-cutting hotspots). Phase 2 surface-by-surface cleanup follows audit landings. 3 surfaces deferred to separate chats with consolidated briefs: `operations/scripts` (250), `snippets/components` (component library), `.github/workflows` (55) | Active — Phase 1 audits running | 2026-05-25 |
 | Repo Features Documentation Audit | Two-track effort consolidated. **Track A** (`workspace/plan/active/REPO-FEATURES-DOCS-AUDIT/`): locked D-DG-01..D-DG-13 IA migration plan, source-of-truth matrix, feature verification, framework/policy gap report, archive deletion queue, `check-docs-guide-reference-freshness.js` validator. **Track B** (`workspace/thread-outputs/repo-docs-consolidation/`): 7 product-forward audits + 00-SYNTHESIS.md (110+ features, 80+ community-help opportunities). **Session 2 (2026-05-19, plan: `~/.claude/plans/ok-i-want-a-rippling-metcalfe.md`)**: rewrote `docs-guide/index.mdx` as the canonical docs-as-infrastructure overview (Hero + Quickstart + Philosophy + Personas + IA Tree + 8 feature sections + Ownerless Mgmt + Community Help). Built two new pages: `docs-guide/tooling/mintlify-built-ins.mdx` (Phase 2) and `docs-guide/contributing/community-help.mdx` (Phase 3 — 80+ opportunities indexed by feature domain with file paths + acceptance criteria). Refreshed `README.md` with live counts (341 scripts, 59 workflows, 35 SKILL.md, 132 components, 1,128 v2 .mdx, 693 docs.json routes — corrected from synthesis estimates). Refreshed public `contribute-to-the-docs.mdx` (lpd workflow, `docs-v2` branch, proposal section removed) and filled in empty public `lpd-cli.mdx`. Render-verified: all 5 touched routes return HTTP 200; lint-structure 0 blocking on new files. One blocked item: `documentation-overview.mdx` retirement to a thin `<IndexSource />` pointer is blocked by a render-gate cache that won't clear until contribute-to-the-docs passes Puppeteer (page renders fine via curl in 0.5s; headless times out at 30s). Needs manual cache-clear or longer Puppeteer timeout to ship — non-blocking for everything else. **Session 3 (2026-05-22)**: RFP Phase 1 — filled 6 empty/skeletal Internal stubs from canonical sources (`v2/internal/rfp/outcomes.mdx`, `rfp/deliverables.mdx`, `definitions.mdx`, `ecosystem.mdx`, `references.mdx`, `overview/strategic-alignment.mdx`). All 6 pass static checks (frontmatter, no em-dashes, structure); smoke-test server-start timed out at 5min so render-verify is structural-only. Appended **Part 13 addendum** (2026-02-21 → 2026-05-22) to `v2/internal/rfp/reports/livepeer-docs-v2-report.md` preserving the original 2026-02-21 record intact — covers numbers refresh (320 scripts, 11 workflows, 35 SKILL.md, 1,128 v2 .mdx, 686 docs.json routes, 132 components), the substantial post-handover work (ownerless governance spine, 34 AI skills, agent adapters, GitHub Actions 4-tier refactor, contracts pipeline gold-standard, styles pipeline, asset/changelog pipelines, contributor toolchain), re-graded RFP matrix rows (Changelog Cancelled → Partial; Tutorials Incomplete → Completed; WCAG audited), and named the new post-handover gaps (218 JSDoc backfill, 307-row v2 cleanup, OpenAPI fetcher 2/5, manual OG/SEO, dead Luma feed, stale governance map). Then user picked orphans #2 + #3 (voice-rules collapse, dev-tools retire). **Voice-rules collapse done**: voice-and-copy.mdx absorbed unique voice-rules content (UK English table extended +5 rows: optimise/utilise/customise/analyse/fibre; per-audience table extended with Tone + Lead-with columns; banned phrases extended with "what it takes" / "not just X" / "can generate|may produce" in value claims; new Heading rules section). voice-rules.mdx (27 lines) is a thin retired pointer to voice-and-copy. 3 inbound links updated in governance-index.mdx. **Dev-tools retire done**: contributor-tools.mdx absorbed the VS Code snippets reference (5 files, live counts 23/25/113/125/26, generator command). dev-tools.mdx (39 lines) is a thin retired pointer to contributor-tools / lpd-cli / lpd-mdx-preview. Inbound links updated in source-of-truth-guide.mdx and canonical/Mintlify/index.md; contributor-tools Related section refreshed. UI-2 and TOOL-3 community-help items marked DONE 2026-05-22 in `docs-guide/contributing/community-help.mdx`. Remaining: contracts-pipeline merge into data-integrations.mdx (needs merge-direction call), counts sweep. | Active — RFP Phase 1 + Part 13 + 2 orphan retirements done; contracts-pipeline merge + counts sweep deferred | 2026-05-22 |
 
 **Rule:** When you finish a task or change status, update your row in this table before closing. If the master-tasks.md file has a matching item, update that too.

.githooks/post-merge

@@ -0,0 +1,84 @@
+#!/bin/bash
+# @script      post-merge
+# @type        dispatch
+# @concern     governance
+# @niche       hooks
+# @category    orchestrator
+# @purpose     Auto-refresh generated catalogs after merge/pull so dev branches stay in sync with source-of-truth
+# @scope       .githooks
+# @domain      docs
+# @pipeline    P0 (post-merge, hook entry point)
+# @usage       Runs automatically after `git pull` or `git merge` (via core.hooksPath = .githooks)
+#
+# Behaviour:
+# - Detects whether the merge brought in changes to script source / workflows / docs.json / v2 MDX / components.
+# - If yes, runs `dispatch-governance-sync.js --write` which regenerates:
+#   * docs-guide/catalog/{workflows,pages,components,scripts}-catalog.mdx
+#   * docs-guide/repo-ops/config/{repo-governance,root-governance}-map.mdx
+#   * .github/workspace/actions-library/* (via separate action-pages generator)
+#   * sitemap-ai.xml, llms.txt (via discoverability dispatcher)
+#   * docs-index.json
+# - Catalog drift then surfaces as a NEW change in `git status` for the dev to commit
+#   in a follow-up "chore: sync generated catalogs" commit.
+#
+# Bypass:
+#   SKIP_POSTMERGE_SYNC=1  Skip the sync (useful for fast iteration cycles or rebases)
+#
+# Why this exists: see workspace/reports/governance/pipeline-inventory.md — the canonical
+# auto-pop trigger is the GitHub Actions post-merge job on docs-v2, but dev branches
+# (docs-v2-dev, docs-v2-dev-draft) don't get that fire. This hook fills the gap locally.
+
+set -euo pipefail
+
+# Bypass
+if [ "${SKIP_POSTMERGE_SYNC:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Only run if interesting files changed in the merge
+INTERESTING_PATHS_RE='^(operations/scripts|tools/scripts|\.github/workflows|docs\.json|v2/.*\.mdx$|snippets/components/.*\.(jsx|json)$|snippets/data|operations/governance/config)'
+
+# git diff between the merge commit's two parents
+CHANGED=$(git diff --name-only ORIG_HEAD HEAD 2>/dev/null | grep -E "$INTERESTING_PATHS_RE" | head -5 || true)
+if [ -z "$CHANGED" ]; then
+  # No relevant changes — skip the sync entirely.
+  exit 0
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
+SYNC_SCRIPT="$REPO_ROOT/operations/scripts/dispatch/governance/dispatch-governance-sync.js"
+
+if [ ! -f "$SYNC_SCRIPT" ]; then
+  # Sync script missing — silent skip (don't block the merge).
+  exit 0
+fi
+
+echo ""
+echo "═══════════════════════════════════════════════════════════════"
+echo "Post-merge: refreshing generated catalogs (NODE_PATH=tools/node_modules)"
+echo "Changed files indicating sync needed (first 5):"
+echo "$CHANGED" | sed 's/^/  /'
+echo ""
+echo "Running: dispatch-governance-sync.js --write"
+echo "(skip next time with SKIP_POSTMERGE_SYNC=1 git pull)"
+echo "───────────────────────────────────────────────────────────────"
+
+cd "$REPO_ROOT"
+if NODE_PATH=tools/node_modules node "$SYNC_SCRIPT" --write 2>&1 | tail -20; then
+  echo ""
+  echo "✓ Catalog sync complete"
+else
+  echo ""
+  echo "⚠ Catalog sync had errors — check output above. The merge itself completed."
+fi
+
+# Show what changed (so dev knows what to commit next)
+NEW_CHANGES=$(git status --short 2>/dev/null | grep -v "^ M\|^M " | wc -l | tr -d ' ')
+DIRTY_CHANGES=$(git status --short 2>/dev/null | wc -l | tr -d ' ')
+if [ "$DIRTY_CHANGES" -gt 0 ]; then
+  echo ""
+  echo "Catalog refresh produced changes — review with: git status"
+  echo "Commit with: git add -u && git commit -m 'chore: sync generated catalogs'"
+fi
+
+exit 0

.githooks/pre-commit

@@ -1,5 +1,8 @@
 #!/bin/bash
 # @script            pre-commit
+# @type              dispatch
+# @concern           governance
+# @niche             hooks
 # @category          orchestrator
 # @purpose           infrastructure:pipeline-orchestration
 # @scope             .githooks
@@ -365,6 +368,21 @@ NODE
     fi
 fi
 
+# Folder allowlist check (D-GOV-08 layer 2) — runs check-folder-allowlist.js against staged paths
+if [ "$SKIP_STRUCTURE_CHECK" != "1" ] && [ -f operations/scripts/validators/governance/repo/check-folder-allowlist.js ]; then
+    if ! node operations/scripts/validators/governance/repo/check-folder-allowlist.js >/dev/null 2>&1; then
+        VIOLATIONS=$((VIOLATIONS + 1))
+        echo -e "${RED}╔═══════════════════════════════════════════════════════════════╗${NC}"
+        echo -e "${RED}║  D-GOV-08: FOLDER ALLOWLIST VIOLATIONS DETECTED              ║${NC}"
+        echo -e "${RED}╚═══════════════════════════════════════════════════════════════╝${NC}"
+        node operations/scripts/validators/governance/repo/check-folder-allowlist.js 2>&1 | head -30 || true
+        echo ""
+        echo -e "${YELLOW}Run: node operations/scripts/dispatch/governance/dispatch-folder-allowlist.js --mode manual --write${NC}"
+        echo -e "${YELLOW}to archive drift files via git mv to x-archive/.${NC}"
+        WARNINGS+=("❌ Folder allowlist violations (D-GOV-08)")
+    fi
+fi
+
 # Root directory structure against allowlist
 if [ "$SKIP_STRUCTURE_CHECK" = "1" ]; then
     echo -e "${YELLOW}⚠️  Structure checks bypassed (SKIP_STRUCTURE_CHECK=1)${NC}"
@@ -425,6 +443,20 @@ if [ "$SKIP_STRUCTURE_CHECK" != "1" ]; then
     fi
 fi
 
+# ═══════════════════════════════════════════════════════════════
+# HARD GATE 6: SECRET LEAK (gitleaks, if installed)
+# ═══════════════════════════════════════════════════════════════
+# Authoritative scan runs in CI (.github/workflows/interface-governance-secret-scan.yml).
+# This local short-circuit catches the obvious case before push so the contributor
+# can rotate before the leak reaches origin. Silent no-op if gitleaks isn't on PATH —
+# CI is still the source of truth.
+if [ "$SKIP_ALL" != "1" ] && command -v gitleaks >/dev/null 2>&1; then
+    if ! gitleaks protect --staged --redact --no-banner >/dev/null 2>&1; then
+        VIOLATIONS=$((VIOLATIONS + 1))
+        WARNINGS+=("Secret detected in staged changes (gitleaks). Rotate the leaked credential, then unstage and recommit.")
+    fi
+fi
+
 # ═══════════════════════════════════════════════════════════════
 # VERDICT
 # ═══════════════════════════════════════════════════════════════

.githooks/pre-commit-no-deletions

@@ -1,5 +1,8 @@
 #!/bin/bash
 # @script            pre-commit-no-deletions
+# @type              dispatch
+# @concern           governance
+# @niche             hooks
 # @category          orchestrator
 # @purpose           infrastructure:pipeline-orchestration
 # @scope             .githooks