QUA-1806: Add Filter Presets and Filter and Sort documentation

[RafaelOsiro]

Overview

Documents the Filter Presets feature (governance and ownership delivered in QUA-1806) and extracts the Filter and Sort filter-bar section from insights.md into a dedicated subtree under Filtering Controls. Also adds Report Date and Timeframe documentation to the Insights page.

Key Changes

• Filter Presets subtree: new 10-page set covering Getting Started, Deep Dive (Introduction, How It Works, Permissions), 4 How-tos (create, apply, update, delete), API, and FAQ.
• Filter and Sort subtree: new 10-page set covering the Explore filter bar (Source Datastores + Tags) with Getting Started, Deep Dive, 4 How-tos (add/remove datastore/tag filters), API, and FAQ.
• mkdocs nav: new Filtering Controls section under Explore, grouping Filter and Sort + Filter Presets.
• Insights: extracted the old "Filtering Controls" section from insights.md (now covered by the dedicated Filter and Sort pages) and added a new "Report Date and Timeframe" section documenting the Insights-specific controls.
• User Roles: added Filter and Sort and Filter Presets permission rows to admin, manager, member, and the overview matrix.
• Asset cleanup: removed two orphan insights screenshots (filter-3-light.png, fuzzy-insights.png) and the unused docs/explore/image.png.

Pages to Test

• http://localhost:8000/explore/filtering-controls/filter-presets/getting-started/
• http://localhost:8000/explore/filtering-controls/filter-presets/deep-dive/introduction/
• http://localhost:8000/explore/filtering-controls/filter-presets/deep-dive/how-it-works/
• http://localhost:8000/explore/filtering-controls/filter-presets/deep-dive/permissions/
• http://localhost:8000/explore/filtering-controls/filter-presets/how-tos/create/
• http://localhost:8000/explore/filtering-controls/filter-presets/how-tos/apply/
• http://localhost:8000/explore/filtering-controls/filter-presets/how-tos/update/
• http://localhost:8000/explore/filtering-controls/filter-presets/how-tos/delete/
• http://localhost:8000/explore/filtering-controls/filter-presets/api/
• http://localhost:8000/explore/filtering-controls/filter-presets/faq/
• http://localhost:8000/explore/filtering-controls/filter-and-sort/getting-started/
• http://localhost:8000/explore/filtering-controls/filter-and-sort/deep-dive/introduction/
• http://localhost:8000/explore/filtering-controls/filter-and-sort/deep-dive/how-it-works/
• http://localhost:8000/explore/filtering-controls/filter-and-sort/deep-dive/permissions/
• http://localhost:8000/explore/filtering-controls/filter-and-sort/how-tos/add-datastore-filter/
• http://localhost:8000/explore/filtering-controls/filter-and-sort/how-tos/remove-datastore-filter/
• http://localhost:8000/explore/filtering-controls/filter-and-sort/how-tos/add-tags-filter/
• http://localhost:8000/explore/filtering-controls/filter-and-sort/how-tos/remove-tags-filter/
• http://localhost:8000/explore/filtering-controls/filter-and-sort/api/
• http://localhost:8000/explore/filtering-controls/filter-and-sort/faq/
• http://localhost:8000/explore/insights/
• http://localhost:8000/settings/security/users/roles/admin/
• http://localhost:8000/settings/security/users/roles/manager/
• http://localhost:8000/settings/security/users/roles/member/
• http://localhost:8000/settings/security/users/roles/overview/

[greptile-apps]

Greptile Summary

