how-to-talk-to-claude/PROJECT-CONTEXT.md

# How to Talk to Claude - Starlight Website Project Context
*Session Context Dump - Continue from here*

## 🎯 PROJECT STATUS: 85% COMPLETE

### ✅ WHAT'S WORKING PERFECTLY
- **Fresh Starlight installation** at `/home/user/claude/how-to-ai-fresh/`
- **Development server running** on `http://localhost:4321`
- **Complete site structure** with proper navigation, styling, and configuration
- **All 3 Tutorials** fully restored with complete content
- **3 Key How-To Guides** restored: "Ask When Uncertain", "Fact-Check", "Persona Prompts"
- **Introduction page** complete and working
- **Quick Reference page** with fixed anchor links and full content
- **Homepage** with proper navigation cards
- **Custom styling** that enhances conversational voice
- **Astro v5.11.0** with latest Starlight - no more head parsing errors

### ⏳ WHAT NEEDS RESTORATION (Content exists, just needs copying)
**10 How-To Guides missing content:**
- `/how-to/match-tone-style.md` (frontmatter only)
- `/how-to/fix-misunderstandings.md` (frontmatter only)
- `/how-to/avoid-walls-of-text.md` (frontmatter only)
- `/how-to/get-useful-sources.md` (frontmatter only)
- `/how-to/research-unfamiliar-topics.md` (frontmatter only)
- `/how-to/organize-information.md` (frontmatter only)
- `/how-to/brainstorm-comfortably.md` (frontmatter only)
- `/how-to/get-helpful-feedback.md` (frontmatter only)
- `/how-to/personal-decisions.md` (frontmatter only)
- `/how-to/maintain-voice-writing.md` (frontmatter only)

**4 Explanations missing content:**
- `/explanations/conversations-vs-commands.md` (frontmatter only)
- `/explanations/psychology-collaboration.md` (frontmatter only)
- `/explanations/how-claude-thinks.md` (frontmatter only)
- `/explanations/making-ai-work-for-life.md` (frontmatter only)

### 📂 KEY LOCATIONS
- **Working site**: `/home/user/claude/how-to-ai-fresh/`
- **Original content**: `/home/user/claude/how-to-ai/` (all source files intact)
- **Dev server**: `npm run dev` in `/home/user/claude/how-to-ai-fresh/`
- **Site URL**: `http://localhost:4321`

### 🔧 RESTORATION PROCESS
Content restoration involves:
1. Reading original file: `/home/user/claude/how-to-ai/[XX-filename].md`
2. Extracting content after frontmatter (skip first ~5 lines)
3. Converting internal links to new structure (TABLE-OF-CONTENTS.md → /, etc.)
4. Writing to: `/home/user/claude/how-to-ai-fresh/src/content/docs/[category]/[filename].md`
5. Preserving frontmatter format:
```yaml
---
title: "Title Here"
description: "Description here" 
---
```

### 📋 FILE MAPPING (for restoration)
Original → Target:
- `06-howto-match-tone-style.md` → `how-to/match-tone-style.md`
- `07-howto-fix-misunderstandings.md` → `how-to/fix-misunderstandings.md`
- `09-howto-avoid-walls-of-text.md` → `how-to/avoid-walls-of-text.md`
- `10-howto-get-useful-sources.md` → `how-to/get-useful-sources.md`
- `11-howto-brainstorm-comfortably.md` → `how-to/brainstorm-comfortably.md`
- `12-howto-research-unfamiliar-topics.md` → `how-to/research-unfamiliar-topics.md`
- `17-howto-organize-information.md` → `how-to/organize-information.md`
- `18-howto-get-helpful-feedback.md` → `how-to/get-helpful-feedback.md`
- `19-howto-personal-decisions.md` → `how-to/personal-decisions.md`
- `20-howto-maintain-voice-writing.md` → `how-to/maintain-voice-writing.md`
- `13-explanation-conversations-vs-commands.md` → `explanations/conversations-vs-commands.md`
- `14-explanation-psychology-collaboration.md` → `explanations/psychology-collaboration.md`
- `15-explanation-how-claude-thinks.md` → `explanations/how-claude-thinks.md`
- `16-explanation-making-ai-work-for-life.md` → `explanations/making-ai-work-for-life.md`

### 🎨 DESIGN & CONFIGURATION
- **Astro config**: `/home/user/claude/how-to-ai-fresh/astro.config.mjs` - complete sidebar navigation
- **Custom CSS**: `/home/user/claude/how-to-ai-fresh/src/styles/custom.css` - conversational styling
- **Site title**: "How to Talk to Claude" 
- **Diátaxis framework**: Maintained with proper content separation
- **Navigation badges**: Working (3 guides, 13 guides, 4 guides, etc.)

### ⚠️ ISSUES RESOLVED
- **Head parsing error**: Fixed by using fresh Starlight installation
- **YAML frontmatter issues**: Resolved with clean format
- **Anchor links in reference**: Fixed to use standard markdown headings
- **Empty pages**: Pattern identified - content needs systematic restoration
- **Import statements showing**: Cleaned up in introduction page

### 🚀 NEXT STEPS
1. **Continue systematic content restoration** (~10-15 minutes to complete all)
2. **Test all internal links** work properly
3. **Build for production**: `npm run build`
4. **Deploy options ready**: GitHub Pages, Netlify, Vercel configurations included

### 🎯 FINAL GOAL
Complete, professional documentation website that:
- Preserves all original conversational voice and content
- Provides modern, accessible, responsive design
- Supports multiple learning paths (tutorials, how-to, explanations, reference)
- Ready for deployment and sharing

---

## 💬 CONTINUATION PROMPT

**To continue this work, use this prompt:**

"I'm continuing work on converting the 'How to Talk to Claude - for Humans' guide into a Starlight website. The project is 85% complete with a working site at `/home/user/claude/how-to-ai-fresh/` running on `http://localhost:4321`. 

All 3 tutorials, introduction, quick reference, and 3 key how-to guides are complete. I need to restore content for the remaining 10 How-To guides and 4 Explanations - they currently only have frontmatter. 

The original content is in `/home/user/claude/how-to-ai/` and needs to be copied to the Starlight site with proper formatting and link conversion. The site structure, navigation, and styling are all working perfectly.

Please help me systematically restore the remaining content to complete this documentation website."

**Context file created**: `/home/user/claude/how-to-ai-fresh/PROJECT-CONTEXT.md`