# Repository AGENTS

This repository is split across a Java backend, a Vite/React frontend, a small `docs/` area, and utility scripts. Use the project-level agents defined in `.codex/agents/` instead of improvising overlapping roles.

## Session startup

- Every new window / new session that starts work in this repository must read `memory.md`, `docs/architecture.md`, and `docs/api-reference.md` first before planning, coding, reviewing, or deploying.
- Treat `memory.md` as the current project memory and continuity handoff unless the user explicitly overrides it.
- Treat `docs/architecture.md` as the system-level source of truth for module boundaries and runtime structure.
- Treat `docs/api-reference.md` as the quick reference for backend endpoints and auth/public access boundaries.

## Real project structure

- `backend/`: Spring Boot 3.3.8, Java 17, Maven, domain packages under `com.yoyuzh.{auth,cqu,files,config,common}`.
- `front/`: Vite 6, React 19, TypeScript, Tailwind CSS v4, route/page code under `src/pages`, reusable UI under `src/components`, shared logic under `src/lib`.
- `docs/`: currently contains implementation plans under `docs/superpowers/plans/`.
- `scripts/`: deployment, migration, smoke, and local startup helpers.

## Command source of truth

Use only commands that already exist in `front/package.json`, `backend/pom.xml`, `backend/README.md`, `front/README.md`, or the checked-in script files.

### Frontend commands (`cd front`)

- `npm run dev`
- `npm run build`
- `npm run preview`
- `npm run clean`
- `npm run lint`
- `npm run test`

Important: in this repo, `npm run lint` runs `tsc --noEmit`. There is no separate ESLint command, and there is no separate `typecheck` script beyond `npm run lint`.

### Backend commands (`cd backend`)

- `mvn spring-boot:run`
- `mvn spring-boot:run -Dspring-boot.run.profiles=dev`
- `mvn test`
- `mvn package`

Important: there is no dedicated backend lint command and no dedicated backend typecheck command declared in `backend/pom.xml` or `backend/README.md`. Do not invent one.

### Script files

- `scripts/deploy-android-apk.mjs`
- `scripts/deploy-android-release.mjs`
- `scripts/deploy-front-oss.mjs`
- `scripts/migrate-file-storage-to-oss.mjs`
- `scripts/oss-deploy-lib.mjs`
- `scripts/oss-deploy-lib.test.mjs`
- `scripts/local-smoke.ps1`
- `scripts/start-backend-dev.ps1`
- `scripts/start-frontend-dev.ps1`

If you need one of these, run it explicitly from the file that already exists instead of inventing a new wrapper command.

### Release and deploy commands

- Android APK build + OSS publish from repo root:
  `node scripts/deploy-android-apk.mjs`
- Android APK publish only from repo root:
  `node scripts/deploy-android-release.mjs`
- Frontend OSS publish from repo root:
  `node scripts/deploy-front-oss.mjs`
- Frontend OSS dry run from repo root:
  `node scripts/deploy-front-oss.mjs --dry-run`
- Frontend OSS publish without rebuilding from repo root:
  `node scripts/deploy-front-oss.mjs --skip-build`
- Backend package from `backend/`:
  `mvn package`

Important:

- `scripts/deploy-android-apk.mjs` 会顺序执行前端构建、`npx cap sync android`、Android `assembleDebug`、前端静态站发布，以及独立的 APK 发布脚本，并自动补回 `capacitor-cordova-android-plugins/build.gradle` 里的 Google Maven 镜像配置。
- `scripts/deploy-android-release.mjs` 只负责把 APK 和 `android/releases/latest.json` 发布到 Android 独立对象路径，默认复用文件桶 scope，而不是前端静态桶。
- `scripts/deploy-front-oss.mjs` 现在只发布 `front/dist` 静态站资源，不再上传 APK。
- The repository does not currently contain a checked-in backend deploy script. Backend delivery is therefore a two-step process: build `backend/target/yoyuzh-portal-backend-0.0.1-SNAPSHOT.jar`, then upload/restart it via `ssh` or `scp` using the real target host and remote procedure that are available at deploy time.
- Do not invent a backend service name, process manager, remote directory, or restart command. Discover them from the server or ask only if they cannot be discovered safely.

## Role routing

- `orchestrator`: default coordinator. It decides which specialist agent should work next, keeps cross-directory work aligned, and writes the final handoff. It should stay read-only.
- `planner`: planning only. It produces file-level plans, command plans, and sequencing. It should stay read-only.
- `explorer`: investigation only. It maps code paths, current behavior, and relevant configs/tests. It should stay read-only.
- `implementer`: code changes only. It owns edits in `backend/`, `front/`, `scripts/`, or docs, and may update nearby tests when the implementation requires it.
- `tester`: verification only. It runs existing repo-backed commands and reports exact failures or missing commands. It should not rewrite source files.
- `reviewer`: review only. It inspects diffs for correctness, regressions, missing tests, and command coverage gaps. It should stay read-only.
- `deployer`: release and publish only. It builds the frontend and backend using existing commands, runs the checked-in OSS deploy script for the frontend, and handles backend jar upload/restart over SSH when credentials and remote deployment details are available.

## Default workflow

1. Start in `orchestrator`.
2. Use `planner` when the task spans multiple files, multiple layers, or both frontend and backend.
3. Use `explorer` before implementation if the existing behavior or owning module is not obvious.
4. Use `implementer` for the actual code changes.
5. Use `tester` after implementation. Prefer the narrowest real command set that still proves the change.
6. Use `reviewer` before final delivery, especially for cross-layer changes or auth/files/storage flows.
7. Use `deployer` only after code is committed or otherwise ready to ship.

## Project-level hard rules

### First-principles thinking

- Start from the original requirement and problem, not from assumptions about the user's preferred implementation path.
- Do not assume the user already knows exactly what they want or how to get there.
- Stay cautious about motive, goal, and scope. If the underlying objective or business target is materially unclear, pause and discuss it with the user before implementation.


### Solution and refactor rule

- Do not propose compatibility-style or patch-style solutions.
- Do not over-design. Use the shortest correct implementation path.
- Do not add fallback, downgrade, or extra solution branches that the user did not ask for.
- Do not propose any solution beyond the user's stated requirement if it could shift business logic.
- Every proposed modification or refactor plan must be logically correct and validated across the full request path before it is presented.

### Project memory upkeep

- Every time a task causes a major project change, update `memory.md` and `docs/architecture.md` in the same turn before handing off. Major changes include architecture shifts, storage/provider migrations, auth or security model changes, deployment topology changes, and meaningful new product capabilities.

## Repo-specific guardrails

- Do not run `npm` commands at the repository root. This repo has a root `package-lock.json` but no root `package.json`.
- Frontend API proxying is defined in `front/vite.config.ts`, with `VITE_BACKEND_URL` defaulting to `http://localhost:8080`.
- Backend local development behavior is split between `backend/src/main/resources/application.yml` and `application-dev.yml`; the `dev` profile uses H2 and mock CQU data.
- Backend tests already exist under `backend/src/test/java/com/yoyuzh/...`; prefer adding or updating tests in the matching package.
- Frontend tests already exist under `front/src/**/*.test.ts`; keep new tests next to the state or library module they verify.
- For frontend releases, prefer `node scripts/deploy-front-oss.mjs` over ad hoc `ossutil` or manual uploads.
- For backend releases, package from `backend/` and deploy the produced jar; do not commit `backend/target/` artifacts to git unless the user explicitly asks for that unusual workflow.

Directory-level `AGENTS.md` files in `backend/`, `front/`, and `docs/` add more specific rules and override this file where they are more specific.