QUA-1756: Restructure anomaly docs and document Assignees

[RafaelOsiro]

Overview

Restructures the Anomalies section into Deep Dive and How-tos hubs and documents the new Assignees feature end-to-end.

Key Changes

• anomalies/deep-dive/: new hub grouping Insights, Source Record, Types, Status, Fingerprints, and the new Assignees deep-dive.
• anomalies/how-tos/: replaces Manage Anomalies; adds Edit Description and Edit Tags (split from Edit Anomalies) plus the new Assignee subgroup (Add, Remove, Bulk-Assign).
• anomalies/api.md: new Anomalies API reference with a dedicated Manage assignees subsection.
• anomalies/faq.md: new Anomalies FAQ covering General, Types, Status, Fingerprints, Tags, Comments, Source Records, Assignees, Permissions, Filtering, and Bulk Operations.
• explore/anomalies.md: documents the new Assigned subtab and Assignees filter.
• mkdocs.yml: nav restructured to match the new hubs and redirects added for every legacy path.

Pages to Test

• http://localhost:8000/anomalies/overview/ — Types link points at deep-dive/types.md.
• http://localhost:8000/anomalies/deep-dive/assignees/ — H1 "Anomaly Assignees"; sections cover the field, inheritance, permissions, notifications (cross-link points at the In-App Notifications introduction page), history, the three-concept comparison table (Owner / Default Anomaly Assignee / Assignees), and filtering.
• http://localhost:8000/anomalies/how-tos/assignee/add-assignee/ — H1 carries the brick :material-plus-circle: icon; two tabs (Anomaly Overview / Anomaly Explore) with identical 6-step flow; single info admonition at the end covers permissions + notification rule.
• http://localhost:8000/anomalies/how-tos/assignee/remove-assignee/ — H1 carries the brick :material-minus-circle: icon; X-button references are labeled Remove (not "X"); note callout about self-unassignment plus tip cross-link to Bulk-Assign.
• http://localhost:8000/anomalies/how-tos/assignee/bulk-assign/ — H1 carries the brick :material-dots-vertical-circle: icon; ellipsis button labeled Bulk menu; Step 6 mentions the in-modal overwrite alert; closing warning flags the replace semantics.
• http://localhost:8000/anomalies/how-tos/filter-and-sort/ — Restructured into ## Sort options + ## Filter options H2s with shared canonical tables outside per-entry-point tabs; Filter table row 8 documents the Assignees filter; Filter by Assignee / Assigned subtab sections remain wrapped in an HTML comment as a TODO.
• http://localhost:8000/anomalies/api/ — H1 with brick :material-api:; API docs tip banner immediately after the intro; PUT/PATCH require Author (Editor only for description); dedicated Manage assignees subsection under Update.
• http://localhost:8000/anomalies/faq/ — H1 with brick :material-help-circle-outline:; "Can an Acknowledged anomaly go back to Active?" answers Yes; permissions answer reflects Author-base + Editor-for-description; comment-mention answer links to the In-App Notifications introduction.
• http://localhost:8000/explore/anomalies/ — Assigned subtab present between Acknowledged and All (screenshot pending, marked with TODO comment); filter table row 6 documents the Assignees filter.

Editorial polish round

• http://localhost:8000/anomalies/deep-dive/status/ — Open/Archived tables no longer list "All" as a status; !!! info admonition rewritten to describe Duplicate vs Discarded in terms of future-scan re-opening (validated against scan re-open logic); table headers normalized to Status | Description; intros now declare "two sub-statuses" and "four sub-statuses" symmetrically.

• http://localhost:8000/anomalies/deep-dive/source-record/ — TODO comment at the top flags future refactor of how-to content out of the Deep Dive (memory exception registered); sort table label is Importance (matches frontend); setting referenced consistently as Maximum Source Examples per Anomaly; ***MASKED*** literal documented; Editor team permission + Admin role terminology applied.

• http://localhost:8000/anomalies/how-tos/filter-by-status/ — Table headers normalized to | No. | Status | Description |; Step 2 reads "colored indicator" (not "icon"); 4 tabs preserved per affirming-capability convention (tables intentionally repeat per entry point).

• http://localhost:8000/anomalies/how-tos/tags/add-tags/ — Lead now includes API link; Step 3 reads "Start typing to narrow the list"; Step 4 uses "Select"; admonition includes current-assignee notification clause matching the assignee how-tos.

• http://localhost:8000/anomalies/how-tos/tags/remove-tags/ — Lead now includes API link; admonition includes current-assignee notification clause.

• http://localhost:8000/anomalies/how-tos/tags/bulk-edit/ — Step 11 mentions in-app notification for current assignees of each anomaly.

• Legacy redirects still resolve: /anomalies/status/, /anomalies/types/, /anomalies/fingerprints/, /anomalies/details/insights/, /anomalies/details/source-record/, and /anomalies/manage-anomalies/<page>/ should all land on their new deep-dive/ or how-tos/ URLs.

[ets]

Approving. No greptile score on this one, so I reviewed manually: internal links across all 29 changed files resolve, all mkdocs.yml nav entries and the ~350 redirect_map targets resolve to existing files, image references resolve, and include-markdown/code-fence/admonition syntax is well-formed. The only dangling image references are intentionally inside HTML comment blocks (TODO placeholders for a follow-up branch), so they're inert. Looks good.

---

Generated by Claude Code

[RafaelOsiro]

@greptileai

[greptile-apps]

Greptile Summary

This PR restructures the Anomalies documentation into Deep Dive and How-tos hubs and introduces end-to-end documentation for the new Assignees feature, including a deep-dive, three how-tos (Add / Remove / Bulk-Assign), an Anomalies API reference, and a new FAQ. All legacy URL paths are covered by redirects in mkdocs.yml.

