writ.repo selects a single-source mode nothing documents, and the guide teaches writ.repos, which nothing reads #1014

writ has a second source model beside the layers, and nothing tells a user about it.

• writ.repo is read and undocumented. With no layer configured, deploy takes writ.repo as its one source root (cmd/writ/writ/config.go:83-88), and tree.Build reads that directory directly, its links pointing into it, with no layer to pin (cmd/writ/writ/tree/builder.go:191-196). Upgrade takes it as its source root whenever it is set (config.go:135-138). No flag sets it. The --repo flag and WRIT_REPO variable that cmd/internal/cli/viper.go:48 and :101 cite do not work: there is no --repo, and the variable that reaches writ.repo is WRIT_WRIT_REPO (The environment prefix is doubled: WRIT_WRIT_VERBOSE works and WRIT_VERBOSE does not; the variable is the prefix plus the bare key, for every program #927). No guide, defaults file or test mentions it; tree_test.go's single-source cases call tree.Build directly.
• The guide teaches a key nothing reads. docs/guides/getting-started.md:222 registers a repository with writ config set writ.repos.personal ~/my-environment. docs/plans/writ-repo-command.md:14 recorded that nothing reads writ.repos.* when writ repo replaced it; the guide was not updated. The config help's writ.repos.0.path example (cmd/internal/cli/config.go:36, and the generated docs/cli/writ/config.md:30 and docs/cli/writ/config/get.md:26) names the same key.
• The kept-snapshots design leaves no room for it. Under Stability between upgrades: a per-layer policy, pinned or live -- deployed links point at the kept snapshot or the working tree #847 each layer is pinned by a private ref and its links target the snapshot; live links are retired. Single-source mode has no layer to pin and links into a working tree.

Found 2026-10-02 at 01634491, checking that every program holds its own defaults (#1009).

Resolution

The guide registers a repository the way writ does (writ repo, or writ migrate for an existing one), and no example names writ.repos. Whether writ.repo and single-source mode are deleted, or kept and documented, is ruled in this lane's plan. Deletion is the recommendation, under the governing principle and #847.

Plan and design documents

Epic: #441 · Feature: #456