# Migration 1.1.0-communication-language

**From:** versions < 1.1.0   **To:** 1.1.0

## Why

1.1.0 adds a **conversational language** setting: the language the agent *talks to the
user* in (questions, explanations, summaries, status). It is recorded in a *Communication
language* block in the project's `AGENTS.md` so every agent that reads the entry point
honours it instead of drifting between languages. Pre-1.1.0 deployments have no such block.

Scope is **dialogue only** — code, identifiers, paths, commands, log output, and
abbreviations stay in their source language, and the `docs/ai/` files + `AGENTS.md` are not
translated either. This migration changes *one* doc block, nothing else.

## Steps

1. Open the project's entry point `AGENTS.md` (the real file; `CLAUDE.md` is a symlink to it).
2. **Idempotency check** — if it already contains a `## 🗣️ Communication language` heading,
   this migration is done; skip to Verification.
3. **Ask the user** which language the agent should converse in (questions, explanations,
   summaries, status). Offer the language they're already writing in as the default.
4. Insert this block immediately **after the opening blockquote** (before `## 🧭 Memory Map`),
   replacing `<their language>` with the answer from step 3:

   ```markdown
   ---

   ## 🗣️ Communication language

   > **Talk to the user in <their language>** — every question, explanation, summary, and status update.
   > Keep code, identifiers, file paths, shell commands, log output, and abbreviations in their **source language** — translating them breaks copy-paste, search, and tooling.
   > This sets the **dialogue** language only — it does not translate the files in `docs/ai/` or this entry point, which stay in their source language (for cross-agent / cross-team portability).
   ```

5. Keep `AGENTS.md` within its ≤100-line budget (the block is ~6 lines; it fits). Do **not**
   touch any other section, and do **not** translate existing file contents.

## Verification

- `AGENTS.md` has exactly one `## 🗣️ Communication language` block, with a real language in
  place of `<their language>` (no leftover `{{COMM_LANGUAGE}}` placeholder).
- The docs cap-validator is still green (`node scripts/check-docs-size.mjs` for Node projects)
  — the entry point did not bust its line budget.
- From now on the agent's replies are in the chosen language; paths/commands/identifiers
  remain in their source language.

## Rollback

Delete the inserted `## 🗣️ Communication language` block (and its trailing `---`) from
`AGENTS.md`. No other files were changed.