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.

docs/workflow.md

@@ -0,0 +1,83 @@
+# Development Workflow
+
+This repo is intentionally simple: make changes, validate locally, then push only when ready.
+
+## Start a session
+
+```bash
+git status --short --branch
+git fetch origin main
+```
+
+If working on staging:
+
+```bash
+git switch terry-staging
+git pull --ff-only
+```
+
+If working directly on production deploy branch:
+
+```bash
+git switch main
+git pull --ff-only origin main
+```
+
+## Make changes
+
+Use the existing structure:
+
+- Public pages: `src/pages/`
+- Admin pages: `src/pages/admin/`
+- Shared components: `src/components/`
+- API helpers/types: `src/api.ts`
+- Translations/copy: `src/i18n.tsx`
+- Display helpers: `src/utils/`
+
+Avoid editing generated `dist/` files.
+
+## Validate
+
+Run:
+
+```bash
+npx tsc --noEmit
+npm run format:check
+npm run build
+```
+
+For formatting fixes:
+
+```bash
+npm run format
+```
+
+## Commit
+
+Check the diff first:
+
+```bash
+git diff
+git status --short
+```
+
+Use concise commits, for example:
+
+```bash
+git add <files>
+git commit -m "fix: remove unused imports"
+```
+
+## Push
+
+Only push when Terry asks.
+
+```bash
+git push origin main
+```
+
+or for staging:
+
+```bash
+git push origin terry-staging
+```