hiivmind-corpus-status

name	hiivmind-corpus-status
description	Check the health and status of registered corpora. Use when users want to see corpus freshness, verify configurations, check for upstream updates, or diagnose issues. Triggers: corpus status, check corpus, corpus health, is corpus up to date, corpus info.

Corpus Status Skill

Check the health and freshness of registered documentation corpora. Reports on index status, source availability, and cache state.

When to Use

• User asks about corpus status or health
• User wants to know if corpora need updating
• Diagnosing navigation or fetch issues
• Before bulk operations (refresh)

Workflow

Phase 1: Load Registry

Read .hiivmind/corpus/registry.yaml:

Read: .hiivmind/corpus/registry.yaml

If not found:

No corpus registry found at .hiivmind/corpus/registry.yaml

No corpora are registered for this project.

Register a corpus with:
  /hiivmind-corpus register github:hiivmind/hiivmind-corpus-flyio

Phase 2: Check Each Corpus

For each registered corpus, gather status information:

2a. Fetch Corpus Config

From GitHub (using gh api - preferred):

gh api repos/{owner}/{repo}/contents/config.yaml?ref={ref} --jq '.content' | base64 -d

Then parse the YAML to extract: schema_version, corpus.name, corpus.keywords, sources[].last_commit_sha, index.last_updated_at

Fallback (WebFetch):

WebFetch: https://raw.githubusercontent.com/{owner}/{repo}/{ref}/config.yaml
prompt: "Extract schema_version, corpus.name, corpus.keywords, sources[].last_commit_sha, index.last_updated_at"

From local:

Read: {source.path}/config.yaml

2b. Check Index Exists

From GitHub (using gh api - preferred):

# Check if file exists (will error if not found)
gh api repos/{owner}/{repo}/contents/index.md?ref={ref} --jq '.name' 2>/dev/null && echo "exists"

# Or fetch first portion to verify content
gh api repos/{owner}/{repo}/contents/index.md?ref={ref} --jq '.content' | base64 -d | head -10

Fallback (WebFetch):

WebFetch: https://raw.githubusercontent.com/{owner}/{repo}/{ref}/index.md
prompt: "Return just the first 10 lines to verify file exists"

From local:

Read: {source.path}/index.md (limit: 10 lines)

2c. Check Source Freshness (Git sources)

For git-based documentation sources, compare tracked commit to latest:

# Get latest commit from GitHub API
gh api repos/{owner}/{repo}/commits/{branch} --jq '.sha'

Compare with sources[].last_commit_sha in config.yaml.

2d. Check Cache Status

If cache.strategy: clone:

# Check if cache exists
if [ -d ".corpus-cache/{corpus_id}" ]; then
    # Check last modified time
    stat -c %Y ".corpus-cache/{corpus_id}/index.md"
fi

Phase 3: Build Status Report

Compile status for all corpora:

corpora_status:
  - id: flyio
    display_name: "Fly.io"
    source: github:hiivmind/hiivmind-corpus-flyio@main
    status: healthy          # healthy | stale | error
    index:
      exists: true
      last_updated: "2026-01-08T12:00:00Z"
      entry_count: 747
    sources:
      - id: flyio
        type: git
        upstream: current    # current | behind | error
        tracked_sha: "e353a1b..."
        latest_sha: "e353a1b..."
    cache:
      strategy: fetch
      cached: false
    keywords: ["flyio", "fly.io", "deployment"]
    embeddings:
      has_db: true
      generated_at: "2026-01-08T12:00:00Z"
      entry_count: 747
      model: "BAAI/bge-small-en-v1.5"
      freshness: "current"      # current | stale | missing

  -  
     
    

Phase 4: Present Report

Summary view (default):

## Corpus Status

| Corpus | Status | Last Updated | Sources | Keywords |
|--------|--------|--------------|---------|----------|
| Fly.io | healthy | 2026-01-08 | 1 current | flyio, fly.io |
| Polars | stale | 2025-12-01 | 1 behind | polars, dataframe |

**Healthy:** 1 corpus
**Stale:** 1 corpus (upstream has changes)
**Errors:** 0

To update stale corpora:
  /hiivmind-corpus refresh polars

Detailed view (with --verbose or specific corpus):

## Fly.io Corpus Status

**Source:** github:hiivmind/hiivmind-corpus-flyio@main
**Status:** healthy

### Index
- **Exists:** Yes
- **Last Updated:** 2026-01-08T12:00:00Z
- **Entry Count:** 747 files indexed

### Sources
| Source ID | Type | Status | Tracked | Latest |
|-----------|------|--------|---------|--------|
| flyio | git | current | e353a1b... | e353a1b... |

### Cache
- **Strategy:** fetch (no local cache)

### Keywords
flyio, fly.io, deployment, hosting, edge, cloud

### Embeddings
- **Status:** current
- **Entries:** 747
- **Model:** BAAI/bge-small-en-v1.5
- **Generated:** 2026-01-08T12:00:00Z
- **Embedding lag:** 3 entries indexed since last embed

