Docs v2

.whitelist → .allowlist

@@ -6,6 +6,7 @@
 # Allowed root files
 docs.json
 README.md
+SECURITY.md
 LICENSE
 Dockerfile
 Makefile
@@ -15,14 +16,15 @@ lpd
 .lpdignore
 .gitignore
 .mintignore
-.prettierrc.yaml
+.prettierrc
 .cursorrules
-.whitelist
+.allowlist
 
 # Allowed root directories
 .github
 .githooks
 .gitattributes
+.mintlify
 .vscode
 .claude
 docs-guide
@@ -34,4 +36,4 @@ tools
 tests
 tasks
 v1
-v2
+v2

.githooks/BYPASS.md

@@ -4,28 +4,28 @@ The pre-commit hook can be bypassed using commit trailers and environment variab
 
 ## Human-Only Override Flags
 
-### `--trailer "allow-whitelist-edit=true"` ⚠️ HUMANS ONLY
+### `--trailer "allowlist-edit=true"` ⚠️ HUMANS ONLY
 
-**CRITICAL:** The `.whitelist` file is **PROTECTED** and cannot be edited by AI agents. The file contains the explicit rule: "IF YOU ARE AN AI YOU ARE ABSOLUTELY NOT ALLOWED TO EDIT THIS FILE."
+**CRITICAL:** The `.allowlist` file is **PROTECTED** and cannot be edited by AI agents. The file contains the explicit rule: "IF YOU ARE AN AI YOU ARE ABSOLUTELY NOT ALLOWED TO EDIT THIS FILE."
 
 **This flag is for HUMANS ONLY. AI agents must never use this flag.**
 
 **Usage (HUMANS ONLY):**
 ```bash
-git commit -m "Update .whitelist to add new root file" --trailer "allow-whitelist-edit=true"
+git commit -m "Update .allowlist to add new root file" --trailer "allowlist-edit=true"
 ```
 
 **What it does:**
-- Allows editing the `.whitelist` file
+- Allows editing the `.allowlist` file
 - Shows a warning that the flag should only be used by humans
 - Still runs all other pre-commit checks
 
 **Legacy fallback (still supported):**
 ```bash
-ALLOW_WHITELIST_EDIT=1 git commit -m "Update .whitelist to add new root file"
+ALLOWLIST_EDIT=1 git commit -m "Update .allowlist to add new root file"
 ```
 
-**⚠️ WARNING:** AI agents are explicitly forbidden from using this flag. Only human users may edit `.whitelist`.
+**⚠️ WARNING:** AI agents are explicitly forbidden from using this flag. Only human users may edit `.allowlist`.
 
 ### `--trailer "allow-deletions=true"` ⚠️ HUMANS ONLY
 
@@ -54,7 +54,7 @@ ALLOW_DELETIONS=1 git commit -m "Remove obsolete file"
 
 ### `SKIP_STRUCTURE_CHECK=1`
 Bypasses structure validation checks:
-- Root directory whitelist enforcement
+- Root directory allowlist enforcement
 - Snippets directory structure checks
 - v1/ frozen directory protection
 

.githooks/README.md

@@ -78,7 +78,7 @@ Current script index targets:
 - `.github/scripts/*` -> `.github/script-index.md`
 - `tests/*` -> `tests/script-index.md`
 - `tools/scripts/*` -> `tools/script-index.md`
-- `tasks/scripts/*` -> `tasks/script-index.md`
+- `tasks/scripts/*` -> `tasks/scripts/script-index.md`
 - Aggregate -> `docs-guide/scripts-index.md`
 
 Example:
@@ -141,17 +141,17 @@ git commit --no-verify -m "message"
 
 **Warning:** Only bypass if you have a legitimate reason and understand the style guide violations.
 
-### Human-Only `.whitelist` Override
+### Human-Only `.allowlist` Override
 
-The `.whitelist` file is protected by the pre-commit hook.
+The `.allowlist` file is protected by the pre-commit hook.
 
-If a human needs to intentionally edit `.whitelist`, use:
+If a human needs to intentionally edit `.allowlist`, use:
 
 ```bash
-git commit -m "Update .whitelist" --trailer "allow-whitelist-edit=true"
+git commit -m "Update .allowlist" --trailer "allowlist-edit=true"
 ```
 
