chore(docs): document make tools-update and unpin version from Tech Stack line

[yuanchen8911]

Summary

Three small contributor-doc fixes, all triggered by a real lint miss on PR #924 where local golangci-lint v2.10.1 silently passed a goconst finding that CI's v2.12.2 caught.

Motivation / Context

While addressing CodeRabbit review on #924, CI flagged a goconst issue that my local make qualify had cleared. Root cause: my local golangci-lint was v2.10.1 while CI runs v2.12.2 (pinned in .settings.yaml). The goconst check tightened its default occurrence threshold between those versions, so the local lint silently produced a false negative.

Investigation surfaced three small doc gaps that contributed:

1. .claude/CLAUDE.md and AGENTS.md hard-code golangci-lint v2.11.3 in the Tech Stack line. Renovate auto-bumps .settings.yaml via the # renovate: annotation on each pinned line, but the bare prose mention in CLAUDE.md/AGENTS.md never moves — so the doc drifts on every minor bump. Today .settings.yaml says v2.12.2; the docs still say v2.11.3.
2. make tools-update is undocumented in CONTRIBUTING.md, DEVELOPMENT.md, and the contributor docs. The target exists in Makefile and is the only way to upgrade an existing local install to match .settings.yaml. The existing docs only describe tools-setup (first-time install) and tools-check (verify). The DEVELOPMENT.md troubleshooting row even pointed contributors at the wrong target (tools-setup for an upgrade scenario).
3. No callout that local lint can silently miss issues if the toolchain is behind CI. The existing docs imply that make qualify passing locally guarantees CI passes — which is only true when .settings.yaml and the local toolchain agree.

Fixes: N/A (no issue filed; surfaced from PR #924 review)
Related: #924

Type of Change

• Documentation update

Component(s) Affected

• Docs/examples (docs/, examples/)
• Other: contributor docs (CONTRIBUTING.md, DEVELOPMENT.md), agent docs (.claude/CLAUDE.md, AGENTS.md)

Implementation Notes

• Self-healing version pointer. Replaced `golangci-lint v2.11.3` in CLAUDE.md/AGENTS.md with `golangci-lint, Ko for images (pinned versions in `.settings.yaml`)`. Eliminates the recurring Renovate drift problem for this line. Same change mirrored in AGENTS.md to keep `check-agents-sync` green.
• DEVELOPMENT.md. Added `make tools-update` to: the quickstart command block, the central "Version Management" bullet list, the make-targets reference table under "Tools", and the troubleshooting row that used to misroute users to `tools-setup`. Also added a second troubleshooting row covering the specific PR fix(bundler): wire PreManifestFiles through flux deployer with terminal-aware dependsOn #924 failure mode ("qualify passes locally but lint fails in CI").
• DEVELOPMENT.md new subsection "Keeping the toolchain in sync" explains the drift trap explicitly: when Renovate bumps .settings.yaml, local installs lag behind CI until you run make tools-update. Calls out the silent false-negative lint scenario as the main pitfall.
• CONTRIBUTING.md. Updated the "What/Why" callout on .settings.yaml to mention tools-update alongside tools-setup, and added a sentence noting that the make qualify ≡ CI guarantee only holds when the local toolchain matches .settings.yaml. Tightened the recommended starting-points bullet to mention tools-update next to tools-check.
• Example output snapshot in DEVELOPMENT.md left untouched — it still shows `v2.11.3` and friends, but it's clearly an illustrative snapshot rather than a current claim, and rewriting it would expand PR scope into version-table maintenance. A maintainer can refresh it later or convert to generic placeholders if desired.

Testing

Doc-only PR (4 markdown files: `.claude/CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `DEVELOPMENT.md`). Per CLAUDE.local.md's doc-only verification rule, ran the cheap doc-scoped checks instead of full `make qualify`:

```bash
make check-agents-sync # OK: AGENTS.md is in sync with .claude/CLAUDE.md
make check-docs-mdx # OK: all doc files are MDX-safe
make check-docs-filenames # OK: all doc filenames follow kebab-case convention
```

Full `make qualify` skipped because:

• No `.go` files changed → Go tests / vet / golangci-lint / coverage can't regress.
• No `.yaml` files changed → yamllint and chainsaw e2e can't regress.
• No `docs/` files changed → lychee anchor-link checker and Fern docs preview have no relevant input.
• Docs sidebar untouched.

Risk Assessment

• Low — doc-only, no behavior change, easy to revert.

Rollout notes: None. Contributors who already know `make tools-update` are unaffected; new contributors and anyone diagnosing the "qualify passes locally but fails in CI" failure mode get correct guidance.

Checklist

• Tests pass locally (make test with -race) — N/A, doc-only
• Linter passes (make lint) — N/A, doc-only; scoped doc checks ran
• I did not skip/disable tests to make CI green
• I added/updated tests for new functionality — N/A, doc-only
• I updated docs if user-facing behavior changed
• Changes follow existing patterns in the codebase
• Commits are cryptographically signed (git commit -S)

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 196a8ea3-3821-44ea-bf67-aa4789515181

📥 Commits

Reviewing files that changed from the base of the PR and between 1ab713a and 374c621.

📒 Files selected for processing (4)

• .claude/CLAUDE.md
• AGENTS.md
• CONTRIBUTING.md
• DEVELOPMENT.md

---

📝 Walkthrough

Walkthrough

This PR updates contributor and reference documentation to centralize tool version management in .settings.yaml. It removes hardcoded version pins from tech stack references in .claude/CLAUDE.md and AGENTS.md, then expands guidance in CONTRIBUTING.md and DEVELOPMENT.md to clarify how contributors should set up tools, sync to pinned versions, and troubleshoot version mismatches. All changes are documentation-only with no code alterations.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested reviewers

• mchmarny
• lockwobr
• njhensley

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}