cafitac · cafitac · Apr 27, 2026 · Apr 27, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@
 - 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 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.
 - 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.
 

diff --git a/README.md b/README.md
@@ -161,6 +161,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/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/assets/hermit-social-preview-review.html](docs/assets/hermit-social-preview-review.html) — local review page for checking the social-preview composition before export

diff --git a/docs/open-source-positioning.md b/docs/open-source-positioning.md
@@ -63,6 +63,7 @@ Cheaper execution across multiple orchestrators.
 - Final editable asset: `docs/assets/hermit-social-preview.svg`
 - Ready-to-upload export: `docs/assets/hermit-social-preview.png`
 - Local review page: `docs/assets/hermit-social-preview-review.html`
+- Operating guide: `docs/social-preview-ops.md`
 - Intended use: GitHub social preview image export, release cards, launch posts, and docs screenshots.
 - Design direction: dark terminal-like card, premium planner on top, cheaper execution lane underneath, no provider-specific billing claims beyond predictable local / flat-rate defaults.
 - Message hierarchy: plan with Claude Code or Codex, execute repetitive repo work with Hermit, and reinforce predictable local / flat-rate routing on the supporting side of the card.

diff --git a/docs/social-preview-ops.md b/docs/social-preview-ops.md
@@ -0,0 +1,110 @@
+# GitHub social preview operations
+
+This document explains how to keep Hermit's GitHub social preview image aligned with the current repository positioning.
+
+## Canonical assets
+
+- Editable source: `docs/assets/hermit-social-preview.svg`
+- Upload-ready export: `docs/assets/hermit-social-preview.png`
+- Local review page: `docs/assets/hermit-social-preview-review.html`
+
+Treat `hermit-social-preview.svg` as the source of truth. Regenerate the PNG from it whenever the card copy or layout changes.
+
+## Current message hierarchy
+
+The image should communicate this, in order:
+
+1. Claude Code or Codex does the planning.
+2. Hermit does the repetitive repo execution.
+3. The executor lane defaults toward predictable local or flat-rate routing.
+
+If a future edit weakens that planner/executor split, update the asset before changing the GitHub preview image.
+
+## When to refresh the social preview
+
+Refresh the image when any of these change:
+
+- README hero copy or top-level positioning
+- Repository description or tagline
+- Core audience definition
+- Product framing around Claude Code / Codex / MCP executor lane
+- Visual branding such as headline, color palette, or comparison emphasis
+
+## Local review workflow
+
+### 1. Review the SVG copy
+
+Open these files together:
+
+- `docs/assets/hermit-social-preview.svg`
+- `docs/open-source-positioning.md`
+- `README.md`
+
+Check that the headline and supporting labels still match the live repository story.
+
+### 2. Review the browser page locally
+
+Open:
+
+- `docs/assets/hermit-social-preview-review.html`
+
+This page is for quick visual review before exporting or uploading.
+
+### 3. Regenerate the PNG export
+
+From the repository root:
+
+```bash
+magick docs/assets/hermit-social-preview.svg docs/assets/hermit-social-preview.png
+```
+
+Expected result:
+- `docs/assets/hermit-social-preview.png` exists
+- dimensions remain `1280x640`
+
+### 4. Verify the output shape
+
+```bash
+file docs/assets/hermit-social-preview.png
+```
+
+Expected output should include:
+- `PNG image data`
+- `1280 x 640`
+
+## GitHub upload steps
+
+1. Open the repository on GitHub.
+2. Go to `Settings`.
+3. In the repository settings page, open the social preview section near the branding/Open Graph controls.
+4. Upload `docs/assets/hermit-social-preview.png`.
+5. Save the change.
+6. Hard-refresh the repository homepage and any external preview surfaces if the old card is cached.
+
+If the GitHub UI wording shifts, search within Settings for `Social preview` or `Open Graph image`.
+
+## Upload checklist
+
+Before uploading, confirm all of the following:
+
+- The card headline still says the planner/executor split clearly.
+- Hermit is positioned as the executor layer, not another premium planner.
+- Claude Code / Codex naming matches the current README.
+- No provider-specific pricing claim has crept into the image.
+- The PNG was regenerated from the latest SVG.
+- The README `See also` section still points at the same asset paths.
+
+## Post-upload checklist
+
+After uploading on GitHub, verify:
+
+- The repo homepage preview shows the new image.
+- The preview still reads well when scaled down.
+- The card is legible against GitHub's dark and light surrounding chrome.
+- The visual message matches the README opening section.
+
+## Maintenance notes
+
+- Keep the PNG checked into the repository so maintainers can upload a known-good artifact without regenerating it.
+- Keep the SVG editable and human-readable so copy tweaks remain cheap.
+- If the image concept changes substantially, update `docs/open-source-positioning.md` at the same time so future refreshes do not drift.