# 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.