docs: add .agents workspace and the Astro refactor plan

Adds the agent-facing workspace and a 20-task plan for migrating the site to Astro. Nothing here implements the refactor; these are briefs, rules and templates that the task agents read. - .agents/ holds context, rules, checklists, skills, specialist agents, component/page/config templates and gate scripts. It is vendor-neutral so MiniMax, Gemini and Codex can all read it; CLAUDE.md just points at AGENTS.md. - .husky/ plus .lintstagedrc.json wire the three gate tiers. gate.sh locks on the shared git-common-dir so parallel worktrees serialise, and guards the assertion count in scripts/verify.mjs against a coverage drop. - plans/astro-refactor/ carries the phase graph, per-task briefs and the model-routing recommendation. These files must be tracked before fanning out: a worktree only checks out tracked files, so an untracked plan is invisible to every agent working in one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-05 01:18:27 +00:00
parent aa85c1d0b7
commit aae4d42229
79 changed files with 3805 additions and 0 deletions
@@ -0,0 +1,59 @@
+# Rule: content and i18n
+
+## Every user-visible string is content
+
+No hard-coded copy in components. Strings live in `src/content/`, typed with
+Zod, and reach components as props or collection entries.
+
+## The existing shape
+
+`app.js` already stores content as `{ en: '…', pt: '…' }` objects across
+`phases`, `handsOnPrompts`, `modelGuide`, `skillSources`, and
+`skillInstallPrompts` — about 50 `en:` keys. That shape is fine and should be
+carried across, not redesigned:
+
+```ts
+// src/content/config.ts
+const localized = z.object({ en: z.string(), pt: z.string() });
+```
+
+Both locales are **required**. A missing `pt` must be a build error, not a
+silent English fallback — that is how bilingual sites quietly become
+monolingual.
+
+## Migrating strings
+
+Copy, do not retype. These are hand-written translations with specific tone
+(`'Transforme ambiguidade em trabalho'`). Retyping introduces typos and drift.
+Move the literal, then diff the extracted content against the original file to
+prove nothing changed:
+
+```bash
+node .agents/scripts/extract-strings.mjs app.js > /tmp/before.json
+node .agents/scripts/extract-strings.mjs src/content/guide/ > /tmp/after.json
+diff /tmp/before.json /tmp/after.json
+```
+
+## Language switching
+
+Today the toggle swaps text client-side and updates `<html lang>`. Two options
+for Astro, decide in task 03:
+
+- **Keep client-side swap.** Both languages ship in the payload. Zero routing
+  change, matches today exactly, no URL work. Recommended — the content is small
+  and the current behaviour is already what people link to.
+- **Route-based (`/en/`, `/pt/`).** Better SEO, more correct, but it changes
+  every existing URL. Only do this with an explicit decision plus redirects.
+
+Whichever you pick, `<html lang>` must track the active language.
+
+## Rendered content
+
+Markdown in `catalog.js` entries (the `improved` field) should become real
+Markdown files in the collection, rendered at build time rather than by a
+hand-rolled client-side renderer. That deletes code and improves fidelity.
+
+Careful: `skill-reviews/improved/**/SKILL.md` is **generated** from those
+entries by `scripts/build-skill-review.mjs`, and the generated files are
+committed. Keep that generator working, or replace it and update every
+reference to it.