state-hub/docs/brief-generation.md

Render orientation briefs without Git operations

Use the existing State Hub renderer independently of consistency writeback:

make brief-generate BRIEF_REPO_PATH=/path/to/repo BRIEF_REPO_SLUG=canonical-slug
make brief-check BRIEF_REPO_PATH=/path/to/repo BRIEF_REPO_SLUG=canonical-slug

The Python entry point is scripts/generate_custodian_brief.py; pass --api-base or set Make's STATE_HUB_API_BASE for another endpoint. It performs only API reads and writes .custodian-brief.md in generation mode. It never stages, commits, pushes, or writes to the hub. Check mode exits nonzero on drift without writing. Timestamp-only changes are ignored.

The brief describes the current hub read model, not the Git index. Sync authored work records before expecting their changes in the brief. API requests are not an atomic snapshot; inspect output if concurrent work is changing the hub. Missing or malformed endpoint responses stop generation before writing. Symlink targets are refused. Preserve any existing local changes before refreshing.

Briefs are local generated orientation, excluded by /.custodian-brief.md in .gitignore. Both this command and ordinary consistency refreshes leave them untracked and never stage or commit them. Existing tracked snapshots can be removed with git rm --cached -- .custodian-brief.md after preserving the local file; do not delete that local orientation. Other consistency writebacks retain their existing behavior. The generated-only commit guard remains in force. This command does not install a network-dependent pre-commit hook.