docs: defer Go version to go.mod and enrich the README

[devantler]

🤖 Generated by the Daily AI Assistant

Fixes #70. Part of the go-template roadmap #67. Docs-only — no code/behaviour change.

What changed

1. Go-version drift in AGENTS.md (fixed). The Project overview claimed the module "targets Go 1.24 (CI/release runners use the latest 1.25.x toolchain)", but go.mod declares go 1.25.10. The prose now defers to go.mod as the single source of truth so it can't drift again, and records why the floor sits on 1.25.x (the reusable Dead Code Analysis check installs deadcode, which needs Go ≥ 1.25 — tooling-driven, not a language-feature need).

Per the issue, I deliberately did not change the go.mod floor itself (e.g. 1.25.10 → 1.25). That would be a behavioural change and is out of scope for this docs-only PR; the rationale is now documented either way.

2. Thin README (enriched). Added a concise ✨ What's included overview (idiomatic scaffold; golangci-lint v2 + MegaLinter via pre-commit; required-checks CI + GoReleaser CD on v* tags; coverage via GitHub Code Quality; Renovate; AGENTS.md + the .claude/skills/maintain card) and a 🚀 Use this template section using gh repo create --template / the Use this template button (the repo already has is_template: true), plus a go mod edit -module re-point step. Kept the existing usage commands.

3. cspell.json — added megalinter (new proper noun introduced in the README). Note: MegaLinter has SPELL_CSPELL disabled, so this isn't CI-blocking — added for correctness per the issue's acceptance criteria.

Acceptance criteria

• AGENTS.md no longer claims "Go 1.24"; the version statement defers to go.mod.
• README has a concise What's included overview and points at the Use this template flow.
• markdownlint stays green (MegaLinter defaults; no MD013/long-line issues introduced). cspell is disabled in MegaLinter but megalinter was still added.
• No behavioural/code change — docs only.

Validation

Docs-only; every claim was verified against live main (go.mod = 1.25.10; .claude/skills/maintain/SKILL.md, the linter configs, and the GoReleaser cd.yaml all exist; is_template: true). CI runs only the required-checks aggregator + MegaLinter (markdownlint).

---

Drive-by triage note (not in this PR): sibling roadmap child #68 ("Enable the GitHub template-repository setting") appears already satisfied — is_template is true on the repo today. It may be closeable as completed.

[github-actions]

✅⚠️MegaLinter analysis: Success with warnings

Descriptor	Linter	Files	Fixed	Errors	Warnings	Elapsed time
✅ ACTION	actionlint	6		0	0	0.27s
✅ ACTION	zizmor	6	0	0	0	1.38s
✅ COPYPASTE	jscpd	yes		no	no	0.78s
✅ GO	golangci-lint	yes	yes	no	no	13.48s
✅ JSON	jsonlint	1		0	0	0.37s
✅ JSON	prettier	1	0	0	0	0.41s
✅ JSON	v8r	1		0	0	2.28s
⚠️ MARKDOWN	markdownlint	4	0	4	0	0.97s
✅ MARKDOWN	markdown-table-formatter	4	0	0	0	0.23s
✅ REPOSITORY	checkov	yes		no	no	20.62s
✅ REPOSITORY	gitleaks	yes		no	no	0.1s
✅ REPOSITORY	git_diff	yes		no	no	0.01s
✅ REPOSITORY	grype	yes		no	no	53.46s
✅ REPOSITORY	osv-scanner	yes		no	no	0.4s
✅ REPOSITORY	secretlint	yes		no	no	0.89s
✅ REPOSITORY	syft	yes		no	no	2.08s
✅ REPOSITORY	trivy	yes		no	no	11.76s
✅ REPOSITORY	trivy-sbom	yes		no	no	0.17s
✅ REPOSITORY	trufflehog	yes		no	no	3.35s
✅ SPELL	lychee	15		0	0	0.9s
✅ YAML	prettier	10	0	0	0	0.47s
✅ YAML	v8r	10		0	0	9.58s
✅ YAML	yamllint	10		0	0	0.59s

Detailed Issues

⚠️ MARKDOWN / markdownlint - 4 errors

.claude/skills/maintain/SKILL.md:5 error MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "Perform maintenance per the **..."]
AGENTS.md:5:401 error MD013/line-length Line length [Expected: 400; Actual: 705]
AGENTS.md:31:401 error MD013/line-length Line length [Expected: 400; Actual: 1143]
CLAUDE.md:1 error MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "@AGENTS.md"]

Notices

📣 MegaLinter 9.5.0 is out! Discover the new features and security recommendations in the release announcement. (Skip this info by defining SECURITY_SUGGESTIONS: false)

See detailed reports in MegaLinter artifacts

Show us your support by starring ⭐ the repository

[Copilot]

Pull request overview

This docs-only PR updates repository documentation to avoid Go-version drift by deferring to go.mod, and enriches the README to better explain what the template provides and how to adopt it.

Changes:

• Update AGENTS.md to reference go.mod as the single source of truth for the minimum Go version (and document why it’s on Go 1.25.x).
• Expand README.md with a “What’s included” overview, template-usage instructions, and a maintenance pointer to AGENTS.md.
• Add megalinter to cspell.json word list.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
README.md	Adds “What’s included”, “Use this template”, and maintenance sections; currently contains a couple of tooling statements that don’t match repo config.
cspell.json	Adds megalinter to the allowed words list.
AGENTS.md	Removes hard-coded Go version and defers to go.mod to prevent future drift.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.