AGENTS.md · diff

git:20260819.88f979a to git:20261116.e9c142a

20 added, 78 removed. Audit A to B.

What this update changes in the checks

This update newly trips 1 check:

  • No link to a raw IP address
    matched: http://127.0.0.1:3000

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

- # Agent Instructions
-
- ## Operating Context
-
- This repository is Motion Lexicon, a static React + TypeScript product for visual animation vocabulary.
-
- Use these files as the current project context:
-
- - `README.md`: project overview, commands, routes, SEO model, and delivery status.
- - `PRODUCT.md`: product promise, user model, phase strategy, and quality bar.
- - `DESIGN.md`: launch architecture, visual system, URL state, and acceptance criteria.
- - `prototype/motion-lexicon-prototype.html`: archived phase-one reference; current production styling lives in `src/styles.css` and `src/library.css`.
-
- ## Communication
-
- - Write Chinese by default.
- - Use direct positive phrasing. Avoid先否定再转折的表达方式。
- - Be concrete about files, commands, routes, and verification results.
-
- ## Product Boundary
-
- - Keep this as a static frontend application unless the user adds a server-side requirement.
- - Store content, assets, categories, recipes, and i18n data on the frontend.
- - Preserve the V6 component-library system: a quiet chroma-zero shell, expressive Product Mono, Editorial Warm, and Spatial Dark scenes, black primary actions, a restrained blue state color, thin borders, compact radii, small mono metadata, dominant preview canvases, and dense documentation structure.
- - Keep the product workflow centered on browsing motion, previewing behavior, tuning parameters, copying prompt/code, and reading review guidance.
- - Treat React as the site implementation. User-facing exports are portable Prompt, HTML, CSS, and framework-independent JavaScript where interaction requires it.
- - Keep the V6 release contract at exactly 100 Components across 11 categories and 10 Page Blocks. Preserve 44 canonical Primitives and all 91 source terms through canonical mappings and redirects; the Motion Lexicon Skill remains independently versioned at 4.2.0.
-
- ## Technical Stack
-
- - Vite, React, TypeScript.
- - Tailwind CSS v4 plus the project stylesheet in `src/styles.css`.
- - Local shadcn-style UI components backed by Radix primitives.
- - lucide-react icons.
- - TanStack Router.
- - i18next and react-i18next.
- - react-helmet-async for route metadata.
- - Build-time static prerendering through `src/entry-server.tsx` and `scripts/prerender.ts`.
- - Vitest and Playwright for verification.
-
- ## SEO Model
-
- SEO is generated during `npm run build`.
-
- The build flow is:
-
- 1. `tsc -b`
- 2. `vite build`
- 3. `tsx --tsconfig tsconfig.app.json scripts/prerender.ts`
-
- `scripts/prerender.ts` enumerates static routes from `src/data/site.ts`, calls the React server renderer in `src/entry-server.tsx`, injects Helmet tags from `src/components/Seo.tsx`, writes `dist/<route>/index.html`, then writes `dist/sitemap.xml` and `dist/robots.txt`.
-
- The deployed artifact is static HTML, CSS, and JS. Runtime deployment can use static hosting such as Cloudflare Pages, Vercel static output, Netlify, or any CDN-backed file server.
-
- ## Quality Gates
+ # Motionboard: notes for agents
- Before handing work back, run the relevant checks:
+ motionboard.app: 38 launch-film shot recipes and a free HyperFrames skill for Claude Code and Codex. Status, next steps and log: `~/code/home/projects/motionboard.md`. Shared site rules: `~/code/home/lines/sites.md`. Design: `DESIGN.md`.
- ```bash
- npm run lint
- npm run typecheck
- npm run test
- npm run i18n:check
- npm run vocabulary:check
- npm run seo:check
- npm run motion:check
- npm run a11y:check
- npm run build
- npm run bundle:check
- npm run crawl:dist
- npm run test:visual
- ```
+ ## Commands
+ - `npm run dev`: local dev server (http://127.0.0.1:3000).
+ - `npm run build`: generates recipe files, `public/robots.txt`, `public/_redirects`, the video sitemap, then prerenders every page.
+ - `npm test`: build, then `scripts/test.mjs` checks the output (sitemap ↔ pages, canonical, hreflang, titles, descriptions, JSON-LD, internal links, redirects, video sitemap, robots).
+ - `npm run deploy`: build and deploy with the `cf` CLI (never wrangler), then pings IndexNow.
+ - `scripts/upload-media.sh`: films and posters in `media/` (gitignored) go to the R2 bucket behind the media host. Video renders never run on the Mac.
- For UI or routing changes, also inspect `/zh/`, `/zh/components/`, `/zh/primitives/slide-in/`, and `/zh/guides/` in a browser.
+ ## Where things are
+ - `src/site.config.ts`: the only place for domain, media host, name, languages, PostHog key variable, IndexNow key, social defaults and hreflang alternates. Scripts import it too.
+ - Content: `src/data/terms.json` + `en.json` (recipes), `src/data/seo/<slug>.json` (search copy), `src/data/pages/<id>.json` (hubs and guides, schema in `src/data/content.ts`), `src/data/renamed.json` (old slug → new, drives the 301s).
+ - SEO head: `seoHead()` in `src/lib/seo.ts`; sitemap pages in `vite.config.ts`.
+ - Analytics: `src/lib/track.ts` (PostHog, shared project "Sites", cookieless) + `src/components/Analytics.tsx`. Every event has `site=motionboard` and `lang`. Cloudflare Web Analytics is injected at the edge.
+ - Skill: `skills/motionboard/` (runnable HyperFrames sources per recipe).
- ## Implementation Notes
+ ## Checks before reporting a UI change
+ - `npm test` passes.
+ - `node ~/code/home/tools/design-check/check.mjs --allow posthog.com --allow cloudflareinsights.com --allow motionboard.app <url>`. Known false positive: on the home page at 1440 it reports `load failed: hero-film-m.mp4`. The browser fires `error` on a `<source>` whose `media` does not match, and nothing actually fails to load.
+ - Home Lighthouse on pagespeed.web.dev (the local kit's Lighthouse runs behind a proxy, so its performance numbers are lower).
- - Recipe pages need stable H1 content, canonical URLs, localized metadata, and shareable query state.
- - Preview markup, controls, Prompt, HTML, CSS, and reduced-motion behavior must come from the same motion specification.
- - Default query values should stay omitted from the URL.
- - Mobile layouts should put the active recipe workflow before the full catalog list.
- - Interactive targets should stay at least 44px where users tap or click.
- - `prefers-reduced-motion` should remove non-essential movement while preserving meaning.
+ ## Handoff (2026-11-16)
+ The repo moved from `~/Documents/motion-lexicon-site` to `~/code/sites/motionboard`. The task-3 audit table, with what passed, what was fixed and what waits on Rui: `~/Library/Application Support/Claude/side-session-notes/local_b345c0d6-e7e0-4bab-8a09-d8143b50b9a1/mb-task3-audit.md`. Open item: aligning with the shared design system (light theme, 17px body and the related size changes) waits on Rui.