-This allows `.whitelist` edits while still running all other checks.
+This allows `.allowlist` edits while still running all other checks.
 
 ### Human-Only Deletions Override
 

.githooks/install.sh

@@ -24,11 +24,16 @@
 #   Keep script behavior deterministic and update script indexes after changes.
 # Install git hooks
 
-HOOKS_DIR=".git/hooks"
+# Support both regular repos and worktrees
+GIT_COMMON_DIR=$(git rev-parse --git-common-dir 2>/dev/null)
+if [ -z "$GIT_COMMON_DIR" ] || [ "$GIT_COMMON_DIR" = "--git-common-dir" ]; then
+    GIT_COMMON_DIR=".git"
+fi
+HOOKS_DIR="$GIT_COMMON_DIR/hooks"
 SOURCE_DIR=".githooks"
 
 if [ ! -d "$HOOKS_DIR" ]; then
-    echo "Error: .git/hooks directory not found. Are you in the repository root?"
+    echo "Error: hooks directory not found at $HOOKS_DIR"
     exit 1
 fi
 

.githooks/pre-commit

@@ -1,29 +1,27 @@
 #!/bin/bash
-/**
- * @script pre-commit
- * @summary Utility script for .githooks/pre-commit.
- * @owner docs
- * @scope .githooks
- *
- * @usage
- *   node .githooks/pre-commit
- *
- * @inputs
- *   No required CLI flags; optional flags are documented inline.
- *
- * @outputs
- *   - Console output and/or file updates based on script purpose.
- *
- * @exit-codes
- *   0 = success
- *   1 = runtime or validation failure
- *
- * @examples
- *   node .githooks/pre-commit
- *
- * @notes
- *   Keep script behavior deterministic and update script indexes after changes.
- */
+# @script pre-commit
+# @summary Pre-commit hook for repository validation
+# @owner docs
+# @scope .githooks
+#
+# @usage
+#   ./.githooks/pre-commit (or invoked automatically by git)
+#
+# @inputs
+#   No required CLI flags; optional flags are documented inline.
+#
+# @outputs
+#   - Console output and/or file updates based on script purpose.
+#
+# @exit-codes
+#   0 = success
+#   1 = runtime or validation failure
+#
+# @examples
+#   ./.githooks/pre-commit
+#
+# @notes
+#   Keep script behavior deterministic and update script indexes after changes.
 # Pre-commit hook to enforce style guide compliance
 # Checks for common violations before allowing commits
 #
@@ -39,8 +37,8 @@
 #   SKIP_ALL=1             - Skip all checks (use with extreme caution)
 #
 # Human-only override flags:
-#   --trailer "allow-whitelist-edit=true" - Allow editing .whitelist file (HUMANS ONLY - AIs must never use this)
-#   ALLOW_WHITELIST_EDIT=1                - Legacy fallback for automation contexts
+#   --trailer "allowlist-edit=true" - Allow editing .allowlist file (HUMANS ONLY - AIs must never use this)
+#   ALLOWLIST_EDIT=1                - Legacy fallback for automation contexts
 #   --trailer "allow-deletions=true"      - Allow file deletions (HUMANS ONLY - AIs must never use this)
 #   ALLOW_DELETIONS=1                      - Legacy fallback for automation contexts
 
@@ -124,7 +122,7 @@ if [ -n "$DELETED_FILES" ]; then
         echo "  1. READ THE FILES to understand their content and purpose"
         echo "  2. CHECK THE MIGRATION PLAN: tasks/plan/migration-plan.md"
         echo "  3. CHECK THE README: README.md (source of truth for structure)"
-        echo "  4. CHECK THE WHITELIST: .whitelist (allowed root files)"
+        echo "  4. CHECK THE ALLOWLIST: .allowlist (allowed root files)"
         echo "  5. DETERMINE CORRECT LOCATION based on file content and structure rules"
         echo "  6. MOVE files to correct location using 'git mv' (NOT delete+add)"
         echo ""
@@ -158,63 +156,63 @@ if [ -n "$DELETED_FILES" ]; then
     fi
 fi
 
