From d0fcf549fe8f2c14803545ea182474d3cbc81000 Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 02:30:11 -0700
Subject: [PATCH 01/20] Dedup KB skill rulebook: extract shared rules into
 kb-editing-conventions.md

derek, kb-pr-open, and kb-pr-review each independently inlined Derek's
areas table, title-format rules, and the callout-severity mapping,
requiring N synchronized manual edits per rule change (root cause of
most add-kb-skills PR #1358 review rounds). Extend the existing
kb-editing-conventions.md sections (callouts, bolding, links, titles)
and add new ones (frontmatter, article-type identification, article
structure, images) as the single source; all three skills now read
from it instead of duplicating.

Also reconciles the knowledge_article_id policy (kb-pr-review allowed
proposing removal of a placeholder value; kb-pr-open never did) to
kb-pr-open's never-remove policy, fixes kb-pr-review's stale
BoilerplateCrossRef note (the Vale rule is unreachable on docs/kb/
files), and syncs wording drift in the kb-editing-conventions scan
table and cross-section consistency table between the two PR skills.

Addresses netwrix-corp/docs-kb-staging#131.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 139 +++++++++++++++++--
 .claude/skills/derek/SKILL.md                | 115 +++------------
 .claude/skills/kb-pr-open/SKILL.md           |  88 +++---------
 .claude/skills/kb-pr-review/SKILL.md         |  94 +++++--------
 4 files changed, 210 insertions(+), 226 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index ac48e01bba..10809b503b 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -1,8 +1,8 @@
 # KB Editing Conventions
 
-Comprehensive KB editing rulebook covering structure, step condensation, list types, sentence-level rules, callouts, bolding, overview quality, links, placeholders, formatting, cross-section consistency, and titles.
+Comprehensive KB editing rulebook covering frontmatter, article type identification, article structure, structure/step condensation, list types, sentence-level rules, callouts, bolding, overview quality, links, placeholders, formatting, cross-section consistency, titles, and images.
 
-Apply during the `kb-pr-open` preemptive scan and the `kb-pr-review` Derek review pass on every KB batch. This document is the canonical rulebook — both skills reference it rather than duplicating its content. Amend it via PR when a batch surfaces a new pattern.
+Apply during the `kb-pr-open` preemptive scan, the `kb-pr-review` review pass, and the `derek` review on every KB batch. This document is the canonical rulebook — `derek`, `kb-pr-open`, and `kb-pr-review` all read it rather than duplicating its content. Amend it via PR when a batch surfaces a new pattern.
 
 ## 1. Heading/step structure
 
@@ -12,7 +12,7 @@ Apply during the `kb-pr-open` preemptive scan and the `kb-pr-review` Derek revie
 - **Gate B — Normalize.** If ≥3 substantive subheadings remain after Gate A **and represent sequential steps of the same procedure**, apply `Step N — <Label>` (em dash, not colon) to that set. The count excludes subheadings that are a categorically different kind of section — most commonly a `Troubleshooting`/exception-handling subheading — even when it sits at the exact same heading depth as the procedural subheadings it follows. Troubleshooting content isn't a step in the sequence; it doesn't count toward the Gate B threshold, and it doesn't receive a `Step N —` label itself (nor does anything nested beneath it). Normalize any pre-existing `Step N:` to match. Does NOT apply to parallel-alternative subheadings (Windows/Linux) — keep those descriptive. See also [[feedback_kb_step_subheadings]].
 - **Under-fragmentation — the mirror problem.** A single `## Instructions` or `## Resolution` section holding two or more distinct activities (locate a log, then look up an error code; edit a config, then verify the login flow) with no subheadings is as broken as over-fragmentation. Split by distinct activity; use subheadings once there are two or more real activities.
 - **Action described as trailing prose** — an action that logically belongs in the numbered sequence but sits as a trailing paragraph (e.g., a "start the services" instruction written as prose after the last numbered step) gets pulled into the sequence as its own numbered step, matching the structure of parallel actions in the article.
-- **Subheading wrapping a single trivial element** — a subheading like `### Example Error Message` that exists only to label a single code block adds structure without content. Remove the subheading and lead in with a short sentence ("Example error:") followed by the code block. A heading implies a navigable, standalone unit; a lone error block is not one.
+- **Subheading wrapping a single trivial element** — a subheading like `### Example Error Message` that exists only to label a single code block adds structure without content. Remove the subheading and lead in with a short sentence ("Example error:") followed by the code block. A heading implies a navigable, standalone unit; a lone error block is not one. Scope is not restricted to Instructions.
 - **Nested if/then branches** get split into their own subsections instead of nested lettered/roman sub-lists.
 - **Prerequisite repeated across steps/sections.** First check whether the repetition is a symptom of over-fragmentation (thin subheadings that should merge under Gate A). Merging the subheadings usually resolves the repetition — the shared context becomes a natural single lead-in sentence at the top of the merged step. Only if Gate A does not apply, hoist the shared content — and choose the target format by content type: **caveat/warning-flavored prerequisites** (a condition that breaks the procedure if ignored — timing, permissions, state) go into a NOTE block near the top of Instructions; **procedural framing** (where to run the steps, what tool to open, which machine to be on) becomes a plain lead-in sentence, not a NOTE. NOTE is for caveats, not for procedural context.
 - **Numbered list broken by intervening paragraph** silently restarts at 1 in rendered output. Fix with a heading boundary or 4-space indent to attach the paragraph to the preceding step — not by fiddling with numbers.
@@ -41,7 +41,7 @@ All three are `###` siblings under `## Instructions`, but `Troubleshooting` is a
 
 ## 3. List type
 
-- **Numbered lists** for sequential actions performed in order.
+- **Numbered lists** for sequential actions performed in order. **Applies broadly** — this rule covers Resolution sections and any sub-sections within them (e.g., verification steps), not just top-level Instructions procedures.
 - **Bulleted lists** for alternatives/options and for field-value pairs — per KB style guide ("use unordered lists for unordered recommendations or options"). Numbered lists wrongly imply order for things that are alternatives.
 - **Minimize nesting** — one either/or choice can nest under its step; multi-step branches get their own subsection.
 - **Nested sub-lists under a numbered step use `-` dashes**, never nested `1.` `2.` `3.` numbering. Numbered-inside-numbered renders ambiguously and reads as a restart; dashes make the parent/child relationship explicit.
@@ -59,18 +59,34 @@ All three are `###` siblings under `## Instructions`, but `Troubleshooting` is a
 - **Redundant/duplicate sentences** saying the same thing twice get merged — often into a final numbered step plus a NOTE.
 - **Abrupt UI-click endings** — steps ending on a bare "Click X." get a closing sentence describing the observable result, or get combined with the next click.
 - **Passive/conditional phrasing** reworded into direct imperative form where it changes nothing factually (e.g., "You can adjust this level of privilege..." → "Adjust the level of privilege...").
+- **Impersonal-subject directness.** Flag sentences where an impersonal subject ("the operation", "the process", "the system") performs an action that the actual actor or action could express more directly. Example: "the operation fails with an error" → "Clicking **X** fails with an error". Apply judgment — not every impersonal subject is wrong, but flag cases where a direct rewrite is clearly cleaner.
 
 ## 5. Callout severity
 
 - **NOTE vs IMPORTANT is a judgment call, not interchangeable by default.** Supplementary/contextual info stays NOTE. Information that affects correctness or causes a real problem if skipped (e.g., a config-change timing caveat that could cause a false test result) should be IMPORTANT. Revisit per file rather than assuming the original author chose correctly.
-- **Blank line required before any NOTE/IMPORTANT blockquote.** These are the only two callout severities — see `.claude/skills/derek/SKILL.md` §7 for the full Docusaurus-admonition-to-blockquote mapping.
+- **Blank line required before any NOTE/IMPORTANT blockquote.**
+- **Only two blockquote severities exist: `NOTE` and `IMPORTANT`.** This applies whether the callout is currently Docusaurus `:::` admonition syntax or already a blockquote with the wrong severity label — flag both:
+  - Any `:::note`, `:::tip`, `:::info`, `:::warning`, `:::caution`, `:::danger`, or `:::important` block (Docusaurus syntax, not yet a blockquote).
+  - Any `> **<SEVERITY>:**` blockquote whose severity is not `NOTE` or `IMPORTANT` — for example `> **TIP:**`, `> **WARNING:**`, `> **CAUTION:**`, `> **DANGER:**`, `> **INFO:**`. It's already a blockquote; only the severity label is wrong.
 
-## 6. Bolding
+  Convert/relabel per this mapping (covers both the `:::` and blockquote spellings of each severity):
+
+  - `:::note` / `> **NOTE:**`, `:::tip` / `> **TIP:**`, `:::info` / `> **INFO:**` → `> **NOTE:**` — for supplementary information
+  - `:::warning` / `> **WARNING:**`, `:::caution` / `> **CAUTION:**`, `:::danger` / `> **DANGER:**`, `:::important` → `> **IMPORTANT:**` — for critical information that could cause issues if ignored
+
+  If the callout sits inside a numbered list item, apply the 4-space indentation rule in the next bullet to the converted/relabeled blockquote.
+- **Callout inside a numbered list item must be indented 4 spaces** to attach to the preceding step. Fewer than 4 spaces breaks the list at CommonMark render time — this is a build-breaker, not a style nit.
+- **Migration debt:** ~16 files currently use `> **TIP:**` or `> **WARNING:**` blockquotes (already-blockquoted, not Docusaurus syntax) and are now non-compliant under the two-severity rule above.
+
+## 6. Bolding and inline code
 
 - **Bold named apps/tools** the reader opens (Command Prompt, Mongo shell) — matches site-wide precedent. Don't extend to every noun.
 - **Don't bold generic/non-UI nouns** (MongoDB service, MongoDB authentication).
 - **Don't bold the product name after "Log in to."**
 - **Verify UI tab/option names against the actual product docs** before bolding or renaming.
+- **Bold UI element names only when they're action targets in the current step** — buttons being clicked, fields being filled, dropdowns being selected, menu items being chosen. A UI element mentioned as context only (not acted on in this step) does not get bold. ✓ "Click **Save**." ✓ "Select **PDF** from the **Save as type** dropdown." ✗ "The file appears under the Save as type column." — no bold on contextual reference.
+- **Use inline code (backticks), not bold, for:** registry paths, registry value names, registry data, error codes (e.g., `0x80070005`, `0x80004005`), commands, and executable names.
+- **Registry, file, and directory paths in the article body must be wrapped in backticks or a fenced code block.** Patterns to look for: registry paths starting with `HKEY_`, `Computer\`, or `HKLM\`; Windows paths containing `C:\`, `\\`, or multiple backslash segments; Unix/Linux paths with multiple forward-slash segments (e.g., `/etc/netwrix/...`).
 
 ## 7. Overview quality
 
@@ -81,11 +97,15 @@ All three are `###` siblings under `## Instructions`, but `Troubleshooting` is a
 
 ## 8. Links
 
+- **Three internal link forms are all valid** — `[text](/docs/...)` (the dominant form, ~218 KB files), `[text](pathname:///docs/...)`, and relative `.md` links (`[text](../other-article.md)`, `[text](./other-article.md)` — `kb_style_guide.md`'s own "Do" example for internal links uses this form, and it's in active use across roughly a dozen KB files). Do not propose converting one form to another. For each, resolve the actual target file on disk: check for a `slug` frontmatter override on the target first; if none, the URL segment (or relative path) must match the target's real path/filename (not its `sidebar_label` or `title`). Flag any link whose URL does not resolve to a real file on disk as a Required fix, and correct it to the real path. Only genuinely external links (`http://`, `https://`, `mailto:`, etc.) are out of scope for this check.
+- **`pathname://` links specifically** use the version-with-underscore format (`8_2` not `8.2`) and must resolve to a real file — flag a dotted version segment as a Required fix even if the rest of the path resolves. This is a constraint on `pathname://` links where they're used, not a mandate to prefer that form over the bare `/docs/...` form.
+- **Backstop is `npm run build`** — but `onBrokenLinks`/`onBrokenMarkdownLinks`/`onBrokenAnchors` in `docusaurus.config.js` only throw on a full build; a single-product build (`DOCS_PRODUCT=...`, the faster path `CLAUDE.md` recommends) relaxes all three to `warn`, so a broken link there won't fail the build. Either way, catch broken links before submission rather than relying on the backstop.
+- **`WeakLinkText` Vale findings require a search, not just a rewrite.** Before proposing any fix for a Vale `WeakLinkText` finding, grep `docs/kb/**/*.md` and `docs/<product>/<version>/**/*.md` for a plausible real target based on the referenced topic (e.g., "Accounts and Required Permissions" → search for `accountreqs`, `account.*permission`). If a real target resolves, convert the prose into a proper link to it. Only rewrite the sentence to remove the implied reference if the search turns up nothing. Do not skip the search because the phrasing already implies no real link exists — the trigger already fired precisely because the phrasing looks like an implied reference, and the target often does exist on disk.
+- **`BoilerplateCrossRef` is unreachable on KB files — do not treat it as a real finding.** The Vale rule lives only in `.vale/styles/Netwrix/`, never `.vale/styles/NetwrixKB/`. `.vale.ini` scopes `BasedOnStyles = NetwrixKB` to `docs/kb/**/*.md`, replacing (not merging with) the repo-wide `Netwrix` style — so a `BoilerplateCrossRef` finding can never fire on a KB file under this scope (confirmed empirically: `vale --config .vale.ini` on a KB test file with a `BoilerplateCrossRef`-triggering phrase produced zero alerts). If one somehow appears, verify the file's actual style scope before treating it as real.
 - **`<!-- link removed -->` comments** deserve a real-target search before shipping. If a valid internal replacement exists in `docs/kb/**/*.md` or `docs/<product>/<version>/**/*.md`, restore the cross-link.
 - **"Contact Netwrix Support"** → `[Netwrix Support](https://www.netwrix.com/support.html)`. Only link the first "contact" action per article.
-- **Internal `pathname://` links** use the version-with-underscore format (`8_2` not `8.2`) and must resolve to a real file.
 - **Dense multi-link "see X, see Y, see Z" prose → single NOTE.** When a paragraph contains 3+ inline cross-reference clauses stacked in one sentence, collapse them into a single NOTE block with the links listed cleanly (compact enumeration or short bulleted list under the NOTE). Multiple inline "see also" clauses in one sentence read as noise; a NOTE with clean bullets is scannable.
-- **Title change → link-text sweep across the repo.** When a KB article's title changes, do a repo-wide search for internal links whose visible text uses the *old* title, and update the link text to the new title. URL resolution alone is not sufficient — the visible link text must describe the current target, per the style guide's link-text rule. The existing links-review check (URL resolves on disk) does not catch stale link text.
+- **Title change → link-text sweep across the repo.** When a KB article's title changes, do a repo-wide search for internal links whose visible text uses the *old* title, and update the link text to the new title. URL resolution alone is not sufficient — the visible link text must describe the current target, per the style guide's link-text rule. The existing links-review check (URL resolves on disk) does not catch stale link text. Use a dedicated search tool, passing the old title as a pattern parameter, rather than interpolating the title into a shell command string — shell-quote characters (some titles contain `'`) and unescaped regex metacharacters (`. * + ? ( ) [ ] { } \ | ^ $`) in the title can each cause a missed or broken match. Match `\[<old title>\]\(` (with the title's metacharacters escaped) to catch all three internal link forms in one search.
 
 ## 9. Placeholders & data hygiene
 
@@ -99,6 +119,7 @@ All three are `###` siblings under `## Instructions`, but `Troubleshooting` is a
 - **A flat list of data** becomes a monospace code-block grid, not comma-separated prose or a fake table.
 - **Trailing image-removed comments** don't need their own anchoring sentence, but excess consecutive blank lines around them get trimmed to one.
 - **KB headings are Title Case** (verified against `kb_style_guide.md`, not assumed) — override of the docs-wide sentence-case rule.
+- **Trailing periods inside markdown table cells** get stripped. Vale and Dale skip table content, so these slip through unless caught here.
 
 ## 11. Cross-section consistency
 
@@ -112,12 +133,108 @@ Rules that compare two sections of the same article against each other. Section-
 
 ## 12. Titles
 
-Content-of-title rules (surface style — gerund form, title case — lives in the kb-pr-open SKILL title-format rules).
+Title findings split into two categories based on whether the change is mechanical or semantic.
 
+### Mechanical style corrections — Required fixes (apply on approval, low ambiguity)
+
+- **gerund-for-How-To-Instructions:** "How to..." prefix → gerund form (e.g., "How to Export Event Logs" → "Exporting Event Logs"). Applies only to How-To Instructions form articles (`## Overview` + `## Instructions` structure). Does NOT apply to How-To Q&A articles — a topic-descriptive title, a "How to..." title, or a question-form title are all valid for Q&A; none is a gerund violation, and the interrogative form doesn't have to live in the title (it can appear in `## Question` instead).
+- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types.
 - **Raw log line or error dump as title.** Titles like `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified in HubDetails.xml at ...` — literal log lines with level tokens (FATAL, ERROR), stack noise, file paths, or truncation fragments — are unreadable and unsearchable. Normalize to the pattern `<Component> Error - <core diagnostic phrase>`, keeping only the searchable message.
   - Examples of the fix:
     - `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified` → `ConfigurationLoader Error - Hub Location Details Have Not Been Specified`
     - `TraceLogger ERROR System.Net.Sockets.SocketException Address already in use` → `TraceLogger Error - Address Already in Use`
     - `RemotePlatformDiscovery Could not get credentials from ...` → `Remote Platform Discovery Error - Could Not Get Credentials`
-  - This rule and the `Error:` *prefix* convention (required for Resolution (Error) titles generally — see `kb_style_guide.md` and `.claude/skills/derek/SKILL.md` §3) are distinct, and this one wins when both could apply: a title normalized to this `<Component> Error - <phrase>` pattern is **exempt** from the `Error:` prefix requirement. The inline `Error` word already disambiguates the title as an error article; prefixing `Error:` in front of a component name would be redundant, and none of the worked examples above use it.
-  - **This is one instance of a broader exemption, not the only one:** `kb_style_guide.md` exempts *any* Resolution (Error) title where the error message itself already contains the word "error" — not just titles normalized from a raw log dump. Titles like `Agents Have Become Unresponsive Error` or `Directory Name Is Invalid Error` are correct as written; do not flag them for missing `Error:`. Only flag a Resolution (Error) title for missing the prefix when it has none of: the `Error:` prefix, the word "error" anywhere in it, or this normalized log-dump form.
+  - **`Error:` prefix exemptions — two, not one.** A Resolution (Error) title is exempt from the `Error:` prefix requirement when EITHER: (a) the error message itself already contains the word "error" (e.g. `Agents Have Become Unresponsive Error`, `Directory Name Is Invalid Error`) — the broader, more common case; or (b) it's normalized to this `<Component> Error - <phrase>` log-dump form — the inline `Error` word already disambiguates the title, so don't also prepend `Error:`. Only flag a Resolution (Error) title for missing the prefix when it has none of: the prefix, the word "error" anywhere in it, or the normalized log-dump form.
+- **H1 / `sidebar_label` consistency:** `sidebar_label` must not be truncated vs. `title`.
+
+These changes are low-ambiguity and preserve reader recognition — the article is still "the one about X," just with corrected surface form. Apply them per the normal fix loop.
+
+### Semantic reframes — soft reminders / judgment calls (author/reviewer decides, never auto-apply)
+
+- **Product name in title** (e.g., "Antivirus Exclusions for Netwrix Data Classification" → drop "for Netwrix Data Classification"). If a product component name (client, agent, add-on) is essential to distinguishing the article from others about the same product, flag it as a judgment call rather than a required fix.
+- **Article-type / title mismatch** (e.g., Symptom Resolution structured article with a procedural-sounding title).
+
+These changes alter what the article appears to be *about* from the reader's perspective. They can break recognition for users searching by remembered title. The file path doesn't change so bookmarks survive, but readers don't navigate by URL — they navigate by name. For every semantic reframe finding: flag the specific issue, suggest one or more alternative titles with reasoning (multiple options are welcome), and defer to the author/reviewer — don't auto-apply, and don't argue if they leave the title alone. Established titles often carry recognition weight that style purity doesn't outweigh. This applies equally to new article drafts and updates to existing articles.
+
+## 13. Frontmatter
+
+All KB articles must begin with a frontmatter block. Check that all required fields are present and valid:
+
+| Field | What to check |
+|---|---|
+| `title` | Present; quoted if it contains colons or special characters; must match the H1 heading exactly |
+| `description` | Present, non-empty, 1–2 sentences; SEO-friendly; accurately summarizes what the article covers. Flag if empty, too vague, or a verbatim copy of the title. |
+| `sidebar_label` | Present, non-empty; must not be truncated vs. `title` |
+| `keywords` | Present, contains 8–12 items — specific and searchable (error codes, product names, technical terms, phrases a customer would type into a search bar), not generic or a verbatim repeat of the title. If a keyword doesn't appear in the article body but is a plausible customer search term, note it as a low-priority observation rather than a required fix. |
+| `products` | Present, contains at least one product ID from the canonical list in `src/config/products.js` — no hyphens or underscores as word separators (`dataclassification`, `directorymanager`, `threatmanager` are correct; `data-classification`, `directory-manager`, `threat-manager` are not) |
+| `tags` | Present and includes `kb` |
+| `knowledge_article_id` | See policy below |
+
+**Product ID carve-outs.** Three values are exceptions to the strict-match rule:
+
+- `onesecure` (5 files) has a real target — flag and correct to `1secure`, the actual `products.js` ID. This is a normal typo/legacy-value correction, not a carve-out.
+- `general` (44 files under `docs/kb/general/`) has no valid `products.js` target — cross-product content with no corresponding product. Never flag.
+- `recoveryad` (1 file) has no single valid target — `scripts/copy-kb-to-versions.mjs` maps both `recoveryforactivedirectory` and `identityrecovery` to this KB folder, so there are two equally defensible IDs and no way to pick one mechanically. Never flag; ask which product the article is actually about instead of guessing.
+
+Product ID hyphenation is otherwise real migration debt: ~300 files across `directory-manager`/`access-analyzer`/`data-classification` still use the non-canonical hyphenated form. The strict `products.js`-exact rule stands; this is tracked as debt, not a reason to loosen the rule.
+
+**`knowledge_article_id` policy — presence/absence is informational, format is corrective.** The field's presence or absence is never a finding — never propose adding or removing the field. Its format, when present and non-empty, is corrective: it must start with `kA` followed by alphanumeric characters.
+
+| State | Finding | Action |
+|-------|---------|--------|
+| Real ID (e.g., `kA04u0000000HuTCAU`) | None | Clean — no finding. |
+| Placeholder (contains `XXXX`, `TODO`, `TBD`, or obvious template markers) | Soft reminder | "Placeholder detected — populate with the real `knowledge_article_id` if applicable, or leave as-is if no ID applies." |
+| Empty string (`knowledge_article_id: ""`) | Soft reminder | "Field is empty — populate if applicable, or leave as-is if no ID applies." |
+| Field missing entirely | Soft reminder | "Field is not present. This is a valid state for a natively authored article — no action needed unless the article originated from an external ticket." |
+| Present, non-empty, not a recognized placeholder, but does not start with `kA` + alphanumeric characters (e.g., `knowledge_article_id: "12345"`) | **Required fix** | "`knowledge_article_id` doesn't match the expected Salesforce/Zendesk ID format (`kA` + alphanumeric). Correct it to the real ID, or clear it to an empty string — this value can't be a valid ID as written." |
+
+**Never propose removing the field when it exists** — its presence preserves the provenance signal (this article expects an external ID). Correcting a malformed value to an empty string is not removing the field — it stays present, just empty, which is itself a valid no-action state. **Never propose adding the field when missing** — the article may be natively authored and may not need one.
+
+Whether the field exists at all is the author's call; the skill only surfaces that. Whether an existing, non-empty value is a well-formed ID is not a judgment call — a value that can't be a real Salesforce/Zendesk ID gets flagged like any other format violation.
+
+## 14. Article Type Identification
+
+Determine the article type from its structure first — this is authoritative and doesn't depend on title phrasing, which Q&A articles are explicitly allowed to leave non-interrogative (see §12). **Partial matches still count** — an article missing one of a type's required headings is that type with a missing heading, not a different type. Requiring *all* headings before classifying would send a Q&A article that's simply missing `## Answer` down the title-fallback path instead, misclassifying it and demanding an unrelated Symptom/Cause/Resolution structure it was never meant to have.
+
+**Check Resolution first, before Q&A or Instructions.** Resolution articles routinely carry an `## Overview` heading alongside Symptom/Cause/Resolution, but How-To articles never carry `## Symptom` — so checking Q&A/Instructions first would let that incidental `## Overview` hijack the classification of a real Resolution article (confirmed against real KB files: an Overview+Symptom+Cause+Resolution article would otherwise misclassify as How-To (Instructions) and get told to add an unnecessary `## Instructions` section). Check in this order (first match wins). **This ordering is load-bearing, not arbitrary — do not reorder it.**
+
+- Contains a Symptom heading (`## Symptom` or `## Symptoms`), a Cause heading (`## Cause` or `## Causes`), or a Resolution heading (`## Resolution` or `## Resolutions`) — any one is enough → **Resolution**. §15 flags whichever of the three is missing. Flag any plural spelling as a rename per §15 — the plural form still counts as a structural match here; it just also gets a §15 finding.
+  - **Error vs. Symptom is decided by content, not title** — this is what breaks the circularity of checking the title against a classification that was itself derived from the title. If the Symptom section names a specific, identifiable error code, exception, or literal error message (commonly introduced by phrasing like "you receive the following error:" and often shown in a code block) → **Resolution (Error)**. Otherwise → **Resolution (Symptom)**.
+  - Having classified by content, *then* check the title against §12 — flag a Required fix only when the title has none of: the `Error:` prefix, the word "error" anywhere in it, or the normalized log-dump form. This is the check that a title-based classifier can never make, because it would always find the classification and the check in agreement by construction.
+- Contains `## Overview` or `## Instructions` (or both) → **How-To (Instructions)**. Same partial-match tolerance.
+- Contains `## Question` or `## Answer` (or both) → **How-To (Q&A)**. If only one is present, §15 flags the other as missing — don't fall through to a different classification.
+
+If none of these section structures are present, fall back to the title:
+
+- Title starts with `Error:` → **Resolution (Error)**
+- Title starts with a gerund (verb ending in -ing, e.g., "Configuring...", "Modifying...") → **How-To (Instructions)**
+- Title is a question or starts with "How to" → **How-To (Q&A)**
+- Everything else → **Resolution (Symptom)**
+
+## 15. Article Structure
+
+Check that the required H2 headings are present for the identified article type (§14):
+
+| Type | Required headings |
+|---|---|
+| Resolution (Error or Symptom) | `## Symptom`, `## Cause`, `## Resolution` — always singular, even when the section describes multiple items |
+| How-To (Instructions) | `## Overview`, `## Instructions` |
+| How-To (Q&A) | `## Question`, `## Answer` |
+
+When a required heading is missing, include the full expected heading template so the writer can copy it in.
+
+**Pluralized form present (`## Symptoms`, `## Causes`, or `## Resolutions`)** is a distinct case from missing — the section exists, it just uses the wrong label. Flag it as "rename `## Symptoms` to `## Symptom`" (singular; even when the section describes multiple items), not as a missing heading — do not tell the writer to add a section that already exists under the plural name. Applies to both Resolution formats (Error and Symptom). ~171 files currently use a plural form (105 `## Causes`, 97 `## Resolutions`, 96 `## Symptoms`); this is accepted migration debt, not a reason to loosen the rule.
+
+**How-To structure check.** How-To articles must use either Instructions form (`## Overview` + `## Instructions`) or Q&A form (`## Question` + `## Answer`). Articles with H1 + body prose but no recognized section structure are a Required structural fix — suggest Instructions form for procedural content or Q&A form for single-answer content. If the prose is missing procedural steps, flag that gap as a content decision (kb-writer territory) rather than auto-generating steps.
+
+**Wrong-shape check.** Even when the article DOES have a recognized structure, verify the shape fits the content. Q&A form is for simple procedures with one procedure and minimal caveat content. An article using Q&A form that actually contains two or more distinct procedures, multi-step workflows, or substantial caveat/note content is a Required structural fix — restructure to `## Overview` + `## Instructions` with H3 subheadings per procedure. Ideally this decision is caught by `kb-writer` before reaching a review skill; apply it here if it arrives unresolved.
+
+**Q&A question format.** In Q&A articles, content under `## Question` (and interrogative sub-headings in FAQ-style articles) must be a complete interrogative sentence — starts with an interrogative word (How do you / How can you / How should you / How will you / Can you / Should you / What / When / Where / Why / Which / Who / Does / Is / Are) and ends with `?`. Use second person ("you"), not first person ("I"), per `kb_style_guide.md`. "How to..." patterns (e.g., "How to export X?") are Required fixes — rewrite as "How do you export X?" or "Can you X?" as appropriate. Mark N/A if the article isn't Q&A form.
+
+**Resolution Option Structure.** When the `## Resolution` section contains multiple options labeled as inline text — e.g., `Option 1:`, `Option 2:` — flag it and tell the writer to convert them to `### Option 1` and `### Option 2` H3 subheadings for scannability.
+
+## 16. Images
+
+- **Location.** KB images must be stored in a `0-images/` folder at the **product level** (`docs/kb/<product>/0-images/`), not inside category subfolders. Articles in category subfolders reference them with `../0-images/filename.<ext>`. Flag any `0-images/` folder created inside a category subfolder rather than at the product level. PNG, WebP, JPG, and JPEG are all in active use and all valid — do not flag file format.
+- **External references.** Flag any images linked from external sources (for example, GitHub CDN `https://github.com/user-attachments/assets/...`) — these must be downloaded and committed to the repo.
+- **Alt text.** Must be descriptive, not just the filename. Flag any image where the alt text is only the raw filename (e.g., `![index_files_location.png](path)`) — rewrite as a short description of what the image shows, per `kb_style_guide.md`'s Screenshots section.
diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index f5c5f32d35..b6930a551e 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -6,7 +6,7 @@ argument-hint: "[docs/kb/path/to/article.md]"
 
 # Overview
 
-You are Derek, a KB article quality reviewer for Netwrix. Your job is to review KB articles against `kb_style_guide.md` and flag issues that Vale and Dale do not catch.
+You are Derek, a KB article quality reviewer for Netwrix. Your job is to review KB articles against the canonical rulebook and flag issues that Vale and Dale do not catch.
 
 **What Vale already handles — do not re-flag these:**
 - Contractions (`NetwrixKB.Contractions`)
@@ -29,110 +29,37 @@ Derek focuses on what's left: frontmatter validity, article type and structure,
 
 # How to Review
 
-1. Read `kb_style_guide.md` from the repo root.
-2. Read the article at `$1`. Always read the file directly from disk — do not use any version of this file that may be in context from earlier in the session.
-3. Identify the article type (see below).
-4. Work through each review area.
-5. Output the assessment line and table.
-
-# Article Type Identification
-
-Determine the article type from its structure first — this is authoritative and doesn't depend on title phrasing, which Q&A articles are explicitly allowed to leave non-interrogative (see §3). **Partial matches still count** — an article missing one of a type's required headings is that type with a missing heading, not a different type. Requiring *all* headings before classifying would send a Q&A article that's simply missing `## Answer` down the title-fallback path instead, misclassifying it and demanding an unrelated Symptom/Cause/Resolution structure it was never meant to have.
-
-**Check Resolution first, before Q&A or Instructions.** Resolution articles routinely carry an `## Overview` heading alongside Symptom/Cause/Resolution, but How-To articles never carry `## Symptom` — so checking Q&A/Instructions first would let that incidental `## Overview` hijack the classification of a real Resolution article (confirmed against real KB files: an Overview+Symptom+Cause+Resolution article would otherwise misclassify as How-To (Instructions) and get told to add an unnecessary `## Instructions` section). Check in this order (first match wins):
-
-- Contains a Symptom heading (`## Symptom` or `## Symptoms`), a Cause heading (`## Cause` or `## Causes`), or a Resolution heading (`## Resolution` or `## Resolutions`) — any one is enough → **Resolution**. §2 flags whichever of the three is missing. Flag any plural spelling as a rename per §2 — the plural form still counts as a structural match here; it just also gets a §2 finding.
-  - **Error vs. Symptom is decided by content, not title** — this is what breaks the circularity of checking the title against a classification that was itself derived from the title. If the Symptom section names a specific, identifiable error code, exception, or literal error message (commonly introduced by phrasing like "you receive the following error:" and often shown in a code block) → **Resolution (Error)**. Otherwise → **Resolution (Symptom)**.
-  - Having classified by content, *then* check the title against §3: flag a Required fix only when the title has none of — the `Error:` prefix, the word "error" anywhere in it (`kb_style_guide.md`'s own exemption), or the normalized `<Component> Error - <phrase>` log-dump form (rulebook §12). This is the check that a title-based classifier can never make, because it would always find the classification and the check in agreement by construction.
-- Contains `## Overview` or `## Instructions` (or both) → **How-To (Instructions)**. Same partial-match tolerance.
-- Contains `## Question` or `## Answer` (or both) → **How-To (Q&A)**. If only one is present, §2 flags the other as missing — don't fall through to a different classification.
-
-If none of these section structures are present, fall back to the title:
-
-- Title starts with `Error:` → **Resolution (Error)**
-- Title starts with a gerund (verb ending in -ing, e.g., "Configuring...", "Modifying...") → **How-To (Instructions)**
-- Title is a question or starts with "How to" → **How-To (Q&A)**
-- Everything else → **Resolution (Symptom)**
+1. Read `.claude/references/kb-editing-conventions.md` from the repo root — this is the canonical rulebook. Read it before every batch, because it evolves per batch. Do not duplicate its content from memory.
+2. Read `kb_style_guide.md` from the repo root for product-name usage and any area not covered by the rulebook.
+3. Read the article at `$1`. Always read the file directly from disk — do not use any version of this file that may be in context from earlier in the session.
+4. Identify the article type per rulebook §14.
+5. Work through each review area below.
+6. Output the assessment line and table.
 
 # Review Areas
 
-## 1. Frontmatter
+Read the named rulebook section before applying each area — do not hard-code rules that may drift from the rulebook.
 
-Check that all required fields are present and valid:
-
-| Field | What to check |
+| Area | Rulebook section |
 |---|---|
-| `title` | Present; quoted if it contains colons or special characters |
-| `description` | Present, non-empty, 1–2 sentences |
-| `sidebar_label` | Present, non-empty |
-| `keywords` | Present, contains 8–12 items |
-| `products` | Present, contains at least one product ID |
-| `tags` | Present and includes `kb` |
-| `knowledge_article_id` | If present and non-empty, it must start with `kA` followed by alphanumeric characters. If present but empty (`""`), output a soft reminder (see note below) — do not count it as an issue or add it to the issue count. If absent, do not flag. |
-
-**Soft reminder for empty `knowledge_article_id`:** After the table (or after "Derek found no issues"), add one line: `> **Note:** \`knowledge_article_id\` is blank. If this article originated from a Salesforce or Zendesk ticket, add the Knowledge Article ID here.` Do not add this to the issue count or the table.
-
-Flag each missing or invalid field as a separate row in the output table.
-
-## 2. Article Structure
-
-Check that the required H2 headings are present for the identified article type:
-
-| Type | Required headings |
-|---|---|
-| Resolution (Error or Symptom) | `## Symptom`, `## Cause`, `## Resolution` — always singular, even when the section describes multiple items |
-| How-To (Instructions) | `## Overview`, `## Instructions` |
-| How-To (Q&A) | `## Question`, `## Answer` |
-
-When a required heading is missing, include the full expected heading template in the Message column so the writer can copy it in.
-
-**Pluralized form present (`## Symptoms`, `## Causes`, or `## Resolutions`)** is a distinct case from missing — the section exists, it just uses the wrong label. Flag it as "rename `## Symptoms` to `## Symptom`" (singular; even when the section describes multiple items), not as a missing heading — do not tell the writer to add a section that already exists under the plural name.
+| Frontmatter (all required fields, product ID carve-outs, `knowledge_article_id` policy) | §13 Frontmatter |
+| Article type identification | §14 Article Type Identification |
+| Article structure (required headings, pluralization, wrong-shape check, Q&A format, Resolution Option Structure) | §15 Article Structure |
+| Title format (mechanical + semantic) | §12 Titles |
+| Callout/admonition format | §5 Callout severity |
+| Links | §8 Links |
+| Bolding, inline code, path formatting | §6 Bolding and inline code |
+| Images | §16 Images |
 
-## 3. Title Format
+## Product Names
 
-Check that the title matches the expected format for the article type:
-
-- **Resolution (Error):** starts with `Error:` followed by the unique error code or message. **Exceptions (per `kb_style_guide.md`):** (1) if the error message itself already contains the word "error" (e.g. `Agents Have Become Unresponsive Error`, `Directory Name Is Invalid Error`), don't add the `Error:` prefix — this is the broader, more common case; (2) a title already normalized from a raw log dump per the log-line/error-dump rule (`<Component> Error - <core diagnostic phrase>`, rulebook §12) is also exempt — the inline `Error` word already disambiguates it. Only flag the *absence* of `Error:` when the title has none of: the prefix, the word "error" anywhere in it, or this normalized log-dump form.
-- **How-To (Instructions):** starts with a gerund — not "How to", no question mark
-- **How-To (Q&A):** not required to use gerund/action form. A topic-descriptive title, a "How to..." title, or a question-form title are all valid — do not flag any of them as missing a gerund. The interrogative form doesn't have to live in the title; it can instead appear in `## Question` itself.
-- **Resolution (Symptom):** `[Feature or Component] [Symptom] [Optional: Context]` — descriptive, not vague (e.g., "AD not working" is too vague)
-
-Also check: title must not contain a product name — product names belong in the `products` frontmatter field.
-
-## 4. Product Names
-
-Check that Netwrix product names follow the correct pattern from `kb_style_guide.md`:
+Check that Netwrix product names follow the correct pattern from `kb_style_guide.md`'s Product Names section:
 
 - First mention in body text: full product name (e.g., "Netwrix Auditor")
 - All subsequent mentions: short product name (e.g., "Auditor")
 - No unapproved abbreviations (e.g., "NA" for Netwrix Auditor)
 
-## 5. Path Formatting
-
-Registry paths, file paths, and directory paths in the article body must be wrapped in backticks (inline code) or a fenced code block. Flag any plain-text path that is not formatted as code.
-
-Patterns to look for:
-- Registry paths starting with `HKEY_`, `Computer\`, or `HKLM\`
-- Windows file paths containing `C:\`, `\\`, or multiple backslash-separated segments
-- Unix/Linux paths with multiple forward-slash segments (e.g., `/etc/netwrix/...`)
-
-## 6. Resolution Option Structure
-
-When the `## Resolution` section contains multiple options labeled as inline text — e.g., `Option 1:`, `Option 2:` — flag it and tell the writer to convert them to `### Option 1` and `### Option 2` H3 subheadings for scannability.
-
-## 7. Admonition Format
-
-KB articles use blockquote callouts, not Docusaurus admonition syntax — and only two blockquote severities exist: `NOTE` and `IMPORTANT`. This applies regardless of whether the callout is currently Docusaurus syntax or already a blockquote with the wrong severity label — flag both:
-
-- Any `:::note`, `:::tip`, `:::info`, `:::warning`, `:::caution`, `:::danger`, or `:::important` block (Docusaurus syntax, not yet a blockquote).
-- Any `> **<SEVERITY>:**` blockquote whose severity is not `NOTE` or `IMPORTANT` — for example `> **TIP:**`, `> **WARNING:**`, `> **CAUTION:**`, `> **DANGER:**`, `> **INFO:**`. It's already a blockquote; only the severity label is wrong.
-
-Tell the writer to convert/relabel to one of the two severities, per this mapping (covers both the `:::` and blockquote spellings of each severity):
-
-- `:::note` / `> **NOTE:**`, `:::tip` / `> **TIP:**`, `:::info` / `> **INFO:**` → `> **NOTE:**` — for supplementary information
-- `:::warning` / `> **WARNING:**`, `:::caution` / `> **CAUTION:**`, `:::danger` / `> **DANGER:**`, `:::important` → `> **IMPORTANT:**` — for critical information that could cause issues if ignored
-
-## 8. Keywords and Description Quality
+## Keywords and Description Quality
 
 **Keywords:** The 8–12 keywords should be specific and searchable — error codes, product names, technical terms, and phrases a customer would type into a search bar. Flag if keywords are too generic, simply repeat the title, or are missing obvious terms visible in the article body.
 
@@ -154,6 +81,8 @@ Then print the markdown table. Every issue must be a row in this table — no ex
 
 If no issues are found, print the assessment line followed by "Derek found no issues." Do not print an empty table.
 
+**Soft reminders** (e.g., an empty `knowledge_article_id` per rulebook §13) print as a separate note after the table, not as a row, and do not count toward the issue total: `> **Note:** \`knowledge_article_id\` is blank. If this article originated from a Salesforce or Zendesk ticket, add the Knowledge Article ID here.`
+
 **Consolidating structure violations:** When multiple required headings are missing for the same article type, use a single `structure-article-type` row. List all missing headings in the Message column. If fixing the title would change the article type and resolve the structure issue automatically, note that in the Message.
 
 **Line number guidance:**
diff --git a/.claude/skills/kb-pr-open/SKILL.md b/.claude/skills/kb-pr-open/SKILL.md
index e58f69dab1..cb9d64a3da 100644
--- a/.claude/skills/kb-pr-open/SKILL.md
+++ b/.claude/skills/kb-pr-open/SKILL.md
@@ -66,31 +66,29 @@ If Vale is not installed or returns an error, note this in the report and contin
 
 - **`NetwrixKB.HeadingCase` on version designators:** Lowercase `v` in version designators (e.g., `v2.8`, `v5.7`, `v2.8+`) is correct title case per Chicago-style convention. When Vale's heading-case rule fires on a heading whose only "violation" is a lowercase `v` followed by digits, treat it as a false positive — note it in the Vale findings table with severity "False positive (no action)" and do NOT propose a rewrite.
 
-**`WeakLinkText` fixes require a search, not just a rewrite.** Before proposing any fix for a Vale `WeakLinkText` finding, grep `docs/kb/**/*.md` and `docs/<product>/<version>/**/*.md` for a plausible real target based on the referenced topic (e.g., "Accounts and Required Permissions" → search for `accountreqs`, `account.*permission`). If a real target resolves, convert the prose into a proper link to it. Only rewrite the sentence to remove the implied reference if the search turns up nothing. Do not skip the search because the phrasing already implies no real link exists — the trigger already fired precisely because the phrasing looks like an implied reference, and the target often does exist on disk.
-
-`BoilerplateCrossRef` is not part of `NetwrixKB` (it lives only in `.vale/styles/Netwrix/`), so it never fires on `docs/kb/` files under this skill's scope — do not treat a `BoilerplateCrossRef` finding as real if one somehow appears; verify the file's actual style scope first.
+**`WeakLinkText` and `BoilerplateCrossRef` findings** — see rulebook §8 Links: `WeakLinkText` fixes require a real-target search before rewriting, and `BoilerplateCrossRef` never fires on `docs/kb/` files under this skill's scope — do not treat it as real if one somehow appears.
 
 **Dale** — apply the Dale rules in `.claude/skills/dale/rules/*.yml` semantically (passive voice, minimizing-difficulty words, idioms, wordiness, undefined acronyms, and the rest). Do not re-implement them from memory — read the rule files.
 
-**Derek** — read `kb_style_guide.md` from the repo root. Read the full article content and perform a holistic KB writing quality review across these areas:
-
-| Area | What to check |
-|------|--------------|
-| **frontmatter** | All required fields present and valid: `title`, `description`, `sidebar_label`, `keywords` (8–12 items), `products` (must use the canonical product ID from `src/config/products.js` — no hyphens or underscores as word separators; `dataclassification`, `directorymanager`, `threatmanager` are correct; `data-classification`, `data_classification`, `directory-manager`, `threat-manager` are not), `tags` (must include `kb`), `knowledge_article_id` (see knowledge_article_id rules in Step 4 — its state is informational only; never propose adding, removing, or rewriting it). `sidebar_label` must not be truncated vs. `title`. **`onesecure` has a real target and should be corrected:** flag it as a Required fix and propose `1secure` (the actual `products.js` ID) — this is a normal typo/legacy-value correction, not a carve-out case. **Two values have no valid `products.js` target at all — do not flag these as Required fixes, there is no correct replacement to propose:** `general` (44 files under `docs/kb/general/` — cross-product content with no corresponding product) and `recoveryad` (1 file — genuinely ambiguous: `scripts/copy-kb-to-versions.mjs` maps both `recoveryforactivedirectory` and `identityrecovery` to the `recoveryad` KB folder, so there are two equally defensible canonical IDs and no way to pick one mechanically; ask the TSE which product the article is actually about instead of guessing). |
-| **article-type: structure** | Identify the article type (How-To Q&A, How-To Instructions, Resolution Error, Resolution Symptom). Verify the structure matches the type. **How-To structure:** How-To articles must use either Instructions form (`## Overview` + `## Instructions`) or Q&A form (`## Question` + `## Answer`). Articles with H1 + body prose but no recognized section structure are a Required structural fix — suggest Instructions form for procedural content or Q&A form for single-answer content; if the prose is missing procedural steps, flag that gap as a TSE-content-decision (kb-writer territory) rather than auto-generating steps. **Wrong-shape check (kb-writer feedback surfaced late):** even when the article DOES have a recognized structure, verify the shape fits the content. Q&A form is for simple procedures with one procedure and minimal caveat content. An article using Q&A form that actually contains two or more distinct procedures, multi-step workflows, or substantial caveat/note content should be flagged as a Required structural fix — restructure to `## Overview` + `## Instructions` with H3 subheadings per procedure. Ideally this decision is caught by `kb-writer` before reaching this skill; if it arrives here unresolved, apply it. |
-| **article-type: qa-format** | **Q&A question format:** In Q&A articles, content under `## Question` (and interrogative sub-headings in FAQ-style articles) must be a complete interrogative sentence — starts with an interrogative word (How do you / How can you / How should you / How will you / Can you / Should you / What / When / Where / Why / Which / Who / Does / Is / Are) and ends with `?`. Use **second person ("you"), not first person ("I")**, per the kb_style_guide.md ("Use second person ('you') when addressing the reader"). "How to..." patterns (e.g., "How to export X?") are Required fixes — rewrite as "How do you export X?" or "Can you X?" as appropriate. Mark N/A if the article isn't Q&A form. |
-| **article-type: heading-labels** | **Resolution section heading pluralization:** Section headings in Resolution articles — both Error and Symptom formats — are always singular: `## Symptom`, `## Cause`, `## Resolution` — even when the section contains multiple items. Flag `## Symptoms`, `## Causes`, `## Resolutions` as Required fixes. |
-| **title: mechanical** | See "Title-format rules — two categories" below. Required fixes, apply on TSE approval, low ambiguity: gerund-form titles for How-To Instructions articles, title case correction, raw log-line/error-dump title normalization (rulebook §12), and the H1/`sidebar_label`-consistency check (`sidebar_label` must not be truncated vs. `title`). |
-| **title: semantic** | See "Title-format rules — two categories" below. Soft reminders / judgment calls — surface with suggested alternatives and reasoning, never auto-apply: product-name-in-title and article-type/title mismatch. |
-| **product-names** | Check that product names and IDs match the Product Long and Short Names table in the style guide. Flag incorrect abbreviations (NDC, NPS, NTA, etc.) and wrong `products` field values (for example, hyphens vs. underscores). |
-| **keywords-quality** | Keywords should be specific and drawn from the article content — error codes, feature names, product names, common customer search terms. Flag if fewer than 8, if they are generic, or if important terms from the article are missing. If a keyword does not appear in the article body but could be a reasonable customer search term for the topic, note it as a low-priority observation rather than a required fix. |
-| **images: location** | Check how images are referenced. KB images must be stored in a `0-images/` folder at the **product level** (`docs/kb/<product>/0-images/`), not inside category subfolders. PNG, WebP, JPG, and JPEG are all in active use and all valid — do not flag file format. Articles in category subfolders reference them with `../0-images/filename.<ext>`. Flag any `0-images/` folders created inside category subfolders rather than at the product level. |
-| **images: external-refs** | Flag any images linked from external sources (for example, GitHub CDN `https://github.com/user-attachments/assets/...`) — these must be downloaded and committed to the repo. |
-| **images: alt-text** | Alt text must be descriptive, not just the filename. Flag any image where the alt text is only the raw filename (e.g., `![index_files_location.png](path)`) — rewrite as a short description of what the image shows, per `kb_style_guide.md` Screenshots section. |
-| **links** | Find every internal markdown link in the article body — `[text](/docs/...)` (the dominant form, ~218 KB files) and `[text](pathname:///docs/...)` patterns to other KB articles and to versioned product docs, **and** relative `.md` links (`[text](../other-article.md)`, `[text](./other-article.md)`) — `kb_style_guide.md`'s own "Do" example for internal links uses the relative-`.md` form, and it's in active use (roughly a dozen KB files). All three forms are valid; do not propose converting one to another. For each, resolve the actual target file on disk: check for a `slug` frontmatter override on the target first; if none, the URL segment (or relative path) must match the target's real path/filename (not its `sidebar_label` or `title`). `pathname://` links specifically must use underscore version segments (`8_2`, not `8.2`) and resolve to a real file, per rulebook §8 — flag a dotted version segment as a Required fix even if the rest of the path resolves. This is a constraint on `pathname://` links where they're used, not a requirement to use that form over the bare `/docs/...` form. Flag any link whose URL does not resolve to a real file on disk as a Required fix, and correct it to the real path. Only genuinely external links (`http://`, `https://`, `mailto:`, etc.) are out of scope for this check. Backstop is `npm run build` — but `onBrokenLinks`/`onBrokenMarkdownLinks`/`onBrokenAnchors` in `docusaurus.config.js` only throw on a full build; a single-product build (`DOCS_PRODUCT=...`, the faster path `CLAUDE.md` recommends) relaxes all three to `warn`, so a broken link there won't fail the build. Either way, this check catches broken links before submission rather than relying on the backstop. |
-| **formatting: bold/backticks** | Registry paths, registry value names, registry data, error codes (e.g., `0x80070005`, `0x80004005`), commands, and executable names use inline code (backticks). UI element names (button labels, menu items, field names) use **bold** only when they are action targets in the current step (buttons being clicked, fields being filled, dropdowns being selected, menu items being chosen) — a UI element mentioned as context only (not acted on in this step) does not get bold. Flag bolded UI elements that are not action targets as Required fixes. ✓ "Click **Save**." ✓ "Select **PDF** from the **Save as type** dropdown." ✗ "The file appears under the Save as type column." — no bold on contextual reference. |
-| **formatting: lists** | Sequential procedures must be numbered lists, not prose — this applies to Resolution sections and any sub-sections within them (e.g., verification steps), not just top-level procedures. Multi-line commands and command output should use fenced code blocks. |
-| **prose-directness** | Flag sentences where an impersonal subject ("the operation", "the process", "the system") performs an action that the actual actor or action could express more directly. Example: "the operation fails with an error" → "Clicking X fails with an error". Apply judgment — not every impersonal subject is wrong, but flag cases where a direct rewrite is clearly cleaner. |
+**Derek** — read `.claude/references/kb-editing-conventions.md` from the repo root before every batch, because it evolves per batch. Read the full article content and perform a holistic KB writing quality review across these areas, reading the named rulebook section for each — do not hard-code rules that may drift:
+
+| Area | Rulebook section |
+|------|-------------------|
+| **frontmatter** | §13 Frontmatter (all required fields, product ID carve-outs, `knowledge_article_id` policy) |
+| **article-type: structure** | §14 Article Type Identification + §15 Article Structure (How-To structure check, wrong-shape check) |
+| **article-type: qa-format** | §15 Article Structure (Q&A question format) |
+| **article-type: heading-labels** | §15 Article Structure (pluralization) |
+| **title: mechanical** | §12 Titles (mechanical style corrections) |
+| **title: semantic** | §12 Titles (semantic reframes) |
+| **product-names** | `kb_style_guide.md` Product Names table. Flag incorrect abbreviations (NDC, NPS, NTA, etc.) and wrong `products` field values (for example, hyphens vs. underscores) per rulebook §13. |
+| **keywords-quality** | §13 Frontmatter (`keywords` row) |
+| **images: location** | §16 Images |
+| **images: external-refs** | §16 Images |
+| **images: alt-text** | §16 Images |
+| **links** | §8 Links |
+| **formatting: bold/backticks** | §6 Bolding and inline code |
+| **formatting: lists** | §3 List type |
+| **prose-directness** | §4 Sentence-level rules (impersonal-subject directness) |
 
 > **Multi-file coverage mandate:** For every file passed to the skill — including each individual file in a multi-file invocation — run the full Derek frontmatter sweep across all areas: `tags`, `products`, `keywords`, `sidebar_label`, `title`/title-format, and `knowledge_article_id`, plus `images` and `links`. Do not abbreviate or skip any area. If the same finding applies to multiple files (for example, all files have the same wrong `products` value), still list it under each file individually in the report — do not consolidate. A partial sweep on any single file is a coverage gap and causes downstream rework.
 
@@ -128,7 +126,7 @@ Run this scan on every file in addition to the Derek areas table above. Each ite
 | 20 | A list that appears with no lead-in sentence, reading disjointed from surrounding prose | Add a short intro sentence ending in a colon. Route to `kb-writer` when the intro needs content judgment; apply here when the missing context is obvious from the surrounding prose. Rulebook §4. |
 | 21 | A paragraph with 3+ inline cross-reference clauses ("see X, see Y, see Z") stacked in one sentence | Collapse into a single NOTE block with the links listed cleanly (compact enumeration or short bulleted list under the NOTE). Rulebook §8. |
 | 22 | A positional reference ("above"/"below"/"the section on X") that points to a named section in the same file | Replace with `[Section Name](#section-slug)` rather than rewording the positional term away. This is the concrete execution of Dale's `positional-references` suggestion. Rulebook §4. |
-| 23 | Either (a) `:::note` / `:::tip` / `:::info` / `:::warning` / `:::caution` / `:::danger` / `:::important` Docusaurus admonition syntax anywhere in the article body, **or** (b) a `> **<SEVERITY>:**` blockquote whose severity is not `NOTE` or `IMPORTANT` (e.g. `> **TIP:**`, `> **WARNING:**`, `> **CAUTION:**`, `> **DANGER:**`, `> **INFO:**`) — a callout can already be in blockquote form and still have the wrong severity label | KB articles use the blockquote callout format — only two severities exist, `NOTE` and `IMPORTANT` — not Docusaurus `:::` admonitions, and not any other blockquote severity label, per `.claude/skills/derek/SKILL.md` §7 (Admonition Format). Map `:::note`/`> **TIP:**`/`> **INFO:**`/etc. → `> **NOTE:**` and `:::warning`/`:::caution`/`> **DANGER:**`/`> **CAUTION:**`/etc. → `> **IMPORTANT:**`. If the callout sits inside a numbered list item, apply row 1's 4-space indentation rule to the converted/relabeled blockquote. |
+| 23 | Either (a) `:::note` / `:::tip` / `:::info` / `:::warning` / `:::caution` / `:::danger` / `:::important` Docusaurus admonition syntax anywhere in the article body, **or** (b) a `> **<SEVERITY>:**` blockquote whose severity is not `NOTE` or `IMPORTANT` (e.g. `> **TIP:**`, `> **WARNING:**`, `> **CAUTION:**`, `> **DANGER:**`, `> **INFO:**`) — a callout can already be in blockquote form and still have the wrong severity label | KB articles use the blockquote callout format — only two severities exist, `NOTE` and `IMPORTANT` — not Docusaurus `:::` admonitions, and not any other blockquote severity label, per rulebook §5 Callout severity. Map `:::note`/`> **TIP:**`/`> **INFO:**`/etc. → `> **NOTE:**` and `:::warning`/`:::caution`/`> **DANGER:**`/`> **CAUTION:**`/etc. → `> **IMPORTANT:**`. If the callout sits inside a numbered list item, apply row 1's 4-space indentation rule to the converted/relabeled blockquote. |
 
 ### Cross-section consistency scan
 
@@ -288,49 +286,9 @@ Do NOT prompt for local testing. Do NOT propose a commit message. Do NOT enter S
 
 If either command returns output — uncommitted changes anywhere in the working tree, or any commit already on the branch ahead of `origin/dev` (for example, content committed by `kb-writer` in an earlier step) — proceed normally to Step 5, even if this skill run applied zero fixes.
 
-### knowledge_article_id rules (flag state, never force change)
-
-The `knowledge_article_id` field's *presence or absence* is informational, not corrective — the skill must never propose adding or removing the field. Its *format*, when present and non-empty, is corrective: it must start with `kA` followed by alphanumeric characters (per `derek/SKILL.md` §1). The four states below are valid, no-action-needed states; the fifth (malformed) is the one exception that gets a Required fix.
-
-| State | Finding | Action |
-|-------|---------|--------|
-| Real ID (e.g., `kA04u0000000HuTCAU`) | None | Clean — no finding. |
-| Placeholder (contains `XXXX`, `TODO`, `TBD`, or obvious template markers) | Soft reminder | "Placeholder detected — populate with the real `knowledge_article_id` if applicable, or leave as-is if no ID applies." |
-| Empty string (`knowledge_article_id: ""`) | Soft reminder | "Field is empty — populate if applicable, or leave as-is if no ID applies." |
-| Field missing entirely | Soft reminder | "Field is not present. This is a valid state for a natively authored article — no action needed unless the article originated from an external ticket." |
-| Present, non-empty, and not a recognized placeholder, but does not start with `kA` followed by alphanumeric characters (e.g., `knowledge_article_id: "12345"`) | **Required fix** | "`knowledge_article_id` doesn't match the expected Salesforce/Zendesk ID format (`kA` + alphanumeric). Correct it to the real ID or clear it — this value can't be a valid ID as written." |
-
-**Never propose removing the field when it exists** — its presence preserves the provenance signal (this article expects an external ID).
-
-**Never propose adding the field when missing** — the article may be natively authored and may not need one.
-
-Reasoning: whether the field exists at all is the TSE's call, and the skill only surfaces that. Whether an existing, non-empty value is a well-formed ID is not a judgment call — a value that can't be a real Salesforce/Zendesk ID gets flagged like any other format violation.
-
-### Title-format rules — two categories
-
-Title findings split into two categories based on whether the change is mechanical or semantic.
-
-**Mechanical style corrections — Required fixes (surface, apply on TSE approval):**
-
-- **gerund-for-How-To-Instructions:** "How to..." prefix → gerund form (e.g., "How to Export Event Logs" → "Exporting Event Logs"). Applies only to How-To Instructions form articles (`## Overview` + `## Instructions` structure). Does NOT apply to How-To Q&A articles — a topic-descriptive title, a "How to..." title, or a question-form title are all valid for Q&A; none is a gerund violation, and the interrogative form doesn't have to live in the title (it can appear in `## Question` instead).
-- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types.
-- **Raw log line / error dump titles** (rulebook §12): titles containing literal log-level tokens (FATAL, ERROR, WARN), stack noise, file paths, or truncation fragments (e.g., `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified in HubDetails.xml at ...`) → normalize to `<Component> Error - <core diagnostic phrase>`, keeping only the searchable message. Examples: `ConfigurationLoader Error - Hub Location Details Have Not Been Specified`; `TraceLogger Error - Address Already in Use`; `Remote Platform Discovery Error - Could Not Get Credentials`. This form is exempt from the `Error:` *prefix* convention required for Resolution (Error) titles generally (`Error: [Unique Error Code/Message]`, per `kb_style_guide.md` and `.claude/skills/derek/SKILL.md` §3) — the inline `Error` word already disambiguates the title, so don't also prepend `Error:`. **This is one of two exemptions, not the only one:** `kb_style_guide.md` also exempts any Resolution (Error) title where the error message itself already contains the word "error" (e.g. `Agents Have Become Unresponsive Error`) — that's the broader, more common case, independent of whether the title is a normalized log dump. A Resolution (Error) title only needs the `Error:` prefix when it has none of: the prefix, the word "error" anywhere in it, or the normalized log-dump form.
-- **H1 / `sidebar_label` consistency:** `sidebar_label` must not be truncated vs. `title`.
-
-These changes are low-ambiguity and preserve reader recognition — the article is still "the one about X," just with corrected surface form. Apply them per the normal fix-loop.
-
-**Semantic reframes — soft reminders / judgment calls (TSE decides, never auto-apply):**
-
-- Product name in title (e.g., "Antivirus Exclusions for Netwrix Data Classification" → drop "for Netwrix Data Classification").
-- Article-type / title mismatch (e.g., Symptom Resolution structured article with a procedural-sounding title).
-
-These changes alter what the article appears to be *about* from the reader's perspective. They can break recognition for users searching by remembered title. The file path doesn't change so bookmarks survive, but readers don't navigate by URL — they navigate by name. For every semantic reframe finding:
-
-1. **Flag the specific issue.**
-2. **Suggest one or more alternative titles** with reasoning. Multiple options are welcome.
-3. **Defer to the TSE.** Don't auto-apply. Don't argue if the TSE leaves the title alone — established titles often carry recognition weight that style purity doesn't outweigh.
+### knowledge_article_id and title-format rules
 
-This applies equally to new article drafts and updates to existing articles. The TSE owns semantic title decisions.
+Both live in `.claude/references/kb-editing-conventions.md` — read §13 Frontmatter for the `knowledge_article_id` policy (presence/absence is informational, format is corrective, never propose adding/removing the field) and §12 Titles for the mechanical/semantic title-format split (gerund rules, title case, log-dump normalization, the two `Error:` prefix exemptions, H1/`sidebar_label` consistency, and the semantic-reframe soft-reminder rules). Apply mechanical fixes per the normal fix loop; semantic reframes are always the TSE's call — flag, suggest alternatives, defer.
 
 ## 5. Local testing
 
diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md
index f85f8197cc..dc956fc116 100644
--- a/.claude/skills/kb-pr-review/SKILL.md
+++ b/.claude/skills/kb-pr-review/SKILL.md
@@ -134,7 +134,7 @@ If Vale is not installed or returns an error, note this in the report and contin
 
 **Known Vale false positive — `NetwrixKB.HeadingCase` on version designators.** Lowercase `v` in version designators (e.g., `v2.8`, `v5.7`, `v2.8+`) is correct title case per Chicago-style convention. When Vale's heading-case rule fires on a heading whose only "violation" is a lowercase `v` followed by digits, treat it as a false positive — note it in the Vale findings table with severity "False positive (no action)" and do NOT propose a rewrite.
 
-**`WeakLinkText` / `BoilerplateCrossRef` fixes require a search, not just a rewrite.** Before proposing any fix for a Vale `WeakLinkText` or `BoilerplateCrossRef` finding, grep `docs/kb/**/*.md` and `docs/<product>/<version>/**/*.md` for a plausible real target based on the referenced topic (e.g., "Accounts and Required Permissions" → search for `accountreqs`, `account.*permission`). If a real target resolves, convert the prose into a proper link to it. Only rewrite the sentence to remove the implied reference if the search turns up nothing. Do not skip the search because the phrasing already implies no real link exists — the trigger already fired precisely because the phrasing looks like an implied reference, and the target often does exist on disk.
+**`WeakLinkText` and `BoilerplateCrossRef` findings** — see rulebook (`.claude/references/kb-editing-conventions.md`) §8 Links: `WeakLinkText` fixes require a real-target search before rewriting, and `BoilerplateCrossRef` never fires on `docs/kb/` files under this skill's scope — do not treat it as real if one somehow appears.
 
 ---
 
@@ -153,77 +153,53 @@ Dale handles: passive voice, vague language, business jargon, idioms, undefined
 
 ### Step 8 — Perform Derek KB quality review on each file
 
-Read `kb_style_guide.md` from the repo root in full before beginning. Then, for each review area below, re-read the named section of the style guide and apply its rules to the article. The style guide is the source of truth — do not substitute your own rules.
+Read `.claude/references/kb-editing-conventions.md` from the repo root in full before beginning — this is the canonical rulebook. Then, for each review area below, re-read the named rulebook section and apply its rules to the article. The rulebook is the source of truth — do not substitute your own rules.
 
 For each file in `KB_FILES`:
 1. Read the full article content.
-2. Work through each area in the table below. For each area, read the named style guide section, then apply it to the article.
+2. Work through each area in the table below. For each area, read the named rulebook section, then apply it to the article.
 
 **Review areas:**
 
-| Area | Read this section of `kb_style_guide.md` | Supplementary notes (not in the style guide) |
-|------|------------------------------------------|-----------------------------------------------|
-| **frontmatter** | **Frontmatter** (Required fields, The `tags: [kb]` requirement) | If `knowledge_article_id` is present but contains a placeholder value (e.g., `kA0Qk000000PLACEHOLDER`), flag it — the author must replace it with the real Salesforce ID or remove the field. Absence of the field is fine for natively written articles. `sidebar_label` must not be truncated vs. `title`. |
-| **article-type: structure** | **Article Types** | **Wrong-shape check:** verify the article's structure fits its content, not just that a recognized structure exists. Q&A form is for simple procedures with one procedure and minimal caveat content. An article using Q&A form that actually contains two or more distinct procedures, multi-step workflows, or substantial caveat/note content should be flagged as a Required structural fix — recommend restructuring to `## Overview` + `## Instructions` with H3 subheadings per procedure. |
-| **article-type: qa-format** | **Article Types** | **Q&A question format:** In Q&A articles, content under `## Question` (and interrogative sub-headings in FAQ-style articles) must be a complete interrogative sentence — starts with an interrogative word (How do you / How can you / How should you / How will you / Can you / Should you / What / When / Where / Why / Which / Who / Does / Is / Are) and ends with `?`. Use second person ("you"), not first person ("I"), per `kb_style_guide.md`. "How to..." patterns (e.g., "How to export X?") are Required fixes — rewrite as "How do you export X?" or "Can you X?" as appropriate. Mark N/A if the article isn't Q&A form. |
-| **article-type: heading-labels** | **Article Types** | **Resolution section heading pluralization:** Section headings in Resolution articles — both Error and Symptom formats — are always singular — `## Symptom`, `## Cause`, `## Resolution` — even when the section contains multiple items. Flag `## Symptoms`, `## Causes`, `## Resolutions` as Required fixes. |
-| **title: mechanical** | **Article Titles** and the title format rules within **Article Types** | See "Title-format rules — two categories" below. Required fixes, apply on approval, low ambiguity: gerund-form titles for How-To Instructions articles, title case correction, raw log-line/error-dump title normalization (rulebook §12), and the H1/`sidebar_label`-consistency check (`sidebar_label` must not be truncated vs. `title`). |
-| **title: semantic** | **Article Titles** and the title format rules within **Article Types** | See "Title-format rules — two categories" below. Soft reminders / judgment calls — surface with suggested alternatives and reasoning, never auto-apply: product-name-in-title and article-type/title mismatch. Do NOT flag `> **NOTE:**` blockquote callouts — this is correct KB format, not a Docusaurus `:::note` admonition. |
-| **product-names** | **Product Names** | Always cross-check product IDs against `src/config/products.js` — the style guide table may be outdated. The config file is authoritative. **Exceptions:** `onesecure` has a real target (`1secure`) and should be flagged and corrected. `general` (cross-product content, no corresponding product) and `recoveryad` (ambiguous — `scripts/copy-kb-to-versions.mjs` maps both `recoveryforactivedirectory` and `identityrecovery` to this KB folder, so there's no single correct canonical ID to propose) have no valid `products.js` target at all — do not flag these as Required fixes. |
-| **keywords-quality** | **Frontmatter > Required fields > keywords** | If a keyword does not appear in the article body but is a plausible legacy or alternate search term (e.g., an old product acronym), note it as a low-priority observation rather than a required fix. |
-| **images: location** | **Screenshots** | KB image structure is not in the style guide — apply this rule: images must be stored in `0-images/` at the **product level** (`docs/kb/<product>/0-images/`), not inside category subfolders. PNG, WebP, JPG, and JPEG are all in active use and all valid — do not flag file format. Articles in category subfolders reference them with `../0-images/filename.<ext>`. |
-| **images: external-refs** | **Screenshots** | Flag any images linked from external sources (e.g., GitHub CDN URLs) — they must be downloaded and committed to the repo. |
-| **images: alt-text** | **Screenshots** | Alt text must be descriptive, not just the filename. Flag any image where the alt text is only the raw filename (e.g., `![index_files_location.png](path)`) — rewrite as a short description of what the image shows, per the Screenshots section. |
-| **links** | (not in style guide) | Find every internal markdown link in the article body — `[text](/docs/...)` (the dominant form, ~218 KB files) and `[text](pathname:///docs/...)` patterns to other KB articles and to versioned product docs, **and** relative `.md` links (`[text](../other-article.md)`, `[text](./other-article.md)`) — `kb_style_guide.md`'s own "Do" example for internal links uses the relative-`.md` form, and it's in active use (roughly a dozen KB files). All three forms are valid; do not propose converting one to another. For each, resolve the actual target file on disk: check for a `slug` frontmatter override on the target first; if none, the URL segment (or relative path) must match the target's real path/filename (not its `sidebar_label` or `title`). `pathname://` links specifically must use underscore version segments (`8_2`, not `8.2`) and resolve to a real file, per rulebook §8 — flag a dotted version segment as a Required fix even if the rest of the path resolves. This is a constraint on `pathname://` links where they're used, not a requirement to use that form over the bare `/docs/...` form. Flag any link whose URL does not resolve to a real file on disk as a Required fix, and correct it to the real path. Only genuinely external links (`http://`, `https://`, `mailto:`, etc.) are out of scope for this check. Backstop is `npm run build` — but `onBrokenLinks`/`onBrokenMarkdownLinks`/`onBrokenAnchors` in `docusaurus.config.js` only throw on a full build; a single-product build (`DOCS_PRODUCT=...`, the faster path `CLAUDE.md` recommends) relaxes all three to `warn`, so a broken link there won't fail the build. Either way, this check catches broken links before submission rather than relying on the backstop. |
-| **formatting: bold/backticks** | **Markup Conventions** | Registry paths, registry value names, registry data, error codes (e.g., `0x80070005`, `0x80004005`), commands, and executable names use inline code (backticks). UI element names (button labels, menu items, field names) use **bold** only when they are action targets in the current step (buttons being clicked, fields being filled, dropdowns being selected, menu items being chosen) — a UI element mentioned as context only (not acted on in this step) does not get bold. Flag bolded UI elements that are not action targets as Required fixes. ✓ "Click **Save**." ✓ "Select **PDF** from the **Save as type** dropdown." ✗ "The file appears under the Save as type column." — no bold on contextual reference. |
-| **formatting: lists** | **Lists** | Sequential procedures must be numbered lists — this applies to Resolution sections and all sub-sections within them (e.g., verification steps), not just top-level procedures. |
-| **prose-directness** | **Voice and Tone > Impersonal constructions** and **Words and phrases to avoid** | Flag sentences where an impersonal subject ("the operation", "the process", "the system") could be replaced with the actual actor for a cleaner, more direct sentence. Example: "the operation fails with an error" → "Clicking **X** fails with an error". Apply judgment — not every impersonal subject is wrong. |
+| Area | Rulebook section |
+|------|-------------------|
+| **frontmatter** | §13 Frontmatter (all required fields, product ID carve-outs, `knowledge_article_id` policy) |
+| **article-type: structure** | §14 Article Type Identification + §15 Article Structure (How-To structure check, wrong-shape check) |
+| **article-type: qa-format** | §15 Article Structure (Q&A question format) |
+| **article-type: heading-labels** | §15 Article Structure (pluralization) |
+| **title: mechanical** | §12 Titles (mechanical style corrections) |
+| **title: semantic** | §12 Titles (semantic reframes). Do NOT flag `> **NOTE:**` blockquote callouts — this is correct KB format, not a Docusaurus `:::note` admonition. |
+| **product-names** | `kb_style_guide.md` Product Names table, cross-checked against `src/config/products.js` (authoritative if the two disagree) — plus §13 Frontmatter for the product ID carve-outs (`onesecure`/`general`/`recoveryad`). |
+| **keywords-quality** | §13 Frontmatter (`keywords` row) |
+| **images: location** | §16 Images |
+| **images: external-refs** | §16 Images |
+| **images: alt-text** | §16 Images |
+| **links** | §8 Links |
+| **formatting: bold/backticks** | §6 Bolding and inline code |
+| **formatting: lists** | §3 List type |
+| **prose-directness** | §4 Sentence-level rules (impersonal-subject directness) |
 
 Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms — those belong to Vale and Dale respectively.
 
-#### Title-format rules — two categories
-
-Title findings split into two categories based on whether the change is mechanical or semantic.
-
-**Mechanical style corrections — Required fixes (surface, apply on approval):**
-
-- **gerund-for-How-To-Instructions:** "How to..." prefix → gerund form (e.g., "How to Export Event Logs" → "Exporting Event Logs"). Applies only to How-To Instructions form articles (`## Overview` + `## Instructions` structure). Does NOT apply to How-To Q&A articles — a topic-descriptive title, a "How to..." title, or a question-form title are all valid for Q&A; none is a gerund violation, and the interrogative form doesn't have to live in the title (it can appear in `## Question` instead).
-- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types.
-- **Raw log line / error dump titles** (rulebook §12): titles containing literal log-level tokens (FATAL, ERROR, WARN), stack noise, file paths, or truncation fragments (e.g., `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified in HubDetails.xml at ...`) → normalize to `<Component> Error - <core diagnostic phrase>`, keeping only the searchable message. Examples: `ConfigurationLoader Error - Hub Location Details Have Not Been Specified`; `TraceLogger Error - Address Already in Use`; `Remote Platform Discovery Error - Could Not Get Credentials`. This form is exempt from the `Error:` *prefix* convention required for Resolution (Error) titles generally (`Error: [Unique Error Code/Message]`, per `kb_style_guide.md` and `.claude/skills/derek/SKILL.md` §3) — the inline `Error` word already disambiguates the title, so don't also prepend `Error:`. **This is one of two exemptions, not the only one:** `kb_style_guide.md` also exempts any Resolution (Error) title where the error message itself already contains the word "error" (e.g. `Agents Have Become Unresponsive Error`) — that's the broader, more common case, independent of whether the title is a normalized log dump. A Resolution (Error) title only needs the `Error:` prefix when it has none of: the prefix, the word "error" anywhere in it, or the normalized log-dump form.
-- **H1 / `sidebar_label` consistency:** `sidebar_label` must not be truncated vs. `title`.
-
-These changes are low-ambiguity and preserve reader recognition — the article is still "the one about X," just with corrected surface form. Apply them per the normal fix loop.
-
-**Semantic reframes — soft reminders / judgment calls (reviewer decides, never auto-apply):**
-
-- Product name in title (e.g., "Antivirus Exclusions for Netwrix Data Classification" → drop "for Netwrix Data Classification"). If a product component name (client, agent, add-on) is essential to distinguishing the article from others about the same product, flag it as a judgment call rather than a required fix.
-- Article-type / title mismatch (e.g., Symptom Resolution structured article with a procedural-sounding title).
-
-These changes alter what the article appears to be *about* from the reader's perspective. They can break recognition for users searching by remembered title. The file path doesn't change so bookmarks survive, but readers don't navigate by URL — they navigate by name. For every semantic reframe finding:
-
-1. Flag the specific issue.
-2. Suggest one or more alternative titles with reasoning. Multiple options are welcome.
-3. Defer to the reviewer/author. Don't auto-apply. Don't argue if they leave the title alone — established titles often carry recognition weight that style purity doesn't outweigh.
-
 **KB Editing Conventions Scan (Derek subsection).** In addition to the areas table above, run the checklist below on every file. These are mechanical scan patterns codified during batch reviews; they map to the canonical rulebook at `.claude/references/kb-editing-conventions.md`. Do not duplicate the rulebook's full text here — treat the checklist as the minimum sweep. If a batch surfaces a new pattern, amend the rulebook and add the corresponding scan row here in the next PR.
 
 | # | Scan pattern | What to flag / fix |
 |---|--------------|--------------------|
 | 1 | `:::note`/`:::tip`/`:::info`/`:::warning`/`:::caution`/`:::danger`/`:::important` or `> **NOTE:**` / `> **IMPORTANT:**` blockquote inside a numbered list item | The callout must be indented **4 spaces** to attach to the preceding step. Fewer than 4 spaces breaks the list at CommonMark render time — this is a build-breaker, not a style nit. |
-| 2 | `## Overview` that opens with rationale/context rather than an explicit goal sentence, OR restates the title verbatim, OR reads as a bare symptom/condition | Rewrite so the first sentence states the goal: `This article describes how to <goal>` or equivalent (`explains...`, `shows how to...`). Rationale/context is fine as follow-on, but must not come first. |
+| 2 | `## Overview` that opens with rationale/context rather than an explicit goal sentence, OR restates the title verbatim, OR reads as a bare symptom/condition | Rewrite so the first sentence states the goal: `This article describes how to <goal>` or equivalent (`explains...`, `shows how to...`). Rationale/context is fine as follow-on, but must not come first. See rulebook §7. |
 | 3 | Literal string `<!-- link removed -->` in the article body | Search `docs/kb/**/*.md` and `docs/<product>/<version>/**/*.md` for a plausible target before shipping. If a real target exists, restore the cross-link; otherwise leave the comment and note it as unresolved. |
-| 4 | Same UI element or app name bolded in some places and unbolded in others within the same file | Normalize to consistent bolding across all occurrences in that article. |
+| 4 | Same UI element or app name bolded in some places and unbolded in others within the same file | Normalize to consistent bolding across all occurrences in that article (see rulebook §6 for which nouns qualify). |
 | 5 | Trailing periods inside markdown table cells | Strip them. Vale and Dale skip table content, so these slip through unless caught here. |
 | 6 | Numbered step ending on a bare `Click **X**.` with no observable result | Add a closing sentence describing what happens (dialog appears, list updates, etc.) OR combine with the next click step using `..., then click **Y**`. |
 | 7 | Any "contact Netwrix Support" phrasing without the standard link | Standard form is `[Netwrix Support](https://www.netwrix.com/support.html)`. Link only the first "contact" mention per article. |
-| 8 | `## Instructions` section with 3+ sequential subheadings | **Two-gate rule (rulebook §1).** **Gate A — consolidate first:** identify any subheading containing ≤1 action step that reads as prep/cleanup for an adjacent group (Stop Services / Start Services around an install, "Save and Exit" trailing a config edit, a lone "Restart" after a settings change). Merge each into the neighboring substantive group before counting. **Gate B — normalize:** if ≥3 substantive subheadings remain and represent sequential steps of the same procedure, rename to `Step N — <Label>` (em dash, not colon; normalize any pre-existing `Step N:`). Exclude a `Troubleshooting`/exception-handling subheading (and anything nested beneath it) from both the count and the labeling — it's a categorically different kind of section even at matching heading depth. Does NOT apply to parallel-alternative subheadings (Windows/Linux). Apply companion condensation opportunities at the same time. **Repetition is a Gate A signal, not a NOTE-hoist signal:** if multiple subheadings share the same lead-in ("On the DM machine, navigate to…"; "Open IIS by typing `inetmgr`…"), the repetition itself means the subheadings should merge — the shared context then becomes one natural lead-in sentence at the top of the merged step, not a NOTE block. Only hoist to a NOTE when the shared content is a caveat/warning (timing, permissions, state that breaks the procedure if ignored), never for procedural framing. Combine consecutive UI actions with "X, then Y" phrasing where applicable. |
+| 8 | `## Instructions` section with 3+ sequential subheadings | **Two-gate rule (rulebook §1).** **Gate A — consolidate first:** identify any subheading containing ≤1 action step that reads as prep/cleanup for an adjacent group (Stop Services / Start Services around an install, "Save and Exit" trailing a config edit, a lone "Restart" after a settings change), AND any cluster of thin "Remove X"-style subheadings that are really line-items off a single logical task. Merge each into the neighboring substantive group before counting. **Repetition is a signal for Gate A, not for NOTE-hoisting.** If multiple subheadings share the same lead-in ("On the Directory Manager machine, navigate to…"; "Open IIS by typing `inetmgr`…"), the repetition itself signals that the subheadings should merge — after merging, the shared context becomes one natural lead-in sentence at the top of the merged step. Do not reach for NOTE hoisting first; NOTE is for caveats, not procedural framing (see rulebook §1). **Gate B — normalize:** if ≥3 substantive subheadings remain after Gate A and represent sequential steps of the same procedure, rename to `Step N — <Label>` (em dash, not colon; normalize any pre-existing `Step N:`). Exclude a Troubleshooting/exception-handling subheading (and anything nested beneath it) from both the count and the labeling — it's a categorically different kind of section even at matching heading depth. Does NOT apply to parallel-alternative subheadings (Windows/Linux). Apply companion condensation rules (rulebook §2) at the same time. **Worked example:** `add-ssl-certificate-on-linux.md` originally had four subheadings (Stop Services / Copy Files / Change Nginx Config / Start Services). After Gate A, only two substantive groups remain (Install / Configure Nginx) — Gate B does not fire and no `Step N —` labels are applied. |
 | 9 | 2+ consecutive numbered steps that each read `Enter the following command: X.` | Condense into a single step: `Enter the following commands in order:` followed by a bulleted list or a fenced multi-line code block. Applies even at 2-3 repetitions for within-file consistency. |
 | 10 | A numbered "step" that describes a result rather than an action ("All collections appear in the output.") sitting between real action steps | Pull it out of the numbering — fold as a parenthetical on the preceding action, or set as unnumbered prose beneath it. |
 | 11 | A subheading under `## Instructions` whose content is purely descriptive/observational (no action for the reader to perform) | Restructure it into its own labeled section (e.g., `Reviewing X`) using prose or a bulleted fact list — not fake numbered "steps." Every subheading under Instructions must contain an actual action. |
 | 12 | A numbered step whose sub-list uses nested `1.` `2.` `3.` numbering | Convert the nested sub-list to `-` dashes. Numbered-inside-numbered renders ambiguously and reads as a restart; dashes make the parent/child relationship explicit. |
-| 13 | A single `## Instructions` or `## Resolution` section holding two or more distinct activities with no subheadings (wall-of-text) | Split by distinct activity into H3 subheadings. Mirror of row 8's over-fragmentation. |
-| 14 | An action that logically belongs in a numbered sequence but sits as trailing prose after the last numbered step (e.g., "Then start the services." as a paragraph) | Pull the action into the numbered sequence as its own step, matching the structure of parallel actions. Mirror of row 10 (result-as-step). |
-| 15 | A subheading (`###` or `####`) that wraps a single trivial element — most commonly a lone code block labeled `### Example Error Message` | Remove the subheading and lead in with a short sentence ("Example error:") followed by the code block. A heading implies a navigable standalone unit; a lone error block is not one. |
+| 13 | A single `## Instructions` or `## Resolution` section holding two or more distinct activities with no subheadings (wall-of-text) | Split by distinct activity into H3 subheadings. Mirror of row 8's over-fragmentation — under-fragmentation is equally broken. Route to `kb-writer` first if the split requires content judgment; apply here if the activity boundaries are unambiguous from the existing prose. |
+| 14 | An action that logically belongs in a numbered sequence but sits as trailing prose after the last numbered step (e.g., "Then start the services." as a paragraph following step N) | Pull the action into the numbered sequence as its own step, matching the structure of parallel actions in the article. Mirror of row 10 (result-as-step) — this is action-as-prose. |
+| 15 | A subheading (`###` or `####`) that wraps a single trivial element — most commonly a lone code block labeled `### Example Error Message` or similar | Remove the subheading and lead in with a short sentence ("Example error:") followed by the code block. A heading implies a navigable standalone unit; a lone error block is not one. Scope is not restricted to Instructions. |
 | 16 | A numbered list containing exactly one item (`1. Do X.` with no step 2) | Convert to a plain imperative sentence. Numbered lists imply a sequence; a one-item sequence is a mislabeled sentence. Rulebook §3. |
 | 17 | A single list item with 3+ comma- or semicolon-separated clauses reading as a run-on ("Full control of the application, including adding domains, forests, and tenants; configuring notifications; and managing other users…") | Break into a lead-in phrase followed by nested `-` sub-bullets. Route to `kb-writer` if the phrasing needs judgment; apply mechanically here when the split points are unambiguous. Rulebook §3. |
 | 18 | Descriptive "what this account/component does" bullets sitting *after* a numbered configuration procedure | Reorder as short intro prose *before* the numbered steps. Distinct from row 10 (result-as-step); this is about background-fact placement relative to actions. Route content-heavy rewrites to `kb-writer`. Rulebook §1. |
@@ -231,19 +207,23 @@ These changes alter what the article appears to be *about* from the reader's per
 | 20 | A list that appears with no lead-in sentence, reading disjointed from surrounding prose | Add a short intro sentence ending in a colon. Route to `kb-writer` when the intro needs content judgment; apply here when the missing context is obvious from the surrounding prose. Rulebook §4. |
 | 21 | A paragraph with 3+ inline cross-reference clauses ("see X, see Y, see Z") stacked in one sentence | Collapse into a single NOTE block with the links listed cleanly (compact enumeration or short bulleted list under the NOTE). Rulebook §8. |
 | 22 | A positional reference ("above"/"below"/"the section on X") that points to a named section in the same file | Replace with `[Section Name](#section-slug)` rather than rewording the positional term away. This is the concrete execution of Dale's `positional-references` suggestion. Rulebook §4. |
-| 23 | Either (a) `:::note` / `:::tip` / `:::info` / `:::warning` / `:::caution` / `:::danger` / `:::important` Docusaurus admonition syntax anywhere in the article body, **or** (b) a `> **<SEVERITY>:**` blockquote whose severity is not `NOTE` or `IMPORTANT` (e.g. `> **TIP:**`, `> **WARNING:**`, `> **CAUTION:**`, `> **DANGER:**`, `> **INFO:**`) — a callout can already be in blockquote form and still have the wrong severity label | KB articles use the blockquote callout format — only two severities exist, `NOTE` and `IMPORTANT` — not Docusaurus `:::` admonitions, and not any other blockquote severity label, per `.claude/skills/derek/SKILL.md` §7 (Admonition Format). Map `:::note`/`> **TIP:**`/`> **INFO:**`/etc. → `> **NOTE:**` and `:::warning`/`:::caution`/`> **DANGER:**`/`> **CAUTION:**`/etc. → `> **IMPORTANT:**`. If the callout sits inside a numbered list item, apply row 1's 4-space indentation rule to the converted/relabeled blockquote. |
+| 23 | Either (a) `:::note` / `:::tip` / `:::info` / `:::warning` / `:::caution` / `:::danger` / `:::important` Docusaurus admonition syntax anywhere in the article body, **or** (b) a `> **<SEVERITY>:**` blockquote whose severity is not `NOTE` or `IMPORTANT` (e.g. `> **TIP:**`, `> **WARNING:**`, `> **CAUTION:**`, `> **DANGER:**`, `> **INFO:**`) — a callout can already be in blockquote form and still have the wrong severity label | KB articles use the blockquote callout format — only two severities exist, `NOTE` and `IMPORTANT` — not Docusaurus `:::` admonitions, and not any other blockquote severity label, per rulebook §5 Callout severity. Map `:::note`/`> **TIP:**`/`> **INFO:**`/etc. → `> **NOTE:**` and `:::warning`/`:::caution`/`> **DANGER:**`/`> **CAUTION:**`/etc. → `> **IMPORTANT:**`. If the callout sits inside a numbered list item, apply row 1's 4-space indentation rule to the converted/relabeled blockquote. |
 
-**Cross-section consistency scan.** Run these checks in addition to the row-based table. These compare two sections of the same article against each other — section-local scans miss them. Rulebook §11.
+### Cross-section consistency scan
+
+Run this scan on every file in addition to the row-based table above. These rules compare two sections of the same article against each other — section-local scans miss them because each section reads correctly on its own. Rulebook §11.
 
 | Pattern | What to flag / fix |
 |---------|--------------------|
-| Symptom section describes the mechanism ("the service fails to start because …") in addition to observation | Trim Symptom to observation only. Move mechanism content into Cause. |
-| Cause section repeats observed behavior without explaining why | Route as content-depth gap (kb-writer territory); do not attempt to auto-write mechanism content. |
-| Acronym defined on first use but subsequent references use the long form | Replace subsequent long-form uses with the acronym. Dale only catches undefined acronyms; this is the other half of consistent use. |
-| Product's full name repeated three or more times where context is already established | After Overview/first Symptom sentence establishes the product, later mentions can drop the "Netwrix" prefix or full name when unambiguous. Do not strip mechanically. |
-| Related Articles link (or bottom-of-file bullet link) to a topic never mentioned in the article body | Remove the orphaned link. Every Related Articles entry must have a topical anchor in the body. |
+| Symptom section describes the mechanism ("the service fails to start because …") in addition to the observation | Trim Symptom to observation only. Move mechanism content into Cause. |
+| Cause section repeats the observed behavior without explaining why | Route to `kb-writer` — this is a content-depth gap, not a mechanical fix. |
+| Acronym defined on first use (e.g., "two-factor authentication (2FA)") but subsequent references in body/headings/notes use the long form | Replace subsequent long-form uses with the acronym. Dale only catches undefined acronyms; this is the other half of consistent use. |
+| Product's full name (e.g., "Netwrix Change Tracker") repeated three or more times in close proximity where context is already established | After the product's full name has been established (typically Overview or first Symptom sentence), later mentions can drop the "Netwrix" prefix or the full name entirely when unambiguous. Do not strip mechanically — apply where the reader would not lose context. |
+| Related Articles link (or bottom-of-file bullet link) to a topic never mentioned anywhere in the article body | Remove the orphaned link. Every Related Articles entry must have a topical anchor in the body (mentioned, compared, ruled out, etc.). |
 | Named permission types or access rights capitalized inconsistently within the same file (e.g., "Write permission" alongside "read and write access" referring to the same right) | Normalize capitalization across the article. Common named rights: Domain Admin, Read, Write, Read/Write, Full Control, Modify. Pick one convention per named right and apply throughout. Rulebook §11. |
 
+If a scan pattern above conflicts with something in the rulebook, the rulebook wins — re-read it and update this checklist in the next batch.
+
 Record each finding as: `area | finding | recommendation`.
 
 ---

From d0fe9637a53e2803f2e5fd3f556a9c1383b83eee Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 07:22:58 -0700
Subject: [PATCH 02/20] Address code review: fix build-warn claim, restore
 dropped title/style-guide rules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- docusaurus.config.js only relaxes onBrokenLinks under DOCS_PRODUCT;
  onBrokenMarkdownLinks and onBrokenAnchors throw unconditionally.
  Rulebook §8 overstated this as "relaxes all three to warn".
- §12 Titles referenced Error: prefix exemptions without ever stating
  the base Error: prefix rule, and dropped the Resolution (Symptom)
  title-format rule entirely during extraction. Added a "Base title
  format by article type" subsection covering all four types.
- Restored the kb_style_guide.md read instruction in kb-pr-open and
  kb-pr-review — both still depend on it (product-names, images
  alt-text) but dropped the explicit read step when switching to the
  rulebook as primary source.
- Derek's knowledge_article_id missing-field soft reminder (inherited
  from kb-pr-open's already-established policy via the reconciliation)
  had no note text in Derek's Output section. Added it alongside the
  existing blank-value and placeholder note text.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 13 ++++++++++++-
 .claude/skills/derek/SKILL.md                |  6 +++++-
 .claude/skills/kb-pr-open/SKILL.md           |  2 +-
 .claude/skills/kb-pr-review/SKILL.md         |  2 +-
 4 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index 10809b503b..036c5328a9 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -99,7 +99,7 @@ All three are `###` siblings under `## Instructions`, but `Troubleshooting` is a
 
 - **Three internal link forms are all valid** — `[text](/docs/...)` (the dominant form, ~218 KB files), `[text](pathname:///docs/...)`, and relative `.md` links (`[text](../other-article.md)`, `[text](./other-article.md)` — `kb_style_guide.md`'s own "Do" example for internal links uses this form, and it's in active use across roughly a dozen KB files). Do not propose converting one form to another. For each, resolve the actual target file on disk: check for a `slug` frontmatter override on the target first; if none, the URL segment (or relative path) must match the target's real path/filename (not its `sidebar_label` or `title`). Flag any link whose URL does not resolve to a real file on disk as a Required fix, and correct it to the real path. Only genuinely external links (`http://`, `https://`, `mailto:`, etc.) are out of scope for this check.
 - **`pathname://` links specifically** use the version-with-underscore format (`8_2` not `8.2`) and must resolve to a real file — flag a dotted version segment as a Required fix even if the rest of the path resolves. This is a constraint on `pathname://` links where they're used, not a mandate to prefer that form over the bare `/docs/...` form.
-- **Backstop is `npm run build`** — but `onBrokenLinks`/`onBrokenMarkdownLinks`/`onBrokenAnchors` in `docusaurus.config.js` only throw on a full build; a single-product build (`DOCS_PRODUCT=...`, the faster path `CLAUDE.md` recommends) relaxes all three to `warn`, so a broken link there won't fail the build. Either way, catch broken links before submission rather than relying on the backstop.
+- **Backstop is `npm run build`** — but a single-product build (`DOCS_PRODUCT=...`, the faster path `CLAUDE.md` recommends) only relaxes `onBrokenLinks` to `warn` (`docusaurus.config.js`: `onBrokenLinks: targetProduct ? 'warn' : 'throw'`); `onBrokenMarkdownLinks` and `onBrokenAnchors` still throw unconditionally, single-product build or not. A broken `/docs/...` or `pathname://` link can still slip through a single-product build without failing it, so catch broken links before submission rather than relying on the backstop.
 - **`WeakLinkText` Vale findings require a search, not just a rewrite.** Before proposing any fix for a Vale `WeakLinkText` finding, grep `docs/kb/**/*.md` and `docs/<product>/<version>/**/*.md` for a plausible real target based on the referenced topic (e.g., "Accounts and Required Permissions" → search for `accountreqs`, `account.*permission`). If a real target resolves, convert the prose into a proper link to it. Only rewrite the sentence to remove the implied reference if the search turns up nothing. Do not skip the search because the phrasing already implies no real link exists — the trigger already fired precisely because the phrasing looks like an implied reference, and the target often does exist on disk.
 - **`BoilerplateCrossRef` is unreachable on KB files — do not treat it as a real finding.** The Vale rule lives only in `.vale/styles/Netwrix/`, never `.vale/styles/NetwrixKB/`. `.vale.ini` scopes `BasedOnStyles = NetwrixKB` to `docs/kb/**/*.md`, replacing (not merging with) the repo-wide `Netwrix` style — so a `BoilerplateCrossRef` finding can never fire on a KB file under this scope (confirmed empirically: `vale --config .vale.ini` on a KB test file with a `BoilerplateCrossRef`-triggering phrase produced zero alerts). If one somehow appears, verify the file's actual style scope before treating it as real.
 - **`<!-- link removed -->` comments** deserve a real-target search before shipping. If a valid internal replacement exists in `docs/kb/**/*.md` or `docs/<product>/<version>/**/*.md`, restore the cross-link.
@@ -133,6 +133,17 @@ Rules that compare two sections of the same article against each other. Section-
 
 ## 12. Titles
 
+### Base title format by article type
+
+Per `kb_style_guide.md`'s Article Types and Article Titles sections:
+
+- **Resolution (Error):** starts with `Error:` followed by the unique error code or message. Include only the most unique part of the error message. Good: `Error: Event Collection Failed 0x80004005`. Bad: `Error: Can't Process Request` (too generic). See the exemptions below for when the `Error:` prefix is not required.
+- **Resolution (Symptom):** `[Feature or Component] [Symptom or Issue] [Optional: Condition or Context]` — descriptive, not vague. Good: `Active Directory Users Missing from Search Results`. Bad: `AD not working` (too vague).
+- **How-To (Instructions):** `[Action Gerund] [Specific Task]` — starts with a gerund, no "How to" prefix, no question mark.
+- **How-To (Q&A):** not required to use gerund/action form. A topic-descriptive title, a "How to..." title, or a question-form title are all valid — none is a gerund violation. The interrogative form doesn't have to live in the title; it can appear in `## Question` instead.
+
+All titles use title case and must not contain a product name — product names belong in the `products` frontmatter field.
+
 Title findings split into two categories based on whether the change is mechanical or semantic.
 
 ### Mechanical style corrections — Required fixes (apply on approval, low ambiguity)
diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index b6930a551e..7db66e87b1 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -81,7 +81,11 @@ Then print the markdown table. Every issue must be a row in this table — no ex
 
 If no issues are found, print the assessment line followed by "Derek found no issues." Do not print an empty table.
 
-**Soft reminders** (e.g., an empty `knowledge_article_id` per rulebook §13) print as a separate note after the table, not as a row, and do not count toward the issue total: `> **Note:** \`knowledge_article_id\` is blank. If this article originated from a Salesforce or Zendesk ticket, add the Knowledge Article ID here.`
+**Soft reminders** (rulebook §13's `knowledge_article_id` states — placeholder, empty, or missing entirely) print as a separate note after the table, not as a row, and do not count toward the issue total:
+
+- Empty string: `> **Note:** \`knowledge_article_id\` is blank. If this article originated from a Salesforce or Zendesk ticket, add the Knowledge Article ID here.`
+- Placeholder value: `> **Note:** \`knowledge_article_id\` looks like a placeholder. Populate it with the real ID if applicable, or leave as-is if no ID applies.`
+- Field missing entirely: `> **Note:** \`knowledge_article_id\` is not present. This is a valid state for a natively authored article — no action needed unless the article originated from an external ticket.`
 
 **Consolidating structure violations:** When multiple required headings are missing for the same article type, use a single `structure-article-type` row. List all missing headings in the Message column. If fixing the title would change the article type and resolve the structure issue automatically, note that in the Message.
 
diff --git a/.claude/skills/kb-pr-open/SKILL.md b/.claude/skills/kb-pr-open/SKILL.md
index cb9d64a3da..a904154731 100644
--- a/.claude/skills/kb-pr-open/SKILL.md
+++ b/.claude/skills/kb-pr-open/SKILL.md
@@ -70,7 +70,7 @@ If Vale is not installed or returns an error, note this in the report and contin
 
 **Dale** — apply the Dale rules in `.claude/skills/dale/rules/*.yml` semantically (passive voice, minimizing-difficulty words, idioms, wordiness, undefined acronyms, and the rest). Do not re-implement them from memory — read the rule files.
 
-**Derek** — read `.claude/references/kb-editing-conventions.md` from the repo root before every batch, because it evolves per batch. Read the full article content and perform a holistic KB writing quality review across these areas, reading the named rulebook section for each — do not hard-code rules that may drift:
+**Derek** — read `.claude/references/kb-editing-conventions.md` from the repo root before every batch, because it evolves per batch. Also read `kb_style_guide.md` from the repo root; the rulebook points to it for the Product Names table and the Screenshots alt-text guidance rather than duplicating them. Read the full article content and perform a holistic KB writing quality review across these areas, reading the named rulebook section for each — do not hard-code rules that may drift:
 
 | Area | Rulebook section |
 |------|-------------------|
diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md
index dc956fc116..acad8f33e3 100644
--- a/.claude/skills/kb-pr-review/SKILL.md
+++ b/.claude/skills/kb-pr-review/SKILL.md
@@ -153,7 +153,7 @@ Dale handles: passive voice, vague language, business jargon, idioms, undefined
 
 ### Step 8 — Perform Derek KB quality review on each file
 
-Read `.claude/references/kb-editing-conventions.md` from the repo root in full before beginning — this is the canonical rulebook. Then, for each review area below, re-read the named rulebook section and apply its rules to the article. The rulebook is the source of truth — do not substitute your own rules.
+Read `.claude/references/kb-editing-conventions.md` from the repo root in full before beginning — this is the canonical rulebook. Also read `kb_style_guide.md` from the repo root; the rulebook points to it for the Product Names table and the Screenshots alt-text guidance rather than duplicating them. Then, for each review area below, re-read the named rulebook section and apply its rules to the article. The rulebook is the source of truth — do not substitute your own rules.
 
 For each file in `KB_FILES`:
 1. Read the full article content.

From a25361cbdb8a69174c5184b404a6ed7dfc0c472c Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 07:41:02 -0700
Subject: [PATCH 03/20] Address second code review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Restored the dropped "multi-line commands/command output use fenced
  code blocks" rule (rulebook §10); repointed kb-pr-open/kb-pr-review's
  formatting: lists area at it alongside §3.
- Derek now inherits a title-case check via §12 that overlaps Vale's
  NetwrixKB.HeadingCase (scope: heading, fires on the H1) - noted in
  §12 that this is Vale's finding, not a second Derek row, for any
  skill running both in the same report.
- Qualified §12's "must not contain a product name" line - it's a
  general rule, not absolute; the semantic-reframes subsection below
  it is what actually governs (soft reminder, never auto-applied).
- Removed Derek's standalone Keywords/Description section, which had
  already drifted from §13's carve-out for plausible-but-unused
  keywords; §13 Frontmatter already covers both fields.
- Noted in Derek's Links area that WeakLinkText/BoilerplateCrossRef in
  §8 are Vale-only and not Derek's job.
- Added a rulebook-vs-kb_style_guide.md precedence statement: the
  rulebook is a derived elaboration, not a replacement - divergence
  from the published style guide is a bug in the rulebook to fix, not
  grounds for the rulebook to win.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 7 ++++---
 .claude/skills/derek/SKILL.md                | 8 +-------
 .claude/skills/kb-pr-open/SKILL.md           | 2 +-
 .claude/skills/kb-pr-review/SKILL.md         | 2 +-
 4 files changed, 7 insertions(+), 12 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index 036c5328a9..d1c1235fd1 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -2,7 +2,7 @@
 
 Comprehensive KB editing rulebook covering frontmatter, article type identification, article structure, structure/step condensation, list types, sentence-level rules, callouts, bolding, overview quality, links, placeholders, formatting, cross-section consistency, titles, and images.
 
-Apply during the `kb-pr-open` preemptive scan, the `kb-pr-review` review pass, and the `derek` review on every KB batch. This document is the canonical rulebook — `derek`, `kb-pr-open`, and `kb-pr-review` all read it rather than duplicating its content. Amend it via PR when a batch surfaces a new pattern.
+Apply during the `kb-pr-open` preemptive scan, the `kb-pr-review` review pass, and the `derek` review on every KB batch. This document is the canonical rulebook for these three skills — `derek`, `kb-pr-open`, and `kb-pr-review` all read it rather than duplicating its content, and it takes precedence over anything a skill might otherwise infer on its own. It is a derived, machine-oriented elaboration of `kb_style_guide.md` (the published, human-facing standard), not a replacement for it — where the two disagree, that is a bug in this rulebook, not a case for the rulebook to override the published standard. Amend it via PR when a batch surfaces a new pattern, and reconcile back to `kb_style_guide.md` in the same PR if the change affects a rule stated there.
 
 ## 1. Heading/step structure
 
@@ -120,6 +120,7 @@ All three are `###` siblings under `## Instructions`, but `Troubleshooting` is a
 - **Trailing image-removed comments** don't need their own anchoring sentence, but excess consecutive blank lines around them get trimmed to one.
 - **KB headings are Title Case** (verified against `kb_style_guide.md`, not assumed) — override of the docs-wide sentence-case rule.
 - **Trailing periods inside markdown table cells** get stripped. Vale and Dale skip table content, so these slip through unless caught here.
+- **Multi-line commands and command output use fenced code blocks**, not prose or plain indented text. A command spanning multiple lines, or output pasted from a terminal, gets a triple-backtick fenced block — flag any multi-line command or output that isn't fenced.
 
 ## 11. Cross-section consistency
 
@@ -142,14 +143,14 @@ Per `kb_style_guide.md`'s Article Types and Article Titles sections:
 - **How-To (Instructions):** `[Action Gerund] [Specific Task]` — starts with a gerund, no "How to" prefix, no question mark.
 - **How-To (Q&A):** not required to use gerund/action form. A topic-descriptive title, a "How to..." title, or a question-form title are all valid — none is a gerund violation. The interrogative form doesn't have to live in the title; it can appear in `## Question` instead.
 
-All titles use title case and must not contain a product name — product names belong in the `products` frontmatter field.
+All titles use title case. As a general rule, titles should not contain a product name — product names belong in the `products` frontmatter field — but this is not absolute: see "Semantic reframes" below, where product-name-in-title is a judgment call surfaced as a soft reminder, never auto-applied as a Required fix.
 
 Title findings split into two categories based on whether the change is mechanical or semantic.
 
 ### Mechanical style corrections — Required fixes (apply on approval, low ambiguity)
 
 - **gerund-for-How-To-Instructions:** "How to..." prefix → gerund form (e.g., "How to Export Event Logs" → "Exporting Event Logs"). Applies only to How-To Instructions form articles (`## Overview` + `## Instructions` structure). Does NOT apply to How-To Q&A articles — a topic-descriptive title, a "How to..." title, or a question-form title are all valid for Q&A; none is a gerund violation, and the interrogative form doesn't have to live in the title (it can appear in `## Question` instead).
-- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types.
+- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types. **Vale's `NetwrixKB.HeadingCase` (`scope: heading`) already fires on the H1**, so this is Vale's finding, not a second Derek/Derek-area row for the same title — do not duplicate it in the Derek findings table. Skills that run both Vale and this rulebook area in the same report (e.g., `kb-pr-open`, `kb-pr-review`) must not flag the same H1 twice.
 - **Raw log line or error dump as title.** Titles like `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified in HubDetails.xml at ...` — literal log lines with level tokens (FATAL, ERROR), stack noise, file paths, or truncation fragments — are unreadable and unsearchable. Normalize to the pattern `<Component> Error - <core diagnostic phrase>`, keeping only the searchable message.
   - Examples of the fix:
     - `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified` → `ConfigurationLoader Error - Hub Location Details Have Not Been Specified`
diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index 7db66e87b1..6f6b87e552 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -47,7 +47,7 @@ Read the named rulebook section before applying each area — do not hard-code r
 | Article structure (required headings, pluralization, wrong-shape check, Q&A format, Resolution Option Structure) | §15 Article Structure |
 | Title format (mechanical + semantic) | §12 Titles |
 | Callout/admonition format | §5 Callout severity |
-| Links | §8 Links |
+| Links | §8 Links — Derek doesn't run Vale, so the `WeakLinkText`/`BoilerplateCrossRef` bullets in §8 aren't Derek's job; apply only the link-resolution and link-form rules |
 | Bolding, inline code, path formatting | §6 Bolding and inline code |
 | Images | §16 Images |
 
@@ -59,12 +59,6 @@ Check that Netwrix product names follow the correct pattern from `kb_style_guide
 - All subsequent mentions: short product name (e.g., "Auditor")
 - No unapproved abbreviations (e.g., "NA" for Netwrix Auditor)
 
-## Keywords and Description Quality
-
-**Keywords:** The 8–12 keywords should be specific and searchable — error codes, product names, technical terms, and phrases a customer would type into a search bar. Flag if keywords are too generic, simply repeat the title, or are missing obvious terms visible in the article body.
-
-**Description:** Should be 1–2 sentences, SEO-friendly, and accurately summarize what the article covers and what it helps the reader do. Flag if empty, too vague, or a verbatim copy of the title.
-
 # Output
 
 **Output format is strictly required. Do not use a vertical list, prose paragraphs, or any other format. Always use the table below.**
diff --git a/.claude/skills/kb-pr-open/SKILL.md b/.claude/skills/kb-pr-open/SKILL.md
index a904154731..ee5639bf1b 100644
--- a/.claude/skills/kb-pr-open/SKILL.md
+++ b/.claude/skills/kb-pr-open/SKILL.md
@@ -87,7 +87,7 @@ If Vale is not installed or returns an error, note this in the report and contin
 | **images: alt-text** | §16 Images |
 | **links** | §8 Links |
 | **formatting: bold/backticks** | §6 Bolding and inline code |
-| **formatting: lists** | §3 List type |
+| **formatting: lists** | §3 List type + §10 Formatting (fenced code blocks for multi-line commands/output) |
 | **prose-directness** | §4 Sentence-level rules (impersonal-subject directness) |
 
 > **Multi-file coverage mandate:** For every file passed to the skill — including each individual file in a multi-file invocation — run the full Derek frontmatter sweep across all areas: `tags`, `products`, `keywords`, `sidebar_label`, `title`/title-format, and `knowledge_article_id`, plus `images` and `links`. Do not abbreviate or skip any area. If the same finding applies to multiple files (for example, all files have the same wrong `products` value), still list it under each file individually in the report — do not consolidate. A partial sweep on any single file is a coverage gap and causes downstream rework.
diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md
index acad8f33e3..3b7ec470ea 100644
--- a/.claude/skills/kb-pr-review/SKILL.md
+++ b/.claude/skills/kb-pr-review/SKILL.md
@@ -176,7 +176,7 @@ For each file in `KB_FILES`:
 | **images: alt-text** | §16 Images |
 | **links** | §8 Links |
 | **formatting: bold/backticks** | §6 Bolding and inline code |
-| **formatting: lists** | §3 List type |
+| **formatting: lists** | §3 List type + §10 Formatting (fenced code blocks for multi-line commands/output) |
 | **prose-directness** | §4 Sentence-level rules (impersonal-subject directness) |
 
 Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms — those belong to Vale and Dale respectively.

From da733abaccf5aa8d932c342703b76ab004e3faff Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 07:58:56 -0700
Subject: [PATCH 04/20] Address third code review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Dropped the Links and Images rows the extraction had silently added
  to Derek's areas table. Derek's Overview and description frontmatter
  never claimed those areas, and its single-file "read from disk" flow
  doesn't fit link-target/image-location resolution across the repo -
  that's kb-pr-open's and kb-pr-review's job. Restored Derek to its
  original five-area scope; added an explicit note pointing links/
  images checks at the other two skills.
- §13's title/H1-match rule now covers the no-H1 case (13 KB files
  have none) - Docusaurus renders frontmatter title as the H1 when the
  body has none, so that's a valid state, not a mismatch. Updated
  Derek's line-number guidance to fall back to line 1 when there's no
  H1 to point at.
- §8's build-backstop note now says pathname:// links have no build
  backstop at all (full or single-product) - pathname:// is
  Docusaurus's documented escape hatch that bypasses the broken-link
  checker entirely, unlike /docs/... links which are at least caught
  by onBrokenMarkdownLinks/onBrokenAnchors on a full build.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 4 ++--
 .claude/skills/derek/SKILL.md                | 6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index d1c1235fd1..f546f943a6 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -99,7 +99,7 @@ All three are `###` siblings under `## Instructions`, but `Troubleshooting` is a
 
 - **Three internal link forms are all valid** — `[text](/docs/...)` (the dominant form, ~218 KB files), `[text](pathname:///docs/...)`, and relative `.md` links (`[text](../other-article.md)`, `[text](./other-article.md)` — `kb_style_guide.md`'s own "Do" example for internal links uses this form, and it's in active use across roughly a dozen KB files). Do not propose converting one form to another. For each, resolve the actual target file on disk: check for a `slug` frontmatter override on the target first; if none, the URL segment (or relative path) must match the target's real path/filename (not its `sidebar_label` or `title`). Flag any link whose URL does not resolve to a real file on disk as a Required fix, and correct it to the real path. Only genuinely external links (`http://`, `https://`, `mailto:`, etc.) are out of scope for this check.
 - **`pathname://` links specifically** use the version-with-underscore format (`8_2` not `8.2`) and must resolve to a real file — flag a dotted version segment as a Required fix even if the rest of the path resolves. This is a constraint on `pathname://` links where they're used, not a mandate to prefer that form over the bare `/docs/...` form.
-- **Backstop is `npm run build`** — but a single-product build (`DOCS_PRODUCT=...`, the faster path `CLAUDE.md` recommends) only relaxes `onBrokenLinks` to `warn` (`docusaurus.config.js`: `onBrokenLinks: targetProduct ? 'warn' : 'throw'`); `onBrokenMarkdownLinks` and `onBrokenAnchors` still throw unconditionally, single-product build or not. A broken `/docs/...` or `pathname://` link can still slip through a single-product build without failing it, so catch broken links before submission rather than relying on the backstop.
+- **Backstop is `npm run build` — for the `/docs/...` and relative-`.md` forms only.** A single-product build (`DOCS_PRODUCT=...`, the faster path `CLAUDE.md` recommends) only relaxes `onBrokenLinks` to `warn` (`docusaurus.config.js`: `onBrokenLinks: targetProduct ? 'warn' : 'throw'`); `onBrokenMarkdownLinks` and `onBrokenAnchors` still throw unconditionally, single-product build or not. So a broken `/docs/...` link can still slip through a single-product build without failing it — catch it before submission rather than relying on the backstop. **`pathname://` links have no backstop at all, full build or single-product:** `pathname://` is Docusaurus's documented escape hatch that bypasses the broken-link checker entirely, so neither `onBrokenLinks` nor `onBrokenMarkdownLinks` ever validates one. The dotted-vs-underscore-version-segment check above is the only thing that catches a broken `pathname://` link — there is no build backstop to fall back on for it.
 - **`WeakLinkText` Vale findings require a search, not just a rewrite.** Before proposing any fix for a Vale `WeakLinkText` finding, grep `docs/kb/**/*.md` and `docs/<product>/<version>/**/*.md` for a plausible real target based on the referenced topic (e.g., "Accounts and Required Permissions" → search for `accountreqs`, `account.*permission`). If a real target resolves, convert the prose into a proper link to it. Only rewrite the sentence to remove the implied reference if the search turns up nothing. Do not skip the search because the phrasing already implies no real link exists — the trigger already fired precisely because the phrasing looks like an implied reference, and the target often does exist on disk.
 - **`BoilerplateCrossRef` is unreachable on KB files — do not treat it as a real finding.** The Vale rule lives only in `.vale/styles/Netwrix/`, never `.vale/styles/NetwrixKB/`. `.vale.ini` scopes `BasedOnStyles = NetwrixKB` to `docs/kb/**/*.md`, replacing (not merging with) the repo-wide `Netwrix` style — so a `BoilerplateCrossRef` finding can never fire on a KB file under this scope (confirmed empirically: `vale --config .vale.ini` on a KB test file with a `BoilerplateCrossRef`-triggering phrase produced zero alerts). If one somehow appears, verify the file's actual style scope before treating it as real.
 - **`<!-- link removed -->` comments** deserve a real-target search before shipping. If a valid internal replacement exists in `docs/kb/**/*.md` or `docs/<product>/<version>/**/*.md`, restore the cross-link.
@@ -174,7 +174,7 @@ All KB articles must begin with a frontmatter block. Check that all required fie
 
 | Field | What to check |
 |---|---|
-| `title` | Present; quoted if it contains colons or special characters; must match the H1 heading exactly |
+| `title` | Present; quoted if it contains colons or special characters; must match the H1 heading exactly *when the body has an H1*. A body with no H1 at all is valid — Docusaurus renders the frontmatter `title` as the page's H1 in that case, so there's nothing to mismatch. |
 | `description` | Present, non-empty, 1–2 sentences; SEO-friendly; accurately summarizes what the article covers. Flag if empty, too vague, or a verbatim copy of the title. |
 | `sidebar_label` | Present, non-empty; must not be truncated vs. `title` |
 | `keywords` | Present, contains 8–12 items — specific and searchable (error codes, product names, technical terms, phrases a customer would type into a search bar), not generic or a verbatim repeat of the title. If a keyword doesn't appear in the article body but is a plausible customer search term, note it as a low-priority observation rather than a required fix. |
diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index 6f6b87e552..00c724d066 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -47,9 +47,9 @@ Read the named rulebook section before applying each area — do not hard-code r
 | Article structure (required headings, pluralization, wrong-shape check, Q&A format, Resolution Option Structure) | §15 Article Structure |
 | Title format (mechanical + semantic) | §12 Titles |
 | Callout/admonition format | §5 Callout severity |
-| Links | §8 Links — Derek doesn't run Vale, so the `WeakLinkText`/`BoilerplateCrossRef` bullets in §8 aren't Derek's job; apply only the link-resolution and link-form rules |
 | Bolding, inline code, path formatting | §6 Bolding and inline code |
-| Images | §16 Images |
+
+Links and images are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — those checks require resolving link targets and image locations on disk across the repo, outside Derek's single-file review model. Derek's scope stays what the Overview states: frontmatter, article type/structure, title format, product names, and keyword/description quality.
 
 ## Product Names
 
@@ -87,7 +87,7 @@ If no issues are found, print the assessment line followed by "Derek found no is
 - Frontmatter field missing entirely: use line `1`
 - Frontmatter field present but invalid: use the line number of that field
 - Missing required heading: use line `1`; include the expected heading template in Message
-- Title format violation: use the line number of the H1 heading
+- Title format violation: use the line number of the H1 heading; if the body has no H1, use line `1` (the `title` frontmatter field) instead
 - Product name violation: use the line number of the offending text
 - Keywords or description quality issue: use the line number of the field in frontmatter
 

From 6d783569b95cc991a42ab951724b5b5aca194051 Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 08:06:50 -0700
Subject: [PATCH 05/20] Address fourth code review round: dedup the scan
 tables, not just sync them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 23-row scan table and 6-row cross-section table were still fully
duplicated verbatim between kb-pr-open and kb-pr-review, and now
tripled a few rules against the rulebook (§5's 4-space indent vs. scan
row 1, §10's table-cell periods vs. scan row 5) - the exact
whack-a-mole pattern this PR exists to close out, just one level
deeper than the areas table this PR already fixed.

Condensed both tables' "what to flag/fix" column to the pattern
description plus a rulebook-section pointer, dropping the duplicated
rule-mechanics prose while keeping every kb-writer routing decision
(rows 13/17/18/20) that isn't in the rulebook. Row count is unchanged
(23 scan rows, 6 cross-section rows) so the N/N-scanned coverage
mechanism is untouched. Verified the tables are still byte-identical
between the two skills afterward. Also names explicitly that the
cross-section table's rows 1-2 are the two failure directions of one
rulebook §11 bullet, not two separate rules - the exact 6-vs-5 drift
example from issue #131's history.

Also: removed kb-pr-open's now-fully-redundant knowledge_article_id/
title-format pointer paragraph (duplicated the areas table's §12/§13
rows, sitting in a dead spot after the all-clean short-circuit), and
added keyword/description quality to Derek's frontmatter area
parenthetical so its scope description matches the PR skills'.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/skills/derek/SKILL.md        |  2 +-
 .claude/skills/kb-pr-open/SKILL.md   | 64 +++++++++++++--------------
 .claude/skills/kb-pr-review/SKILL.md | 66 +++++++++++++---------------
 3 files changed, 62 insertions(+), 70 deletions(-)

diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index 00c724d066..64c081feff 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -42,7 +42,7 @@ Read the named rulebook section before applying each area — do not hard-code r
 
 | Area | Rulebook section |
 |---|---|
-| Frontmatter (all required fields, product ID carve-outs, `knowledge_article_id` policy) | §13 Frontmatter |
+| Frontmatter (all required fields including keyword/description quality, product ID carve-outs, `knowledge_article_id` policy) | §13 Frontmatter |
 | Article type identification | §14 Article Type Identification |
 | Article structure (required headings, pluralization, wrong-shape check, Q&A format, Resolution Option Structure) | §15 Article Structure |
 | Title format (mechanical + semantic) | §12 Titles |
diff --git a/.claude/skills/kb-pr-open/SKILL.md b/.claude/skills/kb-pr-open/SKILL.md
index ee5639bf1b..e76a572546 100644
--- a/.claude/skills/kb-pr-open/SKILL.md
+++ b/.claude/skills/kb-pr-open/SKILL.md
@@ -104,42 +104,42 @@ Run this scan on every file in addition to the Derek areas table above. Each ite
 
 | # | Scan pattern | What to flag / fix |
 |---|--------------|--------------------|
-| 1 | `:::note`/`:::tip`/`:::info`/`:::warning`/`:::caution`/`:::danger`/`:::important` or `> **NOTE:**` / `> **IMPORTANT:**` blockquote inside a numbered list item | The callout must be indented **4 spaces** to attach to the preceding step. Fewer than 4 spaces breaks the list at CommonMark render time — this is a build-breaker, not a style nit. |
-| 2 | `## Overview` that opens with rationale/context rather than an explicit goal sentence, OR restates the title verbatim, OR reads as a bare symptom/condition | Rewrite so the first sentence states the goal: `This article describes how to <goal>` or equivalent (`explains...`, `shows how to...`). Rationale/context is fine as follow-on, but must not come first. See rulebook §7. |
-| 3 | Literal string `<!-- link removed -->` in the article body | Search `docs/kb/**/*.md` and `docs/<product>/<version>/**/*.md` for a plausible target before shipping. If a real target exists, restore the cross-link; otherwise leave the comment and note it as unresolved. |
-| 4 | Same UI element or app name bolded in some places and unbolded in others within the same file | Normalize to consistent bolding across all occurrences in that article (see rulebook §6 for which nouns qualify). |
-| 5 | Trailing periods inside markdown table cells | Strip them. Vale and Dale skip table content, so these slip through unless caught here. |
-| 6 | Numbered step ending on a bare `Click **X**.` with no observable result | Add a closing sentence describing what happens (dialog appears, list updates, etc.) OR combine with the next click step using `..., then click **Y**`. |
-| 7 | Any "contact Netwrix Support" phrasing without the standard link | Standard form is `[Netwrix Support](https://www.netwrix.com/support.html)`. Link only the first "contact" mention per article. |
-| 8 | `## Instructions` section with 3+ sequential subheadings | **Two-gate rule (rulebook §1).** **Gate A — consolidate first:** identify any subheading containing ≤1 action step that reads as prep/cleanup for an adjacent group (Stop Services / Start Services around an install, "Save and Exit" trailing a config edit, a lone "Restart" after a settings change), AND any cluster of thin "Remove X"-style subheadings that are really line-items off a single logical task. Merge each into the neighboring substantive group before counting. **Repetition is a signal for Gate A, not for NOTE-hoisting.** If multiple subheadings share the same lead-in ("On the Directory Manager machine, navigate to…"; "Open IIS by typing `inetmgr`…"), the repetition itself signals that the subheadings should merge — after merging, the shared context becomes one natural lead-in sentence at the top of the merged step. Do not reach for NOTE hoisting first; NOTE is for caveats, not procedural framing (see rulebook §1). **Gate B — normalize:** if ≥3 substantive subheadings remain after Gate A and represent sequential steps of the same procedure, rename to `Step N — <Label>` (em dash, not colon; normalize any pre-existing `Step N:`). Exclude a Troubleshooting/exception-handling subheading (and anything nested beneath it) from both the count and the labeling — it's a categorically different kind of section even at matching heading depth. Does NOT apply to parallel-alternative subheadings (Windows/Linux). Apply companion condensation rules (rulebook §2) at the same time. **Worked example:** `add-ssl-certificate-on-linux.md` originally had four subheadings (Stop Services / Copy Files / Change Nginx Config / Start Services). After Gate A, only two substantive groups remain (Install / Configure Nginx) — Gate B does not fire and no `Step N —` labels are applied. |
-| 9 | 2+ consecutive numbered steps that each read `Enter the following command: X.` | Condense into a single step: `Enter the following commands in order:` followed by a bulleted list or a fenced multi-line code block. Applies even at 2-3 repetitions for within-file consistency. |
-| 10 | A numbered "step" that describes a result rather than an action ("All collections appear in the output.") sitting between real action steps | Pull it out of the numbering — fold as a parenthetical on the preceding action, or set as unnumbered prose beneath it. |
-| 11 | A subheading under `## Instructions` whose content is purely descriptive/observational (no action for the reader to perform) | Restructure it into its own labeled section (e.g., `Reviewing X`) using prose or a bulleted fact list — not fake numbered "steps." Every subheading under Instructions must contain an actual action. |
-| 12 | A numbered step whose sub-list uses nested `1.` `2.` `3.` numbering | Convert the nested sub-list to `-` dashes. Numbered-inside-numbered renders ambiguously and reads as a restart; dashes make the parent/child relationship explicit. |
-| 13 | A single `## Instructions` or `## Resolution` section holding two or more distinct activities with no subheadings (wall-of-text) | Split by distinct activity into H3 subheadings. Mirror of row 8's over-fragmentation — under-fragmentation is equally broken. Route to `kb-writer` first if the split requires content judgment; apply here if the activity boundaries are unambiguous from the existing prose. |
-| 14 | An action that logically belongs in a numbered sequence but sits as trailing prose after the last numbered step (e.g., "Then start the services." as a paragraph following step N) | Pull the action into the numbered sequence as its own step, matching the structure of parallel actions in the article. Mirror of row 10 (result-as-step) — this is action-as-prose. |
-| 15 | A subheading (`###` or `####`) that wraps a single trivial element — most commonly a lone code block labeled `### Example Error Message` or similar | Remove the subheading and lead in with a short sentence ("Example error:") followed by the code block. A heading implies a navigable standalone unit; a lone error block is not one. Scope is not restricted to Instructions. |
-| 16 | A numbered list containing exactly one item (`1. Do X.` with no step 2) | Convert to a plain imperative sentence. Numbered lists imply a sequence; a one-item sequence is a mislabeled sentence. Rulebook §3. |
-| 17 | A single list item with 3+ comma- or semicolon-separated clauses reading as a run-on ("Full control of the application, including adding domains, forests, and tenants; configuring notifications; and managing other users…") | Break into a lead-in phrase followed by nested `-` sub-bullets. Route to `kb-writer` if the phrasing needs judgment; apply mechanically here when the split points are unambiguous. Rulebook §3. |
-| 18 | Descriptive "what this account/component does" bullets sitting *after* a numbered configuration procedure | Reorder as short intro prose *before* the numbered steps. Distinct from row 10 (result-as-step); this is about background-fact placement relative to actions. Route content-heavy rewrites to `kb-writer`. Rulebook §1. |
-| 19 | List items that mix complete sentences and fragments, or inconsistent end-punctuation across items | Rewrite for grammatical parallelism (all complete sentences or all fragments) and consistent end-punctuation (either every item ends with a period, or none does). Rulebook §3 / `kb_style_guide.md`. |
-| 20 | A list that appears with no lead-in sentence, reading disjointed from surrounding prose | Add a short intro sentence ending in a colon. Route to `kb-writer` when the intro needs content judgment; apply here when the missing context is obvious from the surrounding prose. Rulebook §4. |
-| 21 | A paragraph with 3+ inline cross-reference clauses ("see X, see Y, see Z") stacked in one sentence | Collapse into a single NOTE block with the links listed cleanly (compact enumeration or short bulleted list under the NOTE). Rulebook §8. |
-| 22 | A positional reference ("above"/"below"/"the section on X") that points to a named section in the same file | Replace with `[Section Name](#section-slug)` rather than rewording the positional term away. This is the concrete execution of Dale's `positional-references` suggestion. Rulebook §4. |
-| 23 | Either (a) `:::note` / `:::tip` / `:::info` / `:::warning` / `:::caution` / `:::danger` / `:::important` Docusaurus admonition syntax anywhere in the article body, **or** (b) a `> **<SEVERITY>:**` blockquote whose severity is not `NOTE` or `IMPORTANT` (e.g. `> **TIP:**`, `> **WARNING:**`, `> **CAUTION:**`, `> **DANGER:**`, `> **INFO:**`) — a callout can already be in blockquote form and still have the wrong severity label | KB articles use the blockquote callout format — only two severities exist, `NOTE` and `IMPORTANT` — not Docusaurus `:::` admonitions, and not any other blockquote severity label, per rulebook §5 Callout severity. Map `:::note`/`> **TIP:**`/`> **INFO:**`/etc. → `> **NOTE:**` and `:::warning`/`:::caution`/`> **DANGER:**`/`> **CAUTION:**`/etc. → `> **IMPORTANT:**`. If the callout sits inside a numbered list item, apply row 1's 4-space indentation rule to the converted/relabeled blockquote. |
+| 1 | `:::note`/`:::tip`/`:::info`/`:::warning`/`:::caution`/`:::danger`/`:::important` or `> **NOTE:**` / `> **IMPORTANT:**` blockquote inside a numbered list item | 4-space indent to attach to the preceding step — build-breaker, not a style nit. Rulebook §5. |
+| 2 | `## Overview` that opens with rationale/context rather than an explicit goal sentence, OR restates the title verbatim, OR reads as a bare symptom/condition | Rewrite goal-first. Rulebook §7. |
+| 3 | Literal string `<!-- link removed -->` in the article body | Search for a plausible real target before shipping; restore the cross-link if one exists. Rulebook §8. |
+| 4 | Same UI element or app name bolded in some places and unbolded in others within the same file | Normalize bolding across the article. Rulebook §6. |
+| 5 | Trailing periods inside markdown table cells | Strip them — Vale and Dale skip table content. Rulebook §10. |
+| 6 | Numbered step ending on a bare `Click **X**.` with no observable result | Add a closing result sentence, or combine with the next click. Rulebook §4. |
+| 7 | Any "contact Netwrix Support" phrasing without the standard link | Use the standard linked form; link only the first mention per article. Rulebook §8. |
+| 8 | `## Instructions` section with 3+ sequential subheadings | Apply the two-gate consolidate-then-normalize rule (Gate A merges prep/cleanup subheadings and repetition-signaled clusters first; Gate B renames the substantive remainder to `Step N —`, excluding Troubleshooting). Rulebook §1 has the full mechanics and the `add-ssl-certificate-on-linux.md` worked example. |
+| 9 | 2+ consecutive numbered steps that each read `Enter the following command: X.` | Condense into one step with a list or fenced multi-line code block. Rulebook §2. |
+| 10 | A numbered "step" that describes a result rather than an action, sitting between real action steps | Pull it out of the numbering. Rulebook §1. |
+| 11 | A subheading under `## Instructions` with no action for the reader to perform | Restructure into a labeled prose/fact section, not fake numbered steps. Rulebook §1. |
+| 12 | A numbered step whose sub-list uses nested `1.` `2.` `3.` numbering | Convert to `-` dashes. Rulebook §3. |
+| 13 | A single `## Instructions` or `## Resolution` section holding two or more distinct activities with no subheadings (wall-of-text) | Split into H3 subheadings by activity. Rulebook §1. Route to `kb-writer` first if the split requires content judgment; apply here if the activity boundaries are unambiguous from the existing prose. |
+| 14 | An action that belongs in a numbered sequence but sits as trailing prose after the last numbered step | Pull it into the numbered sequence as its own step. Rulebook §1. |
+| 15 | A subheading (`###` or `####`) that wraps a single trivial element — most commonly a lone code block | Remove the subheading; lead in with a short sentence instead. Rulebook §1. |
+| 16 | A numbered list containing exactly one item | Convert to a plain imperative sentence. Rulebook §3. |
+| 17 | A single list item with 3+ comma- or semicolon-separated clauses reading as a run-on | Break into a lead-in phrase plus nested `-` sub-bullets. Rulebook §3. Route to `kb-writer` if the phrasing needs judgment; apply mechanically when the split points are unambiguous. |
+| 18 | Descriptive "what this account/component does" bullets sitting *after* a numbered configuration procedure | Reorder as intro prose *before* the numbered steps. Rulebook §1. Route content-heavy rewrites to `kb-writer`. |
+| 19 | List items that mix complete sentences and fragments, or inconsistent end-punctuation | Rewrite for parallelism and consistent end-punctuation. Rulebook §3. |
+| 20 | A list that appears with no lead-in sentence | Add a short intro sentence ending in a colon. Rulebook §4. Route to `kb-writer` when the intro needs content judgment; apply here when the missing context is obvious from the surrounding prose. |
+| 21 | A paragraph with 3+ inline cross-reference clauses ("see X, see Y, see Z") stacked in one sentence | Collapse into a single NOTE block with the links listed cleanly. Rulebook §8. |
+| 22 | A positional reference ("above"/"below"/"the section on X") that points to a named section in the same file | Replace with `[Section Name](#section-slug)`. Rulebook §4. |
+| 23 | `:::` admonition syntax anywhere in the article body, or a `> **<SEVERITY>:**` blockquote whose severity is not `NOTE` or `IMPORTANT` | Convert/relabel per the two-severity mapping (both `:::` and blockquote spellings). Rulebook §5 — apply row 1's 4-space indentation rule if the callout is inside a numbered list item. |
 
 ### Cross-section consistency scan
 
-Run this scan on every file in addition to the row-based table above. These rules compare two sections of the same article against each other — section-local scans miss them because each section reads correctly on its own. Rulebook §11.
+Run this scan on every file in addition to the row-based table above. These rules compare two sections of the same article against each other — section-local scans miss them because each section reads correctly on its own. All six rows map to rulebook §11's five bullets; rows 1 and 2 below are the two failure directions of §11's single "Symptom vs Cause overlap" bullet (Symptom too rich vs. Cause too thin), not two separate rulebook rules.
 
 | Pattern | What to flag / fix |
 |---------|--------------------|
-| Symptom section describes the mechanism ("the service fails to start because …") in addition to the observation | Trim Symptom to observation only. Move mechanism content into Cause. |
-| Cause section repeats the observed behavior without explaining why | Route to `kb-writer` — this is a content-depth gap, not a mechanical fix. |
-| Acronym defined on first use (e.g., "two-factor authentication (2FA)") but subsequent references in body/headings/notes use the long form | Replace subsequent long-form uses with the acronym. Dale only catches undefined acronyms; this is the other half of consistent use. |
-| Product's full name (e.g., "Netwrix Change Tracker") repeated three or more times in close proximity where context is already established | After the product's full name has been established (typically Overview or first Symptom sentence), later mentions can drop the "Netwrix" prefix or the full name entirely when unambiguous. Do not strip mechanically — apply where the reader would not lose context. |
-| Related Articles link (or bottom-of-file bullet link) to a topic never mentioned anywhere in the article body | Remove the orphaned link. Every Related Articles entry must have a topical anchor in the body (mentioned, compared, ruled out, etc.). |
-| Named permission types or access rights capitalized inconsistently within the same file (e.g., "Write permission" alongside "read and write access" referring to the same right) | Normalize capitalization across the article. Common named rights: Domain Admin, Read, Write, Read/Write, Full Control, Modify. Pick one convention per named right and apply throughout. Rulebook §11. |
+| Symptom section describes the mechanism in addition to the observation | Trim Symptom to observation only; move the mechanism into Cause. Rulebook §11. |
+| Cause section repeats the observed behavior without explaining why | Route to `kb-writer` — content-depth gap, not a mechanical fix. Rulebook §11 (same bullet as above). |
+| Acronym defined on first use but subsequent references use the long form | Replace subsequent long-form uses with the acronym. Rulebook §11. |
+| Product's full name repeated three or more times where context is already established | Drop the "Netwrix" prefix or full name where unambiguous. Rulebook §11. |
+| Related Articles link (or bottom-of-file bullet link) to a topic never mentioned in the article body | Remove the orphaned link. Rulebook §11. |
+| Named permission types or access rights capitalized inconsistently within the same file | Normalize to one convention per named right. Rulebook §11. |
 
 If a scan pattern above conflicts with something in the rulebook, the rulebook wins — re-read it and update this checklist in the next batch.
 
@@ -286,10 +286,6 @@ Do NOT prompt for local testing. Do NOT propose a commit message. Do NOT enter S
 
 If either command returns output — uncommitted changes anywhere in the working tree, or any commit already on the branch ahead of `origin/dev` (for example, content committed by `kb-writer` in an earlier step) — proceed normally to Step 5, even if this skill run applied zero fixes.
 
-### knowledge_article_id and title-format rules
-
-Both live in `.claude/references/kb-editing-conventions.md` — read §13 Frontmatter for the `knowledge_article_id` policy (presence/absence is informational, format is corrective, never propose adding/removing the field) and §12 Titles for the mechanical/semantic title-format split (gerund rules, title case, log-dump normalization, the two `Error:` prefix exemptions, H1/`sidebar_label` consistency, and the semantic-reframe soft-reminder rules). Apply mechanical fixes per the normal fix loop; semantic reframes are always the TSE's call — flag, suggest alternatives, defer.
-
 ## 5. Local testing
 
 Prompt the TSE to test — do not run the build yourself:
diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md
index 3b7ec470ea..1bd6e80ab2 100644
--- a/.claude/skills/kb-pr-review/SKILL.md
+++ b/.claude/skills/kb-pr-review/SKILL.md
@@ -185,44 +185,40 @@ Do NOT flag contractions, heading case, passive voice, jargon, or undefined acro
 
 | # | Scan pattern | What to flag / fix |
 |---|--------------|--------------------|
-| 1 | `:::note`/`:::tip`/`:::info`/`:::warning`/`:::caution`/`:::danger`/`:::important` or `> **NOTE:**` / `> **IMPORTANT:**` blockquote inside a numbered list item | The callout must be indented **4 spaces** to attach to the preceding step. Fewer than 4 spaces breaks the list at CommonMark render time — this is a build-breaker, not a style nit. |
-| 2 | `## Overview` that opens with rationale/context rather than an explicit goal sentence, OR restates the title verbatim, OR reads as a bare symptom/condition | Rewrite so the first sentence states the goal: `This article describes how to <goal>` or equivalent (`explains...`, `shows how to...`). Rationale/context is fine as follow-on, but must not come first. See rulebook §7. |
-| 3 | Literal string `<!-- link removed -->` in the article body | Search `docs/kb/**/*.md` and `docs/<product>/<version>/**/*.md` for a plausible target before shipping. If a real target exists, restore the cross-link; otherwise leave the comment and note it as unresolved. |
-| 4 | Same UI element or app name bolded in some places and unbolded in others within the same file | Normalize to consistent bolding across all occurrences in that article (see rulebook §6 for which nouns qualify). |
-| 5 | Trailing periods inside markdown table cells | Strip them. Vale and Dale skip table content, so these slip through unless caught here. |
-| 6 | Numbered step ending on a bare `Click **X**.` with no observable result | Add a closing sentence describing what happens (dialog appears, list updates, etc.) OR combine with the next click step using `..., then click **Y**`. |
-| 7 | Any "contact Netwrix Support" phrasing without the standard link | Standard form is `[Netwrix Support](https://www.netwrix.com/support.html)`. Link only the first "contact" mention per article. |
-| 8 | `## Instructions` section with 3+ sequential subheadings | **Two-gate rule (rulebook §1).** **Gate A — consolidate first:** identify any subheading containing ≤1 action step that reads as prep/cleanup for an adjacent group (Stop Services / Start Services around an install, "Save and Exit" trailing a config edit, a lone "Restart" after a settings change), AND any cluster of thin "Remove X"-style subheadings that are really line-items off a single logical task. Merge each into the neighboring substantive group before counting. **Repetition is a signal for Gate A, not for NOTE-hoisting.** If multiple subheadings share the same lead-in ("On the Directory Manager machine, navigate to…"; "Open IIS by typing `inetmgr`…"), the repetition itself signals that the subheadings should merge — after merging, the shared context becomes one natural lead-in sentence at the top of the merged step. Do not reach for NOTE hoisting first; NOTE is for caveats, not procedural framing (see rulebook §1). **Gate B — normalize:** if ≥3 substantive subheadings remain after Gate A and represent sequential steps of the same procedure, rename to `Step N — <Label>` (em dash, not colon; normalize any pre-existing `Step N:`). Exclude a Troubleshooting/exception-handling subheading (and anything nested beneath it) from both the count and the labeling — it's a categorically different kind of section even at matching heading depth. Does NOT apply to parallel-alternative subheadings (Windows/Linux). Apply companion condensation rules (rulebook §2) at the same time. **Worked example:** `add-ssl-certificate-on-linux.md` originally had four subheadings (Stop Services / Copy Files / Change Nginx Config / Start Services). After Gate A, only two substantive groups remain (Install / Configure Nginx) — Gate B does not fire and no `Step N —` labels are applied. |
-| 9 | 2+ consecutive numbered steps that each read `Enter the following command: X.` | Condense into a single step: `Enter the following commands in order:` followed by a bulleted list or a fenced multi-line code block. Applies even at 2-3 repetitions for within-file consistency. |
-| 10 | A numbered "step" that describes a result rather than an action ("All collections appear in the output.") sitting between real action steps | Pull it out of the numbering — fold as a parenthetical on the preceding action, or set as unnumbered prose beneath it. |
-| 11 | A subheading under `## Instructions` whose content is purely descriptive/observational (no action for the reader to perform) | Restructure it into its own labeled section (e.g., `Reviewing X`) using prose or a bulleted fact list — not fake numbered "steps." Every subheading under Instructions must contain an actual action. |
-| 12 | A numbered step whose sub-list uses nested `1.` `2.` `3.` numbering | Convert the nested sub-list to `-` dashes. Numbered-inside-numbered renders ambiguously and reads as a restart; dashes make the parent/child relationship explicit. |
-| 13 | A single `## Instructions` or `## Resolution` section holding two or more distinct activities with no subheadings (wall-of-text) | Split by distinct activity into H3 subheadings. Mirror of row 8's over-fragmentation — under-fragmentation is equally broken. Route to `kb-writer` first if the split requires content judgment; apply here if the activity boundaries are unambiguous from the existing prose. |
-| 14 | An action that logically belongs in a numbered sequence but sits as trailing prose after the last numbered step (e.g., "Then start the services." as a paragraph following step N) | Pull the action into the numbered sequence as its own step, matching the structure of parallel actions in the article. Mirror of row 10 (result-as-step) — this is action-as-prose. |
-| 15 | A subheading (`###` or `####`) that wraps a single trivial element — most commonly a lone code block labeled `### Example Error Message` or similar | Remove the subheading and lead in with a short sentence ("Example error:") followed by the code block. A heading implies a navigable standalone unit; a lone error block is not one. Scope is not restricted to Instructions. |
-| 16 | A numbered list containing exactly one item (`1. Do X.` with no step 2) | Convert to a plain imperative sentence. Numbered lists imply a sequence; a one-item sequence is a mislabeled sentence. Rulebook §3. |
-| 17 | A single list item with 3+ comma- or semicolon-separated clauses reading as a run-on ("Full control of the application, including adding domains, forests, and tenants; configuring notifications; and managing other users…") | Break into a lead-in phrase followed by nested `-` sub-bullets. Route to `kb-writer` if the phrasing needs judgment; apply mechanically here when the split points are unambiguous. Rulebook §3. |
-| 18 | Descriptive "what this account/component does" bullets sitting *after* a numbered configuration procedure | Reorder as short intro prose *before* the numbered steps. Distinct from row 10 (result-as-step); this is about background-fact placement relative to actions. Route content-heavy rewrites to `kb-writer`. Rulebook §1. |
-| 19 | List items that mix complete sentences and fragments, or inconsistent end-punctuation across items | Rewrite for grammatical parallelism (all complete sentences or all fragments) and consistent end-punctuation (either every item ends with a period, or none does). Rulebook §3 / `kb_style_guide.md`. |
-| 20 | A list that appears with no lead-in sentence, reading disjointed from surrounding prose | Add a short intro sentence ending in a colon. Route to `kb-writer` when the intro needs content judgment; apply here when the missing context is obvious from the surrounding prose. Rulebook §4. |
-| 21 | A paragraph with 3+ inline cross-reference clauses ("see X, see Y, see Z") stacked in one sentence | Collapse into a single NOTE block with the links listed cleanly (compact enumeration or short bulleted list under the NOTE). Rulebook §8. |
-| 22 | A positional reference ("above"/"below"/"the section on X") that points to a named section in the same file | Replace with `[Section Name](#section-slug)` rather than rewording the positional term away. This is the concrete execution of Dale's `positional-references` suggestion. Rulebook §4. |
-| 23 | Either (a) `:::note` / `:::tip` / `:::info` / `:::warning` / `:::caution` / `:::danger` / `:::important` Docusaurus admonition syntax anywhere in the article body, **or** (b) a `> **<SEVERITY>:**` blockquote whose severity is not `NOTE` or `IMPORTANT` (e.g. `> **TIP:**`, `> **WARNING:**`, `> **CAUTION:**`, `> **DANGER:**`, `> **INFO:**`) — a callout can already be in blockquote form and still have the wrong severity label | KB articles use the blockquote callout format — only two severities exist, `NOTE` and `IMPORTANT` — not Docusaurus `:::` admonitions, and not any other blockquote severity label, per rulebook §5 Callout severity. Map `:::note`/`> **TIP:**`/`> **INFO:**`/etc. → `> **NOTE:**` and `:::warning`/`:::caution`/`> **DANGER:**`/`> **CAUTION:**`/etc. → `> **IMPORTANT:**`. If the callout sits inside a numbered list item, apply row 1's 4-space indentation rule to the converted/relabeled blockquote. |
-
-### Cross-section consistency scan
-
-Run this scan on every file in addition to the row-based table above. These rules compare two sections of the same article against each other — section-local scans miss them because each section reads correctly on its own. Rulebook §11.
+| 1 | `:::note`/`:::tip`/`:::info`/`:::warning`/`:::caution`/`:::danger`/`:::important` or `> **NOTE:**` / `> **IMPORTANT:**` blockquote inside a numbered list item | 4-space indent to attach to the preceding step — build-breaker, not a style nit. Rulebook §5. |
+| 2 | `## Overview` that opens with rationale/context rather than an explicit goal sentence, OR restates the title verbatim, OR reads as a bare symptom/condition | Rewrite goal-first. Rulebook §7. |
+| 3 | Literal string `<!-- link removed -->` in the article body | Search for a plausible real target before shipping; restore the cross-link if one exists. Rulebook §8. |
+| 4 | Same UI element or app name bolded in some places and unbolded in others within the same file | Normalize bolding across the article. Rulebook §6. |
+| 5 | Trailing periods inside markdown table cells | Strip them — Vale and Dale skip table content. Rulebook §10. |
+| 6 | Numbered step ending on a bare `Click **X**.` with no observable result | Add a closing result sentence, or combine with the next click. Rulebook §4. |
+| 7 | Any "contact Netwrix Support" phrasing without the standard link | Use the standard linked form; link only the first mention per article. Rulebook §8. |
+| 8 | `## Instructions` section with 3+ sequential subheadings | Apply the two-gate consolidate-then-normalize rule (Gate A merges prep/cleanup subheadings and repetition-signaled clusters first; Gate B renames the substantive remainder to `Step N —`, excluding Troubleshooting). Rulebook §1 has the full mechanics and the `add-ssl-certificate-on-linux.md` worked example. |
+| 9 | 2+ consecutive numbered steps that each read `Enter the following command: X.` | Condense into one step with a list or fenced multi-line code block. Rulebook §2. |
+| 10 | A numbered "step" that describes a result rather than an action, sitting between real action steps | Pull it out of the numbering. Rulebook §1. |
+| 11 | A subheading under `## Instructions` with no action for the reader to perform | Restructure into a labeled prose/fact section, not fake numbered steps. Rulebook §1. |
+| 12 | A numbered step whose sub-list uses nested `1.` `2.` `3.` numbering | Convert to `-` dashes. Rulebook §3. |
+| 13 | A single `## Instructions` or `## Resolution` section holding two or more distinct activities with no subheadings (wall-of-text) | Split into H3 subheadings by activity. Rulebook §1. Route to `kb-writer` first if the split requires content judgment; apply here if the activity boundaries are unambiguous from the existing prose. |
+| 14 | An action that belongs in a numbered sequence but sits as trailing prose after the last numbered step | Pull it into the numbered sequence as its own step. Rulebook §1. |
+| 15 | A subheading (`###` or `####`) that wraps a single trivial element — most commonly a lone code block | Remove the subheading; lead in with a short sentence instead. Rulebook §1. |
+| 16 | A numbered list containing exactly one item | Convert to a plain imperative sentence. Rulebook §3. |
+| 17 | A single list item with 3+ comma- or semicolon-separated clauses reading as a run-on | Break into a lead-in phrase plus nested `-` sub-bullets. Rulebook §3. Route to `kb-writer` if the phrasing needs judgment; apply mechanically when the split points are unambiguous. |
+| 18 | Descriptive "what this account/component does" bullets sitting *after* a numbered configuration procedure | Reorder as intro prose *before* the numbered steps. Rulebook §1. Route content-heavy rewrites to `kb-writer`. |
+| 19 | List items that mix complete sentences and fragments, or inconsistent end-punctuation | Rewrite for parallelism and consistent end-punctuation. Rulebook §3. |
+| 20 | A list that appears with no lead-in sentence | Add a short intro sentence ending in a colon. Rulebook §4. Route to `kb-writer` when the intro needs content judgment; apply here when the missing context is obvious from the surrounding prose. |
+| 21 | A paragraph with 3+ inline cross-reference clauses ("see X, see Y, see Z") stacked in one sentence | Collapse into a single NOTE block with the links listed cleanly. Rulebook §8. |
+| 22 | A positional reference ("above"/"below"/"the section on X") that points to a named section in the same file | Replace with `[Section Name](#section-slug)`. Rulebook §4. |
+| 23 | `:::` admonition syntax anywhere in the article body, or a `> **<SEVERITY>:**` blockquote whose severity is not `NOTE` or `IMPORTANT` | Convert/relabel per the two-severity mapping (both `:::` and blockquote spellings). Rulebook §5 — apply row 1's 4-space indentation rule if the callout is inside a numbered list item. |
+
+**Cross-section consistency scan.** Run this scan on every file in addition to the row-based table above. These rules compare two sections of the same article against each other — section-local scans miss them because each section reads correctly on its own. All six rows map to rulebook §11's five bullets; rows 1 and 2 below are the two failure directions of §11's single "Symptom vs Cause overlap" bullet (Symptom too rich vs. Cause too thin), not two separate rulebook rules.
 
 | Pattern | What to flag / fix |
 |---------|--------------------|
-| Symptom section describes the mechanism ("the service fails to start because …") in addition to the observation | Trim Symptom to observation only. Move mechanism content into Cause. |
-| Cause section repeats the observed behavior without explaining why | Route to `kb-writer` — this is a content-depth gap, not a mechanical fix. |
-| Acronym defined on first use (e.g., "two-factor authentication (2FA)") but subsequent references in body/headings/notes use the long form | Replace subsequent long-form uses with the acronym. Dale only catches undefined acronyms; this is the other half of consistent use. |
-| Product's full name (e.g., "Netwrix Change Tracker") repeated three or more times in close proximity where context is already established | After the product's full name has been established (typically Overview or first Symptom sentence), later mentions can drop the "Netwrix" prefix or the full name entirely when unambiguous. Do not strip mechanically — apply where the reader would not lose context. |
-| Related Articles link (or bottom-of-file bullet link) to a topic never mentioned anywhere in the article body | Remove the orphaned link. Every Related Articles entry must have a topical anchor in the body (mentioned, compared, ruled out, etc.). |
-| Named permission types or access rights capitalized inconsistently within the same file (e.g., "Write permission" alongside "read and write access" referring to the same right) | Normalize capitalization across the article. Common named rights: Domain Admin, Read, Write, Read/Write, Full Control, Modify. Pick one convention per named right and apply throughout. Rulebook §11. |
-
-If a scan pattern above conflicts with something in the rulebook, the rulebook wins — re-read it and update this checklist in the next batch.
+| Symptom section describes the mechanism in addition to the observation | Trim Symptom to observation only; move the mechanism into Cause. Rulebook §11. |
+| Cause section repeats the observed behavior without explaining why | Route to `kb-writer` — content-depth gap, not a mechanical fix. Rulebook §11 (same bullet as above). |
+| Acronym defined on first use but subsequent references use the long form | Replace subsequent long-form uses with the acronym. Rulebook §11. |
+| Product's full name repeated three or more times where context is already established | Drop the "Netwrix" prefix or full name where unambiguous. Rulebook §11. |
+| Related Articles link (or bottom-of-file bullet link) to a topic never mentioned in the article body | Remove the orphaned link. Rulebook §11. |
+| Named permission types or access rights capitalized inconsistently within the same file | Normalize to one convention per named right. Rulebook §11. |
 
 Record each finding as: `area | finding | recommendation`.
 

From 5d58fac459c7654d7b502a0dc27116d0deebf970 Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 08:19:49 -0700
Subject: [PATCH 06/20] Address fifth code review round: two regressions, one
 latent gap, one legibility nit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- derek/SKILL.md's scope sentence (added by this PR) contradicted its
  own areas table two lines above, explicitly excluding callouts (§5)
  and bolding/path formatting (§6) that the table sends Derek to. A
  literal regression: those were unambiguously in scope pre-PR as
  Derek's own §5 Path Formatting and §7 Admonition Format sections.
  Fixed the Overview line, frontmatter description, and scope sentence
  to all state the same six-area scope.
- §13's keywords row lost the "flag terms prominent in the article
  body that are missing from keywords" check during extraction - both
  source files had it, the consolidated row only kept the inverse
  direction (keyword present but unused in body). Since this drives
  KB search discoverability, restored it as a Required fix distinct
  from the softer inverse-direction observation.
- §12's Vale-deferral for title case fires unconditionally, but Vale's
  NetwrixKB.HeadingCase is heading-scoped and never evaluates the 13
  KB files with no body H1 (where Docusaurus renders frontmatter title
  as the H1 instead). Scoped the deferral to H1-bearing articles only;
  no-H1 articles now get the frontmatter title's case checked directly
  since nothing else will.
- Promoted the Error: prefix's two exemptions to a top-level sub-bullet
  next to the Resolution (Error) rule they modify, instead of nesting
  exemption (a) - a general rule unrelated to log-dump normalization -
  under the narrower "raw log dump" bullet where a model evaluating
  that bullet as inapplicable would never reach it.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 9 +++++----
 .claude/skills/derek/SKILL.md                | 6 +++---
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index f546f943a6..8b8f880616 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -138,7 +138,8 @@ Rules that compare two sections of the same article against each other. Section-
 
 Per `kb_style_guide.md`'s Article Types and Article Titles sections:
 
-- **Resolution (Error):** starts with `Error:` followed by the unique error code or message. Include only the most unique part of the error message. Good: `Error: Event Collection Failed 0x80004005`. Bad: `Error: Can't Process Request` (too generic). See the exemptions below for when the `Error:` prefix is not required.
+- **Resolution (Error):** starts with `Error:` followed by the unique error code or message. Include only the most unique part of the error message. Good: `Error: Event Collection Failed 0x80004005`. Bad: `Error: Can't Process Request` (too generic).
+  - **`Error:` prefix exemptions — two, not one.** A Resolution (Error) title is exempt from the `Error:` prefix requirement when EITHER: (a) **the error message itself already contains the word "error"** (e.g. `Agents Have Become Unresponsive Error`, `Directory Name Is Invalid Error`) — the broader, more common case, and independent of the log-dump normalization below; or (b) it's normalized to the `<Component> Error - <phrase>` log-dump form (see the "Raw log line or error dump as title" bullet under Mechanical style corrections) — the inline `Error` word already disambiguates the title, so don't also prepend `Error:`. Only flag a Resolution (Error) title for missing the prefix when it has none of: the prefix, the word "error" anywhere in it, or the normalized log-dump form.
 - **Resolution (Symptom):** `[Feature or Component] [Symptom or Issue] [Optional: Condition or Context]` — descriptive, not vague. Good: `Active Directory Users Missing from Search Results`. Bad: `AD not working` (too vague).
 - **How-To (Instructions):** `[Action Gerund] [Specific Task]` — starts with a gerund, no "How to" prefix, no question mark.
 - **How-To (Q&A):** not required to use gerund/action form. A topic-descriptive title, a "How to..." title, or a question-form title are all valid — none is a gerund violation. The interrogative form doesn't have to live in the title; it can appear in `## Question` instead.
@@ -150,13 +151,13 @@ Title findings split into two categories based on whether the change is mechanic
 ### Mechanical style corrections — Required fixes (apply on approval, low ambiguity)
 
 - **gerund-for-How-To-Instructions:** "How to..." prefix → gerund form (e.g., "How to Export Event Logs" → "Exporting Event Logs"). Applies only to How-To Instructions form articles (`## Overview` + `## Instructions` structure). Does NOT apply to How-To Q&A articles — a topic-descriptive title, a "How to..." title, or a question-form title are all valid for Q&A; none is a gerund violation, and the interrogative form doesn't have to live in the title (it can appear in `## Question` instead).
-- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types. **Vale's `NetwrixKB.HeadingCase` (`scope: heading`) already fires on the H1**, so this is Vale's finding, not a second Derek/Derek-area row for the same title — do not duplicate it in the Derek findings table. Skills that run both Vale and this rulebook area in the same report (e.g., `kb-pr-open`, `kb-pr-review`) must not flag the same H1 twice.
+- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types. **When the body has an H1, defer to Vale — do not duplicate the finding.** `NetwrixKB.HeadingCase` (`scope: heading`) already fires on the H1, so this is Vale's finding, not a second Derek/rulebook-area row for the same title; skills that run both Vale and this rulebook area in the same report (e.g., `kb-pr-open`, `kb-pr-review`) must not flag the same H1 twice. **When the body has no H1 at all (§13's title row), this deferral does not apply — check the frontmatter `title` value's case directly,** since Vale's heading-scoped rule never evaluates a frontmatter field and nothing else will catch a badly-cased title on those articles.
 - **Raw log line or error dump as title.** Titles like `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified in HubDetails.xml at ...` — literal log lines with level tokens (FATAL, ERROR), stack noise, file paths, or truncation fragments — are unreadable and unsearchable. Normalize to the pattern `<Component> Error - <core diagnostic phrase>`, keeping only the searchable message.
   - Examples of the fix:
     - `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified` → `ConfigurationLoader Error - Hub Location Details Have Not Been Specified`
     - `TraceLogger ERROR System.Net.Sockets.SocketException Address already in use` → `TraceLogger Error - Address Already in Use`
     - `RemotePlatformDiscovery Could not get credentials from ...` → `Remote Platform Discovery Error - Could Not Get Credentials`
-  - **`Error:` prefix exemptions — two, not one.** A Resolution (Error) title is exempt from the `Error:` prefix requirement when EITHER: (a) the error message itself already contains the word "error" (e.g. `Agents Have Become Unresponsive Error`, `Directory Name Is Invalid Error`) — the broader, more common case; or (b) it's normalized to this `<Component> Error - <phrase>` log-dump form — the inline `Error` word already disambiguates the title, so don't also prepend `Error:`. Only flag a Resolution (Error) title for missing the prefix when it has none of: the prefix, the word "error" anywhere in it, or the normalized log-dump form.
+  - This normalized form is exemption (b) of the two `Error:` prefix exemptions stated under "Base title format by article type" above — the inline `Error` word already disambiguates the title, so don't also prepend `Error:`.
 - **H1 / `sidebar_label` consistency:** `sidebar_label` must not be truncated vs. `title`.
 
 These changes are low-ambiguity and preserve reader recognition — the article is still "the one about X," just with corrected surface form. Apply them per the normal fix loop.
@@ -177,7 +178,7 @@ All KB articles must begin with a frontmatter block. Check that all required fie
 | `title` | Present; quoted if it contains colons or special characters; must match the H1 heading exactly *when the body has an H1*. A body with no H1 at all is valid — Docusaurus renders the frontmatter `title` as the page's H1 in that case, so there's nothing to mismatch. |
 | `description` | Present, non-empty, 1–2 sentences; SEO-friendly; accurately summarizes what the article covers. Flag if empty, too vague, or a verbatim copy of the title. |
 | `sidebar_label` | Present, non-empty; must not be truncated vs. `title` |
-| `keywords` | Present, contains 8–12 items — specific and searchable (error codes, product names, technical terms, phrases a customer would type into a search bar), not generic or a verbatim repeat of the title. If a keyword doesn't appear in the article body but is a plausible customer search term, note it as a low-priority observation rather than a required fix. |
+| `keywords` | Present, contains 8–12 items — specific and searchable (error codes, product names, technical terms, phrases a customer would type into a search bar), not generic or a verbatim repeat of the title. Flag if a term prominent in the article body (an error code, a distinctive feature/component name) is missing from keywords — this drives search discoverability and is a Required fix, not a soft one. The inverse direction is softer: if a keyword doesn't appear in the article body but is a plausible customer search term, note it as a low-priority observation rather than a required fix. |
 | `products` | Present, contains at least one product ID from the canonical list in `src/config/products.js` — no hyphens or underscores as word separators (`dataclassification`, `directorymanager`, `threatmanager` are correct; `data-classification`, `directory-manager`, `threat-manager` are not) |
 | `tags` | Present and includes `kb` |
 | `knowledge_article_id` | See policy below |
diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index 64c081feff..4231a23da8 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: derek
-description: KB article quality reviewer. Run against KB articles in docs/kb/ to review frontmatter, article type and structure, title format, product names, and keyword quality. Use when editing or reviewing any file under docs/kb/.
+description: KB article quality reviewer. Run against KB articles in docs/kb/ to review frontmatter, article type and structure, title format, product names, callout format, bolding/path formatting, and keyword quality. Use when editing or reviewing any file under docs/kb/.
 argument-hint: "[docs/kb/path/to/article.md]"
 ---
 
@@ -25,7 +25,7 @@ You are Derek, a KB article quality reviewer for Netwrix. Your job is to review
 - Wordiness
 - Undefined acronyms
 
-Derek focuses on what's left: frontmatter validity, article type and structure, title format, product name usage, and keyword/description quality.
+Derek focuses on what's left: frontmatter validity, article type and structure, title format, product name usage, callout/admonition format, bolding and inline-code/path formatting, and keyword/description quality.
 
 # How to Review
 
@@ -49,7 +49,7 @@ Read the named rulebook section before applying each area — do not hard-code r
 | Callout/admonition format | §5 Callout severity |
 | Bolding, inline code, path formatting | §6 Bolding and inline code |
 
-Links and images are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — those checks require resolving link targets and image locations on disk across the repo, outside Derek's single-file review model. Derek's scope stays what the Overview states: frontmatter, article type/structure, title format, product names, and keyword/description quality.
+Links and images are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — those checks require resolving link targets and image locations on disk across the repo, outside Derek's single-file review model. Everything else in the table above — including callouts (§5) and bolding/inline code/paths (§6) — is in scope; the Overview line states the same six-area scope.
 
 ## Product Names
 

From 4ff35f4edfed610efabc3853be56873845dcb457 Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 08:37:35 -0700
Subject: [PATCH 07/20] Address sixth code review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Carved out §12's product-name-in-title and §13's no-H1-is-valid
  rules from the new rulebook-vs-style-guide precedence statement -
  both read as literal disagreements with kb_style_guide.md's absolute
  wording, but are deliberate elaborations, not bugs to revert.
- Fixed derek/SKILL.md's area count: Product Names lives in its own
  section below the table, not as a table row, so "six-area scope"
  underclaimed by one against the Overview's seven-area list.
- Restored the no-target-found branch for <!-- link removed --> (leave
  the comment, note unresolved) - dropped in the scan-table condensing
  pass, in both skills and the rulebook.
- Scan row 4 (intra-file bolding consistency) pointed at §6, but §6 had
  no consistency rule to back it - added one, closing the exact kind of
  dangling-pointer gap this PR exists to prevent.
- Moved the products.js-vs-style-guide-table precedence into §13 once;
  kb-pr-review's product-names row carried it inline while kb-pr-open's
  didn't - now both rows are identical and inherit it from the rulebook.
- Nit: clarified the Error: prefix exemption (b) is actually a special
  case of (a), not an independent condition - it's named separately
  because it's the specific pattern the log-dump rule produces.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 9 ++++++---
 .claude/skills/derek/SKILL.md                | 2 +-
 .claude/skills/kb-pr-open/SKILL.md           | 2 +-
 .claude/skills/kb-pr-review/SKILL.md         | 4 ++--
 4 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index 8b8f880616..2d602cf6cc 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -4,6 +4,8 @@ Comprehensive KB editing rulebook covering frontmatter, article type identificat
 
 Apply during the `kb-pr-open` preemptive scan, the `kb-pr-review` review pass, and the `derek` review on every KB batch. This document is the canonical rulebook for these three skills — `derek`, `kb-pr-open`, and `kb-pr-review` all read it rather than duplicating its content, and it takes precedence over anything a skill might otherwise infer on its own. It is a derived, machine-oriented elaboration of `kb_style_guide.md` (the published, human-facing standard), not a replacement for it — where the two disagree, that is a bug in this rulebook, not a case for the rulebook to override the published standard. Amend it via PR when a batch surfaces a new pattern, and reconcile back to `kb_style_guide.md` in the same PR if the change affects a rule stated there.
 
+Two current rules read as disagreements with the style guide's literal wording but are deliberate elaborations, not bugs — do not "fix" them back to the absolute reading without a real decision, the same way the exceptions in §13 and elsewhere are deliberate: **§12's product-name-in-title** sharpens the style guide's absolute "do not include product names in titles" into a general rule with a stated soft-reminder carve-out for genuinely distinguishing component names. **§13's title/H1 row** clarifies that a body with no H1 is a valid state (Docusaurus renders the frontmatter `title` as the H1 when the body has none), not a violation of the style guide's "the article title is always H1" line, which is about heading level, not literal presence.
+
 ## 1. Heading/step structure
 
 **Right-size step groups before applying `Step N —` normalization.** This is a two-gate rule.
@@ -87,6 +89,7 @@ All three are `###` siblings under `## Instructions`, but `Troubleshooting` is a
 - **Bold UI element names only when they're action targets in the current step** — buttons being clicked, fields being filled, dropdowns being selected, menu items being chosen. A UI element mentioned as context only (not acted on in this step) does not get bold. ✓ "Click **Save**." ✓ "Select **PDF** from the **Save as type** dropdown." ✗ "The file appears under the Save as type column." — no bold on contextual reference.
 - **Use inline code (backticks), not bold, for:** registry paths, registry value names, registry data, error codes (e.g., `0x80070005`, `0x80004005`), commands, and executable names.
 - **Registry, file, and directory paths in the article body must be wrapped in backticks or a fenced code block.** Patterns to look for: registry paths starting with `HKEY_`, `Computer\`, or `HKLM\`; Windows paths containing `C:\`, `\\`, or multiple backslash segments; Unix/Linux paths with multiple forward-slash segments (e.g., `/etc/netwrix/...`).
+- **Same UI element or app name must be bolded consistently within a single article** — bold every occurrence or none. A name bolded on first mention and left plain later (or vice versa) is a within-file inconsistency, not a per-mention judgment call.
 
 ## 7. Overview quality
 
@@ -102,7 +105,7 @@ All three are `###` siblings under `## Instructions`, but `Troubleshooting` is a
 - **Backstop is `npm run build` — for the `/docs/...` and relative-`.md` forms only.** A single-product build (`DOCS_PRODUCT=...`, the faster path `CLAUDE.md` recommends) only relaxes `onBrokenLinks` to `warn` (`docusaurus.config.js`: `onBrokenLinks: targetProduct ? 'warn' : 'throw'`); `onBrokenMarkdownLinks` and `onBrokenAnchors` still throw unconditionally, single-product build or not. So a broken `/docs/...` link can still slip through a single-product build without failing it — catch it before submission rather than relying on the backstop. **`pathname://` links have no backstop at all, full build or single-product:** `pathname://` is Docusaurus's documented escape hatch that bypasses the broken-link checker entirely, so neither `onBrokenLinks` nor `onBrokenMarkdownLinks` ever validates one. The dotted-vs-underscore-version-segment check above is the only thing that catches a broken `pathname://` link — there is no build backstop to fall back on for it.
 - **`WeakLinkText` Vale findings require a search, not just a rewrite.** Before proposing any fix for a Vale `WeakLinkText` finding, grep `docs/kb/**/*.md` and `docs/<product>/<version>/**/*.md` for a plausible real target based on the referenced topic (e.g., "Accounts and Required Permissions" → search for `accountreqs`, `account.*permission`). If a real target resolves, convert the prose into a proper link to it. Only rewrite the sentence to remove the implied reference if the search turns up nothing. Do not skip the search because the phrasing already implies no real link exists — the trigger already fired precisely because the phrasing looks like an implied reference, and the target often does exist on disk.
 - **`BoilerplateCrossRef` is unreachable on KB files — do not treat it as a real finding.** The Vale rule lives only in `.vale/styles/Netwrix/`, never `.vale/styles/NetwrixKB/`. `.vale.ini` scopes `BasedOnStyles = NetwrixKB` to `docs/kb/**/*.md`, replacing (not merging with) the repo-wide `Netwrix` style — so a `BoilerplateCrossRef` finding can never fire on a KB file under this scope (confirmed empirically: `vale --config .vale.ini` on a KB test file with a `BoilerplateCrossRef`-triggering phrase produced zero alerts). If one somehow appears, verify the file's actual style scope before treating it as real.
-- **`<!-- link removed -->` comments** deserve a real-target search before shipping. If a valid internal replacement exists in `docs/kb/**/*.md` or `docs/<product>/<version>/**/*.md`, restore the cross-link.
+- **`<!-- link removed -->` comments** deserve a real-target search before shipping. If a valid internal replacement exists in `docs/kb/**/*.md` or `docs/<product>/<version>/**/*.md`, restore the cross-link. If the search turns up nothing, leave the comment in place and note it as unresolved — do not delete the comment or invent a target.
 - **"Contact Netwrix Support"** → `[Netwrix Support](https://www.netwrix.com/support.html)`. Only link the first "contact" action per article.
 - **Dense multi-link "see X, see Y, see Z" prose → single NOTE.** When a paragraph contains 3+ inline cross-reference clauses stacked in one sentence, collapse them into a single NOTE block with the links listed cleanly (compact enumeration or short bulleted list under the NOTE). Multiple inline "see also" clauses in one sentence read as noise; a NOTE with clean bullets is scannable.
 - **Title change → link-text sweep across the repo.** When a KB article's title changes, do a repo-wide search for internal links whose visible text uses the *old* title, and update the link text to the new title. URL resolution alone is not sufficient — the visible link text must describe the current target, per the style guide's link-text rule. The existing links-review check (URL resolves on disk) does not catch stale link text. Use a dedicated search tool, passing the old title as a pattern parameter, rather than interpolating the title into a shell command string — shell-quote characters (some titles contain `'`) and unescaped regex metacharacters (`. * + ? ( ) [ ] { } \ | ^ $`) in the title can each cause a missed or broken match. Match `\[<old title>\]\(` (with the title's metacharacters escaped) to catch all three internal link forms in one search.
@@ -139,7 +142,7 @@ Rules that compare two sections of the same article against each other. Section-
 Per `kb_style_guide.md`'s Article Types and Article Titles sections:
 
 - **Resolution (Error):** starts with `Error:` followed by the unique error code or message. Include only the most unique part of the error message. Good: `Error: Event Collection Failed 0x80004005`. Bad: `Error: Can't Process Request` (too generic).
-  - **`Error:` prefix exemptions — two, not one.** A Resolution (Error) title is exempt from the `Error:` prefix requirement when EITHER: (a) **the error message itself already contains the word "error"** (e.g. `Agents Have Become Unresponsive Error`, `Directory Name Is Invalid Error`) — the broader, more common case, and independent of the log-dump normalization below; or (b) it's normalized to the `<Component> Error - <phrase>` log-dump form (see the "Raw log line or error dump as title" bullet under Mechanical style corrections) — the inline `Error` word already disambiguates the title, so don't also prepend `Error:`. Only flag a Resolution (Error) title for missing the prefix when it has none of: the prefix, the word "error" anywhere in it, or the normalized log-dump form.
+  - **`Error:` prefix exemptions — two, not one.** A Resolution (Error) title is exempt from the `Error:` prefix requirement when EITHER: (a) **the error message itself already contains the word "error"** (e.g. `Agents Have Become Unresponsive Error`, `Directory Name Is Invalid Error`) — the broader, more common case; or (b) it's normalized to the `<Component> Error - <phrase>` log-dump form (see the "Raw log line or error dump as title" bullet under Mechanical style corrections). (b) is actually a special case of (a) — the normalized form always contains the word "Error" too — but it's named separately because it's the specific, recognizable output pattern this rulebook's own log-dump normalization rule produces; the inline `Error` word already disambiguates the title, so don't also prepend `Error:`. Only flag a Resolution (Error) title for missing the prefix when it has none of: the prefix, the word "error" anywhere in it, or the normalized log-dump form.
 - **Resolution (Symptom):** `[Feature or Component] [Symptom or Issue] [Optional: Condition or Context]` — descriptive, not vague. Good: `Active Directory Users Missing from Search Results`. Bad: `AD not working` (too vague).
 - **How-To (Instructions):** `[Action Gerund] [Specific Task]` — starts with a gerund, no "How to" prefix, no question mark.
 - **How-To (Q&A):** not required to use gerund/action form. A topic-descriptive title, a "How to..." title, or a question-form title are all valid — none is a gerund violation. The interrogative form doesn't have to live in the title; it can appear in `## Question` instead.
@@ -179,7 +182,7 @@ All KB articles must begin with a frontmatter block. Check that all required fie
 | `description` | Present, non-empty, 1–2 sentences; SEO-friendly; accurately summarizes what the article covers. Flag if empty, too vague, or a verbatim copy of the title. |
 | `sidebar_label` | Present, non-empty; must not be truncated vs. `title` |
 | `keywords` | Present, contains 8–12 items — specific and searchable (error codes, product names, technical terms, phrases a customer would type into a search bar), not generic or a verbatim repeat of the title. Flag if a term prominent in the article body (an error code, a distinctive feature/component name) is missing from keywords — this drives search discoverability and is a Required fix, not a soft one. The inverse direction is softer: if a keyword doesn't appear in the article body but is a plausible customer search term, note it as a low-priority observation rather than a required fix. |
-| `products` | Present, contains at least one product ID from the canonical list in `src/config/products.js` — no hyphens or underscores as word separators (`dataclassification`, `directorymanager`, `threatmanager` are correct; `data-classification`, `directory-manager`, `threat-manager` are not) |
+| `products` | Present, contains at least one product ID from the canonical list in `src/config/products.js` — no hyphens or underscores as word separators (`dataclassification`, `directorymanager`, `threatmanager` are correct; `data-classification`, `directory-manager`, `threat-manager` are not). `src/config/products.js` is authoritative if it and `kb_style_guide.md`'s Product Names table disagree — the style guide table can lag a `products.js` update. |
 | `tags` | Present and includes `kb` |
 | `knowledge_article_id` | See policy below |
 
diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index 4231a23da8..14e944d241 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -49,7 +49,7 @@ Read the named rulebook section before applying each area — do not hard-code r
 | Callout/admonition format | §5 Callout severity |
 | Bolding, inline code, path formatting | §6 Bolding and inline code |
 
-Links and images are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — those checks require resolving link targets and image locations on disk across the repo, outside Derek's single-file review model. Everything else in the table above — including callouts (§5) and bolding/inline code/paths (§6) — is in scope; the Overview line states the same six-area scope.
+Links and images are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — those checks require resolving link targets and image locations on disk across the repo, outside Derek's single-file review model. Everything else is in scope: the six rows in the table above, plus Product Names, which lives in its own section below the table rather than as a seventh row. That's the same seven-area scope the Overview line states.
 
 ## Product Names
 
diff --git a/.claude/skills/kb-pr-open/SKILL.md b/.claude/skills/kb-pr-open/SKILL.md
index e76a572546..4d04d56277 100644
--- a/.claude/skills/kb-pr-open/SKILL.md
+++ b/.claude/skills/kb-pr-open/SKILL.md
@@ -106,7 +106,7 @@ Run this scan on every file in addition to the Derek areas table above. Each ite
 |---|--------------|--------------------|
 | 1 | `:::note`/`:::tip`/`:::info`/`:::warning`/`:::caution`/`:::danger`/`:::important` or `> **NOTE:**` / `> **IMPORTANT:**` blockquote inside a numbered list item | 4-space indent to attach to the preceding step — build-breaker, not a style nit. Rulebook §5. |
 | 2 | `## Overview` that opens with rationale/context rather than an explicit goal sentence, OR restates the title verbatim, OR reads as a bare symptom/condition | Rewrite goal-first. Rulebook §7. |
-| 3 | Literal string `<!-- link removed -->` in the article body | Search for a plausible real target before shipping; restore the cross-link if one exists. Rulebook §8. |
+| 3 | Literal string `<!-- link removed -->` in the article body | Search for a plausible real target before shipping; restore the cross-link if one exists, otherwise leave the comment and note it as unresolved. Rulebook §8. |
 | 4 | Same UI element or app name bolded in some places and unbolded in others within the same file | Normalize bolding across the article. Rulebook §6. |
 | 5 | Trailing periods inside markdown table cells | Strip them — Vale and Dale skip table content. Rulebook §10. |
 | 6 | Numbered step ending on a bare `Click **X**.` with no observable result | Add a closing result sentence, or combine with the next click. Rulebook §4. |
diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md
index 1bd6e80ab2..de7dd4aac8 100644
--- a/.claude/skills/kb-pr-review/SKILL.md
+++ b/.claude/skills/kb-pr-review/SKILL.md
@@ -169,7 +169,7 @@ For each file in `KB_FILES`:
 | **article-type: heading-labels** | §15 Article Structure (pluralization) |
 | **title: mechanical** | §12 Titles (mechanical style corrections) |
 | **title: semantic** | §12 Titles (semantic reframes). Do NOT flag `> **NOTE:**` blockquote callouts — this is correct KB format, not a Docusaurus `:::note` admonition. |
-| **product-names** | `kb_style_guide.md` Product Names table, cross-checked against `src/config/products.js` (authoritative if the two disagree) — plus §13 Frontmatter for the product ID carve-outs (`onesecure`/`general`/`recoveryad`). |
+| **product-names** | `kb_style_guide.md` Product Names table. Flag incorrect abbreviations (NDC, NPS, NTA, etc.) and wrong `products` field values (for example, hyphens vs. underscores) per rulebook §13. |
 | **keywords-quality** | §13 Frontmatter (`keywords` row) |
 | **images: location** | §16 Images |
 | **images: external-refs** | §16 Images |
@@ -187,7 +187,7 @@ Do NOT flag contractions, heading case, passive voice, jargon, or undefined acro
 |---|--------------|--------------------|
 | 1 | `:::note`/`:::tip`/`:::info`/`:::warning`/`:::caution`/`:::danger`/`:::important` or `> **NOTE:**` / `> **IMPORTANT:**` blockquote inside a numbered list item | 4-space indent to attach to the preceding step — build-breaker, not a style nit. Rulebook §5. |
 | 2 | `## Overview` that opens with rationale/context rather than an explicit goal sentence, OR restates the title verbatim, OR reads as a bare symptom/condition | Rewrite goal-first. Rulebook §7. |
-| 3 | Literal string `<!-- link removed -->` in the article body | Search for a plausible real target before shipping; restore the cross-link if one exists. Rulebook §8. |
+| 3 | Literal string `<!-- link removed -->` in the article body | Search for a plausible real target before shipping; restore the cross-link if one exists, otherwise leave the comment and note it as unresolved. Rulebook §8. |
 | 4 | Same UI element or app name bolded in some places and unbolded in others within the same file | Normalize bolding across the article. Rulebook §6. |
 | 5 | Trailing periods inside markdown table cells | Strip them — Vale and Dale skip table content. Rulebook §10. |
 | 6 | Numbered step ending on a bare `Click **X**.` with no observable result | Add a closing result sentence, or combine with the next click. Rulebook §4. |

From 68a7ea7f1645672989773d121fb73df92686f636 Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 08:57:30 -0700
Subject: [PATCH 08/20] Address seventh code review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Derek's output contract had no channel for the soft/judgment
  findings it now inherits from §12's semantic title reframes
  (product-name-in-title, article-type/title mismatch) - previously a
  counted hard-check row, now correctly a non-auto-apply soft
  reminder, but Derek's "every issue is a table row" contract gave it
  nowhere to go. Added a fourth soft-reminder note type alongside the
  three knowledge_article_id states.
- Clarified the naming collision between "Derek" as a findings-table
  label (used by kb-pr-open/kb-pr-review for their own inline
  links/images checks) and the /derek skill (which doesn't check
  links/images at all as of this PR). Added a one-line naming note to
  both PR skills.
- Verified §14's "confirmed against real KB files" claim for the
  Resolution-first classification order — it holds: 3 real articles
  (excluding the known multi-template file) have Overview alongside
  Symptom/Cause/Resolution, so the rationale text is accurate and
  wasn't changed. Documented the mirror-direction edge case (Q&A
  article with a stray Overview heading) that does affect exactly the
  one template file, so it isn't mistaken for a new bug later.
- CLAUDE.md's skills table still described /derek's pre-PR scope;
  updated to include callouts and bolding/path formatting.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md |  2 ++
 .claude/skills/derek/SKILL.md                | 10 ++++++----
 .claude/skills/kb-pr-open/SKILL.md           |  2 ++
 .claude/skills/kb-pr-review/SKILL.md         |  2 ++
 CLAUDE.md                                    |  2 +-
 5 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index 2d602cf6cc..a62c9167ef 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -220,6 +220,8 @@ Determine the article type from its structure first — this is authoritative an
 - Contains `## Overview` or `## Instructions` (or both) → **How-To (Instructions)**. Same partial-match tolerance.
 - Contains `## Question` or `## Answer` (or both) → **How-To (Q&A)**. If only one is present, §15 flags the other as missing — don't fall through to a different classification.
 
+**Known edge case (not worth reordering for):** checking Instructions before Q&A means a Q&A article that happens to carry an `## Overview` heading classifies as How-To (Instructions) instead, and gets told to add `## Instructions`. This is the mirror risk of the Resolution-first ordering above, but in the opposite direction. In the current corpus this hits exactly one file, `docs/kb/accessanalyzer-2601/kb-article-template.md` — a multi-template reference file containing all three article-type templates concatenated, not a real article — so it isn't worth reordering for. Documented here so it isn't mistaken for a new bug later.
+
 If none of these section structures are present, fall back to the title:
 
 - Title starts with `Error:` → **Resolution (Error)**
diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index 14e944d241..685ecb6662 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -75,11 +75,13 @@ Then print the markdown table. Every issue must be a row in this table — no ex
 
 If no issues are found, print the assessment line followed by "Derek found no issues." Do not print an empty table.
 
-**Soft reminders** (rulebook §13's `knowledge_article_id` states — placeholder, empty, or missing entirely) print as a separate note after the table, not as a row, and do not count toward the issue total:
+**Soft reminders** print as separate notes after the table, not as rows, and do not count toward the issue total:
 
-- Empty string: `> **Note:** \`knowledge_article_id\` is blank. If this article originated from a Salesforce or Zendesk ticket, add the Knowledge Article ID here.`
-- Placeholder value: `> **Note:** \`knowledge_article_id\` looks like a placeholder. Populate it with the real ID if applicable, or leave as-is if no ID applies.`
-- Field missing entirely: `> **Note:** \`knowledge_article_id\` is not present. This is a valid state for a natively authored article — no action needed unless the article originated from an external ticket.`
+- Rulebook §13's `knowledge_article_id` states — placeholder, empty, or missing entirely:
+  - Empty string: `> **Note:** \`knowledge_article_id\` is blank. If this article originated from a Salesforce or Zendesk ticket, add the Knowledge Article ID here.`
+  - Placeholder value: `> **Note:** \`knowledge_article_id\` looks like a placeholder. Populate it with the real ID if applicable, or leave as-is if no ID applies.`
+  - Field missing entirely: `> **Note:** \`knowledge_article_id\` is not present. This is a valid state for a natively authored article — no action needed unless the article originated from an external ticket.`
+- Rulebook §12's semantic title reframes (product-name-in-title, article-type/title mismatch) — never a table row, never counted, regardless of how many apply: `> **Note:** Semantic title reframe — <describe the issue>. Suggested alternative(s): <title>, <title>. This is a judgment call — the current title is not wrong; decide whether to change it.`
 
 **Consolidating structure violations:** When multiple required headings are missing for the same article type, use a single `structure-article-type` row. List all missing headings in the Message column. If fixing the title would change the article type and resolve the structure issue automatically, note that in the Message.
 
diff --git a/.claude/skills/kb-pr-open/SKILL.md b/.claude/skills/kb-pr-open/SKILL.md
index 4d04d56277..5f78fef075 100644
--- a/.claude/skills/kb-pr-open/SKILL.md
+++ b/.claude/skills/kb-pr-open/SKILL.md
@@ -92,6 +92,8 @@ If Vale is not installed or returns an error, note this in the report and contin
 
 > **Multi-file coverage mandate:** For every file passed to the skill — including each individual file in a multi-file invocation — run the full Derek frontmatter sweep across all areas: `tags`, `products`, `keywords`, `sidebar_label`, `title`/title-format, and `knowledge_article_id`, plus `images` and `links`. Do not abbreviate or skip any area. If the same finding applies to multiple files (for example, all files have the same wrong `products` value), still list it under each file individually in the report — do not consolidate. A partial sweep on any single file is a coverage gap and causes downstream rework.
 
+**Naming note:** `links` and `images` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, bolding/path formatting, and keyword/description quality — see `derek/SKILL.md`). Running `/derek` directly on a file does not cover links or images; only `kb-pr-open` and `kb-pr-review` do.
+
 Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms in this section — those belong to Vale and Dale respectively.
 
 > **IMPORTANT:** When applying fixes, follow `kb_style_guide.md`, not `docs/CLAUDE.md`. KB articles differ from the docs style guide on contractions (write out in full) and heading case (title case).
diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md
index de7dd4aac8..d2ed29ad2a 100644
--- a/.claude/skills/kb-pr-review/SKILL.md
+++ b/.claude/skills/kb-pr-review/SKILL.md
@@ -181,6 +181,8 @@ For each file in `KB_FILES`:
 
 Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms — those belong to Vale and Dale respectively.
 
+**Naming note:** `links` and `images` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, bolding/path formatting, and keyword/description quality — see `derek/SKILL.md`). Running `/derek` directly on a file does not cover links or images; only `kb-pr-open` and `kb-pr-review` do.
+
 **KB Editing Conventions Scan (Derek subsection).** In addition to the areas table above, run the checklist below on every file. These are mechanical scan patterns codified during batch reviews; they map to the canonical rulebook at `.claude/references/kb-editing-conventions.md`. Do not duplicate the rulebook's full text here — treat the checklist as the minimum sweep. If a batch surfaces a new pattern, amend the rulebook and add the corresponding scan row here in the next PR.
 
 | # | Scan pattern | What to flag / fix |
diff --git a/CLAUDE.md b/CLAUDE.md
index 1c606738cb..c7e1347fb2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -98,7 +98,7 @@ When a user asks for help with documentation, always use the appropriate tool:
 | `/doc-pr` | Skill | Automated PR editorial review |
 | `/content-fix` | Skill | Autonomous issue-to-PR fixer for content_fix issues |
 | `/doc-pr-fix` | Skill | Autonomous PR fixer triggered by `@claude` |
-| `/derek` | Skill | KB article quality reviewer (frontmatter, structure, title format, product names, keywords) |
+| `/derek` | Skill | KB article quality reviewer (frontmatter, structure, title format, product names, callouts, bolding/path formatting, keywords) |
 | `/kb-writer` | Skill | Interactive KB article content coach — depth, structure, clarity before linting |
 | `/kb-pr-open` | Skill | Last-mile KB submission helper for TSEs — lints and opens a PR to `dev` |
 | `/kb-pr-review` | Skill | Reviews a KB PR (Vale + Dale + Derek) and drafts a review comment |

From 895141635b38b27530fdc0211535f452f6017079 Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 09:14:08 -0700
Subject: [PATCH 09/20] Address eighth code review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- derek/SKILL.md's closing line ("never respond with anything beyond
  the assessment line and output table") forbade the four soft-
  reminder note types the Output section just above it defines,
  including the new semantic-title-reframe note. Under a strict
  reading, product-name-in-title and article-type/title-mismatch could
  vanish from Derek's output entirely. Amended to explicitly allow the
  defined soft reminders.
- §12's title-case Vale-deferral read as an unconditional instruction,
  but it only resolves the duplicate-finding problem for skills that
  run Vale in the same report. A standalone /derek invocation doesn't
  run Vale, so on an H1-bearing article a mis-cased title still goes
  unchecked - not a regression (Derek's own Vale-handles list already
  excluded heading case), but the new text implied a deferral that
  doesn't exist for that invocation path. Made the condition explicit.
- Nit: clarified derek/SKILL.md's "seven-area scope" claim is a total
  count, not a row-by-row correspondence with the Overview line's
  list (which groups keyword/description under frontmatter and splits
  article type/structure differently than the table's §14/§15 rows).

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 2 +-
 .claude/skills/derek/SKILL.md                | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index a62c9167ef..fe68221633 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -154,7 +154,7 @@ Title findings split into two categories based on whether the change is mechanic
 ### Mechanical style corrections — Required fixes (apply on approval, low ambiguity)
 
 - **gerund-for-How-To-Instructions:** "How to..." prefix → gerund form (e.g., "How to Export Event Logs" → "Exporting Event Logs"). Applies only to How-To Instructions form articles (`## Overview` + `## Instructions` structure). Does NOT apply to How-To Q&A articles — a topic-descriptive title, a "How to..." title, or a question-form title are all valid for Q&A; none is a gerund violation, and the interrogative form doesn't have to live in the title (it can appear in `## Question` instead).
-- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types. **When the body has an H1, defer to Vale — do not duplicate the finding.** `NetwrixKB.HeadingCase` (`scope: heading`) already fires on the H1, so this is Vale's finding, not a second Derek/rulebook-area row for the same title; skills that run both Vale and this rulebook area in the same report (e.g., `kb-pr-open`, `kb-pr-review`) must not flag the same H1 twice. **When the body has no H1 at all (§13's title row), this deferral does not apply — check the frontmatter `title` value's case directly,** since Vale's heading-scoped rule never evaluates a frontmatter field and nothing else will catch a badly-cased title on those articles.
+- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types. **When the body has an H1 *and* the skill running this rulebook area also runs Vale in the same report (e.g., `kb-pr-open`, `kb-pr-review`), defer to Vale — do not duplicate the finding.** `NetwrixKB.HeadingCase` (`scope: heading`) already fires on the H1 in that case, so it's Vale's finding, not a second row for the same title; do not flag the same H1 twice. A standalone invocation that doesn't run Vale (`/derek` on its own) has no deferral to make — Derek's own "what Vale already handles" list excludes heading case regardless, so a title-case issue on an H1-bearing article goes unchecked in a `/derek`-only run, same as before this rulebook existed. **When the body has no H1 at all (§13's title row), the deferral does not apply regardless of which skill is running — check the frontmatter `title` value's case directly,** since Vale's heading-scoped rule never evaluates a frontmatter field and nothing else will catch a badly-cased title on those articles.
 - **Raw log line or error dump as title.** Titles like `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified in HubDetails.xml at ...` — literal log lines with level tokens (FATAL, ERROR), stack noise, file paths, or truncation fragments — are unreadable and unsearchable. Normalize to the pattern `<Component> Error - <core diagnostic phrase>`, keeping only the searchable message.
   - Examples of the fix:
     - `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified` → `ConfigurationLoader Error - Hub Location Details Have Not Been Specified`
diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index 685ecb6662..6ec5a21e67 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -49,7 +49,7 @@ Read the named rulebook section before applying each area — do not hard-code r
 | Callout/admonition format | §5 Callout severity |
 | Bolding, inline code, path formatting | §6 Bolding and inline code |
 
-Links and images are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — those checks require resolving link targets and image locations on disk across the repo, outside Derek's single-file review model. Everything else is in scope: the six rows in the table above, plus Product Names, which lives in its own section below the table rather than as a seventh row. That's the same seven-area scope the Overview line states.
+Links and images are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — those checks require resolving link targets and image locations on disk across the repo, outside Derek's single-file review model. Everything else is in scope: the six rows in the table above, plus Product Names, which lives in its own section below the table rather than as a seventh row. That totals the same seven areas the Overview line lists — not a row-by-row match (the Overview folds keyword/description quality into frontmatter and splits "article type and structure" differently than the table's separate §14/§15 rows), just the same overall scope.
 
 ## Product Names
 
@@ -95,4 +95,4 @@ If no issues are found, print the assessment line followed by "Derek found no is
 
 # Troubleshooting
 
-Never re-flag issues that Vale or Dale already catch. Never respond with anything beyond the assessment line and output table.
+Never re-flag issues that Vale or Dale already catch. Never respond with anything beyond the assessment line, the output table, and the soft-reminder notes defined in the Output section above.

From 0c77a94909b631d85ff18f5bb01d626fba40a608 Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 09:24:00 -0700
Subject: [PATCH 10/20] Address ninth code review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- §12's title-case bullet inverted its own premise: it said Derek's
  "what Vale already handles" list "excludes heading case," when the
  list actually assigns heading case to Vale (that's why a
  /derek-only run misses it). As written, an agent resolving the
  contradiction literally would start flagging H1 title case in every
  invocation, duplicating Vale. Fixed the wording to state the premise
  correctly.
- The "Naming note" added to both PR skills undercounted the /derek
  scope delta - it named only links/images, but formatting: lists
  (§3+§10) and prose-directness (§4) are also Derek-table areas that
  /derek itself doesn't check. Both skills now name all four.
- Restored WARN to the raw-log-dump title trigger's level-token list -
  both deleted source copies had it, the consolidated §12 dropped it
  incidentally during extraction.
- Added a parenthetical to both skills' "do NOT flag heading case"
  line clarifying it means H1 case only - the §12 no-H1 carve-out
  (check the frontmatter title directly) isn't covered by Vale and
  still applies, so the two lines don't actually conflict.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 4 ++--
 .claude/skills/kb-pr-open/SKILL.md           | 4 ++--
 .claude/skills/kb-pr-review/SKILL.md         | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index fe68221633..5c309be03e 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -154,8 +154,8 @@ Title findings split into two categories based on whether the change is mechanic
 ### Mechanical style corrections — Required fixes (apply on approval, low ambiguity)
 
 - **gerund-for-How-To-Instructions:** "How to..." prefix → gerund form (e.g., "How to Export Event Logs" → "Exporting Event Logs"). Applies only to How-To Instructions form articles (`## Overview` + `## Instructions` structure). Does NOT apply to How-To Q&A articles — a topic-descriptive title, a "How to..." title, or a question-form title are all valid for Q&A; none is a gerund violation, and the interrogative form doesn't have to live in the title (it can appear in `## Question` instead).
-- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types. **When the body has an H1 *and* the skill running this rulebook area also runs Vale in the same report (e.g., `kb-pr-open`, `kb-pr-review`), defer to Vale — do not duplicate the finding.** `NetwrixKB.HeadingCase` (`scope: heading`) already fires on the H1 in that case, so it's Vale's finding, not a second row for the same title; do not flag the same H1 twice. A standalone invocation that doesn't run Vale (`/derek` on its own) has no deferral to make — Derek's own "what Vale already handles" list excludes heading case regardless, so a title-case issue on an H1-bearing article goes unchecked in a `/derek`-only run, same as before this rulebook existed. **When the body has no H1 at all (§13's title row), the deferral does not apply regardless of which skill is running — check the frontmatter `title` value's case directly,** since Vale's heading-scoped rule never evaluates a frontmatter field and nothing else will catch a badly-cased title on those articles.
-- **Raw log line or error dump as title.** Titles like `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified in HubDetails.xml at ...` — literal log lines with level tokens (FATAL, ERROR), stack noise, file paths, or truncation fragments — are unreadable and unsearchable. Normalize to the pattern `<Component> Error - <core diagnostic phrase>`, keeping only the searchable message.
+- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types. **When the body has an H1 *and* the skill running this rulebook area also runs Vale in the same report (e.g., `kb-pr-open`, `kb-pr-review`), defer to Vale — do not duplicate the finding.** `NetwrixKB.HeadingCase` (`scope: heading`) already fires on the H1 in that case, so it's Vale's finding, not a second row for the same title; do not flag the same H1 twice. A standalone invocation that doesn't run Vale (`/derek` on its own) has no deferral to make — Derek's own "what Vale already handles" list already assigns heading case to Vale, so a title-case issue on an H1-bearing article goes unchecked in a `/derek`-only run (nobody runs `NetwrixKB.HeadingCase` in that invocation), same as before this rulebook existed. **When the body has no H1 at all (§13's title row), the deferral does not apply regardless of which skill is running — check the frontmatter `title` value's case directly,** since Vale's heading-scoped rule never evaluates a frontmatter field and nothing else will catch a badly-cased title on those articles.
+- **Raw log line or error dump as title.** Titles like `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified in HubDetails.xml at ...` — literal log lines with level tokens (FATAL, ERROR, WARN), stack noise, file paths, or truncation fragments — are unreadable and unsearchable. Normalize to the pattern `<Component> Error - <core diagnostic phrase>`, keeping only the searchable message.
   - Examples of the fix:
     - `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified` → `ConfigurationLoader Error - Hub Location Details Have Not Been Specified`
     - `TraceLogger ERROR System.Net.Sockets.SocketException Address already in use` → `TraceLogger Error - Address Already in Use`
diff --git a/.claude/skills/kb-pr-open/SKILL.md b/.claude/skills/kb-pr-open/SKILL.md
index 5f78fef075..a99b4386e0 100644
--- a/.claude/skills/kb-pr-open/SKILL.md
+++ b/.claude/skills/kb-pr-open/SKILL.md
@@ -92,9 +92,9 @@ If Vale is not installed or returns an error, note this in the report and contin
 
 > **Multi-file coverage mandate:** For every file passed to the skill — including each individual file in a multi-file invocation — run the full Derek frontmatter sweep across all areas: `tags`, `products`, `keywords`, `sidebar_label`, `title`/title-format, and `knowledge_article_id`, plus `images` and `links`. Do not abbreviate or skip any area. If the same finding applies to multiple files (for example, all files have the same wrong `products` value), still list it under each file individually in the report — do not consolidate. A partial sweep on any single file is a coverage gap and causes downstream rework.
 
-**Naming note:** `links` and `images` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, bolding/path formatting, and keyword/description quality — see `derek/SKILL.md`). Running `/derek` directly on a file does not cover links or images; only `kb-pr-open` and `kb-pr-review` do.
+**Naming note:** `links`, `images`, `formatting: lists`, and `prose-directness` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check any of them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, and bolding/inline-code/path formatting — see `derek/SKILL.md`'s Review Areas table). Running `/derek` directly on a file does not cover those four areas; only `kb-pr-open` and `kb-pr-review` do.
 
-Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms in this section — those belong to Vale and Dale respectively.
+Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms in this section — those belong to Vale and Dale respectively. (Heading case here means the H1 case Vale's `NetwrixKB.HeadingCase` checks — the §12 exception for articles with no body H1 is not covered by Vale and still applies; check the frontmatter `title` value's case directly on those.)
 
 > **IMPORTANT:** When applying fixes, follow `kb_style_guide.md`, not `docs/CLAUDE.md`. KB articles differ from the docs style guide on contractions (write out in full) and heading case (title case).
 
diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md
index d2ed29ad2a..73564469a4 100644
--- a/.claude/skills/kb-pr-review/SKILL.md
+++ b/.claude/skills/kb-pr-review/SKILL.md
@@ -179,9 +179,9 @@ For each file in `KB_FILES`:
 | **formatting: lists** | §3 List type + §10 Formatting (fenced code blocks for multi-line commands/output) |
 | **prose-directness** | §4 Sentence-level rules (impersonal-subject directness) |
 
-Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms — those belong to Vale and Dale respectively.
+Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms — those belong to Vale and Dale respectively. (Heading case here means the H1 case Vale's `NetwrixKB.HeadingCase` checks — the §12 exception for articles with no body H1 is not covered by Vale and still applies; check the frontmatter `title` value's case directly on those.)
 
-**Naming note:** `links` and `images` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, bolding/path formatting, and keyword/description quality — see `derek/SKILL.md`). Running `/derek` directly on a file does not cover links or images; only `kb-pr-open` and `kb-pr-review` do.
+**Naming note:** `links`, `images`, `formatting: lists`, and `prose-directness` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check any of them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, and bolding/inline-code/path formatting — see `derek/SKILL.md`'s Review Areas table). Running `/derek` directly on a file does not cover those four areas; only `kb-pr-open` and `kb-pr-review` do.
 
 **KB Editing Conventions Scan (Derek subsection).** In addition to the areas table above, run the checklist below on every file. These are mechanical scan patterns codified during batch reviews; they map to the canonical rulebook at `.claude/references/kb-editing-conventions.md`. Do not duplicate the rulebook's full text here — treat the checklist as the minimum sweep. If a batch surfaces a new pattern, amend the rulebook and add the corresponding scan row here in the next PR.
 

From 60424c8c2b01f47fd749a337088f7e47533c00dd Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 09:56:03 -0700
Subject: [PATCH 11/20] Address tenth code review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- §13's product-ID carve-out header said "three values are exceptions
  to the strict-match rule" but the first bullet (onesecure) said to
  flag and correct it - contradicting both the header and its own
  sibling bullets' "never flag." Restructured so only general/
  recoveryad are labeled carve-outs; onesecure is explicitly "always
  flag."
- Scan row 8's "repetition-signaled clusters" claim had no home left
  in §1 Gate A after extraction - the base rule's thin "Remove X"-
  cluster merge criterion never made it into the consolidated section.
  Restored it as Gate A's second merge criterion.
- The precedence preamble claimed exactly two deliberate rulebook-vs-
  style-guide elaborations; two more exist in the extracted text
  (sidebar_label truncation as a mechanical Required fix vs. the style
  guide's softer "may be shortened," and the knowledge_article_id
  presence-is-informational policy vs. the style guide's unqualified
  Required-field listing). Added both to the list.
- Synced kb-pr-review's scan-row label wording to match kb-pr-open's
  exactly (both now say "as of this writing; recount if...").
- Moved the "don't flag > **NOTE:** blockquotes as :::note admonitions"
  line out of kb-pr-review's title:semantic row (where it has nothing
  to do with titles) into rulebook §5 Callout severity, its actual
  home; kb-pr-open never had the stray copy.
- Added a one-line carve-out to the rulebook preamble noting Derek
  doesn't apply §8/§16, so "apply during the derek review" doesn't
  read as covering areas Derek's own Review Areas table excludes.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 20 +++++++++++++-------
 .claude/skills/kb-pr-review/SKILL.md         |  4 ++--
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index 5c309be03e..59e52b9bae 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -2,15 +2,20 @@
 
 Comprehensive KB editing rulebook covering frontmatter, article type identification, article structure, structure/step condensation, list types, sentence-level rules, callouts, bolding, overview quality, links, placeholders, formatting, cross-section consistency, titles, and images.
 
-Apply during the `kb-pr-open` preemptive scan, the `kb-pr-review` review pass, and the `derek` review on every KB batch. This document is the canonical rulebook for these three skills — `derek`, `kb-pr-open`, and `kb-pr-review` all read it rather than duplicating its content, and it takes precedence over anything a skill might otherwise infer on its own. It is a derived, machine-oriented elaboration of `kb_style_guide.md` (the published, human-facing standard), not a replacement for it — where the two disagree, that is a bug in this rulebook, not a case for the rulebook to override the published standard. Amend it via PR when a batch surfaces a new pattern, and reconcile back to `kb_style_guide.md` in the same PR if the change affects a rule stated there.
+Apply during the `kb-pr-open` preemptive scan, the `kb-pr-review` review pass, and the `derek` review on every KB batch. This document is the canonical rulebook for these three skills — `derek`, `kb-pr-open`, and `kb-pr-review` all read it rather than duplicating its content, and it takes precedence over anything a skill might otherwise infer on its own. `derek` does not apply every section here: see `derek/SKILL.md`'s Review Areas table for its actual scope, which excludes §8 Links and §16 Images (those are `kb-pr-open`'s and `kb-pr-review`'s job, requiring filesystem resolution outside Derek's single-file model). It is a derived, machine-oriented elaboration of `kb_style_guide.md` (the published, human-facing standard), not a replacement for it — where the two disagree, that is a bug in this rulebook, not a case for the rulebook to override the published standard. Amend it via PR when a batch surfaces a new pattern, and reconcile back to `kb_style_guide.md` in the same PR if the change affects a rule stated there.
 
-Two current rules read as disagreements with the style guide's literal wording but are deliberate elaborations, not bugs — do not "fix" them back to the absolute reading without a real decision, the same way the exceptions in §13 and elsewhere are deliberate: **§12's product-name-in-title** sharpens the style guide's absolute "do not include product names in titles" into a general rule with a stated soft-reminder carve-out for genuinely distinguishing component names. **§13's title/H1 row** clarifies that a body with no H1 is a valid state (Docusaurus renders the frontmatter `title` as the H1 when the body has none), not a violation of the style guide's "the article title is always H1" line, which is about heading level, not literal presence.
+Four current rules read as disagreements with the style guide's literal wording but are deliberate elaborations, not bugs — do not "fix" them back to the absolute reading without a real decision, the same way the exceptions in §13 and elsewhere are deliberate:
+
+- **§12's product-name-in-title** sharpens the style guide's absolute "do not include product names in titles" into a general rule with a stated soft-reminder carve-out for genuinely distinguishing component names.
+- **§13's title/H1 row** clarifies that a body with no H1 is a valid state (Docusaurus renders the frontmatter `title` as the H1 when the body has none), not a violation of the style guide's "the article title is always H1" line, which is about heading level, not literal presence.
+- **§12/§13's `sidebar_label` "must not be truncated vs. `title`"** is a stricter, mechanically checkable reading of the style guide's "may be shortened if the title is very long" — the style guide doesn't forbid shortening, but doesn't define "very long" either; this rulebook resolves the ambiguity in favor of flagging any truncation as a Required fix rather than guessing at a length threshold.
+- **§13's `knowledge_article_id` presence/absence-is-informational policy** treats the field's absence as valid for natively authored articles, where the style guide lists it under Required fields with no optionality note. This is the reconciled policy this PR adopted (`kb-pr-open`'s pre-existing design) over the contradictory alternative `kb-pr-review` previously stated — a deliberate call, not an oversight.
 
 ## 1. Heading/step structure
 
 **Right-size step groups before applying `Step N —` normalization.** This is a two-gate rule.
 
-- **Gate A — Consolidate first.** Before applying any `Step N — <Label>` normalization, evaluate each candidate subheading against a substance test. A subheading is a merge candidate when it contains ≤1 action step *and* that action reads as prep/cleanup for an adjacent group — e.g., "Stop Services" or "Start Services" bracketing an install step, "Save and Exit" trailing a config edit, a lone "Restart the Agent" after a settings change. Fold merge candidates into the neighboring subheading. Only substantive subheadings count toward Gate B.
+- **Gate A — Consolidate first.** Before applying any `Step N — <Label>` normalization, evaluate each candidate subheading against a substance test. A subheading is a merge candidate under either of two criteria: (1) it contains ≤1 action step *and* that action reads as prep/cleanup for an adjacent group — e.g., "Stop Services" or "Start Services" bracketing an install step, "Save and Exit" trailing a config edit, a lone "Restart the Agent" after a settings change; or (2) it's one of a cluster of thin "Remove X"-style subheadings that are really line-items off a single logical task, rather than distinct procedures. Fold merge candidates into the neighboring subheading. Only substantive subheadings count toward Gate B.
 - **Gate B — Normalize.** If ≥3 substantive subheadings remain after Gate A **and represent sequential steps of the same procedure**, apply `Step N — <Label>` (em dash, not colon) to that set. The count excludes subheadings that are a categorically different kind of section — most commonly a `Troubleshooting`/exception-handling subheading — even when it sits at the exact same heading depth as the procedural subheadings it follows. Troubleshooting content isn't a step in the sequence; it doesn't count toward the Gate B threshold, and it doesn't receive a `Step N —` label itself (nor does anything nested beneath it). Normalize any pre-existing `Step N:` to match. Does NOT apply to parallel-alternative subheadings (Windows/Linux) — keep those descriptive. See also [[feedback_kb_step_subheadings]].
 - **Under-fragmentation — the mirror problem.** A single `## Instructions` or `## Resolution` section holding two or more distinct activities (locate a log, then look up an error code; edit a config, then verify the login flow) with no subheadings is as broken as over-fragmentation. Split by distinct activity; use subheadings once there are two or more real activities.
 - **Action described as trailing prose** — an action that logically belongs in the numbered sequence but sits as a trailing paragraph (e.g., a "start the services" instruction written as prose after the last numbered step) gets pulled into the sequence as its own numbered step, matching the structure of parallel actions in the article.
@@ -65,6 +70,7 @@ All three are `###` siblings under `## Instructions`, but `Troubleshooting` is a
 
 ## 5. Callout severity
 
+- **A `> **NOTE:**` blockquote is correct KB format, not a finding.** Do not flag it as a Docusaurus `:::note` admonition that needs converting — it's already in the target blockquote form.
 - **NOTE vs IMPORTANT is a judgment call, not interchangeable by default.** Supplementary/contextual info stays NOTE. Information that affects correctness or causes a real problem if skipped (e.g., a config-change timing caveat that could cause a false test result) should be IMPORTANT. Revisit per file rather than assuming the original author chose correctly.
 - **Blank line required before any NOTE/IMPORTANT blockquote.**
 - **Only two blockquote severities exist: `NOTE` and `IMPORTANT`.** This applies whether the callout is currently Docusaurus `:::` admonition syntax or already a blockquote with the wrong severity label — flag both:
@@ -186,11 +192,11 @@ All KB articles must begin with a frontmatter block. Check that all required fie
 | `tags` | Present and includes `kb` |
 | `knowledge_article_id` | See policy below |
 
-**Product ID carve-outs.** Three values are exceptions to the strict-match rule:
+**Product ID exceptions.** Three non-canonical values need special handling — only two of them are carve-outs (never flag); the third is always a Required fix, not an exception to flagging:
 
-- `onesecure` (5 files) has a real target — flag and correct to `1secure`, the actual `products.js` ID. This is a normal typo/legacy-value correction, not a carve-out.
-- `general` (44 files under `docs/kb/general/`) has no valid `products.js` target — cross-product content with no corresponding product. Never flag.
-- `recoveryad` (1 file) has no single valid target — `scripts/copy-kb-to-versions.mjs` maps both `recoveryforactivedirectory` and `identityrecovery` to this KB folder, so there are two equally defensible IDs and no way to pick one mechanically. Never flag; ask which product the article is actually about instead of guessing.
+- **Always flag — `onesecure` (5 files) has a real target.** Correct to `1secure`, the actual `products.js` ID. This is a normal typo/legacy-value correction like any other wrong `products` value, not a carve-out.
+- **Never flag — `general` (44 files under `docs/kb/general/`) has no valid `products.js` target.** Cross-product content with no corresponding product.
+- **Never flag — `recoveryad` (1 file) has no single valid target.** `scripts/copy-kb-to-versions.mjs` maps both `recoveryforactivedirectory` and `identityrecovery` to this KB folder, so there are two equally defensible IDs and no way to pick one mechanically. Ask which product the article is actually about instead of guessing.
 
 Product ID hyphenation is otherwise real migration debt: ~300 files across `directory-manager`/`access-analyzer`/`data-classification` still use the non-canonical hyphenated form. The strict `products.js`-exact rule stands; this is tracked as debt, not a reason to loosen the rule.
 
diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md
index 73564469a4..b3bf1b11db 100644
--- a/.claude/skills/kb-pr-review/SKILL.md
+++ b/.claude/skills/kb-pr-review/SKILL.md
@@ -168,7 +168,7 @@ For each file in `KB_FILES`:
 | **article-type: qa-format** | §15 Article Structure (Q&A question format) |
 | **article-type: heading-labels** | §15 Article Structure (pluralization) |
 | **title: mechanical** | §12 Titles (mechanical style corrections) |
-| **title: semantic** | §12 Titles (semantic reframes). Do NOT flag `> **NOTE:**` blockquote callouts — this is correct KB format, not a Docusaurus `:::note` admonition. |
+| **title: semantic** | §12 Titles (semantic reframes) |
 | **product-names** | `kb_style_guide.md` Product Names table. Flag incorrect abbreviations (NDC, NPS, NTA, etc.) and wrong `products` field values (for example, hyphens vs. underscores) per rulebook §13. |
 | **keywords-quality** | §13 Frontmatter (`keywords` row) |
 | **images: location** | §16 Images |
@@ -256,7 +256,7 @@ Per-file structure:
 
 - One row each for Vale and Dale.
 - One row for `Derek (N checks)` — a single roll-up covering every frontmatter sub-field (`title`, `description`, `sidebar_label`, `keywords`, `products`, `tags`, `knowledge_article_id`) and every other named area (`article-type: structure`, `article-type: qa-format`, `article-type: heading-labels`, `title: mechanical`, `title: semantic`, `product-names`, `keywords-quality`, `images: location`, `images: external-refs`, `images: alt-text`, `links`, `formatting: bold/backticks`, `formatting: lists`, `prose directness`). N is the total count of sub-fields + areas — 21 as of this writing; recount if the areas table changes. Status cell: `N/N scanned, <total findings> findings in <count> areas` (or `✓ Clean` if zero findings).
-- One row for the `kb-editing-conventions scan (rows 1–23)`.
+- One row for the `kb-editing-conventions scan (rows 1–23 as of this writing; recount if the scan table changes)`.
 - One row for `Cross-section consistency (6 patterns as of this writing; recount if the cross-section table changes)`.
 
 No per-area or per-sub-field rows appear in the Overview table in default mode, under any circumstance — that detail lives only in the Derek findings table below. The Overview table is a fixed 5 rows regardless of file size; that fixed shape is the coverage receipt for the tool level, backed by the Coverage discipline enumeration for the check level.

From 1bef9b1a39b165a20f8fd67b8eb56870fb13c1de Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 10:14:45 -0700
Subject: [PATCH 12/20] Address eleventh code review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rulebook preamble's Derek-scope carve-out named only two excluded
  sections (§8, §16) as if that were the complete exclusion list, when
  Derek's Review Areas table actually includes just six sections total
  (§5, §6, §12-§15). Restated as an inclusion list - the same fix
  already applied to both PR skills' "Naming note" - so the preamble
  isn't a third, less accurate copy of the same scope statement.
- The heading-case Vale-deferral parenthetical (added last round to
  both PR skills) never reached derek/SKILL.md itself. Derek's own
  "what Vale already handles" list still said heading case
  unqualified, which would make an agent resolve the no-H1 exception
  against its own closer, more specific instruction and skip the
  finding §12 exists to catch. Added the same parenthetical to Derek's
  list entry.
- Added an explicit "Derek reports; it never edits" guard. The
  rulebook sections Derek now reads are written in fixer voice for the
  applying skills ("convert/relabel," "must be wrapped in backticks")
  with no per-skill framing to signal report-only intent anymore.
- Nits: added line-number guidance for Derek's two new areas (§5, §6);
  consolidated the sidebar_label truncation rule to one copy in §13,
  with §12 pointing to it instead of restating it.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 6 +++---
 .claude/skills/derek/SKILL.md                | 5 ++++-
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index 59e52b9bae..368426549b 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -2,13 +2,13 @@
 
 Comprehensive KB editing rulebook covering frontmatter, article type identification, article structure, structure/step condensation, list types, sentence-level rules, callouts, bolding, overview quality, links, placeholders, formatting, cross-section consistency, titles, and images.
 
-Apply during the `kb-pr-open` preemptive scan, the `kb-pr-review` review pass, and the `derek` review on every KB batch. This document is the canonical rulebook for these three skills — `derek`, `kb-pr-open`, and `kb-pr-review` all read it rather than duplicating its content, and it takes precedence over anything a skill might otherwise infer on its own. `derek` does not apply every section here: see `derek/SKILL.md`'s Review Areas table for its actual scope, which excludes §8 Links and §16 Images (those are `kb-pr-open`'s and `kb-pr-review`'s job, requiring filesystem resolution outside Derek's single-file model). It is a derived, machine-oriented elaboration of `kb_style_guide.md` (the published, human-facing standard), not a replacement for it — where the two disagree, that is a bug in this rulebook, not a case for the rulebook to override the published standard. Amend it via PR when a batch surfaces a new pattern, and reconcile back to `kb_style_guide.md` in the same PR if the change affects a rule stated there.
+Apply during the `kb-pr-open` preemptive scan, the `kb-pr-review` review pass, and the `derek` review on every KB batch. This document is the canonical rulebook for these three skills — `derek`, `kb-pr-open`, and `kb-pr-review` all read it rather than duplicating its content, and it takes precedence over anything a skill might otherwise infer on its own. `derek` applies only §5, §6, §12, §13, §14, and §15 — see `derek/SKILL.md`'s Review Areas table. Every other section (step structure, condensation, list type, sentence-level rules, overview quality, links, placeholders, general formatting, cross-section consistency, images) belongs to `kb-pr-open` and `kb-pr-review`, not to a standalone `/derek` run. It is a derived, machine-oriented elaboration of `kb_style_guide.md` (the published, human-facing standard), not a replacement for it — where the two disagree, that is a bug in this rulebook, not a case for the rulebook to override the published standard. Amend it via PR when a batch surfaces a new pattern, and reconcile back to `kb_style_guide.md` in the same PR if the change affects a rule stated there.
 
 Four current rules read as disagreements with the style guide's literal wording but are deliberate elaborations, not bugs — do not "fix" them back to the absolute reading without a real decision, the same way the exceptions in §13 and elsewhere are deliberate:
 
 - **§12's product-name-in-title** sharpens the style guide's absolute "do not include product names in titles" into a general rule with a stated soft-reminder carve-out for genuinely distinguishing component names.
 - **§13's title/H1 row** clarifies that a body with no H1 is a valid state (Docusaurus renders the frontmatter `title` as the H1 when the body has none), not a violation of the style guide's "the article title is always H1" line, which is about heading level, not literal presence.
-- **§12/§13's `sidebar_label` "must not be truncated vs. `title`"** is a stricter, mechanically checkable reading of the style guide's "may be shortened if the title is very long" — the style guide doesn't forbid shortening, but doesn't define "very long" either; this rulebook resolves the ambiguity in favor of flagging any truncation as a Required fix rather than guessing at a length threshold.
+- **§13's `sidebar_label` "must not be truncated vs. `title`"** (referenced from §12's mechanical-fixes list) is a stricter, mechanically checkable reading of the style guide's "may be shortened if the title is very long" — the style guide doesn't forbid shortening, but doesn't define "very long" either; this rulebook resolves the ambiguity in favor of flagging any truncation as a Required fix rather than guessing at a length threshold.
 - **§13's `knowledge_article_id` presence/absence-is-informational policy** treats the field's absence as valid for natively authored articles, where the style guide lists it under Required fields with no optionality note. This is the reconciled policy this PR adopted (`kb-pr-open`'s pre-existing design) over the contradictory alternative `kb-pr-review` previously stated — a deliberate call, not an oversight.
 
 ## 1. Heading/step structure
@@ -167,7 +167,7 @@ Title findings split into two categories based on whether the change is mechanic
     - `TraceLogger ERROR System.Net.Sockets.SocketException Address already in use` → `TraceLogger Error - Address Already in Use`
     - `RemotePlatformDiscovery Could not get credentials from ...` → `Remote Platform Discovery Error - Could Not Get Credentials`
   - This normalized form is exemption (b) of the two `Error:` prefix exemptions stated under "Base title format by article type" above — the inline `Error` word already disambiguates the title, so don't also prepend `Error:`.
-- **H1 / `sidebar_label` consistency:** `sidebar_label` must not be truncated vs. `title`.
+- **H1 / `sidebar_label` consistency:** see §13's `sidebar_label` row for the truncation rule.
 
 These changes are low-ambiguity and preserve reader recognition — the article is still "the one about X," just with corrected surface form. Apply them per the normal fix loop.
 
diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index 6ec5a21e67..68a9af52c8 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -10,7 +10,7 @@ You are Derek, a KB article quality reviewer for Netwrix. Your job is to review
 
 **What Vale already handles — do not re-flag these:**
 - Contractions (`NetwrixKB.Contractions`)
-- Heading case (`NetwrixKB.HeadingCase`)
+- Heading case (`NetwrixKB.HeadingCase`) — H1 case only. The rulebook §12 no-H1 exception is not covered by Vale and still applies: on an article with no body H1, check the frontmatter `title` value's case directly and flag it as a Required fix if it's wrong.
 - "Please" in instructions (`NetwrixKB.Please`)
 - "Note that" inline (`NetwrixKB.NoteThat`)
 - Impersonal constructions (`NetwrixKB.ImpersonalFiller`)
@@ -91,8 +91,11 @@ If no issues are found, print the assessment line followed by "Derek found no is
 - Missing required heading: use line `1`; include the expected heading template in Message
 - Title format violation: use the line number of the H1 heading; if the body has no H1, use line `1` (the `title` frontmatter field) instead
 - Product name violation: use the line number of the offending text
+- Callout severity (§5) or bolding/inline-code/path (§6) violation: use the line number of the offending text
 - Keywords or description quality issue: use the line number of the field in frontmatter
 
 # Troubleshooting
 
 Never re-flag issues that Vale or Dale already catch. Never respond with anything beyond the assessment line, the output table, and the soft-reminder notes defined in the Output section above.
+
+**Derek reports; it never edits the article.** The rulebook sections Derek reads are written in fixer voice for the skills that apply fixes (`kb-pr-open`, `kb-pr-review`) — "convert/relabel," "must be wrapped in backticks," "get stripped." Derek translates each into a table row; it does not act on the imperative itself. Never edit, write, or otherwise modify the article file being reviewed.

From 7d65c4ab4c4ebc563932dd48ca6321b8e8965399 Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 10:31:07 -0700
Subject: [PATCH 13/20] Address twelfth code review round: sync
 title/H1/sidebar_label on any one fix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

§13 requires frontmatter title, H1, and sidebar_label to agree, but
nothing said to keep them in sync when correcting just one — including
a Vale HeadingCase fix that rewrites only the H1 line. That fix would
otherwise introduce a fresh §13 violation immediately after Derek's
pass reported clean, with nothing in the same run left to catch it.
Added an explicit "fix all three together" instruction to §12's
mechanical-fixes list; both kb-pr-open and kb-pr-review inherit it
automatically since they already route title:mechanical to §12.

The other item from this round (Derek's frontmatter/title scope
correctly growing louder on ~300 legacy hyphenated-product-ID files)
is a real, intended behavior change already documented as accepted
migration debt in the rulebook preamble - not a defect, no fix needed.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index 368426549b..693ed68fea 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -171,6 +171,8 @@ Title findings split into two categories based on whether the change is mechanic
 
 These changes are low-ambiguity and preserve reader recognition — the article is still "the one about X," just with corrected surface form. Apply them per the normal fix loop.
 
+**Fix all three together, not just the one that was flagged.** Frontmatter `title`, the body H1, and `sidebar_label` must stay in sync (per §13's `title` and `sidebar_label` rows). Any mechanical fix above that changes one of them — including a Vale `NetwrixKB.HeadingCase` fix that rewrites only the H1 line — must update the other two in the same edit. Fixing the H1 and leaving the frontmatter `title` (or `sidebar_label`) stale creates a fresh §13 violation that nothing in a single fix pass re-checks.
+
 ### Semantic reframes — soft reminders / judgment calls (author/reviewer decides, never auto-apply)
 
 - **Product name in title** (e.g., "Antivirus Exclusions for Netwrix Data Classification" → drop "for Netwrix Data Classification"). If a product component name (client, agent, add-on) is essential to distinguishing the article from others about the same product, flag it as a judgment call rather than a required fix.

From 88386829565d3e3a97e857a4c933adfe237ee252 Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 10:42:29 -0700
Subject: [PATCH 14/20] Address thirteenth code review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Derek's output contract had no channel for §13's low-priority
  keyword observation (a keyword absent from the body but a plausible
  search term) - explicitly not a Required fix per §13's own text, but
  also not one of Derek's two defined soft-reminder types. Added it as
  a third soft-reminder bullet, matching the severity kb-pr-open
  already handles correctly for the same rule.
- Nit: Derek's links/images exclusion rationale ("outside Derek's
  single-file review model") didn't actually distinguish those checks
  from two areas Derek does own - the §13 products.js lookup and the
  Product Names "verify against product docs" check are also outside
  the article file. Rewrote the rationale around what actually
  differs: link/image resolution is an unbounded search across
  docs/kb/**, while products.js and product-docs checks are one fixed
  lookup against one known source.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/skills/derek/SKILL.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index 68a9af52c8..8f0aeec1a3 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -49,7 +49,7 @@ Read the named rulebook section before applying each area — do not hard-code r
 | Callout/admonition format | §5 Callout severity |
 | Bolding, inline code, path formatting | §6 Bolding and inline code |
 
-Links and images are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — those checks require resolving link targets and image locations on disk across the repo, outside Derek's single-file review model. Everything else is in scope: the six rows in the table above, plus Product Names, which lives in its own section below the table rather than as a seventh row. That totals the same seven areas the Overview line lists — not a row-by-row match (the Overview folds keyword/description quality into frontmatter and splits "article type and structure" differently than the table's separate §14/§15 rows), just the same overall scope.
+Links and images are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — resolving a link target or an image's location means searching across `docs/kb/**` and `docs/<product>/<version>/**` for a matching file, an unbounded lookup with no fixed answer. That's different from the fixed-location lookups Derek does do — checking a `products` value against `src/config/products.js` (§13) or a UI name against the product's own docs (Product Names, below) — each of those is one lookup against one known source, not a search. Everything else is in scope: the six rows in the table above, plus Product Names, which lives in its own section below the table rather than as a seventh row. That totals the same seven areas the Overview line lists — not a row-by-row match (the Overview folds keyword/description quality into frontmatter and splits "article type and structure" differently than the table's separate §14/§15 rows), just the same overall scope.
 
 ## Product Names
 
@@ -82,6 +82,7 @@ If no issues are found, print the assessment line followed by "Derek found no is
   - Placeholder value: `> **Note:** \`knowledge_article_id\` looks like a placeholder. Populate it with the real ID if applicable, or leave as-is if no ID applies.`
   - Field missing entirely: `> **Note:** \`knowledge_article_id\` is not present. This is a valid state for a natively authored article — no action needed unless the article originated from an external ticket.`
 - Rulebook §12's semantic title reframes (product-name-in-title, article-type/title mismatch) — never a table row, never counted, regardless of how many apply: `> **Note:** Semantic title reframe — <describe the issue>. Suggested alternative(s): <title>, <title>. This is a judgment call — the current title is not wrong; decide whether to change it.`
+- Rulebook §13's low-priority keyword observation (a keyword absent from the body but a plausible customer search term) — not a Required fix, never a table row, never counted: `> **Note:** Keyword \`<term>\` doesn't appear in the article body but is a plausible search term. Low-priority — no action required.`
 
 **Consolidating structure violations:** When multiple required headings are missing for the same article type, use a single `structure-article-type` row. List all missing headings in the Message column. If fixing the title would change the article type and resolve the structure issue automatically, note that in the Message.
 

From 2abe6e0a272fd9bf21cad6beea46b22c89d74d93 Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 11:26:14 -0700
Subject: [PATCH 15/20] Address fourteenth code review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- §14's Q&A+Overview edge-case note pointed at
  docs/kb/accessanalyzer-2601/kb-article-template.md as the one file
  that hits it - verified that file actually has Symptom/Cause/
  Resolution headings too, so under the Resolution-first rule it
  classifies as Resolution, not the Q&A/Overview collision the note
  describes. Verified corpus-wide the edge case hits zero files
  (every ## Question+## Overview file also has a Symptom/Cause/
  Resolution heading). Rewrote the note to state that accurately
  instead of citing a file that demonstrates the opposite.
- "Heading case ... H1 case only" (derek) and the matching parenthetical
  in both PR skills understated NetwrixKB.HeadingCase's actual scope -
  it's scope: heading, firing on every heading level, not just the H1.
  As written, the do-not-re-flag list read as license to flag H2-H6
  case as a new finding, duplicating Vale. The real gap is narrower:
  an article with no body H1 at all, where Vale's heading-scoped rule
  never runs on anything. Fixed all three copies to state the correct
  scope and the correct (narrower) gap.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 2 +-
 .claude/skills/derek/SKILL.md                | 2 +-
 .claude/skills/kb-pr-open/SKILL.md           | 2 +-
 .claude/skills/kb-pr-review/SKILL.md         | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index 693ed68fea..6f1cad8c5e 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -228,7 +228,7 @@ Determine the article type from its structure first — this is authoritative an
 - Contains `## Overview` or `## Instructions` (or both) → **How-To (Instructions)**. Same partial-match tolerance.
 - Contains `## Question` or `## Answer` (or both) → **How-To (Q&A)**. If only one is present, §15 flags the other as missing — don't fall through to a different classification.
 
-**Known edge case (not worth reordering for):** checking Instructions before Q&A means a Q&A article that happens to carry an `## Overview` heading classifies as How-To (Instructions) instead, and gets told to add `## Instructions`. This is the mirror risk of the Resolution-first ordering above, but in the opposite direction. In the current corpus this hits exactly one file, `docs/kb/accessanalyzer-2601/kb-article-template.md` — a multi-template reference file containing all three article-type templates concatenated, not a real article — so it isn't worth reordering for. Documented here so it isn't mistaken for a new bug later.
+**Known edge case (not worth reordering for):** checking Instructions before Q&A means a Q&A article that happens to carry an `## Overview` heading — with no Symptom/Cause/Resolution heading, which would otherwise claim it first under the Resolution-first rule above — classifies as How-To (Instructions) instead, and gets told to add `## Instructions`. This is the mirror risk of the Resolution-first ordering, but in the opposite direction. It hits zero files in the current corpus (checked: every `## Question`+`## Overview` file also has a Symptom/Cause/Resolution heading and classifies as Resolution instead, per the Resolution-first rule — including `docs/kb/accessanalyzer-2601/kb-article-template.md`, a multi-template reference file containing all three article-type templates concatenated, which is a Resolution match, not an instance of this edge case). Documented here so a future maintainer doesn't mistake it for a new bug when a file eventually does hit it.
 
 If none of these section structures are present, fall back to the title:
 
diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index 8f0aeec1a3..9304d01d04 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -10,7 +10,7 @@ You are Derek, a KB article quality reviewer for Netwrix. Your job is to review
 
 **What Vale already handles — do not re-flag these:**
 - Contractions (`NetwrixKB.Contractions`)
-- Heading case (`NetwrixKB.HeadingCase`) — H1 case only. The rulebook §12 no-H1 exception is not covered by Vale and still applies: on an article with no body H1, check the frontmatter `title` value's case directly and flag it as a Required fix if it's wrong.
+- Heading case (`NetwrixKB.HeadingCase`) — all heading levels, `scope: heading`. Not covered by Vale: an article with no body H1 at all — there, check the frontmatter `title` value's case directly (rulebook §12) and flag it as a Required fix if it's wrong.
 - "Please" in instructions (`NetwrixKB.Please`)
 - "Note that" inline (`NetwrixKB.NoteThat`)
 - Impersonal constructions (`NetwrixKB.ImpersonalFiller`)
diff --git a/.claude/skills/kb-pr-open/SKILL.md b/.claude/skills/kb-pr-open/SKILL.md
index a99b4386e0..5775e71530 100644
--- a/.claude/skills/kb-pr-open/SKILL.md
+++ b/.claude/skills/kb-pr-open/SKILL.md
@@ -94,7 +94,7 @@ If Vale is not installed or returns an error, note this in the report and contin
 
 **Naming note:** `links`, `images`, `formatting: lists`, and `prose-directness` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check any of them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, and bolding/inline-code/path formatting — see `derek/SKILL.md`'s Review Areas table). Running `/derek` directly on a file does not cover those four areas; only `kb-pr-open` and `kb-pr-review` do.
 
-Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms in this section — those belong to Vale and Dale respectively. (Heading case here means the H1 case Vale's `NetwrixKB.HeadingCase` checks — the §12 exception for articles with no body H1 is not covered by Vale and still applies; check the frontmatter `title` value's case directly on those.)
+Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms in this section — those belong to Vale and Dale respectively. (`NetwrixKB.HeadingCase` covers all heading levels, not just the H1. The one gap is an article with no body H1 at all — Vale's heading-scoped rule never evaluates that case, so the §12 exception applies there: check the frontmatter `title` value's case directly.)
 
 > **IMPORTANT:** When applying fixes, follow `kb_style_guide.md`, not `docs/CLAUDE.md`. KB articles differ from the docs style guide on contractions (write out in full) and heading case (title case).
 
diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md
index b3bf1b11db..4445f26611 100644
--- a/.claude/skills/kb-pr-review/SKILL.md
+++ b/.claude/skills/kb-pr-review/SKILL.md
@@ -179,7 +179,7 @@ For each file in `KB_FILES`:
 | **formatting: lists** | §3 List type + §10 Formatting (fenced code blocks for multi-line commands/output) |
 | **prose-directness** | §4 Sentence-level rules (impersonal-subject directness) |
 
-Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms — those belong to Vale and Dale respectively. (Heading case here means the H1 case Vale's `NetwrixKB.HeadingCase` checks — the §12 exception for articles with no body H1 is not covered by Vale and still applies; check the frontmatter `title` value's case directly on those.)
+Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms — those belong to Vale and Dale respectively. (`NetwrixKB.HeadingCase` covers all heading levels, not just the H1. The one gap is an article with no body H1 at all — Vale's heading-scoped rule never evaluates that case, so the §12 exception applies there: check the frontmatter `title` value's case directly.)
 
 **Naming note:** `links`, `images`, `formatting: lists`, and `prose-directness` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check any of them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, and bolding/inline-code/path formatting — see `derek/SKILL.md`'s Review Areas table). Running `/derek` directly on a file does not cover those four areas; only `kb-pr-open` and `kb-pr-review` do.
 

From 89511ec14031ff199c05814b0d7c6a600ebf424f Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 12:13:42 -0700
Subject: [PATCH 16/20] Address fifteenth code review round: keep authoring
 notes out of the report

Both skills' Overview-table row-label instructions baked "as of this
writing; recount if the table changes" directly into the literal
string used as the row label - that maintenance note would render
verbatim in the posted PR review comment. Moved it to prose next to
the instruction, kept the row labels short (matching the example
output blocks, which already used the short form).

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/skills/kb-pr-open/SKILL.md   | 6 ++++--
 .claude/skills/kb-pr-review/SKILL.md | 6 ++++--
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/kb-pr-open/SKILL.md b/.claude/skills/kb-pr-open/SKILL.md
index 5775e71530..a3ae346e38 100644
--- a/.claude/skills/kb-pr-open/SKILL.md
+++ b/.claude/skills/kb-pr-open/SKILL.md
@@ -175,8 +175,10 @@ Structure per file:
 
 - One row each for Vale and Dale.
 - One row for `Derek (N checks)` — a single roll-up covering every frontmatter sub-field (`title`, `description`, `sidebar_label`, `keywords`, `products`, `tags`, `knowledge_article_id`) and every other named area (`article-type: structure`, `article-type: qa-format`, `article-type: heading-labels`, `title: mechanical`, `title: semantic`, `product-names`, `keywords-quality`, `images: location`, `images: external-refs`, `images: alt-text`, `links`, `formatting: bold/backticks`, `formatting: lists`, `prose directness`). N is the total count of sub-fields + areas — 21 as of this writing; recount if the areas table changes. Status cell: `N/N scanned, <total findings> findings in <count> areas` (or `✓ Clean` if zero findings).
-- One row for the `kb-editing-conventions scan (rows 1–23 as of this writing; recount if the scan table changes)`.
-- One row for `Cross-section consistency (6 patterns as of this writing; recount if the cross-section table changes)`.
+- One row for `kb-editing-conventions scan (23 rows)`.
+- One row for `Cross-section consistency (6 patterns)`.
+
+Row labels use the current counts (23 scan rows, 6 cross-section patterns) as of this writing — recount and update both the labels above and this note if either table's row count changes in a future batch. These are authoring notes for whoever edits this skill; they must not appear in the generated report itself.
 
 No per-area or per-sub-field rows appear in the Overview table in default mode, under any circumstance — that detail lives only in the Derek findings table below. The Overview table is a fixed 5 rows regardless of file size; that fixed shape is the coverage receipt for the tool level, backed by the Coverage discipline enumeration for the check level.
 
diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md
index 4445f26611..45bfe77426 100644
--- a/.claude/skills/kb-pr-review/SKILL.md
+++ b/.claude/skills/kb-pr-review/SKILL.md
@@ -256,8 +256,10 @@ Per-file structure:
 
 - One row each for Vale and Dale.
 - One row for `Derek (N checks)` — a single roll-up covering every frontmatter sub-field (`title`, `description`, `sidebar_label`, `keywords`, `products`, `tags`, `knowledge_article_id`) and every other named area (`article-type: structure`, `article-type: qa-format`, `article-type: heading-labels`, `title: mechanical`, `title: semantic`, `product-names`, `keywords-quality`, `images: location`, `images: external-refs`, `images: alt-text`, `links`, `formatting: bold/backticks`, `formatting: lists`, `prose directness`). N is the total count of sub-fields + areas — 21 as of this writing; recount if the areas table changes. Status cell: `N/N scanned, <total findings> findings in <count> areas` (or `✓ Clean` if zero findings).
-- One row for the `kb-editing-conventions scan (rows 1–23 as of this writing; recount if the scan table changes)`.
-- One row for `Cross-section consistency (6 patterns as of this writing; recount if the cross-section table changes)`.
+- One row for `kb-editing-conventions scan (23 rows)`.
+- One row for `Cross-section consistency (6 patterns)`.
+
+Row labels use the current counts (23 scan rows, 6 cross-section patterns) as of this writing — recount and update both the labels above and this note if either table's row count changes in a future batch. These are authoring notes for whoever edits this skill; they must not appear in the generated report itself.
 
 No per-area or per-sub-field rows appear in the Overview table in default mode, under any circumstance — that detail lives only in the Derek findings table below. The Overview table is a fixed 5 rows regardless of file size; that fixed shape is the coverage receipt for the tool level, backed by the Coverage discipline enumeration for the check level.
 

From 444912b5e3e52f50fc3c524fc9009e9ca81e71db Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 13:22:18 -0700
Subject: [PATCH 17/20] Address sixteenth code review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- §16's exclusion from Derek was justified by an "unbounded filesystem
  lookup" rationale that only actually applies to the location rule.
  external-refs (is this URL an external CDN link) and alt-text (does
  alt text just repeat the filename) are pure single-file text checks,
  same cost class as everything else in Derek's scope - dropping them
  had no real justification. Moved both into Derek's scope; kept
  location with kb-pr-open/kb-pr-review since it genuinely requires
  checking the filesystem beyond the article. Updated Derek's areas
  table, Overview line, description frontmatter, line-number guidance,
  and the rulebook preamble's inclusion list to match. This also fixed
  the "four areas" nit in both PR skills' naming notes for free - the
  excluded set is now exactly four rows (links, images: location,
  formatting: lists, prose-directness), matching the stated count.
- The precedence preamble's "four deliberate deviations" list missed
  two real ones: §6's action-target-only bolding rule (contradicts the
  style guide's unconditional "bold for UI elements...") and §13's
  products.js-authoritative rule (the style guide's own example
  frontmatter uses a non-canonical underscored value). Added both so
  a future reader doesn't "fix" either back to the literal reading.
- PR description now lists four /derek behavior changes instead of
  two: the previously-undocumented product-name-in-title downgrade
  (counted finding -> uncounted note) and the newly-in-scope callout-
  indent/bolding-consistency rules, plus a note on the images scope
  split.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 6 ++++--
 .claude/skills/derek/SKILL.md                | 9 +++++----
 .claude/skills/kb-pr-open/SKILL.md           | 2 +-
 .claude/skills/kb-pr-review/SKILL.md         | 2 +-
 CLAUDE.md                                    | 2 +-
 5 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index 6f1cad8c5e..005312af44 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -2,14 +2,16 @@
 
 Comprehensive KB editing rulebook covering frontmatter, article type identification, article structure, structure/step condensation, list types, sentence-level rules, callouts, bolding, overview quality, links, placeholders, formatting, cross-section consistency, titles, and images.
 
-Apply during the `kb-pr-open` preemptive scan, the `kb-pr-review` review pass, and the `derek` review on every KB batch. This document is the canonical rulebook for these three skills — `derek`, `kb-pr-open`, and `kb-pr-review` all read it rather than duplicating its content, and it takes precedence over anything a skill might otherwise infer on its own. `derek` applies only §5, §6, §12, §13, §14, and §15 — see `derek/SKILL.md`'s Review Areas table. Every other section (step structure, condensation, list type, sentence-level rules, overview quality, links, placeholders, general formatting, cross-section consistency, images) belongs to `kb-pr-open` and `kb-pr-review`, not to a standalone `/derek` run. It is a derived, machine-oriented elaboration of `kb_style_guide.md` (the published, human-facing standard), not a replacement for it — where the two disagree, that is a bug in this rulebook, not a case for the rulebook to override the published standard. Amend it via PR when a batch surfaces a new pattern, and reconcile back to `kb_style_guide.md` in the same PR if the change affects a rule stated there.
+Apply during the `kb-pr-open` preemptive scan, the `kb-pr-review` review pass, and the `derek` review on every KB batch. This document is the canonical rulebook for these three skills — `derek`, `kb-pr-open`, and `kb-pr-review` all read it rather than duplicating its content, and it takes precedence over anything a skill might otherwise infer on its own. `derek` applies §5, §6, §12, §13, §14, §15, and §16's external-references and alt-text rows only (not §16's location row) — see `derek/SKILL.md`'s Review Areas table. Every other section (step structure, condensation, list type, sentence-level rules, overview quality, links, placeholders, general formatting, cross-section consistency, and §16's image-location row) belongs to `kb-pr-open` and `kb-pr-review`, not to a standalone `/derek` run. It is a derived, machine-oriented elaboration of `kb_style_guide.md` (the published, human-facing standard), not a replacement for it — where the two disagree, that is a bug in this rulebook, not a case for the rulebook to override the published standard. Amend it via PR when a batch surfaces a new pattern, and reconcile back to `kb_style_guide.md` in the same PR if the change affects a rule stated there.
 
-Four current rules read as disagreements with the style guide's literal wording but are deliberate elaborations, not bugs — do not "fix" them back to the absolute reading without a real decision, the same way the exceptions in §13 and elsewhere are deliberate:
+Six current rules read as disagreements with the style guide's literal wording but are deliberate elaborations, not bugs — do not "fix" them back to the absolute reading without a real decision, the same way the exceptions in §13 and elsewhere are deliberate:
 
 - **§12's product-name-in-title** sharpens the style guide's absolute "do not include product names in titles" into a general rule with a stated soft-reminder carve-out for genuinely distinguishing component names.
 - **§13's title/H1 row** clarifies that a body with no H1 is a valid state (Docusaurus renders the frontmatter `title` as the H1 when the body has none), not a violation of the style guide's "the article title is always H1" line, which is about heading level, not literal presence.
 - **§13's `sidebar_label` "must not be truncated vs. `title`"** (referenced from §12's mechanical-fixes list) is a stricter, mechanically checkable reading of the style guide's "may be shortened if the title is very long" — the style guide doesn't forbid shortening, but doesn't define "very long" either; this rulebook resolves the ambiguity in favor of flagging any truncation as a Required fix rather than guessing at a length threshold.
 - **§13's `knowledge_article_id` presence/absence-is-informational policy** treats the field's absence as valid for natively authored articles, where the style guide lists it under Required fields with no optionality note. This is the reconciled policy this PR adopted (`kb-pr-open`'s pre-existing design) over the contradictory alternative `kb-pr-review` previously stated — a deliberate call, not an oversight.
+- **§6's "bold UI elements only when they're action targets in the current step"** narrows the style guide's unconditional "**bold** for UI elements, buttons, menu items, tabs, checkboxes, dropdown options, navigation steps, and form field names" to exclude contextual (non-acted-on) mentions. This is deliberate, pre-existing text both PR skills already flagged as a Required fix before this PR — not a new rulebook invention — and it survives the merge into the shared rulebook as-is.
+- **§13's `products.js`-is-authoritative-over-the-style-guide-table policy**, including the exact-match, no-hyphen/underscore format rule. The style guide's own example frontmatter block (`kb_style_guide.md` around line 211) uses `products: - enterprise_auditor`, an underscored, non-canonical value that this rule would flag — a known, pre-existing gap in the style guide's example, not a rulebook bug. `src/config/products.js` is the real authoritative source per `CLAUDE.md`'s own Architecture section; the style guide's table can lag it.
 
 ## 1. Heading/step structure
 
diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index 9304d01d04..a70cdc0e40 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: derek
-description: KB article quality reviewer. Run against KB articles in docs/kb/ to review frontmatter, article type and structure, title format, product names, callout format, bolding/path formatting, and keyword quality. Use when editing or reviewing any file under docs/kb/.
+description: KB article quality reviewer. Run against KB articles in docs/kb/ to review frontmatter, article type and structure, title format, product names, callout format, bolding/path formatting, image alt-text/external-references, and keyword quality. Use when editing or reviewing any file under docs/kb/.
 argument-hint: "[docs/kb/path/to/article.md]"
 ---
 
@@ -25,7 +25,7 @@ You are Derek, a KB article quality reviewer for Netwrix. Your job is to review
 - Wordiness
 - Undefined acronyms
 
-Derek focuses on what's left: frontmatter validity, article type and structure, title format, product name usage, callout/admonition format, bolding and inline-code/path formatting, and keyword/description quality.
+Derek focuses on what's left: frontmatter validity, article type and structure, title format, product name usage, callout/admonition format, bolding and inline-code/path formatting, image external-references and alt-text (not location), and keyword/description quality.
 
 # How to Review
 
@@ -48,8 +48,9 @@ Read the named rulebook section before applying each area — do not hard-code r
 | Title format (mechanical + semantic) | §12 Titles |
 | Callout/admonition format | §5 Callout severity |
 | Bolding, inline code, path formatting | §6 Bolding and inline code |
+| Images: external references, alt text (not location) | §16 Images — external references and alt text rows only |
 
-Links and images are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — resolving a link target or an image's location means searching across `docs/kb/**` and `docs/<product>/<version>/**` for a matching file, an unbounded lookup with no fixed answer. That's different from the fixed-location lookups Derek does do — checking a `products` value against `src/config/products.js` (§13) or a UI name against the product's own docs (Product Names, below) — each of those is one lookup against one known source, not a search. Everything else is in scope: the six rows in the table above, plus Product Names, which lives in its own section below the table rather than as a seventh row. That totals the same seven areas the Overview line lists — not a row-by-row match (the Overview folds keyword/description quality into frontmatter and splits "article type and structure" differently than the table's separate §14/§15 rows), just the same overall scope.
+Links, and image *location* specifically, are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — resolving a link target, or confirming whether a `0-images/` folder actually exists at the category level on disk (§16's location rule), means checking the filesystem beyond the article itself: an unbounded lookup with no fixed answer from the article's text alone. That's different from every other check in Derek's scope: a `products` value against `src/config/products.js` (§13), a UI name against the product's own docs (Product Names, below), or §16's external-references/alt-text rules — each of those is either one lookup against one known source, or a pure text check within the article (is this URL an external CDN link; does this alt text just repeat the filename) — never a search across the repo. Everything else is in scope: the seven rows in the table above, plus Product Names, which lives in its own section below the table rather than as an eighth row. That totals eight areas — the seven-area Overview line below should be read as naming the same overall scope, not a strict count (it folds keyword/description quality into frontmatter and doesn't itemize images separately).
 
 ## Product Names
 
@@ -92,7 +93,7 @@ If no issues are found, print the assessment line followed by "Derek found no is
 - Missing required heading: use line `1`; include the expected heading template in Message
 - Title format violation: use the line number of the H1 heading; if the body has no H1, use line `1` (the `title` frontmatter field) instead
 - Product name violation: use the line number of the offending text
-- Callout severity (§5) or bolding/inline-code/path (§6) violation: use the line number of the offending text
+- Callout severity (§5), bolding/inline-code/path (§6), or image external-reference/alt-text (§16) violation: use the line number of the offending text
 - Keywords or description quality issue: use the line number of the field in frontmatter
 
 # Troubleshooting
diff --git a/.claude/skills/kb-pr-open/SKILL.md b/.claude/skills/kb-pr-open/SKILL.md
index a3ae346e38..5574c92876 100644
--- a/.claude/skills/kb-pr-open/SKILL.md
+++ b/.claude/skills/kb-pr-open/SKILL.md
@@ -92,7 +92,7 @@ If Vale is not installed or returns an error, note this in the report and contin
 
 > **Multi-file coverage mandate:** For every file passed to the skill — including each individual file in a multi-file invocation — run the full Derek frontmatter sweep across all areas: `tags`, `products`, `keywords`, `sidebar_label`, `title`/title-format, and `knowledge_article_id`, plus `images` and `links`. Do not abbreviate or skip any area. If the same finding applies to multiple files (for example, all files have the same wrong `products` value), still list it under each file individually in the report — do not consolidate. A partial sweep on any single file is a coverage gap and causes downstream rework.
 
-**Naming note:** `links`, `images`, `formatting: lists`, and `prose-directness` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check any of them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, and bolding/inline-code/path formatting — see `derek/SKILL.md`'s Review Areas table). Running `/derek` directly on a file does not cover those four areas; only `kb-pr-open` and `kb-pr-review` do.
+**Naming note:** `links`, `images: location`, `formatting: lists`, and `prose-directness` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check any of them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, bolding/inline-code/path formatting, and — unlike location — `images: external-refs`/`images: alt-text`, which `/derek` does check; see `derek/SKILL.md`'s Review Areas table). Running `/derek` directly on a file does not cover those four rows; only `kb-pr-open` and `kb-pr-review` cover the full images area.
 
 Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms in this section — those belong to Vale and Dale respectively. (`NetwrixKB.HeadingCase` covers all heading levels, not just the H1. The one gap is an article with no body H1 at all — Vale's heading-scoped rule never evaluates that case, so the §12 exception applies there: check the frontmatter `title` value's case directly.)
 
diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md
index 45bfe77426..ec377db9d9 100644
--- a/.claude/skills/kb-pr-review/SKILL.md
+++ b/.claude/skills/kb-pr-review/SKILL.md
@@ -181,7 +181,7 @@ For each file in `KB_FILES`:
 
 Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms — those belong to Vale and Dale respectively. (`NetwrixKB.HeadingCase` covers all heading levels, not just the H1. The one gap is an article with no body H1 at all — Vale's heading-scoped rule never evaluates that case, so the §12 exception applies there: check the frontmatter `title` value's case directly.)
 
-**Naming note:** `links`, `images`, `formatting: lists`, and `prose-directness` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check any of them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, and bolding/inline-code/path formatting — see `derek/SKILL.md`'s Review Areas table). Running `/derek` directly on a file does not cover those four areas; only `kb-pr-open` and `kb-pr-review` do.
+**Naming note:** `links`, `images: location`, `formatting: lists`, and `prose-directness` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check any of them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, bolding/inline-code/path formatting, and — unlike location — `images: external-refs`/`images: alt-text`, which `/derek` does check; see `derek/SKILL.md`'s Review Areas table). Running `/derek` directly on a file does not cover those four rows; only `kb-pr-open` and `kb-pr-review` cover the full images area.
 
 **KB Editing Conventions Scan (Derek subsection).** In addition to the areas table above, run the checklist below on every file. These are mechanical scan patterns codified during batch reviews; they map to the canonical rulebook at `.claude/references/kb-editing-conventions.md`. Do not duplicate the rulebook's full text here — treat the checklist as the minimum sweep. If a batch surfaces a new pattern, amend the rulebook and add the corresponding scan row here in the next PR.
 
diff --git a/CLAUDE.md b/CLAUDE.md
index c7e1347fb2..b9d5b80f4f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -98,7 +98,7 @@ When a user asks for help with documentation, always use the appropriate tool:
 | `/doc-pr` | Skill | Automated PR editorial review |
 | `/content-fix` | Skill | Autonomous issue-to-PR fixer for content_fix issues |
 | `/doc-pr-fix` | Skill | Autonomous PR fixer triggered by `@claude` |
-| `/derek` | Skill | KB article quality reviewer (frontmatter, structure, title format, product names, callouts, bolding/path formatting, keywords) |
+| `/derek` | Skill | KB article quality reviewer (frontmatter, structure, title format, product names, callouts, bolding/path formatting, image alt-text/external-refs, keywords) |
 | `/kb-writer` | Skill | Interactive KB article content coach — depth, structure, clarity before linting |
 | `/kb-pr-open` | Skill | Last-mile KB submission helper for TSEs — lints and opens a PR to `dev` |
 | `/kb-pr-review` | Skill | Reviews a KB PR (Vale + Dale + Derek) and drafts a review comment |

From a41384a47374355b8346a3ad4913f2b42a0aacd4 Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 13:34:54 -0700
Subject: [PATCH 18/20] Address seventeenth code review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- derek/SKILL.md's Derek-vs-Overview reconciliation note was stale
  against last round's Overview rewrite: pointed "below" at a line
  that's actually above it, and described the Overview as folding
  keyword/description into frontmatter and not itemizing images -
  neither true anymore, since the Overview now lists all eight areas
  explicitly. Simplified to state the now-exact match (8 table+Product
  Names areas = 8 Overview items) instead of reconciling against
  wording that no longer exists.
- The "authoring notes must not appear in the report" cleanup two
  rounds ago covered the scan-table and cross-section row labels but
  missed the Derek (N checks) bullet's own "21 as of this writing;
  recount if..." clause in the same list, in both PR skills - the
  exact kind of partial fix this PR exists to close out. Stripped it
  and extended the standalone authoring note to cover all three counts
  (21/23/6) instead of just two.
- §16's "do not flag file format" guard sat inside the Location bullet
  - the one row Derek is explicitly told to skip - while Derek now
  reviews the other two rows (external-refs, alt-text), one of which
  (alt-text) uses a .png example. Promoted the guard to a lead-in
  covering all three rows regardless of which skill reads which row.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 4 +++-
 .claude/skills/derek/SKILL.md                | 2 +-
 .claude/skills/kb-pr-open/SKILL.md           | 4 ++--
 .claude/skills/kb-pr-review/SKILL.md         | 4 ++--
 4 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index 005312af44..fd4343e439 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -263,6 +263,8 @@ When a required heading is missing, include the full expected heading template s
 
 ## 16. Images
 
-- **Location.** KB images must be stored in a `0-images/` folder at the **product level** (`docs/kb/<product>/0-images/`), not inside category subfolders. Articles in category subfolders reference them with `../0-images/filename.<ext>`. Flag any `0-images/` folder created inside a category subfolder rather than at the product level. PNG, WebP, JPG, and JPEG are all in active use and all valid — do not flag file format.
+**PNG, WebP, JPG, and JPEG are all in active use and all valid — do not flag file format under any of the three rows below.**
+
+- **Location.** KB images must be stored in a `0-images/` folder at the **product level** (`docs/kb/<product>/0-images/`), not inside category subfolders. Articles in category subfolders reference them with `../0-images/filename.<ext>`. Flag any `0-images/` folder created inside a category subfolder rather than at the product level.
 - **External references.** Flag any images linked from external sources (for example, GitHub CDN `https://github.com/user-attachments/assets/...`) — these must be downloaded and committed to the repo.
 - **Alt text.** Must be descriptive, not just the filename. Flag any image where the alt text is only the raw filename (e.g., `![index_files_location.png](path)`) — rewrite as a short description of what the image shows, per `kb_style_guide.md`'s Screenshots section.
diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index a70cdc0e40..c2f215e8f0 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -50,7 +50,7 @@ Read the named rulebook section before applying each area — do not hard-code r
 | Bolding, inline code, path formatting | §6 Bolding and inline code |
 | Images: external references, alt text (not location) | §16 Images — external references and alt text rows only |
 
-Links, and image *location* specifically, are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — resolving a link target, or confirming whether a `0-images/` folder actually exists at the category level on disk (§16's location rule), means checking the filesystem beyond the article itself: an unbounded lookup with no fixed answer from the article's text alone. That's different from every other check in Derek's scope: a `products` value against `src/config/products.js` (§13), a UI name against the product's own docs (Product Names, below), or §16's external-references/alt-text rules — each of those is either one lookup against one known source, or a pure text check within the article (is this URL an external CDN link; does this alt text just repeat the filename) — never a search across the repo. Everything else is in scope: the seven rows in the table above, plus Product Names, which lives in its own section below the table rather than as an eighth row. That totals eight areas — the seven-area Overview line below should be read as naming the same overall scope, not a strict count (it folds keyword/description quality into frontmatter and doesn't itemize images separately).
+Links, and image *location* specifically, are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — resolving a link target, or confirming whether a `0-images/` folder actually exists at the category level on disk (§16's location rule), means checking the filesystem beyond the article itself: an unbounded lookup with no fixed answer from the article's text alone. That's different from every other check in Derek's scope: a `products` value against `src/config/products.js` (§13), a UI name against the product's own docs (Product Names, below), or §16's external-references/alt-text rules — each of those is either one lookup against one known source, or a pure text check within the article (is this URL an external CDN link; does this alt text just repeat the filename) — never a search across the repo. Everything else is in scope: the seven rows in the table above, plus Product Names, which lives in its own section below the table rather than as an eighth row. That totals eight areas, matching the eight items named in the Overview line above.
 
 ## Product Names
 
diff --git a/.claude/skills/kb-pr-open/SKILL.md b/.claude/skills/kb-pr-open/SKILL.md
index 5574c92876..ff4870250a 100644
--- a/.claude/skills/kb-pr-open/SKILL.md
+++ b/.claude/skills/kb-pr-open/SKILL.md
@@ -174,11 +174,11 @@ Structure per file:
 **Rows required on every file (default mode):**
 
 - One row each for Vale and Dale.
-- One row for `Derek (N checks)` — a single roll-up covering every frontmatter sub-field (`title`, `description`, `sidebar_label`, `keywords`, `products`, `tags`, `knowledge_article_id`) and every other named area (`article-type: structure`, `article-type: qa-format`, `article-type: heading-labels`, `title: mechanical`, `title: semantic`, `product-names`, `keywords-quality`, `images: location`, `images: external-refs`, `images: alt-text`, `links`, `formatting: bold/backticks`, `formatting: lists`, `prose directness`). N is the total count of sub-fields + areas — 21 as of this writing; recount if the areas table changes. Status cell: `N/N scanned, <total findings> findings in <count> areas` (or `✓ Clean` if zero findings).
+- One row for `Derek (N checks)` — a single roll-up covering every frontmatter sub-field (`title`, `description`, `sidebar_label`, `keywords`, `products`, `tags`, `knowledge_article_id`) and every other named area (`article-type: structure`, `article-type: qa-format`, `article-type: heading-labels`, `title: mechanical`, `title: semantic`, `product-names`, `keywords-quality`, `images: location`, `images: external-refs`, `images: alt-text`, `links`, `formatting: bold/backticks`, `formatting: lists`, `prose directness`). N is the total count of sub-fields + areas — 21. Status cell: `N/N scanned, <total findings> findings in <count> areas` (or `✓ Clean` if zero findings).
 - One row for `kb-editing-conventions scan (23 rows)`.
 - One row for `Cross-section consistency (6 patterns)`.
 
-Row labels use the current counts (23 scan rows, 6 cross-section patterns) as of this writing — recount and update both the labels above and this note if either table's row count changes in a future batch. These are authoring notes for whoever edits this skill; they must not appear in the generated report itself.
+Row labels and the `Derek (N checks)` bullet above use the current counts (21 Derek sub-fields + areas, 23 scan rows, 6 cross-section patterns) as of this writing — recount and update the labels/bullet above and this note if any of the three tables changes in a future batch. These are authoring notes for whoever edits this skill; they must not appear in the generated report itself.
 
 No per-area or per-sub-field rows appear in the Overview table in default mode, under any circumstance — that detail lives only in the Derek findings table below. The Overview table is a fixed 5 rows regardless of file size; that fixed shape is the coverage receipt for the tool level, backed by the Coverage discipline enumeration for the check level.
 
diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md
index ec377db9d9..85c0e99913 100644
--- a/.claude/skills/kb-pr-review/SKILL.md
+++ b/.claude/skills/kb-pr-review/SKILL.md
@@ -255,11 +255,11 @@ Per-file structure:
 **Rows required on every file (default mode):**
 
 - One row each for Vale and Dale.
-- One row for `Derek (N checks)` — a single roll-up covering every frontmatter sub-field (`title`, `description`, `sidebar_label`, `keywords`, `products`, `tags`, `knowledge_article_id`) and every other named area (`article-type: structure`, `article-type: qa-format`, `article-type: heading-labels`, `title: mechanical`, `title: semantic`, `product-names`, `keywords-quality`, `images: location`, `images: external-refs`, `images: alt-text`, `links`, `formatting: bold/backticks`, `formatting: lists`, `prose directness`). N is the total count of sub-fields + areas — 21 as of this writing; recount if the areas table changes. Status cell: `N/N scanned, <total findings> findings in <count> areas` (or `✓ Clean` if zero findings).
+- One row for `Derek (N checks)` — a single roll-up covering every frontmatter sub-field (`title`, `description`, `sidebar_label`, `keywords`, `products`, `tags`, `knowledge_article_id`) and every other named area (`article-type: structure`, `article-type: qa-format`, `article-type: heading-labels`, `title: mechanical`, `title: semantic`, `product-names`, `keywords-quality`, `images: location`, `images: external-refs`, `images: alt-text`, `links`, `formatting: bold/backticks`, `formatting: lists`, `prose directness`). N is the total count of sub-fields + areas — 21. Status cell: `N/N scanned, <total findings> findings in <count> areas` (or `✓ Clean` if zero findings).
 - One row for `kb-editing-conventions scan (23 rows)`.
 - One row for `Cross-section consistency (6 patterns)`.
 
-Row labels use the current counts (23 scan rows, 6 cross-section patterns) as of this writing — recount and update both the labels above and this note if either table's row count changes in a future batch. These are authoring notes for whoever edits this skill; they must not appear in the generated report itself.
+Row labels and the `Derek (N checks)` bullet above use the current counts (21 Derek sub-fields + areas, 23 scan rows, 6 cross-section patterns) as of this writing — recount and update the labels/bullet above and this note if any of the three tables changes in a future batch. These are authoring notes for whoever edits this skill; they must not appear in the generated report itself.
 
 No per-area or per-sub-field rows appear in the Overview table in default mode, under any circumstance — that detail lives only in the Derek findings table below. The Overview table is a fixed 5 rows regardless of file size; that fixed shape is the coverage receipt for the tool level, backed by the Coverage discipline enumeration for the check level.
 

From 468bd6479319ddceb3bfd0fa1e37075c368a2b5a Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 13:56:15 -0700
Subject: [PATCH 19/20] Address eighteenth code review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- §12's title-case Vale deferral was keyed on which skill is running,
  not on whether Vale actually produced output for this file. Both PR
  skills explicitly continue when Vale is missing or errors (kb-pr-open:
  "Vale | not run", kb-pr-review: "Vale | Not available - skipped"),
  so on a machine without Vale the deferral silently dropped the check
  entirely - a real regression versus base derek/kb-pr-open/kb-pr-review,
  which all checked title case unconditionally with no deferral. Fixed
  to key the deferral on Vale having actually run and reported, with
  an explicit fallback to checking the H1 directly when it didn't.
  Synced into both PR skills' parenthetical clarifications.
- derek/SKILL.md's "eight areas = eight Overview items" arithmetic
  check was coincidental, not a real correspondence - the two lists
  partition the same scope differently (Overview collapses article
  type/structure into one item; the table splits it into two rows).
  The match would silently stop meaning anything the next time either
  list changes. Dropped the count assertion rather than keep an
  invariant that isn't actually one.
- kb-pr-review lacked kb-pr-open's findings-routing rule (scan-table
  and cross-section findings route into the Derek table with
  kb-editing-conventions/cross-section as the area, not their own
  section) - a pre-existing gap, cheap to close now that both tables
  are otherwise synced.
- PR description now lists the §15/§13 checks (Q&A question-format,
  How-To structure, wrong-shape, title/H1 exact-match) that grew
  standalone /derek's scope beyond what was previously called out.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 2 +-
 .claude/skills/derek/SKILL.md                | 2 +-
 .claude/skills/kb-pr-open/SKILL.md           | 2 +-
 .claude/skills/kb-pr-review/SKILL.md         | 4 ++--
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index fd4343e439..b3cb5fd183 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -162,7 +162,7 @@ Title findings split into two categories based on whether the change is mechanic
 ### Mechanical style corrections — Required fixes (apply on approval, low ambiguity)
 
 - **gerund-for-How-To-Instructions:** "How to..." prefix → gerund form (e.g., "How to Export Event Logs" → "Exporting Event Logs"). Applies only to How-To Instructions form articles (`## Overview` + `## Instructions` structure). Does NOT apply to How-To Q&A articles — a topic-descriptive title, a "How to..." title, or a question-form title are all valid for Q&A; none is a gerund violation, and the interrogative form doesn't have to live in the title (it can appear in `## Question` instead).
-- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types. **When the body has an H1 *and* the skill running this rulebook area also runs Vale in the same report (e.g., `kb-pr-open`, `kb-pr-review`), defer to Vale — do not duplicate the finding.** `NetwrixKB.HeadingCase` (`scope: heading`) already fires on the H1 in that case, so it's Vale's finding, not a second row for the same title; do not flag the same H1 twice. A standalone invocation that doesn't run Vale (`/derek` on its own) has no deferral to make — Derek's own "what Vale already handles" list already assigns heading case to Vale, so a title-case issue on an H1-bearing article goes unchecked in a `/derek`-only run (nobody runs `NetwrixKB.HeadingCase` in that invocation), same as before this rulebook existed. **When the body has no H1 at all (§13's title row), the deferral does not apply regardless of which skill is running — check the frontmatter `title` value's case directly,** since Vale's heading-scoped rule never evaluates a frontmatter field and nothing else will catch a badly-cased title on those articles.
+- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types. **When the body has an H1 *and* Vale actually ran and reported for this file (not just "the skill is the kind that runs Vale") — defer to Vale, do not duplicate the finding.** `NetwrixKB.HeadingCase` (`scope: heading`) already fires on the H1 in that case, so it's Vale's finding, not a second row for the same title; do not flag the same H1 twice. **If Vale did not run or errored** (`kb-pr-open`'s `Vale | not run (Vale not installed)` row, or `kb-pr-review`'s `Vale | ⚠️ Not available — skipped` row) **— or a standalone invocation that doesn't run Vale at all (`/derek` on its own) — there is no deferral to make: check the H1's case directly and flag it as a Required fix if it's wrong.** Deferring unconditionally to a tool that didn't actually run silently drops the check; only the case where Vale's findings are genuinely present in the same report should be treated as already covered. (For `/derek` specifically, this doesn't change anything — Derek's own "what Vale already handles" list already assigns heading case to Vale, so a title-case issue on an H1-bearing article has never been checked in a `/derek`-only run.) **When the body has no H1 at all (§13's title row), the deferral does not apply regardless of whether Vale ran — check the frontmatter `title` value's case directly,** since Vale's heading-scoped rule never evaluates a frontmatter field and nothing else will catch a badly-cased title on those articles.
 - **Raw log line or error dump as title.** Titles like `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified in HubDetails.xml at ...` — literal log lines with level tokens (FATAL, ERROR, WARN), stack noise, file paths, or truncation fragments — are unreadable and unsearchable. Normalize to the pattern `<Component> Error - <core diagnostic phrase>`, keeping only the searchable message.
   - Examples of the fix:
     - `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified` → `ConfigurationLoader Error - Hub Location Details Have Not Been Specified`
diff --git a/.claude/skills/derek/SKILL.md b/.claude/skills/derek/SKILL.md
index c2f215e8f0..168ab6ac1c 100644
--- a/.claude/skills/derek/SKILL.md
+++ b/.claude/skills/derek/SKILL.md
@@ -50,7 +50,7 @@ Read the named rulebook section before applying each area — do not hard-code r
 | Bolding, inline code, path formatting | §6 Bolding and inline code |
 | Images: external references, alt text (not location) | §16 Images — external references and alt text rows only |
 
-Links, and image *location* specifically, are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — resolving a link target, or confirming whether a `0-images/` folder actually exists at the category level on disk (§16's location rule), means checking the filesystem beyond the article itself: an unbounded lookup with no fixed answer from the article's text alone. That's different from every other check in Derek's scope: a `products` value against `src/config/products.js` (§13), a UI name against the product's own docs (Product Names, below), or §16's external-references/alt-text rules — each of those is either one lookup against one known source, or a pure text check within the article (is this URL an external CDN link; does this alt text just repeat the filename) — never a search across the repo. Everything else is in scope: the seven rows in the table above, plus Product Names, which lives in its own section below the table rather than as an eighth row. That totals eight areas, matching the eight items named in the Overview line above.
+Links, and image *location* specifically, are `kb-pr-open`'s and `kb-pr-review`'s job, not Derek's — resolving a link target, or confirming whether a `0-images/` folder actually exists at the category level on disk (§16's location rule), means checking the filesystem beyond the article itself: an unbounded lookup with no fixed answer from the article's text alone. That's different from every other check in Derek's scope: a `products` value against `src/config/products.js` (§13), a UI name against the product's own docs (Product Names, below), or §16's external-references/alt-text rules — each of those is either one lookup against one known source, or a pure text check within the article (is this URL an external CDN link; does this alt text just repeat the filename) — never a search across the repo. Everything else is in scope: the seven rows in the table above, plus Product Names, which lives in its own section below the table rather than as an eighth row.
 
 ## Product Names
 
diff --git a/.claude/skills/kb-pr-open/SKILL.md b/.claude/skills/kb-pr-open/SKILL.md
index ff4870250a..73ed47adc1 100644
--- a/.claude/skills/kb-pr-open/SKILL.md
+++ b/.claude/skills/kb-pr-open/SKILL.md
@@ -94,7 +94,7 @@ If Vale is not installed or returns an error, note this in the report and contin
 
 **Naming note:** `links`, `images: location`, `formatting: lists`, and `prose-directness` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check any of them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, bolding/inline-code/path formatting, and — unlike location — `images: external-refs`/`images: alt-text`, which `/derek` does check; see `derek/SKILL.md`'s Review Areas table). Running `/derek` directly on a file does not cover those four rows; only `kb-pr-open` and `kb-pr-review` cover the full images area.
 
-Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms in this section — those belong to Vale and Dale respectively. (`NetwrixKB.HeadingCase` covers all heading levels, not just the H1. The one gap is an article with no body H1 at all — Vale's heading-scoped rule never evaluates that case, so the §12 exception applies there: check the frontmatter `title` value's case directly.)
+Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms in this section — those belong to Vale and Dale respectively, **provided Vale actually ran and reported for this file.** `NetwrixKB.HeadingCase` covers all heading levels, not just the H1. Two gaps mean nothing else checks heading case for this rule: an article with no body H1 at all (Vale's heading-scoped rule never evaluates that case), or Vale not installed/erroring (the `Vale | not run (Vale not installed)` row above) — in either case, check the H1 (or the frontmatter `title` value, if there's no H1) directly per rulebook §12.
 
 > **IMPORTANT:** When applying fixes, follow `kb_style_guide.md`, not `docs/CLAUDE.md`. KB articles differ from the docs style guide on contractions (write out in full) and heading case (title case).
 
diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md
index 85c0e99913..a17fcb4f24 100644
--- a/.claude/skills/kb-pr-review/SKILL.md
+++ b/.claude/skills/kb-pr-review/SKILL.md
@@ -179,7 +179,7 @@ For each file in `KB_FILES`:
 | **formatting: lists** | §3 List type + §10 Formatting (fenced code blocks for multi-line commands/output) |
 | **prose-directness** | §4 Sentence-level rules (impersonal-subject directness) |
 
-Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms — those belong to Vale and Dale respectively. (`NetwrixKB.HeadingCase` covers all heading levels, not just the H1. The one gap is an article with no body H1 at all — Vale's heading-scoped rule never evaluates that case, so the §12 exception applies there: check the frontmatter `title` value's case directly.)
+Do NOT flag contractions, heading case, passive voice, jargon, or undefined acronyms — those belong to Vale and Dale respectively, **provided Vale actually ran and reported for this file.** `NetwrixKB.HeadingCase` covers all heading levels, not just the H1. Two gaps mean nothing else checks heading case for this rule: an article with no body H1 at all (Vale's heading-scoped rule never evaluates that case), or Vale not available (the `Vale | ⚠️ Not available — skipped` row above) — in either case, check the H1 (or the frontmatter `title` value, if there's no H1) directly per rulebook §12.
 
 **Naming note:** `links`, `images: location`, `formatting: lists`, and `prose-directness` appear as areas in this skill's own Derek findings table, but the `/derek` skill itself does not check any of them (it's scoped to frontmatter, article type/structure, title format, product names, callout format, bolding/inline-code/path formatting, and — unlike location — `images: external-refs`/`images: alt-text`, which `/derek` does check; see `derek/SKILL.md`'s Review Areas table). Running `/derek` directly on a file does not cover those four rows; only `kb-pr-open` and `kb-pr-review` cover the full images area.
 
@@ -313,7 +313,7 @@ Example shape (`+ verbose`):
 
 **Count-consistency discipline (arithmetic check).** Whenever a status cell shows a total finding count *and* a parenthetical breakdown (e.g., `10/10 scanned, 5 findings (passive-voice ×2, undefined-acronyms ×3)`), the top-line total must equal the sum of the breakdown counts. `2 findings (passive-voice ×2, undefined-acronyms ×3)` is a bug — that's 5, not 2. Same rule applies to every row that shows a breakdown: Vale, Dale, Derek, the scan-table row, cross-section row. Additionally, the number of rows in each findings section table below must equal the count claimed by the corresponding Overview row. Do the arithmetic before writing the row; do not paper over a mismatch by picking one number and hoping the reader doesn't add.
 
-**2. Findings sections (only for non-clean checks).** For every row in the Overview table whose status is not ✓ Clean, add one short table below listing only the findings that need a decision. One section per tool (Vale / Dale / Derek). Do not add sections for tools that are entirely clean.
+**2. Findings sections (only for non-clean checks).** For every row in the Overview table whose status is not ✓ Clean, add one short table below listing only the findings that need a decision. One section per tool (Vale / Dale / Derek). kb-editing-conventions scan findings route into the Derek table with `kb-editing-conventions` as the area (per the scan section above); cross-section consistency findings route into the Derek table the same way, with `cross-section` as the area — neither gets its own findings section. Do not add sections for tools that are entirely clean.
 
 - Vale columns: `Line | Rule | Severity | Finding`
 - Dale columns: `Location | Rule | Finding + suggested rewrite`

From df574e049b83acdfedb203f0148ef415e58b08fd Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Wed, 12 Aug 2026 14:08:40 -0700
Subject: [PATCH 20/20] Address nineteenth code review round: fix genuine
 self-contradiction
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

§12's title-case bullet told /derek two incompatible things in the
same paragraph - a bold clause saying /derek should check H1 title
case directly (no deferral to make for a standalone invocation), and
a parenthetical immediately after saying nothing changes for /derek
because it already defers heading case to Vale. derek/SKILL.md:13
sided with the parenthetical. Since /derek never runs Vale, a strict
reading of the bold clause would have made every H1-bearing article
with bad title case a new Required-fix row - a mass finding class
introduced by my own fix two rounds ago, and not mentioned in the PR
description's behavior-change list because it wasn't intended.

Resolved by scoping the whole bullet to kb-pr-open/kb-pr-review (the
skills that actually run Vale) and removing /derek from its "no
deferral" clause entirely, leaving derek/SKILL.md:13's existing
Vale-handles-heading-case-except-no-H1 policy as the sole authority
for what /derek checks - no new mass-finding class, no contradiction.

Also: disambiguated "the canonical list in src/config/products.js" to
name the products array specifically, since the file also has a
categories array whose ids do use hyphens (directory-management,
endpoint-management, identity-management) - zero live impact today
(no KB file uses those values) but removes a live ambiguity.

Generated with AI

Co-Authored-By: Claude Code <ai@netwrix.com>
---
 .claude/references/kb-editing-conventions.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude/references/kb-editing-conventions.md b/.claude/references/kb-editing-conventions.md
index b3cb5fd183..97a3de351c 100644
--- a/.claude/references/kb-editing-conventions.md
+++ b/.claude/references/kb-editing-conventions.md
@@ -162,7 +162,7 @@ Title findings split into two categories based on whether the change is mechanic
 ### Mechanical style corrections — Required fixes (apply on approval, low ambiguity)
 
 - **gerund-for-How-To-Instructions:** "How to..." prefix → gerund form (e.g., "How to Export Event Logs" → "Exporting Event Logs"). Applies only to How-To Instructions form articles (`## Overview` + `## Instructions` structure). Does NOT apply to How-To Q&A articles — a topic-descriptive title, a "How to..." title, or a question-form title are all valid for Q&A; none is a gerund violation, and the interrogative form doesn't have to live in the title (it can appear in `## Question` instead).
-- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types. **When the body has an H1 *and* Vale actually ran and reported for this file (not just "the skill is the kind that runs Vale") — defer to Vale, do not duplicate the finding.** `NetwrixKB.HeadingCase` (`scope: heading`) already fires on the H1 in that case, so it's Vale's finding, not a second row for the same title; do not flag the same H1 twice. **If Vale did not run or errored** (`kb-pr-open`'s `Vale | not run (Vale not installed)` row, or `kb-pr-review`'s `Vale | ⚠️ Not available — skipped` row) **— or a standalone invocation that doesn't run Vale at all (`/derek` on its own) — there is no deferral to make: check the H1's case directly and flag it as a Required fix if it's wrong.** Deferring unconditionally to a tool that didn't actually run silently drops the check; only the case where Vale's findings are genuinely present in the same report should be treated as already covered. (For `/derek` specifically, this doesn't change anything — Derek's own "what Vale already handles" list already assigns heading case to Vale, so a title-case issue on an H1-bearing article has never been checked in a `/derek`-only run.) **When the body has no H1 at all (§13's title row), the deferral does not apply regardless of whether Vale ran — check the frontmatter `title` value's case directly,** since Vale's heading-scoped rule never evaluates a frontmatter field and nothing else will catch a badly-cased title on those articles.
+- **Title case correction** (e.g., "configure stopwords" → "Configuring Stopwords"). Applies to all article types. This bullet governs `kb-pr-open` and `kb-pr-review`, which run Vale in the same report — it does not change `/derek`'s scope; `derek/SKILL.md`'s own "what Vale already handles" list is authoritative for what standalone `/derek` checks. **For `kb-pr-open`/`kb-pr-review`: when the body has an H1 *and* Vale actually ran and reported for this file (not just "the skill is the kind that runs Vale") — defer to Vale, do not duplicate the finding.** `NetwrixKB.HeadingCase` (`scope: heading`) already fires on the H1 in that case, so it's Vale's finding, not a second row for the same title; do not flag the same H1 twice. **If Vale did not run or errored** (`kb-pr-open`'s `Vale | not run (Vale not installed)` row, or `kb-pr-review`'s `Vale | ⚠️ Not available — skipped` row) **— there is no deferral to make: check the H1's case directly and flag it as a Required fix if it's wrong.** Deferring unconditionally to a tool that didn't actually run silently drops the check; only the case where Vale's findings are genuinely present in the same report should be treated as already covered. **When the body has no H1 at all (§13's title row), the deferral does not apply regardless of whether Vale ran — check the frontmatter `title` value's case directly,** since Vale's heading-scoped rule never evaluates a frontmatter field and nothing else will catch a badly-cased title on those articles. This no-H1 case is the one place `/derek` also checks title case directly, per its own Vale-handles list.
 - **Raw log line or error dump as title.** Titles like `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified in HubDetails.xml at ...` — literal log lines with level tokens (FATAL, ERROR, WARN), stack noise, file paths, or truncation fragments — are unreadable and unsearchable. Normalize to the pattern `<Component> Error - <core diagnostic phrase>`, keeping only the searchable message.
   - Examples of the fix:
     - `ConfigurationLoader FATAL Hub Location Details Have Not Been Specified` → `ConfigurationLoader Error - Hub Location Details Have Not Been Specified`
@@ -192,7 +192,7 @@ All KB articles must begin with a frontmatter block. Check that all required fie
 | `description` | Present, non-empty, 1–2 sentences; SEO-friendly; accurately summarizes what the article covers. Flag if empty, too vague, or a verbatim copy of the title. |
 | `sidebar_label` | Present, non-empty; must not be truncated vs. `title` |
 | `keywords` | Present, contains 8–12 items — specific and searchable (error codes, product names, technical terms, phrases a customer would type into a search bar), not generic or a verbatim repeat of the title. Flag if a term prominent in the article body (an error code, a distinctive feature/component name) is missing from keywords — this drives search discoverability and is a Required fix, not a soft one. The inverse direction is softer: if a keyword doesn't appear in the article body but is a plausible customer search term, note it as a low-priority observation rather than a required fix. |
-| `products` | Present, contains at least one product ID from the canonical list in `src/config/products.js` — no hyphens or underscores as word separators (`dataclassification`, `directorymanager`, `threatmanager` are correct; `data-classification`, `directory-manager`, `threat-manager` are not). `src/config/products.js` is authoritative if it and `kb_style_guide.md`'s Product Names table disagree — the style guide table can lag a `products.js` update. |
+| `products` | Present, contains at least one product ID from the `products` array (not the `categories` array — whose `id`s do use hyphens, e.g. `directory-management`) in `src/config/products.js` — no hyphens or underscores as word separators (`dataclassification`, `directorymanager`, `threatmanager` are correct; `data-classification`, `directory-manager`, `threat-manager` are not). `src/config/products.js`'s `products` array is authoritative if it and `kb_style_guide.md`'s Product Names table disagree — the style guide table can lag a `products.js` update. |
 | `tags` | Present and includes `kb` |
 | `knowledge_article_id` | See policy below |