Using loclizr with agents

Point an agent at the Markdown and llms.txt versions below, not the HTML.

llms.txt

File	What it holds
llms.txt	Index: a description, a link per page to its Markdown twin in sidebar order, and the two files below.
llms-full.txt	Every page as Markdown in one file, the 404 page included.
llms-small.txt	For a small context window: no 404 page, note and tip asides or collapsible details, prose whitespace collapsed.

One Markdown file per page

Drop the page URL’s trailing slash and add .md: Catalogs is at guides/catalogs.md, and the landing page is at index.md.

Each opens with the title and description, then the page source:

• component imports are stripped
• asides become blockquotes
• steps, tabs, file trees and card grids lose their tags; a tab label or card title becomes bold text, and a link card becomes a bullet link

Copy page

The Copy page button beside each title copies the page source as Markdown, frontmatter first. The arrow next to it opens the page in ChatGPT or Claude with a prompt that asks for help with it.

For AGENTS.md or CLAUDE.md

Paste this into the instruction file of a project that uses loclizr. The CLI, Catalog checks and Context record pages carry the detail.

AGENTS.md

## loclizr

- Catalogs are JSON at `locales/{locale}.json`, ICU MessageFormat inside, with the source locale in
  `locales/en.json`. The compiler reads them and never writes them; you edit them directly.
- After editing a catalog, `loclizr.config.ts` or `locales/en.meta.json`, run `npx loclizr build`.
  It writes the generated tree under the config's `outDir` (`src/loclizr` in the config `init`
  writes) and `locales/loclizr.context.json` beside the catalogs.
- Never edit files under `outDir`. The generated `.js` and `.d.ts` files start with
  `` // @generated by loclizr abi=1. Do not edit; run `loclizr build`. ``, the next build
  overwrites them, and a build prunes any file carrying that header which it did not produce. A
  file under `outDir` without the header is reported as `LZ1021 outdir-foreign-file`.
- Commit `locales/loclizr.context.json` in the same change as the string edit. `build` warns
  `LZ5007 record-rewritten` when it rewrote the committed record; `check` fails with
  `LZ5003 record-stale` when the committed one no longer matches the catalogs. Per message the
  record carries the argument types, the plural or select shape, the file and enclosing scope of
  each usage, and the description if one was written.
- Descriptions for translators go in `locales/en.meta.json`, keyed by the flat message key, the
  same one every diagnostic prints:
  `{ "cart.items": { "description": "Badge under the cart icon.", "placeholders": { "count": "Line items, not quantity." } } }`.
  Two keys sharing one source text where one has no description is `LZ3012 ambiguous-source`.
- `npx loclizr check` is the CI gate. It does everything `build` does with no writes, plus
  `LZ5002 output-stale` when the generated tree on disk differs from what this build would write
  and `LZ5003 record-stale`. Do not run `loclizr build` in CI: it rewrites the record in the
  workspace and passes. `check` refuses `--no-fail`.
- Machine-readable diagnostics: `npx loclizr check --reporter json`. One JSON object on stdout
  with `schema`, `diagnostics` and `summary`. Each diagnostic carries `code`, `rule`, `severity`,
  `fatal`, `message`, `hint`, `file`, `locale`, `key`, `span` and `related`, with `null` where a
  field does not apply. `--quiet` does not thin the JSON output.
- Exit codes: 0 is clean, or warnings only at or under `--max-warnings` (no cap by default);
  1 is at least one error, or warnings over the cap; 2 is the tool could not run (invalid config,
  `outDir` outside the project, unwritable output, or a usage error). `build --no-fail` exits 0
  once output was written and belongs in dev scripts such as `predev`, never in CI.