# Repository Guidelines

## Project Structure & Module Organization
This repo is an Astro-based personal homepage with build-time data syncing. Main app code lives in `src/`: reusable UI in `src/components`, page routes in `src/pages`, layouts in `src/layouts`, shared helpers in `src/utils`, and site/data config in `src/config.ts`, `src/content.config.ts`, and `src/data/`. Editable content lives under `src/content/` (`logs/`, `projects/`, `shares/`, `seafile/`, `static-assets/`). Generated sync output is written to `src/data/generated/`; treat it as build output. Static public files belong in `public/`, deployment assets in `docker/`, and operational notes in `docs/`.

## Build, Test, and Development Commands
- `npm install` — install dependencies (Node `>=22.12.0`).
- `npm run dev` — start the Astro dev server.
- `npm run build` — create a production build in `dist/`.
- `npm run preview` — serve the built site locally.
- `npm run content:sync` — pull remote content and refresh generated JSON.
- `npm run assets:sync` — download static assets listed in `src/content/static-assets/index.json`.
- `npm run rebuild` — full validation path: sync content, then build.

## Coding Style & Naming Conventions
Use TypeScript ESM and Astro components with 2-space indentation. Keep components in PascalCase (`ProjectCard.astro`), utilities in camelCase (`datetime.ts`), and CSS classes in kebab-case with BEM-style modifiers when helpful (`activity-item__meta`). Prefer small, focused modules and reuse existing loaders/schemas before adding new abstractions. Keep content JSON filenames stable as `index.json` within each content folder.

## Testing Guidelines
There is no dedicated test framework configured yet. For code or content changes, run `npm run build`; for sync-related work, run `npm run rebuild`. Treat a clean build as the minimum acceptance check, and verify changed pages in `npm run preview` when UI or content rendering changes.

## Commit & Pull Request Guidelines
Recent history favors short, intent-first commit subjects in either English or Chinese. For new commits, keep the subject concise and explain why the change exists; include Lore trailers when applicable (`Constraint:`, `Rejected:`, `Confidence:`, `Tested:`). Pull requests should summarize the user-visible change, list affected paths, note any `.env` or content-schema updates, and include screenshots for visual changes. Always report which validation commands you ran.

## Security & Configuration Tips
Copy `.env.example` to `.env` for local setup, and never commit secrets such as Gitea or Seafile tokens. When editing sync scripts in `scripts/`, document any new environment variables or external dependencies in `README.md` or `docs/`.