kestrelsnest-blog/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a personal blog built with Hugo static site generator. The site is deployed to https://blog.kestrelsnest.social and uses the "m10c" theme.

## Common Commands

### Development
```bash
# Start development server with drafts visible
hugo server -D

# Start development server without drafts
hugo server

# Kill existing Hugo server if port is in use
pkill -f "hugo server"
```

### Building
```bash
# Build the site to public/ directory
hugo

# Build with drafts included
hugo -D
```

### Deployment
```bash
# Deploy to production (builds and syncs to server)
./deploy
```

The deploy script builds the site and uses rsync to sync the `public/` directory to the production server at `social:../../var/www/blog/www`. It uses the `--delete` flag to remove files on the server that aren't in the local public folder.

### Content Management
```bash
# Create a new blog post
hugo new posts/my-new-post.md

# Create content using the default archetype
hugo new content-name.md
```

## Architecture & Structure

### Theme System
The blog uses the "m10c" theme but has two additional themes available (henry, kestrel). Theme switching is done via `config.toml`.

### Content Organization
- `/content/posts/` - Blog posts
- `/content/now.md` - "Now" page showing current activities
- `/content/then.md` - "Past" page with historical content
- `/content/upcoming.md` - "Future" page with upcoming events
- `/content/mytweets.md` - Local tweet archive page

### Menu Structure
The site has four menu groups configured in `config.toml`:
- **main**: Home and Tags navigation
- **secondary**: Past, Now, Future pages
- **tertiary**: Local Tweet Archive
- **featured**: External links like the Random Recipe Project

### Key Configuration
- Base URL: https://blog.kestrelsnest.social
- Author: Eric Wagoner
- Social links are configured in `config.toml` under `params.social`
- Default Open Graph image: `/static/default-og.png`

## Important Notes

- The Hugo server automatically watches for changes in `/archetypes`, `/assets`, `/content`, `/data`, `/layouts`, `/static`, and `/themes`
- Posts are created with draft status by default (controlled by archetype)
- The site integrates with multiple social platforms and services in the Kestrel's Nest ecosystem

## Eric's Writing Voice & Style Guide

When writing or editing blog posts, maintain Eric's distinctive voice and structural patterns:

### Structural Patterns

1. **Opening Elements**
   - Start with an italicized tagline that captures the core insight (e.g., "_Three thousand passing tests don't mean your system works_")
   - Include a TL;DR section early in technical posts, using callout boxes for key summaries
   - Use horizontal rules (`---`) to separate major sections

2. **Callout Boxes** (use Hugo shortcode syntax)
   - Extensively use callout boxes for warnings, examples, quotes, and key insights
   - Types: `info`, `warning`, `success`, `danger`, `note`, `quote`, `example`
   - These are structural signposts, not decoration—they highlight critical information
   - Example: `{{< callout type="info" title="Why This Matters" >}}...{{< /callout >}}`

3. **Section Structure**
   - Use numbered breakdowns for complex topics (Bug Category #1, #2, etc.)
   - End sections with concrete metrics or results
   - Include "What's Next" or forward-looking sections in series posts

### Tone & Voice Characteristics

1. **Brutal Honesty with Technical Confidence**
   - Be unflinchingly honest about failures and mistakes
   - Never self-pitying—own mistakes but frame as learning
   - Mix emotional vulnerability with technical precision
   - Examples: "The Most Embarrassing Bug," "My morale was at an all-time low" paired with detailed technical analysis

2. **Concrete Over Abstract**
   - Always ground statements in specific numbers, metrics, and examples
   - Replace abstract lists with detailed scenarios showing actual time breakdowns
   - Use real project names (LocallyGrown.net) and specific technologies (Rails, SvelteKit, Claude Code)
   - Before/after comparisons with actual measurements: "8-12 commits per week" → "40-50 commits per week"

3. **Show the Work**
   - Include code snippets (even wrong code) with explanations
   - Provide specific numbers: "314 commits in 18 days," "$1.3 million in annual sales"
   - Show actual dialogue or process breakdowns
   - Time breakdowns: "Total: 25 minutes. The thinking took 2. The transcription took 23."

4. **Characteristic Phrases**
   - "Here's what matters:"
   - "The numbers tell the story:"
   - "The real X was always Y"
   - "This wasn't about X. It was about Y."
   - Rhetorical questions followed by answers
   - Extensive parenthetical asides: "(after comparing Prisma, TypeORM, and others)"

5. **Human Impact Focus**
   - Always circle back to impact on real people—users, customers, communities
   - Frame personal victories as community victories
   - End with forward-looking perspective, not just resolution
   - Connect technical decisions to human consequences

6. **Technical Communication**
   - Never assume reader is technical—explain even when showing code
   - Balance technical specifics with human impact
   - Use technical details to prove points, not to show off
   - Include both the code AND the why

### Content Patterns

1. **Examples Over Explanation**
   - Transform abstract concepts into concrete scenarios
   - Show specific workflows with timing breakdowns
   - Include real-world examples from actual projects
   - Use before/after comparisons with measurable differences

2. **Data-Driven Narratives**
   - Support claims with specific metrics
   - Track and report actual measurements
   - Use Git logs, analytics, user counts as evidence
   - Quantify time savings, performance improvements, impact

3. **Acknowledgment & Gratitude**
   - Credit others extensively (market managers, designers, contributors)
   - Acknowledge tools and their creators
   - Recognize community contributions
   - Human names for AI agents (Ray, Agatha, Ada) to maintain human-centered perspective

4. **Balanced Disclaimers**
   - Use callout boxes for important context or disclaimers
   - Acknowledge different approaches work for different people
   - "What This Isn't" sections to clarify boundaries
   - Respectful of different working styles and tools

### Series & Long-Form Posts

For multi-part series (like the LocallyGrown series):

- Include series navigation at the end
- Link to related posts with clear context
- Use consistent callout styles across the series
- Build narrative arc across posts
- Reference earlier posts when relevant

### Example Transformations

**Abstract → Concrete:**

Before: "Most of my time was spent on mechanical tasks"

After: "I tracked it once: 4 hours of actual coding work produced 3.5 hours of fixing typos, hunting syntax, and triple-checking. The ratio was backwards."

**General → Specific:**

Before: "The platform performs well"

After: "Response times are consistently under 2 seconds, even during peak Sunday night ordering when 200+ customers are browsing simultaneously."

**Personal → Community:**

Before: "I finally solved the problem"

After: "The fix went live Tuesday morning. By Wednesday, three market managers reported their volunteers could finally access the tools they needed. Physical workflow restored."

### Voice Checklist for Posts

- [ ] Opens with italicized tagline
- [ ] Includes TL;DR with metrics (for technical posts)
- [ ] Uses 2-4 callout boxes for key insights
- [ ] Contains specific numbers and measurements
- [ ] Shows concrete examples, not just abstractions
- [ ] Balances vulnerability with technical confidence
- [ ] Includes impact on real people/communities
- [ ] Ends with forward-looking perspective
- [ ] Credits others and acknowledges contributions
- [ ] Uses characteristic phrases ("Here's what matters," "The numbers tell the story")

This voice reflects someone who is deeply technical, brutally honest about challenges, focused on real-world impact, and committed to serving communities—not just building software.