# AGENTS.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

## Project baseline
- Stack: Nuxt 4 + Vue 3 + TypeScript + Nuxt UI + Nuxt Content.
- Package manager: `pnpm` (see `packageManager` in `package.json`).
- The current `README.md` is mostly upstream template documentation; use scripts/config in this repo as source of truth.

## Commands used in this repo
- Install dependencies:
  - `pnpm install`
- Start local dev server:
  - `pnpm dev`
- Build production bundle:
  - `pnpm build`
- Preview production build locally:
  - `pnpm preview`
- Lint:
  - `pnpm lint`
- Typecheck:
  - `pnpm typecheck`

### Database/Drizzle commands
- Push schema:
  - `pnpm db:push`
- Generate migrations:
  - `pnpm db:generate`
- Open Drizzle Studio:
  - `pnpm db:studio`

Note: `drizzle.config.ts` points to `server/db/schema.ts`, but the repository currently has `server/db/schema.ts.bak` (not `schema.ts`). DB commands may fail until schema paths/files are aligned.

## Testing status
- There is no automated test script in `package.json` and no test runner config (`vitest`, `jest`, `playwright`, etc.) checked in.
- “Run a single test” is currently not applicable in this repository.
- For validation, use:
  - `pnpm lint`
  - `pnpm typecheck`
  - manual verification via `pnpm dev`

## High-level architecture
### 1) Data model and content source
- Primary app data comes from markdown/content files in `content/novels/**` via Nuxt Content (`queryCollection('content')`).
- Pattern:
  - One novel metadata file per novel (`content/novels/<slug>/index.md`)
  - Chapter files per novel (`content/novels/<slug>/ch-*.md`)
  - Homepage curation file at `content/novels/homepage.md` (featured/trending/recent lists).

### 2) Frontend structure and routing
- UI shell and navigation live in `app/layouts/default.vue` (dashboard/sidebar/search structure).
- Page routes are file-based under `app/pages/**`.
- Core user-facing routes:
  - `/` homepage (`app/pages/index.vue`)
  - `/novels/[id]` novel detail + chapter list (`app/pages/novels/[id].vue`)
  - `/novel/[novelId]/[chapterId]` chapter reader (`app/pages/novel/[novelId]/[chapterId].vue`)
  - `/titles/search` advanced catalog search (`app/pages/titles/search.vue`)
  - `/myreading/*` local user state views (history/library/updates).

### 3) Chapter identity and reader navigation
- Chapter URLs are intentionally not the raw `ch-<n>` IDs.
- Both `app/pages/novels/[id].vue` and `app/pages/novel/[novelId]/[chapterId].vue` generate deterministic UUIDv5 chapter IDs using the same namespace constant and `${novelId}/${internalId}` seed.
- This UUID mapping is critical for route compatibility and resume/history behavior.

### 4) State and persistence strategy
- Persistent user-specific state is currently browser-side via `localStorage`:
  - `user_library`
  - `reading_history`
  - `readerPreferences`
- Shared logic lives in `app/composables/useReaderStorage.ts`.
- `myreading` pages and reader screens consume this composable and/or the same storage keys directly.

### 5) Server API layer
- Nitro handlers under `server/api/**` expose novels/chapters/search endpoints.
- Current handlers also read from Nuxt Content (`queryCollection('content')`), not from a live DB.
- `server/data/*.json` exists as legacy/sample data and is not the primary source for the current UI flows.

### 6) Repository caveats to know before editing
- `app/pages/oldbak/**` contains older backup pages; avoid treating this directory as active product surface unless explicitly migrating/reviving it.
- Type interfaces in `app/types/index.d.ts` include both dashboard-template sample types and web-novel-specific types; be careful to update the right domain types.