Merge pull request #1491 from netwrix/jordan/AA-docs-26.1-rewrite docs(accessanalyzer): rewrite the 26.1 documentation

.claude/references/kb-editing-conventions.md

@@ -229,7 +229,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 — 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.
+**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-26.1/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:
 

docs/accessanalyzer/2601/gettingstarted/sharepoint-online/_category_.json → docs/accessanalyzer/26.1/agents/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "SharePoint Online",
+  "label": "Agents",
   "position": 50,
   "collapsed": true,
   "collapsible": true

docs/accessanalyzer/26.1/agents/agent-labels.md

@@ -0,0 +1,99 @@
+---
+title: Agent Labels and Scan Routing
+description: How agent labels route each scan execution to an agent, and what happens when no agent carries the label.
+sidebar_position: 2
+---
+
+Labels are how you tell a scan where to run. Each deployed agent carries one or more `key=value` labels. A scan names a label, and its executions run on an agent that carries it. Leave the label out and the scan runs on the System agent.
+
+Agent labels are separate from the labels you put on sources. Source labels group sources and pick scan targets; agent labels pick the machine that does the scanning. They don't interact, and they follow different rules. [Labels](../sources/labels.md) describes source labels.
+
+## Agent Labels
+
+You add labels when you [deploy an agent](deploy-agent.md) and change them later with **Edit**. A deployed agent must have at least one label. The System agent has no labels you can edit, so its **Labels** column on the Agents page is empty.
+
+The **Labels** field's hint reads "Keys and values are lowercased; spaces become hyphens." Access Analyzer trims surrounding spaces, lowercases the key and the value, and turns each run of spaces inside them into a single hyphen. Enter `Data Center` as the key and `US East` as the value, and the stored label is `data-center=us-east`.
+
+After that clean-up, the key and the value must fit these rules.
+
+| Part | Must start with | Can contain | Maximum length |
+|---|---|---|---|
+| Key | A letter or number | Letters, numbers, and hyphens | 53 characters |
+| Value | A letter or number | Letters, numbers, hyphens, underscores, and dots | 63 characters |
+
+Avoid two keys. Access Analyzer reserves `name`, and `default` marks the System agent internally. Common choices are `region`, `environment`, and `network`, but any keys that make sense for you are fine.
+
+Pick labels around how you'll route scans, not around how the hosts are built. `region=us-east` and `network=dmz` describe what a scan needs; `cpu=16` doesn't. The **Search agents…** field on the Agents page finds agents by label key, label value, or `key:value`, so a consistent scheme helps there too.
+
+## Agent Selection
+
+You select a scan's agent when you create it, in the **Agent** field on the **Schedule** step. The dropdown has two groups: **System**, holding the single option **System agent**, and **Agent labels**, listing every `key=value` your agents carry. Select one label. Any agent that carries it can run the scan.
+
+![Agent location options](/images/accessanalyzer/26.1/scans/create-scan-4-schedule-agent-menu.webp)
+
+A scan with several sources can send one of them elsewhere. On the **Configure** step:
+
+1. Expand the source type's section (for example **File Server**).
+2. Click **Add source override**.
+3. In **Source to override**, select the source.
+4. In the override's **Agent** field, select a label.
+
+Click **Remove override** to undo it. The override applies to that source only; the scan's other sources keep the scan-level choice.
+
+When an execution starts, Access Analyzer picks the agent for each source in this order:
+
+```mermaid
+flowchart TD
+    A[Execution starts for a source] --> B{Source has an agent override?}
+    B -- Yes --> C[Use the override label]
+    B -- No --> D{Scan has an agent label?}
+    D -- Yes --> E[Use the scan-level label]
+    D -- No --> F[Run on the System agent]
+    C --> G{An online agent carries the label?}
+    E --> G
+    G -- Yes --> H[Execution runs on that agent]
+    G -- No --> I[Execution waits]
+```
+
+Two details matter here. First, matching is exact: the agent must carry both the key and the value of the label you picked. An agent labeled `region=us-west` doesn't qualify for `region=us-east`, and an agent with only `env=production` doesn't either. Second, an agent that shows **Offline** on the Agents page can't run scans, so a match on labels alone isn't enough; the agent must be online.
+
+Access Analyzer decides routing each time an execution starts, not when you save the scan. Relabeling an agent, or changing a scan's **Agent** field, takes effect from the next execution.
+
+The **Agent** column on the Scans page shows where each scan runs: **System** for scans with no label, otherwise the label.
+
+## Executions With No Matching Agent {#when-no-agent-matches}
+
+The **Agent** dropdown only offers labels that agents carry, but nothing checks again later. If you delete or relabel the only agent with a scan's label, the scan keeps that label and its schedule fires as normal. Access Analyzer creates the execution, but no scanning happens and the execution doesn't fail immediately. It waits for an agent that carries the label to come online: a new agent you deploy, an offline agent that comes back, or an existing agent you relabel. If no matching agent comes online within about two hours, Access Analyzer marks the execution **Failed**, and the scan's next scheduled execution tries again.
+
+The same wait happens when the only matching agent goes offline.
+
+If an execution shows **Running** but makes no progress:
+
+1. Go to **Configuration > Agents**.
+2. Check for a **Healthy** agent whose **Labels** include the scan's label.
+3. If there isn't one, deploy an agent with that label, bring the offline agent back online, or edit the scan and select a label that an online agent carries.
+
+Editing the scan fixes its next execution only; the execution that's already waiting still needs a matching agent to come online. The Home page's **Needs attention** panel lists offline agents with a **Check agents** link, the quickest way to spot an agent that has gone offline. [Scan executions](../scans/scan-executions.md) lists every execution and its status.
+
+## Example
+
+Suppose you run the Access Analyzer server in your main data center and have two more agents deployed.
+
+| Agent | Labels |
+|---|---|
+| **Default Agent** (the System agent) | none |
+| `agent-east` | `env=production`, `region=us-east` |
+| `agent-west` | `env=production`, `region=us-west` |
+
+You configure four scans.
+
+| Scan | Agent field | Override | Where it runs |
+|---|---|---|---|
+| HR shares | **System agent** | none | On the server, because you set no label |
+| East finance shares | `region=us-east` | none | On `agent-east`, the only agent with that label |
+| All production shares | `env=production` | none | On either `agent-east` or `agent-west`, since both carry the label |
+| Regional archives | `region=us-east` | `fs-west-01` set to `region=us-west` | On `agent-east` for every source except `fs-west-01`, which runs on `agent-west` |
+
+If `agent-west` goes offline, "All production shares" keeps running on `agent-east`, while the `fs-west-01` override in "Regional archives" waits for `agent-west` to report **Healthy** again, or fails after about two hours.
+
+Later you delete `agent-east` to rebuild it. "East finance shares" and the `region=us-east` sources of "Regional archives" keep their label, so their next executions wait, while "All production shares" continues on `agent-west`. The waiting executions start as soon as you deploy the rebuilt agent with `region=us-east` again; if that takes longer than about two hours, Access Analyzer marks them **Failed** and the next scheduled executions try again.

