QUA-1756: Restructure anomaly docs and document Assignees

docs/anomalies/deep-dive/assignees.md

@@ -0,0 +1,85 @@
+# Anomaly Assignees
+
+This page covers the behavior of the **Assignees** field on an anomaly. For step-by-step actions, see [Add Anomaly Assignees](../how-tos/assignee/add-assignee.md){:target="_blank"}, [Remove Anomaly Assignees](../how-tos/assignee/remove-assignee.md){:target="_blank"}, and [Bulk-Assign Anomalies](../how-tos/assignee/bulk-assign.md){:target="_blank"}.
+
+## The field
+
+The **Assignees** field on an anomaly is a list of users responsible for reviewing and resolving it. An anomaly can have zero, one, or many assignees, and any user with at least the **Viewer** role on the datastore can be selected. In the **Summary** section of the anomaly details, the first assignee's avatar is shown, with the names of assignees beside it. With one or two assignees, all names appear. With three or more, only the first assignee's name appears, followed by `+N` for the remaining count. A `+N` badge sits beside the avatar whenever an anomaly has more than one assignee; hovering the badge shows the remaining assignees.
+
+The field is independent from the anomaly's **status**, **description**, and **tags**: assigning a user does not change any of those, and changing those does not change the assignees. The only automatic write to this field happens at creation, as described in [Inheritance from the originating check](#inheritance-from-the-originating-check) below.
+
+## Inheritance from the originating check
+
+Every quality check has a single **Default Anomaly Assignee** field, available on both Authored and AI Managed checks. For details, see [Anomaly Assignee](../../data-quality-checks/ai-managed/edit.md#anomaly-assignee){:target="_blank"} on the check editing guide. When a new anomaly is created from a check that has a default assignee set, that user is automatically added as the initial assignee of the anomaly.
+
+A few details worth knowing:
+
+- **Anomalies can have many failed checks.** When the anomaly is generated from multiple failed checks, the default assignees of every contributing check are combined into a single list with duplicates removed, then applied to the anomaly. So if check A defaults to user *Alice* and check B defaults to user *Bob*, an anomaly produced from both checks is created with **Alice and Bob** as assignees.
+- **Inheritance happens only at creation.** Changing a check's default assignee later does **not** retroactively re-assign anomalies that have already been created. Existing anomalies keep whatever assignees they have until someone edits them.
+- **Checks without a default contribute nothing.** Only failed checks that have a default assignee add users to the list. If every failed check behind an anomaly has no default, the anomaly is created with no assignees.
+
+## Permissions
+
+| Action | Required permission on the anomaly's datastore |
+| :--- | :--- |
+| See the Assignees field | Viewer |
+| Be selectable as an assignee | Viewer |
+| Add or remove assignees | Author |
+
+When editing, the user picker lists every user that has at least the **Viewer** role on the datastore. Users without access are filtered out by the platform and cannot be assigned even by an Author. See [Team Permissions](../../settings/security/teams/team-permissions/overview.md){:target="_blank"} for the full role matrix.
+
+!!! note "Archived anomalies are read-only"
+    Assignees of archived anomalies (status **Resolved**, **Duplicate**, **Invalid**, or **Discarded**) cannot be changed. Restore the anomaly first (it returns to **Acknowledged**) before editing assignees.
+
+## Notifications
+
+Whenever an anomaly's **status**, **tags**, **description**, or **assignees** change, the platform creates an **Assignment** in-app notification for every user currently listed as an assignee, except the user who made the change. The notification has the form:
+
+> *<updater name>* updated an anomaly you're assigned to
+>
+> `#<anomaly id>` • *<current status>*
+
+Clicking the notification opens the affected anomaly.
+
+A few specifics:
+
+- **Self-edits do not notify.** If you edit the anomaly yourself, you do not get a notification for that edit. Other assignees do.
+- **Newly added assignees are notified.** When a user is added to the assignee list, they become part of the recipient set for the same update event. The notification is the first signal they receive about the anomaly.
+- **Removed assignees are not notified.** Users who are removed from the assignee list as part of the update do not receive a notification for that update.
+- **Creation is silent.** Auto-assignment via the originating check's default assignee at anomaly creation does **not** produce a notification. The first notification for a newly created anomaly fires on the next update event.
+
+See [In-App Notifications · Assignment](../../using-the-platform/web-app/top-right-menu/in-app-notifications.md#assignment){:target="_blank"} for how Assignment notifications appear in the bell-icon list alongside other notification types.
+
+## History tracking
+
+Every change to the assignee list is recorded in the anomaly's **History** section, alongside status changes, description edits, tag updates, and comments. The timeline shows:
+
+- **Who** made the change.
+- **When** the change happened.
+- **Which users** were added and which were removed.
+- **Self-assignment and self-unassignment** entries are surfaced explicitly, so it is clear when a teammate took ownership of an anomaly or stepped away from it. Like other assignee edits, this requires the **Author** team permission on the anomaly's datastore.
+
+See the [History](insights.md#history){:target="_blank"} section of the Anomaly Insights page for how to read and comment on the timeline.
+
+## Assignees, owners, and default assignees
+
+Three related concepts are easy to mix up. Here is how they differ:
+
+| Concept | Lives on | Cardinality | What it does |
+| :--- | :--- | :---: | :--- |
+| **Owner** | Quality check | One user | The person responsible for the check itself. Used for filtering checks by owner and for ownership notifications. |
+| **Default Anomaly Assignee** | Quality check | One user | The user that anomalies produced by the check are auto-assigned to at creation time. |
+| **Assignees** | Anomaly | Many users | The users actually responsible for resolving the anomaly. Editable per anomaly. |
+
+So the chain reads: a check has one owner and one default assignee; when the check produces an anomaly, that default seeds the anomaly's assignees list, which can then be expanded or narrowed independently.
+
+## Filtering by assignee
+
+You can narrow the anomaly list to a specific set of users in two ways:
+
+- **The Assignees filter.** A multi-select dropdown of active platform users. Selecting one or more users narrows the list to anomalies where any selected user is an assignee. Available on both the [explore anomalies](../../explore/anomalies.md){:target="_blank"} page and the per-datastore anomalies tab.
+<!-- TODO: When the Filter and Sort how-to page documents the Assignees filter, restore the cross-link below at the end of the bullet above. -->
+<!-- ; see [Filter and Sort · Assignees](../how-tos/filter-and-sort.md#filter-by-assignee){:target="_blank"} -->
+- **The Assigned subtab inside Open.** A one-click shortcut to "open anomalies assigned to me." See [Open · Assigned](../../explore/anomalies.md#open){:target="_blank"}.
+
+Both work alongside the other anomaly filters (tags, rule type, timeframe, etc.), so you can layer them. For example, combine "assigned to me" with a specific tag or a "last 7 days" window to narrow the list further.

docs/anomalies/deep-dive/description.md

@@ -0,0 +1,69 @@
+# Anomaly Description
+
+The **Description** is a business-friendly explanation of the data quality issue captured by an anomaly. It appears in the **Description** section of the anomaly details view and serves as a free-text field that complements the structured attributes (Status, Severity, Failed Checks, etc.) with narrative context.
+
+For the step-by-step tutorial on editing, see [Edit Anomaly Description](../how-tos/edit-description.md){:target="_blank"}.
+
+## How the default description is built
+
+When Qualytics creates an anomaly during a Scan operation, it auto-fills the description by combining the messages of every failed check into a multi-line summary like:
+
+```
+Field customer_id is expected to be not null;
+ Field email is expected to match pattern ^[^@]+@[^@]+\.[^@]+$
+```
+
+Each failed-check message includes the rule type, the field involved, and the expected condition that was violated. The default acts as a starting point: users can leave it as-is, refine it, or rewrite it entirely.
+
+!!! note
+    The default description is only set at anomaly creation. Once a user edits the text, re-running a Scan does not overwrite it.
+
+## Editing the description
+
+Any user with the **Editor** team permission (or higher) on the anomaly's datastore can edit the description. The **Edit :material-pencil-outline:** button appears next to the **Description** label in the anomaly details view. Clicking it switches the section into edit mode, with the following actions:
+
+| Action | What it does |
+| :--- | :--- |
+| **Edit :material-pencil-outline:** | Opens the description in edit mode. |
+| **Save** | Saves the new text and exits edit mode. The change is recorded in the anomaly's **History**. Disabled if the description is empty or contains only whitespace. |
+| **Cancel** | Discards unsaved changes and reverts to the previous description. |
+
+The Edit button is hidden on archived anomalies (Resolved, Duplicate, Invalid, Discarded) and for users without the **Editor** team permission.
+
+## AI-suggested description
+
+When Agent Q is configured on the deployment, a second button appears next to the **Description** label: **Suggest a description :material-star-four-points:**. Clicking it asks Agent Q to generate a candidate description from the anomaly's failed checks. The suggestion appears in an overlay with three options:
+
+| Action | What it does |
+| :--- | :--- |
+| **Use** | Replaces the current description with the suggestion. The text appears in the editor so you can still refine it before saving. |
+| **Regenerate** | Asks Agent Q for a fresh suggestion. Useful if the first proposal does not match the issue. |
+| **Dismiss** | Closes the overlay and keeps the current description unchanged. |
+
+If Agent Q is not configured for the deployment, the Suggest button is hidden. For details on configuring Agent Q, see the [Agent Q](../../agent-q/overview.md){:target="_blank"} documentation.
+
+## Description and masked fields
+
+If the failed check involved a [masked field](../../fields/field-status/concepts/field-masking.md){:target="_blank"}, the original value **never** appears in the description. The check failure message permanently shows `***MASKED***` in place of the actual value, both in the default description and in any later regeneration. To investigate the underlying value, reveal masked source records via the Source Records toolbar instead. See [Masked Fields in Source Records](source-record.md#masked-fields-in-source-records){:target="_blank"}.
+
+## Archived anomalies are read-only
+
+Once an anomaly is archived (status **Resolved**, **Duplicate**, **Invalid**, or **Discarded**), the description becomes read-only. The Edit and Suggest buttons disappear. To edit the description, restore the anomaly first; see [Restore Anomalies](../how-tos/restore-anomalies.md){:target="_blank"}.
+
+## History tracking
+
+Every description change is recorded in the anomaly's **History** section, alongside status changes, tag updates, assignee changes, and comments. Each entry shows:
+
+- The user who made the change.
+- The timestamp of the edit.
+- The previous value and the new value, so you can see exactly what changed.
+
+See the [History](insights.md#history){:target="_blank"} section of the Anomaly Insights page for details on the timeline.
+
+## Permissions summary
+
+| Action | Required permission on the anomaly's datastore |
+| :--- | :--- |
+| Read the description | Viewer team permission |
+| Edit the description | Editor team permission |
+| Suggest a description with Agent Q | Editor team permission + Agent Q configured on the deployment |

docs/anomalies/fingerprints.md → docs/anomalies/deep-dive/fingerprints.md

@@ -32,7 +32,7 @@ For **record-level anomalies**, fingerprinting is based on the specific check th
 
 ### Shape Anomalies
 
-For **shape anomalies**—which refer to patterns or distributions of data rather than individual records, the fingerprint is derived from a broader set of attributes:
+For **shape anomalies**, which refer to patterns or distributions of data rather than individual records, the fingerprint is derived from a broader set of attributes:
 
 * **Identifying check(s):** The rule(s) that triggered the anomaly at the dataset level.
 
@@ -69,7 +69,7 @@ The lack of a persistent identifier means **Qualytics** cannot distinguish betwe
 
 To handle recurring anomalies in truncate-and-reload tables, configure your scan to use fingerprint-based duplicate handling.
 
-Follow the steps in the [scan operation configuration](../operations/scan/scan.md#configuration) to reach the correct settings. Then, under **Step 8 → Scan Settings**, open the [anomaly options section](https://userguide.qualytics.io/source-datastore/scan/#configuration:~:text=Step%208%3A%20Configure%20the%20Scan%20Settings) and enable both duplicate-handling options:
+Follow the steps in the [scan operation configuration](../../operations/scan/scan.md#configuration) to reach the correct settings. Then, under **Step 8 → Scan Settings**, open the [anomaly options section](https://userguide.qualytics.io/source-datastore/scan/#configuration:~:text=Step%208%3A%20Configure%20the%20Scan%20Settings) and enable both duplicate-handling options:
 
 - **Archive Duplicate Anomalies:** When the same 127 anomalies appear again after the table reload, Qualytics recognizes their fingerprints and automatically marks them as duplicates rather than new anomalies.  
 - **Reactivate Recurring Anomalies:** If an anomaly was previously archived or resolved but reappears in subsequent scans, Qualytics reactivates the original anomaly record, maintaining full historical context.