QUA-1806: Platform Audit documentation

[RafaelOsiro]

Overview

This PR adds the full Platform Audit documentation under settings/audit/, restructures the Settings overview as an H2-per-section hub, updates the user-role permission docs to reflect Audit and Defaults tab access, and consolidates writing conventions in CLAUDE.md (with internal references moved to shared memory).

Key Changes

• Platform Audit documentation: new 10-page sub-tree at docs/settings/audit/ covering Getting Started, Deep Dive (Introduction, How It Works, Permissions, Best Practices), How-tos (Summary Section, Filter Activity, Export Activity), API, and FAQ.
• Settings overview: docs/settings/overview.md restructured as an H2-per-section hub with 137 cards in mkdocs.yml nav order. H1 updated to "Settings Overview" with :material-book-alphabet: brick icon. Card icons follow the verified-only rule (mirror the sub-overview).
• User role permissions: admin.md / manager.md / member.md / overview.md updated to include Audit (Admin-only at API and UI) and Defaults (Admin-only via UI tab visibility). Tab lists reordered to match the frontend SettingsTabs order, plus 7 pre-existing em-dashes swept across the four files.
• CLAUDE.md: consolidates writing-style conventions (Page Structure with the H2-per-subsection hub layout, Tables, Cards, Workflow) and sanitizes internal references. Specific private-repo names, internal symbol patterns, and architecture component names now live in shared memory (the userguide repo is public on GitHub).
• Chart legend variable: added --q-secondary: #86AA5B to docs/stylesheets/extra.css (light and dark modes) so the audit Summary Section legend renders the User vs Automated colors matching the frontend chart.
• Navigation: mkdocs.yml gets the Audit sub-tree entries under Settings.
• Greptile review feedback applied: replaced the hardcoded demo.qualytics.io URL in the audit API tip box with the your-instance.qualytics.io placeholder; reworded the adoption-tracking bullet and the "Did this user log in yesterday?" timeframe example to "users have taken actions" / "Did this user take any actions yesterday?" since the audit log is state-change-only (logins are not recorded); clarified the FAQ schema-renames entry so action_count is correctly shown as a sub-field of top_actor rather than a renamed top-level field.

Pages to Test

• http://localhost:8000/settings/overview/ — H1 with brick :material-book-alphabet: + "Settings Overview"; six H2 sections (Connections, Integrations, Security, Access Tokens, Audit, Status) separated by HR dividers; 137 cards in mkdocs.yml nav order; Audit Deep Dive cards qualified (Audit Introduction, How the Audit Page Works, Audit Permissions, Audit Best Practices); no "Hub page", "under the hood", "Synthetic users", "Re-fetch", or "graceful shutdown signal" wording.
• http://localhost:8000/settings/audit/getting-started/ — H1 with brick :material-book-open-page-variant:; !!! info "Permissions" block (Admin-only); three H2 sections (Deep Dive / How-tos / Reference) separated by HR; card icons mirror destination H1s.
• http://localhost:8000/settings/audit/deep-dive/introduction/ — H1 with brick :material-book-open-variant:; !!! info "Existing data, new view" admonition; Next Steps grid at the bottom with 4 cards; adoption-tracking bullet says "users have taken actions" (no login claim); "Qualytics system account" wording.
• http://localhost:8000/settings/audit/deep-dive/how-it-works/ — H1 with brick :material-file-cog:; eight H2 sections; zero em-dashes; "internal users" terminology; empty-state line names every card behavior.
• http://localhost:8000/settings/audit/deep-dive/permissions/ — H1 with brick :material-shield-lock-outline:; sentence-case H2s; Admin-only permission matrix; "does not load the page" wording.
• http://localhost:8000/settings/audit/deep-dive/best-practices/ — Plain H1; "Schedule regular reviews" section; "Match the timeframe to the question" table has "Did this user take any actions yesterday?" (no login claim); parentheses replace em-dashes.
• http://localhost:8000/settings/audit/how-tos/summary-section/ — Plain H1; restructured as reference (no Step N: labels); chart legend table shows brick (User) and olive (Automated) colored squares — NOT both black.
• http://localhost:8000/settings/audit/how-tos/filter-activity/ — Plain H1; restructured as reference; H2 sections "Date and Timeframe" / "Filter menu" / "Clear filters"; "internal users" wording.
• http://localhost:8000/settings/audit/how-tos/export-activity/ — Plain H1; restructured as reference; "Unknown is written when the user account no longer exists" wording.
• http://localhost:8000/settings/audit/api/ — H1 with brick :material-api:; tip banner uses your-instance.qualytics.io/api/docs placeholder; "internal users" terminology; transaction.user schema says "null when the user account no longer exists".
• http://localhost:8000/settings/audit/faq/ — H1 with brick :material-help-circle-outline:; seven H2 categories; "Why is one row tinted?"; "Did the schema fields change names?" answer correctly identifies action_count as a sub-field of top_actor.
• http://localhost:8000/settings/security/users/roles/overview/ — Permission matrix has both Defaults and Audit tab rows (Member ❌ / Manager ❌ / Admin ✅).
• http://localhost:8000/settings/security/users/roles/admin/ — Settings UI row lists all 7 tabs in frontend order. Adds "View platform activity log (Audit)" → Allowed.
• http://localhost:8000/settings/security/users/roles/manager/ — Settings UI Allowed-tabs excludes Audit and Defaults. Two explicit Not-allowed rows.
• http://localhost:8000/settings/security/users/roles/member/ — Settings UI Not-allowed list includes Defaults alongside Integrations, Security, Audit, Status.
• Sidebar nav — Audit sub-tree appears under Settings with all 10 children.
• Light and dark modes — confirm brick H1 icons render correctly and the chart legend squares (brick + olive) are visually distinguishable in both color schemes.

