Regenerate permissions documentation from backend source

[nrichers]

Pull Request Description

What and why?

[sc-5927] Overhaul of permissions documentation to match the actual backend implementation.

Before: Hardcoded permissions tables that were outdated and incomplete:

• Missing 18 resources (Attestation, Analytics, Inventory Schema, Artifact Schema, etc.)
• Missing permissions (workflow execution, delete comments, manage attachments, etc.)
• Incorrect role columns for model-scoped permissions

After: Auto-generated documentation from backend source files:

• Adds scripts/generate_permissions_docs.py to generate permissions from:
  • backend/src/backend/templates/platform_resources/data.json (resources/actions)
  • backend/src/backend/templates/platform_resources/org_initials.json (role permissions)
• Two-level permission system clearly documented:
  • Organization-level permissions (Customer Admin, Developer, Validator)
  • Model-level permissions (Model Owner, Model Developer, Model Validator, Basic User)
• All 23 organization-level resources with correct permissions
• All 5 model-level resources with correct role assignments
• Role descriptions for all roles
• UI terminology mapping applied (Finding → Artifact)

How to test

1. Check the live preview (link will be available once preview builds)
2. Verify all permission tables render correctly
3. Compare with backend data.json and org_initials.json to confirm accuracy
4. Run the script locally: python scripts/generate_permissions_docs.py

What needs special review?

• Verify the permission mappings are accurate by comparing with the backend source files
• Confirm the UI terminology mapping (Finding → Artifact) is correctly applied throughout
• Check that model-level permissions display the correct roles

Dependencies, breaking changes, and deployment notes

• None. This is documentation-only.
• The Python script reads from the backend repo (expected at ../backend/) — CI should clone the backend repo if we want to regenerate during build.

Release notes

Updated permissions documentation to accurately reflect the platform's two-level permission system. The documentation now includes all available permissions for both organization-level and model-level roles, generated directly from the backend source to ensure accuracy.

Checklist

• What and why
• How to test
• What needs special review
• Dependencies, breaking changes, and deployment notes
• Labels applied
• PR linked to Shortcut
• Unit tests added (Backend) — N/A (documentation only)
• Tested locally
• Documentation updated (if required)
• Environment variable additions/changes documented (if required) — N/A

[github-actions]

Pull requests must include at least one of the required labels: internal (no release notes required), highlight, enhancement, bug, deprecation, documentation. Except for internal, pull requests must also include a description in the release notes section.

[github-actions]

Pull requests must include at least one of the required labels: internal (no release notes required), highlight, enhancement, bug, deprecation, documentation. Except for internal, pull requests must also include a description in the release notes section.

[github-actions]

Pull requests must include at least one of the required labels: internal (no release notes required), highlight, enhancement, bug, deprecation, documentation. Except for internal, pull requests must also include a description in the release notes section.

[github-actions]

Pull requests must include at least one of the required labels: internal (no release notes required), highlight, enhancement, bug, deprecation, documentation. Except for internal, pull requests must also include a description in the release notes section.

[github-actions]

Pull requests must include at least one of the required labels: internal (no release notes required), highlight, enhancement, bug, deprecation, documentation. Except for internal, pull requests must also include a description in the release notes section.

[github-actions]

PR Summary

This PR introduces a new script (scripts/generate_permissions_docs.py) that auto-generates permissions documentation from backend source JSON files. The script reads resource and permission definitions from two files in the backend repository and outputs updated Quarto markdown files (e.g., site/guide/configuration/_permissions-generated.qmd). In addition, the README.md and site documentation files have been updated to include instructions on how to run the permissions documentation generation script. The changes ensure that when permission definitions in the backend are updated, developers can easily regenerate the documentation to keep it in sync with the backend configuration.

Key functional changes:

• A new Python script parses JSON data for resources, actions, and role permissions and generates comprehensive markdown tables.
• The script differentiates between organization-level and model-level permissions based on resource attributes.
• The README.md now includes a new section outlining the prerequisites and steps required to regenerate permissions documentation.
• The manage-permissions.qmd file has been updated to include the auto-generated permissions content instead of maintaining manually defined tables.

These enhancements automate the update process for permissions documentation, reduce the risk of discrepancies between code and documentation, and improve maintainability across the project.

Test Suggestions

• Run the generate_permissions_docs.py script in an environment with a sample backend repository structure to verify that the output file (_permissions-generated.qmd) is generated correctly.
• Test the script with missing or malformed JSON files to ensure it fails gracefully or produces appropriate error messages.
• Validate that the generated markdown tables correctly reflect permissions for both organization-level and model-level roles.
• Check that README instructions and inlined documentation are accurate and clearly guide the user on how to run the permissions generation script.

[claude]

Code Review

Found 1 issue:

Python 3.9 Compatibility Issue

Location: scripts/generate_permissions_docs.py:41

The function format_action_name uses the str | None type annotation syntax (PEP 604), which is only supported at runtime starting with Python 3.10. However, the README added in this PR specifies Python 3.9+ as the requirement.

On Python 3.9, importing this module will fail with:

TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'

Fix: Either:

1. Change the type annotation to Optional[str] (from typing) to support Python 3.9:

   from typing import Any, Optional
   
   def format_action_name(action_id: str, action_name: Optional[str] = None) -> str:
   

2. Or update the README requirement to Python 3.10+

Note: Even though format_action_name is never called (appears to be unused code), the annotation is still evaluated at module load time, causing the script to fail on Python 3.9.

[github-actions]

Validate docs site

✓ INFO: A live preview of the docs site is available — Open the preview

[github-actions]

Lighthouse check results

⚠️ WARN: Average accessibility score is 0.87 (required: >0.9) — Check the workflow run

Show Lighthouse scores

Folder depth level checked: 0

Commit SHA: 33e2c62

Modify the workflow to check a different depth:

• 0: Top-level navigation only — /index.html, /guide/guides.html, ...
• 1: All first-level subdirectories — /guide/.html, /developer/.html, ...
• 2: All second-level subdirectories — /guide/attestation/*.html, ...

Page	Accessibility	Performance	Best Practices	SEO
/developer/validmind-library.html	0.85	0.67	1.00	0.82
/get-started/get-started.html	0.85	0.70	1.00	0.73
/guide/guides.html	0.85	0.68	1.00	0.82
/index.html	0.93	0.62	1.00	0.82
/releases/all-releases.html	0.86	0.69	1.00	0.73
/support/support.html	0.91	0.67	1.00	0.82
/training/training.html	0.85	0.60	0.96	0.73

[github-actions]

Lighthouse check results

⚠️ WARN: Average accessibility score is 0.87 (required: >0.9) — Check the workflow run

Show Lighthouse scores

Folder depth level checked: 0

Commit SHA: 3d1faa3

Modify the workflow to check a different depth:

• 0: Top-level navigation only — /index.html, /guide/guides.html, ...
• 1: All first-level subdirectories — /guide/.html, /developer/.html, ...
• 2: All second-level subdirectories — /guide/attestation/*.html, ...

Page	Accessibility	Performance	Best Practices	SEO
/developer/validmind-library.html	0.85	0.61	1.00	0.82
/get-started/get-started.html	0.85	0.70	1.00	0.73
/guide/guides.html	0.85	0.69	1.00	0.82
/index.html	0.93	0.66	1.00	0.82
/releases/all-releases.html	0.86	0.72	1.00	0.73
/support/support.html	0.91	0.65	1.00	0.82
/training/training.html	0.85	0.69	0.96	0.73