-# Check for .whitelist file changes (BLOCKED for AIs, requires human override)
-WHITELIST_CHANGES=$(git diff --cached --name-only | grep -E '^\.whitelist$|^\.whitelist ' || true)
+# Check for .allowlist file changes (BLOCKED for AIs, requires human override)
+WHITELIST_CHANGES=$(git diff --cached --name-only | grep -E '^\.allowlist$|^\.allowlist ' || true)
 if [ -n "$WHITELIST_CHANGES" ]; then
-    ALLOW_WHITELIST_EDIT=${ALLOW_WHITELIST_EDIT:-0}
+    ALLOWLIST_EDIT=${ALLOWLIST_EDIT:-0}
 
-    if [ "$ALLOW_WHITELIST_EDIT" != "1" ]; then
-        if has_human_override_trailer "allow-whitelist-edit"; then
-            ALLOW_WHITELIST_EDIT=1
+    if [ "$ALLOWLIST_EDIT" != "1" ]; then
+        if has_human_override_trailer "allowlist-edit"; then
+            ALLOWLIST_EDIT=1
         fi
     fi
 
-    if [ "$ALLOW_WHITELIST_EDIT" != "1" ]; then
+    if [ "$ALLOWLIST_EDIT" != "1" ]; then
         VIOLATIONS=$((VIOLATIONS + 1))
         echo -e "${RED}╔═══════════════════════════════════════════════════════════════╗${NC}"
-        echo -e "${RED}║  .whitelist FILE CHANGES BLOCKED                              ║${NC}"
+        echo -e "${RED}║  .allowlist FILE CHANGES BLOCKED                              ║${NC}"
         echo -e "${RED}╚═══════════════════════════════════════════════════════════════╝${NC}"
         echo ""
-        echo -e "${RED}Attempted changes to .whitelist:${NC}"
-        echo -e "${RED}  ❌ .whitelist${NC}"
+        echo -e "${RED}Attempted changes to .allowlist:${NC}"
+        echo -e "${RED}  ❌ .allowlist${NC}"
         echo ""
-        echo -e "${YELLOW}⚠️  CRITICAL: .whitelist file is protected.${NC}"
-        echo -e "${YELLOW}   The .whitelist file contains the rule:${NC}"
+        echo -e "${YELLOW}⚠️  CRITICAL: .allowlist file is protected.${NC}"
+        echo -e "${YELLOW}   The .allowlist file contains the rule:${NC}"
         echo -e "${YELLOW}   'IF YOU ARE AN AI YOU ARE ABSOLUTELY NOT ALLOWED TO EDIT THIS FILE.'${NC}"
         echo ""
-        echo -e "${YELLOW}To allow editing .whitelist (HUMANS ONLY):${NC}"
-        echo -e "${YELLOW}  git commit -m \"your message\" --trailer \"allow-whitelist-edit=true\"${NC}"
-        echo -e "${YELLOW}  (legacy fallback: ALLOW_WHITELIST_EDIT=1 git commit -m \"your message\")${NC}"
+        echo -e "${YELLOW}To allow editing .allowlist (HUMANS ONLY):${NC}"
+        echo -e "${YELLOW}  git commit -m \"your message\" --trailer \"allowlist-edit=true\"${NC}"
+        echo -e "${YELLOW}  (legacy fallback: ALLOWLIST_EDIT=1 git commit -m \"your message\")${NC}"
         echo ""
-        echo -e "${RED}Commit blocked. Only humans may edit .whitelist with explicit override.${NC}"
+        echo -e "${RED}Commit blocked. Only humans may edit .allowlist with explicit override.${NC}"
         echo ""
         exit 1
     else
-        echo -e "${YELLOW}⚠️  WARNING: .whitelist edit allowed (human override detected)${NC}"
+        echo -e "${YELLOW}⚠️  WARNING: .allowlist edit allowed (human override detected)${NC}"
         echo -e "${YELLOW}   This flag should ONLY be used by humans, never by AI agents.${NC}"
     fi
 fi
 
-# Check root directory structure against whitelist
+# Check root directory structure against allowlist
 if [ "$SKIP_STRUCTURE_CHECK" = "1" ]; then
     echo -e "${YELLOW}⚠️  Structure checks bypassed (SKIP_STRUCTURE_CHECK=1)${NC}"
 else
     echo -e "${YELLOW}🔍 Checking root directory structure...${NC}"
 
