diff --git a/docs/agents/conventions.md b/docs/agents/conventions.md
index 091f23fc8..d0dd9cc1b 100644
--- a/docs/agents/conventions.md
+++ b/docs/agents/conventions.md
@@ -27,6 +27,23 @@ Applies to AI tools and humans. Many readers are non-native English speakers —
 
 Covers GitHub issues, PR titles/bodies/comments, and commit messages.
 
+## Glossary of repo jargon
+
+Terms that come up often in issues, PRs, and code comments. Link here (or gloss
+the term in one clause) the first time a PR or issue uses one of these —
+per [issue-and-pr-style.md](issue-and-pr-style.md), don't assume the reader
+already knows the vocabulary.
+
+| Term | Meaning |
+| --- | --- |
+| **Shim** | A small compatibility layer that makes old code keep compiling/working against a new API, without being the real implementation. |
+| **Transition shim** | A shim meant to be temporary — it exists only to ease an upgrade and is expected to be removed later. |
+| **Sentinel** (e.g. "consumer sentinel") | A small test project whose only job is to fail the build if something regresses — an early-warning check, not a feature. |
+| **Canonical type / namespace** | The current, "real" location of a type — as opposed to an old namespace kept alive only by a shim. |
+| **Ceiling** (of a shim/fix) | The limit of what a shim or fix covers — what it does *not* handle, so the reader knows when to reach for something else. |
+| **Shallow (by design)** | The change intentionally covers only the common case, not every possible scenario. |
+| **Blast radius** | How many consumers/how much code is affected by a change. |
+
 ## `[Experimental]` for opt-in unstable APIs
 
 Per [ADR-0004 §5](../adr/0004-calendar-versioning-and-dual-pace-channels.md) (channel ladder amended by [ADR-0008](../adr/0008-collapse-experimental-into-main.md)), public APIs that aren't ready to commit to a stability guarantee are marked with [`System.Diagnostics.CodeAnalysis.ExperimentalAttribute`](https://learn.microsoft.com/dotnet/api/system.diagnostics.codeanalysis.experimentalattribute) instead of being held back or shipped silently. The attribute ships in the .NET 8+ BCL — **no package reference needed** (the repo targets .NET 10).
diff --git a/docs/agents/issue-and-pr-style.md b/docs/agents/issue-and-pr-style.md
index c360b8990..f1a2c3474 100644
--- a/docs/agents/issue-and-pr-style.md
+++ b/docs/agents/issue-and-pr-style.md
@@ -19,7 +19,23 @@ does not constrain an agent running `gh issue create`).
   marketing tone ("elegant", "robust", "seamlessly"), no emoji section headers.
 - **Write for non-native English readers.** Plain words over idiom, short
   sentences, no slang or cultural references — many contributors read English as
-  a second language. Clarity beats cleverness.
+  a second language. Clarity beats cleverness. Concretely:
+  - **One idea per sentence.** Don't stack clauses with em-dashes or semicolons
+    ("This doesn't do X — that stands — it does Y, and gives Z a path off W").
+    Split into separate sentences or bullets.
+  - **No idioms or figurative language.** "Blast radius", "shrinks the gap",
+    "grace period", "ceiling", "shallow by design" don't translate. Say what you
+    mean literally: "affects fewer consumers", "closes the gap", "temporary
+    fallback", "limit", "handles the common case only".
+  - **Define repo jargon on first use, or link it.** Terms like "shim",
+    "sentinel", "canonical type" are fine once explained — link to the
+    [glossary in conventions.md](conventions.md#glossary-of-repo-jargon) or a
+    one-clause gloss the first time a PR uses them, don't assume the reader
+    already knows the vocabulary.
+  - **Spell out cross-references.** Don't lean on `#257`/`#253` alone — add a
+    3–5 word gloss of what each one did ("#257, the ProjectModel rename").
+  - **Prefer short, common words.** "use" over "leverage", "keep" over
+    "preserve", "shows" over "surfaces", "fixes" over "remediates".
 - **Bullets over prose** for anything enumerable.
 - **Link, don't recap.** Reference issues (`#123`), PRs, docs, and code
   (`path/to/file.cs:42`) instead of pasting them.
@@ -93,3 +109,5 @@ Closes #<issue>
 | Three paragraphs restating the title | One line, then bullets |
 | Pasting the full stack trace inline | Link to the run / collapse in `<details>` |
 | "As part of this work, I also…" | A second bullet, or a second PR |
+| "This doesn't reclassify #257 — that break stands — it shrinks the blast radius for consumers upgrading from 11.0.1–11.0.12" | "#257 (the ProjectModel rename) is still breaking. This PR only makes upgrading past it easier for 11.0.1–11.0.12 users." |
+| "Deliberately shallow… same ceiling as the generated shim" | "This only covers the common case. For everything else, use `fallout-migrate`." |