fix: CI/CD robustness, search path resolution, and test self-sufficiency

.github/workflows/coverage.yml

@@ -24,8 +24,8 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install requests>=2.32.0
-          pip install pytest pytest-cov pytest-asyncio pytest-mock pyyaml coverage
+          python3 -m pip install requests>=2.32.0
+          python3 -m pip install pytest pytest-cov pytest-asyncio pytest-mock pyyaml coverage
 
       - name: Generate coverage
         run: |

.github/workflows/test.yml

@@ -23,8 +23,8 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install requests>=2.32.0
-          pip install pytest pytest-cov pytest-asyncio pytest-mock pyyaml
+          python3 -m pip install requests>=2.32.0
+          python3 -m pip install pytest pytest-cov pytest-asyncio pytest-mock pyyaml
 
       - name: Run unit tests
         run: |
@@ -53,7 +53,7 @@ jobs:
       - name: Generate coverage reports
         run: |
           if [ -f "coverage.xml" ]; then
-            pip install coverage
+            python3 -m pip install coverage
             # Generate HTML coverage report
             coverage html -d htmlcov
             # Generate JSON coverage report
@@ -66,7 +66,7 @@ jobs:
       - name: Check coverage threshold
         run: |
           if [ -f "coverage.xml" ]; then
-            pip install coverage
+            python3 -m pip install coverage
             coverage report --fail-under=75 || echo "Coverage below 75% threshold - current: 78.7%"
           else
             echo "Skipping coverage check - no coverage data"
@@ -137,7 +137,7 @@ jobs:
         run: |
           # Test that enhanced mode works with Python
           bash -c 'set -e
-          pip install requests>=2.32.0
+          python3 -m pip install requests>=2.32.0
 
           # Verify Python scripts exist
           if [ -f "scripts/main.py" ] && [ -f "scripts/lookup_paths.py" ]; then

.github/workflows/update-docs.yml

@@ -27,8 +27,8 @@ jobs:
 
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        pip install -r scripts/requirements.txt
+        python3 -m pip install --upgrade pip
+        python3 -m pip install -r scripts/requirements.txt
 
     # =================================================================
     # SAFEGUARD: Count files BEFORE fetch to detect mass deletions
@@ -46,7 +46,7 @@ jobs:
         GITHUB_REPOSITORY: ${{ github.repository }}
         GITHUB_REF_NAME: ${{ github.ref_name }}
       run: |
-        python scripts/fetch_claude_docs.py || echo "fetch_failed=true" >> $GITHUB_OUTPUT
+        python3 scripts/fetch_claude_docs.py || echo "fetch_failed=true" >> $GITHUB_OUTPUT
       continue-on-error: true
 
     # =================================================================
@@ -93,6 +93,14 @@ jobs:
 
         echo "✅ Safeguard validation passed: $AFTER files present"
 
+    - name: Build search index
+      if: steps.validate-safeguard.outputs.safeguard_triggered != 'true'
+      continue-on-error: true
+      run: |
+        echo "Building full-text search index..."
+        python3 scripts/build_search_index.py || echo "⚠️ Search index build failed — content search may be unavailable"
+        echo "✅ Search index step complete"
+
     - name: Check for changes
       id: verify-changed-files
       run: |
@@ -103,7 +111,7 @@ jobs:
       id: commit-msg
       run: |
         # Stage changes to see what will be committed
-        git add -A docs/
+        git add -A docs/ paths_manifest.json
 
         # Get list of changed files with proper quoting
         # Using printf with %q for shell-safe quoting would be ideal, but not available in all shells

.github/workflows/validate.yml

@@ -19,11 +19,11 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install requests>=2.32.0
-          pip install pytest pytest-cov pytest-asyncio pytest-mock pyyaml
+          python3 -m pip install requests>=2.32.0
+          python3 -m pip install pytest pytest-cov pytest-asyncio pytest-mock pyyaml
 
       - name: Validate all paths reachable
-        run: python scripts/lookup_paths.py --validate-all
+        run: python3 scripts/lookup_paths.py --validate-all
 
       - name: Run validation tests
         run: |

.gitignore

@@ -93,6 +93,9 @@ upstream/
 # Archive folder (legacy/orphaned scripts)
 archive/
 
+# Plan documents (local development only, contain local paths)
+docs/plans/
+
 # ============================================================================
 # Documentation & Tracking Files (DO NOT COMMIT)
 # ============================================================================

CLAUDE.md

@@ -21,10 +21,10 @@ The docs are periodically updated via GitHub Actions with safeguards to prevent
 This repository uses a **graceful degradation** approach:
 
 **Installation** (always the same):
-- 573 documentation paths tracked in manifest (6 categories)
-- 571 files downloaded
+- Documentation paths tracked in manifest (6 categories)
+- Documentation files downloaded
 - Python scripts for enhanced features
-- Full test suite (294 tests) and GitHub workflows
+- Full test suite (303 tests) and GitHub workflows
 
 **Runtime Features** (Python-dependent):
 - **Without Python 3.9+**: Basic documentation reading via shell scripts
@@ -395,7 +395,7 @@ When Python 3.9+ is installed, these additional capabilities are available:
 - **Full-text search**: `--search "keyword"` searches across all documentation content
 - **Category filtering**: `--category api` lists paths in specific categories
 - **Path validation**: `--validate` checks documentation integrity
