chore: add GitHub secrets setup tools and guide

- setup-secrets.sh: Bash script using gh CLI
- setup-secrets.py: Python script using GitHub API
- GITHUB_SECRETS_SETUP.md: Comprehensive guide with 4 methods

Methods include:
1. Manual web UI (easiest, no tools)
2. GitHub CLI (fast)
3. Python script (automated)
4. Raw API (advanced)

Pick any method - all accomplish the same goal securely.

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

Author: bhunt

GITHUB_SECRETS_SETUP.md

@@ -0,0 +1,307 @@
+# GitHub Secrets Setup Guide
+
+There are 4 ways to add the required secrets to your GitHub repository. Pick the one that works best for you.
+
+---
+
+## Method 1: Manual Web UI (Easiest, 5 minutes)
+
+**No tools required. Just a browser.**
+
+### Steps
+
+1. Go to: `https://github.com/ciscoittech/binary-math-system/settings/secrets/actions`
+
+2. Click **"New repository secret"** button (top right)
+
+3. For each of these 5 secrets, follow the pattern:
+   - Click "New repository secret"
+   - Enter **Name** (from list below)
+   - Enter **Value** (from sources below)
+   - Click "Add secret"
+
+### Secrets to Add
+
+#### 1. `CLOUDFLARE_API_TOKEN`
+- **Where to get**: https://dash.cloudflare.com/profile/api-tokens
+- **How**:
+  - Click "Create Token"
+  - Use template: "Edit Cloudflare Workers"
+  - Grant all suggested permissions
+  - Copy the token
+
+#### 2. `CLOUDFLARE_ACCOUNT_ID`
+- **Where to get**: https://dash.cloudflare.com
+- **How**:
+  - Right sidebar under "Account Details"
+  - Copy "Account ID"
+
+#### 3. `TURSO_URL`
+- **Where to get**: https://turso.io/dashboard
+- **How**:
+  - Click your database
+  - Copy connection URL
+  - Format: `libsql://your-db.turso.io`
+
+#### 4. `TURSO_AUTH_TOKEN`
+- **Where to get**: https://turso.io/dashboard
+- **How**:
+  - Click your database
+  - Copy auth token
+
+#### 5. `OPENROUTER_API_KEY` (Optional)
+- **Where to get**: https://openrouter.ai/keys
+- **How**:
+  - Create API key
+  - Copy the key
+- **Note**: Only needed if using AI features
+
+### Verify
+
+Go to `https://github.com/ciscoittech/binary-math-system/settings/secrets/actions`
+
+You should see all 5 secrets listed (values are hidden for security).
+
+---
+
+## Method 2: GitHub CLI (Fast, 2 minutes)
+
+**Requires**: GitHub CLI installed (`gh`) and authenticated
+
+### Install & Authenticate
+
+```bash
+# Install if you haven't
+brew install gh
+
+# Authenticate
+gh auth login
+# Follow prompts (choose HTTPS, create token if needed)
+```
+
+### Run Our Script
+
+```bash
+# Make executable
+chmod +x setup-secrets.sh
+
+# Run the script
+./setup-secrets.sh
+```
+
+The script will:
+1. Prompt for each secret value
+2. Use `gh secret set` to add them
+3. Confirm each one
+
+### Verify
+
+```bash
+gh secret list --repo ciscoittech/binary-math-system
+```
+
+---
+
+## Method 3: Python Script (Automated, 2 minutes)
+
+**Requires**: Python 3.7+, `requests`, `pynacl` libraries
+
+### Setup
+
+```bash
+# Install dependencies
+pip install requests pynacl
+
+# Make executable
+chmod +x setup-secrets.py
+
+# Run
+python3 setup-secrets.py
+```
+
+The script will:
+1. Use GitHub API to encrypt secrets
+2. Prompt for each value
+3. Set them directly via API
+
+### What It Does
+
+- Authenticates via `gh` CLI
+- Gets public key from GitHub for encryption
+- Encrypts each secret with public key
+- Posts to GitHub API
+- Verifies setup
+
+---
+
+## Method 4: Raw GitHub API (Advanced)
+
+**For complete control / CI environments**
+
+### Prerequisites
+
+```bash
+# Get your GitHub token
+gh auth token > /tmp/github_token.txt
+
+# Or create a Personal Access Token:
+# Settings → Developer settings → Personal access tokens → Tokens (classic)
+# Scopes: repo, admin:repo_hook
+```
+
+### Manual API Calls
+
+```bash
+REPO="ciscoittech/binary-math-system"
+TOKEN="ghp_xxxxxxxxxxxx"
+
+# Get public key
+curl -X GET \
+  -H "Authorization: Bearer $TOKEN" \
+  https://api.github.com/repos/$REPO/actions/secrets/public-key
+
+# Set secret (requires encryption - see below)
+curl -X PUT \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  https://api.github.com/repos/$REPO/actions/secrets/SECRET_NAME \
+  -d '{
+    "encrypted_value": "base64_encrypted_value",
+    "key_id": "key_id_from_above"
+  }'
+```
+
+**Note**: Requires NaCl encryption. Easier to use Method 2 or 3.
+
+---
+
+## Recommended: Use Method 1 or 2
+
+### If you like clicking:
+→ **Method 1** (Web UI)
+
+### If you like terminals:
+→ **Method 2** (GitHub CLI)
+
+### If you want it fully automated:
+→ **Method 3** (Python script)
+
+---
+
+## Troubleshooting
+
+### "gh: command not found"
+```bash
+# Install GitHub CLI
+brew install gh
+
+# Then authenticate
+gh auth login
+```
+
+### "Not authenticated with GitHub"
+```bash
+# Authenticate
+gh auth login
+
+# Verify
+gh auth status
+```
+
+### "Python: No module named requests"
+```bash
+pip install requests pynacl
+```
+
+### "401 Unauthorized" (API method)
+```bash
+# Your token may have expired
+gh auth login  # Re-authenticate
+
+# Or create new Personal Access Token:
+# https://github.com/settings/tokens/new
+# Scopes: repo, admin:repo_hook
+```
+
+### Secrets not showing up
+- Refresh the GitHub page
+- Wait a few seconds (GitHub caches)
+- Verify you're in the right repo settings
+
+---
+
+## Verify Setup
+
+After adding secrets, verify they're there:
+
+### Via Web UI
+- Go to `https://github.com/ciscoittech/binary-math-system/settings/secrets/actions`
+- You should see all 5 secrets listed
+
+### Via CLI
+```bash
+gh secret list --repo ciscoittech/binary-math-system
+```
+
+Expected output:
+```
+CLOUDFLARE_API_TOKEN
+CLOUDFLARE_ACCOUNT_ID
+TURSO_URL
+TURSO_AUTH_TOKEN
+OPENROUTER_API_KEY
+```
+
+---
+
+## Next Steps
+
+After secrets are set:
+
+1. **Trigger deployment**
+   ```bash
+   git push origin main
+   ```
+
+2. **Watch GitHub Actions**
+   ```bash
+   https://github.com/ciscoittech/binary-math-system/actions
+   ```
+
+3. **Monitor logs**
+   ```bash
+   gh run list --repo ciscoittech/binary-math-system
+   ```
+
+---
+
+## Security Notes
+
+- ✅ Secrets are **encrypted** at rest in GitHub
+- ✅ Secrets are **never logged** in workflow runs
+- ✅ Only available to **authenticated deployments**
+- ✅ Not visible in pull requests or forks
+- ✅ Can be **rotated** anytime
+
+---
+
+## Secret Rotation
+
+To update a secret (e.g., if token expires):
+
+### Method 1 (Web UI)
+1. Go to Settings → Secrets
+2. Find the secret
+3. Click "Update"
+4. Enter new value
+5. Click "Update secret"
+
+### Method 2 (CLI)
+```bash
+gh secret set SECRET_NAME --repo ciscoittech/binary-math-system
+# Paste new value when prompted
+```
+
+---
+
+**Choose a method above and let's get your secrets set up!**