docs: add AGENTS.md

Author: ChouChiu

AGENTS.md

@@ -0,0 +1,82 @@
+# AGENTS.md
+
+VitePress 2.0.0-alpha static site for the MicYou Android microphone app. Vue 3 + pnpm + Biome.
+
+## Commands
+
+```bash
+pnpm dev            # Dev server at localhost:5173
+pnpm build          # Production build → .vitepress/dist/
+pnpm preview        # Preview production build
+pnpm lint           # Biome linter check
+pnpm format         # Biome auto-fix formatting
+pnpm fetch:ghdata   # Fetch GitHub release/contributor data (needs GH_TOKEN or GITHUB_TOKEN)
+pnpm llms:generate  # Generate llms.txt and llms-full.txt
+```
+
+No test framework is configured. There are no tests to run.
+
+## Architecture
+
+- `src/` is the VitePress source directory (`srcDir: "./src"` in config)
+- `.vitepress/config.mts` — Main config: locales, SEO, head tags, markdown plugins
+- `.vitepress/data/i18n.ts` — Central i18n exports (nav, footer, component translations)
+- `.vitepress/data/lang/zh.ts`, `en.ts`, `zh_tw.ts` — Per-language UI translations
+- `.vitepress/theme/index.ts` — Custom theme entry: registers global components, Umami analytics
+- `scripts/fetch-gh-data.ts` — GitHub GraphQL API fetcher for release/contributor data
+- `scripts/generate-llms-txt.ts` — Generates LLM-friendly text files
+
+### Key Content Structure
+
+```
+src/
+├── index.md, download.md, video.md, changelog.md  ← Top-level pages (zh-CN default)
+├── docs/           ← Documentation pages with sidebar config in sidebar.ts
+├── en/             ← English translations (mirror src/ structure)
+├── zh-TW/          ← Traditional Chinese translations
+└── public/         ← Static assets (images, ghdata.json, favicon)
+```
+
+## i18n — Three Locales Required
+
+Every content change must exist in all three locations:
+- `src/<page>.md` → `src/en/<page>.md` → `src/zh-TW/<page>.md`
+
+UI translations live in `.vitepress/data/lang/` and are re-exported through `.vitepress/data/i18n.ts`.
+
+Sidebar config uses `sidebarTranslations` in `src/docs/sidebar.ts` — update all three language blocks.
+
+## Biome Formatting
+
+- Tabs for indentation, double quotes for JS/TS strings
+- Vue files: `noUnusedImports`, `noUnusedVariables`, and `organizeImports` are disabled (auto-reordering can break template refs)
+- Pre-commit hook: Husky runs `lint-staged` which auto-formats staged `*.{js,ts,vue,json,mts,mjs,cjs,cts}` files
+
+## Frontmatter Required
+
+All doc pages need `title` and `description` in frontmatter for SEO. Homepage uses `layout: home` instead.
+
+## Images
+
+Place in `src/public/`, reference with root-relative paths (`/image.png`). Never use external image links (GitHub attachments, external URLs).
+
+## Data Pipeline
+
+`ghdata.json` at `src/public/ghdata.json` is generated by `scripts/fetch-gh-data.ts` (runs via GitHub Actions every 6 hours). Components fetch it at runtime with cache-busting — do NOT static-import it.
+
+The fetch script uses GitHub GraphQL API to count non-merge commits on master (matching GitHub `/graphs/contributors` counting). It excludes bots and core maintainers defined in `EXCLUDE_USERS`.
+
+## Dependencies
+
+- `@theojs/lumen` — Theme component library (BoxCube, Card, Links, Pill, Footer, CopyText, umamiAnalytics)
+- `@mdit/plugin-figure` — Markdown figure plugin for images
+- `marked` — Markdown parsing (used in ChangelogViewer for runtime rendering)
+- `iconify-icon` — Icon component (registered as custom element in VitePress config)
+
+## Deployment
+
+Auto-deploys to GitHub Pages via GitHub Actions on push to `main`. Build output in `.vitepress/dist/`.
+
+## Commits
+
+Conventional commits format: `feat:`, `fix:`, `docs:`, `chore:`, etc.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md