-    if [ ! -f ".whitelist" ]; then
-        echo -e "${YELLOW}⚠️  .whitelist file not found, skipping root structure check${NC}"
+    if [ ! -f ".allowlist" ]; then
+        echo -e "${YELLOW}⚠️  .allowlist file not found, skipping root structure check${NC}"
     else
-    # Read whitelist (skip comments and empty lines)
-    WHITELIST=$(grep -v '^#' .whitelist | grep -v '^$' | tr '\n' '|' | sed 's/|$//')
+    # Read allowlist (skip comments and empty lines)
+    ALLOWLIST=$(grep -v '^#' .allowlist | grep -v '^$' | tr '\n' '|' | sed 's/|$//')
 
-    if [ -z "$WHITELIST" ]; then
-        echo -e "${YELLOW}⚠️  .whitelist is empty, skipping root structure check${NC}"
+    if [ -z "$ALLOWLIST" ]; then
+        echo -e "${YELLOW}⚠️  .allowlist is empty, skipping root structure check${NC}"
     else
-        # Check for new root files (not in whitelist)
-        NEW_ROOT_FILES=$(git diff --cached --name-only --diff-filter=A | grep -E '^[^/]+$' | grep -vE "^($WHITELIST)$" || true)
+        # Check for new root files (not in allowlist)
+        NEW_ROOT_FILES=$(git diff --cached --name-only --diff-filter=A | grep -E '^[^/]+$' | grep -vE "^($ALLOWLIST)$" || true)
 
-        # Check for new root directories (not in whitelist)
-        NEW_ROOT_DIRS=$(git diff --cached --name-only --diff-filter=A | grep -E '^[^/]+/' | cut -d'/' -f1 | sort -u | grep -vE "^($WHITELIST)$" || true)
+        # Check for new root directories (not in allowlist)
+        NEW_ROOT_DIRS=$(git diff --cached --name-only --diff-filter=A | grep -E '^[^/]+/' | cut -d'/' -f1 | sort -u | grep -vE "^($ALLOWLIST)$" || true)
 
         if [ -n "$NEW_ROOT_FILES" ] || [ -n "$NEW_ROOT_DIRS" ]; then
             VIOLATIONS=$((VIOLATIONS + 1))
@@ -245,7 +243,7 @@ else
                 echo ""
             fi
 
-            echo -e "${YELLOW}Allowed root files/directories are listed in .whitelist${NC}"
+            echo -e "${YELLOW}Allowed root files/directories are listed in .allowlist${NC}"
             echo -e "${YELLOW}See contribute/STRUCTURE.md for repository structure rules${NC}"
             echo ""
         else
@@ -503,6 +501,31 @@ else
                 fi
             fi
 
+            # Docs-guide source-of-truth checks are advisory during stabilization
+            if [ -f "tests/unit/docs-guide-sot.test.js" ]; then
+                echo -e "${YELLOW}Running docs-guide SoT checks (advisory)...${NC}"
+                if node tests/unit/docs-guide-sot.test.js 2>&1; then
+                    echo -e "${GREEN}✓ Docs-guide SoT checks passed${NC}"
+                else
+                    WARNINGS+=("⚠️ Docs-guide SoT checks need updates - run node tests/unit/docs-guide-sot.test.js")
+                    echo -e "${YELLOW}⚠️  Docs-guide SoT checks reported advisory issues${NC}"
+                fi
+            fi
+
+            # Staged link audit (internal links/imports strict, external links classify-only)
+            if [ -f "tests/integration/v2-link-audit.js" ]; then
+                echo -e "${YELLOW}Running staged V2 link audit...${NC}"
+                if node tests/integration/v2-link-audit.js --staged --strict --report /tmp/livepeer-link-audit-precommit.md 2>&1; then
+                    echo -e "${GREEN}✓ Staged V2 link audit passed${NC}"
+                else
+                    LINK_AUDIT_EXIT=$?
+                    if [ $LINK_AUDIT_EXIT -ne 0 ]; then
+                        VIOLATIONS=$((VIOLATIONS + 1))
+                        WARNINGS+=("❌ Staged V2 link audit failed - see output above")
+                    fi
+                fi
+            fi
+
             # Domain page load audit (stable report path in tests/reports)
             if [ -f "tests/integration/domain-pages-audit.js" ]; then
                 echo -e "${YELLOW}Running domain page load audit (staged pages)...${NC}"
