Description
Repair the first-run transition shared by source execution and Docker Compose. The checked-in env example currently carries a Docker-only all-interface bind into direct runs, the primary live examples leave DRY_RUN true, loose boolean parsing accepts misleading values, and a fresh Compose inspection has no safe preflight path.
Acceptance Criteria
- #1 A direct run created from .env.example binds the control plane to loopback unless the user explicitly opts into broader exposure
- #2 Docker Compose overrides only the container-internal HTTP bind so loopback-safe host publishing still works
- #3 Every primary live-start path explicitly transitions DRY_RUN to false and verifies /control/status reports dry_run=false
- #4 Invalid DRY_RUN boolean values fail with an actionable configuration error rather than silently remaining dry-run
- #5 Fresh-clone preflight and .env creation preserve mode 0600 without printing secrets
Definition of Done
- #1 make gate (build vet test race rw-proto-check spdx-check forbidden-words)
- #2 make blueprint-schema (only if a blueprint field or construct/workload config struct changed)
- #3 DRY_RUN=true go run ./cmd/synthkit -once -dump — inventory diffed against signals/
Implementation Plan
- Add a failing config test proving invalid DRY_RUN values are rejected, then implement strict boolean parsing.
- Make .env.example loopback-safe for direct execution and set the container-only 0.0.0.0 bind in Compose.
- Update landing/quickstart live transitions and secure env-file creation without touching README (root integration owner).
- Verify internal/config tests, env-surface alignment, and rendered Compose config with a non-secret fixture.
Implementation Notes
Wave 1 started. File owner: safe-defaults lane owns internal/config config/tests, .env.example, docker-compose.yml, docs/index.md, and docs/quickstart.md. README is root-owned integration.
Implementation complete pending integrated review/gate. TDD evidence: TestLoadRejectsInvalidDryRun was added first and failed because DRY_RUN=maybe was accepted; after strict parsing, go test ./internal/config -count=1 and make env-check passed. .env.example now defaults direct runs to 127.0.0.1:8088; Compose alone overrides container JSON_HTTP_ADDR to 0.0.0.0:8088 while SYNTHKIT_BIND retains loopback host exposure. README, docs/index.md, and docs/quickstart.md now create .env mode 0600, require DRY_RUN=false, and verify /control/status reports false. Isolated non-secret Compose inspection confirmed the internal bind and 127.0.0.1 published host IP. Full gate remains root-owned.
Integrated evidence: CodeRabbit review 4 completed with zero findings after fixes; make gate passed all build, vet, helper, Go test, race, RW2 provenance, SPDX, and forbidden-words legs. DRY_RUN=true go run ./cmd/synthkit -once -dump exited 0 with 26 blueprints, 3,151 output lines, and no hard error lines; no signal contract changed, and the gate’s inventory/integration tests passed.
Final Summary
Landed in 9c93f5c: loopback-safe direct defaults, container-only all-interface bind, explicit live-mode transition and status proof, strict safe DRY_RUN parsing, and mode-0600 env setup. Verified by clean CodeRabbit review 4, make gate, focused Compose/config checks, and a successful 26-blueprint dry-run inventory.