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 (filter-bar reference: datastores, tags, and Insights-specific controls) and Filter Presets (save, apply, update, delete named filter combinations) — each with Getting Started, Deep Dive, How-tos, API, and FAQ pages. It also refactors insights.md to replace the old Filtering Controls section with a focused Report Date and Timeframe section, updates all four user-role pages with the new permission rows, and cleans up three orphaned asset files.

• 20 new markdown pages covering both features end-to-end, with step-by-step how-tos and full API reference.
• Permission matrix updates across admin.md, manager.md, member.md, and overview.md correctly reflect who can filter by all-workspace datastores and who can edit/delete presets they did not create.
• One internal inconsistency: how-it-works.md and faq.md both state that presets save only datastores + tags, while api.md documents a timeframe field on the preset resource (used by the Create, Update, and Get Insights endpoints). Readers comparing the two areas will get conflicting answers about what a preset stores.

Confidence Score: 4/5

Safe to merge after resolving the timeframe contradiction between the deep-dive and API pages.

The deep-dive how-it-works page and the FAQ both tell users that presets store only datastores and tags, while the API page in the same PR documents a timeframe field that is stored on the preset and read back by the Get Insights endpoint. Any user who reads both areas will get conflicting answers about what a preset saves. All other content — nav wiring, permission tables, how-tos, and the insights.md refactor — is clean and internally consistent.

docs/explore/filtering-controls/filter-presets/deep-dive/how-it-works.md and docs/explore/filtering-controls/filter-presets/faq.md need to align with the timeframe behavior documented in docs/explore/filtering-controls/filter-presets/api.md.

Important Files Changed

Filename	Overview
docs/explore/filtering-controls/filter-presets/deep-dive/how-it-works.md	New page documenting how filter presets work; "What a Preset Contains" table omits the timeframe field that the API page documents as a storable preset property, creating a contradiction with the FAQ.
docs/explore/filtering-controls/filter-presets/faq.md	New FAQ page; the answer stating presets save only "datastores + tags" conflicts with the api.md which documents a timeframe field on the preset resource.
docs/explore/filtering-controls/filter-presets/api.md	New API reference for filter presets; endpoints and schemas are well-documented; timeframe field documented in create/update/insights endpoints but not reflected in the deep-dive pages.
docs/explore/filtering-controls/filter-and-sort/api.md	New API reference for filter-bar query parameters; clean and concise.
docs/explore/filtering-controls/filter-presets/how-tos/create.md	New how-to for creating filter presets; covers both entry points (save-icon and dropdown link) with clear step-by-step instructions and screenshots.
docs/explore/filtering-controls/filter-presets/how-tos/update.md	New how-to covering name/description updates and inline filter selection updates; permissions correctly noted; reset and save icon behaviors clearly documented.
docs/explore/insights.md	Refactored to remove the old Filtering Controls section and add a new Report Date and Timeframe section; removed references to deleted screenshots; clean change.
docs/settings/security/users/roles/overview.md	Adds Filter and Sort and Filter Presets rows to the overview matrix; Apply a filter preset row is now present for all three roles; permissions are consistent with individual role pages.
docs/settings/security/users/roles/admin.md	Adds Filter and Sort and Filter Presets capability rows for admin; uses combined row for edit/delete — intentional simplification, logically equivalent to the two-row split in member/manager pages.
mkdocs.yml	Adds the new Filtering Controls nav subtree (Filter and Sort + Filter Presets) under Explore; all referenced markdown files exist in the PR; nav structure matches the documented page hierarchy.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Explore Page Filter Bar] --> B[Source Datastores Dropdown]
    A --> C[Tags Dropdown]
    A --> D[Report Date - Insights only]
    A --> E[Timeframe - Insights only]

    B --> F{Filters applied?}
    C --> F

    F -- Yes --> G[Save as new preset icon]
    F -- Always --> H[Saved Filters dropdown]

    G --> I[Add Filter Preset dialog]
    H --> I

    I --> J[Filter Preset stored - Name · Description · Datastores · Tags + timeframe via API]

    J --> K[Apply via Saved Filters dropdown]
    J --> L[Share via URL ?filter=id]
    J --> M[Update: rename / re-save filters]
    J --> N[Delete: permanent]

    K --> A
    L --> A

    subgraph Permissions
        O[Member: own presets only]
        P[Manager: any visible preset]
        Q[Admin: all workspace presets]
    end

    M --> Permissions
    N --> Permissions

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[Explore Page Filter Bar] --> B[Source Datastores Dropdown]
    A --> C[Tags Dropdown]
    A --> D[Report Date - Insights only]
    A --> E[Timeframe - Insights only]

    B --> F{Filters applied?}
    C --> F

    F -- Yes --> G[Save as new preset icon]
    F -- Always --> H[Saved Filters dropdown]

    G --> I[Add Filter Preset dialog]
    H --> I

    I --> J[Filter Preset stored - Name · Description · Datastores · Tags + timeframe via API]

    J --> K[Apply via Saved Filters dropdown]
    J --> L[Share via URL ?filter=id]
    J --> M[Update: rename / re-save filters]
    J --> N[Delete: permanent]

    K --> A
    L --> A

    subgraph Permissions
        O[Member: own presets only]
        P[Manager: any visible preset]
        Q[Admin: all workspace presets]
    end

    M --> Permissions
    N --> Permissions

Loading

_{Reviews (2): Last reviewed commit: "docs(filter-presets): add Apply row to r..." | Re-trigger Greptile}

[ets]

Approving — greptile-apps scored this 4/5.

---

Generated by Claude Code

[RafaelOsiro]

@greptileai review