Merge pull request #380 from netwrix/dev

dev to main

Author: jth-nw

.github/workflows/claude-documentation-reviewer.yml

@@ -23,7 +23,10 @@ jobs:
         with:
           # Check out by SHA to prevent TOCTOU attacks from forks.
           ref: ${{ github.event.pull_request.head.sha }}
-          fetch-depth: 0
+          fetch-depth: 1
+
+      - name: Fetch base commit for diff
+        run: git fetch --depth=1 origin ${{ github.event.pull_request.base.sha }}
 
       - name: Get changed markdown files
         id: changed-files

CLAUDE.md

@@ -0,0 +1,142 @@
+# Netwrix Product Documentation — Claude Code Guide
+
+A Docusaurus v3.8.1 site serving documentation for 27+ Netwrix security products across 6 categories, with multi-version support and a centralized configuration system.
+
+## Development Commands
+
+```bash
+npm run start          # Dev server on port 4500
+npm run build          # Production build (16 GB heap pre-configured)
+npm run clear          # Clear Docusaurus cache
+npm run serve          # Serve production build after build
+
+# Build/run a single product for faster iteration:
+export DOCS_PRODUCT="pingcastle"
+npm run start
+```
+
+Available product IDs are defined in `src/config/products.js`.
+
+## Architecture
+
+### Single Source of Truth: `src/config/products.js`
+
+All product and version configuration lives here. Never manually edit `docusaurus.config.js` to add products, routes, or plugins — `products.js` auto-generates all of that. Changing a product means changing this file.
+
+### Versioned Documentation
+
+Docs live at `docs/<product>/<version>/` (for example, `docs/accessanalyzer/12.0/`). Edits to one version do not propagate to others — update each version that needs the change explicitly.
+
+Single-version (SaaS) products use `docs/<product>/` without a version subfolder.
+
+### Sidebars
+
+Each product version has a sidebar config in `sidebars/<product>/<version>.js` (or `sidebars/<product>.js` for single-version). These are separate from the doc content. Most use `autogenerated` and don't need manual editing unless custom ordering is required.
+
+### KB (Knowledge Base) System
+
+`docs/kb/` is the canonical source for KB articles. The script `scripts/copy-kb-to-versions.mjs` distributes articles into versioned product folders at build time (runs automatically as a pre-build step).
+
+**Never manually copy KB articles into versioned product folders.** Edit the source in `docs/kb/` and control distribution via `kb_allowlist.json`.
+
+## Adding Content
+
+### New product
+
+1. Add an entry to the `PRODUCTS` array in `src/config/products.js`
+2. Create `docs/<id>/`
+3. Create `sidebars/<id>.js`
+
+### New version of an existing product
+
+1. Update the `versions` array for that product in `src/config/products.js` — set `isLatest: true` on the new version and `isLatest: false` on the previous one
+2. Create `docs/<product>/<version>/`
+3. Create `sidebars/<product>/<version>.js`
+
+### New product category
+
+Add to the `PRODUCT_CATEGORIES` array in `src/config/products.js`.
+
+## Writing Style
+
+The full standards are in `netwrix_style_guide.md` at the project root. Read it when in doubt.
+
+**Always run Vale before finishing any documentation edit. Run it iteratively — fix all reported issues, then run again until Vale reports zero errors.** Fixes can occasionally introduce new violations.
+
+```bash
+vale <file>
+```
+
+Vale enforces 26 Netwrix-specific rules in CI. Rules are in `.vale/styles/Netwrix/`.
+
+If Vale isn't installed, install it first:
+
+```bash
+# macOS
+brew install vale
+
+# Windows
+choco install vale
+# or download from https://github.com/errata-ai/vale/releases
+
+# Linux
+snap install vale --edge
+```
+
+### Fixing Vale errors
+
+Most errors are simple substitutions — Vale reports the exact file, line, and column. Three rules require extra care:
+
+- **`NoteThat`** — Replace inline "Note that..." or "Please note..." with a Docusaurus admonition block:
+  ```md
+  :::note
+  Content here.
+  :::
+  ```
+  Use `:::warning` for warnings and `:::tip` for tips.
+
+- **`BoilerplateCrossRef`** and **`WeakLinkText`** — Read the surrounding context and the link destination before rewriting. The fix must reflect what the reader will actually find at the destination.
+
+- **`ImpersonalConstructions`** — Read the full sentence before rewriting. Restructure with an active subject rather than simply removing the flagged phrase.
+
+### Rules Vale doesn't catch
+
+Vale handles pattern-based violations automatically — run it and fix everything it reports. The following rules require judgment that Vale can't apply:
+
+**Voice and structure**
+- Active voice and present tense throughout
+- Second person ("you") — address the reader directly
+- Contractions are encouraged: don't, can't, you'll
+- Keep sentences to one idea per sentence
+- Write for a global audience — avoid metaphors, idioms, and culturally specific references that don't translate
+- Omit "currently", "presently", and "as of this writing" — documentation should read as permanently accurate
+
+**Document structure**
+- Order: overview → prerequisites → procedures
+- Task headings use imperative verbs: "Configure the monitoring plan"
+- Concept/overview headings use gerunds: "Configuring the monitoring plan"
+- Examples immediately follow the concept they illustrate
+- Images: store in `static/img/product_docs/<product>/`, use `.webp`, reference with absolute paths (`/img/product_docs/...`)
+
+**Terminology**
+- Spell out acronyms on first use: "group Managed Service Account (gMSA)"
+- Use angle brackets for placeholders: `<report-name>` not `[report-name]`
+- Sentence case for feature names; capitalize Netwrix product names correctly
+- Oxford comma required in lists
+
+## CI/CD Context
+
+**Vale linter** — runs on every PR touching `.md` files, posts inline review comments. Does not block merges but issues are visible.
+
+**Doc reviewer** (Claude Opus 4.6) — runs on every PR, reads full files, categorizes issues as "in PR changes" vs "preexisting", and posts inline suggestions reviewers can apply with one click.
+
+**Doc fixer** — triggered by an `@claude` comment on a PR. Claude applies fixes and pushes. Fork PRs cannot be pushed to and receive a notice instead.
+
+**Branch workflow** — PRs target `dev`. Merges to `main` trigger production deployment.
+
+## Common Mistakes to Avoid
+
+- Don't add products or routes by editing `docusaurus.config.js` — use `src/config/products.js`
+- Don't copy KB content manually into versioned product folders — it's managed by the KB script
+- Don't skip Vale before submitting — it will catch issues in CI anyway
+- Don't target `main` in PRs — use `dev`

