---
name: index-catalog
description: Bootstraps or refreshes the local FTS5 catalog at ~/.claude/cache/maxv-orchestration/index.db by downloading the latest release artifact (default) or rebuilding it locally with --rebuild. Use after first install OR when version-check shows the index is stale OR when you want to force a refresh.
when_to_use: |
  Trigger phrases: "atualize o catalogo", "rebuild index", "/maxvision-orchestration:index-catalog",
  "refresh skills index", "the catalog is outdated".
disable-model-invocation: true
allowed-tools: Read Bash(test *) Bash(mkdir -p *) Bash(cp -f *) Bash(mv -f *) Bash(rm -f *) Bash(gh auth status) Bash(gh release download *) Bash(sha256sum *) Bash(gunzip *) Bash(sqlite3 *) Bash(python -m scripts.build_index *)
---

# Index catalog

Argument: `$ARGUMENTS` — flags `--bootstrap` (default if no index exists) | `--rebuild` (force local build) | `--force` (re-download even if fresh)

## Workflow

### 1. Resolve cache path
```bash
set -euo pipefail
CACHE_DIR=~/.claude/cache/maxv-orchestration
mkdir -p "$CACHE_DIR"
INDEX_DB="$CACHE_DIR/index.db"
INDEX_BAK="$CACHE_DIR/index.db.bak"
```

### 2. Decide mode
- If `$ARGUMENTS` contains `--rebuild`, build locally via `python scripts/build_index.py` (skip to step 3b).
- Else if `gh` is not authenticated (`gh auth status` fails), fall back to local rebuild after confirming with the user.
- Else if `index.db` exists and is < 24 h old AND `--force` is not in `$ARGUMENTS`, report cached state and exit.
- Else download from release (step 3a, default).

### 3a. Download path (default — pulls release artifact)
```bash
set -euo pipefail
# Backup current index before any overwrite
[ -f "$INDEX_DB" ] && cp -f "$INDEX_DB" "$INDEX_BAK"

gh release download catalog-index-latest \
  -R produtoramaxvision/claude-code-maxvision-orchestration \
  -p 'index.db.gz' -p 'index.db.sha256' \
  --dir "$CACHE_DIR" --clobber

# Manifest produced by build-index.yml lists relative paths; cd before -c
( cd "$CACHE_DIR" && sha256sum -c index.db.sha256 ) || {
  echo "SECURITY: sha256 mismatch on index.db.gz — aborting" >&2
  rm -f "$CACHE_DIR/index.db.gz" "$CACHE_DIR/index.db.sha256"
  exit 2
}

gunzip -f "$CACHE_DIR/index.db.gz"
```

### 3b. Local rebuild path (--rebuild or gh-not-authenticated)
```bash
set -euo pipefail
[ -f "$INDEX_DB" ] && cp -f "$INDEX_DB" "$INDEX_BAK"
python -m scripts.build_index --output "$INDEX_DB"
```

### 4. Validate + restore-on-failure
```bash
set -euo pipefail
# table name 'item' must match scripts/build_index.py schema
ITEMS=$(sqlite3 "$INDEX_DB" 'select count(*) from item')
test "$ITEMS" -ge 100 || {
  echo "index too small ($ITEMS), restoring backup" >&2
  [ -f "$INDEX_BAK" ] && mv -f "$INDEX_BAK" "$INDEX_DB"
  exit 1
}
GENERATED_AT=$(sqlite3 "$INDEX_DB" "select value from meta where key='generated_at'" 2>/dev/null || echo "unknown")
```

### 5. Report
```
✓ Catalog ready
  Path:       ~/.claude/cache/maxv-orchestration/index.db
  Items:      <ITEMS>
  Generated:  <GENERATED_AT>
  Method:     <download|local-rebuild>
```

## Guardrails

- **Backup before overwrite.** Workflow copies `index.db` → `index.db.bak` before any download or local-rebuild step. On validation failure, the backup is restored.
- **Security on download.** `set -euo pipefail` + explicit `|| { … exit 2; }` after `sha256sum -c` so a checksum mismatch aborts and removes the poisoned `.gz` and manifest.
- **Auth check up front.** `gh auth status` is verified in step 2; on failure the workflow falls back to local rebuild after user confirmation.
- **Never run during a synthesis flow** — synthesis assumes the index is stable.