docs: tighten landing page and release framing

CHANGELOG.md

@@ -6,9 +6,11 @@
 - Refreshed the README opening section to position Hermit as a distinct open-source executor layer for Claude Code and Codex rather than a generic terminal UI.
 - Added a comparison section that explains why teams would pair Hermit with Claude Code or Codex instead of treating it as a replacement orchestrator.
 - Added explicit "who Hermit is for / not for" guidance so the landing page qualifies the intended audience instead of only describing features.
-- Added a reusable `docs/open-source-positioning.md` copy deck for repository descriptions, social preview messaging, release framing, and audience-fit guidance.
+- Added a reusable `docs/open-source-positioning.md` copy deck for repository descriptions, social preview messaging, release framing, audience-fit guidance, and topic candidates.
 - Added a final social-preview asset set: editable SVG, ready-to-upload PNG export, and a local review page under `docs/assets/` for GitHub/social-preview iteration.
 - Added `docs/social-preview-ops.md` so maintainers have a concrete review/export/upload checklist for the GitHub social preview image.
+- Added `docs/release-notes-template.md` so release blurbs and GitHub Releases can reuse the same planner/executor positioning without improvising each time.
+- Reordered the README badge row around release health and package availability, and tightened the hero copy so the landing page reads closer to the final social-preview message.
 - Updated package and repository-facing descriptions to emphasize the MCP executor + cheaper execution lane story instead of the outdated Codex-first fallback wording.
 - Tightened the public metadata around predictable local / flat-rate defaults so the repository pitch matches the current install and routing policy.
 

README.md

@@ -1,11 +1,12 @@
 # HermitAgent
 
