nerve config init-repo + config-repo setup runbook (13/13)

[alex-clickhouse]

What

nerve config init-repo scaffolds a workspace into a shareable config repo — the CI validation workflow, a secrets-aware .gitignore, a README, and a seeded config/settings.yaml — then prints the git/gh and instance-side steps it cannot do for you. Scaffolding is idempotent: an existing file is never overwritten, only reported as skipped, so re-running is safe (--dry-run shows the split without writing).

The generated workflow gates every PR: a gitleaks scan first, then nerve config validate --workspace . --portable-only --strict-keys. It needs no Actions secret to run.

Alongside it: --portable-only now covers cron as well as the machine-local config layers, docs/config.md gains the full setup runbook with the generated workflow embedded verbatim, and python -m nerve.config_validate becomes a supported entry point for environments that cannot install nerve.

Why

A config repo is only as good as the gate in front of it. Without CI, "reviewed configuration" means whatever a reviewer noticed by eye, and the failure modes that matter — a schedule the scheduler silently never runs, a secret committed in plaintext — are exactly the ones eyes miss.

Order matters. The secret scan runs before anything else is fetched: a validation failure that stopped the workflow early would leave a leaked credential unreported, and scanning before the install means it scans this repo and nothing else, so it needs no token of its own. Its image tag is pinned because an argument renamed in a later gitleaks would fail every config repo at once, with no pull request anywhere to explain it.

The validator tracks nerve's default branch rather than pinning to a revision. That is the safe direction for --strict-keys: a validator at or ahead of the instance knows every key the instance reads, so an unknown key is a typo rather than version skew. It is also the direction the rest of this flow already leans — propose_config_change and instance-side sync both leave an unrecognized key a warning, on the grounds that a key this nerve does not know is inert, and refusing an already-reviewed change over one would strand the instance on a stale config for a spelling the next upgrade may well know. Those asymmetries are now stated where they live rather than left to be rediscovered. A repo that would rather check against one release appends a ref to the install line; and where CI and an instance can still disagree, the --strict-keys failure says so, so a config repo does not get blamed for a version difference.

--portable-only had a hole. Cron resolution is file-aware: a workspace carrying no jobs falls back to the machine-local ~/.nerve/cron so an un-migrated install keeps working. That fallback is right at load time and wrong in a run asked to judge the shared bundle alone — it hands CI a file the repo does not contain, and a typo in that file fails a config repo with nothing wrong with it. It is the same substitution that skipping config.yaml / config.local.yaml prevents, one directory over. An explicit cron.jobs_file pointing outside the tracked subtree goes the same way.

config/settings.yaml is part of the scaffold for a narrow reason: a repo with no config/ at all fails its own workflow on the very first commit, because a portable-only run that opened no file under config/ is an error there, not a pass. An instance's workspace already has the file and skips it.

The standalone python -m nerve.config_validate path exists because everything the validator needs is the standard library plus PyYAML — a bundle can be checked by cloning nerve and setting PYTHONPATH, with no install and no resolution of nerve's full runtime. It shares the CLI's renderer, and the tests assert both directions of parity: identical output, and the same set of flags, since a flag the CLI has and this parser does not is a documented invocation this path cannot run.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds “config repo” scaffolding + CI validation workflow, and introduces a zero-install validator entry point (python -m nerve.config_validate) designed to safely validate a checked-out config repo (portable-only, no machine overlays, no execution of repo code).

Changes:

• Add nerve config init-repo and nerve.config_repo.scaffold_config_repo() to scaffold a config repo (workflow, gitignore, README, seeded settings).
• Add a standalone validator entry point (python -m nerve.config_validate) and unify output formatting via render_result.
• Update portable-only validation to suppress machine-local cron fallback, plus docs/tests/templates to match the new runbook + CI flow.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_config_validate.py	Adds portable-only cron fallback tests and coverage for the standalone validator entry point parity with the CLI.
tests/test_config_repo.py	New end-to-end tests for repo scaffolding, workflow correctness, pin “honesty”, and CI-safe execution.
nerve/templates/skills/nerve-workspace/SKILL.md	Documents operator-guided first-time config repo setup steps for the workspace skill.
nerve/templates/config-repo/validate-config.yml	Adds scaffolded GitHub Actions workflow: gitleaks scan + pinned-source validator run under PYTHONSAFEPATH.
nerve/templates/config-repo/README.md	Adds scaffolded README explaining repo layout and PR-based change flow.
nerve/templates/config-repo/gitignore	Adds scaffolded .gitignore for secrets/machine-local state (including backup secret members).
nerve/sync_service.py	Clarifies strict-keys behavior asymmetry between config-repo CI and instance sync validation.
nerve/config_validate.py	Implements portable-only cron suppression, adds shared rendering, and adds standalone argparse-based entry point.
nerve/config_repo.py	New module implementing idempotent scaffolding and validator ref pinning/notes.
nerve/config_pr.py	Documents intentional asymmetry between proposal validation and stricter CI validation.
nerve/cli.py	Updates config validate to use shared renderer and adds config init-repo command.
docs/config.md	Adds/updates full runbook for config repo setup and embeds the generated workflow verbatim.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.