# statehub register — Consumer Guide

Use this guide when bootstrapping a new Coulomb repository from the `repo-seed`
template and registering it with Custodian State Hub.

## Prerequisites

- State Hub API running locally (`cd ~/state-hub && make api`) or reachable via tunnel
- `statehub` CLI installed from `~/state-hub` (`uv tool install .` or `uv run statehub`)
- A git repository cloned or copied from `repo-seed` (or an equivalent scaffold)

## Quick start

From the new repository root:

```bash
cd /path/to/new-repo

# Optional: skip LLM inference and supply facts manually
statehub register \
  --domain <domain-slug> \
  --repo-slug <repo-slug> \
  --wp-prefix <PREFIX-WP> \
  --description "One-sentence repo purpose." \
  --no-llm

# Operator follow-up (from state-hub checkout)
cd ~/state-hub
make fix-consistency REPO=<repo-slug>
```

`statehub register` is idempotent: existing files are not overwritten unless you
pass `--force`.

## What register writes

`statehub register` inspects the repository, infers identity (optionally via
`llm-connect`), and writes these files when absent:

| File | Purpose |
|------|---------|
| `INTENT.md` | Why the repository exists |
| `SCOPE.md` | In/out scope and current state |
| `AGENTS.md` | Codex/Grok agent instructions with repo identity placeholders filled |
| `.custodian-brief.md` | Offline-safe session orientation |
| `workplans/<PREFIX>-0001-statehub-bootstrap.md` | First workplan with T01–T03 bootstrap tasks |

It also registers the repo and host path through the State Hub API and records a
progress milestone.

## Template extras (from repo-seed)

Cloning `repo-seed` provides additional scaffold not written by `register`:

| Path | Purpose |
|------|---------|
| `CLAUDE.md` + `.claude/rules/` | Claude Code agent instructions |
| `registry/` | Capability registry scaffold |
| `README.md`, `LICENSE`, `.gitignore` | Project metadata |
| `.repo-classification.yaml` | Repo classification metadata |

After `register`, complete the bootstrap workplan (`*-0001-statehub-bootstrap.md`):

1. **T01** — Review and refine generated integration files
2. **T02** — Document install/test/lint/build/run commands in agent instructions
3. **T03** — Create the first real implementation workplan

## CLI reference

```
statehub register [options]

  --path PATH           Repo directory (default: cwd)
  --domain SLUG         State Hub domain slug
  --repo-slug SLUG      Repo slug (auto-detected from directory name)
  --wp-prefix PREFIX    Workplan prefix, e.g. DEMO-WP
  --description TEXT    One-sentence repo description
  --intent TEXT         Intent text when INTENT.md is absent
  --api-base URL        State Hub API base (default: http://127.0.0.1:8000)
  --no-llm              Skip LLM inference; use files and flags
  --force               Overwrite generated files
```

Environment overrides: `API_BASE`, `STATEHUB_REGISTER_LLM_PROVIDER`,
`STATEHUB_REGISTER_LLM_MODEL`, `STATEHUB_REGISTER_LLM_API_KEY`,
`STATEHUB_REGISTER_LLM_TIMEOUT`.

## fix-consistency

Workplans are canonical in repo files (ADR-001). After creating or updating
workplan files, sync them into State Hub:

```bash
cd ~/state-hub
make fix-consistency REPO=<repo-slug>
```

This rebuilds hub workstreams/tasks from files, updates `.custodian-brief.md`,
and reports consistency findings (C-15 file/DB drift, C-16 remote behind, etc.).

## Validation

Use [template-validation-checklist.md](template-validation-checklist.md) to
verify a bootstrapped repo against expected `statehub register` output.