docs/accessanalyzer/26.1/agents/deploy-agent.md

@@ -0,0 +1,136 @@
+---
+title: Deploy an Agent
+description: Prepare a Linux host and an SSH service account, deploy the agent from the Agents page, and edit or remove it later.
+sidebar_position: 1
+---
+
+Access Analyzer installs agents for you. You point it at a Linux host it can reach over SSH, and the server runs a set of checks, installs the agent software, and joins the host to the installation. You don't install anything on the host by hand.
+
+You need the Admin role for everything on this page. Viewers can see the Agents page but can't deploy, edit, or remove agents.
+
+## Prepare the Host
+
+The host needs a Linux operating system with `bash`, `curl`, and `sudo` installed, an SSH user the server can sign in as, and enough headroom to run scans. Access Analyzer checks every requirement in this table before it installs anything, both when you click **Test connection** and again at the start of a real deployment.
+
+| Requirement | Minimum |
+|---|---|
+| CPU | 2 cores |
+| Memory | 512 MB available |
+| Disk | 5 GB free on `/` |
+| SSH user | Can run `sudo` without a password |
+| Tools | `bash`, `curl`, and `sudo` on the path |
+| Internet | Can reach `https://get.k3s.io` |
+
+The host also needs these network paths; every port is Transmission Control Protocol (TCP). [Requirements](../install/requirements.md) lists the server side of the first two rows.
+
+| Direction | Port | Purpose |
+|---|---|---|
+| Server to host | TCP 22, or the port you enter in **SSH port** | SSH session that installs and configures the agent |
+| Host to server | TCP 6443 | The agent's connection to the Access Analyzer server |
+| Host to `get.k3s.io` | TCP 443 | Agent software installer |
+| Host to `raw.githubusercontent.com` | TCP 443 | Installer checksum |
+| Host to `oci.pkg.keygen.sh` | TCP 443 | Licensed software distribution for scan components |
+
+A deployed agent runs scan work and nothing else. Access Analyzer places nothing else on it.
+
+## SSH Service Account
+
+Access Analyzer signs in to the host with a service account of type **SSH username/key**. The account holds two values: **SSH username**, the Linux user to sign in as, and **SSH key**, that user's private key pasted in PEM or OpenSSH format. The key must not have a passphrase; deployment rejects a passphrase-protected key. The user must be able to run `sudo` without a password prompt.
+
+You can create the account ahead of time under **Configuration > Service accounts**, or from inside the Deploy agent panel with the **Add new service account** button next to the **Service account** field. The inline **Add service account** form fixes the type to **SSH username/key**; click **Add account** to save it. Either way the result is the same account, and you can reuse it for every agent that uses the same user and key. The field-level detail is in [SSH username and key](../service-accounts/ssh-key.md).
+
+The host key isn't part of the service account. Each agent has its own, entered when you deploy it.
+
+## Get the Host Key
+
+Access Analyzer checks the host's SSH identity against the key you enter and refuses to continue if the host presents a different one. Collect the public host key from a machine that can reach the host, such as the Access Analyzer server:
+
+```bash
+ssh-keyscan -t ecdsa <host>
+```
+
+If SSH listens on a port other than 22, add `-p <port>`. The output line begins with the hostname; copy the key type and the key that follow it, for example `ecdsa-sha2-nistp256 AAAA…`. That is the value the **SSH host key** field expects: a key type, a space, and the key. If you can, compare it with the key on the host itself before you trust it.
+
+## Deploy the Agent
+
+1. Go to **Configuration > Agents**.
+2. Click **Deploy agent**.
+
+   ![Deploy agent panel with Name, SSH host, SSH host key, SSH port, Service account, and Labels](/images/accessanalyzer/26.1/agents/deploy-agent.webp)
+
+3. In **Name**, enter a name for the agent.
+4. In **SSH host**, enter the hostname or IP address of the host.
+5. In **SSH host key**, paste the host key you collected.
+6. In **SSH port**, enter the SSH port if it isn't 22.
+7. In **Service account**, select the SSH account. To create one now, click **Add new service account**.
+8. Under **Labels**, add at least one label, such as `env=production` or `region=us-east`. Labels are how scans find this agent; see [Agent labels and scan routing](agent-labels.md).
+9. To check the host before installing anything, click **Test connection** and wait for **Connection successful**.
+10. Click **Deploy**.
+
+When deployment finishes, the panel closes, a notification reads `Agent "<name>" deployed`, and the agent appears in the list with its **Health Status** and **Last Heartbeat**.
+
+### Fields
+
+| Field | What to enter | Rules |
+|---|---|---|
+| **Name** | A display name, for example `Production Agent` | Required; up to 255 characters |
+| **SSH host** | Hostname or IP address, for example `node01.company.com` or `192.168.1.50` | Required; up to 255 characters; must be a valid hostname or IP address |
+| **SSH host key** | The host's public key as `<key-type> <key>` | Required; must match the key the host presents |
+| **SSH port** | The SSH port | Optional; 1 to 65535; defaults to 22 |
+| **Service account** | An account of type SSH username/key | Required; the list shows only SSH accounts; **Edit credentials** opens the selected account |
+| **Labels** | One or more `key=value` pairs | At least one required; keys and values are lowercased and spaces become hyphens |
+
+If you close the panel with unsaved changes, Access Analyzer asks you to confirm.
+
+### Test Connection
+
+In the Deploy agent panel, **Test connection** becomes available after you fill in **SSH host**, **SSH host key**, and **Service account**. It signs in to the host and runs the checks from [Prepare the host](#prepare-the-host), installing nothing. The button reads **Testing...** while it runs.
+
+A green **Connection successful** alert means every check passed. It can carry warnings underneath. A red alert reports what failed, for example a missing `curl`, a `sudo` that prompts for a password, or too little free disk. The result clears if you change any of the connection fields.
+
+### Deployment Sequence
+
+1. The server signs in over SSH and runs the same checks as **Test connection**.
+2. It configures the host to download scan components from the software distribution service, authenticated with your license key, and writes the key to a root-only file on the host.
+3. It installs the agent software on the host at the same version the server runs.
+4. The host connects to the server on port 6443 and joins the installation.
+5. The server applies the name and labels you entered to the agent.
+
+Allow about five minutes. Installation typically takes three to four minutes, and the server allows five minutes for the whole deployment, from signing in over SSH to the agent checking in. If it hasn't checked in by then, deployment still finishes. The Agents list refreshes every 60 seconds, so the agent can still appear a little later.
+
+If deployment fails, the panel shows the reason. Causes include an SSH user without passwordless `sudo`, a host that can't reach the server on port 6443, and a pasted host key that doesn't match the host.
+
+## Edit an Agent
+
+1. Go to **Configuration > Agents**.
+2. In the agent's **Actions** menu, click **Edit**.
+
+   ![Agent row menu with Edit](/images/accessanalyzer/26.1/agents/row-actions.webp)
+
+3. Change the **Name** or the **Labels**. A deployed agent must keep at least one label.
+
+   ![Edit agent panel with Name and Labels](/images/accessanalyzer/26.1/agents/edit-agent.webp)
+
+4. Click **Save changes**.
+
+The SSH fields don't appear when you edit. Access Analyzer uses SSH only to deploy the agent; after that, the agent talks to the server over its own connection and no longer needs the host key or service account.
+
+**Test connection** works differently here: instead of checking the host over SSH, it sends a short test task through the agent and confirms it runs. It's a quick way to prove a deployed agent can accept work. Success shows **Connection successful**; a failure shows the server's message.
+
+You can't rename or relabel the System agent, listed as **Default Agent**; opening **Edit** on it shows **Name** and **Labels** locked.
+
+## Remove an Agent
+
+1. Go to **Configuration > Agents**.
+2. In the agent's **Actions** menu, click **Delete**.
+3. Click **Delete Agent** to confirm.
+
+A notification reads `Agent "<name>" deleted`, and the agent leaves the list.
+
+Removal takes the agent out of Access Analyzer. The server doesn't connect to the host again, and the agent software stays installed there until you remove it yourself.
+
+You can't remove an agent while a scan is running on it; the attempt fails with **Failed to delete agent**. Wait for the execution to finish, or stop it from [Scan executions](../scans/scan-executions.md), then try again.
+
+Scans whose agent label pointed at the removed agent keep that label. Their next execution waits until another agent with matching labels is available, as described in [Agent labels and scan routing](agent-labels.md#when-no-agent-matches). Edit those scans, or deploy a replacement agent with the same labels, before their next scheduled run.
+
+The System agent has no **Delete** action.