blz-source-management

# BLZ Source Management Add and manage llms.txt documentation sources for local search. ## Source Types | Type | Description | Action | |------|-------------|--------| | `llms-full.txt` | Complete documentation (preferred) | Add directly | | `llms.txt` (full) | Complete docs under standard name | Add directly | | `llms.txt` (index) | Links to other docs (< 100 lines) | Expand linked files | ## Adding Sources ### Standard Workflow ```bash # 1. Dry-run to validate blz add react https://react.dev/llms.txt --dry-run --quiet # 2. Check output # Good: contentType: "full", lineCount > 1000 # Index: contentType: "index", lineCount < 100 → find linked docs # 3. Add if good blz add react https://react.dev/llms.txt -y # 4. Verify blz list --json | jq '.[] | select(.alias=="react")' ``` ### Discovering URLs Web search patterns: ``` "llms-full.txt" site:docs.example.com "llms.txt" OR "llms-full.txt" <library-name> site:github.com/org/repo "llms.txt" ``` Common URL patterns: ``` https://docs.example.com/llms-full.txt https://example.com/llms.txt https://example.com/llms-full.txt ``` ## Index File Handling If dry-run shows `contentType: "index"` with < 100 lines: ```bash # Inspect the index curl -s <index-url> | head -50 # Look for .txt references like: # ./guides.txt # ./js.txt # ./python.txt # Resolve and add each linked file blz add supabase-guides https://supabase.com/llms/guides.txt -y blz add supabase-js https://supabase.com/llms/js.txt -y ``` ## Quality Criteria | Criteria | Good | Index | Skip | |----------|------|-------|------| | contentType | "full" | "index" | "unknown" | | lineCount | > 1000 | < 100 | < 50 | | Action | Add | Expand | Investigate | ## Alias Best Practices Good aliases: - `bun`, `react`, `deno` (short, clear) - `supabase-guides` (variant-specific) - `langchain-python` (language-specific) Bad aliases: - `b` (too short) - `my-docs` (vague) - `the-react-docs-2024` (too long) ## Management Commands ```bash # List sources blz list --json blz list --status --json # With freshness # Refresh sources blz refresh --all --json # Update all blz refresh bun --json # Update specific # Remove source blz remove bun # Source details blz info bun --json ``` ## Troubleshooting | Issue | Solution | |-------|----------| | 404 Not Found | Try `/llms.txt` vs `/llms-full.txt`, check GitHub repo | | Small line count | Likely index file - expand linked docs | | contentType unknown | Inspect content manually, verify it's markdown/text | | Already exists | Use `blz refresh <alias>` to update |