[greptile-apps]

Greptile Summary

This PR adds a complete Platform Audit documentation section to the Qualytics user guide (docs/settings/audit/) covering Getting Started, Deep Dive, How-tos, API, and FAQ pages. It also restructures the Settings overview as an H2-per-section hub, updates user role permission tables to include the new Audit and Defaults tabs, adds a CSS custom property for the chart legend, and wires the new section into the nav.

• Ten new audit pages document every aspect of the Platform Audit page: timeframe mechanics, timezone handling, user/automated splits, permissions, export, API schemas, and FAQ answers, all using consistent terminology and cross-references.
• Role permission pages (admin.md, manager.md, member.md, overview.md) are updated to show Audit (Admin-only in both UI and API) and Defaults (Admin-only via tab visibility), with tab lists reordered to match the frontend SettingsTabs order.
• All three previously flagged review issues (hardcoded demo URL, login-event claim in adoption tracking, and action_count mis-categorized as a top-level field) are correctly resolved in this version.

Confidence Score: 5/5

Documentation-only PR with no runtime logic changes; all previously flagged content errors are resolved.

The change is entirely documentation and a single CSS variable addition. The three prior review findings (hardcoded demo URL, incorrect login-event claim in the adoption-tracking bullet, and action_count miscategorized as a top-level field in the FAQ migration note) are all correctly addressed. Content across all ten new audit pages is internally consistent — timeframe definitions, permission rules, and API schema descriptions agree. The role permission tables in admin.md, manager.md, member.md, and overview.md are mutually consistent with each other and with the new audit deep-dive permissions page.

No files require special attention.

Important Files Changed