This PR adds two new documentation subtrees under Explore — Filter and Sort (10 pages covering the filter bar's Source Datastores and Tags controls) and Filter Presets (10 pages covering the Saved Filters dropdown) — wires them into the mkdocs nav, updates the Insights page to focus on Report Date and Timeframe only, and adds Filter and Sort / Filter Presets permission rows to all four role pages.

• The new Filter and Sort and Filter Presets subtrees follow a consistent Getting Started → Deep Dive → How-tos → API → FAQ structure; cross-links between the two subtrees and back to the role pages are all correct, and image paths match the newly added asset directories.
• The Insights page correctly removes the old "Filtering Controls" section (including the fuzzy-search include and its screenshots) and replaces it with a focused "Report Date and Timeframe" table; deleted asset files (filter-3-light.png, fuzzy-insights.png, image.png) have no remaining references in the updated docs.
• The role pages (admin, manager, member, overview) all receive matching Filter and Sort and Filter Presets rows, and the permission values are internally consistent across every file — with one small gap: the "Apply a filter preset" row present in the dedicated permissions page is missing from the overview matrix.

Confidence Score: 4/5

Safe to merge; all changes are documentation-only with no runtime impact.

The documentation is thorough and well-structured, cross-links are correct, deleted asset references are fully cleaned up, and permissions are consistent across the role pages. The only two findings are minor: a missing Apply a filter preset row in the overview matrix and API doc links that point to the demo instance rather than a placeholder URL.

docs/settings/security/users/roles/overview.md (missing Apply row) and both api.md files (hardcoded demo URL).

Important Files Changed

Filename	Overview
mkdocs.yml	Adds a new Filtering Controls nav section under Explore with 10-page subtrees for Filter and Sort and Filter Presets; file paths and nesting all look correct.
docs/explore/insights.md	Replaces old Filtering Controls section with a focused Report Date and Timeframe section; screenshot references updated and orphan images deleted.
docs/explore/filtering-controls/filter-presets/api.md	New API reference covering List, Get, Create, Update, Delete, and Insights endpoints; permission levels and error codes are internally consistent. Hardcodes the demo instance URL for the full API docs link.
docs/explore/filtering-controls/filter-presets/deep-dive/permissions.md	New permissions page with a 4-row matrix; content matches individual role files. Apply a filter preset row is present here but absent from overview.md.
docs/settings/security/users/roles/overview.md	Adds Filter and Sort and Filter Presets rows to the overview permission matrix; permissions align with role pages, but the Apply a filter preset row is missing.
docs/settings/security/users/roles/admin.md	Adds Filter and Sort and Filter Presets capability rows for admin; consistent with overview and permissions pages.
docs/settings/security/users/roles/manager.md	Adds Filter and Sort and Filter Presets rows for manager; consistent with overview and permissions pages.
docs/settings/security/users/roles/member.md	Adds Filter and Sort and Filter Presets rows for member; consistent with overview and permissions pages.
docs/explore/filtering-controls/filter-presets/how-tos/update.md	New how-to covering name/description edits and filter-selection updates; clear two-subsection structure with distinct screenshots for each flow.
docs/explore/filtering-controls/filter-and-sort/api.md	New API reference listing shared query parameters with AND/OR combination logic documented; correct and internally consistent.
docs/explore/filtering-controls/filter-presets/deep-dive/introduction.md	Detailed introduction covering the Saved Filters dropdown, URL sharing, creator/last-editor display, and real-world examples; well-structured and thorough.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Explore] --> B[Filtering Controls]
    B --> C[Filter and Sort]
    B --> D[Filter Presets]
    C --> C1[Getting Started]
    C --> C2[Deep Dive]
    C --> C3[How-tos]
    C --> C4[API]
    C --> C5[FAQ]
    C2 --> C2a[Introduction]
    C2 --> C2b[How It Works]
    C2 --> C2c[Permissions]
    C3 --> C3a[Add Datastore Filter]
    C3 --> C3b[Remove Datastore Filter]
    C3 --> C3c[Add Tags Filter]
    C3 --> C3d[Remove Tags Filter]
    D --> D1[Getting Started]
    D --> D2[Deep Dive]
    D --> D3[How-tos]
    D --> D4[API]
    D --> D5[FAQ]
    D2 --> D2a[Introduction]
    D2 --> D2b[How It Works]
    D2 --> D2c[Permissions]
    D3 --> D3a[Create]
    D3 --> D3b[Apply]
    D3 --> D3c[Update]
    D3 --> D3d[Delete]
    A --> E[Insights]
    E --> E1[Report Date and Timeframe - NEW]
    F[User Roles] --> F1[Admin]
    F --> F2[Manager]
    F --> F3[Member]
    F --> F4[Overview]
    F1 & F2 & F3 & F4 --> G[Filter and Sort + Filter Presets rows added]

Loading

_{Reviews (1): Last reviewed commit: "docs(insights): add Report Date and Time..." | Re-trigger Greptile}

[greptile-apps]

The dedicated Filter Presets permissions page includes an "Apply a filter preset" row (all three roles: Allowed), but this row is absent from the overview matrix. Readers using this page as the authoritative reference won't see that applying a preset is open to everyone, which could create the impression that only creation/edit/delete are governed here.

Suggested change

	| **Filter Presets** | | | |
	| Create a filter preset | :material-check-circle:{ title="Allowed" } | :material-check-circle:{ title="Allowed" } | :material-check-circle:{ title="Allowed" } |
	| Edit or delete a filter preset you created | :material-check-circle:{ title="Allowed" } | :material-check-circle:{ title="Allowed" } | :material-check-circle:{ title="Allowed" } |
	| Edit or delete a filter preset created by another user | :material-close-circle-outline:{ title="Not allowed" } | :material-check-circle:{ title="Allowed" } | :material-check-circle:{ title="Allowed" } |
	| **Filter Presets** | | | |
	| Create a filter preset | :material-check-circle:{ title="Allowed" } | :material-check-circle:{ title="Allowed" } | :material-check-circle:{ title="Allowed" } |
	| Apply a filter preset | :material-check-circle:{ title="Allowed" } | :material-check-circle:{ title="Allowed" } | :material-check-circle:{ title="Allowed" } |
	| Edit or delete a filter preset you created | :material-check-circle:{ title="Allowed" } | :material-check-circle:{ title="Allowed" } | :material-check-circle:{ title="Allowed" } |
	| Edit or delete a filter preset created by another user | :material-close-circle-outline:{ title="Not allowed" } | :material-check-circle:{ title="Allowed" } | :material-check-circle:{ title="Allowed" } |

[greptile-apps]

Hardcoded demo instance URL in API docs

Both filter-presets/api.md and filter-and-sort/api.md link to https://demo.qualytics.io/api/docs as the full API documentation reference. Users on production or self-hosted instances will land on the demo environment rather than their own, which may show a different API version or require credentials they don't have. Consider using a placeholder like https://your-instance.qualytics.io/api/docs or a documentation-site variable so that each deployment resolves to the correct base URL.