Architecture

Use docs/README.md as the central topic index.

1. packages/cli/bin/cli.ts — Commander program, global flags, preprocessArgv, preAction.
2. packages/cli/src/argv/ — Argv preprocessing (langs → languages, version flags).
3. packages/cli/src/config/ — Schema, load (TS/JS via jiti), resolve (duplicate config handling), init prompts.
4. packages/cli/src/core/ — Context, JSON merge/prune, extractor, dynamic/ heuristics, scanner, translator, progress, errors, languages catalog.
5. packages/cli/src/commands/ — One folder per command; logger for output.
6. packages/cli/src/utils/ — style, ansi, logger, fs, paths, rg, help.

Data flow: argv → RunOptions + overrides → resolveContext() → command → stdout/stderr via logger.

Topic hubs (canonical docs)

Topic	Where
JSON / --json	JSON output (--json), SDK operations
Runtime hosts	Runtime overview
Command vs core layout	ADR 006
CLI prompts	CLI prompt modules
Translator engine	Translator engine
Loader & user i18n wiring	Loader & config, patching overview
Project tree	tree
Languages catalog	languages command

ADRs

• ADR template — structure for new decision records
• ADR 001 — v0.x scope
• ADR 002 — Configurable translation calls
• ADR 003 — User i18n loader (opt-in)
• ADR 004 — Opt-in auto-patching
• ADR 005 — Dynamic key rebuild & prefix
• ADR 006 — Command orchestrator boundary
• ADR 007 — CLI JSON envelope contract
• ADR 008 — Cache ownership and host boundary
• ADR 009 — Share hosted snapshot contract
• ADR 010 — Locale layout and metadata modes
• ADR 011 — Runtime-neutral SDK host model