ironcommit · Jun 17, 2026 · Jun 16, 2026
@@ -110,6 +110,10 @@ docs-deps: ## Install the Fern docs tooling (docs/fern node deps)
 docs: ## Start the Fern docs dev server (local preview, prints a localhost URL)
 	cd docs/fern && npm run dev
 
+.PHONY: docs-watch
+docs-watch: ## Start Fern docs dev plus a repo-level watcher for docs/** changes
+	cd docs/fern && npm run watch
+
 .PHONY: docs-check
 docs-check: ## Validate the Fern docs (fern check + validate-mdx + gated-link check)
 	cd docs/fern && npm run check

@@ -10,12 +10,15 @@ Run these from the repo root (they wrap `cd docs/fern && npm run …`):
 |---|---|
 | `make docs-deps` | Install docs tooling (first run on a machine) |
 | `make docs` | Local dev server (live preview) |
+| `make docs-watch` | Local dev server plus repo-level watcher for `docs/**` changes outside `docs/fern/` |
 | `make docs-check` | `fern check` + MDX validation + gated-link check (what CI runs) |
 | `make docs-broken-links` | Report broken links |
 | `make docs-fix-links` | Auto-delink references into gated pages |
 
 Local preview and the published site read the **same** `docs/fern/versions/latest.yml`, so what you see locally is what ships.
 
+Use `make docs` when you are only editing `docs/fern/` config. Use `make docs-watch` when you are editing page content elsewhere under `docs/`, since it restarts the Fern dev server when repo-level docs files change outside `docs/fern/`.
+
 ## Rules that bite if you miss them
 
 - **Navigation is the build.** Fern only builds pages listed in `docs/fern/versions/latest.yml`. A `.mdx` not in the nav is **not built** (404, not indexed) — that is how unready features are gated. Do **not** use `hidden: true` for gating (it still builds/serves the page).

@@ -38,7 +38,7 @@ Add users to workspaces, assign roles, manage members.
 Token-level scope model and two-layer authorization.
 
 </Card>
-<Card title="Permissions Reference" href="/documentation/reference/authorization/permissions-reference">
+<Card title="Permissions Reference" href="/documentation/access-control/authorization/permissions-reference">
 
 Complete list of all permissions with role assignments.
 

@@ -2,12 +2,12 @@
 title: "Permissions Reference"
 description: ""
 ---
-(permissions-reference)=
 
+{/* This page is generated from the auth configuration. Regenerate it with `uv run python services/core/auth/scripts/auth-tools.py generate-docs`. */}
 
-Complete reference of all permissions across the NeMo Platform APIs. Each permission controls access to a specific operation within an individual API. Permissions are assigned to users through [roles](roles-and-permissions.md).
+Complete reference of all permissions across the NeMo Platform APIs. Each permission controls access to a specific operation within an individual API. Permissions are assigned to users through [roles](/documentation/access-control/authorization/roles-and-permissions).
 
-For token-level access restrictions, see [API Scopes](api-scopes.md). For the RBAC model, see [Authorization Concepts](../concepts.md).
+For token-level access restrictions, see [API Scopes](/documentation/access-control/authorization/api-scopes). For the RBAC model, see [Authorization Concepts](/documentation/access-control/concepts).
 
 <Note>
 
@@ -18,79 +18,79 @@ PlatformAdmin is omitted — it bypasses permission checks entirely at the polic
 
 | Permission | Description | Viewer | Editor | Admin |
 |------------|-------------|:------:|:------:|:-----:|