docs/passwordsecure/9.1/index.md

@@ -6,20 +6,16 @@ sidebar_position: 1
 
 # Why Netwrix Password Secure?
 
-## Users depend on passwords
-
-Now more than ever in their day-to-day business worldwide. They are used constantly and everywhere,
-and they need to be professionally managed. Passwords should be safe, have at least 12 characters,
-including uppercase and lowercase as well as special characters. In the best case, a separate access
+Users depend on passwords in their day-to-day business worldwide. Passwords are used constantly and everywhere,
+and they need to be professionally managed. Passwords should be safe, have at least 12 characters, and include uppercase and lowercase characters as well as special characters. In the best case, a separate access
 password should be used for each account. It should be changed regularly. It is hard enough to meet
-this challenge in private settings. In a large corporate environment, you wouldn’t be able to
-adequately manage this task without the use of a professional password management tool.
+this challenge in private settings. In a large corporate environment, adequately managing passwords without the use of a professional password management tool is difficult.
 
 ## Scalability
 
-The scalability of Netwrix Netwrix Password Secure (NPS) makes it suitable for use in SMEs, large
+The scalability of Netwrix Password Secure (NPS) makes it suitable for use in SMEs, large
 companies, and global corporations. The flexibility required for this task is the driving factor
-behind our development to meet the ever-changing requirements of modern and safety-conscious
-companies. NPS is the perfect software solution for companies that wish to effectively manage
+behind the development to meet the ever-changing requirements of modern and safety-conscious
+companies. NPS is a software solution for companies that want to effectively manage
 security-relevant data such as passwords, documents, or certificates at a very high encryption
-level.
+level.

docs/passwordsecure/9.2/index.md

@@ -6,20 +6,16 @@ sidebar_position: 1
 
 # Why Netwrix Password Secure?
 
-## Users depend on passwords
-
-Now more than ever in their day-to-day business worldwide. They are used constantly and everywhere,
-and they need to be professionally managed. Passwords should be safe, have at least 12 characters,
-including uppercase and lowercase as well as special characters. In the best case, a separate access
+Users depend on passwords in their day-to-day business worldwide. Passwords are used constantly and everywhere,
+and they need to be professionally managed. Passwords should be safe, have at least 12 characters, and include uppercase and lowercase characters as well as special characters. In the best case, a separate access
 password should be used for each account. It should be changed regularly. It is hard enough to meet
