docs: add frontend onboarding docs

AGENTS.md

@@ -0,0 +1,76 @@
+# AI Agent Instructions
+
+This file is the first-stop context for AI coding agents working in this repo.
+
+## Repository identity
+
+- Project: Arkie Library Frontend / ARK database web UI.
+- Package name: `ark-database-web`.
+- Stack: React 18, TypeScript, Vite, Tailwind CSS, React Router, RainbowKit/Wagmi.
+- Backend API is expected at `/api`; uploaded assets under `/uploads`.
+
+## Branch rules
+
+- Current deploy branch: `main`.
+- Work/staging branch available: `terry-staging`.
+- Do not commit or push unless Terry explicitly asks.
+- Pushing to `main` triggers production frontend deploy via Gitea Actions.
+- Before branch-changing or pulling, run `git status --short --branch` and preserve local work.
+
+## Required checks
+
+Before proposing a push or deploy, run:
+
+```bash
+npx tsc --noEmit
+npm run format:check
+```
+
+If code formatting is needed, run:
+
+```bash
+npm run format
+```
+
+Notes:
+
+- `tsconfig.json` has `strict`, `noUnusedLocals`, and `noUnusedParameters`; unused imports fail CI.
+- `dist/` is build output and should not be edited manually.
+
+## App structure quick map
+
+- `src/main.tsx` chooses normal app vs admin-only build using `VITE_ADMIN_ONLY`.
+- `src/App.tsx` contains public routes and conditionally exposes admin routes unless `VITE_DISABLE_ADMIN === "true"`.
+- `src/api.ts` defines `apiBase`, fetch helpers, and shared resource/category types.
+- `src/i18n.tsx` contains all UI copy for `zh-TW`, `zh-CN`, and `en`.
+- `src/pages/admin/` contains admin UI screens.
+- `src/adminPaths.ts` handles admin path prefix logic. Keep it in sync with backend/nginx admin host config if changed.
+
+## Environment variables
+
+See `.env.example` and `README.md` for details. Do not commit real secrets or private deployment keys.
+
+Common production public build env:
+
+```bash
+VITE_API_URL=https://api.ark-library.com
+VITE_DISABLE_ADMIN=true
+```
+
+## Deployment context
+
+`.gitea/workflows/deploy.yml` deploys on push to `main`:
+
+1. `npm ci`
+2. `npx tsc --noEmit`
+3. `npm run format:check`
+4. `npm run build` with production public env
+5. rsync `dist/` to both frontend servers
+6. compare remote `index.html` checksums
+
+## Agent behavior preferences
+
+- Answer Terry in concise Chinese unless the task requires code/docs in English.
+- Prefer small, direct fixes over broad refactors.
+- Update README/docs/memory when learning non-obvious project facts.
+- Search existing project memory before making decisions about workflow, deploy, or conventions.