fix(docs): match blog card images to post titles and fix broken badge (#204)

* fix(docs): match blog card images to post titles and fix broken badge

- Replace broken shields.io GitHub stars badge with custom "built with
  ralph-starter" badge (PNG with Ralph icon, includes @2x retina)
- Add dedicated card images for 2 posts that were using wrong cards:
  - why-autonomous-coding.md was showing "The Ralph Wiggum Technique" card
  - validation-driven-development.md was showing "Specs Are the New Code" card
- Update all card titles/subtitles to match actual blog post frontmatter
- Fix "Five AI Coding Agents" → "5 AI coding agents" on card image
- Regenerate all 14 blog card images with correct titles

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(docs): two-tone badge with contrast and customization page

- Regenerate dark badge with contrasting backgrounds (#1a1a1e / #333338)
- Add light variant badge (gray / amber)
- Create /badge page for users to customize and copy badge code
- Add badge section to README.md
- Move badge to footer, restore GitHub stars in navbar

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(docs): add rounded corners to badge PNGs

Ensure transparent alpha channel so the rx=8 rounded corners
from the SVG clip-path are preserved in the exported PNGs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add built-with badge to top of README

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(docs): use real Ralph favicon as shields.io logo

Convert favicon-96x96.png to 14x14 base64 PNG for the shields.io
flat badge variant. The logo now shows the actual Ralph character
instead of a placeholder.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(docs): higher-res shields.io logo and natural badge size

- Upgrade Ralph logo from 14x14 to 32x32 base64 for sharper rendering
- Flat badge now renders at natural shields.io height (~20px) instead
  of being forced to 28px which made it look oversized and blurry

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(docs): remove shields.io flat badge option

Keep only Dark and Light custom badge variants which render
consistently at the right size and resolution.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: rubenmarcus

README.md

@@ -2,6 +2,10 @@
   <img src="ralph.png" alt="Ralph Wiggum" />
 </p>
 
+<p align="center">
+  <a href="https://ralphstarter.ai/badge"><img src="https://ralphstarter.ai/img/badge-built-with@2x.png" alt="built with ralph-starter" height="28"></a>
+</p>
+
 <p align="center">
   <a href="https://www.npmjs.com/package/ralph-starter"><img src="https://img.shields.io/npm/v/ralph-starter.svg?style=flat-square" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/ralph-starter"><img src="https://img.shields.io/npm/dm/ralph-starter.svg?style=flat-square" alt="npm downloads"></a>
@@ -734,6 +738,18 @@ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 For creating custom integrations, agents, or using the programmatic API, see the [Developer Extension Guide](https://ralphstarter.ai/docs/guides/extending-ralph-starter).
 
+## Badge
+
+Using ralph-starter? Add the badge to your README:
+
+[![built with ralph-starter](https://ralphstarter.ai/img/badge-built-with@2x.png)](https://github.com/multivmlabs/ralph-starter)
+
+```markdown
+[![built with ralph-starter](https://ralphstarter.ai/img/badge-built-with@2x.png)](https://github.com/multivmlabs/ralph-starter)
+```
+
+More styles available at [ralphstarter.ai/badge](https://ralphstarter.ai/badge).
+
 ## License
 
 MIT

docs/blog/2026-01-15-why-autonomous-coding.md

@@ -4,7 +4,7 @@ title: Why autonomous AI coding loops work
 authors: [ruben]
 tags: [ai, coding, automation]
 description: I spent months copy-pasting between ChatGPT and my editor before I realized the loop itself was the problem, not the AI.
-image: /img/blog/ralph-wiggum-technique.png
+image: /img/blog/why-autonomous-coding.png
 ---
 
 I spent months copy-pasting code between ChatGPT and my editor before I realized I was the bottleneck.

docs/blog/2026-01-20-validation-driven-development.md

@@ -4,7 +4,7 @@ title: Let your tests guide the AI
 authors: [ruben]
 tags: [testing, validation, quality, best-practices]
 description: AI-generated code that looks perfect can blow up at runtime. Adding tests to the loop lets the agent catch and fix its own mistakes.
-image: /img/blog/specs-new-code.png
+image: /img/blog/validation-driven-dev.png
 ---
 
 The first time I let an AI agent write code without running tests, it produced something that looked perfect. Clean code, nice comments, the works. Blew up at runtime. The second time, I added `--test` and the agent caught its own mistake and fixed it in the next loop. That's when I realized: the tests aren't just for me anymore. They're for the agent.

docs/docusaurus.config.ts

@@ -325,7 +325,7 @@ const config: Config = {
         {
           type: 'html',
           position: 'right',
-          value: '<a href="https://github.com/multivmlabs/ralph-starter" target="_blank" rel="noopener noreferrer" class="navbar__badge-link"><img src="https://img.shields.io/github/stars/multivmlabs/ralph-starter?style=for-the-badge&colorA=08080A&colorB=28282E&label=stars&logo=github&logoColor=white" alt="GitHub stars" height="28" /></a>',
+          value: '<a href="https://github.com/multivmlabs/ralph-starter" target="_blank" rel="noopener noreferrer" class="navbar__badge-link"><img src="https://img.shields.io/github/stars/multivmlabs/ralph-starter?style=for-the-badge&logo=github&logoColor=white&label=stars&color=28282E" alt="GitHub stars" height="28" /></a>',
         },
       ],
     },
@@ -358,7 +358,7 @@ const config: Config = {
           ],
         },
       ],
-      copyright: `<div class="footer__logos"><a href="/" class="footer__logo-link"><img src="/img/favicon-96x96.png" alt="ralph-starter" height="28" /></a><span class="footer__logo-separator">&</span><a href="https://multivmlabs.com" target="_blank" rel="noopener noreferrer" class="footer__logo-link"><img src="/img/multivm-logo.png" alt="MultiVM Labs" height="28" /></a></div><div class="footer__copyright-text">v${version} · vibecoded with love ❤️ by <a href="https://github.com/rubenmarcus" target="_blank" rel="noopener noreferrer">rubenmarcus</a></div>`,
+      copyright: `<div class="footer__logos"><a href="/" class="footer__logo-link"><img src="/img/favicon-96x96.png" alt="ralph-starter" height="28" /></a><span class="footer__logo-separator">&</span><a href="https://multivmlabs.com" target="_blank" rel="noopener noreferrer" class="footer__logo-link"><img src="/img/multivm-logo.png" alt="MultiVM Labs" height="28" /></a></div><div class="footer__badge"><a href="/badge" class="footer__badge-link"><img src="/img/badge-built-with.png" srcset="/img/badge-built-with@2x.png 2x" alt="built with ralph-starter" height="28" /></a></div><div class="footer__copyright-text">v${version} · vibecoded with love ❤️ by <a href="https://github.com/rubenmarcus" target="_blank" rel="noopener noreferrer">rubenmarcus</a></div>`,
     },
     prism: {
       theme: prismThemes.dracula,

docs/scripts/generate-blog-images.sh

@@ -97,66 +97,78 @@ generate_image_with_logo() {
 
 echo "Generating blog images with Ralph characters..."
 
+# Titles and subtitles must match the blog post frontmatter (title + description)
+
+generate_image "why-autonomous-coding" \
+  "Why autonomous AI coding loops work" \
+  "The loop itself was the problem, not the AI" \
+  "${IMG_DIR}/coder.png"
+
 generate_image "why-i-built-ralph-starter" \
-  "Why I Built ralph-starter" \
-  "The story behind autonomous AI coding loops" \
+  "Why I built ralph-starter" \
+  "I was copy-pasting between ChatGPT and my editor" \
   "${IMG_DIR}/coder.png"
 
 generate_image "first-ralph-loop" \
-  "My First Ralph Loop" \
-  "What happens when AI codes on repeat" \
+  "My first ralph loop" \
+  "What actually happens from start to PR" \
   "${IMG_DIR}/engineer.png"
 
+generate_image "validation-driven-dev" \
+  "Let your tests guide the AI" \
+  "Tests in the loop catch and fix mistakes" \
+  "${RALPH_DIR}/scientist.png"
+
 generate_image "claude-code-setup" \
   "ralph-starter + Claude Code" \
-  "The full setup guide" \
+  "Zero to your first automated PR" \
   "${IMG_DIR}/coder.png"
 
 generate_image_with_logo "figma-to-code" \
-  "Figma to Code in One Command" \
-  "Design specs to production components" \
+  "Figma to code in one command" \
+  "12-screen dashboard, 87 cents total" \
   "${RALPH_DIR}/scientist.png" \
   "${IMG_DIR}/figma-logo.svg"
 
 generate_image "auto-mode-github" \
-  "Automating Entire Workflows" \
+  "Automating entire workflows" \
   "From specs to PRs on autopilot" \
   "${RALPH_DIR}/astronaut-fly.png"
 
 generate_image_with_logo "linear-workflow" \
-  "Ship Linear Tasks with AI" \
-  "Daily workflow from tickets to PRs" \
+  "Ship Linear tasks with AI" \
+  "My daily workflow from tickets to PRs" \
   "${IMG_DIR}/engineer.png" \
   "${IMG_DIR}/linear.jpeg"
 
 generate_image "connect-your-tools" \
-  "From Spec to Code" \
-  "One command pulls specs from GitHub, Linear, Notion" \
+  "From spec to code in one command" \
+  "Pulls specs from GitHub, Linear, Notion" \
   "${IMG_DIR}/coder.png"
 
 generate_image "cost-tracking" \
-  "Prompt Caching Saved Me \$47" \
-  "Real cost breakdown of AI coding loops" \
+  "Prompt caching saved me \$47" \
+  "90% off input tokens after the first loop" \
   "${RALPH_DIR}/ralphwiggum.png"
 
 generate_image "specs-new-code" \
-  "Specs Are the New Code" \
-  "Why writing specs beats writing code" \
+  "Specs are the new code" \
+  "A clear spec gets you a working PR in 2 loops" \
   "${RALPH_DIR}/scientist.png"
 
 generate_image "ralph-wiggum-technique" \
-  "The Ralph Wiggum Technique" \
-  "Dumb loops, smart results" \
+  "The Ralph Wiggum technique" \
+  "AI coding agents in loops until done" \
   "${RALPH_DIR}/ralphwiggum.png"
 
 generate_image "ai-agents-comparison" \
-  "Five AI Coding Agents Compared" \
+  "5 AI coding agents compared" \
   "Claude Code, Cursor, Codex, OpenCode and more" \
   "${RALPH_DIR}/scientist.png"
 
 generate_image "vs-manual" \
-  "ralph-starter vs Manual" \
-  "One week, 12 tasks, real numbers" \
+  "ralph-starter vs manual" \
+  "6 tasks manual, 6 with ralph-starter" \
   "${IMG_DIR}/engineer.png"
 
-echo "Done! Generated 12 blog images in ${OUT_DIR}"
+echo "Done! Generated 14 blog images in ${OUT_DIR}"

docs/src/css/custom.css

@@ -432,6 +432,22 @@ body::before {
   color: var(--quantum-steel);
 }
 
+.footer__badge {
+  display: flex;
+  justify-content: center;
+  margin-bottom: var(--space-md);
+}
+
+.footer__badge-link {
+  display: inline-flex;
+  opacity: 0.8;
+  transition: opacity 0.2s ease;
+}
+
+.footer__badge-link:hover {
+  opacity: 1;
+}
+
 .footer__copyright-text {
   margin-top: 0;
 }

docs/src/pages/badge.module.css

@@ -0,0 +1,131 @@
+.main {
+  padding: 4rem 1rem;
+  min-height: calc(100vh - 60px);
+}
+
+.container {
+  max-width: 640px;
+  margin: 0 auto;
+}
+
+.title {
+  font-size: 2rem;
+  font-weight: 700;
+  margin-bottom: 0.5rem;
+}
+
+.subtitle {
+  color: var(--ifm-color-secondary-darkest);
+  margin-bottom: 2.5rem;
+  font-size: 1.05rem;
+  line-height: 1.6;
+}
+
+.preview {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 2.5rem;
+  border-radius: 12px;
+  background: var(--ifm-background-surface-color, #1a1a1e);
+  border: 1px solid var(--ifm-color-emphasis-200);
+  margin-bottom: 2rem;
+}
+
+.badgeImg {
+  height: 28px;
+  width: auto;
+}
+
+.options {
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+  margin-bottom: 2rem;
+}
+
+.optionGroup {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+}
+
+.label {
+  font-weight: 600;
+  font-size: 0.85rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  min-width: 60px;
+  color: var(--ifm-color-secondary-darkest);
+}
+
+.btnGroup {
+  display: flex;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.optionBtn {
+  padding: 0.4rem 0.85rem;
+  border-radius: 6px;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  background: transparent;
+  color: var(--ifm-font-color-base);
+  cursor: pointer;
+  font-size: 0.85rem;
+  transition: all 0.15s ease;
+}
+
+.optionBtn:hover {
+  border-color: var(--ifm-color-primary);
+}
+
+.optionBtn.active {
+  background: var(--ifm-color-primary);
+  border-color: var(--ifm-color-primary);
+  color: #000;
+  font-weight: 600;
+}
+
+.codeBlock {
+  border-radius: 8px;
+  overflow: hidden;
+  border: 1px solid var(--ifm-color-emphasis-200);
+}
+
+.codeHeader {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 0.5rem 1rem;
+  background: var(--ifm-color-emphasis-100);
+  font-size: 0.8rem;
+  color: var(--ifm-color-secondary-darkest);
+}
+
+.copyBtn {
+  padding: 0.25rem 0.75rem;
+  border-radius: 4px;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  background: transparent;
+  color: var(--ifm-font-color-base);
+  cursor: pointer;
+  font-size: 0.75rem;
+  transition: all 0.15s ease;
+}
+
+.copyBtn:hover {
+  background: var(--ifm-color-primary);
+  border-color: var(--ifm-color-primary);
+  color: #000;
+}
+
+.code {
+  margin: 0;
+  padding: 1rem;
+  font-size: 0.82rem;
+  line-height: 1.5;
+  overflow-x: auto;
+  white-space: pre-wrap;
+  word-break: break-all;
+}