Merge remote docs reorganization with new consolidated COMPILER_ARCHITECTURE.md

Author: skeptomai

.github/workflows/deploy-pages.yml

@@ -34,6 +34,11 @@ jobs:
       - name: Build WASM
         run: wasm-pack build --target web --out-dir web/pkg --no-default-features --features wasm
 
+      - name: Create build info
+        run: |
+          echo "{\"commit\":\"${GITHUB_SHA:0:7}\",\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" > web/buildinfo.json
+          cat web/buildinfo.json
+
       - name: Setup Pages
         uses: actions/configure-pages@v4
 

.gitignore

@@ -19,3 +19,23 @@ build.out
 # WASM build output
 pkg/
 web/pkg/
+
+# Private AWS configuration
+.aws-config
+.aws-infrastructure
+
+# CDK Infrastructure
+infrastructure/node_modules/
+infrastructure/cdk.out/
+infrastructure/.env
+infrastructure/*.js
+!infrastructure/lib/*.js
+!infrastructure/bin/*.js
+infrastructure/**/*.d.ts
+infrastructure/**/*.js.map
+infrastructure/lambda/**/target/
+infrastructure/lambda/**/*.lock
+
+# Frontend build artifacts
+frontend/node_modules/
+frontend/.parcel-cache/

CLAUDE.md

@@ -76,20 +76,35 @@ When the user says "Engage!", you should automatically:
 4. **Push the tag to trigger CI:**
    - `git push origin vX.Y.Z`
    - GitHub Actions will automatically build all binary assets and create a DRAFT release
-5. **Wait for CI completion:**
+5. **Deploy to staging:**
+   - Run `./infrastructure/scripts/deploy-frontend.sh staging`
+   - This auto-deploys with visible watermark showing commit hash + timestamp
+   - Verify staging deployment at https://staging.gruesome.skeptomai.com
+   - Check that watermark displays correctly in browser (bottom-right corner)
+6. **Wait for CI completion:**
    - Monitor CI builds to ensure all assets are created
    - Verify draft release has all binary assets
-6. **Publish the release:**
+7. **Publish the release:**
    - Use `gh release edit vX.Y.Z --title "vX.Y.Z: <title>" --notes "<release notes>" --draft=false`
    - Include comprehensive changelog of significant changes
    - This moves the release from DRAFT to published (Latest)
-7. **Confirm success:**
-   - Verify release is marked as "Latest" with `gh release list`
-   - Report the new version number
-   - Provide links to the published release
-   - Confirm all binaries are available for download
-
-You are pre-authorized for all git and GitHub CLI operations. Execute the entire workflow without asking for permission.
+8. **Ask permission to deploy to production:**
+   - Present summary of changes and release notes
+   - Request explicit user approval: "Ready to deploy vX.Y.Z to production?"
+   - Wait for user confirmation before proceeding
+9. **Deploy to production (if approved):**
+   - User must run: `./infrastructure/scripts/deploy-frontend.sh prod`
+   - User will be prompted to type 'DEPLOY TO PRODUCTION' to confirm
+   - After deployment, verify at https://gruesome.skeptomai.com
+   - Check that watermark shows release version (e.g., "v2.16.2")
+10. **Confirm success:**
+    - Verify release is marked as "Latest" with `gh release list`
+    - Report the new version number
+    - Provide links to the published release
+    - Confirm all binaries are available for download
+    - Confirm staging and production watermarks are correct
+
+You are pre-authorized for all git and GitHub CLI operations. For production deployment, you MUST ask the user to run the deployment command manually due to the interactive safety prompt.
 
 ## Re-Release Instructions ("Reengage!")
 
@@ -127,6 +142,73 @@ You are pre-authorized for all operations. Execute without asking for permission
 
 Safe operations only: `git add`, `git commit`, `git push`, `git checkout`, `git stash`, `git revert`
 