Filename	Overview
docs/settings/audit/api.md	New API reference page; documents GET /api/activity and GET /api/activity/insights with query parameters, example requests, and response schemas. Uses your-instance.qualytics.io placeholder (previous hardcoded demo URL addressed). Schema correctly shows action_count as a sub-field of top_actor.
docs/settings/audit/deep-dive/introduction.md	New introduction page; adoption-tracking bullet correctly uses 'users have taken actions' (not 'logged in'), consistent with the audit log's state-change-only scope documented in faq.md and how-it-works.md.
docs/settings/audit/faq.md	New FAQ page; schema migration note correctly identifies action_count as a sub-field of top_actor rather than a renamed top-level field, resolving the previously flagged inconsistency with the API schema.
docs/settings/audit/deep-dive/best-practices.md	New best-practices page; timeframe table updated to 'Did this user take any actions yesterday?' (previously flagged login question resolved). Parentheses replace em-dashes throughout.
docs/settings/audit/getting-started.md	New hub page organizing Deep Dive, How-tos, and Reference card grids. Card icons correctly mirror destination page H1 icons; Admin-only permissions admonition present.
docs/settings/security/users/roles/overview.md	Adds Defaults tab and Audit tab rows (both Admin-only) and a View platform activity log row to the Settings section of the permission matrix. Em-dashes replaced by colons in prose descriptions.
docs/settings/security/users/roles/admin.md	Settings UI tab list updated to include Defaults and Audit; new row added for 'View platform activity log (Audit)' as Allowed. Tab order matches stated frontend SettingsTabs order.
docs/settings/security/users/roles/manager.md	Settings UI rows updated: Allowed tabs (Connections, Integrations, Security, Tokens, Status) listed separately from two new Not Allowed rows (Defaults and Audit). Consistent with overview.md permission matrix.
docs/settings/security/users/roles/member.md	Not Allowed tab list extended to include Integrations, Defaults, Security, Audit, Status; new row added for 'View platform activity log (Audit)' as Not Allowed. Consistent with the overview matrix.
docs/stylesheets/extra.css	Adds --q-secondary: #86AA5B to both default and slate color scheme blocks; used by the chart legend color square in summary-section.md to distinguish Automated activity from User activity.
mkdocs.yml	Adds the Audit sub-tree (10 entries) under Settings between Access Tokens and Status, matching the documented tab order and the pages-to-test checklist in the PR description.
docs/settings/audit/deep-dive/how-it-works.md	New technical deep-dive page; documents Report Date + Timeframe mechanics, day grouping, timezone handling, chart bucket widths, user/automated split, masking audit overlay, and all empty/loading states.
docs/settings/audit/deep-dive/permissions.md	New permissions page; Admin-only permission matrix covers UI access, API access, and the 'does not load the page' scenario for non-Admin direct URL navigation.
docs/settings/audit/how-tos/summary-section.md	New how-to reference page; chart legend table uses var(--q-primary) and var(--q-secondary) CSS variables for colored squares, which are now defined in extra.css for both color schemes.
docs/settings/audit/how-tos/filter-activity.md	New how-to reference page; documents Date/Timeframe, Filter menu (Users, Actions, Hide Qualytics), and Clear filters, with screenshots referenced by relative asset paths.
docs/settings/audit/how-tos/export-activity.md	New how-to reference page; CSV column table uses 'Unknown is written when the user account no longer exists', consistent with the api.md null user description.
docs/settings/overview.md	Major restructure from flat list to H2-per-section hub with card grids for Connections, Integrations, Security, Access Tokens, Audit, and Status. New Audit section cards match the getting-started.md card structure.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    GS[Getting Started<br/>getting-started.md]

    GS --> DD[Deep Dive]
    GS --> HT[How-tos]
    GS --> REF[Reference]

    DD --> INTRO[Introduction<br/>introduction.md]
    DD --> HIW[How It Works<br/>how-it-works.md]
    DD --> PERM[Permissions<br/>permissions.md]
    DD --> BP[Best Practices<br/>best-practices.md]

    HT --> SS[Summary Section<br/>summary-section.md]
    HT --> FA[Filter Activity<br/>filter-activity.md]
    HT --> EA[Export Activity<br/>export-activity.md]

    REF --> API[API<br/>api.md]
    REF --> FAQ[FAQ<br/>faq.md]

    API --> EP1["GET /api/activity<br/>(paginated log)"]
    API --> EP2["GET /api/activity/insights<br/>(summary cards + chart)"]

    PERM --> ROLES[User Roles Overview<br/>roles/overview.md]

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
    GS[Getting Started<br/>getting-started.md]

    GS --> DD[Deep Dive]
    GS --> HT[How-tos]
    GS --> REF[Reference]

    DD --> INTRO[Introduction<br/>introduction.md]
    DD --> HIW[How It Works<br/>how-it-works.md]
    DD --> PERM[Permissions<br/>permissions.md]
    DD --> BP[Best Practices<br/>best-practices.md]

    HT --> SS[Summary Section<br/>summary-section.md]
    HT --> FA[Filter Activity<br/>filter-activity.md]
    HT --> EA[Export Activity<br/>export-activity.md]

    REF --> API[API<br/>api.md]
    REF --> FAQ[FAQ<br/>faq.md]

    API --> EP1["GET /api/activity<br/>(paginated log)"]
    API --> EP2["GET /api/activity/insights<br/>(summary cards + chart)"]

    PERM --> ROLES[User Roles Overview<br/>roles/overview.md]

Loading

_{Reviews (3): Last reviewed commit: "docs(audit): fix login-claim in best-pra..." | Re-trigger Greptile}

[RafaelOsiro]

@greptileai review

[RafaelOsiro]

@greptileai review

[RafaelOsiro]

@greptileai review