docs(aa2601): overhaul install section for interactive wizard installer

[Cmej413]

Summary

• Quick Install fully restructured for the new interactive dspm-installer wizard — prerequisites checklist, three TLS cert options (self-signed / AD CS / BYOC), prompt reference table, installation complete summary step, direct AD first-admin sign-in, bootstrap account demoted to breakglass
• install/identity-provider.md and install/install-commands.md hidden with draft: true — both built around the old curl/bash env-var installer; preserved for future IdP work
• System subsections cleaned of old CLI flag references (--size, --configure-idp-only, SKIP_AV_CHECK, DSPM_HOSTNAME, env var/flag tables in certificates.md)
• Broken links to hidden pages fixed across configurations/identity-provider.md, postinstall.md, and uninstall.md

Test plan

• Review Quick Install page on dev server at /docs/accessanalyzer/2601/install/quickinstall
• Confirm identity-provider and install-commands pages no longer appear in sidebar
• Verify all links resolve — no broken link build errors
• Review Configuration > Identity Provider page for updated first-admin sign-in flow

Generated with AI

Co-Authored-By: Claude Code ai@netwrix.com

[github-actions]

⚠️ Broken Anchor Links

1 broken anchor link(s) found — these will cause the build to fail.

  docs/accessanalyzer/2601/install/install-commands.md:114
    `LDAP_BIND_PASSWORD` is the only secret environment variable, and the installer doesn't actually honor it — the installer always reads the bind password via an interactive prompt or piped stdin, overwriting any exported value. See [Quick Install — Step 3](quickinstall.md#required-actions) for the two supported ways to provide the password.
    #required-actions not found in docs/accessanalyzer/2601/install/quickinstall.md
    Available: #quick-install · #prerequisites-checklist · #system-requirements · #dns · #tls-certificates · #bring-your-own-certificate-file-requirements · #active-directory-information · #first-admin-account · #license-key · #connector-port-requirements · #internal-port-requirements · #required-domains · #installation · #step-1-ssh-into-the-server · #step-2-download-the-installer · #step-3-verify-the-download · #step-4-run-the-installer · #step-5-review-the-installation-summary · #step-6-sign-in · #breakglass-account · #option-b-entra-id-authentication-oidc · #step-1-prepare-the-vm-upload-certs-and-trust-the-ca · #step-2-set-environment-variables · #step-3-download-and-run-the-installer · #step-4-verify-the-installation · #step-5-sign-in-with-entra-id-credentials · #roles · #troubleshooting · #reinstalling

Auto-Fix Summary

40 issues fixed, 20 skipped across 9 files

Category	Fixes
Contractions	12
Plurals	1
Dale: idioms	1
Dale: passive-voice	21
Dale: positional-references	5

Skipped (needs manual review)	Reason

