Pull ttag-cli docs into ttag.js.org (sidebar unification)

[AlexMost]

Context

Unify the library and CLI docs on a single Docusaurus site (ttag.js.org). Right now the CLI lives entirely in README.md in the ttag-cli repo — a user landing on ttag.js.org doesn't see half of the workflow. This is a structural gap that prevents "Getting Started" from ever being clear, no matter how many times we rewrite it.

Blocked by the Docusaurus v3 migration — no point doing sidebar reorg on v1 only to redo it.

A secondary motivation: prepare the ground for an Ecosystem section (msgai, related tools) and "Translation options" in Getting Started.

Target sidebar

ttag.js.org
├── Introduction
│   ├── Why ttag?
│   ├── Getting Started      ← rewritten in a separate issue
│   └── Concepts (tagged templates, gettext, .po)
├── Library
│   ├── API (t, ngettext, msgid, c, jt, gettext)
│   ├── React / JSX
│   ├── Plurals & contexts
│   ├── Multi-instance (TTag class, SSR)
│   ├── Configuration (addLocale, useLocale, defaultLang)
│   └── Validation (dev-only)
├── CLI
│   ├── Installation
│   ├── Commands
│   │   ├── extract, check, merge, update
│   │   ├── replace, translate, po2json
│   │   ├── validate, stats, spell
│   │   ├── pseudo, init, filter, color
│   │   └── web (interactive UI)
│   └── Build integration (babel-plugin-ttag, webpack, vite)
├── Babel plugin
│   └── (stub with a link to the repo for now)
└── Ecosystem
    ├── babel-plugin-ttag
    ├── msgai (translation via LLM)
    └── Related tools (Poedit, Crowdin, Weblate)

Architectural question — source of truth for CLI docs

Two options:

A. CLI docs in ttag-org/ttag-cli, synced into the website

• CLI docs live in ttag-cli/docs/ as .md
• Website pulls them via git submodule, npm tarball, or a sync script
• README in ttag-cli becomes short, links to ttag.js.org/cli

Pros: SSOT. Updating commands/foo.ts → autogenerate docs/commands/foo.md (via yargs --help parsing) → site updates on next release.
Cons: more setup, two-repo ritual.

B. CLI docs in this repo (website/docs/cli/)

• Everything in one place; sidebar updates are trivial
• README in ttag-cli stays as a full fallback

Pros: simple, no extra infra.
Cons: doc drift — release a CLI 1.12 with a new command and the other repo's docs can lag.

Intuitive recommendation: start with B (faster, lets us validate the structure), then move to A with autogeneration if drift becomes a problem.

Scope

• Finalize the sidebar (open to adjustment as we go)
• Decide A vs B for the CLI docs source-of-truth
• Create website/docs/cli/ (if B) — initially copies of README sections, then split into pages
• Move the README command block into separate pages (one page per command group, with examples)
• Create website/docs/library/ — restructure existing pages under the new hierarchy
• Create stub website/docs/ecosystem/ — babel-plugin-ttag, msgai (placeholder), related tools
• Update sidebars.js
• Verify no existing URL breaks — or add redirects (Docusaurus redirects plugin)
• Update the ttag-cli README — short description + link to ttag.js.org/cli

Out of scope

• Rewriting Getting Started — separate issue
• Adding an msgai section — blocked on a separate ecosystem positioning decision; a stub folder is fine
• Moving to another platform (VitePress, Astro Starlight) — separate discussion

Definition of Done

• ttag.js.org sidebar shows "Library" and "CLI" as parallel sections
• All CLI commands have their own pages on the site (not only in README)
• ttag-cli README is short and points to ttag.js.org/cli for the full reference
• Existing deep links to the site still work (with redirects if needed)
• Source-of-truth decision (A or B) documented