docs: add frontend onboarding docs

docs/deploy.md

@@ -0,0 +1,75 @@
+# Deployment
+
+Production frontend deploy is handled by Gitea Actions in `.gitea/workflows/deploy.yml`.
+
+## Trigger
+
+A push to `main` triggers the deploy workflow.
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+```
+
+## CI/deploy steps
+
+1. Checkout code.
+2. Install dependencies with `npm ci`.
+3. Type check with `npx tsc --noEmit`.
+4. Check formatting with `npm run format:check`.
+5. Build with `npm run build` using:
+
+   ```bash
+   VITE_API_URL=https://api.ark-library.com
+   VITE_DISABLE_ADMIN=true
+   ```
+
+6. Configure SSH key from `DEPLOY_KEY` secret.
+7. `rsync --delete` built `dist/` to both frontend servers:
+
+   ```text
+   ec2-user@FRONTEND_1_HOST:/var/www/ark-library/
+   ec2-user@FRONTEND_2_HOST:/var/www/ark-library/
+   ```
+
+8. Verify both servers have matching `index.html` SHA-256 checksums.
+9. Remove temporary SSH key.
+
+## Required repository secrets
+
+The workflow expects these Gitea secrets:
+
+- `DEPLOY_KEY`
+- `FRONTEND_1_HOST`
+- `FRONTEND_2_HOST`
+
+## Common failures
+
+### TypeScript fails on unused imports
+
+This repo uses `noUnusedLocals` and `noUnusedParameters`. Remove unused imports/variables and rerun:
+
+```bash
+npx tsc --noEmit
+```
+
+### Format check fails
+
+Run:
+
+```bash
+npm run format
+npm run format:check
+```
+
+Then commit the formatting changes.
+
+### Build uses wrong API
+
+Check `VITE_API_URL` in `.gitea/workflows/deploy.yml` or local `.env`.
+
+### One frontend server differs from the other
+
+The workflow compares remote `index.html` checksums. If it fails, inspect the rsync step and both `FRONTEND_*_HOST` values.