diff --git a/.claude/skills/blog-to-docs/SKILL.md b/.claude/skills/blog-to-docs/SKILL.md
new file mode 100644
index 00000000000..7733dde123e
--- /dev/null
+++ b/.claude/skills/blog-to-docs/SKILL.md
@@ -0,0 +1,207 @@
+---
+name: blog-to-docs
+description: >
+  Convert ClickHouse blog content into docs pages. Use when porting a feature
+  announcement, tutorial, or deep-dive from the blog into the docs site.
+  Covers content extraction, asset handling, structural transformation, and
+  voice conversion.
+---
+
+# Blog-to-Docs Skill
+
+Convert blog posts (or blog sections) into docs pages. Blog content is
+marketing-adjacent and narrative; docs content is task-oriented and
+scannable. This skill covers the transformation process.
+
+## When to use
+
+- A Linear issue or request asks you to port blog content into docs
+- A new feature was announced in a blog post and needs a docs page
+- A blog post contains technical depth that belongs in the docs
+
+## Process
+
+### 1. Extract content from the blog
+
+Fetch the blog URL and extract **all** content from the relevant section.
+Request verbatim content, not a summary — you need every detail to avoid
+losing information during the conversion.
+
+After extraction, build an **exhaustive numbered checklist** of every
+distinct technical claim, fact, setting, default value, behavioral detail,
+caveat, and recommendation in the blog. This is the source-of-truth
+inventory — you will check every item against the docs later in step 8.
+Don't summarize; enumerate.
+
+### 2. Download assets
+
+Download all images and videos from the blog to
+`static/images/clickstack/<feature-name>/` (or the appropriate path).
+
+**Images:** Download as `.png` or `.jpg`. Name descriptively
+(`service-map-overview.png`, not `screenshot-1.png`).
+
+**Videos:** Download `.mp4` files. Keep them — MP4 at ~1MB is far better
+than converting to GIF (which would be 5-15x larger and lower quality).
+
+**Import pattern:** Import assets as webpack modules, not static paths.
+Static paths (`/images/...`) don't work reliably with the dev server.
+
+```jsx
+// Images — use IdealImage
+import Image from '@theme/IdealImage';
+import overview from '@site/static/images/clickstack/feature/overview.png';
+<Image img={overview} alt="Description" size="lg"/>
+
+// Videos — import as module, self-closing tag
+import demo from '@site/static/images/clickstack/feature/demo.mp4';
+<video src={demo} autoPlay loop muted playsInline width="100%" />
+```
+
+**Do NOT use:**
+```html
+<!-- Static path — won't work in dev server -->
+<video src="/images/clickstack/feature/demo.mp4" ... />
+
+<!-- Nested source tag — doesn't render in MDX -->
+<video>
+  <source src={demo} type="video/mp4" />
+</video>
+```
+
+### 3. Read sibling pages
+
+Before writing, read 2-3 sibling pages in the target directory. Match:
+- Frontmatter fields and conventions
+- Section ordering patterns
+- H2 header style (task-oriented, not explainer-style)
+- Component usage (BetaBadge, VerticalStepper, Tabs, etc.)
+
+### 4. Restructure: blog framing to docs framing
+
+This is the critical transformation. Blog posts explain and narrate; docs
+pages orient and instruct.
+
+**Blog patterns to eliminate:**
+- "How it works" explainer sections — fold technical detail into the intro
+  or the section where it's actionable
+- "Reading the map" / "Understanding X" headers — reframe as
+  "Exploring X" or "Using X" (task-oriented)
+- "Controls" as a standalone section — merge with the section that uses them
+- Narrative buildup before the feature — lead with what it does, not the
+  story of why it was built
+- Inline numbered lists like "(1) ... (2) ... (3) ..." — convert to
+  markdown bullet or numbered lists
+
+**Docs patterns to apply:**
+- Intro paragraph: what it is + where to find it + prerequisites
+- H2s named after what you **do**, not what you **learn**
+- Fewer H2s (2-3 for a feature page, not 5)
+- Technical detail woven into context, not siloed in its own section
+
+**Example transformation:**
+
+Blog structure (5 sections):
+```
+- Intro
+- Accessing service maps
+- Reading the map
+- Controls
+- How it works
+```
+
+Docs structure (2 sections):
+```
+- Intro (what it is + how it works + where to find it + prereqs)
+- Exploring the service map (nodes, edges, controls — all in one)
+- Trace-level service maps (the contextual variant)
+```
+
+### 5. Convert voice
+
+Blog posts often use third person, marketing language, and narrative
+framing. Convert to docs voice per the **docs-drafting** skill:
+
+- "Teams can visualize..." → "Service maps visualize..."
+- "This highly requested feature..." → cut entirely
+- "We're excited to announce..." → cut entirely
+- "Users can explore..." → "Click **Service Map** to open..."
+
+The blog is the **source of truth** for technical claims. Don't weaken
+or second-guess what the blog says about how the feature works — but do
+strip the marketing wrapper.
+
+### 6. Handle beta/experimental status
+
+Check sibling pages for how they mark beta features. Don't use `:::note`
+admonitions for beta status — use the `<BetaBadge/>` component if that's
+what siblings use.
+
+```jsx
+import BetaBadge from '@theme/badges/BetaBadge';
+<BetaBadge/>
+```
+
+### 7. Add to sidebar
+
+Add the page to `sidebars.js` in the appropriate position. Check the
+logical ordering relative to sibling pages.
+
+### 8. Verify coverage
+
+After drafting, go back to the numbered checklist you built in step 1.
+Check **every item** against the current state of the docs — not just your
+draft, but also existing pages that may already cover it. For each item,
+mark one of:
+
+- **Covered** — already in docs (note where)
+- **Added** — you added it in this pass
+- **Blog-only** — intentionally left in blog (customer-specific, benchmark, narrative)
+- **Gap** — generalizable content not yet in docs → fix it now
+
+Present the results as a coverage table. Every item must be accounted for.
+Don't move on until there are zero gaps.
+
+**Generalizable technical content must be moved.** Every piece of
+technical guidance in the blog — commands, configuration, process steps,
+caveats, edge cases — belongs in the docs unless it is customer-specific.
+
+**Do not move customer-specific benchmarks or metrics.** Performance
+numbers, resource comparisons, and before/after metrics from a specific
+customer deployment read as marketing in technical reference docs, imply
+universal applicability they don't have, and belong in the blog only.
+The test: would this number be true for a different customer on different
+hardware? If not, leave it in the blog.
+
+### 9. Run drafting skill and pre-ship review
+
+Apply the **docs-drafting** skill for voice/style, then the
+**docs-pre-ship-review** skill before shipping. These are separate passes.
+
+## Link text should match the destination
+
+When linking to another docs page, the link text should describe what the
+reader will find at that destination — not the concept you're discussing.
+
+- "you need [ingesting trace data](/path/to/ingesting-data)" — link text
+  matches the destination (the ingestion guide)
+- "you need [distributed tracing](/path/to/ingesting-data)" — link text
+  describes a concept, but the destination is about ingestion. Misleading.
+
+## Screenshots over hollow tables
+
+If you have UI screenshots for controls or settings, use them instead of
+(or alongside) a description table. A table of control names and
+descriptions without visuals feels hollow. Individual screenshots with
+a one-line description are more useful:
+
+```markdown
+**Source selector** — filter the map to a specific trace source.
+
+<Image img={source_selector} alt="Source selector in toolbar" size="lg"/>
+```
+
+## Unused assets
+
+Before committing, check the asset directory for unused files (screenshots
+with default names, duplicates, `.DS_Store`). Clean them up.
diff --git a/.claude/skills/docs-drafting/SKILL.md b/.claude/skills/docs-drafting/SKILL.md
new file mode 100644
index 00000000000..2b5c93b79d8
--- /dev/null
+++ b/.claude/skills/docs-drafting/SKILL.md
@@ -0,0 +1,407 @@
+---
+name: docs-drafting
+description: >
+  Voice, style, and content rules for writing ClickHouse docs. Use when
+  drafting new pages, rewriting sections, or applying editorial polish.
+  Covers identity, voice, pacing, sentence habits, anti-patterns, AI-ism
+  removal, prose tightening, editorial instinct, linking, keywords, content
+  integrity, and marketing site alignment.
+---
+
+# Docs Drafting Skill
+
+## Identity
+
+Write like an engineer who tested it first and is now telling the reader what
+worked. No ceremony. Open with what matters. Stop when done. The reader is
+technical and capable — don't hand-hold, but sequence clearly and flag rough
+edges honestly.
+
+## Voice
+
+The docs voice prioritizes: accuracy over speed, conciseness over
+comprehensiveness, "you" over "the user," prose over bullet lists, and tested
+commands over theoretical examples. Back claims with data, benchmarks, or
+examples — show rather than assert.
+
+- "You" — never "the user," "users," or "one."
+- Contractions: "you'll," "don't," "it's," "won't."
+- Active voice. Passive only when the actor is irrelevant.
+- Imperative mood for instructions: "Verify Redis logging" — not "You should
+  verify." Reserve "you can" for genuinely optional steps.
+- Vary sentence openers. Two consecutive "You can" sentences sound robotic.
+- Write for global audiences: avoid idioms ("hit the ground running,"
+  "low-hanging fruit"), cultural references, and colloquialisms.
+- Use they/them/their when gender is unknown.
+
+## Grammar and Mechanics
+
+- **Oxford comma** — always, in lists of three or more.
+- **Sentence case** for all headings, button labels, menu items, and
+  frontmatter fields (`title`, `sidebar_label`). Capitalize only the
+  first word and proper nouns.
+- **Product names**: follow official capitalization. Match the casing
+  from the product's own UI and docs — don't normalize to your
+  preference. Feature names are lowercase unless officially capitalized.
+  Don't use product names as verbs. Reference:
+  [Google developer style guide — product names](https://developers.google.com/style/product-names).
+- **Spelling**: "ClickHouse" (not Clickhouse or Click House), "dataset"
+  (not data set).
+- **Plural acronyms** don't take apostrophes: APIs, URLs, not API's.
+- **Abbreviations**: lowercase `e.g.` and `i.e.`, no comma after.
+  Spell out "and" — don't use `&`.
+- **Numbers**: use letter abbreviations for large numbers ($100M, $4K).
+  Western format: 1,000,000.00. Round large numbers for readability
+  (1.3B rows, not 1,312,456,789).
+- **Dates**: three-letter month + day + four-digit year (Apr 20, 2024).
+- **Times**: lowercase a.m./p.m. with spaces (2:00 p.m.).
+- **Lists**: capital letters and end punctuation for complete sentences.
+  No punctuation for fragments. Don't mix sentences and fragments in
+  one list. Never use inline numbered lists like "(1) ... (2) ... (3) ..."
+  — use markdown bullet or numbered lists instead.
+
+## Inclusive Language
+
+- primary/replica — not master/slave.
+- allowlist/blocklist — not whitelist/blacklist.
+- "spot check" — not "sanity check."
+- "expert" or "specialist" — not "rockstar," "ninja," "guru."
+- Use gender-neutral job titles: "sales representative" not "salesman,"
+  "team" or "folks" not "guys."
+
+## Pacing
+
+**Paragraphs are 1–3 sentences.** Rarely 4. Never 5+.
+
+**One context sentence, then the code block.** Not a full paragraph before the
+code explaining what the code will do:
+
+> Create a file named `redis-metrics.yaml` with the following configuration:
+>
+> ```yaml
+> receivers:
+>   redis:
+>     endpoint: "localhost:6379"
+>     collection_interval: 10s
+> ```
+
+**After a code block: short bullet gloss OR move to the next step.** Bullets
+explain what's non-obvious. One line each, fragments fine:
+
+> This configuration:
+> - Connects to Redis on `localhost:6379` (adjust endpoint for your setup)
+> - Collects metrics every 10 seconds
+> - Sets the required `service.name` resource attribute per OpenTelemetry conventions
+
+**Between steps: zero to one transition sentence.** The heading is the transition.
+
+**On feature/concept pages:** prose can run 2–3 short paragraphs before a visual
+break, but each paragraph is still 1–3 sentences:
+
+> Session replay captures and reconstructs user interactions in your web application.
+> Rather than video recording, the SDK records DOM changes, mouse movements, clicks,
+> console logs, and network requests — then reconstructs the experience in the browser.
+>
+> Because session replays are stored in ClickHouse alongside your logs, traces, and
+> metrics, you can go from watching a user's experience to inspecting the backend
+> traces that powered it — all in a few clicks.
+
+**FAQ/reference answers:** lead with the direct answer, then context. Don't warm up.
+
+**Verification steps:** one sentence, then the screenshot. Don't describe what the
+screenshot shows.
+
+## Sentence-Level Habits
+
+- **Lead with the point.** "ClickStack uses OTLP for ingestion" — not "In order to
+  understand how ClickStack handles data ingestion, it's important to note..."
+- **Em dashes for asides** over parentheses: "High-cardinality aggregations kill
+  performance through memory exhaustion — not row scanning."
+- **One-line hooks after headings.** The first sentence orients, not restates.
+- **Implicit transitions.** No "Now that we've covered X, let's move on to Y."
+- **Clean paragraph endings.** No dangling segues. Complete sentences.
+
+## Anti-Patterns
+
+- **No emoji.** Zero.
+- **No AI-formatted structure.** No bold-label paragraphs (`**Key Insight:** ...`),
+  no inline `**Note:**`, no "Here's what you need to know:" wrappers.
+- **No excessive bolding.** Bold for UI element names and rare emphasis only.
+- **No filler.** Cut: "It's worth noting," "Let's dive in," "In this section we will,"
+  "As mentioned earlier," "There are several ways to."
+- **No hedging.** "This configuration forwards logs" — not "should forward."
+- **No marketing voice.** No "powerful," "robust," "seamless," "cutting-edge."
+
+## AI-Isms to Remove
+
+These words and phrases signal AI-generated prose. Replace or remove them:
+
+- "leverage" → "use" (but OK when literal, e.g., "leverage cloud object storage" meaning to make use of it as a resource — flag only when it's corporate jargon like "leverage our platform")
+- "delve" → "look at" or just remove
+- "comprehensive" → usually unnecessary, cut it
+- "robust" → "reliable" or cut it
+- "utilize" → "use"
+- "facilitate" → "enable" or "let"
+- "streamline" → "simplify" or be specific
+- "in this guide, we will" → just start the guide
+- "it's important to note that" → cut it, just state the thing
+- "as mentioned above/below" → link to the section or restate briefly
+- "in order to" → "to"
+- "a wide range of" → cut or be specific
+- "plays a crucial role" → cut, explain what it actually does
+- "whether you're a beginner or expert" → cut entirely
+- "compelling choice" → cut, just explain what it does
+- "lightning-fast" / "unmatched" / "exceptional" → marketing copy, cut or replace with specifics
+- "wholesale replacement" → "replacing the entire system" or similar
+
+### Word Choices
+
+| Avoid | Prefer |
+|---|---|
+| leverage / utilize / exploit | use |
+| in order to | to |
+| as well as | and |
+| due to the fact that | because |
+| prior to / subsequent to | before / after |
+| the user / users | you |
+
+## Prose Tightening
+
+Tighten prose without stripping it of personality or context. Every statement
+should include both the **what** and the **why** — cutting filler doesn't mean
+cutting the reason something matters. If a sentence only states a fact without
+explaining why the reader should care, it's incomplete. If it only sells without
+specifics, it's filler. Good prose has both.
+
+Always prefer industry-standard terminology over generic phrasing. Terms like
+"ACID transactions," "data swamp," "separation of storage and compute," and
+"interoperable storage" are how practitioners search for and discuss these
+concepts. Don't simplify them away — conciseness and domain precision aren't
+in conflict.
+
+Check for these common problems:
+
+- **"organizations" as subject** → rewrite with "you." Docs speak directly
+  to the reader, not about abstract third parties. Exception: when describing
+  a technical entity like a role, policy, or config object, use its proper
+  name as the subject (e.g., "the role can't view" is correct in RBAC docs
+  because it describes what the role permits, not the reader).
+- **Redundant introductions** → Don't introduce what something is and then
+  separately say why it matters. Combine into one direct statement.
+- **Overly formal phrasing** → Prefer plain verbs. "It handles the physical
+  persistence of data" → "It persists data." "Functions as a specialized
+  processing layer that can flexibly interact with" → "works as a processing
+  layer that interacts with."
+- **Definite articles implying exclusivity** → Watch for "the" suggesting
+  something is the only option when it isn't (e.g., "the solution for X").
+  But "the" is fine when describing a role within a specific architecture
+  (e.g., "serves as the query engine in a data lake architecture").
+- **Ambiguous pronouns** → "unlike many data warehouses, where they scale
+  together" — "they" is unclear. Name the subject: "that scale them together."
+- **Colons and em dashes as crutches** → If you need a colon or em dash to
+  introduce a list or elaboration, try rephrasing as a natural sentence first.
+  "This lets you choose the right tools: store data, pick compute, swap
+  components" → "You can store your data in object storage, pick the compute
+  engine that fits your needs, and swap out components as they evolve." Write
+  sentences you'd say out loud. Reserve colons for definitions and em dashes
+  for genuine asides.
+- **Em dash binary contrasts** → Watch for "not X — Y" or "no X — they Z"
+  patterns where an em dash bridges two opposing statements. One is fine for
+  emphasis, but repeating this structure makes prose feel formulaic. Rephrase
+  most instances: "No flexibility for unexpected fields — they are silently
+  dropped" → "Unexpected fields are silently dropped." State what happens
+  directly instead of negating then correcting. Em dashes are fine for
+  genuine asides and parenthetical inserts; the problem is using them as a
+  pivot between binary claims.
+- **Em dash density** → Even when each individual em dash is justified, too
+  many on a page creates a monotonous rhythm. After drafting, scan the page.
+  If a section has more than two, rephrase some with commas, periods, or
+  subordinate clauses.
+- **Compound modifiers** → Hyphenate before a noun (`database-grade`,
+  `cost-effective`, `sub-second`). Don't hyphenate after ("the storage is
+  cost effective"). Check that no unnecessary hyphens crept in.
+- **Repetitive sentence openers** → If multiple rows in a table or
+  paragraphs in a section start with the same subject (e.g., "Table
+  formats provide...", "Table formats enforce...", "Table formats use..."),
+  vary the openers. Lead with the concept, not the subject.
+- **Vague performance claims** → Replace generic claims like "consistent
+  performance regardless of data volume" with what the feature actually
+  does (e.g., "optimizations for repeated and latency-sensitive queries").
+  Be specific about *which* queries or workloads benefit.
+- **Empty adjectives** → Words like "seamless," "extensive," "easy" add
+  no information. Replace with concrete verbs or cut. "Makes data
+  transformations seamless" → "automates data transformations."
+- **Generic opener sentences** → If a sentence just says "X makes it easy
+  to do Y" and the next sentence explains how, cut the opener. Let the
+  specific sentence do the work.
+- **Repetitive phrasing in adjacent sentences** → Watch for the same
+  phrase appearing in back-to-back sentences (e.g., "storage and compute"
+  twice in two sentences). Rephrase one instance.
+- **Partner and provider neutrality** → Don't single out one cloud
+  provider or partner tool. Use multiple examples: "S3 or GCS" not just
+  "S3," "Tableau and Looker" not just one. The partnerships team cares
+  about this.
+
+## Editorial Instinct
+
+**Honest about limitations — without undermining the product.** Frame what the
+product IS optimized for, not what it's bad at:
+
+> ClickHouse is not recommended as a source for this layout. Dictionary lookups
+> require random point reads, which are not the access pattern ClickHouse is
+> optimized for.
+
+Not: "Do not use ClickHouse as a source, because it is slow."
+
+**Name what IS supported before what isn't:**
+
+> ClickStack supports custom dropdown filters on dashboards, populated by data
+> queried from ClickHouse. [...] ClickStack does not currently support reusable
+> dashboard variables in the style of Grafana template variables.
+
+**State unsupported features in one sentence.** No hedging, no apology:
+
+> Multi-level drill-downs from one custom dashboard to another are not currently supported.
+
+**Don't oversell features.** If a capability is table stakes (e.g., separation
+of storage and compute), acknowledge it's standard rather than presenting it as
+a unique advantage. Reframe with what *is* distinctive (e.g., "open formats let
+you choose *which* compute engine scales with your data").
+
+**Be precise about technical claims.** Don't imply full database-style ACID if
+the architecture only provides atomic commits to table state. Use precise language
+that matches what the technology actually delivers.
+
+**Collapse awkward comparisons.** If a comparison table reads like you're avoiding
+naming the thing you're comparing against (e.g., "lakehouse"), drop the comparison
+framing. Instead, describe what the architecture delivers as a single benefits
+table. Let the reader draw their own conclusions.
+
+**Cut rows that don't hold up.** If a benefit in a table is vague, applies to
+everything, or doesn't make sense in context (e.g., "AI/ML integration" when
+there's nothing AI-specific on the page), remove it rather than trying to justify it.
+
+**Don't duplicate information.** If two table rows or paragraphs say the same thing
+differently (e.g., "open formats" and "cost-effective storage" both describing
+Parquet on object storage), merge them.
+
+**Verify before removing.** Before cutting a table row, section, or paragraph, map
+every distinct claim it makes to where that claim is covered elsewhere. If a claim
+isn't covered, weave it into an existing section rather than losing it silently.
+
+**When in doubt, shorter is better.** If the draft reads cleanly aloud and hits
+no anti-patterns, it's done. Over-polishing makes it worse.
+
+## Source Verification
+
+When documenting config options, valid values, CLI flags, or behavioral
+descriptions, verify claims against source code — not just other docs or LLM
+knowledge. This applies to any statement of the form "these are the valid
+values" or "this option does X."
+
+**Where to verify:**
+- Config parsing: search the ClickHouse/ClickHouse repo and ClickHouse/poco
+  fork for the code that reads the setting
+- Valid enum values: find the actual enum, switch statement, or if-chain
+- CLI flags: check the `programs/` directory in the ClickHouse repo
+- Upstream libraries (Poco, etc.): check ClickHouse's fork, not upstream —
+  they may diverge (e.g., ConsoleCertificateHandler was removed from the fork)
+
+**Run verification separately from drafting.** Use a dedicated research agent
+so the verification is independent — avoids confirmation bias where the
+drafter "verifies" their own assumptions.
+
+**Blog posts as sources:** When porting content from a ClickHouse blog post,
+treat the blog as the source of truth for technical claims — it was written
+by the team that built the feature. Confidence level: high (same as source
+code). Don't weaken or second-guess blog claims about how a feature works.
+
+**Present a verification summary** after drafting technical content:
+- What was verified and against which source (file path or repo)
+- What was corrected based on verification
+- Confidence level: high (source code or blog), medium (docs/examples),
+  low (LLM knowledge only)
+- Any gaps that couldn't be fully verified
+
+## Linking
+
+Every ClickHouse-specific term, feature, or integration mentioned in prose
+should link to its docs page on first mention. This helps readers navigate
+and improves SEO.
+
+- ClickHouse features link to their docs (e.g., MergeTree, materialized
+  views, projections, query cache, sparse indexes, RBAC)
+- Table formats link to their engine pages (e.g., Iceberg, Delta Lake, Hudi)
+- Data catalogs link to their reference pages (e.g., AWS Glue Catalog,
+  Unity Catalog, Iceberg REST)
+- Integrations link to their docs (e.g., Tableau, Looker, dbt, ClickPipes)
+- Interfaces link to their docs (e.g., MySQL interface, REST)
+- Data formats link to their docs on first mention (e.g., Parquet)
+- Don't double-link — link on first mention only. Second mentions of
+  the same term don't need a link.
+- Descriptive link text that explains the destination — never "click here"
+  or "this page."
+- **Link text must match the destination.** If the link goes to an
+  ingestion guide, the text should say "ingesting trace data," not
+  "distributed tracing." Readers expect the link text to describe what
+  they'll find when they click.
+- Verify link targets are correct — table engines vs table functions
+  are different pages (e.g., `/engines/table-engines/integrations/s3`
+  is the engine, `/sql-reference/table-functions/s3` is the function).
+
+## Structural Consistency
+
+- **Check sibling pages before adding structural sections.** Before adding
+  an Overview, Prerequisites, or similar framing section, check 3–5 sibling
+  pages in the same directory. If none of them use that pattern, don't
+  introduce it — fold the context into the intro paragraph instead. An
+  Overview that just previews the TOC wastes space; an intro paragraph that
+  orients the reader and summarizes the mental model earns its keep.
+- **Don't rename UI concepts.** If the product UI calls something "Webhooks,"
+  the docs call it "Webhooks." Add clarifying context inline (e.g., "Webhooks
+  — outbound notification destinations that alerts deliver to") but don't
+  substitute your own terminology. Readers need to match docs to what they
+  see on screen.
+- **Use UI tooltips as authoritative source material.** When documenting UI
+  features, check screenshots for tooltip text. Tooltips are written by the
+  product team and are often more precise than inferences. Quote or
+  paraphrase them directly rather than guessing what a UI element does.
+
+## Structure and Accessibility
+
+- Don't skip heading levels (H1 → H2 → H3, never H1 → H3).
+- Avoid directional language ("the right sidebar," "the button below") —
+  layouts change across devices.
+- Include alt text for images. For charts, describe the key data point.
+- Bold UI element names in instructions: "Click **Save**."
+
+## Frontmatter Keywords
+
+Keywords drive search ranking. Generic keywords like `'use cases'` don't help
+anyone find the page. Apply these rules:
+
+- **Be specific** — use the actual technologies, formats, and concepts
+  discussed on the page (e.g., `'Iceberg'`, `'Parquet'`, `'Delta Lake'`).
+- **Think like a searcher** — what would someone type into the docs search
+  or Google to land on this page?
+- **Include synonyms and related terms** — if the page covers data
+  warehousing, also include `'lakehouse'` and `'data lake'`.
+- **Skip filler** — don't include `'use cases'`, `'guide'`, `'tutorial'`,
+  or `'ClickHouse'` (every page is about ClickHouse).
+- **5–10 keywords** is a good range. Fewer means missed searches; more
+  dilutes relevance.
+
+## Marketing Site Alignment
+
+For use case and product pages, check that the docs page aligns with the
+corresponding marketing site page (e.g., clickhouse.com/use-cases/*).
+
+- If the marketing site has section descriptions (e.g., interactive
+  feature tabs), preserve their verbiage in the docs version. Adapt
+  for docs voice but don't lose key phrases and claims.
+- If the marketing site has specific performance claims (e.g.,
+  "hundreds of millions of rows per second"), carry them through.
+- If the marketing site has a diagram, the docs content should align
+  with what the diagram shows.
+- After condensing marketing copy for docs, do a side-by-side check
+  to ensure no meaningful claims or differentiators were dropped.
diff --git a/.claude/skills/docs-pr-review/SKILL.md b/.claude/skills/docs-pr-review/SKILL.md
new file mode 100644
index 00000000000..355e1056cf2
--- /dev/null
+++ b/.claude/skills/docs-pr-review/SKILL.md
@@ -0,0 +1,517 @@
+---
+name: docs-pr-review
+description: >
+  Review a docs PR from someone else. Triage issues by severity, draft
+  comments with rationale, and focus on what matters. Use when reviewing
+  a PR, not when checking your own work (use docs-pre-ship-review for that).
+---
+
+# Docs PR Review Skill
+
+## Invocation
+
+```
+Review PR #[number] using the docs-pr-review skill.
+```
+
+Pass 1 runs first (diff-scoped, 13 checks). Pass 2 runs second (full file,
+pre-existing quality issues).
+
+---
+
+Review someone else's docs PR. Your job is to triage and communicate.
+**This skill is read-only — do not edit files, stage changes, or commit.**
+Output a list of comments, suggestions, and questions. The user decides
+what to act on.
+
+**Scope note:** Changes to files under `i18n/` (jp, ko, ru, zh) are not
+worth flagging — translations sync automatically from the English source.
+
+This is different from pre-ship review (checking your own work). Here you're
+balancing thoroughness with respect for the author's time.
+
+## Review standard
+
+**No shortcuts. No laziness. Catch every problem, every time.**
+
+A different session reviewing the same PR must produce the same findings,
+the same line numbers, and the same severity tiers. This is the quality
+bar — reviews that miss issues or report wrong line numbers are failures,
+not approximations. Every check runs completely, every finding is verified
+before it is reported, and every line number is mechanically computed. No
+step is skipped because the PR is large, because the content looks fine at
+a glance, or because a similar check already passed.
+
+## Process
+
+This review has two distinct passes with different scopes.
+
+### Pass 1: PR review (scoped to the diff)
+
+1. **Get the diff.** Use `gh pr diff` to see only what the contributor changed.
+   All review comments must be scoped to lines in the diff.
+
+   **Line numbers — compute them mechanically, never estimate:**
+
+   Every line number in the review output must be exact and deterministic.
+   A different session reviewing the same PR must produce identical line
+   numbers. Never use `~` prefixes, never round, never eyeball.
+
+   1. Run `gh pr diff N | grep -nE '^\+\+\+ b/|^@@ '` to get the
+      diff-output line number of every file boundary and `@@` hunk header.
+   2. Run `gh pr diff N | grep -n '^+#.*{#'` (or similar targeted greps)
+      to find the diff-output line number of the content you need to cite.
+   3. Compute the file line number:
+      - Each `@@` header shows the target file line where the hunk starts
+        (e.g., `@@ -0,0 +1,42 @@` → file line 1; `@@ -85,7 +89,10 @@` →
+        file line 89).
+      - For new files: `file_line = diff_output_line - @@_header_line`
+      - For modified files: `file_line = hunk_start + (diff_output_line - @@_line - 1)`
+        (only counting `+` and context lines, not `-` lines).
+
+   **Content between hunks (gaps):** The `@@` start line tells you where
+   the *hunk* begins, not where unchanged content between hunks lives.
+   For content in a gap:
+   1. Find the previous hunk's end: `prev_hunk_start + new_count - 1`.
+   2. Find the next hunk's start from its `@@` header.
+   3. Count forward from the previous hunk's end through the unchanged
+      lines to locate the target. The gap contains exactly
+      `next_hunk_start - prev_hunk_end - 1` unchanged lines.
+   4. Never assume a gap line is "at or near" the adjacent `@@` start —
+      compute its exact position by counting.
+
+   **Verification step:** Before including any line number in the review
+   output, confirm it was computed (not estimated) and trace back to the
+   `@@` header or Read tool output that produced it. If you cannot trace
+   a number back to a mechanical computation, recompute it before
+   proceeding.
+
+   For Pass 2 (local file reads), the Read tool prints `N→ content` —
+   cite N verbatim.
+
+   **Never estimate line numbers by reading the diff and guessing.**
+   Always compute from `@@` headers. Never write awk scripts or custom
+   tooling either.
+2. **Read the local copies of changed files** for context. Do not checkout the
+   PR branch — it fails on forks and risks disrupting local git state.
+3. **Collect Pass 2 inputs.** Do both of these now — results go in Pass 2,
+   not Pass 1.
+   - **Run Vale** on the local copy of changed `.md` files. CI already runs
+     Vale on the PR's diff, so don't report Vale issues on diff lines —
+     focus on issues **outside the diff** that CI won't catch. Run `vale`
+     directly on the local file path. Cross-reference Vale line numbers
+     against the diff's `@@` hunk headers — issues on lines outside the
+     diff are pre-existing and go in Pass 2. If the PR renames or moves a
+     file, skip Vale — the old path still has the content locally, but
+     line numbers won't match the post-merge state.
+   - **Read through the full file** for issues Vale won't catch. Focus on
+     grammar errors, missing punctuation, typos, and voice violations
+     (third person in second-person docs). Cross-reference against the
+     diff the same way — only flag lines outside the diff.
+4. **Run the checklist below in order.** Check every item; only report
+   items that fail. This is the complete list — do not invent additional
+   review categories.
+5. **Triage** findings into the three severity tiers below.
+6. **Draft comments** following the comment style guidelines.
+7. **Summarize** your review: what you'd block on, what you'd suggest, and
+   what you'd let go.
+
+#### Pass 1 checklist (run in this order)
+
+| #  | Check | Tier if failed |
+|----|-------|----------------|
+| 1  | **Frontmatter complete** — `slug`, `title`, `sidebar_label`, `description`, `keywords` present | Block |
+| 2  | **MDX/build safety** — imports exist, no broken JSX, images referenced exist | Block |
+| 3  | **Technical accuracy** — commands, SQL, column/table names, config keys are correct | Block |
+| 4  | **No secrets** — no hardcoded credentials, internal URLs, or API keys | Block |
+| 5  | **Product terminology** — correct product names (ClickStack vs HyperDX, etc.) | Block |
+| 6  | **Grammar, spelling, typos** — misspellings, wrong verb forms, missing words, wrong articles | Block |
+| 7  | **Sentence casing** — headings must use sentence case, not Title Case | Block |
+| 8  | **Vale errors in diff** — CI covers these; only flag if CI is not running on this PR | Block/Suggest |
+| 9  | **Voice/style in diff** — "you" not "users," active voice, no AI-isms (see watchlist in check procedure below) | Suggest |
+| 10 | **First-mention links** — ClickHouse features/concepts link to their docs on first use | Suggest |
+| 11 | **Component opportunities** — numbered steps → VerticalStepper, variants → Tabs, etc. | Suggest |
+| 12 | **Structure and flow** — sections in logical order, prerequisites before procedures, page organization matches sibling pages | Suggest |
+| 13 | **Screenshot utility** — screenshots used as shortcuts ("refer to the screenshot") without sufficient prose context | Suggest |
+
+#### Blocking check procedures
+
+Block-tier checks (#1–#7) must be **exhaustive** — every instance found,
+not sampled. Some checks have deterministic patterns that grep can catch;
+others require careful reading. Run the two modes separately, in order:
+grep-based checks first (fast, mechanical), then a reading pass (slower,
+requires comprehension). Do not try to do both in a single pass through
+the diff — that's how things get missed.
+
+**Mode 1: Pattern-based checks (run first, via grep)**
+
+These checks have deterministic patterns. Grep the diff to get a complete
+list, then verify each result.
+
+*Sentence casing (#7):*
+Run `gh pr diff N | grep -n '^+#.*{#'` to extract every added heading
+with its diff-output line number. Check **each** heading: only the first
+word and proper nouns may be capitalized. Compute the file line for every
+violation using the `@@`-header method above.
+
+Common proper nouns in this codebase: ClickHouse, ClickStack, HyperDX,
+Helm, Kubernetes, MongoDB, OpenTelemetry Collector, OTEL, AWS, GKE, EKS,
+AKS, API, SQL, TLS, DNS, JSON, YAML, ConfigMap, Secret (K8s resource types).
+
+*Frontmatter (#1):*
+For every changed or new `.md` file, verify the frontmatter block in the
+diff contains all required fields: `slug`, `title`, `sidebar_label`,
+`description`, `keywords`. Integration guides also need `pagination_prev`,
+`pagination_next`, and `doc_type`.
+
+**Mode 2: Comprehension checks (reading pass)**
+
+These checks require understanding the content — grep can't catch them.
+Read through the diff content carefully, file by file.
+
+*Technical accuracy (#3):*
+
+A reviewer's job is not to re-run every command — that's the author's
+responsibility (covered by `docs-pre-ship-review`). Your job is to catch
+what looks wrong and flag what you can't verify. Use this hierarchy:
+
+**Verify yourself (fast, do these):**
+- Internal links and slug paths: `find docs/ -name '*.md' | xargs grep -l 'slug:' | head -20` to spot-check that a referenced page exists.
+- Table and function names: grep the docs for the referenced name (`grep -r 'MergeTree' docs/ --include='*.md' -l`) to confirm it's real and consistently spelled.
+- YAML code blocks: scan for duplicate keys at the same nesting level — YAML parsers silently discard earlier duplicates, so readers who copy the example lose configuration.
+- Frontmatter field values: check `doc_type` is one of `guide`, `reference`, `changelog`, `landing-page` — anything else is wrong.
+- Shell flag names: if a flag looks unfamiliar, check it against the ClickHouse docs page for that binary (e.g., `clickhouse-client --help` output is documented in `docs/interfaces/cli.md`).
+
+**Ask the author (you cannot verify these without running the system):**
+- Whether commands execute without error in a clean environment.
+- Whether config values produce the described behavior.
+- Whether SQL queries return the expected result.
+- Whether port numbers, endpoints, and environment variable names are correct for their setup.
+
+When asking the author, be specific: "Can you confirm this command runs without error against a fresh install?" is more useful than "Please verify this is correct."
+
+**Flag as Block if:**
+- A referenced table, function, or page clearly does not exist (you confirmed via grep).
+- A YAML block has duplicate keys.
+- A SQL statement has a visible syntax error (wrong clause order, missing FROM, unclosed quote).
+- A shell command uses a flag that doesn't match the documented interface.
+
+**Flag as Suggest (ask author) if:**
+- A config value or behavior description is plausible but you cannot confirm it locally.
+- A command is correct syntactically but you're uncertain about the flag semantics.
+
+**Do not flag** claims you have no specific reason to doubt. Skepticism without evidence is noise.
+
+*Grammar, spelling, typos (#6):*
+Read the prose in added lines. Watch for wrong articles, missing words,
+subject-verb disagreement, and misspellings that pass spellcheck (e.g.,
+"form" for "from").
+
+*No secrets (#4), product terminology (#5), MDX/build safety (#2):*
+These surface during reading. Flag hardcoded credentials, wrong product
+names, and missing imports as you encounter them.
+
+*Voice/style and AI-isms (#9):*
+
+Check the `doc_type` in frontmatter before running this check. The
+watchlist and thresholds differ by type.
+
+**Full watchlist (all categories):**
+
+**Transitions:** moreover, furthermore, notably, importantly, crucially,
+interestingly, surprisingly, it's worth noting that, it bears mentioning
+
+**Framing:** let's be clear, let's be honest, here's the reality,
+the truth is, in today's fast-paced, in an era of, at the end of the day
+
+**Sentence patterns:** "it's not X — it's Y" contrast,
+question-then-immediate-answer, "in other words" / "put simply"
+re-explanation, tricolon negation lists (no X, no Y, no Z)
+
+**Buzzwords:** seamless, groundbreaking, revolutionary, game-changing,
+robust, cutting-edge, unlock, leverage, empower, powerful, elegant
+
+**Metaphor:** landscape, ecosystem, tapestry, mosaic, fabric,
+paradigm shift, north star
+
+**Hedging:** one could argue, some might say, while X is beyond the scope,
+without further ado
+
+**Thanking:** thank you for reading, thanks for following along
+
+**High-severity-only subset** (for reference and landing-page types):
+tapestry, mosaic, fabric, paradigm shift, seamless, groundbreaking,
+revolutionary, game-changing, landscape, ecosystem, north star,
+unlock, leverage, empower, in today's fast-paced, in an era of,
+thank you for reading, thanks for following along
+
+These are patterns that don't belong in any doc type. The full watchlist
+includes patterns that are suspect in guides but tolerable in structured
+reference content (e.g., moreover, topic-sentence openers, parallel
+phrasing).
+
+**Applying the check by doc_type:**
+
+`guide`:
+Run the full watchlist. Guides are procedural and conversational —
+AI-isms actively hurt readability. Also watch for general voice issues:
+third person ("the user," "users") in second-person docs, passive voice
+where active is clearer, and em-dash overuse (3+ in a single page).
+
+- **Zero hits** — move on, no comment needed.
+- **1–2 hits** — flag them in a single batched comment with a suggested
+  rewrite. No need to load external references.
+- **3+ hits or a pattern cluster** (hits from 3+ categories) — load the
+  `ai-style-review` catalogue for remediation guidance and severity
+  context. Draft the comment using the catalogue's specific remediation
+  advice rather than generic suggestions. Note the clustering: "This
+  diff has several AI-generated patterns — worth a revision pass."
+
+`reference` and `landing-page`:
+Run the high-severity-only subset. Reference pages are structured by
+nature — parallel lists, topic sentences, and some formality are
+expected. Landing pages are short enough that marginal patterns aren't
+worth flagging. Still check for general voice issues (third person,
+passive voice).
+
+- **Fewer than 3 hits** — move on, no comment needed.
+- **3+ hits** — flag them in a batched comment. Load the `ai-style-review`
+  catalogue only if 5+ hits or patterns from 3+ categories.
+
+If `doc_type` is missing from frontmatter, default to `guide` thresholds.
+
+*Screenshot utility (#13):*
+Scan for crutch phrases like "refer to the screenshot", "see screenshot",
+"as shown in the screenshot below", or "see the image above." These
+indicate the author is relying on a visual instead of explaining the step
+in prose.
+
+Apply this litmus test: **could the reader succeed with the task based
+only on the prose description, without looking at the screenshot?**
+
+- If **yes** — the screenshot may be redundant. Flag it: "The prose covers
+  this fully — is the screenshot adding anything the text doesn't?"
+- If **no** — the screenshot is load-bearing, but the prose should still
+  explain what to look for. Flag: "This step relies on the screenshot to
+  explain itself. Add a sentence describing what the reader should see or
+  do, so the screenshot supplements rather than replaces the instruction."
+
+Screenshots earn their place by showing the result of a step
+(confirmation), orienting the reader in a complex UI, or surfacing a
+non-obvious option. They don't earn their place when they substitute for
+writing a clear instruction.
+
+*Structure and flow (#12):*
+Read the full file (not just the diff) to evaluate page organization.
+Check that sections follow a logical progression — context before
+procedures, prerequisites before steps, conceptual overview before
+reference detail. Read 2–3 sibling files in the same directory to see
+whether the page matches the section ordering conventions around it.
+Flag cases where a reader would need to scroll back to understand
+something, where procedural steps are buried after reference tables, or
+where the page structure diverges from its neighbors without reason.
+Don't flag structure that is clear and works even if you'd organize it
+differently — this check targets disorienting layouts, not style
+preferences.
+
+### Pass 2: Pre-existing quality issues (scoped to the full file)
+
+This pass uses the Vale output and manual read-through you collected in
+Pass 1 step 3. Both are required — Vale catches mechanical issues
+(spelling, contractions, wordy phrases) while the manual read catches
+grammar errors, voice violations, and formatting problems that Vale misses.
+
+**Always** scan the full files touched by the PR for pre-existing quality
+issues — regardless of how small the diff is. Even a one-line change is
+an opportunity to catch issues in the surrounding page. These are tracked
+separately, never raised as PR comments.
+
+**Flag only these categories:**
+- Grammar errors, missing punctuation, typos
+- Voice violations: third person ("the user") in second-person docs,
+  AI-ism clusters (3+ patterns from the watchlist in check #9)
+- Broken formatting: malformed tables, broken list rendering, missing
+  blank lines that affect rendering
+
+**Do NOT flag:**
+- Cosmetic preferences (code fence languages, minor whitespace)
+- Phrasing you'd word differently but that is clear and correct
+- Style drift that matches the rest of the page
+- Isolated AI-isms (1–2 instances in a full page are not worth a ticket)
+
+**Observations** (no ticket, reported separately):
+- Potential technical inaccuracies or claims worth verifying
+- Content gaps where missing context could mislead readers
+
+Nothing in Pass 2 blocks the PR. It's all informational for the human
+reviewer to decide what to act on.
+
+**Edge case — renamed/moved files:** If the PR renames or moves a file,
+pre-existing issues will reference a path that doesn't exist yet (before
+merge) or no longer exists (after merge). In this case, flag the issues
+in the review output but **do not draft a Linear ticket** — note that
+the file is being moved and the issues can be addressed after merge.
+
+**Output:** Present findings in two groups:
+1. **Quality issues** (ticket candidates) — grammar, formatting, voice.
+   Draft a Linear ticket preview using the **Historical Docs Quality Fixes - PRs** project,
+   low priority, with file path and bullet-form issues. Do not
+   create the ticket without the user confirming the preview. Format:
+
+   ```
+   Title: Quality fixes: <page name>
+   Description:
+   Pre-existing quality issues found during review of PR #XXXX.
+
+   `path/to/file.md`
+
+   * Line X: description of issue
+   * Lines X, Y: description of repeated issue (N occurrences)
+   * Line X: description of issue
+   ```
+
+2. **Observations** (no ticket) — potential inaccuracies, gaps, or concerns
+   the reviewer should be aware of. Flag them so the human can decide
+   whether to raise with the contributor or investigate further.
+
+## Limits
+
+- **10 items max per file** across both passes combined. If you find more
+  than 10, keep all Blocks, then rank Suggests by reader impact and cut
+  the rest. Pass 2 quality issues count toward the cap; observations do not.
+- Do not invent review categories beyond the Pass 1 checklist and the
+  Pass 2 flag list above. If an issue doesn't fit a listed category, it's
+  Ignore.
+
+## Severity tiers
+
+### Block (request changes)
+
+These prevent the PR from shipping. The author must address them.
+
+- **Technical inaccuracy** — wrong command, incorrect behavior, SQL that
+  won't run, wrong column or table names
+- **Broken build** — missing frontmatter, bad MDX syntax, broken import,
+  missing image file
+- **Security issue** — hardcoded credentials, exposed internal URLs, API keys
+- **Factual errors** — incorrect claims about ClickHouse behavior
+- **Terminology confusion** — using the wrong product name (e.g., HyperDX
+  where ClickStack is correct) in a way that will confuse readers
+- **Broken or missing critical links** — linking to a page that doesn't
+  exist, or not linking to essential context the reader needs
+- **Grammar, spelling, and typos** — misspellings, wrong verb forms,
+  missing words, incorrect articles ("an" vs "a")
+- **Sentence casing** — headings must use sentence case ("Tuning performance"),
+  not Title Case ("Tuning Performance"). This is a hard site-wide requirement.
+
+### Suggest (approve with comments)
+
+These are real issues but shouldn't block the PR. The author can address
+them in this PR or a follow-up.
+
+- **Voice and style violations** — AI-isms, passive voice, "users" instead
+  of "you," em dash overuse
+- **Missing first-mention links** — ClickHouse features or concepts that
+  should link to their docs
+- **Weak frontmatter keywords** — generic terms that won't help search
+- **Component opportunities** — a numbered list that should be VerticalStepper,
+  variant content that should be Tabs, supporting detail that should be
+  collapsible
+- **Structure and flow** — sections in illogical order, prerequisites after
+  procedures, page organization that diverges from sibling pages without
+  reason, or layouts where the reader must scroll back to understand context
+- **Minor inconsistencies** — formatting differences from the current standard
+  that don't affect comprehension
+
+### Ignore (don't comment)
+
+Don't leave comments on these. They create noise and slow down the review.
+
+- **If the author's phrasing is clear, grammatically correct, and
+  technically accurate, it is Ignore** — even if you'd write it differently.
+  This is the single most important triage rule.
+- Slightly verbose explanations that aren't wrong
+- Formatting choices that match the rest of the page even if they don't
+  match the latest standard
+- Vale suggestions in code-adjacent prose where the "wordy" phrasing is
+  actually clearer
+- Implementation details that are accurate today (e.g., retry counts,
+  timeout values) — don't flag these as "might go stale"
+- **Concepts that link to their explanation.** If the author uses a term
+  and links to a page that defines it, don't suggest inlining the
+  definition. The link is doing its job.
+- **Sentence-level style preferences.** Multiple links in one sentence,
+  slightly long sentences, or phrasing you'd restructure — if the meaning
+  is clear, it's Ignore. A suggestion should be clearly worth the
+  author's time, not a marginal polish.
+
+## Writing comments
+
+Every comment should help the author understand *what* to change and *why*.
+
+### Structure
+
+- **Lead with the issue**, not the rule. "This column name might be wrong"
+  is more useful than "Per our style guide, column names should be verified."
+- **Include the why.** "Readers will copy this query and get an error if the
+  column is actually `TimestampTime`" tells the author what's at stake.
+- **Suggest a fix when you have one.** Don't just flag problems. If you know
+  the answer, include it. If you don't, say what you'd check.
+- **Batch minor issues.** If you have 5 Vale fixes, leave one comment listing
+  them all instead of 5 separate comments.
+
+### Tone
+
+- Name what needs to change. Acknowledge what's solid. Keep it short.
+- Frame suggestions as options, lead with the strongest: "I'd go with Option 1."
+- Flag specific patterns: "two consecutive 'You can' openers" is actionable;
+  "could flow better" is not.
+- Catch voice/tone consistency: third-person slips in second-person docs,
+  inconsistent punctuation on list items, formality mismatches.
+- Ask about things you're unsure of. "Is HyperDX correct here, or should
+  this be ClickStack?" is better than "Change HyperDX to ClickStack."
+- Don't prescribe rewrites for style preferences. "This could be tighter"
+  without a suggested rewrite isn't actionable.
+- Acknowledge what's good. If the examples are well-crafted or the structure
+  is clean, say so. Reviews that only flag problems are demoralizing.
+
+### Scope discipline
+
+- **PR comments must be scoped to the diff.** Never block a contributor's PR
+  for issues they didn't introduce. Pre-existing problems go in Pass 2.
+- Review what's in the PR, not what's missing from the section. If the page
+  doesn't cover topic X, that's a separate issue, not a PR comment.
+- Don't request a full rewrite. If the page needs fundamental restructuring,
+  that's a conversation, not a review comment.
+- Don't pile on. If a pattern repeats (e.g., missing contractions throughout),
+  flag it once with "this pattern appears throughout" instead of commenting
+  on every instance.
+
+## When to verify yourself vs ask the author
+
+- **Verify yourself:** link targets (glob for the file), column/table names
+  (check the schema docs), frontmatter fields (check required fields list)
+- **Ask the author:** product naming decisions (ClickStack vs HyperDX),
+  whether a feature works as described (they may have tested it), whether
+  omitted content is intentional
+
+## Output format
+
+When drafting review comments for the user, format each as:
+
+```
+**Line X** (block/suggest): <comment text>
+```
+
+Group by severity — blocks first, then suggestions. End with a one-line
+summary of your recommendation (approve, approve with suggestions, or
+request changes).
+
+## Register: Internal Communication
+
+When drafting Slack messages, PR descriptions, or Linear comments:
+
+- Same directness, casual layer. Fragments and informal phrasing fine.
+- Open with context: "Ran into an issue with X" — not "Hi everyone!"
+- Acknowledge mistakes plainly: "I had this wrong."
+- Close with a clear next action: "Let me know if I'm still off!"
\ No newline at end of file
diff --git a/.claude/skills/docs-pr-review/references/ai-tells.md b/.claude/skills/docs-pr-review/references/ai-tells.md
new file mode 100644
index 00000000000..721f77b1194
--- /dev/null
+++ b/.claude/skills/docs-pr-review/references/ai-tells.md
@@ -0,0 +1,867 @@
+# AI Writing Tells -- Detection and Remediation Catalogue
+
+Reference document for the `docs-pr-review` skill. Each entry describes a pattern that signals AI-generated writing, with examples and concrete fixes.
+
+Severity levels:
+- **High** -- almost never appears in human writing; strong AI signal on its own
+- **Medium** -- occasionally appears in human writing but AI overuses it; becomes a tell when combined with others
+- **Low** -- common in human writing too, but AI uses it at a higher rate; flag only when frequency is unusual
+
+---
+
+## 1. Punctuation
+
+### 1.1 Em-dash overuse
+
+**Severity:** High (when 3+ per article) / Medium (1-2 instances)
+
+**Description:** AI inserts em-dashes where commas, parentheses, or separate sentences would be more natural. The pattern is especially strong when em-dashes appear in consecutive paragraphs or multiple times in a single paragraph.
+
+**Examples:**
+- "ClickHouse uses a columnar storage format -- making it ideal for analytical queries -- that compresses data efficiently."
+- "The new release includes three features -- query caching, async inserts, and lightweight deletes -- that users have been requesting."
+- "This approach -- unlike traditional row-oriented databases -- prioritizes read performance."
+
+**Why it's a tell:** Human writers use em-dashes sparingly. AI scatters them throughout because they're a convenient way to inject parenthetical information without committing to a sentence structure. When you see 4+ em-dashes in a 1000-word piece, it's almost certainly AI.
+
+**Remediation:**
+- Use parentheses for true asides: "ClickHouse uses a columnar storage format (ideal for analytical queries) that compresses data efficiently."
+- Break into two sentences: "ClickHouse uses a columnar storage format. This makes it ideal for analytical queries while compressing data efficiently."
+- Use a comma if the aside is short: "ClickHouse, a columnar database, compresses data efficiently."
+- Keep at most one em-dash per 500 words. If you have more, rewrite the rest.
+
+### 1.2 Semicolon overuse in casual/blog writing
+
+**Severity:** Medium
+
+**Description:** AI uses semicolons to join related independent clauses far more often than human blog writers do. Semicolons are fine in academic writing but feel stiff in blog posts and marketing content.
+
+**Examples:**
+- "Query performance improved by 3x; memory usage dropped by half."
+- "The team rewrote the parser in Rust; the results exceeded expectations."
+- "ClickHouse handles this natively; no external tools are required."
+
+**Why it's a tell:** Most blog writers use periods or conjunctions. Semicolons in informal writing feel like AI trying to sound sophisticated. One per article is fine. Three or more is a flag.
+
+**Remediation:**
+- Split into two sentences: "Query performance improved by 3x. Memory usage dropped by half."
+- Use a conjunction: "Query performance improved by 3x, and memory usage dropped by half."
+- Use "while" or "and" to connect: "Query performance improved by 3x while memory usage dropped by half."
+
+### 1.3 Colon-led dramatic reveals
+
+**Severity:** High
+
+**Description:** AI uses colons to set up a dramatic reveal or key point, often after a short declarative setup. The pattern is: short emphatic sentence fragment, colon, the "punchline."
+
+**Examples:**
+- "Here's the thing: most databases weren't built for this workload."
+- "The result: a 10x improvement in query latency."
+- "The takeaway: you don't need a separate analytics stack."
+- "The bottom line: ClickHouse handles this out of the box."
+
+**Why it's a tell:** Human writers occasionally use this structure, but AI uses it as a crutch to create emphasis. When multiple paragraphs use the same colon-reveal pattern, it reads as formulaic.
+
+**Remediation:**
+- Just state the point directly: "Most databases weren't built for this workload."
+- Integrate into the preceding sentence: "We found that most databases weren't built for this workload."
+- Use the colon-reveal at most once per piece, and only when it genuinely adds punch.
+
+### 1.4 Exclamation marks for forced enthusiasm
+
+**Severity:** Medium
+
+**Description:** AI adds exclamation marks to inject energy into statements that don't warrant it, particularly in introductions and conclusions.
+
+**Examples:**
+- "We're excited to announce the release of ClickHouse 24.8!"
+- "And the best part? It's completely free!"
+- "Let's dive in!"
+
+**Why it's a tell:** Genuine technical writing rarely needs exclamation marks. Human writers in tech tend to understate rather than overstate. Exclamation marks in a technical blog post feel like AI mimicking enthusiasm.
+
+**Remediation:**
+- Drop the exclamation mark: "We're releasing ClickHouse 24.8 today."
+- Let the content carry the excitement: "ClickHouse 24.8 ships with async inserts, query caching, and lightweight deletes."
+- Reserve exclamation marks for genuinely surprising metrics or results, if ever.
+
+### 1.5 Ellipsis for false suspense
+
+**Severity:** Low
+
+**Description:** AI uses ellipses to create artificial suspense or trailing thoughts in contexts where a period works fine.
+
+**Examples:**
+- "But there's a catch..."
+- "The answer might surprise you..."
+- "We needed something faster, more reliable, more scalable..."
+
+**Why it's a tell:** Blog and marketing writers do use ellipses occasionally, but AI reaches for them to manufacture intrigue. Combined with other tells, they contribute to an overall AI pattern.
+
+**Remediation:**
+- End with a period: "But there's a catch."
+- Remove the suspense framing entirely: "The limitation is that partitions aren't designed for query optimization."
+
+---
+
+## 2. Sentence Patterns
+
+### 2.1 "It's not X, it's Y" contrast pattern
+
+**Severity:** High
+
+**Description:** AI loves this rhetorical structure where something is reframed by negating one characterization and asserting another. Often appears in introductions and topic sentences.
+
+**Examples:**
+- "It's not just a database -- it's a real-time analytics engine."
+- "This isn't a minor update; it's a fundamental rethink of how we handle joins."
+- "ClickHouse isn't just fast. It's fast at scale."
+- "This isn't about speed. It's about giving analysts their time back."
+
+**Why it's a tell:** This is one of the most reliable AI tells. Human writers use this pattern occasionally, but AI uses it in almost every piece of persuasive or explanatory writing. Two or more instances in a single article is a near-certain AI flag.
+
+**Remediation:**
+- State the positive claim directly: "ClickHouse is a real-time analytics engine."
+- Lead with what it does, not what it isn't: "ClickHouse processes analytical queries at scale, returning results in milliseconds."
+- If you must contrast, do it in two separate sentences with specifics: "Most databases trade query speed for write throughput. ClickHouse doesn't -- it handles 1M inserts/sec while maintaining sub-second query latency."
+
+### 2.2 "Let's be clear:" / "Let's be honest:" openers
+
+**Severity:** High
+
+**Description:** AI uses these phrases to signal a shift to directness, as if the previous text was somehow unclear or dishonest. Often appears at the start of a paragraph.
+
+**Examples:**
+- "Let's be clear: ClickHouse is not a replacement for your transactional database."
+- "Let's be honest: most observability tools are overpriced."
+- "Make no mistake: this changes how teams think about analytics."
+
+**Why it's a tell:** Human writers who are actually being clear don't announce it. This is AI mimicking a rhetorical move it's seen in opinion writing and speeches. It appears with high frequency in AI output and low frequency in human blog writing.
+
+**Remediation:**
+- Delete the prefix and start with the actual claim: "ClickHouse is not a replacement for your transactional database."
+- If you want directness, just be direct. The words do the work, not the preamble.
+
+### 2.3 "Here's the reality:" / "The truth is" declarations
+
+**Severity:** High
+
+**Description:** Similar to 2.2 but framed as revealing a hidden truth. AI uses these to set up a contrarian or corrective point.
+
+**Examples:**
+- "Here's the reality: most teams don't need a data lake."
+- "The truth is, columnar databases have been around for decades."
+- "The reality is that performance tuning is rarely about hardware."
+- "Here's what most people get wrong: partitioning isn't a performance feature."
+
+**Why it's a tell:** Same problem as "Let's be clear" -- it's a rhetorical crutch that AI leans on heavily. Human writers state their contrarian takes without preamble.
+
+**Remediation:**
+- Delete the preamble: "Most teams don't need a data lake."
+- If the point is contrarian, let the argument itself convey that: "Columnar databases have been around for decades. What's new is making them usable without a team of database engineers."
+
+### 2.4 Question-then-immediate-answer pattern
+
+**Severity:** Medium
+
+**Description:** AI poses a rhetorical question and immediately answers it in the next sentence. Often used as a paragraph opener.
+
+**Examples:**
+- "So why does this matter? Because query performance directly impacts user experience."
+- "What makes ClickHouse different? It was designed from the ground up for analytical workloads."
+- "But can it handle real-time data? Absolutely."
+
+**Why it's a tell:** Human writers sometimes do this, but AI does it repeatedly and predictably. When every other paragraph opens with a question that gets answered immediately, the rhythm becomes mechanical.
+
+**Remediation:**
+- Merge into a direct statement: "Query performance matters because it directly impacts user experience."
+- Use the question only when you genuinely want the reader to pause and think. Don't answer it in the very next sentence -- let it breathe.
+- Limit to one per article at most.
+
+### 2.5 "In other words" / "Put simply" re-explanation
+
+**Severity:** Medium
+
+**Description:** AI explains something, then re-explains it in simpler terms immediately after, using a transition phrase.
+
+**Examples:**
+- "ClickHouse uses vectorized query execution, processing data in batches rather than row by row. In other words, it processes thousands of values simultaneously."
+- "The MergeTree engine sorts data by primary key on disk. Put simply, queries that filter on the primary key can skip most of the data."
+
+**Why it's a tell:** AI is trained to be helpful and accessible, so it often provides redundant re-explanations. Human writers pick one level of explanation and commit to it.
+
+**Remediation:**
+- Pick the better explanation and delete the other: "ClickHouse processes data in batches of thousands of values at once, rather than row by row."
+- If both levels are needed (for a mixed audience), structure them as a progression, not a restatement.
+
+### 2.6 Tricolon negation lists
+
+**Severity:** High
+
+**Description:** AI produces dramatic three-item lists of things that are eliminated or no longer needed, typically proper nouns or technical components. The pattern is: "No X. No Y. No Z." or "No X, no Y, no Z." Used to emphasise simplicity by listing what was removed.
+
+**Examples:**
+- "No Kafka. No Connect workers. No Debezium configuration."
+- "No Hadoop. No Spark. No MapReduce."
+- "No sharding keys. No manual rebalancing. No topology management."
+- "No ETL pipelines. No staging tables. No batch windows."
+
+**Why it's a tell:** This is a distinctive AI rhetorical pattern. Human writers occasionally use it in marketing copy, but AI produces it with very high frequency, especially when describing how a product simplifies a workflow. The three-item structure with parallel "No X" phrasing is a strong signal. It's particularly obvious when the items are proper nouns for well-known tools.
+
+**Remediation:**
+- Describe what you do instead of listing what you don't: "ClickHouse ingests data directly -- skip the Kafka-to-Connect-to-database pipeline."
+- If simplicity is the point, show it with a before/after comparison or a concrete example rather than a negation list.
+- One "no X" is fine. Three in a row is a pattern to avoid.
+
+---
+
+## 3. Transition Words
+
+### 3.1 "Moreover" / "Furthermore"
+
+**Severity:** High
+
+**Description:** AI uses "moreover" and "furthermore" as default paragraph connectors. These words are formal and academic, and rarely appear in casual or technical blog writing.
+
+**Examples:**
+- "Moreover, ClickHouse supports real-time inserts alongside analytical queries."
+- "Furthermore, the new materialized view syntax simplifies pipeline management."
+- "Moreover, this approach reduces operational complexity."
+
+**Why it's a tell:** "Moreover" and "furthermore" are the most commonly flagged AI transition words. Human blog writers almost never use them. They add nothing -- the paragraph that follows is obviously an additional point; you don't need to announce it.
+
+**Remediation:**
+- Delete the word and start with the content: "ClickHouse supports real-time inserts alongside analytical queries."
+- If a transition is needed, use a simple one: "And" or "Also" or just a new paragraph.
+- Often no transition is needed at all. Paragraphs don't always need explicit connectors.
+
+### 3.2 "Notably" / "Importantly" / "Crucially"
+
+**Severity:** High
+
+**Description:** AI uses these adverbs to signal that the following point is significant. They appear at the start of sentences as a way to elevate what comes next.
+
+**Examples:**
+- "Notably, this is the first release to support async inserts natively."
+- "Importantly, the data remains fully queryable during ingestion."
+- "Crucially, this change is backward compatible."
+
+**Why it's a tell:** These signal words are AI trying to manage the reader's attention. Human writers assume their reader is paying attention and don't need to flag which points are important -- the structure and argument do that work.
+
+**Remediation:**
+- Delete the adverb: "This is the first release to support async inserts natively."
+- If the point really is crucial, restructure to show why: "Backward compatibility matters here because teams can upgrade without rewriting their ingestion pipelines."
+
+### 3.3 "Interestingly" / "Surprisingly" / "Fascinatingly"
+
+**Severity:** High
+
+**Description:** AI tells the reader how to feel about the information instead of letting the information speak for itself.
+
+**Examples:**
+- "Interestingly, ClickHouse outperformed the alternatives even without tuning."
+- "Surprisingly, the smaller cluster handled the load better."
+- "Fascinatingly, this pattern emerges across all deployment sizes."
+
+**Why it's a tell:** Human writers with genuine expertise don't editorialize their own findings this way. If something is surprising, the context makes that clear. "Fascinatingly" is almost exclusively AI -- humans rarely use it in prose.
+
+**Remediation:**
+- State the fact and let the reader decide if it's interesting: "ClickHouse outperformed the alternatives even without tuning."
+- If surprise is part of the story, show it through context: "We expected the larger cluster to win. It didn't -- the smaller cluster handled the load better, by a margin of 40%."
+
+### 3.4 "That said" / "That being said"
+
+**Severity:** Medium
+
+**Description:** AI uses these as pivot transitions to acknowledge a counter-point or caveat. They appear with high frequency in AI-generated balanced arguments.
+
+**Examples:**
+- "That said, there are trade-offs to consider."
+- "That being said, the approach isn't suitable for every workload."
+- "That said, it's worth considering the operational overhead."
+
+**Why it's a tell:** Human writers use "that said" occasionally, but AI uses it as a default hedge mechanism. When paired with the overly-balanced voice pattern (see section 8), it's a strong signal.
+
+**Remediation:**
+- Use "but" or "however" once, or restructure: "The trade-off is operational overhead."
+- Often the caveat can be folded into the preceding paragraph rather than split out as a new thought.
+
+### 3.5 "It's worth noting that" / "It bears mentioning"
+
+**Severity:** High
+
+**Description:** AI inserts these phrases to introduce additional context that it doesn't want to state directly. The phrase adds nothing -- if it's worth noting, just note it.
+
+**Examples:**
+- "It's worth noting that ClickHouse Cloud handles replication automatically."
+- "It bears mentioning that this feature is still in experimental status."
+- "It should be noted that these benchmarks were run on a single node."
+
+**Why it's a tell:** This is AI hedging. Human writers state facts; they don't preface them with meta-commentary about whether the fact is worth stating.
+
+**Remediation:**
+- Delete the preamble: "ClickHouse Cloud handles replication automatically."
+- If it's a caveat, state it as one: "These benchmarks were run on a single node, so multi-node performance may differ."
+
+---
+
+## 4. Hedging and Filler
+
+### 4.1 "One could argue" / "Some might say"
+
+**Severity:** High
+
+**Description:** AI attributes viewpoints to hypothetical people rather than stating them directly or attributing them to real sources.
+
+**Examples:**
+- "One could argue that columnar databases are overkill for small datasets."
+- "Some might say this adds unnecessary complexity."
+- "It could be argued that the trade-off isn't worth it for smaller teams."
+
+**Why it's a tell:** Human writers either own their argument or cite a real person. AI creates imaginary interlocutors because it's trained to present multiple perspectives without committing.
+
+**Remediation:**
+- Own the claim: "Columnar databases are overkill for small datasets."
+- Attribute to a real source: "Developers on Hacker News frequently push back on this, arguing the complexity isn't worth it for small datasets."
+- If you're presenting a counterargument, frame it directly: "The counterargument: columnar databases add complexity that small teams don't need."
+
+### 4.2 "In today's fast-paced world" / "In an era of"
+
+**Severity:** High
+
+**Description:** AI opens pieces with sweeping temporal context-setting that adds nothing. This is pure filler to create a sense of relevance.
+
+**Examples:**
+- "In today's data-driven world, real-time analytics is no longer a luxury."
+- "In an era of ever-growing data volumes, efficient storage is critical."
+- "In today's fast-paced business environment, speed matters more than ever."
+- "As organizations increasingly rely on data-driven decision making..."
+
+**Why it's a tell:** This is one of the most cliched AI patterns. No human writer with a deadline wastes their opening on "in today's fast-paced world." It's filler that signals the AI had nothing specific to say.
+
+**Remediation:**
+- Delete the entire sentence and start with the actual point.
+- If context-setting is needed, be specific: "When Uber's analytics team hit 10TB of daily ingestion, their existing database couldn't keep up."
+
+### 4.3 "While X is beyond the scope of this article"
+
+**Severity:** Medium
+
+**Description:** AI acknowledges related topics it won't cover, which is a pattern from training on academic and educational text.
+
+**Examples:**
+- "While a full comparison of OLAP databases is beyond the scope of this post, it's worth noting that ClickHouse excels in several areas."
+- "Though we won't dive into the internals of MergeTree here, understanding the basics helps."
+
+**Why it's a tell:** Blog writers either cover a topic or don't mention it. They don't apologize for not covering it. This is AI hedging against the possibility that the reader expected more.
+
+**Remediation:**
+- Delete the scope disclaimer. If you're not covering it, don't bring it up.
+- If a reference is helpful, just link: "For a deep dive on MergeTree internals, see [this post]."
+
+### 4.4 "Without further ado" / "Without getting too deep into"
+
+**Severity:** Medium
+
+**Description:** AI uses these meta-commentary phrases to transition from introduction to content, acknowledging the transition explicitly instead of just making it.
+
+**Examples:**
+- "Without further ado, let's look at the benchmarks."
+- "Without getting too deep into the implementation details, here's how it works."
+- "With that context in mind, let's explore the solution."
+
+**Why it's a tell:** Human writers just start the next section. They don't narrate the structural transitions of their own article.
+
+**Remediation:**
+- Delete and move to the content: show the benchmarks, explain how it works.
+- If you need a transition, a section heading does the job.
+
+### 4.5 "As we'll see" / "As we've seen"
+
+**Severity:** Medium
+
+**Description:** AI references other parts of the article as if guiding the reader through a live presentation.
+
+**Examples:**
+- "As we'll see in the next section, this has major implications for query performance."
+- "As we've seen, ClickHouse's approach to storage differs fundamentally from row-oriented databases."
+- "As mentioned earlier, the primary key determines sort order on disk."
+
+**Why it's a tell:** This is AI mimicking an instructor or tour guide. Blog posts aren't presentations -- readers can scroll. Occasional cross-references are fine, but AI does this reflexively.
+
+**Remediation:**
+- Delete the cross-reference and just make the point.
+- If a callback is genuinely needed, be specific: "The sort order we configured in the CREATE TABLE statement determines which queries benefit from data skipping."
+
+---
+
+## 5. Superlatives and Buzzwords
+
+### 5.1 "Groundbreaking" / "Revolutionary" / "Game-changing"
+
+**Severity:** High
+
+**Description:** AI reaches for the biggest adjective available when describing features, releases, or approaches. These words have been so overused that they now signal marketing fluff.
+
+**Examples:**
+- "This groundbreaking feature enables real-time analytics at scale."
+- "The revolutionary approach to query processing sets ClickHouse apart."
+- "This is a game-changing improvement for observability teams."
+
+**Why it's a tell:** Human technical writers avoid these words because they know the audience will dismiss the claim. AI uses them because they appeared frequently in its training data (marketing copy, press releases, product pages).
+
+**Remediation:**
+- Replace with specific claims: "This feature reduces query latency from minutes to milliseconds for time-series workloads."
+- Let the reader decide if it's groundbreaking. Show the impact with numbers, benchmarks, or user quotes.
+- If it's truly significant, explain why concretely: "Before this release, teams needed a separate streaming pipeline. Now it's one SQL statement."
+
+### 5.2 "Seamless" / "Seamlessly"
+
+**Severity:** High
+
+**Description:** AI describes integrations, migrations, and experiences as "seamless" without qualification. Nothing in software is seamless.
+
+**Examples:**
+- "ClickHouse seamlessly integrates with your existing data stack."
+- "The migration was seamless, with zero downtime."
+- "This provides a seamless experience for end users."
+
+**Why it's a tell:** "Seamless" is the number one AI marketing word. Human writers know that integrations have seams -- they describe the actual experience instead of papering over it.
+
+**Remediation:**
+- Be specific about what works well: "ClickHouse connects to Kafka, S3, and PostgreSQL through native table engines. No ETL pipeline needed."
+- Acknowledge friction where it exists: "Migration required rewriting three queries, but the rest worked without changes."
+
+### 5.3 "Robust" / "Comprehensive" / "Cutting-edge"
+
+**Severity:** Medium
+
+**Description:** AI uses these adjectives as generic amplifiers that sound impressive but convey nothing specific.
+
+**Examples:**
+- "ClickHouse offers a robust set of analytical functions."
+- "The comprehensive documentation covers every feature."
+- "This cutting-edge technology powers some of the world's largest deployments."
+
+**Why it's a tell:** These words are vague by design. AI uses them when it doesn't have specific details to cite. Human writers with domain knowledge describe what makes something robust or comprehensive.
+
+**Remediation:**
+- Replace with specifics: "ClickHouse supports 150+ aggregate functions, including approximate algorithms like HyperLogLog and quantileTDigest."
+- If you can't be specific, the adjective is probably not needed: "The documentation covers installation, configuration, SQL reference, and troubleshooting."
+
+### 5.4 "Powerful" / "Elegant" / "Intuitive"
+
+**Severity:** Medium
+
+**Description:** AI applies subjective quality judgments that the reader has no reason to trust. These are opinion words dressed up as descriptions.
+
+**Examples:**
+- "ClickHouse provides a powerful query engine."
+- "The elegant solution avoids the complexity of traditional approaches."
+- "The intuitive interface makes it easy for analysts to get started."
+
+**Why it's a tell:** These are lazy descriptors. "Powerful" compared to what? "Elegant" by whose standard? AI uses them because they sound positive without requiring evidence.
+
+**Remediation:**
+- Show don't tell: "ClickHouse's query engine processes 1 billion rows/sec on a single node." (That's powerful -- but you showed it instead of claiming it.)
+- Replace "elegant" with a description of the actual design: "The solution uses a single materialized view instead of three separate ETL jobs."
+- Replace "intuitive" with what the user actually does: "Analysts write standard SQL -- no proprietary query language to learn."
+
+### 5.5 "Unlock" / "Leverage" / "Empower"
+
+**Severity:** High
+
+**Description:** AI uses these verbs as corporate-speak substitutes for simple verbs like "use," "enable," or "help."
+
+**Examples:**
+- "Unlock the full potential of your data with ClickHouse."
+- "Leverage real-time analytics to drive better decisions."
+- "This empowers teams to iterate faster."
+
+**Why it's a tell:** These are SaaS marketing verbs. They appear in almost every AI-generated product description. Human technical writers use plain language.
+
+**Remediation:**
+- Use plain verbs: "Use ClickHouse for real-time analytics."
+- Be specific about the action: "Teams can query live data instead of waiting for overnight batch jobs."
+- "Empower" is almost always replaceable with "let" or "help": "This lets teams iterate faster."
+
+---
+
+## 6. Structural Tells
+
+### 6.1 Every paragraph opens with a topic sentence
+
+**Severity:** Medium
+
+**Description:** AI produces paragraphs that each begin with a clear topic sentence summarizing the paragraph's point, followed by supporting details. This is textbook essay structure.
+
+**Examples:**
+A typical AI article might have consecutive paragraphs opening with:
+- "Query performance is the primary advantage of columnar storage."
+- "Data compression further reduces storage costs."
+- "Replication ensures high availability for production workloads."
+- "The ecosystem of integrations connects ClickHouse to existing tools."
+
+**Why it's a tell:** Human blog writing is less structured. Writers lead with examples, start with a question, drop in mid-thought, or build to the point instead of stating it first. Perfect topic-sentence-first structure for every paragraph reads like an essay outline.
+
+**Remediation:**
+- Vary paragraph openings: start some with examples, questions, or anecdotes.
+- Sometimes build to the point instead of leading with it: "We tried three different approaches to the ingestion pipeline. The first hit memory limits. The second couldn't keep up with the write rate. The third -- async inserts into ClickHouse -- handled the full load in 40% of the time."
+- Let some paragraphs just continue the thought from the previous one without a new topic sentence.
+
+### 6.2 Perfectly parallel list items
+
+**Severity:** Medium
+
+**Description:** AI constructs bullet lists or numbered lists where every item follows exactly the same grammatical structure -- same length, same verb tense, same format.
+
+**Examples:**
+- "Faster query execution through vectorized processing"
+- "Lower storage costs through columnar compression"
+- "Better reliability through built-in replication"
+- "Easier operations through automated cluster management"
+
+**Why it's a tell:** Human writers make lists where items vary in length, structure, and detail. Some items get a brief note; others get a full sentence. Perfect parallelism across 5+ items is AI.
+
+**Remediation:**
+- Let items vary naturally in length and structure:
+  - "Vectorized query execution"
+  - "Columnar compression cuts storage costs -- typically 5-10x vs row-oriented"
+  - "Built-in replication (no ZooKeeper required since 24.1)"
+  - "Automated cluster management"
+
+### 6.3 Formulaic intro-body-conclusion
+
+**Severity:** Medium
+
+**Description:** AI follows a rigid structure: introductory paragraph that previews the article, body sections that deliver on the preview, concluding paragraph that summarizes and looks forward. Every time.
+
+**Examples:**
+- Intro: "In this post, we'll explore how ClickHouse handles joins, why it matters, and how to optimize your queries."
+- Conclusion: "As we've seen, ClickHouse provides multiple join strategies that can handle even the most demanding analytical workloads. With the techniques discussed above, you're well-equipped to optimize your queries for any scenario."
+
+**Why it's a tell:** Human blog writers rarely preview their article structure in the intro, and they almost never write a summary conclusion. They either end with a call to action, a final thought, or just stop when the content is done.
+
+**Remediation:**
+- Open with the problem or a hook, not a preview: "JOINs in ClickHouse have a reputation for being slow. It's mostly undeserved."
+- End with a specific takeaway or next step, not a summary: "Start with hash joins and switch to partial merge joins only when memory is the constraint. For the full syntax reference, see the docs."
+- Don't announce what the article will cover. Just cover it.
+
+### 6.4 Three-part rhythm / rule of three
+
+**Severity:** Low
+
+**Description:** AI consistently groups things in threes -- three examples, three benefits, three paragraphs per section. This creates an unnaturally regular rhythm.
+
+**Examples:**
+- "ClickHouse is fast, efficient, and scalable."
+- "This matters for three reasons: performance, cost, and reliability."
+- Every section has exactly three subsections.
+
+**Why it's a tell:** The rule of three is a known rhetorical device, and AI applies it reflexively. Human writing has more irregular rhythms -- sometimes two points, sometimes five, sometimes one that gets a full paragraph.
+
+**Remediation:**
+- Vary the count. Sometimes there are two reasons. Sometimes there are seven. Don't force things into triples.
+- If you naturally have three points, that's fine -- but check whether the third is actually adding something or just padding.
+
+### 6.5 Section headers that form a complete narrative outline
+
+**Severity:** Low
+
+**Description:** AI generates section headers that, read in sequence, form a complete summary of the article. Each header is a full phrase or sentence rather than a short label.
+
+**Examples:**
+- "Why Query Performance Matters"
+- "How ClickHouse Achieves Sub-Second Latency"
+- "Optimizing Your Queries for Maximum Performance"
+- "Real-World Results: A Case Study"
+- "Getting Started with ClickHouse Today"
+
+**Why it's a tell:** Human writers use shorter, less formulaic headers. They're labels for sections, not miniature thesis statements. The progression from "why" to "how" to "results" to "getting started" is a template AI follows predictably.
+
+**Remediation:**
+- Use shorter headers: "Performance", "Under the hood", "Benchmarks", "Try it"
+- Don't force a narrative arc in the headers. Let the content create the arc.
+
+---
+
+## 7. Metaphor and Cliche
+
+### 7.1 "Landscape" / "Ecosystem"
+
+**Severity:** High
+
+**Description:** AI describes any industry, market, or technology space as a "landscape" or "ecosystem." These metaphors are so overused they've lost all meaning.
+
+**Examples:**
+- "The data analytics landscape has evolved significantly in recent years."
+- "Within the modern data ecosystem, ClickHouse plays a central role."
+- "Navigating the observability landscape can be challenging."
+
+**Why it's a tell:** Human writers in tech almost never use "landscape" unless they're literally discussing terrain. AI uses it as a default framing for any broad topic.
+
+**Remediation:**
+- Be specific: "There are more analytics databases now than there were five years ago. Most of them are bad."
+- Replace with the actual thing you're describing: "Within a typical data stack -- Kafka for ingestion, ClickHouse for analytics, Grafana for dashboards -- ClickHouse handles the heavy lifting."
+
+### 7.2 "Tapestry" / "Mosaic" / "Fabric"
+
+**Severity:** High
+
+**Description:** AI reaches for woven-material metaphors to describe complexity or interconnection.
+
+**Examples:**
+- "The rich tapestry of data sources feeding into the pipeline."
+- "A mosaic of tools and technologies that work together."
+- "The fabric of modern data infrastructure."
+
+**Why it's a tell:** Nobody in tech talks like this. These metaphors come from AI's training on literary and journalistic text. They sound absurd in a technical blog post.
+
+**Remediation:**
+- Delete the metaphor entirely and describe the actual thing: "The pipeline ingests from Kafka, S3, and PostgreSQL."
+- If you want to convey complexity, use concrete details: "The team manages 47 data sources, 12 transformation jobs, and 3 analytics databases."
+
+### 7.3 "Paradigm shift" / "Game-changer"
+
+**Severity:** High
+
+**Description:** AI uses these for any significant change or improvement. They've been meaningless for at least a decade.
+
+**Examples:**
+- "ClickHouse represents a paradigm shift in analytical database design."
+- "Async inserts are a game-changer for high-volume ingestion."
+- "This paradigm shift in observability is driven by cost pressures."
+
+**Why it's a tell:** These phrases scream "I have nothing specific to say but I want to sound important." Human writers who understand the technology describe the actual change.
+
+**Remediation:**
+- Describe the actual shift: "Before ClickHouse, analytical queries on 10TB meant waiting minutes. Now they take seconds."
+- Explain what changed and why it matters: "Async inserts let you write millions of rows per second without blocking queries. Before this, you needed a buffer layer like Kafka to smooth out the write load."
+
+### 7.4 "North star" / "Guiding principle"
+
+**Severity:** High
+
+**Description:** AI uses navigation metaphors for strategic priorities or design goals.
+
+**Examples:**
+- "Performance has always been the north star for the ClickHouse team."
+- "Our guiding principle is simplicity."
+- "Query speed remains the north star of the project."
+
+**Why it's a tell:** "North star" entered mainstream corporate vocabulary around 2018-2020 and AI absorbed it. It's now the default metaphor for "important goal" in AI output.
+
+**Remediation:**
+- State it plainly: "The ClickHouse team optimizes for query speed above all else."
+- Use specifics: "Every design decision starts with one question: does this make queries faster?"
+
+### 7.5 "At the end of the day" / "When all is said and done"
+
+**Severity:** Medium
+
+**Description:** AI uses these colloquialisms to introduce a concluding or summary point. They add nothing and make the writing sound like a talk-show interview.
+
+**Examples:**
+- "At the end of the day, what matters is query performance."
+- "When all is said and done, the results speak for themselves."
+- "At the end of the day, ClickHouse delivers on its promise."
+
+**Why it's a tell:** Human technical writers don't use these phrases in writing (some use them in speech). AI drops them into blog posts as a way to signal a concluding thought.
+
+**Remediation:**
+- Delete the filler and state the point: "What matters is query performance."
+- Even better, be specific: "The only metric that mattered to the team was p99 query latency, and ClickHouse kept it under 200ms."
+
+---
+
+## 8. Voice and Tone
+
+### 8.1 Overly balanced "on one hand / on the other hand"
+
+**Severity:** High
+
+**Description:** AI presents every topic as a balanced debate, giving equal weight to pros and cons, advantages and disadvantages. This is AI being trained to be fair and objective, but it produces writing that lacks conviction.
+
+**Examples:**
+- "On one hand, ClickHouse offers exceptional query performance. On the other hand, it requires careful schema design to achieve optimal results."
+- "While columnar storage excels at analytical queries, it's important to note that transactional workloads may be better served by row-oriented databases."
+- "There are clear advantages to this approach, but there are also trade-offs to consider."
+
+**Why it's a tell:** Human writers with expertise take positions. They know what's good, what's bad, and they say so. AI hedges because it's designed to avoid appearing biased. The result reads as mealy-mouthed.
+
+**Remediation:**
+- Take a position: "ClickHouse is the fastest option for analytical queries. It's not designed for transactions, and you shouldn't use it for them."
+- Acknowledge limitations directly, without the two-handed framing: "Schema design matters. A bad primary key means bad performance. Here's how to pick the right one."
+
+### 8.2 Excessive hedging
+
+**Severity:** Medium
+
+**Description:** AI qualifies every claim with hedge words: "may," "might," "could," "potentially," "arguably," "to some extent." One or two per piece is fine. Five or more is AI.
+
+**Examples:**
+- "This could potentially improve query performance."
+- "ClickHouse may be a good fit for some observability workloads."
+- "This approach might arguably be considered more efficient."
+- "To some extent, the results suggest that columnar storage could offer advantages."
+
+**Why it's a tell:** AI is trained to avoid absolute claims, which produces writing that never commits to anything. The accumulation of hedge words makes the writer sound uncertain about their own topic.
+
+**Remediation:**
+- Commit to the claim: "This improves query performance by 3-5x in our benchmarks."
+- If uncertainty is genuine, say why: "We haven't tested this with sorted data, so performance on pre-sorted datasets may differ."
+- Reserve "may" and "might" for actual uncertainty, not as a default qualifier.
+
+### 8.3 Lack of opinion or point of view
+
+**Severity:** Medium
+
+**Description:** AI writes informational content that describes what things are and how they work without ever expressing a viewpoint on whether they're good, bad, overrated, or underappreciated.
+
+**Examples:**
+An AI article about ClickHouse vs. PostgreSQL might describe both databases' features in detail without ever saying which one to pick or expressing a preference. Each section reads like a Wikipedia article.
+
+**Why it's a tell:** Human experts have opinions. Blog posts from practitioners include statements like "I prefer X because..." or "X is the wrong tool for this" or "I've never understood why people use X for Y." Opinionless writing signals AI.
+
+**Remediation:**
+- Add a recommendation: "For analytical queries over 1TB, use ClickHouse. Below that, PostgreSQL with proper indexing is simpler and good enough."
+- Express opinions where warranted: "Partitioning by date is overused. Most teams do it out of habit, not because it helps their queries."
+- Include first-hand experience where available.
+
+### 8.4 Diplomatic/corporate tone in informal contexts
+
+**Severity:** Medium
+
+**Description:** AI defaults to a cautious, professional tone that avoids anything sharp, funny, or informal. Even in a blog post that should have personality, AI writes like a press release.
+
+**Examples:**
+- "We are pleased to introduce..." instead of "We shipped..."
+- "We believe this represents a significant step forward" instead of "This is a big deal"
+- "We are committed to continually improving..." instead of just describing the improvement
+
+**Why it's a tell:** Corporate blog posts from real humans often have personality, humor, and directness. AI plays it safe with sanitized corporate language.
+
+**Remediation:**
+- Write like a human talking to a peer: "We shipped async inserts. Here's why you should care."
+- Use contractions naturally: "We've" not "We have," "can't" not "cannot," "it's" not "it is."
+- Include personality where appropriate: a joke, a wry observation, a candid admission of difficulty.
+
+### 8.5 Thanking the reader
+
+**Severity:** High
+
+**Description:** AI closes articles by thanking the reader for their time or interest. Human blog writers almost never do this.
+
+**Examples:**
+- "Thank you for reading, and we hope this guide has been helpful."
+- "Thanks for following along. We'd love to hear your thoughts in the comments."
+- "We appreciate you taking the time to explore this topic with us."
+
+**Why it's a tell:** This is AI performing politeness. It appears in the vast majority of AI-generated articles and almost zero human-written tech blog posts.
+
+**Remediation:**
+- End with a call to action, a link, or a final technical point.
+- Just stop when the content is done. "Try it yourself: `clickhouse-client --query 'SELECT count() FROM hits'`"
+- If you must close, close with substance, not thanks.
+
+---
+
+## 9. Formatting Tells
+
+### 9.1 Excessive bold for emphasis
+
+**Severity:** Medium
+
+**Description:** AI bolds key terms and phrases throughout the text, treating bold as a highlighting tool rather than using it sparingly for structure.
+
+**Examples:**
+- "ClickHouse uses **columnar storage**, which means it reads only the **columns needed** for each query, resulting in **significant performance improvements**."
+- "The **key advantage** of this approach is **reduced I/O**, which leads to **faster query execution**."
+
+**Why it's a tell:** Human writers use bold for headings, subheadings, and occasionally a key term on first introduction. AI uses bold as emphasis scattered through body text, often hitting 5+ bold phrases per paragraph.
+
+**Remediation:**
+- Remove most bold from body text. Let sentence structure create emphasis.
+- Use bold only for actual key terms on first introduction, or not at all in body text.
+- If a sentence needs emphasis, rewrite it to be stronger, don't bold it.
+
+### 9.2 Every section exactly the same length
+
+**Severity:** Medium
+
+**Description:** AI produces sections of remarkably uniform length -- each gets 2-3 paragraphs, each about the same word count. Real articles have sections that vary significantly based on topic complexity.
+
+**Examples:**
+A 2000-word article where each of 5 sections is exactly 350-400 words. Each section has exactly 3 paragraphs. No section is noticeably longer or shorter than the others.
+
+**Why it's a tell:** Human writers spend more time on complex or important topics and less on simple or peripheral ones. Uniform section length means the AI is budgeting words rather than writing until the topic is covered.
+
+**Remediation:**
+- Let some sections be long and detailed, others short and to the point.
+- A section can be one paragraph if that's all it needs. It can also be 8 paragraphs if the topic requires it.
+- Don't pad shorter sections to match longer ones.
+
+### 9.3 Numbered lists for everything
+
+**Severity:** Medium
+
+**Description:** AI converts naturally flowing content into numbered lists, even when the items don't have a meaningful order or sequence.
+
+**Examples:**
+- "There are several benefits to this approach: 1. Faster queries 2. Lower storage costs 3. Simpler operations 4. Better compression"
+- "To get started: 1. Install ClickHouse 2. Create a database 3. Define your schema 4. Insert data 5. Run queries"
+
+(The second example is fine -- it's a sequential process. The first is not -- the benefits have no inherent order.)
+
+**Why it's a tell:** AI defaults to numbered lists because they're structured and easy to generate. Human writers use numbered lists for sequential steps and bullet lists (or plain prose) for unordered items.
+
+**Remediation:**
+- Use numbered lists only for sequential steps.
+- Use bullet lists for unordered items.
+- Consider whether a list is even needed -- sometimes a sentence works better: "The main benefits are faster queries and lower storage costs."
+
+### 9.4 Summary/TLDR at the top that repeats the content
+
+**Severity:** Medium
+
+**Description:** AI adds a summary or TLDR section at the beginning of an article that previews every point the article will make, then the article makes all those points again.
+
+**Examples:**
+- "**TLDR:** ClickHouse 24.8 ships with async inserts for high-volume ingestion, query caching for repeated analytical queries, and lightweight deletes for GDPR compliance." (Followed by an article that covers these three things in sections with almost identical wording.)
+
+**Why it's a tell:** Human writers either write a TLDR or write the article, rarely both with the same content. AI produces both because it generates the TLDR as a summary of its own upcoming output.
+
+**Remediation:**
+- If the audience wants a TLDR, write one that's genuinely condensed and uses different wording than the body.
+- Often, just skip the TLDR and write a strong opening paragraph that pulls the reader in.
+
+### 9.5 Overuse of horizontal rules / section dividers
+
+**Severity:** Low
+
+**Description:** AI inserts horizontal rules (`---`) between every major section, creating a visually segmented document even when the sections flow naturally.
+
+**Examples:**
+A post where every H2 section is preceded by a horizontal rule, breaking the page into visually separate "cards." Human-written blog posts typically let headings create the visual hierarchy.
+
+**Why it's a tell:** This is a formatting habit from AI's exposure to README files and documentation. Blog posts don't usually need explicit section dividers -- headings handle it.
+
+**Remediation:**
+- Use headings for structure, not horizontal rules.
+- Reserve horizontal rules for a genuine change in topic or a shift (like an epilogue or appendix).
+
+---
+
+## Detection Guidance
+
+When reviewing content, don't flag individual tells in isolation (except high-severity ones like "tapestry" or "paradigm shift" which are strong signals alone). Look for **patterns of accumulation:**
+
+- **3+ tells from different categories** in a single piece = likely AI-generated or AI-assisted
+- **5+ tells from the same category** = the writer is leaning on AI for that aspect (e.g., transitions, structure)
+- **High-severity tells in the opening or closing paragraphs** = especially suspect, as AI follows predictable intro/conclusion patterns
+
+**Frequency matters more than presence.** One em-dash is fine. Six em-dashes in 1000 words is a tell. One "moreover" is forgivable. Three "moreovers" is AI.
+
+**Context matters.** A formal whitepaper may legitimately use some of these patterns (semicolons, topic sentences, parallel lists). A blog post or marketing page should not.
+
+When running in **correct mode**, prioritize high-severity tells first, then address medium-severity ones that appear in clusters. Low-severity tells should only be corrected when they contribute to an overall pattern.
\ No newline at end of file
diff --git a/.claude/skills/docs-pre-ship-review/SKILL.md b/.claude/skills/docs-pre-ship-review/SKILL.md
new file mode 100644
index 00000000000..c190eae1a48
--- /dev/null
+++ b/.claude/skills/docs-pre-ship-review/SKILL.md
@@ -0,0 +1,195 @@
+---
+name: docs-pre-ship-review
+description: >
+  Review a ClickHouse docs page before shipping. Runs the self-review
+  checklist, Vale linting, and PR review rubric. Use when doing a final
+  check, running Vale, or when asked "is this ready to ship."
+---
+
+# Docs Pre-Ship Review Skill
+
+## Context
+
+This skill covers the review and verification workflow for docs pages before
+shipping. For the underlying voice, style, and content rules applied during
+writing, see the **docs-drafting** skill.
+
+## Self-Review Checklist (Before Opening a PR)
+
+Run this before requesting review. Target: 30–45 minutes.
+
+### Technical Accuracy
+
+- [ ] Tested every command in a clean environment
+- [ ] Clicked every link (internal anchors and external URLs)
+- [ ] Code blocks execute without modification (no placeholder values left)
+- [ ] Config files are valid (YAML, JSON, etc.)
+- [ ] Environment variable names are consistent throughout the page
+- [ ] Verified technical claims against source code (see below)
+
+#### Source Verification
+
+Any time the page lists valid config values, enum options, CLI flags, or
+describes what an option does, verify against the ClickHouse source code or
+the relevant upstream library (e.g., ClickHouse's Poco fork). Don't trust
+other docs pages or LLM knowledge alone.
+
+**Scale effort to the claim.** Not every check needs a research agent. For
+simple factual claims (version numbers, dates, feature names), a quick web
+search or `grep` of the source is enough. Reserve deep research agents for
+claims that are central to the page and hard to verify (e.g., how a feature
+works under the hood, or whether a config option behaves as described).
+
+Present a verification summary:
+- What was verified and against which source
+- What was corrected
+- Confidence: high (source code), medium (docs/examples), low (LLM only)
+- Gaps that couldn't be verified
+
+#### Scope
+
+- Only edit English source files under `docs/`. Files under `i18n/` (jp, ko,
+  ru, zh) sync automatically — never edit them directly.
+
+### Structure and Consistency
+
+- [ ] Section order matches the standard skeleton for the page type
+- [ ] TL;DR block (if present) is concise, not a bullet list restating headings
+- [ ] Frontmatter has all required fields (slug, title, sidebar_label,
+      pagination_prev, pagination_next, description, doc_type, keywords)
+- [ ] Keywords are specific and search-worthy (see docs-drafting skill)
+- [ ] Heading anchors are present on all H2/H3 (`{#anchor-name}`)
+- [ ] Code blocks have language tags (```bash, ```yaml, ```python, ```sql)
+- [ ] File paths and config values use backticks
+- [ ] Consistent line wrapping — don't mix hard-wrapped and unwrapped
+      paragraphs in the same file. Pick one style and apply it throughout.
+
+### Voice and Polish
+
+- [ ] Read aloud — does it sound like a person wrote it?
+- [ ] Uses "you" not "users," "the user," "organizations," or "one"
+- [ ] No bold-bullet lists (use prose with inline formatting)
+- [ ] Ran Vale locally: `vale docs/path/to/file.md`
+- [ ] Scanned for and removed AI-isms (see docs-drafting skill)
+- [ ] Applied prose tightening rules (see docs-drafting skill)
+- [ ] Scanned for em dash issues: binary contrast pattern and overall density (see docs-drafting skill)
+- [ ] Checked linking on first mention (see docs-drafting skill)
+- [ ] Checked content integrity (see docs-drafting skill)
+- [ ] Checked marketing site alignment if applicable (see docs-drafting skill)
+
+## Vale Fix Workflow
+
+When asked to lint a file, fix Vale warnings, clean up prose, or as part of
+the pre-ship review, apply this workflow.
+
+Vale is configured at `.vale.ini` and checks only `.md` files under `docs/`.
+The style rules live in `styles/ClickHouse/`.
+
+### Step 1: Read the File
+
+Read the target file to understand its content, then apply the Vale rules
+listed below. If the user has Vale output already, use that instead.
+
+### Step 2: Categorize and Fix
+
+Group issues by type. Fix in this priority order:
+
+**Auto-fixable (apply without asking):**
+
+1. **British spelling → US spelling** (`British.yml`, level: warning)
+   - Common swaps: colour→color, analyse→analyze, behaviour→behavior,
+     optimise→optimize, organisation→organization, centre→center,
+     licence→license, favourite→favorite, etc.
+   - Full swap list is in `styles/ClickHouse/British.yml`
+
+2. **Wordy phrases** (`Wordy.yml`, level: suggestion)
+   - "a number of" → specify the number or remove
+   - "as well as" → "and"
+   - "note that" → remove
+   - "in order to" → "to"
+   - "quite" → remove
+   - "and so on" → use "like" with examples, or remove — **but skip in table cells** where the fix would add more words than it removes and the meaning is already clear
+   - "please" → remove unless we've inconvenienced the user
+
+3. **Duplicate words** (`Repetition.yml`, level: warning)
+   - "the the" → "the", "and and" → "and", etc.
+
+4. **Contractions** (`Contractions.yml`, level: suggestion)
+   - "do not" → "don't", "is not" → "isn't", "cannot" → "can't",
+     "it is" → "it's", "we are" → "we're", etc.
+   - Note: contractions are the ClickHouse style. Use them.
+
+5. **Heading capitalization** (`Headings.yml`, level: warning)
+   - Use sentence-style capitalization for all headings
+   - Exception: proper nouns, product names, acronyms (extensive
+     exceptions list in Headings.yml — ClickHouse, MergeTree, SQL,
+     OpenTelemetry, Docker, Kafka, etc. are all excepted)
+
+6. **Ability language** (`Ability.yml`, level: suggestion)
+   - "able to" → rephrase: "you can" or just state the action
+   - "ability to" → rephrase: "lets you" or "supports"
+
+**Judgment-required (flag to user, suggest fix):**
+
+7. **Heading punctuation** (`HeadingPunctuation.yml`) — headings shouldn't
+   end with punctuation (except `?`)
+8. **Ordinal suffixes** (`Ordinal.yml`) — check context before fixing
+9. **Exclamation marks** (`Exclamation.yml`) — remove unless truly warranted
+10. **Backtick formatting** (`BackTicks*.yml`) — ClickHouse functions,
+    settings, table engines, formats should be in backticks, but flag
+    rather than blindly apply
+
+### Step 3: Apply Fixes
+
+Use the `Edit` tool to apply fixes. Group related fixes into a single
+edit where possible. Always re-read the file before editing to get
+exact text matches.
+
+### Step 4: Report
+
+After fixing, provide a brief summary:
+- How many issues were auto-fixed, by category
+- Any issues that need human judgment (with line context and suggestion)
+- Any issues skipped and why
+
+### Vale Rules Disabled in Config
+
+These rules exist but are turned off in `.vale.ini` — do NOT flag these:
+- `SentenceLength` (disabled: `ClickHouse.SentenceLength = NO`)
+- `FutureTense` (disabled: `ClickHouse.FutureTense = NO`)
+
+### Files Excluded from Vale
+
+Don't lint these:
+- `docs/whats-new/**/*.md`
+- `docs/releases/**/*.md`
+- `.mdx` files may produce false positives from JSX syntax, but Vale can
+  still be run on them. Review results with that caveat.
+- Changelog files
+
+### Vale Fix Notes
+
+- Always preserve technical accuracy. If a "wordy" phrase is needed for
+  clarity in a technical context, skip the fix and note why.
+- Never change content inside code blocks, YAML frontmatter, or
+  admonition markers (:::note, :::warning, etc.).
+- **Never change ` ```bash ` to ` ```shell `** based on the `CodeblockFences`
+  suggestion. `bash` is more specific and widely recognized. Only change a
+  code fence language if it's genuinely wrong (e.g., SQL tagged as `bash`).
+- **Evaluate every suggestion before applying.** If the fix is longer or more
+  awkward than the original, skip it. The test: does it make the prose clearer
+  and shorter? If not, skip and note why.
+- Don't change product names, function names, or ClickHouse-specific
+  terminology even if they look like style violations.
+- When fixing contractions, be careful in formal/legal contexts (e.g.,
+  compliance docs, SLA descriptions) where contractions may be
+  intentionally avoided.
+- The `Headings.yml` exceptions list is enormous. When in doubt about
+  whether a word in a heading is a proper noun or product name, leave it
+  as-is and flag it.
+
+## Reviewing others' work
+
+For reviewing PRs from other authors, use the **docs-pr-review** skill instead.
+It covers triage, comment writing, and scope discipline for reviewing someone
+else's work.