gadget/site/AGENTS.md

# Agent Instructions: Gadget Code Landing Site

You are working on the Gadget Code landing site—a static React/Vite application served at **https://g4dge7.com**.

---

## Project Overview

- **Framework**: React 19 with Vite 8
- **Styling**: Tailwind CSS 4
- **Language**: TypeScript 5.8
- **3D Graphics**: Three.js with @react-three/fiber
- **Build Output**: Static files in `site/dist/`
- **Production Host**: Ubuntu 24.04 DigitalOcean droplet at `g4dge7.com`

---

## Development Commands

```bash
cd site

pnpm dev          # Start local dev server (Vite)
pnpm build        # Type check + production build
pnpm preview      # Preview production build locally
pnpm typecheck    # TypeScript check only
```

---

## Deployment to Production

### Standard Deployment

Always follow this process after making changes:

```bash
# 1. Build
pnpm build

# 2. Verify build output exists
ls -la dist/

# 3. Deploy to production
rsync -avz --delete dist/ g4dge7.com:/var/www/g4dge7.com/

# 4. Fix ownership
ssh g4dge7.com "chown -R www-data:www-data /var/www/g4dge7.com"

# 5. Verify site loads
curl -sk https://g4dge7.com/ | head -5
```

### Quick Deploy (One-Liner)

```bash
pnpm build && rsync -avz --delete dist/ g4dge7.com:/var/www/g4dge7.com/ && ssh g4dge7.com "chown -R www-data:www-data /var/www/g4dge7.com"
```

### Post-Deployment Verification

After deploying, verify:

1. **Site loads**: Visit https://g4dge7.com in browser
2. **No console errors**: Check browser dev tools Console tab
3. **Assets load**: Check Network tab for 404s
4. **Git server unaffected**: Visit https://git.g4dge7.com (should still show Gitea)

---

## Production Environment Details

### Server Configuration

| Component | Value |
|-----------|-------|
| **Domain** | `g4dge7.com` |
| **Git Domain** | `git.g4dge7.com` |
| **Web Server** | Nginx |
| **SSL** | Let's Encrypt (auto-renewing) |
| **Deploy Path** | `/var/www/g4dge7.com` |
| **SSH User** | `root` |
| **SSH Host** | `g4dge7.com` or `157.230.50.250` |

### Nginx Configuration

The site is configured with:
- **HTTP → HTTPS redirect** (301)
- **SPA routing**: All routes serve `index.html` (client-side routing)
- **Gzip compression** enabled
- **Static asset caching**: 1 year for `.css`, `.js`, images, fonts
- **Security headers**: X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy

### File Locations

```
/var/www/g4dge7.com/          # Production site root
├── index.html                # Entry point
├── favicon.png
├── icon.png
├── web-app.png
└── assets/                   # Bundled JS/CSS
    ├── index-*.css
    └── *.js
```

---

## Important Constraints

### DO NOT

- ❌ Do not modify Nginx configuration without explicit instruction
- ❌ Do not change the deploy path (`/var/www/g4dge7.com`)
- ❌ Do not modify SSL certificate configuration
- ❌ Do not deploy without testing the build locally first
- ❌ Do not use `--force` with rsync unless explicitly told to
- ❌ Do not modify the `git.g4dge7.com` Nginx config (that's Gitea)

### DO

- ✅ Always run `pnpm build` before deploying
- ✅ Always verify the build succeeds before deploying
- ✅ Always test locally with `pnpm preview` before deploying
- ✅ Always verify the site loads after deployment
- ✅ Check browser console for errors after deployment
- ✅ Use `--delete` flag with rsync to remove stale files

---

## Troubleshooting Guide

### Build Fails

```bash
# Check TypeScript errors
pnpm typecheck

# Check for missing dependencies
pnpm install

# Clear cache and rebuild
rm -rf dist node_modules/.vite
pnpm build
```

### Site Not Loading After Deploy

```bash
# Check if files were deployed
ssh g4dge7.com "ls -la /var/www/g4dge7.com/"

# Check Nginx status
ssh g4dge7.com "systemctl status nginx"

# Check Nginx config
ssh g4dge7.com "nginx -t"

# Check error logs
ssh g4dge7.com "tail -50 /var/log/nginx/error.log"

# Check file permissions
ssh g4dge7.com "ls -la /var/www/g4dge7.com/"
```

### Assets Returning 404

Usually means the build output changed filenames (hash-based) but old files weren't cleaned up:

```bash
# Re-deploy with --delete to remove stale files
rsync -avz --delete dist/ g4dge7.com:/var/www/g4dge7.com/
```

### Gitea Becomes Inaccessible

This means Nginx config was modified incorrectly. Restore from backup:

```bash
# Check git.g4dge7.com config is intact
ssh g4dge7.com "cat /etc/nginx/sites-available/git.g4dge7.com"

# Reload Nginx
ssh g4dge7.com "nginx -t && systemctl reload nginx"
```

---

## Git Workflow

This site is part of a monorepo. The production branch is `master`.

```bash
# Work on a feature branch
git checkout -b feature/your-feature

# Make changes, commit
git add .
git commit -m "feat: your changes"

# Test locally
pnpm build
pnpm preview

# Deploy to production (after review/approval)
git checkout master
git merge feature/your-feature
git push dtp master

# Then deploy the site
cd site
pnpm build
rsync -avz --delete dist/ g4dge7.com:/var/www/g4dge7.com/
```

---

## SSH Access

### Standard SSH
```bash
ssh root@g4dge7.com
```

### Direct IP (if DNS issues)
```bash
ssh root@157.230.50.250
```

### Git SSH (for repo access)
```bash
# Use IP directly (Cloudflare doesn't proxy SSH)
git@157.230.50.250:dtp/gadget.git

# Or configure SSH config (~/.ssh/config):
# Host g4dge7-git
#   HostName 157.230.50.250
#   User git
#   IdentityFile ~/.ssh/id_ed25519
```

---

## Emergency Rollback

If a deployment breaks the site:

```bash
# 1. Revert code changes in monorepo
git revert HEAD

# 2. Rebuild
pnpm build

# 3. Re-deploy
rsync -avz --delete dist/ g4dge7.com:/var/www/g4dge7.com/

# 4. Verify
curl -sk https://g4dge7.com/ | head -5
```

---

## Contact

For production access or emergencies, contact the system administrator.