state-hub/dashboard/src/docs/repos.md

---
title: Repos — Reference
---

# Repos — Reference

The Repos page shows every repository registered in the Custodian ecosystem,
their SBOM ingestion status, and a domain-grouped coverage map.

---

## What is a managed repo?

A managed repo is a git repository that has been registered with the state hub
via `custodian register-project` or `register_repo()`. Registration records the
repo's slug, domain, local path, and optional remote URL. Once registered, the
repo receives a `CLAUDE.custodian.md` integration suggestion, an onboarding
workstream with 4 tasks for the repo agent, and is eligible for SBOM ingestion
and the ADR-001 workplan validator.

For the full onboarding journey see **[Repo Integration](/docs/repo-integration)**.

---

## KPI row

| Card | Meaning |
|------|---------|
| **Registered Repos** | Active repos only (status = active) |
| **Domains** | Count of distinct domain slugs across registered repos |
| **SBOM Ingested** | Repos with at least one SBOM snapshot |
| **SBOM Gaps** | Repos with no ingested SBOM — red border when > 0 |

---

## Coverage Map

Groups repos by domain. Each domain block shows:

- **Domain name** with SBOM, EP, and TD chip indicators
- **SBOM chip** — green ✓ if all repos in the domain are ingested, amber ⚠ if any gap exists
- **EPs chip** — count of open/in-progress extension points for this domain
- **TDs chip** — count of open/in-progress technical debt items for this domain
- **Repo table** — one row per repo with SBOM status, package count, and local path

Rows with no SBOM are highlighted in amber.

---

## Filters

| Filter | Effect |
|--------|--------|
| **Domain** | Show repos for a single domain only |
| **Gaps only** | Toggle to show only repos without an ingested SBOM |

---

## Onboarding a new repo

See **[Repo Integration](/docs/repo-integration)** for the full journey.

Quick reference:

```bash
# From the repo root — registers, writes CLAUDE.custodian.md, creates onboarding tasks
custodian register-project --domain <slug>
```

## Ingesting a repo's SBOM

```bash
# Auto-detects lockfile at repo root
cd ~/state-hub
make ingest-sbom REPO=<slug> REPO_PATH=/absolute/path

# Multi-ecosystem repo — scan all lockfiles recursively
make ingest-sbom REPO=<slug> SCAN=1 REPO_PATH=/absolute/path
```

Supported lockfile formats: `uv.lock`, `requirements.txt`, `package-lock.json`,
`yarn.lock`, `Cargo.lock`, `.terraform.lock.hcl`.

---

## Infra-only repos

Repos with no lockfile (Ansible, shell scripts) can be registered for inventory
purposes. The SBOM gap is expected and can be left as-is. Terraform providers
are auto-detected via `.terraform.lock.hcl` when using `--scan`.

---

*SBOM snapshots are replaced on each ingest — not appended. The last ingestion
timestamp is recorded on the managed_repo row.*