| docs/accessanalyzer/2601/configurations/identity-provider.md:93 — Dale: passive-voice | 'this traffic is permitted' — actor (firewall) is implicit; rewriting to 'the firewall permits' would assert which device handles the rule, beyond what the source intends |
| docs/accessanalyzer/2601/configurations/identity-provider.md:106 — Dale: passive-voice | Table description 'where user accounts are stored' — concise table phrasing; alternatives change the descriptor's meaning |
| docs/accessanalyzer/2601/configurations/identity-provider.md:114 — Dale: passive-voice | 'whose email was entered' — entered by an unspecified party (could be the deployer or installer); rewrite would require choosing an actor that may be incorrect |
| docs/accessanalyzer/2601/configurations/identity-provider.md:133 — Dale: passive-voice | 'no matching account has been created' — present perfect passive; rewriting risks changing temporal nuance about pre-provisioning |
| docs/accessanalyzer/2601/configurations/identity-provider.md:136 — Dale: passive-voice | 'address sent by the IdP or stored in the LDAP mail attribute' — adjectival participles; multiple actors make a clean rewrite ambiguous |
| docs/accessanalyzer/2601/configurations/identity-provider.md:145 — Dale: passive-voice | 'No password is required' — common state-of-being construction; alternatives less natural in context |
| docs/accessanalyzer/2601/configurations/identity-provider.md:176 — Dale: passive-voice | 'Roles and permissions are set in Access Analyzer, not in your IdP or directory' — emphasizes location of configuration; active rewrite obscures the contrast |
| docs/accessanalyzer/2601/configurations/identity-provider.md:179 — Dale: passive-voice | 'their name and email are set from the IdP token and can't be changed' — multiple passive constructs in a table cell; rewrite would require restructuring the row |
| docs/accessanalyzer/2601/install/identity-provider.md:33 — Dale: passive-voice | 'system requirements are met' — checklist style commonly uses past-participle states for verification items |
| docs/accessanalyzer/2601/install/identity-provider.md:65 — Dale: passive-voice | 'The alias is shown as the label on the login button' — state describing UI; alternatives like 'Keycloak displays the alias' assert a specific component |
| docs/accessanalyzer/2601/install/identity-provider.md:166 — Dale: passive-voice | 'is signed by an internal CA' — conditional clause; rewriting changes the relative-clause structure and may obscure the precondition |
| docs/accessanalyzer/2601/install/identity-provider.md:256 — Dale: passive-voice | 'are read from environment variables' — explains data flow; ambiguous which component does the reading (Keycloak/kcadm.sh/the pod) |
| docs/accessanalyzer/2601/install/install-commands.md:22 — Dale: passive-voice | Inside HIDDEN block; not visible to readers |
| docs/accessanalyzer/2601/install/postinstall.md:68 — Dale: passive-voice | 'should be deployed and healthy' — expected-state construction with modal 'should'; rewrite changes conditional nuance |
| docs/accessanalyzer/2601/install/quickinstall.md:81 — Dale: passive-voice | 'to be signed by your internal Enterprise CA' — passive infinitive in a complex table cell; rewriting risks meaning change |
| docs/accessanalyzer/2601/install/quickinstall.md:85 — Dale: passive-voice | 'is always required' — state-of-being construction in admonition; alternatives change emphasis |
| docs/accessanalyzer/2601/install/quickinstall.md:287 — Dale: passive-voice | Table cell description 'where user accounts are stored' — concise table phrasing |
| docs/accessanalyzer/2601/install/system/certificates.md:32 — Dale: passive-voice | 'Must be readable by the OS user' / 'may be owned by root' — multiple state passives in bullet items; rewrite would substantially restructure the section |
| docs/accessanalyzer/2601/install/system/network.md:46 — Dale: passive-voice | 'is exposed externally' — state describing port exposure; rewrite to 'the installer exposes' asserts a specific actor and timing |
| docs/accessanalyzer/2601/install/system/requirements.md:99 — Dale: passive-voice | 'If no swap is configured on a system' — conditional state; rewrites either remain passive or change the meaning |

Ask @claude on this PR if you'd like an explanation of any fix.

[github-actions]

Documentation PR Review

Editorial Review

docs/accessanalyzer/2601/configurations/identity-provider.md

• Clarity — Line 116: "From here, add additional users under Configuration > Users." reads as a sentence fragment with an abrupt transition. Suggested fix: "After signing in, pre-provision additional users under Configuration > Users."
• Clarity — Line 118: "Breakglass account" is jargon that may be unfamiliar to newer administrators (CLAUDE.md: "Never assume what the reader knows"). The body explains it as a "recovery mechanism," but the heading itself is opaque. Suggested fix: rename the heading to "Recovery account (admin@dspm.local)" or add a short parenthetical: "Breakglass (recovery) account."
• Completeness — Line 120: The procedure tells the reader to "retrieve the bootstrap password to regain access" but doesn't say what to do after they have it (where to navigate, how to sign in, what to do once inside). Suggested fix: add the explicit sign-in steps, or link to the Quick Install Step 6 sign-in section that covers this.

docs/accessanalyzer/2601/configurations/users.md

• Completeness — Line 58: The link text says "Quick Install — Step 5" but the anchor #step-6-sign-in and the actual heading in quickinstall.md is "Step 6: Sign in" (not Step 5 — Step 5 is now "Review the installation summary"). The visible link label will mislead readers. Suggested fix: change the link text to "Quick Install — Step 6".