Compute the Embedding lag line per ${CLAUDE_PLUGIN_ROOT}/lib/corpus/patterns/embeddings.md § Embedding Lag (count of entries whose last_indexed postdates the Lance _meta.generated_at). Show "no embeddings" when index-embeddings.lance/ is absent (lag is null).

Status Classifications

Status	Meaning	Action
healthy	Index exists, sources current	None needed
embeddings current	index-embeddings.lance/ generated_at >= index.yaml generated_at	Healthy
embeddings stale	index-embeddings.lance/ generated_at < index.yaml generated_at	Warning — re-run build or embed.py
no embeddings	No index-embeddings.lance/	Info — optional feature
stale	Upstream has new commits	Run /hiivmind-corpus refresh
outdated	Schema version is old	Update config.yaml manually
no-index	Config exists but no index	Run /hiivmind-corpus build
unreachable	Cannot fetch from source	Check network/URL
invalid	Config is malformed	Check config.yaml

Arguments

Argument	Description	Example
{corpus}	Optional specific corpus	flyio
--verbose	Detailed output
--json	JSON output for scripts

Usage examples:

/hiivmind-corpus status              # All corpora summary
/hiivmind-corpus status flyio        # Specific corpus detail
/hiivmind-corpus status --verbose    # All corpora detailed

Checking Upstream Freshness

For git sources, check if upstream has new commits:

Using GitHub API

# Get latest commit SHA
latest=$(gh api repos/superfly/docs/commits/main --jq '.sha')

# Compare with tracked SHA from config
tracked=$(yq -r '.sources[] | select(.id == "flyio") | .last_commit_sha' config.yaml)

if [ "$latest" = "$tracked" ]; then
    echo "current"
else
    echo "behind"
fi

Using WebFetch

WebFetch: https://api.github.com/repos/superfly/docs/commits/main
prompt: "Extract just the SHA value from the response"

Compare with tracked commit in corpus config.

Self Sources

Self sources use local git log instead of remote API calls:

# Get current scoped SHA
DOCS_ROOT=$(yq '.sources[] | select(.type == "self") | .docs_root // "."' config.yaml)
[ "$DOCS_ROOT" = "." ] && DOCS_ROOT=""

if [ -n "$DOCS_ROOT" ]; then
    current=$(git log -1 --format=%H -- "$DOCS_ROOT")
else
    current=$(git log -1 --format=%H)
fi

tracked=$(yq -r '.sources[] | select(.type == "self") | .last_commit_sha' config.yaml)

if [ "$current" = "$tracked" ]; then
    echo "current"
else
    echo "stale"
fi

No network required — purely local check.

Error Handling

Registry not found:

No corpus registry found.

Register a corpus first:
  /hiivmind-corpus register github:hiivmind/hiivmind-corpus-flyio

Corpus not in registry:

Corpus 'unknown' is not registered.

Registered corpora: flyio, polars

Register with: /hiivmind-corpus register github:owner/repo

Cannot fetch corpus:

Cannot reach corpus 'flyio' at github:hiivmind/hiivmind-corpus-flyio

Network error or repository may have moved.

Last known good state:
- Index updated: 2026-01-08
- Sources tracked: e353a1b...

Invalid corpus config:

Corpus 'flyio' has invalid configuration.

Missing required fields in config.yaml:
- corpus.name
- sources[]

Try rebuilding: /hiivmind-corpus build flyio

Integration with Other Skills

Before refresh:

/hiivmind-corpus status flyio

Corpus 'flyio' is stale:
- Upstream has 3 new commits since last index

Run refresh to update:
  /hiivmind-corpus refresh flyio

Before navigate (if stale):

Note: Corpus 'flyio' is 5 days behind upstream.
Documentation may be outdated.

[Proceed with current index] [Refresh first]

Pattern Documentation

• ${CLAUDE_PLUGIN_ROOT}/lib/corpus/patterns/embeddings.md — Embedding freshness detection
• ${CLAUDE_PLUGIN_ROOT}/lib/corpus/patterns/freshness.md — Index and embedding staleness

Related Skills

• Migrate v1→v2 (headless): ${CLAUDE_PLUGIN_ROOT}/skills/hiivmind-corpus-migrate/SKILL.md
• Headless status (pipelines): ${CLAUDE_PLUGIN_ROOT}/skills/hiivmind-corpus-status-headless/SKILL.md
• Headless rebuild (pipelines): ${CLAUDE_PLUGIN_ROOT}/skills/hiivmind-corpus-build-headless/SKILL.md
• Navigate: hiivmind-corpus-navigate - Query corpus documentation
• Register: hiivmind-corpus-register - Add new corpora
• Refresh: hiivmind-corpus-refresh - Update stale corpora
• Enrich (headless): hiivmind-corpus-enrich-headless - Resolve accumulated stale entries in pipelines
• Discover: hiivmind-corpus-discover - Find available corpora
• ${CLAUDE_PLUGIN_ROOT}/skills/hiivmind-corpus-graph/SKILL.md — View, validate, edit concept graphs
• ${CLAUDE_PLUGIN_ROOT}/skills/hiivmind-corpus-bridge/SKILL.md — Cross-corpus concept bridges and aliases