# catalog

> Documentation reference catalog commands for building, checking, and fixing doc-to-code links.

- Author: Steve Glen
- Repository: FrostyTeeth/claude_plugin1
- Version: 20260124133458
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/FrostyTeeth/claude_plugin1
- Web: https://mule.run/skillshub/@@FrostyTeeth/claude_plugin1~catalog:20260124133458

---

---
name: catalog
description: Documentation reference catalog commands for building, checking, and fixing doc-to-code links.
argument-hint: <command>
---

# Catalog Commands

Manage the documentation reference catalog.

## Available Commands

### /catalog build

Build the complete catalog from scratch.

```bash
python -m scripts.librarian.catalog build
```

**What it does:**
1. Scans all Python files in `app/`, `scripts/` → builds symbol index
2. Scans all Markdown files in `docs/` → extracts code references
3. Resolves references to exact file/symbol locations
4. Computes content hashes for change detection

**Output files:**
- `docs/indexes/symbols.json` - All defined symbols
- `docs/indexes/extracted_refs.json` - Raw references from docs
- `docs/indexes/links.json` - Resolved links with hashes

---

### /catalog check

Check all links for staleness.

```bash
python -m scripts.librarian.catalog check
```

**What it does:**
1. Loads existing links from `links.json`
2. Recomputes hashes for all targets
3. Compares stored vs current hashes
4. Marks links as CURRENT or STALE

**Output:** Updates `links.json` with status field, prints report.

---

### /catalog status

Show current catalog status.

```bash
python -m scripts.librarian.catalog status
```

**Shows:**
- Symbol index stats (count, last generated)
- Links index stats (total, broken, errors, stale)
- Health summary

---

### /catalog fix

Generate fix prompts for issues.

```bash
python -m scripts.librarian.catalog fix
```

**What it does:**
1. Runs check to find stale links
2. Gathers context for broken/stale/ambiguous refs
3. Generates prompts for librarian agent to fix

**Output:**
- `docs/indexes/fix_report.json` - Structured fix context
- Printed prompts for each issue

**After running:** Invoke librarian agent to apply fixes.

---

### /catalog rebuild

Alias for `/catalog build` - rebuilds everything.

---

## Workflow

```
1. /catalog build      # Initial catalog creation
2. /catalog check      # After code changes, check for staleness
3. /catalog fix        # Generate fix prompts if issues found
4. Librarian agent     # Apply fixes to documentation
5. /catalog build      # Rebuild to update hashes
```

## Output Files

| File | Purpose | Committed |
|------|---------|-----------|
| `docs/indexes/symbols.json` | All code symbols | Yes |
| `docs/indexes/extracted_refs.json` | Raw doc references | Yes |
| `docs/indexes/links.json` | Resolved links + hashes + status | Yes |
| `docs/indexes/fix_report.json` | Fix context for agent | No (temp) |

## Link States

| State | Meaning |
|-------|---------|
| **CURRENT** | Hash matches - doc is up to date |
| **STALE** | Hash changed - code modified since doc written |
| **Broken** | Reference target not found |
| **Error** | Ambiguous reference (multiple matches) |

## Integration with Librarian Agent

After `/catalog fix`, invoke the librarian agent:

```
Librarian: Fix the documentation issues in fix_report.json.
For each issue, update the doc to match current code.
```

The agent reads `fix_report.json` and applies fixes.