chore: strengthen agent onboarding, lint pinning and CI structure

[whg517]

Summary

Makes it easier for an AI agent (or a new human contributor) to pick up this repository and not break it. Three commits, reviewable independently.

Changes

chore: pin markdownlint and add lint/verify scripts

Markdown lint ran through markdownlint-cli2-action, which pins markdownlint-cli2 internally. Nothing told a contributor which version that was, so running npx markdownlint-cli2 locally pulled the latest instead — 0.23 enforces MD060 (table-column-style) and reports ~46 violations on tables CI considers clean. That trap already cost time here.

The version now lives in package.json as an exact devDependency, matching what the action was already resolving, and the globs live in an npm script so local and CI cannot disagree:

Script	Does
npm run lint:md	markdownlint over *.md, docs/**, i18n/**
npm run lint	lint:md + typecheck
npm run verify	lint + build — mirrors CI end to end

Pinning to the version already in effect keeps this a pure guardrail change with no new violations. Upgrading later means either fixing the MD060 tables or disabling the rule, and should be its own PR.

ci: split lint, build and deploy into separate jobs

Four fixes:

• npm install → npm ci. With a committed lockfile, npm install can resolve differently from what is pinned. Added setup-node's npm cache while there.
• Build was hiding inside the deploy job. On a PR the check that actually verified the build was reported as "Deploy to GitHub Pages", which deploys nothing. Build is now its own job scoped to PRs; deploy is scoped to main pushes and still builds what it publishes.
• The deploy job checked out shallow while showLastUpdateAuthor / showLastUpdateTime are enabled. Those read git history, so at depth 1 every page reported the same last-updated date. Both building jobs now use fetch-depth: 0.
• Trigger and permission scoping. push is limited to main so forks stop running the whole workflow on every branch push; superseded PR runs cancel but an in-flight deploy never does; the default token drops to contents: read except in deploy.

No status check was required by branch protection (verified via the API — only required_approving_review_count: 1), so renaming jobs is safe.

docs: rewrite AGENTS.md for agent onboarding, symlink CLAUDE.md

AGENTS.md described the repository but omitted most of what is needed to avoid breaking it, and a few details were wrong (typecheck is tsc, not npx tsc --noEmit). Added:

• npm run verify as the definition of done
• The four traps this repo has produced: unpinned markdownlint; MD013's strict: false exemption making "max 200 characters" not literal; byte-vs-character counting inflating CJK line lengths ~3x; mermaid being unverifiable from build output because it renders client-side
• Content state: 13 of 24 pages are placeholders, with the command to list them, so a stub is not mistaken for a real page
• The en/zh mirroring invariant and how to check it — Docusaurus falls back to English, so the build stays green when it is violated
• The Chinese-prose-in-the-English-tree inconsistency, flagged as something not to copy
• Which sidebar categories are autogenerated and which need hand-editing
• A do-not-stack-PRs rule, with the fix: render mermaid diagrams instead of raw code blocks #33/chore: fix markdown lint coverage, write-translations command, and a deprecation #35/fix: remove duplicated markdown and themes config keys (main is red) #36 breakage as the stated reason

CLAUDE.md is a symlink to AGENTS.md — git mode 120000, not a copy — so both conventions resolve to one file.

Testing

• npm run verify exits 0 — 52 files linted, 0 errors, both locales built
• npm ci succeeds from a clean node_modules
• Workflow YAML parses; jobs resolve to Lint (always), Build (PR only), Deploy to GitHub Pages (push only, needs lint)
• CLAUDE.md resolves to AGENTS.md (identical content, symlink preserved in the index)
• Verified against the repo's own facts before documenting them: en/zh trees match 1:1, 13/24 placeholders, gh-pages branch exists, architecture is a manual sidebar entry

Note for Windows contributors

With core.symlinks disabled, git materialises CLAUDE.md as a text file containing the path AGENTS.md rather than following it. Mentioned in the commit body.

🤖 Generated with Claude Code