docs: correct contributor guidance that contradicts the code

[awsome-o]

TL;DR

An agent starting from AGENTS.md, a contributor skill, or a design doc can get instructions that no longer match this repository. This corrects those statements against the code, in 29 files, +201/−177. No runtime behavior changes: the single Go edit is a comment.

This is the first of four slices carved out of the original #1318 (50 files, +1087/−795). The others cover CLI contracts, provider migration, and review publication. Nothing here depends on them.

The corrections

Conflict	Before	After	Expected outcome
Worktree bootstrap	AGENTS.md promised dependencies download automatically on worktree entry, but the hook fires only for Claude's EnterWorktree and invoked a bare go, which is not on PATH in every shell	Hook uses mise exec --; AGENTS.md gives the explicit mise trust + mise exec -- go mod download commands	A plain git worktree, or another agent's worktree, can bootstrap without guessing
Validation coverage	The command list claimed mise run tests runs race detection; the tests:* tasks run CLI, linter-rule and installer tests with no -race. gate was called a pre-push gate while the PR checklist requires mise run all	Coverage is stated as it is, and gate is named the iteration gate	Agents run the intended checks and report coverage they actually have
Stacked-PR base	The PR checklist rebased onto main unconditionally; self-review T10 said stacked PRs use their real target but offered git merge-base as the fallback	Resolve the PR's actual base; merge-base is for ancestry checks after both refs are named, not for choosing a target	No replaying commits the parent already carries, which is how deleted work comes back
Release task	CONTRIBUTING.md and mise.toml said the task tags and pushes; scripts/tag.sh commits and pushes a release/vX.Y.Z branch and only prints the tagging commands	All three describe release-branch preparation, with tagging separate	Nobody waits for a tag that was never created
Auth precedence	The architecture diagram chose credentials by inspecting the token field first, while the auth contract selects by the configured method	The diagram follows resolved context → validated auth/TLS → transport, and the APIToken comment says AuthMethod selects	A populated token field does not silently override a selected auth method. Runtime auth is unchanged
Concurrency	patterns.md carried a contradiction resolution defending unbounded GetMultiple, but GetMultiple and Puller both call SetLimit already	Both limits are documented; the obsolete resolution is removed and the remaining ones renumbered	Bounded parallelism is preserved at both layers, and transport rate limiting is not mistaken for it
Package-map ownership	doc-maintenance.md required every internal package in three places including CLAUDE.md, while its own rules say keep the entry point short and don't duplicate	project-structure.md owns the detailed inventory; the entry point keeps routing and the command-group map	One place to update for a package change, so the maps stop diverging
Stale command paths	Skills named datasources generic and auth login; the registered commands are datasources query and login	Current full command paths	Skills invoke commands that exist, and the drift gate can check them
Observability ordering	The skill said export and review must both run last, then ran them concurrently — though review can add missing schedules	Review and authorized remediation run before export, and a later change requires a refresh	The exported state reflects remediation instead of racing it
Portable hosts	README.md offers these skills to Codex, OpenCode and Pi; the workflow required Claude-style task tools with no alternative	Checklist, sequential-worker and question fallbacks	Those hosts can follow the workflow instead of stalling on a missing tool
Broken links	The ADR index linked ADR-006 to a file that is not in the repository, and VISION.md linked a dead ARCHITECTURE.md anchor	ADR-006 is an unlinked historical entry; the anchor points at § 4 Developer Tooling	Following a link in the index lands somewhere

Reviewing order

Seven files are split across the four slices by hunk, so each change sits with the rule it belongs to. In this PR that means ARCHITECTURE.md (the ADR-006 entry only), DESIGN.md (one stale command path), VISION.md (one anchor), patterns.md (concurrency only), and two integrate-with-gcx files (bootstrap and base selection only). The exit-code and agent-mode hunks in those same files belong to the CLI-contract slice.

What this does not change

Runtime behavior, command surfaces, output formats and auth resolution are all untouched. The only Go change is the APIToken doc comment in internal/config/types.go. Two generated reference files move with it because they are generated from that struct.

Validation

GCX_AGENT_MODE=false mise run all passes end to end: skill validation, lint (0 issues), Go tests, linter-rule tests, installer tests, build, reference regeneration and docs. mise run reference leaves no drift.

MkDocs reports 33 link warnings, all pre-existing and none naming a file this PR touches. Two of the branch's edits would have added new ones by linking from inside docs/ to root files; both now reference those files the way the surrounding text already does.

🤖 Generated with Claude Code