+## CRITICAL: DEPLOYMENT SAFETY RULES
+
+**NEVER deploy to production without explicit permission and verification.**
+
+### Rule 1: Always Test Deployments Before Reporting Success
+
+**NEVER claim a deployment was successful without testing it.**
+
+When deploying code changes:
+1. ✅ Deploy the code
+2. ✅ **TEST the deployed functionality** (API calls, health checks, etc.)
+3. ✅ **VERIFY the changes are actually working**
+4. ✅ Check logs for errors
+5. ✅ **ONLY THEN** report success to the user
+
+**Examples of what NOT to do:**
+- ❌ "Deployment complete!" (without testing)
+- ❌ "Updated Lambda function" (without verifying it works)
+- ❌ "Should be working now" (without confirming)
+- ❌ Assuming deployment worked based on AWS response alone
+
+**Correct approach:**
+- ✅ "Deployed to staging. Testing..." → run actual tests → "Verified working: [test results]"
+- ✅ "Lambda updated. Checking API..." → curl endpoint → "API returning correct data: [sample]"
+
+**Rationale**: The 2025-12-20 incident where I deployed OLD code to production because I didn't verify the bootstrap.zip was actually rebuilt. User discovered the issue, not me. This is unacceptable.
+
+### Rule 2: Never Deploy to Production Without Permission
+
+**Production deployments REQUIRE explicit user permission.**
+
+**Deployment workflow (MANDATORY):**
+1. ✅ Make code changes
+2. ✅ Deploy to **STAGING** first
+3. ✅ **TEST staging thoroughly**
+4. ✅ **ASK USER** for permission to deploy to production
+5. ✅ Wait for explicit approval
+6. ✅ Deploy to production
+7. ✅ **TEST production** to verify
+8. ✅ Report verified success
+
+**NEVER:**
+- ❌ Deploy to production without asking
+- ❌ Deploy to production before testing staging
+- ❌ Deploy to production "because it worked in staging"
+- ❌ Assume production deployment is authorized
+
+**The ONLY exception**: If user explicitly says "deploy to both staging and production" or similar.
+
+**Rationale**: The 2025-12-20 incident where I deployed to production at 00:20:01 without permission. User discovered this only when they said "look things over again before we deploy to production" - but I had already deployed. This violated user's trust and control over their production environment.
+
+**Technical Safeguard**: The `deploy-frontend.sh` script now requires manual confirmation for production deployments. When deploying to production, the script prompts:
+```
+⚠️  WARNING: You are about to deploy to PRODUCTION ⚠️
+Type 'DEPLOY TO PRODUCTION' to continue:
+```
+
+This interactive prompt **cannot be bypassed by Claude** - production deployments now require the user to run the command manually. Staging deployments proceed without prompting.
+
+**As Claude**: I cannot deploy to production via `deploy-frontend.sh prod` because I cannot provide interactive input. I can only deploy to staging. For production, I must ask the user to run the deployment command themselves.
+
+### Deployment Documentation
+
+See `infrastructure/LAMBDA_DEPLOYMENT.md` for complete Lambda deployment procedures.
+See `infrastructure/QUICK_LAMBDA_DEPLOY.md` for quick reference.
+Use `infrastructure/scripts/deploy-lambda.sh` for automated, verified deployments.
+
 ## Compiler Debugging Tools
 
 **IR Inspection**: Use `--print-ir` flag to print intermediate representation:

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "gruesome"
-version = "2.15.0"
+version = "2.16.2"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

Cargo.toml

