---
name: wallora-searcher
description: Project-specific guide for working on the Wallora searcher Next.js app. Use when Codex is asked to modify, debug, design, review, build, lint, or explain this project, especially public APIs with JWT auth, admin session auth, protected admin pages, SEO public pages, shadcn UI, Supabase data with wg_ table prefixes, gallery photo sync jobs, Aliyun OSS images, NextAuth authentication, Swagger/OpenAPI docs, files under app/, public/, Next.js configuration, Tailwind CSS styling, package scripts, or project setup.
---

# Wallora Searcher

## Purpose

Use this skill to work consistently inside the Wallora searcher project. Treat the local codebase as the source of truth and keep changes aligned with the current Next.js App Router, React, TypeScript, and Tailwind CSS setup.

## First Steps

1. Confirm the working directory is the project root: `/Users/luoyangwei/Documents/workspace/wallora.top/searcher`.
2. Read `references/project.md` when the task involves commands, current baseline state, or project conventions.
3. Read `references/architecture.md` when the task involves API design, authentication, authorization, admin features, public website pages, data storage, image upload/storage, or API documentation.
4. Read `references/supabase-gallery-sync.md` when the task involves gallery photos, Unsplash sync, cron jobs, Supabase migrations, or `wg_gallery_*` tables.
5. Inspect the relevant files before editing. Prefer `rg` and targeted `sed -n` reads.

## Project Workflow

- Use `pnpm` commands because the project has `pnpm-lock.yaml` and `pnpm-workspace.yaml`.
- Use the App Router under `app/`; avoid creating a `pages/` tree unless the project intentionally changes architecture.
- Keep UI work in React Server Components by default. Add `"use client"` only when interactivity, state, effects, or browser APIs require it.
- Use shadcn/ui as the base UI system once it is initialized. Check `components.json` and installed UI components before importing or adding components.
- Prefer Tailwind utility classes and the existing `app/globals.css` theme variables before adding custom CSS.
- Keep metadata in `app/layout.tsx` current when building user-facing pages.
- Do not assume a Git repository is present in this directory; verify before using Git-based workflows.
- Do not add Vercel-specific deployment config unless the user explicitly changes the deployment target. This project is not planned for Vercel.

## Product Architecture

- Separate three surfaces clearly: public API clients, authenticated admin users, and public SEO website visitors.
- Treat API JWT authorization and admin session authorization as different trust boundaries. Do not reuse admin session checks as public API authorization.
- Store application data in Supabase and design RLS/policies deliberately for every exposed table.
- Prefix application-owned Supabase table names with `wg_`.
- Store image files in Aliyun OSS; keep metadata, ownership, and public/private visibility decisions in Supabase.
- Treat raw gallery rows as admin curation data. Public gallery APIs should expose picked rows only.
- Picked photos use `wg_gallery_photos.is_picked` plus `picked_*` and `oss_*` metadata; admin pick/unpick should mirror selected images to Aliyun OSS when `OSS_*` env vars are configured.
- App photo APIs live under `/api/v1/gallery/photos`; list/detail endpoints expose picked photos only and include `isFavorited` when a Bearer app-user JWT is provided.
- Collections are built from picked photos with `wg_photo_collections` and `wg_photo_collection_items`; admin CRUD lives at `/admin/collections` and public APIs live under `/api/v1/gallery/collections`.
- App user features use `wg_app_users`, `wg_user_favorites`, and `wg_user_settings`; public app user auth is email/password plus Bearer JWT, kept separate from admin NextAuth sessions. Admins can view and enable/disable app users under `/admin/users`.
- Use NextAuth for authentication flows where appropriate, especially account/password admin login and session persistence.
- Generate and update `swagger.yaml` when API routes or request/response contracts change.
- Protect every page under `app/(admin)` except `/admin/login`. Use route middleware/proxy and server-side layout checks for protected admin route groups.

## Frontend Expectations

- Build the actual usable experience as the first screen; avoid placeholder landing copy unless explicitly requested.
- Keep layouts responsive from mobile through desktop using stable dimensions, clear spacing, and readable type.
- Use visual assets for website/app experiences when they materially improve the feature. Prefer existing public assets only when they are relevant.
- Avoid adding decorative gradients, oversized marketing sections, or generic template aesthetics unless the user asks for that direction.
- When adding interactive UI, include loading, empty, error, and disabled states where the workflow naturally needs them.

## Verification

Run the smallest useful checks after edits:

```bash
pnpm format:check
pnpm lint
pnpm build
```

For visual or interaction changes, start the dev server with `pnpm dev` and verify in the browser at `http://localhost:3000`. Use screenshots or browser inspection when layout quality matters.

If a command fails because dependencies are missing, install with `pnpm install` only after confirming that is appropriate for the workspace.

## References

- `references/project.md`: project snapshot, file map, scripts, conventions, and current baseline notes.
- `references/architecture.md`: role model, auth boundaries, storage choices, API documentation expectations, and implementation guardrails.
- `references/supabase-gallery-sync.md`: `wg_` table naming, gallery sync schema, Unsplash cron workflow, and non-Vercel scheduler expectations.