-| `entities.(read \\| create \\| update \\| delete)` | Read, create, update, delete entities |  |  |  |
+| <code>entities.(read &#124; create &#124; update &#124; delete)</code> | Read, create, update, delete entities |  |  |  |
 
 ## Files API
 
 | Permission | Description | Viewer | Editor | Admin |
 |------------|-------------|:------:|:------:|:-----:|
-| `filesets.(read \\| list)` | Read, list files | ✓ | ✓ | ✓ |
-| `filesets.(create \\| update \\| delete)` | Create, update, delete files |  | ✓ | ✓ |
+| <code>filesets.(read &#124; list)</code> | Read, list files | ✓ | ✓ | ✓ |
+| <code>filesets.(create &#124; update &#124; delete)</code> | Create, update, delete files |  | ✓ | ✓ |
 
 ## Guardrails API
 
 | Permission | Description | Viewer | Editor | Admin |
 |------------|-------------|:------:|:------:|:-----:|
 | `guardrails.checks.exec` | Execute guardrail checks |  | ✓ | ✓ |
-| `guardrails.configs.(read \\| list)` | Read, list guardrails configs | ✓ | ✓ | ✓ |
-| `guardrails.configs.(create \\| update \\| delete)` | Create, update, delete guardrails configs |  | ✓ | ✓ |
+| <code>guardrails.configs.(read &#124; list)</code> | Read, list guardrails configs | ✓ | ✓ | ✓ |
+| <code>guardrails.configs.(create &#124; update &#124; delete)</code> | Create, update, delete guardrails configs |  | ✓ | ✓ |
 
 ## IAM API
 
 | Permission | Description | Viewer | Editor | Admin |
 |------------|-------------|:------:|:------:|:-----:|
-| `iam.(read \\| list \\| create \\| delete)` | Read, list, create, delete iam |  |  | ✓ |
+| <code>iam.(read &#124; list &#124; create &#124; delete)</code> | Read, list, create, delete iam |  |  | ✓ |
 | `iam.bundle.read` | Download OPA authorization bundle (external OPA / advanced ops) |  |  |  |
 
 ## Inference API
 
 | Permission | Description | Viewer | Editor | Admin |
 |------------|-------------|:------:|:------:|:-----:|
-| `inference.deployment-configs.(read \\| list)` | Read, list inference deployment-configs | ✓ | ✓ | ✓ |
-| `inference.deployment-configs.(create \\| delete)` | Create, delete inference deployment-configs |  | ✓ | ✓ |
-| `inference.deployments.(read \\| list)` | Read, list inference deployments | ✓ | ✓ | ✓ |
-| `inference.deployments.(create \\| update \\| delete)` | Create, update, delete inference deployments |  | ✓ | ✓ |
+| <code>inference.deployment-configs.(read &#124; list)</code> | Read, list inference deployment-configs | ✓ | ✓ | ✓ |
+| <code>inference.deployment-configs.(create &#124; delete)</code> | Create, delete inference deployment-configs |  | ✓ | ✓ |
+| <code>inference.deployments.(read &#124; list)</code> | Read, list inference deployments | ✓ | ✓ | ✓ |
+| <code>inference.deployments.(create &#124; update &#124; delete)</code> | Create, update, delete inference deployments |  | ✓ | ✓ |
 | `inference.gateway.model.exec` | Execute model gateway inference | ✓ | ✓ | ✓ |
 | `inference.gateway.openai.exec` | Execute OpenAI-compatible gateway inference | ✓ | ✓ | ✓ |
 | `inference.gateway.provider.exec` | Execute provider gateway inference | ✓ | ✓ | ✓ |
-| `inference.providers.(read \\| list)` | Read, list inference providers | ✓ | ✓ | ✓ |
-| `inference.providers.(create \\| update \\| delete)` | Create, update, delete inference providers |  | ✓ | ✓ |
-| `inference.virtual-models.(read \\| list)` | Read, list inference virtual-models | ✓ | ✓ | ✓ |
-| `inference.virtual-models.(create \\| update \\| delete)` | Create, update, delete inference virtual-models |  | ✓ | ✓ |
+| <code>inference.providers.(read &#124; list)</code> | Read, list inference providers | ✓ | ✓ | ✓ |
+| <code>inference.providers.(create &#124; update &#124; delete)</code> | Create, update, delete inference providers |  | ✓ | ✓ |
+| <code>inference.virtual-models.(read &#124; list)</code> | Read, list inference virtual-models | ✓ | ✓ | ✓ |
+| <code>inference.virtual-models.(create &#124; update &#124; delete)</code> | Create, update, delete inference virtual-models |  | ✓ | ✓ |
 
 ## Intake API
 
 | Permission | Description | Viewer | Editor | Admin |
 |------------|-------------|:------:|:------:|:-----:|
-| `intake.annotations.(read \\| list)` | Read, list intake annotations | ✓ | ✓ | ✓ |
-| `intake.annotations.(create \\| delete)` | Create, delete intake annotations |  | ✓ | ✓ |
-| `intake.evaluator-results.(read \\| list)` | Read, list intake evaluator-results | ✓ | ✓ | ✓ |
+| <code>intake.annotations.(read &#124; list)</code> | Read, list intake annotations | ✓ | ✓ | ✓ |
+| <code>intake.annotations.(create &#124; delete)</code> | Create, delete intake annotations |  | ✓ | ✓ |
+| <code>intake.evaluator-results.(read &#124; list)</code> | Read, list intake evaluator-results | ✓ | ✓ | ✓ |
 | `intake.evaluator-results.create` | Create intake evaluator results |  | ✓ | ✓ |
 | `intake.experiment-groups.read` | Read intake experiment groups | ✓ | ✓ | ✓ |
-| `intake.experiment-groups.(create \\| update \\| delete)` | Create, update, delete intake experiment-groups |  | ✓ | ✓ |
+| <code>intake.experiment-groups.(create &#124; update &#124; delete)</code> | Create, update, delete intake experiment-groups |  | ✓ | ✓ |
 | `intake.experiments.read` | Read intake experiments | ✓ | ✓ | ✓ |
-| `intake.experiments.(create \\| update \\| delete)` | Create, update, delete intake experiments |  | ✓ | ✓ |
+| <code>intake.experiments.(create &#124; update &#124; delete)</code> | Create, update, delete intake experiments |  | ✓ | ✓ |
 | `intake.ingest.create` | Ingest traces into intake |  | ✓ | ✓ |
-| `intake.spans.(read \\| list)` | Read, list intake spans | ✓ | ✓ | ✓ |
+| <code>intake.spans.(read &#124; list)</code> | Read, list intake spans | ✓ | ✓ | ✓ |
 | `intake.traces.read` | Read intake traces | ✓ | ✓ | ✓ |
 
 ## Jobs API
 
 | Permission | Description | Viewer | Editor | Admin |
 |------------|-------------|:------:|:------:|:-----:|
-| `jobs.(read \\| list)` | Read, list jobs | ✓ | ✓ | ✓ |
-| `jobs.(create \\| update \\| delete \\| cancel)` | Create, update, delete, cancel jobs |  | ✓ | ✓ |
+| <code>jobs.(read &#124; list)</code> | Read, list jobs | ✓ | ✓ | ✓ |
+| <code>jobs.(create &#124; update &#124; delete &#124; cancel)</code> | Create, update, delete, cancel jobs |  | ✓ | ✓ |
 
 ## Models API
 
 | Permission | Description | Viewer | Editor | Admin |
 |------------|-------------|:------:|:------:|:-----:|
-| `models.(read \\| list)` | Read, list models | ✓ | ✓ | ✓ |
-| `models.(create \\| update \\| delete)` | Create, update, delete models |  | ✓ | ✓ |
-| `models.adapters.(read \\| list)` | Read, list models adapters | ✓ | ✓ | ✓ |
-| `models.adapters.(create \\| update \\| delete)` | Create, update, delete models adapters |  | ✓ | ✓ |
+| <code>models.(read &#124; list)</code> | Read, list models | ✓ | ✓ | ✓ |
+| <code>models.(create &#124; update &#124; delete)</code> | Create, update, delete models |  | ✓ | ✓ |
+| <code>models.adapters.(read &#124; list)</code> | Read, list models adapters | ✓ | ✓ | ✓ |
+| <code>models.adapters.(create &#124; update &#124; delete)</code> | Create, update, delete models adapters |  | ✓ | ✓ |
 | `models.prompts.read` | Read model prompts | ✓ | ✓ | ✓ |
-| `models.prompts.(create \\| update \\| delete)` | Create, update, delete models prompts |  | ✓ | ✓ |
+| <code>models.prompts.(create &#124; update &#124; delete)</code> | Create, update, delete models prompts |  | ✓ | ✓ |
 | `models.prompts.list` | List model prompts |  |  |  |
 | `models.tool-call-plugin.set` | Whether this user can set tool_call_plugin on Models or Deployment Configs *(policy-enforced)* |  |  | ✓ |
 | `models.trust-remote-code.set` | Whether this user can set trust_remote_code on Models *(policy-enforced)* |  |  | ✓ |
@@ -105,35 +105,35 @@ PlatformAdmin is omitted — it bypasses permission checks entirely at the polic
 
 | Permission | Description | Viewer | Editor | Admin |
 |------------|-------------|:------:|:------:|:-----:|
-| `projects.(read \\| list)` | Read, list projects | ✓ | ✓ | ✓ |
-| `projects.(create \\| update \\| delete)` | Create, update, delete projects |  | ✓ | ✓ |
+| <code>projects.(read &#124; list)</code> | Read, list projects | ✓ | ✓ | ✓ |
+| <code>projects.(create &#124; update &#124; delete)</code> | Create, update, delete projects |  | ✓ | ✓ |
 
 ## Safe Synthesizer API
 
 | Permission | Description | Viewer | Editor | Admin |
 |------------|-------------|:------:|:------:|:-----:|
-| `safe-synthesizer.jobs.(read \\| list \\| create \\| delete \\| cancel)` | Read, list, create, delete, cancel safe synthesizer jobs |  |  |  |
+| <code>safe-synthesizer.jobs.(read &#124; list &#124; create &#124; delete &#124; cancel)</code> | Read, list, create, delete, cancel safe synthesizer jobs |  |  |  |
 
 ## Secrets API
 
 | Permission | Description | Viewer | Editor | Admin |
 |------------|-------------|:------:|:------:|:-----:|
-| `secrets.(read \\| list)` | Read, list secrets | ✓ | ✓ | ✓ |
-| `secrets.(create \\| update \\| delete)` | Create, update, delete secrets |  | ✓ | ✓ |
-| `secrets.(access \\| rotate)` | Access, rotate secrets |  |  |  |
+| <code>secrets.(read &#124; list)</code> | Read, list secrets | ✓ | ✓ | ✓ |
+| <code>secrets.(create &#124; update &#124; delete)</code> | Create, update, delete secrets |  | ✓ | ✓ |
+| <code>secrets.(access &#124; rotate)</code> | Access, rotate secrets |  |  |  |
 
 ## Workspaces API
 
 | Permission | Description | Viewer | Editor | Admin |
 |------------|-------------|:------:|:------:|:-----:|
-| `workspaces.(read \\| list)` | Read, list workspaces | ✓ | ✓ | ✓ |
-| `workspaces.(update \\| delete)` | Update, delete workspaces |  | ✓ | ✓ |
-| `workspaces.members.(list \\| create \\| update \\| delete)` | List, create, update, delete workspaces members |  |  | ✓ |
+| <code>workspaces.(read &#124; list)</code> | Read, list workspaces | ✓ | ✓ | ✓ |
+| <code>workspaces.(update &#124; delete)</code> | Update, delete workspaces |  | ✓ | ✓ |
+| <code>workspaces.members.(list &#124; create &#124; update &#124; delete)</code> | List, create, update, delete workspaces members |  |  | ✓ |
 | `workspaces.members.read` | Read workspace member details |  |  |  |
 
 ## Related
 
-- [Roles & Permissions](roles-and-permissions.md) — Role descriptions and hierarchy.
-- [API Scopes](api-scopes.md) — Token-level scope restrictions.
-- [Authorization Concepts](../concepts.md) — Workspaces, roles, bindings, and the RBAC model.
-- [Security Model](../security-model.md) — Trust boundaries and authorization layers.
+- [Roles & Permissions](/documentation/access-control/authorization/roles-and-permissions) — Role descriptions and hierarchy.
+- [API Scopes](/documentation/access-control/authorization/api-scopes) — Token-level scope restrictions.
+- [Authorization Concepts](/documentation/access-control/concepts) — Workspaces, roles, bindings, and the RBAC model.
+- [Security Model](/documentation/access-control/security-model) — Trust boundaries and authorization layers.
@@ -41,19 +41,32 @@ NeMo Platform provides four predefined roles, each designed for a specific user
 
 Each role includes all permissions of the roles below it:
 
-```text
-PlatformAdmin
- ▲
- Admin (+manage_members, +change_visibility)
- ▲
- Editor (+create, +update, +delete, +cancel)
- ▲
- Viewer (list, read, inference)
+```mermaid
+flowchart BT
+    Viewer["Viewer
++list
++read
++inference"]
+    Editor["Editor
++create
++update
++delete
++cancel"]
+    Admin["Admin
++manage members
++change visibility"]
+    PlatformAdmin["PlatformAdmin
+all workspaces
+all operations"]
+
+    Viewer --> Editor
+    Editor --> Admin
+    Admin --> PlatformAdmin
 ```
 
 ## Permission Matrix
 
-Rows are operations; columns are roles. A checkmark indicates the role has permission.
+Rows are operations; columns are roles. Read the hierarchy above first: each role inherits everything below it, and the tables call out the points where additional privileges appear.
 
 ### Workspace Operations
 

@@ -33,11 +33,16 @@ Workspaces can have different access levels based on role bindings:
 
 Each principal can have different roles in different workspaces:
 
-```text
-alice@company.com:
- - Admin in workspace "team-ml"
- - Editor in workspace "shared-datasets"
- - Viewer in workspace "prod-models"
+```mermaid
+flowchart TB
+    Alice["alice@company.com"]
+    TeamML["team-ml<br/>Admin"]
+    Shared["shared-datasets<br/>Editor"]
+    Prod["prod-models<br/>Viewer"]
+
+    Alice --> TeamML
+    Alice --> Shared
+    Alice --> Prod
 ```
 
 ### Wildcard Principal
@@ -46,10 +51,14 @@ The special principal `*` (asterisk) represents **all authenticated users**. Gra
 
 This is the mechanism for creating shared workspaces:
 
-```text
-Workspace: "shared-datasets"
-├── Role Binding: principal="*", role="Viewer" # Everyone can read
-└── Role Binding: principal="alice@company.com", role="Admin" # Alice manages
+```mermaid
+flowchart TB
+    Workspace["Workspace: shared-datasets"]
+    Everyone["Role Binding<br/>principal=*<br/>role=Viewer"]
+    AliceAdmin["Role Binding<br/>principal=alice@company.com<br/>role=Admin"]
+
+    Workspace --> Everyone
+    Workspace --> AliceAdmin
 ```
 
 When both a wildcard binding and an explicit binding exist for a user, the highest role wins.
@@ -60,14 +69,16 @@ When both a wildcard binding and an explicit binding exist for a user, the highe
 
 The predefined roles form a hierarchy — each role includes all permissions of the roles below it:
 
-```text
-PlatformAdmin (all operations across all workspaces)
- ▲
- Admin (+ manage members, change visibility)
- ▲
- Editor (+ create, update, delete resources)
- ▲
- Viewer (list, read, run inference)
+```mermaid
+flowchart BT
+    Viewer["Viewer<br/>list, read, run inference"]
+    Editor["Editor<br/>create, update, delete resources"]
+    Admin["Admin<br/>manage members, change visibility"]
+    PlatformAdmin["PlatformAdmin<br/>all operations across all workspaces"]
+
+    Viewer --> Editor
+    Editor --> Admin
+    Admin --> PlatformAdmin
 ```
 
 Custom roles can be defined at deployment time with arbitrary permission sets — they do not need to follow this hierarchy. For the complete permission matrix, see [Roles & Permissions](/documentation/access-control/authorization/roles-and-permissions).
@@ -118,19 +129,16 @@ A role binding contains:
 - **Workspace**: The workspace where access is granted (e.g., `team-ml`)
 - **Role**: The role being assigned (e.g., `Editor`)
 
-```text
-Workspace: "team-ml-research"
-├── Role Binding 1
-│ ├── Principal: "alice@company.com"
-│ └── Role: "Admin"
-│
-├── Role Binding 2
-│ ├── Principal: "bob@company.com"
-│ └── Role: "Editor"
-│
-└── Role Binding 3
- ├── Principal: "charlie@company.com"
- └── Role: "Viewer"
+```mermaid
+flowchart TB
+    WorkspaceRB["Workspace: team-ml-research"]
+    RB1["Role Binding 1<br/>alice@company.com<br/>Admin"]
+    RB2["Role Binding 2<br/>bob@company.com<br/>Editor"]
+    RB3["Role Binding 3<br/>charlie@company.com<br/>Viewer"]
+
+    WorkspaceRB --> RB1
+    WorkspaceRB --> RB2
+    WorkspaceRB --> RB3
 ```
 
 ## Automatic Role Assignment

@@ -37,7 +37,7 @@ auth:
  admin_email: "your-admin@company.com"
 ```
 
-For a complete reference of all `auth` fields and their defaults, see the [platform configuration reference](/documentation/reference/configuration-reference). Auth-related values are found under `platformConfig.auth` in the values file.
+This page covers the auth-specific configuration fields you need to enable and operate authorization. Auth-related values are found under `platformConfig.auth` in the values file.
 
 For OIDC-specific fields (`auth.oidc`), see [OIDC Setup](/documentation/access-control/authentication/oidc-setup).