docs/accessanalyzer/2601/install/identity-provider.md

• Structure — Line 5: draft: true was added. Confirm no published pages link here — the diff shows the cross-reference from configurations/identity-provider.md was rerouted to network.md and certificates.md, which is consistent, but verify no other live pages still point at this file (Docusaurus throws on broken links).

docs/accessanalyzer/2601/install/install-commands.md

• Structure — Line 5: draft: true was added. Same caveat as above — confirm no live pages link to this file. The cross-reference removed from postinstall.md line 97 in this PR is consistent with that intent.
• Completeness — Line 114: The link quickinstall.md#required-actions points to a heading that does not exist as a markdown heading. "Required Actions" appears only inside the fenced code block at lines 308–336 of quickinstall.md, not as an ## or ### heading, so the anchor won't resolve at build time. Suggested fix: link to a real anchor that covers password handling, e.g. quickinstall.md#step-4-run-the-installer, since that section is where the bind password is entered.

docs/accessanalyzer/2601/install/postinstall.md

• No issues found.

docs/accessanalyzer/2601/install/quickinstall.md

• Clarity — Line 18: "Bring Your Own" uses title-case capitalization that doesn't match the option name "Bring your own certificate" used everywhere else in the file (lines 76, 82, 88, 90). Suggested fix: "TLS certificate option chosen; certificate files prepared if using Bring your own certificate."
• Clarity — Line 19: "AD/DC Root CA bundle" (lowercase "bundle") is inconsistent with "AD/DC Root CA Bundle" (capitalized "Bundle") used in the prompt reference and Active Directory information sections. Pick one form and apply consistently across the file.
• Clarity — Line 22: "Netwrix license key on hand" — [idiom] "on hand" is idiomatic. Suggested fix: "Netwrix license key available."
• Clarity — Line 80: "browsers will show a security warning" uses future tense; Netwrix style is present tense. Suggested fix: "browsers show a security warning."
• Completeness — Line 81: "Sign with AD Certificate Services" introduces "AD CS" without spelling it out. CLAUDE.md requires acronyms be spelled out on first use. Suggested fix: "Sign with Active Directory Certificate Services (AD CS)" on first mention.
• Clarity — Line 290: "Advanced Settings | No (standard installations)" — the parenthetical reads as a label rather than guidance. Suggested fix: "No — recommended for standard installations."
• Structure — Lines 304–306: The note "You can skip this step if you're signing in for the first time and only need to add users and assign roles. Return to complete the required actions before using kubectl or configuring firewall rules." contradicts the bolded instruction at line 338: "Complete the required actions before signing in:". One of the required actions IS configuring the firewall (line 340), so the note simultaneously says "skip" and the section says "do these before signing in." Suggested fix: rewrite the note to say Step 5 is informational only — readers may scan the summary and proceed — and remove the "before configuring firewall rules" clause that conflicts with the required-actions list immediately below.
• Clarity — Line 341: "Commands like kubectl get pods will not work until you do this." Future tense; style guide prefers present tense. Suggested fix: "Commands like kubectl get pods don't work until you do this."
• Clarity — Line 347: "From here, add additional users under Configuration > Users." Same fragment phrasing as in configurations/identity-provider.md. Suggested fix: "After signing in, add additional users under Configuration > Users."
• Clarity — Line 349: "Breakglass account" — same jargon concern as in configurations/identity-provider.md. Apply the same fix in both files for consistency.

docs/accessanalyzer/2601/install/system/certificates.md

• No issues found.

docs/accessanalyzer/2601/install/system/network.md

• Clarity — Line 87: "The installer's preflight check detects common antivirus products and will prompt you to confirm exclusions are in place before proceeding." Future tense. Suggested fix: "...and prompts you to confirm exclusions are in place before proceeding."

docs/accessanalyzer/2601/install/system/requirements.md

• No issues found.

docs/accessanalyzer/2601/install/uninstall.md

• No issues found.

Summary

