---
name: content-migration
description:
  Move bilingual copy out of app.js and catalog.js into typed Astro content
  collections without losing or altering a single string. Use for any task that
  relocates user-visible text.
---

# Content migration

## What you are moving

- `app.js` — ~50 `{ en, pt }` keys across `phases`, `handsOnPrompts`,
  `modelGuide`, `skillSources`, `skillInstallPrompts`
- `skills-review/catalog.js` + `submitted-catalog.js` — 24 entries with `id`,
  `author`, `title`, `status`, `focus`, `wins[]`, `improve[]`, `extras`,
  `improved` (full markdown)

These are hand-written translations with deliberate tone. **Copy them. Never
retype them.** Retyping introduces drift you will not notice.

## Schema

```ts
// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const localized = z.object({ en: z.string(), pt: z.string() });

const guide = defineCollection({
  type: 'data',
  schema: z.object({
    id: z.string(),
    model: localized,
    title: localized,
    copy: localized,
    code: localized,
  }),
});
```

Both locales **required**. A missing `pt` must be a build error — silent English
fallback is how a bilingual site quietly becomes monolingual.

## Procedure

1. Extract the literals mechanically (script, not by hand).
2. Write them into the collection.
3. Diff extracted-before against extracted-after. Must be empty.

```bash
node .agents/scripts/extract-strings.mjs app.js          > /tmp/before.json
node .agents/scripts/extract-strings.mjs src/content/    > /tmp/after.json
diff /tmp/before.json /tmp/after.json
```

4. Only then delete the source literals.

## The generator trap

`skill-reviews/improved/**/SKILL.md` is **generated** from `catalog.js`
`improved` fields by `scripts/build-skill-review.mjs`, and the output is
committed to the repo. If you move `catalog.js`, that generator breaks silently
— it will still run, just against nothing.

Either keep the generator pointed at the new collection, or replace it and
update `package.json`, `README.md`, `docs/operations-guide.md`, and the review
desk footer, all of which reference it.

## Markdown

The `improved` fields are full Markdown rendered client-side today. Move them to
real `.md` files in the collection and let Astro render at build time. That
deletes the hand-rolled renderer and improves fidelity — but re-check the review
desk's diff view, which compares original and improved source text and needs the
raw string, not just rendered HTML.