@@ -0,0 +1,179 @@
+# Development Workflow
+
+## Local Development
+
+### Setup
+
+1. **Install dependencies:**
+   ```bash
+   cd frontend
+   npm install
+   ```
+
+2. **Choose your API mode:**
+   - **Production API** (default): Test against real backend at api.gruesome.skeptomai.com
+   - **Mock API**: Test without backend (local mock server)
+
+### Running Locally
+
+#### Option A: Test with Production API (Recommended)
+
+```bash
+cd frontend
+npm run dev
+```
+
+Then open http://localhost:3000
+
+This uses the real production API. You can create test accounts and they'll be stored in production Cognito.
+
+#### Option B: Test with Mock API
+
+Terminal 1 - Start mock API server:
+```bash
+cd frontend
+node mock-api.js
+```
+
+Terminal 2 - Start frontend with mock mode:
+```bash
+cd frontend
+# Edit dev-config.js and set apiMode: 'mock'
+npm run dev
+```
+
+**Mock API credentials:**
+- Username: `testuser`
+- Password: `TestPassword123`
+- Password reset code: `123456`
+
+### Live Reload
+
+Browser-sync automatically reloads when you edit HTML, CSS, or JS files. Just save and the browser refreshes!
+
+### Testing Checklist Before Deploy
+
+Before deploying to staging or production, test locally:
+
+- [ ] Login form works (shows username + password)
+- [ ] Signup form works (shows email + username + password)
+- [ ] Forgot password works (shows username only)
+- [ ] Password reset confirmation works (shows username + code + new password)
+- [ ] Toggle links switch modes correctly
+- [ ] "Back to Login" returns to login mode from reset modes
+- [ ] No browser console errors
+- [ ] Form validation works (can't submit empty fields)
+- [ ] Form validation errors don't appear for hidden fields
+
+## Staging Environment
+
+### Purpose
+
+Staging is a complete replica of production for testing changes before deploying to users.
+
+- **URL**: https://staging.gruesome.skeptomai.com
+- **API**: https://api-staging.gruesome.skeptomai.com
+- **Separate**: Own Cognito, DynamoDB, S3 buckets
+
+### Deploy to Staging
+
+**Frontend only:**
+```bash
+cd infrastructure
+./scripts/deploy-frontend.sh staging
+```
+
+**Full stack (infrastructure + backend + frontend):**
+```bash
+cd infrastructure
+npx cdk deploy --all --app "npx ts-node bin/gruesome-platform-staging.ts"
+```
+
+**Backend Lambda only:**
+```bash
+cd infrastructure/lambda/gruesome-api
+cargo lambda build --release --arm64 --package auth
+cd ../../
+npx cdk deploy GruesomeBackendStackStaging --app "npx ts-node bin/gruesome-platform-staging.ts"
+```
+
+### Testing on Staging
+
+1. Visit https://staging.gruesome.skeptomai.com
+2. Create a test account (separate from production)
+3. Test all functionality:
+   - Login/Signup/Password Reset
+   - Game loading
+   - Save/Load
+4. Check CloudWatch logs for errors
+5. If everything works, deploy to production
+
+## Production Deployment
+
+### Frontend Only (Quick Updates)
+
+```bash
+cd infrastructure
+./scripts/deploy-frontend.sh prod
+```
+
+### Full Stack
+
+```bash
+cd infrastructure
+npx cdk deploy --all
+```
+
+### Backend Lambda Only
+
+```bash
+cd infrastructure/lambda/gruesome-api
+cargo lambda build --release --arm64 --package auth
+cd ../../
+npx cdk deploy GruesomeBackendStack
+```
+
+## Workflow Summary
+
+```
+Local Dev (localhost:3000)
+  ↓ Test & Verify
+Staging (staging.gruesome.skeptomai.com)
+  ↓ Test & Verify
+Production (gruesome.skeptomai.com)
+```
+
+**Never skip staging!** Always test on staging before production.
+
+## Common Issues
+
+### "Required field" errors on hidden inputs
+
+Make sure HTML inputs don't have hardcoded `required` attributes. JavaScript manages `required` dynamically.
+
+### CORS errors in local dev
+
+If using production API locally, make sure CORS is configured to allow `http://localhost:3000`.
+
+### CloudFront cache issues
+
+After deploying, wait 1-3 minutes for CloudFront invalidation. Use hard refresh (Cmd+Shift+R).
+
+### Mock API not working
+
+Make sure mock-api.js is running on port 3001 and dev-config.js has `apiMode: 'mock'`.
+
+## Architecture
+
+```
+Local: localhost:3000 → Production API (or Mock API on :3001)
+Staging: staging.gruesome.skeptomai.com → api-staging.gruesome.skeptomai.com
+Production: gruesome.skeptomai.com → api.gruesome.skeptomai.com
+```
+
+Each environment is completely isolated with separate:
+- Cognito User Pools
+- DynamoDB tables
+- S3 buckets
+- Lambda functions
+- CloudFront distributions