Update CLAUDE.md to latest version

Author: jloh

CLAUDE.md

@@ -4,18 +4,90 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is a Docker Compose setup for Ghost, a modern publishing platform. The repository currently contains a minimal structure with a `compose.yml` file for containerized deployment.
+This is a comprehensive Docker Compose setup for running Ghost CMS in production with automatic HTTPS, optional analytics, and ActivityPub support. The repository orchestrates multiple services including Ghost, MySQL, Caddy (reverse proxy), and optional Tinybird analytics and ActivityPub federation.
+
+## Architecture
+
+The project uses Docker Compose to orchestrate these services:
+
+1. **Ghost** - The main CMS application (runs on internal port 2368)
+2. **MySQL** - Database backend with health checks and support for multiple databases
+3. **Caddy** - Reverse proxy handling HTTPS/SSL, routing, and external access
+4. **Traffic Analytics** (optional profile) - Tinybird integration for web analytics
+5. **ActivityPub** (optional profile) - Federated social networking support
+6. **Supporting services** - Tinybird setup tools and ActivityPub migrations
+
+Services communicate internally via Docker networks. Caddy handles all external traffic routing including special paths for analytics (`/_tinybird`) and ActivityPub (`/.well-known/`, `/activitypub/`).
 
 ## Common Commands
 
-Since this is a Docker Compose project, the primary commands will be:
+```bash
+# Core operations
+docker compose up -d                    # Start Ghost + MySQL + Caddy
+docker compose down                     # Stop all services
+docker compose logs -f [service]        # View logs (e.g., ghost, mysql, caddy)
+docker compose ps                       # Check service status
+docker compose pull                     # Update all images
+docker compose restart ghost            # Restart just Ghost
 
-- `docker compose up -d` - Start Ghost services in detached mode
-- `docker compose down` - Stop and remove Ghost services
-- `docker compose logs` - View service logs
-- `docker compose ps` - View running services
-- `docker compose pull` - Pull latest images
+# With optional profiles
+docker compose --profile=analytics up -d     # Include analytics services
+docker compose --profile=activitypub up -d   # Include ActivityPub services
+COMPOSE_PROFILES=analytics,activitypub docker compose up -d  # Start everything
 
-## Architecture
+# Tinybird analytics setup (if using analytics profile)
+docker compose run --rm tinybird-login       # Interactive Tinybird login
+docker compose --profile=analytics up tinybird-sync   # Sync datasources/pipes
+docker compose --profile=analytics up tinybird-deploy # Deploy configuration
+
+# Development & debugging
+docker compose exec ghost sh            # Access Ghost container shell
+docker compose exec mysql mysql -u root -p  # Access MySQL CLI
+```
+
+## Configuration
+
+All configuration is done via environment variables. Key patterns:
+
+- **Required variables**: `DOMAIN`, `DATABASE_PASSWORD`, `DATABASE_ROOT_PASSWORD`
+- **Ghost config pattern**: `section__subsection__key=value` (e.g., `mail__options__service=Mailgun`)
+- **Developer experiments**: Must set `labs__publicAPI=true` for analytics/ActivityPub features
+- **Data persistence**: Volumes stored in `./data/ghost` and `./data/mysql`
+
+### Key configuration files:
+- `.env` - Main environment configuration (create from `.env.example`)
+- `compose.yml` - Docker Compose service definitions
+- `Caddyfile` - Reverse proxy routing configuration
+- `mysql-init/create-multiple-databases.sh` - MySQL multi-database initialization
+
+## Migration from Ghost CLI
+
+The repository includes comprehensive migration tools:
+
+- `scripts/migrate.sh` - Main migration script that:
+  - Backs up existing Ghost installation
+  - Converts config.json to environment variables
+  - Preserves content and database
+  - Creates recovery script
+  - Sets up Docker Compose environment
+
+- `scripts/config-to-env.js` - Converts Ghost JSON config to .env format
+
+## Development Workflow
+
+1. Clone repository and copy `.env.example` to `.env`
+2. Configure required environment variables (domain, passwords)
+3. Enable developer experiments if using analytics/ActivityPub
+4. Run `docker compose up -d` to start services
+5. Access Ghost at `https://DOMAIN` (Caddy handles SSL automatically)
+6. Monitor logs with `docker compose logs -f ghost`
+
+For analytics setup, see `TINYBIRD.md` for detailed instructions.
+
+## Important Notes
 
-The project uses Docker Compose to orchestrate Ghost and its dependencies (typically MySQL/MariaDB database). The main configuration is defined in `compose.yml`.
+- Ghost runs internally on port 2368; Caddy exposes it on 80/443
+- Email configuration is critical even without newsletter features (used for admin notifications)
+- MySQL health checks ensure database is ready before Ghost starts
+- The compose file uses yaml-language-server schema for IDE completion support
+- For production, always use strong passwords and consider additional security measures