config-atlas/.claude/rules/stack-and-commands.md

## Stack

- **Language:** Markdown-first registry and planning repo (no application runtime)
- **Key deps:** State Hub ADR-001 workplans, `registry/indexes/{capabilities,surfaces}.yaml`,
  `schemas/surface-entry.schema.json` (validated with PyYAML + jsonschema)

## Dev Commands

```bash
# Orient (offline-safe)
cat .custodian-brief.md
cat INTENT.md
cat SCOPE.md
ls workplans/
ls registry/

# Validate the registry (the CI gate — run after any registry/schema edit)
make validate                       # schema + index + whitespace + reuse-surface
python3 tools/validate_registry.py  # schema + index consistency only
git diff --check                    # whitespace / conflict markers
reuse-surface validate --root .     # capability federation (from reuse-surface checkout)

# Explain a surface's effective-config override path (no values shown)
make explain SURFACE=surface.infotech.state-hub.api-config

# Change blast-radius / dependency view for a surface
make blast-radius SURFACE=surface.infotech.state-hub.api-config

# Regenerate / query the config knowledge-graph edges (registry/indexes/graph.yaml)
make graph
make graph-query SURFACE=surface.infotech.state-hub.api-config

# After workplan or registry edits — from ~/state-hub
make fix-consistency REPO=config-atlas
```

**Validation gate (CI):** `make validate` is the single gate run by agents and CI
(`.github/workflows/validate.yml`, read by GitHub *and* Gitea Actions). It validates
every `registry/surfaces/*.md` against `schemas/surface-entry.schema.json`
(forbidding inline values/secrets), checks `registry/indexes/surfaces.yaml`
consistency, and runs `git diff --check`. Requires `pip install pyyaml jsonschema`.

**Install / test / build / run:** not applicable — no application runtime. Verify
changes with `make validate`.