• New Assignees content (deep-dive/assignees.md, how-tos/assignee/*) documents field behavior, inheritance from originating checks, permissions, notification rules, history tracking, and the Owner/Default Assignee/Assignees concept comparison. The bulk-assign and remove how-tos correctly describe the replace-semantics and notification behavior.
• Anomalies API reference (api.md) is comprehensive and resolves the previously flagged ambiguity about archived-anomaly restore by explicitly stating that PUT with "status": "Acknowledged" returns an archived anomaly to Acknowledged (not Active).
• "Viewer role" terminology in deep-dive/assignees.md (lines 7 and 29) and how-tos/assignee/add-assignee.md (Step 3 in both tabs) uses "Viewer role" instead of "Viewer team permission" — inconsistent with every other page in this same PR and factually incorrect in the Qualytics permission model where Viewer is a team permission, not a platform role.

Confidence Score: 4/5

Safe to merge with minor fixes — three instances of incorrect permission terminology in the new Assignees deep-dive and add-assignee how-to should be corrected before the pages go live to avoid confusing administrators.

The new Assignees documentation uses "Viewer role" in deep-dive/assignees.md lines 7 and 29, and in both Step 3 variants of how-tos/assignee/add-assignee.md. In Qualytics, Viewer is a team permission — platform roles are Member, Manager, and Admin. Every other page in this same PR (api.md, bulk-assign.md, faq.md) correctly says "Viewer team permission." An admin who reads only the assignees deep-dive or add-assignee how-to could look for a non-existent "Viewer" platform role when configuring datastore access.

docs/anomalies/deep-dive/assignees.md (lines 7, 29) and docs/anomalies/how-tos/assignee/add-assignee.md (Step 3 in both tabs)

Important Files Changed

Filename	Overview
docs/anomalies/deep-dive/assignees.md	New deep-dive for Assignees field — content is thorough (field behavior, inheritance, permissions table, notifications, history, concept comparison table, filtering) but uses "Viewer role" instead of "Viewer team permission" in two places, inconsistent with the rest of the PR.
docs/anomalies/how-tos/assignee/add-assignee.md	New add-assignee how-to with two-tab layout — same "Viewer role" terminology error appears in both Step 3 variants; the rest of the content and cross-links are correct.
docs/anomalies/how-tos/assignee/remove-assignee.md	New remove-assignee how-to — two-tab layout, correct X-button labeling, self-unassignment note, and notification callout all accurate.
docs/anomalies/how-tos/assignee/bulk-assign.md	New bulk-assign how-to — uses "Viewer team permission" correctly, replace-semantics warning is present, in-modal overwrite notice documented in Step 6.
docs/anomalies/api.md	New Anomalies API reference — schema, list/retrieve, update (single + bulk), assignee management subsection, archive/delete, history, source records, and ticket endpoints all documented with consistent "Author team permission" terminology. The status field note now explicitly documents archived→Acknowledged restore behavior, addressing the previously flagged ambiguity.
docs/anomalies/faq.md	New FAQ — Active↔Acknowledged reversibility answer is correct and consistent with api.md's updated restore description; Assignees section is comprehensive; "Viewer team permission" used correctly throughout.
docs/explore/anomalies.md	Assigned subtab and Assignees filter documented; pre-existing warning at line 100 ("once acknowledged, never reverts to active") still contradicts faq.md — flagged in a prior review round, not newly introduced by this PR.
mkdocs.yml	Nav restructured into Deep Dive / How-tos hubs; legacy redirects added for every moved page including anomalies/types.md, anomalies/status.md, anomalies/fingerprints.md, and all manage-anomalies/* paths.
docs/anomalies/how-tos/filter-and-sort.md	Restructured into Sort/Filter H2s; filter table row 8 adds Assignees filter; Filter-by-Assignee and Assigned-subtab how-to sections correctly left in an HTML comment pending screenshots.
docs/anomalies/deep-dive/description.md	New description deep-dive — uses "Editor team permission" consistently; AI-suggested description and masked fields sections look accurate.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Anomaly Created by Scan] --> B{Check has Default\nAnomaly Assignee?}
    B -- Yes --> C[Auto-assign user\nat creation — silent]
    B -- No --> D[No assignees]
    C --> E[Anomaly: Open / Active]
    D --> E

    E --> F{Author edits\nassignees / tags /\ndescription / status}
    F --> G[Platform notifies\ncurrent assignees\nexcept the editor]

    E --> H[Bulk-Assign via\nBulk Edit modal]
    H -- Replaces existing set --> E

    E --> I[Archive via\nDELETE endpoint]
    I --> J[Archived — read-only\nAssignees locked]

    J --> K[Restore via PUT\nstatus: Acknowledged]
    K --> L[Open / Acknowledged\nAssignees editable again]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Anomaly Created by Scan] --> B{Check has Default\nAnomaly Assignee?}
    B -- Yes --> C[Auto-assign user\nat creation — silent]
    B -- No --> D[No assignees]
    C --> E[Anomaly: Open / Active]
    D --> E

    E --> F{Author edits\nassignees / tags /\ndescription / status}
    F --> G[Platform notifies\ncurrent assignees\nexcept the editor]

    E --> H[Bulk-Assign via\nBulk Edit modal]
    H -- Replaces existing set --> E

    E --> I[Archive via\nDELETE endpoint]
    I --> J[Archived — read-only\nAssignees locked]

    J --> K[Restore via PUT\nstatus: Acknowledged]
    K --> L[Open / Acknowledged\nAssignees editable again]

Loading

_{Reviews (2): Last reviewed commit: "docs(anomalies): apply Greptile review f..." | Re-trigger Greptile}

[RafaelOsiro]

@greptileai review