# Trae / Cursor / Claude AI Rules

This file is automatically loaded by AI coding agents (Trae, Cursor, Claude Code, etc.).
It enforces project-specific constraints. **Read [PROJECT_RULES.md](file:///Users/guoshuyu/workspace/gitbook/PROJECT_RULES.md) for full context.**

---

## CRITICAL — Dependency Constraints

1. **15-day rule**: Every npm package version added or upgraded MUST be at least **15 days old** from today. Check with:
   ```bash
   npm view <pkg> time --json
   ```
2. **No pre-release**: Never use `latest`, `next`, `beta`, `alpha`, `rc`, `dev`, or `canary` tags.
3. **Pinned versions**: Always pin exact versions in `package.json` (no `^` or `~`).
4. **pnpm only**: Use `pnpm` for all install/add/remove. Never run `npm install` or `yarn`.

## CRITICAL — Source of Truth Versions

These are the locked stable versions for this project (verified ≥ 15 days old):

| Package | Version | Released |
|---------|---------|----------|
| vitepress | 1.6.4 | 2025-08-05 |
| vue | 3.5.33 | 2026-04-22 |
| pagefind | 1.5.2 | 2026-04-12 |
| sass | 1.99.0 | 2026-04-02 |
| typescript | 5.9.3 | (≥15d) |
| fast-glob | 3.3.3 | 2025-01-05 |
| gray-matter | 4.0.3 | 2021-04-24 |

If you need to upgrade any of them, re-verify the 15-day rule first.

## Project Conventions

- This is a **VitePress + Pagefind** project, not a GitBook project.
- Content lives in `docs/<category>/*.md`. The legacy flat `.md` files in repo root are kept only as migration source and will be cleaned up after migration is verified.
- The sidebar is auto-generated by `scripts/migrate.mjs` from `SUMMARY.md` into `docs/.vitepress/sidebar.generated.mts`. Do not edit the generated file by hand.
- Default search uses **Pagefind**, not VitePress's local/Algolia search.

## Build & Deploy

- Build:   `pnpm run build`   (runs vitepress build + pagefind indexing)
- Dev:     `pnpm run dev`
- Preview: `pnpm run preview`
- Deploy is **only** triggered by pushing a tag matching `v*` or `release-*`. CI lives in `.github/workflows/deploy.yml`.

## Coding Style

- No comments in generated code unless explicitly asked.
- Follow existing file naming and conventions.
- Run `GetDiagnostics` after edits to verify no lint/type errors.

## CRITICAL — Open Source Privacy

This repository is PUBLIC. Never write any of the following into ANY file in the repo (including markdown, yaml, code comments, commit messages):

- Real production domain (e.g. the actual `.cn` / `.com` the site is hosted on)
- Public IP addresses
- SSH usernames (`deploy`, `root`, real personal usernames…)
- Non-default SSH port numbers
- Absolute deploy paths on the production server (e.g. `/home/<name>`, `/data/<name>`)
- Private keys, passwords, tokens, cookies

All such values MUST live in **GitHub Actions Secrets** only, referenced as `${{ secrets.XXX }}`.
When writing examples in docs, always use neutral placeholders: `your-domain.com`, `123.45.67.89`, `/var/www/<site>`, `deploy`.
When the user asks for help with their real environment, give the answer in the chat reply, but DO NOT persist real values into any file.