+[![GitHub Release](https://img.shields.io/github/v/release/cafitac/hermit-agent?cacheSeconds=300)](https://github.com/cafitac/hermit-agent/releases)
 [![Python tests](https://github.com/cafitac/hermit-agent/actions/workflows/python-tests.yml/badge.svg)](https://github.com/cafitac/hermit-agent/actions/workflows/python-tests.yml)
 [![npm version](https://img.shields.io/npm/v/@cafitac/hermit-agent?cacheSeconds=300)](https://www.npmjs.com/package/@cafitac/hermit-agent)
 [![PyPI version](https://img.shields.io/pypi/v/cafitac-hermit-agent?cacheSeconds=300)](https://pypi.org/project/cafitac-hermit-agent/)
-[![npm downloads](https://img.shields.io/npm/dm/@cafitac/hermit-agent?cacheSeconds=300)](https://www.npmjs.com/package/@cafitac/hermit-agent)
+[![License: MIT](https://img.shields.io/badge/license-MIT-8b5cf6)](LICENSE)
 
-> Hermit is the executor layer for Claude Code or Codex: keep the premium orchestrator for planning and review, and offload the repetitive coding work to cheaper local or flat-rate models.
+> Hermit adds a dedicated MCP execution lane under Claude Code or Codex: keep the premium orchestrator for judgment, and route the repetitive repo work to predictable local or flat-rate models.
 
 ```
 ┌──────────────┐
@@ -19,7 +20,7 @@
 └──────────────┘
 ```
 
-Claude Code or Codex stays in charge of planning, interviewing, and review. Hermit takes the mechanical path: file edits, test runs, refactors, commits, and MCP-executed follow-through on cheaper execution models. The switch is one word in a slash command: `/foo` → `/foo-hermit`.
+Claude Code or Codex stays in charge of planning, interviewing, and review. Hermit takes the mechanical path: file edits, test runs, refactors, commits, and MCP-executed follow-through on predictable local or flat-rate execution models. The switch is one word in a slash command: `/foo` → `/foo-hermit`.
 
 Why Hermit stands out:
 - Keep your best reasoning model on the work that needs judgment, not boilerplate execution.
@@ -161,6 +162,7 @@ MIT — see [LICENSE](LICENSE).
 - [docs/hermit-variants.md](docs/hermit-variants.md) — the `-hermit` skill family
 - [docs/measure-savings.md](docs/measure-savings.md) — cost-savings measurement protocol
 - [docs/open-source-positioning.md](docs/open-source-positioning.md) — short public-facing copy for descriptions, releases, and future social previews
+- [docs/release-notes-template.md](docs/release-notes-template.md) — reusable release-note framing that matches Hermit's planner/executor positioning
 - [docs/social-preview-ops.md](docs/social-preview-ops.md) — how to review, export, and upload the GitHub social-preview image
 - [docs/assets/hermit-social-preview.svg](docs/assets/hermit-social-preview.svg) — final editable social-preview asset for repo cards and launch posts
 - [docs/assets/hermit-social-preview.png](docs/assets/hermit-social-preview.png) — ready-to-upload GitHub social-preview export

docs/open-source-positioning.md

@@ -4,7 +4,11 @@ This file keeps the short public-facing copy for repository metadata, launch pos
 
 ## One-line description
 
-MCP executor for Claude Code or Codex that offloads repetitive coding work to cheaper local or flat-rate models.
+Primary:
+MCP executor layer for Claude Code or Codex that routes repetitive repo work to predictable local or flat-rate models.
+
+Alternate:
+Dedicated MCP execution lane for Claude Code or Codex — keep premium judgment up top, and offload repo mechanics underneath.
 
 ## Short pitch
 
@@ -71,3 +75,24 @@ Cheaper execution across multiple orchestrators.
 ## Release-note framing
 
 Hermit helps teams separate high-value reasoning from high-volume execution. That means better cost control, cleaner planner/executor boundaries, and an MCP-native path from idea to tested repo change.
+
+Template: `docs/release-notes-template.md`
+
+## Topic candidates
+
+Core:
+- `mcp`
+- `mcp-server`
+- `claude-code`
+- `codex`
+- `coding-agent`
+- `local-llm`
+- `llm-routing`
+- `cost-optimization`
+
+Optional:
+- `developer-tools`
+- `model-context-protocol`
+- `agentic-workflows`
+- `terminal-ui`
+- `sub-agent`

docs/release-notes-template.md

@@ -0,0 +1,59 @@
+# Release notes template
+
+Use this template when publishing GitHub Releases, package announcements, or changelog summaries for Hermit.
+
+## Short version
+
+```md
+## What changed
+- [main user-visible change]
+- [workflow or operator-facing change]
+- [why it matters for cost, reliability, or usability]
+
+## Why it matters
+[one short paragraph connecting the change back to Hermit's planner/executor positioning]
+```
+
+## Full version
+
+```md
+## Summary
+[One sentence: what changed in this release.]
+
+## What changed
+- [Change 1]
+- [Change 2]
+- [Change 3]
+
+## Why it matters
+[Explain how this improves planner/executor separation, cost predictability, release reliability, or day-to-day usability.]
+
+## Operator notes
+- [migration / config / rollout note]
+- [verification or fallback note]
+
+## Assets
+- npm: https://www.npmjs.com/package/@cafitac/hermit-agent
+- PyPI: https://pypi.org/project/cafitac-hermit-agent/
+- README: https://github.com/cafitac/hermit-agent#readme
+```
+
+## Tone guidelines
+
+- Lead with the user-facing outcome, not internal implementation detail.
+- Use the same framing as the README and social preview: premium orchestrator for judgment, Hermit for repetitive repo execution.
+- Prefer "predictable local or flat-rate execution" over provider-specific claims.
+- Keep bullets concrete: edits, tests, commits, release follow-through, routing defaults, or maintainer workflow.
+- If the release is mostly documentation or positioning, say that plainly instead of overselling it as core product capability.
+
+## Reusable opening lines
+
+- Hermit keeps Claude Code or Codex focused on judgment while offloading repetitive repo work to a dedicated MCP executor lane.
+- This release sharpens the executor-layer experience: better operator guidance, clearer positioning, and more predictable follow-through.
+- This update improves the public-facing story around Hermit's planner/executor split without changing its core role.
+
+## Reusable closing lines
+
+- Hermit continues to optimize for one job: cheaper, more predictable execution underneath a premium orchestrator.
+- The planner stays premium; the repo mechanics stay efficient.
+- The goal remains the same: better judgment up top, cheaper follow-through underneath.