-this challenge in private settings. In a large corporate environment, you wouldn’t be able to
-adequately manage this task without the use of a professional password management tool.
+this challenge in private settings. In a large corporate environment, adequately managing passwords without the use of a professional password management tool is difficult.
 
 ## Scalability
 
-The scalability of Netwrix Netwrix Password Secure (NPS) makes it suitable for use in SMEs, large
+The scalability of Netwrix Password Secure (NPS) makes it suitable for use in SMEs, large
 companies, and global corporations. The flexibility required for this task is the driving factor
-behind our development to meet the ever-changing requirements of modern and safety-conscious
-companies. NPS is the perfect software solution for companies that wish to effectively manage
+behind the development to meet the ever-changing requirements of modern and safety-conscious
+companies. NPS is a software solution for companies that want to effectively manage
 security-relevant data such as passwords, documents, or certificates at a very high encryption
 level.

docs/passwordsecure/9.3/index.md

@@ -6,20 +6,16 @@ sidebar_position: 1
 
 # Why Netwrix Password Secure?
 
-## Users depend on passwords
-
-Passwords are used constantly and everywhere,
-and they must be professionally managed. Passwords should be safe, have at least 12 characters,
-including uppercase and lowercase as well as special characters. In the best case, a separate access
+Users depend on passwords in their day-to-day business worldwide. Passwords are used constantly and everywhere,
+and they need to be professionally managed. Passwords should be safe, have at least 12 characters, and include uppercase and lowercase characters as well as special characters. In the best case, a separate access
 password should be used for each account. It should be changed regularly. It is hard enough to meet
-this challenge in private settings. In a large corporateee environment, you wouldn’t be able to
-adequately manage this task without the use of a professional password management tool.
+this challenge in private settings. In a large corporate environment, adequately managing passwords without the use of a professional password management tool is difficult.
 
 ## Scalability
 
 The scalability of Netwrix Password Secure (NPS) makes it suitable for use in SMEs, large
 companies, and global corporations. The flexibility required for this task is the driving factor
-behind our development to meet the ever-changing requirements of modern and safety-conscious
-companies. NPS is the perfect software solution for companies that wish to effectively manage
+behind the development to meet the ever-changing requirements of modern and safety-conscious
+companies. NPS is a software solution for companies that want to effectively manage
 security-relevant data such as passwords, documents, or certificates at a very high encryption
 level.

netwrix_style_guide.md

@@ -153,8 +153,8 @@ This style guide establishes the specific rules for grammar, punctuation, and st
 | Rule | Description | Do  | Don't |
 |------|-------------|-----|-------|
 | **Headings** | Use sentence case for headings. Capitalize only the first word and proper nouns. | Configure the monitoring plan | Configure the Monitoring Plan<br><br>Configure The Monitoring Plan |
-| **Headings with infinitives** | Start task-based headings with infinitives. | Install Netwrix Auditor<br><br>Configure monitoring plans | Installing Netwrix Auditor (in a heading for a section with multiple steps)<br><br>Configuring monitoring plans |
-| **Headings with gerunds**  | Start headings with gerunds ("-ing" verbs) when the topics are concepts, overviews, or when they describe continuous actions. | Reviewing audit logs | Review audit logs (unless it's a task) |
+| **Task-based headings** | Start task-based headings with imperative verbs. | Install Netwrix Auditor<br><br>Configure monitoring plans | Installing Netwrix Auditor (in a heading for a section with multiple steps)<br><br>Configuring monitoring plans |
+| **Conceptual headings**  | Start headings with gerunds ("-ing" verbs) when the topics are concepts, overviews, or when they describe continuous actions. | Reviewing audit logs | Review audit logs (unless it's a task) |
 | **Bold text** | Use bold for UI elements, buttons, and menu items. | Click **Add** to create a new monitoring plan. | Click "Add" to create a new monitoring plan.<br><br>Click Add to create a new monitoring plan. |
 | **Italic text** | Avoid italics. | This process is known as agentless monitoring. | Click the *Add* button. |
 | **Code formatting** | Use monospace formatting for code, commands, file paths, and technical values. | Run the `Get-NWXUser`cmdlet to retrieve user information.<br><br>Edit the`C:\Program Files\Netwrix\config.xml` file. | Run the Get-NWXUser cmdlet to retrieve user information.<br><br>Edit the C:\\Program Files\\Netwrix\\config.xml file. |