@@ -559,6 +582,31 @@ else
                 fi
             fi
 
+            # Docs-guide source-of-truth checks are advisory during stabilization
+            if [ -f "tests/unit/docs-guide-sot.test.js" ]; then
+                echo -e "${YELLOW}Running docs-guide SoT checks (advisory)...${NC}"
+                if node tests/unit/docs-guide-sot.test.js 2>&1; then
+                    echo -e "${GREEN}✓ Docs-guide SoT checks passed${NC}"
+                else
+                    WARNINGS+=("⚠️ Docs-guide SoT checks need updates - run node tests/unit/docs-guide-sot.test.js")
+                    echo -e "${YELLOW}⚠️  Docs-guide SoT checks reported advisory issues${NC}"
+                fi
+            fi
+
+            # Staged link audit (internal links/imports strict, external links classify-only)
+            if [ -f "tests/integration/v2-link-audit.js" ]; then
+                echo -e "${YELLOW}Running staged V2 link audit...${NC}"
+                if node tests/integration/v2-link-audit.js --staged --strict --report /tmp/livepeer-link-audit-precommit.md 2>&1; then
+                    echo -e "${GREEN}✓ Staged V2 link audit passed${NC}"
+                else
+                    LINK_AUDIT_EXIT=$?
+                    if [ $LINK_AUDIT_EXIT -ne 0 ]; then
+                        VIOLATIONS=$((VIOLATIONS + 1))
+                        WARNINGS+=("❌ Staged V2 link audit failed - see output above")
+                    fi
+                fi
+            fi
+
             # Domain page load audit (stable report path in tests/reports)
             if [ -f "tests/integration/domain-pages-audit.js" ]; then
                 echo -e "${YELLOW}Running domain page load audit (staged pages)...${NC}"

.githooks/script-index.md

@@ -6,7 +6,7 @@
 | Script | Summary | Usage | Owner |
 |---|---|---|---|
 | `.githooks/install.sh` | Utility script for .githooks/install.sh. | `bash .githooks/install.sh` | docs |
-| `.githooks/pre-commit` | Utility script for .githooks/pre-commit. | `node .githooks/pre-commit` | docs |
+| `.githooks/pre-commit` | Pre-commit hook for repository validation | `./.githooks/pre-commit (or invoked automatically by git)` | docs |
 | `.githooks/pre-commit-no-deletions` | Utility script for .githooks/pre-commit-no-deletions. | `node .githooks/pre-commit-no-deletions` | docs |
 | `.githooks/server-manager.js` | Utility script for .githooks/server-manager.js. | `node .githooks/server-manager.js` | docs |
 | `.githooks/verify-browser.js` | Utility script for .githooks/verify-browser.js. | `node .githooks/verify-browser.js` | docs |

.github/AGENTS.md

@@ -35,7 +35,7 @@ destructive or history-altering actions.
 ### Critical Structure Rules
 
 1. **Root Directory** - Only essential files allowed:
-   - ✅ Allowed: `docs.json`, `package.json`, `README.md`, `LICENSE`, `Dockerfile`, `Makefile`, `style.css`, `.gitignore`, `.mintignore`, `.whitelist`
+   - ✅ Allowed: `docs.json`, `package.json`, `README.md`, `LICENSE`, `Dockerfile`, `Makefile`, `style.css`, `.gitignore`, `.mintignore`, `.allowlist`
    - ❌ Forbidden: Scripts, config files, documentation files, temporary files, OpenAPI specs
    - **CRITICAL:** Mintlify only allows ONE CSS file (`style.css`) at root - NO `styles/` folder
 
@@ -58,7 +58,7 @@ destructive or history-altering actions.
    - ❌ Components cannot import other components
 
 4. **Enforcement** - Structure is enforced:
-   - `.whitelist` file lists allowed root files/directories
+   - `.allowlist` file lists allowed root files/directories
    - Pre-commit hook blocks unauthorized root files/directories
    - Always check structure rules before creating new files