Decisions

You are working inside a forked copy of byob-go-cli, a personal template repository for Go CLI tools. The beads database you're looking at contains the template's architectural decisions alongside the tasks for this specific project.

Options struct + NewCmdXxx constructor + pure runFunc three-part separation.

Layered, lazily loaded configuration with discovery and provenance.

Semantic error types mapped to exit codes by the top-level runner.

Central factory struct with lazy-loaded dependencies passed into every command.

A single *http.Client on the Factory, built from a composable http.RoundTripper middleware chain; deterministic httptest seams in tests.

Defense against untrusted input beyond the flag-value checks already in byob-errors.1: path traversal, config-shape validation, shell injection, SQL injection, and enum/range checks at the Options boundary.

Interface-driven seams for swappable implementations and test doubles.

Single abstraction for stdin/stdout/stderr with TTY detection and color support.

Conventional directory split and cobra command grouping.

Process-lifecycle and cancellation: signal handling, context propagation through runFuncs.

Structured, contextual, leveled logging threaded through every command without ceremony.

TTY-adaptive human output plus first-class structured export.

Adaptive progress that looks right on a TTY and degrades off-TTY. Spinners for unknown-total, bars for known-total.

Narrow Prompter interface on the Factory with TTY detection, scripted test double, and a library pick that won't rot.

Pure-Go discipline (CGO_ENABLED=0, go:embed) as the foundation; Makefile+ldflags for day-to-day builds; goreleaser for tag-triggered cross-compile, archives, checksums, optional homebrew/nfpm channels. Both paths inject the same ldflags vars so version output is path-independent.

Per-OS directories for cache, state, and data (config is covered in byob-config), plus the atomic-write discipline that keeps them consistent under concurrent invocations.

Supply-chain and secret-handling posture: pin by hash not tag, scan for known CVEs on every push, ship SBOMs and signatures from the release pipeline, and refuse to accept secrets as flag values.

Multi-engine persistent storage for CLI state: sqlite + postgres behind a consumer-scoped Store interface. CockroachDB rides the postgres wire protocol.

Test-first command structure: runF injection, in-memory IO, test doubles.

Narrative user docs distinct from generated reference (byob-output.3). README carries orient-and-quickstart only; --help Long/Example fields carry the detailed reference; narrative docs cover concepts and troubleshooting. Release notes come from git history, not a hand-maintained CHANGELOG.