-- **Active documentation**: Access to 573 paths across 6 categories:
+- **Active documentation**: Access to paths across 6 categories:
   - API Reference (377 paths, 65.8%) - Includes multi-language SDK docs (Python, TypeScript, Go, Java, Kotlin, Ruby)
   - Core Documentation (82 paths, 14.3%)
   - Prompt Library (65 paths, 11.3%)
@@ -409,7 +409,7 @@ See `enhancements/` directory for comprehensive feature documentation and exampl
 
 ```
 /
-├── docs/                   # 571 documentation files (.md format)
+├── docs/                   # Documentation files (.md format)
 │   ├── docs_manifest.json  # File tracking manifest
 │   └── .search_index.json  # Full-text search index (Python-generated)
 ├── scripts/
@@ -434,14 +434,14 @@ See `enhancements/` directory for comprehensive feature documentation and exampl
 │       ├── validation.py           # Path validation
 │       ├── formatting.py           # Output formatting
 │       └── cli.py                  # Main entry point
-├── paths_manifest.json     # Active paths manifest (573 paths, 6 categories)
+├── paths_manifest.json     # Active paths manifest (6 categories)
 ├── archive/               # Archived/deprecated scripts (git-ignored)
 ├── enhancements/          # Feature documentation
 │   ├── README.md          # Overview
 │   ├── FEATURES.md        # Technical specs
 │   ├── CAPABILITIES.md    # Detailed capabilities
 │   └── EXAMPLES.md        # Usage examples
-├── tests/                 # Test suite (294 tests, 294 passing)
+├── tests/                 # Test suite (303 tests, 303 passing)
 ├── install.sh            # Installation script
 └── CLAUDE.md             # This file (AI context)
 
@@ -464,8 +464,8 @@ When working on this repository:
 @scripts/fetcher/ - Documentation fetching package (8 modules)
 @scripts/lookup/ - Search & validation package (7 modules)
 @scripts/build_search_index.py - Full-text search indexing
-@paths_manifest.json - Active paths manifest (573 paths, 6 categories)
-@tests/ - Test suite (294 tests)
+@paths_manifest.json - Active paths manifest (6 categories)
+@tests/ - Test suite (303 tests)
 
 ### Automation
 @.github/workflows/ - Auto-update workflows (runs every 3 hours)
@@ -525,7 +525,7 @@ python3 scripts/lookup_paths.py --search "mcp"
 pytest tests/ -v
 
 # Run full test suite
-pytest tests/ -q  # Should see: 294 passed, 2 skipped
+pytest tests/ -q  # Should see: 303 passed
 ```
 
 ## Upstream Compatibility

CONTRIBUTING.md

@@ -7,16 +7,16 @@ Thank you for contributing to the Enhanced Claude Code Documentation Mirror!
 This project extends [ericbuess/claude-code-docs](https://github.com/ericbuess/claude-code-docs) with optional Python features:
 
 **Core Principle: Graceful Degradation**
-- Single installation (573 paths tracked across 6 categories + Python scripts)
+- Single installation (paths tracked across 6 categories + Python scripts)
 - Python features activate only when Python 3.9+ is available
 - Everything works without Python (basic `/docs` command)
 - No separate "modes" - just feature detection at runtime
 
 **Design Goals:**
-1. **Honesty**: Accurate claims about what we deliver (573 paths tracked, 571 files downloaded)
+1. **Honesty**: Accurate claims about what we deliver (paths tracked in manifest, files downloaded)
 2. **Simplicity**: One installation, automatic feature detection
 3. **Compatibility**: Works with upstream, same `/docs` interface
-4. **Testing**: All changes tested (294 tests)
+4. **Testing**: All changes tested (303 tests)
 
 ## Repository URL Strategy
 
@@ -125,7 +125,7 @@ pip install -e ".[dev]"
 ~/.claude-code-docs/claude-docs-helper.sh --validate
 
 # Run tests (REQUIRED before submitting PR)
-pytest tests/ -v  # Should see: 294 passed, 2 skipped
+pytest tests/ -v  # Should see: 303 passed
 
 # Test specific changes
 python scripts/lookup_paths.py "your test query"
@@ -136,7 +136,7 @@ python scripts/fetch_claude_docs.py --help
 - `scripts/fetch_claude_docs.py` - Documentation fetcher with auto-regeneration
 - `scripts/lookup_paths.py` - Search & validation
 - `scripts/build_search_index.py` - Full-text search indexing
-- `tests/` - Test suite (629 tests)
+- `tests/` - Test suite (303 tests)
 
 ## Code Standards
 
@@ -330,9 +330,8 @@ def test_search_paths_with_limit():
 ```
 
 **Current test status:**
-- Total: 296 tests
-- Passing: 294 (99.3%)
-- Skipped: 2 (intentional)
+- Total: 303 tests
+- Passing: 303 (100%)
 
 ## Pull Request Guidelines
 
@@ -415,7 +414,7 @@ git push origin v0.x.x
 
 **When to release:**
 - New Python features complete
-- All tests passing (294/296 or 296/296)
+- All tests passing (303/303)
 - Documentation updated
 
 **Process:**