15 editorial suggestions across 10 files. Notable items: a broken anchor in install-commands.md (#required-actions is inside a code block, not a real heading), a mismatched link label in configurations/users.md ("Step 5" vs the actual Step 6), and a contradictory note/instruction pair in quickinstall.md Step 5. Vale and Dale issues are auto-fixed separately.

---

What to do next:

Comment @claude on this PR followed by your instructions to get help:

• @claude fix all issues — fix all editorial issues
• @claude help improve the flow of this document — get writing assistance
• @claude explain the voice issues — understand why something was flagged

You can ask Claude anything about the review or about Netwrix writing standards.

Automated fixes are only available for branches in this repository, not forks.

[github-actions]

⚠️ Broken Anchor Links

1 broken anchor link(s) found — these will cause the build to fail.

  docs/accessanalyzer/2601/install/install-commands.md:114
    `LDAP_BIND_PASSWORD` is the only secret environment variable, and the installer doesn't honor it — the installer always reads the bind password via an interactive prompt or piped stdin, overwriting any exported value. See [Quick Install — Step 3](quickinstall.md#required-actions) for the two supported ways to provide the password.
    #required-actions not found in docs/accessanalyzer/2601/install/quickinstall.md
    Available: #quick-install · #prerequisites-checklist · #system-requirements · #dns · #tls-certificates · #bring-your-own-certificate-file-requirements · #active-directory-information · #first-admin-account · #license-key · #connector-port-requirements · #internal-port-requirements · #required-domains · #installation · #step-1-ssh-into-the-server · #step-2-download-the-installer · #step-3-verify-the-download · #step-4-run-the-installer · #step-5-review-the-installation-summary · #step-6-sign-in · #breakglass-account · #option-b-entra-id-authentication-oidc · #step-1-prepare-the-vm-upload-certs-and-trust-the-ca · #step-2-set-environment-variables · #step-3-download-and-run-the-installer · #step-4-verify-the-installation · #step-5-sign-in-with-entra-id-credentials · #roles · #troubleshooting · #reinstalling

Auto-Fix Summary

25 issues fixed, 7 skipped across 10 files

Category	Fixes
Contractions	4
Dale: passive-voice	18
Dale: positional-references	2
Dale: wordiness	1

Skipped (needs manual review)	Reason

| docs/accessanalyzer/2601/install/identity-provider.md:33 — Dale: passive-voice | Bullet in a 'Before you begin' checklist where 'requirements are met' / 'are prepared' is the conventional format for prerequisite confirmation; rewriting would change the discoverable scanning pattern. |
| docs/accessanalyzer/2601/configurations/identity-provider.md:136 — Dale: passive-voice | Multiple participial passives ('entered during pre-provisioning', 'sent by the IdP', 'stored in the LDAP mail attribute') function as adjectives describing the email values; rewriting would split the sentence and change emphasis. |
| docs/accessanalyzer/2601/configurations/users.md:99 — Dale: passive-voice | 'When your deployment is configured to use an external Identity Provider' — making it active ('When you've configured your deployment') changes who performed the action and may not be accurate, since the deployment may have been set up by another team. |
| docs/accessanalyzer/2601/install/postinstall.md:68 — Dale: passive-voice | 'The following components should be deployed and healthy after a successful installation' — the active rewrite ('The installer should deploy ... and they should be healthy') is awkward and the agent isn't the focus; the sentence is describing post-state. |
| docs/accessanalyzer/2601/install/quickinstall.md:22 — Dale: idioms | 'Netwrix license key on hand' — 'on hand' is borderline idiomatic but is well-understood standard business English; rewriting risks unwanted formality. |
| docs/accessanalyzer/2601/install/quickinstall.md:464 — Dale: passive-voice | 'The bootstrap admin@dspm.local account is assigned this role' is inside a SYNC block instructed to remain matched to a counterpart in another file; modifying may diverge from the source-of-truth pattern. |
| docs/accessanalyzer/2601/configurations/identity-provider.md:178 — Dale: passive-voice | 'is available for local accounts only' is a stative passive describing availability state, not an action; active rewrite would distort meaning. |

Ask @claude on this PR if you'd like an explanation of any fix.