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

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:

# 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)

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

# 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

# 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:

# 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:

# 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.

# 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

ssh root@g4dge7.com

Direct IP (if DNS issues)

ssh root@157.230.50.250

Git SSH (for repo access)

# 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:

# 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.