From 9b9f95a259929e36874611aeb754b5bfd5f0d3d7 Mon Sep 17 00:00:00 2001
From: Juan <juan@validmind.ai>
Date: Wed, 22 Jul 2026 18:12:43 +0200
Subject: [PATCH 1/2] Add risk tiering user guide

Add a new Risk tiering section under Guides covering the Risk Tier Engine:
an overview page plus how-tos for managing templates, configuring tier
calculation, and managing assessments. Wire the section into the guide
sidebar, the Guides landing page, and the footer navigation.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 site/_quarto.yml                              |   1 +
 site/guide/_sidebar.yaml                      |   8 +
 site/guide/guides.qmd                         |  16 ++
 .../configure-risk-tier-calculation.qmd       | 268 ++++++++++++++++++
 .../manage-risk-tier-assessments.qmd          | 179 ++++++++++++
 .../manage-risk-tier-templates.qmd            | 128 +++++++++
 .../working-with-risk-tiering.qmd             |  96 +++++++
 7 files changed, 696 insertions(+)
 create mode 100644 site/guide/risk-tiering/configure-risk-tier-calculation.qmd
 create mode 100644 site/guide/risk-tiering/manage-risk-tier-assessments.qmd
 create mode 100644 site/guide/risk-tiering/manage-risk-tier-templates.qmd
 create mode 100644 site/guide/risk-tiering/working-with-risk-tiering.qmd

diff --git a/site/_quarto.yml b/site/_quarto.yml
index 9cdad331c7..7a9d1a8903 100644
--- a/site/_quarto.yml
+++ b/site/_quarto.yml
@@ -205,6 +205,7 @@ website:
                 <li><a href="/guide/guides.qmd#integrations">Integrations</a></li>
                 <li><a href="/guide/guides.qmd#workflows">Workflows</a></li>
                 <li><a href="/guide/guides.qmd#inventory">Inventory</a></li>
+                <li><a href="/guide/guides.qmd#risk-tiering">Risk tiering</a></li>
               </ul>
               <ul class="footer-user-guides-column-2">
                 <li><a href="/guide/guides.qmd#documents-templates">Documents & templates</a></li>
diff --git a/site/guide/_sidebar.yaml b/site/guide/_sidebar.yaml
index c9860201bc..51ca2441ce 100644
--- a/site/guide/_sidebar.yaml
+++ b/site/guide/_sidebar.yaml
@@ -99,6 +99,14 @@ website:
                 - guide/inventory/configure-record-interdependencies.qmd
                 - guide/inventory/archive-delete-records.qmd
         - text: "---"
+        - section: "Risk tiering"
+          contents:
+            - file: guide/risk-tiering/working-with-risk-tiering.qmd
+              contents:
+                - guide/risk-tiering/manage-risk-tier-templates.qmd
+                - guide/risk-tiering/configure-risk-tier-calculation.qmd
+                - guide/risk-tiering/manage-risk-tier-assessments.qmd
+        - text: "---"
         - section: "Documents & templates"
           contents:
             - text: "Working with templates"
diff --git a/site/guide/guides.qmd b/site/guide/guides.qmd
index b5d36744f1..e095ff3dd6 100644
--- a/site/guide/guides.qmd
+++ b/site/guide/guides.qmd
@@ -53,6 +53,17 @@ listing:
     - inventory/setting-up-the-inventory.qmd
     - inventory/working-with-the-inventory.qmd
     - inventory/managing-the-inventory.qmd
+  - id: risk-tiering
+    type: grid
+    grid-columns: 3
+    max-description-length: 250
+    sort: false
+    fields: [title, description]
+    contents:
+    - risk-tiering/working-with-risk-tiering.qmd
+    - risk-tiering/manage-risk-tier-templates.qmd
+    - risk-tiering/configure-risk-tier-calculation.qmd
+    - risk-tiering/manage-risk-tier-assessments.qmd
   - id: documents-templates
     type: grid
     grid-columns: 3
@@ -138,6 +149,11 @@ Our guides offer step-by-step instructions for frequent tasks you perform within
 :::{#inventory}
 :::
 
+## Risk tiering
+
+:::{#risk-tiering}
+:::
+
 ## Documents & templates
 
 :::{#documents-templates}
diff --git a/site/guide/risk-tiering/configure-risk-tier-calculation.qmd b/site/guide/risk-tiering/configure-risk-tier-calculation.qmd
new file mode 100644
index 0000000000..5ab831ab89
--- /dev/null
+++ b/site/guide/risk-tiering/configure-risk-tier-calculation.qmd
@@ -0,0 +1,268 @@
+---
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
+# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
+title: "Configure risk tier calculation"
+date: last-modified
+description: "Set up scoring levels, risk factors, components, scoring rules, thresholds, and override rules inside a draft template."
+---
+
+This page covers all calculation configuration inside a risk tier template: scoring levels, risk factors, components, scoring rules, thresholds, and override rules. All configuration requires the template to be in **Draft** status — configuration is locked once a template is published.
+
+For creating a template, defining risk tier levels, and managing its lifecycle, see [Manage risk tier templates](manage-risk-tier-templates.qmd).
+
+## Prerequisites
+
+- Active {{< var vm.product >}} login
+- Governance Admin or Validator role with `manage_risk_tier_template` permission
+- A risk tier template in **Draft** status with the tier calculation method selected and at least one risk tier level defined
+
+## Set up a Scorecard template
+
+### 1. Configure scoring levels
+
+Scoring levels define the numeric scale used to score each risk factor.
+
+1. Open the draft template and go to the **Scoring Levels** section.
+2. Click **Add Scoring Level**.
+3. Enter a **Name**, a numeric **Value**, and choose a **Color**.
+4. Repeat for each level in the scale.
+
+:::{.callout-note}
+Every scoring rule in every component must map to a valid scoring level.
+:::
+
+### 2. Add risk factors
+
+Risk factors are the dimensions scored during a risk assessment — for example: Materiality, Complexity, Data Sensitivity.
+
+1. Go to the **Risk Factors** section.
+2. Click **Add Risk Factor**.
+3. Enter a **Name** and an optional **Description**.
+4. Select the **Factor Aggregation Method**:
+   - **Sum** — adds all component scores in this factor.
+   - **Max** — uses only the highest component score in this factor.
+5. Click **Save**.
+6. Repeat for each risk dimension your methodology requires.
+
+To assign individual weights to factors, enable the **Weight factors individually** toggle. Each factor then carries a weight, and the weighted sum of scores determines the tier. Click **Edit Weights** to open the **Edit Risk Factor Weights** modal — use the sliders or enter values directly. The total must remain 1.00; locked factors stay fixed while other weights rebalance automatically.
+
+:::{.callout-note}
+Different factors in the same template can use different aggregation methods — for example, a Materiality factor using Sum while a Data Sensitivity factor uses Max.
+:::
+
+### 3. Add components and scoring rules
+
+Components link inventory fields to a risk factor and define how their values are scored.
+
+1. Expand a risk factor and click **Add Component**.
+2. Select the **Inventory Field** to evaluate.
+3. Select the **Scoring Type**:
+   - **Numeric range** — maps numeric field values within min/max bands to a scoring level.
+   - **Boolean** — maps a true/false field value to a scoring level.
+   - **Text match** — maps an exact text or option value to a scoring level.
+4. Click **Save**.
+5. Click **Add Rule** to write scoring rules for the component.
+
+A factor cannot have two components referencing the same inventory field.
+
+**Numeric range rules** — use for fields with numeric values (for example: number of input features, model age in months).
+
+1. Enter the **Min value** and **Max value** that define the band.
+2. Select the **Scoring Level** to assign when the field value falls within this band.
+3. Repeat to cover the full expected range. Ranges can be adjacent — for example: 0–10 → Low, 11–50 → Medium, 51+ → High.
+
+**Boolean rules** — use for checkbox fields (for example: "Is the model customer-facing?").
+
+1. Set **Value** to **True** or **False**.
+2. Select the **Scoring Level** to assign.
+3. Add a second rule for the opposite value. A Boolean component typically has two rules.
+
+**Text match rules** — use for single-select or multi-select fields (for example: "Data Classification," "Deployment Region").
+
+1. Enter the **Text value** to match (the exact option string).
+2. Select the **Scoring Level** to assign.
+3. Add one rule per option value you want to score. Values not covered by any rule are unscored.
+
+:::{.callout-note}
+Rules within a component are evaluated in order — the first matching rule wins.
+:::
+
+### 4. Set risk tier thresholds
+
+Set the score range that corresponds to each risk tier. The lowest-risk tier starts at the minimum score and the highest-risk tier ends at the maximum score.
+
+1. Go to the **Risk Tier Thresholds** section.
+2. Click **Edit Thresholds** to open the **Edit Risk Tier Thresholds** modal.
+3. Define the score range for each risk tier. Shared boundaries update automatically to keep ranges aligned.
+
+### 5. Configure override rules
+
+See [Override rules](#override-rules) below.
+
+## Set up a Risk Matrix template
+
+### 1. Configure scoring levels
+
+Scoring levels define the numeric scale used to score each risk factor.
+
+1. Open the draft template and go to the **Scoring Levels** section.
+2. Click **Add Scoring Level**.
+3. Enter a **Name**, a numeric **Value**, and choose a **Color**.
+4. Repeat for each level in the scale.
+
+:::{.callout-note}
+Every scoring rule in every component must map to a valid scoring level.
+:::
+
+### 2. Define factor levels
+
+Factor levels classify each factor's computed score into a discrete risk band — for example: High, Medium, Low.
+
+1. Go to the **Factor Levels** section.
+2. Click **Add Factor Level**.
+3. Enter a **Name**, choose a **Color**, and add an optional **Description**.
+4. Drag and drop to reorder — highest risk at the top, lowest at the bottom.
+5. Repeat for each level in the classification scale.
+
+### 3. Add risk factors
+
+Risk factors are the dimensions scored during a risk assessment — for example: Materiality, Complexity, Data Sensitivity.
+
+1. Go to the **Risk Factors** section.
+2. Click **Add Risk Factor**.
+3. Enter a **Name** and an optional **Description**.
+4. Select the **Factor Aggregation Method**:
+   - **Sum** — adds all component scores in this factor.
+   - **Max** — uses only the highest component score in this factor.
+5. Click **Save**.
+6. Repeat for each risk dimension your methodology requires.
+
+### 4. Add components and scoring rules
+
+Components link inventory fields to a risk factor and define how their values are scored.
+
+1. Expand a risk factor and click **Add Component**.
+2. Select the **Inventory Field** to evaluate.
+3. Select the **Scoring Type**:
+   - **Numeric range** — maps numeric field values within min/max bands to a scoring level.
+   - **Boolean** — maps a true/false field value to a scoring level.
+   - **Text match** — maps an exact text or option value to a scoring level.
+4. Click **Save**.
+5. Click **Add Rule** to write scoring rules for the component.
+
+A factor cannot have two components referencing the same inventory field.
+
+**Numeric range rules** — use for fields with numeric values.
+
+1. Enter the **Min value** and **Max value** for the band.
+2. Select the **Scoring Level** to assign.
+3. Repeat to cover the full expected range.
+
+**Boolean rules** — use for checkbox fields.
+
+1. Set **Value** to **True** or **False**.
+2. Select the **Scoring Level** to assign.
+3. Add a second rule for the opposite value.
+
+**Text match rules** — use for single-select or multi-select fields.
+
+1. Enter the **Text value** to match.
+2. Select the **Scoring Level** to assign.
+3. Add one rule per option value you want to score.
+
+:::{.callout-note}
+Rules within a component are evaluated in order — the first matching rule wins.
+:::
+
+### 5. Set factor level thresholds
+
+Each risk factor requires a score threshold for each factor level, defining the score range that maps to that level.
+
+1. Expand a risk factor and go to the **Factor Level Thresholds** section.
+2. Click **Edit Factor Level Thresholds**.
+3. Define the score range for each factor level. Shared boundaries update automatically to keep ranges aligned.
+4. Repeat for each risk factor.
+
+### 6. Assign tiers to factor level combinations
+
+Tier assignment maps every combination of factor levels to a risk tier.
+
+1. Go to the **Tier Assignment** section.
+2. Click **Edit Tiers**.
+3. Choose a view:
+   - **Matrix** — displays a visual grid with factors on each axis. Use the **Factor**, **At Level**, **Row Axis**, and **Column Axis** dropdowns to navigate combinations. Click a cell to assign a risk tier.
+   - **Table** — lists every factor level combination as a row with an **Assigned Tier** column. Use this view when you have more than two factors.
+4. Assign a risk tier to every combination. All cells must be assigned before the template can be published.
+
+### 7. Configure override rules
+
+See [Override rules](#override-rules) below.
+
+## Override rules
+
+Override rules allow you to hard-code a specific tier outcome for records that match certain field conditions, bypassing the computed score or matrix lookup entirely. If a rule matches, the tier it specifies is used and no further rules or scores are evaluated.
+
+Use override rules when certain field values are disqualifying regardless of the overall score — for example: "if a model processes health data AND is customer-facing, always assign Critical."
+
+### Add an override rule
+
+1. Open the **Override Rules** section of the template.
+2. Click **Add Rule**.
+3. Select the **Target Tier** — the tier to assign when this rule matches.
+4. Select the **Condition Logic**:
+   - **AND** — all conditions must be true for the rule to match.
+   - **OR** — any single condition being true causes the rule to match.
+5. Add one or more **Conditions** (see below).
+6. Click **Save**.
+
+Rules are evaluated in order; the first matching rule wins. New rules are appended at the end.
+
+### Add conditions to a rule
+
+1. Within an override rule, click **Add Condition**.
+2. Select the **Inventory Field** to evaluate. Only supported field types are available (see table below).
+3. Select the **Operator**.
+4. Enter the **Value** to compare against.
+5. Click **Save**.
+
+### Supported field types and operators
+
+| Field type | Available operators |
+|---|---|
+| Number | equals, not equals, greater than, less than, greater than or equal, less than or equal |
+| Checkbox | equals |
+| Single-select | equals, not equals |
+| Multi-select | contains, not contains |
+
+:::{.callout-note}
+Override rules are copied forward when a new template version is created. Removing a tier level that an override rule targets will blank the rule's target tier and block publishing until it is reassigned.
+:::
+
+## Publish readiness checklist
+
+Before publishing, verify:
+
+**Both methods:**
+
+- [ ] At least one risk tier is defined
+- [ ] At least one risk factor is configured
+- [ ] Every factor has at least one component
+- [ ] Every component has at least one scoring rule
+- [ ] All scoring rules map to valid scoring levels
+- [ ] Override rules: all target tiers point to existing tier levels; all conditions reference valid fields
+
+**Scorecard only:**
+
+- [ ] Tier thresholds cover the full score range without gaps
+- [ ] All factor weights sum to 1.00 if **Weight factors individually** is enabled
+
+**Risk Matrix only:**
+
+- [ ] All factor level thresholds are set for every factor
+- [ ] Every factor level combination in the matrix has an assigned tier
+
+## What's next
+
+- [Manage risk tier templates](manage-risk-tier-templates.qmd) — publish, version, and manage the template lifecycle.
+- [Manage risk tier assessments](manage-risk-tier-assessments.qmd) — create assessments and apply the published template to your records.
diff --git a/site/guide/risk-tiering/manage-risk-tier-assessments.qmd b/site/guide/risk-tiering/manage-risk-tier-assessments.qmd
new file mode 100644
index 0000000000..b946d2c605
--- /dev/null
+++ b/site/guide/risk-tiering/manage-risk-tier-assessments.qmd
@@ -0,0 +1,179 @@
+---
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
+# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
+title: "Manage risk tier assessments"
+date: last-modified
+description: "Create, review, publish, and version risk tier assessments for individual inventory records."
+---
+
+A risk tier assessment is a formal evaluation of a specific inventory record against a published risk tier template. It reads the current inventory field values, applies the template's scoring rules, and produces a tier determination — either computed from scores or set by an override rule.
+
+This page covers creating an assessment, reviewing factor scores, publishing, managing versions, and handling stale assessments.
+
+## Prerequisites
+
+- Active {{< var vm.product >}} login
+- A record registered in the model inventory
+- An active risk tier template published for that record's type
+
+## Access risk tier assessments
+
+Open a record from the **Model Inventory** and select the **Risk Tier Assessments** tab. The tab shows:
+
+- **Active Template** — the currently published template displayed at the top of the page. Any new assessment or new version is automatically linked to this template version.
+- The list of assessments for this record, with columns: Name, Template, Status, Tier, Last Updated, Last Updated By.
+
+The list defaults to hiding Archived assessments. Remove the **Status not in Archived** filter to see the full history.
+
+## Create an assessment
+
+1. Click **+ Add Risk Tier Assessment**.
+2. Enter a **Name** — for example: "Annual Review 2025" or "Post-remediation check".
+3. Enter an optional **Description**.
+4. Click **Save**. The assessment is created in **Draft** status and automatically linked to the current Active Template version. The template version is locked in at this point — subsequent template updates do not affect this assessment.
+
+:::{.callout-note}
+If no active template exists for the record's type, a new assessment cannot be created. Contact your administrator to ensure a template has been published for this record type.
+:::
+
+## Review factor scores
+
+The assessment detail page is organized into five sections. Together they show how the record's current inventory field values translate into a risk tier.
+
+### Risk Factors
+
+The **Risk Factors** section lists each factor from the template as a collapsible row, showing the factor name and the number of inventory fields it evaluates.
+
+Expand a factor to see its components. For each component you can see:
+
+- The **inventory field name** and its current value.
+- A scoring explanation — **This value scores X → matches [rule]** — showing which scoring rule matched and what score level it produced.
+- An **ℹ** icon that opens a popover with the field description and **Recent Field Activity** (a log of recent updates to that field with View Details links).
+
+If a field value has changed since the assessment was last published, the updated value and score are reflected immediately.
+
+### Factor Score Breakdown
+
+The **Factor Score Breakdown** table summarizes how each factor's components roll up into a factor score:
+
+| Column | Description |
+|---|---|
+| Risk Factor | Factor name |
+| Current Score | The factor's computed score given the current field values |
+| Components | Number of components in this factor |
+| Aggregation | The factor aggregation method in use (Sum or Max) |
+| Min Score | The lowest possible score for this factor |
+| Max Score | The highest possible score for this factor |
+
+The **Current Total Score** row at the bottom shows the sum across all factors.
+
+### Risk Tier Thresholds
+
+The **Risk Tier Thresholds** table shows the score band for each risk tier. The row corresponding to the current total score is highlighted, indicating where the record lands on the scorecard.
+
+### Override Rules
+
+The **Override Rules** section displays the template's override rules as read-only, evaluated in order against this record. Each rule shows its number, target tier, and condition — for example: "Rule 1 → Tier 1: If Estimated Dollar Exposure ≥ 10000000."
+
+Override rules are part of the template and cannot be modified from within an assessment.
+
+### Calculated Tier
+
+The **Calculated Tier** section shows the final tier determination for this assessment:
+
+- If an override rule matched, the section indicates which rule applied and the tier it assigned.
+- If no override rule matched, the tier is determined by where the current total score falls in the threshold bands.
+
+## Assessment sidebar
+
+The sidebar on the assessment detail page shows:
+
+- **Status** — Draft, Active, or Archived.
+- **Assessment Version** — a dropdown showing the current version (for example: "13 (Latest)"). Use this to navigate to any previous version of the assessment.
+- **Risk Tier Template** — the template name and version this assessment is linked to, with a badge showing the calculation method (Scorecard or Risk Matrix).
+- **Published / Published By** — the publication date and the user who published it (shown once the assessment has been published).
+
+Actions available from the sidebar depend on the assessment's status:
+
+- **Draft** — Publish button to publish the assessment.
+- **Active** — **Create New Version** to start a new draft, and **Archive Assessment** to manually archive.
+
+## Publish an assessment
+
+When you are satisfied with the factor scores and the calculated tier:
+
+1. Click **Publish** in the sidebar.
+2. Confirm the publish. The assessment moves to **Active**, receives a version number (v1, v2, …), and becomes the record's current official risk tier. The record's **Assessed Risk Tier** field is updated automatically — see [Assessed Risk Tier field](#assessed-risk-tier-field) below.
+
+Only one assessment can be Active per record at a time.
+
+:::{.callout-note}
+An assessment can only be published against an **Active** template version. If the template linked to your assessment has since been archived, you must migrate to the current template before publishing (see [Migrate a stale assessment](#migrate-a-stale-assessment)).
+:::
+
+## Assessed Risk Tier field
+
+When an assessment is published, the record's **Assessed Risk Tier** inventory field is automatically updated to reflect the calculated tier. This field is system-managed and read-only — it cannot be edited manually.
+
+The field displays the tier using the same badge style used throughout the Risk Tier Engine. A **See Assessment** link appears directly below it, allowing anyone viewing the record to navigate to the published assessment in one click.
+
+The Assessed Risk Tier field coexists with the legacy **Tier** field on the record. The legacy Tier field remains manually managed and independent of the assessment outcome.
+
+## Create a new version
+
+When a record's risk profile changes and a re-evaluation is needed:
+
+1. Open the active assessment and click **Create New Version** in the sidebar.
+2. A new **Draft** is created, pre-linked to the latest active template. Previously entered values are carried forward for fields that exist in both the old and new template.
+3. Review the factor scores and confirm the calculated tier.
+4. Publish. The new assessment becomes Active and the previous is Archived.
+
+## Archive an assessment
+
+To manually retire the active assessment without publishing a new version:
+
+1. Open the active assessment and click **Archive Assessment** in the sidebar.
+2. Confirm. The assessment moves to **Archived**.
+
+:::{.callout-note}
+Archiving leaves the record without an active assessment. The **Assessed Risk Tier** inventory field will no longer reflect a current determination until a new assessment is published.
+:::
+
+## Understand stale assessments
+
+An assessment becomes **stale** when the template version it was created against has been superseded by a new active version.
+
+- **Active assessments** are never marked stale — a published assessment's methodology is frozen at the version it was published against.
+- **Draft assessments** are marked stale when their linked template version is no longer active.
+- A stale draft **cannot be published** until it is on the current active template version — create a new version to move it there (see [Migrate a stale assessment](#migrate-a-stale-assessment)).
+
+Stale assessments are flagged with a warning banner in the assessment detail view.
+
+## Migrate a stale assessment
+
+There is no in-place "use latest template" action. To move an assessment onto the current active template, create a new version — the new version is automatically linked to the latest active template.
+
+1. Open the assessment and click **Create New Version** in the sidebar (see [Create a new version](#create-a-new-version)).
+2. The new **Draft** is automatically linked to the current active template version. Previously entered values are carried forward for fields that exist in both versions; fields removed from the new template are cleared, and new fields appear as not set.
+3. Review the updated factor scores and calculated tier.
+4. Publish as normal.
+
+## View version history
+
+The **Assessment Version** dropdown in the sidebar gives access to all versions of the current assessment. Remove the Archived filter on the **Risk Tier Assessments** tab to see the full history across all statuses. Archived assessments remain readable at any time for audit and comparison purposes.
+
+## Delete a draft assessment
+
+1. Open the draft assessment and click **Delete**.
+2. Confirm. The assessment is permanently removed.
+
+:::{.callout-note}
+Only **Draft** assessments can be deleted. Active and Archived assessments are permanent audit artifacts and cannot be deleted.
+:::
+
+## What's next
+
+- [Working with risk tiering](working-with-risk-tiering.qmd) — concepts, lifecycle overview, and roles.
+- [Manage risk tier templates](manage-risk-tier-templates.qmd) — how templates are configured and published.
+- [Configure risk tier calculation](configure-risk-tier-calculation.qmd) — how factors, scoring rules, and override rules work.
diff --git a/site/guide/risk-tiering/manage-risk-tier-templates.qmd b/site/guide/risk-tiering/manage-risk-tier-templates.qmd
new file mode 100644
index 0000000000..0ac0b301b5
--- /dev/null
+++ b/site/guide/risk-tiering/manage-risk-tier-templates.qmd
@@ -0,0 +1,128 @@
+---
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
+# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
+title: "Manage risk tier templates"
+date: last-modified
+description: "Create, publish, version, duplicate, and archive the risk tier templates that define your classification methodology."
+---
+
+Risk tier templates define the methodology your organization uses to classify records into risk tiers. This page covers creating a template, defining its risk tier levels, publishing it, and managing its lifecycle.
+
+For configuring the scoring levels, risk factors, components, thresholds, and override rules that determine how a tier is calculated, see [Configure risk tier calculation](configure-risk-tier-calculation.qmd).
+
+## Prerequisites
+
+- Active {{< var vm.product >}} login
+- Governance Admin or Validator role with `manage_risk_tier_template` permission
+- At least one primary record type configured in your inventory
+
+## Access risk tier templates
+
+Navigate to **Settings → Governance → Risk Tier Templates**. The page lists all templates in your organization across all lifecycle statuses. Use the status filter to view Draft, Active, or Archived templates separately.
+
+## Create a template
+
+1. Click **Add Risk Tier Template**.
+2. Enter a **Name**. Template names must be unique across the entire system — no two templates, even across different version lineages, can share the same name.
+3. Enter an optional **Description**.
+4. Select one or more **Record Types** the template applies to. A separate active template can exist for each record type, allowing your organization to use different risk methodologies for models, agents, or other inventory types.
+5. Optionally link one or more **Regulations** that this template's methodology is designed to support. Regulation links can be added or removed at any time while the template is in Draft.
+6. Click **Save**. The template is created in **Draft** status.
+
+## Select a tier calculation method
+
+On the template detail page, select the **Tier Calculation Method**:
+
+- **Scorecard** — factor scores are summed into a total that falls into a threshold band mapped to a tier. Factor weights can optionally be configured in the Risk Factors section.
+- **Risk Matrix** — each factor is independently classified into a discrete risk level, and the combination of all factor levels is looked up in a matrix to determine the final tier.
+
+Once selected, configure the scoring logic for your chosen method. See [Configure risk tier calculation](configure-risk-tier-calculation.qmd).
+
+## Define risk tier levels
+
+Risk tier levels are the possible classification outcomes the template can produce — for example: Low, Medium, High, Critical.
+
+1. Open the draft template and go to the **Risk Tiers** section.
+2. Click **Add Risk Tier**.
+3. Enter a **Name**, an optional **Description**, and choose a **Color** to visually distinguish the level across the platform.
+4. Drag and drop to reorder — highest risk at the top, lowest at the bottom.
+5. Repeat for each tier your methodology requires.
+
+:::{.callout-note}
+Removing a tier level after thresholds, matrix assignments, or override rules have been set will blank the affected entries and block publishing until they are reassigned.
+:::
+
+## Publish a template
+
+Before publishing, the system validates that the template is complete. See the publish readiness checklist in [Configure risk tier calculation](configure-risk-tier-calculation.qmd#publish-readiness-checklist) for the full list of requirements.
+
+To publish:
+
+1. Open the draft template and click **Publish**.
+2. Review the confirmation — the template will be assigned the next version number (v1, v2, …).
+3. Confirm. The template moves to **Active** and any previously active version for the same record type is automatically **Archived**.
+
+:::{.callout-note}
+Published templates are immutable. To make changes, create a new version.
+:::
+
+## Create a new version
+
+Use a new version to update a published template without disrupting in-progress assessments.
+
+1. Open the active template and click **New Version**.
+2. A new **Draft** is created as a complete copy of the active template, including all scoring configuration and override rules. If a draft already exists, clicking **New Version** returns the existing draft rather than creating a duplicate.
+3. Edit the draft as needed and publish.
+
+:::{.callout-note}
+Active assessments linked to the previous version are not affected. Draft assessments linked to the previous version are flagged as **stale** and must be migrated before they can be published. See [Manage risk tier assessments](manage-risk-tier-assessments.qmd#understand-stale-assessments).
+:::
+
+## Duplicate a template
+
+Duplicating creates an independent copy of an existing template as a new Draft, starting a separate version lineage under a new name.
+
+1. From the template list, open the row menu (**⋯**) on any Active or Archived template.
+2. Select **Duplicate Template**. A new Draft is created with a full copy of the template's configuration.
+3. Open the draft, rename it, and edit as needed.
+4. Publish when ready.
+
+:::{.callout-note}
+If published without renaming, the duplicate joins the same version lineage as the source template.
+:::
+
+## Archive a template
+
+1. Open the active template and click **Archive**.
+2. Confirm. The template moves to **Archived**.
+
+:::{.callout-note}
+Archiving leaves the record type without an active template — new assessments cannot be created until a new template is published. Archived templates are read-only and cannot be directly reactivated.
+:::
+
+## Restore an archived version
+
+1. Open the archived template and click **Restore this version**.
+2. A new **Draft** is created pre-populated with the archived version's configuration.
+3. Review, adjust if needed, and publish.
+
+Restoring does not reactivate the archived version — it always creates a new Draft, preserving the append-only version history.
+
+## Delete a draft template
+
+1. Open the draft template and click **Delete**.
+2. Confirm. The template and all its configuration are permanently removed.
+
+:::{.callout-note}
+Only **Draft** templates can be deleted. Active and Archived templates are permanent audit artifacts and cannot be deleted.
+:::
+
+## View version history
+
+Every template's detail page shows its full version history — all published versions with their version numbers, publication dates, and current status. Archived versions remain readable at any time for audit purposes and can be restored as described above.
+
+## What's next
+
+- [Configure risk tier calculation](configure-risk-tier-calculation.qmd) — set up scoring levels, factors, components, thresholds, and override rules.
+- [Manage risk tier assessments](manage-risk-tier-assessments.qmd) — create and publish assessments for your records against a published template.
diff --git a/site/guide/risk-tiering/working-with-risk-tiering.qmd b/site/guide/risk-tiering/working-with-risk-tiering.qmd
new file mode 100644
index 0000000000..72cdae2a96
--- /dev/null
+++ b/site/guide/risk-tiering/working-with-risk-tiering.qmd
@@ -0,0 +1,96 @@
+---
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
+# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
+title: "Working with risk tiering"
+date: last-modified
+description: "Concepts, lifecycle, and roles for classifying inventory records into discrete risk tiers."
+listing:
+  - id: risk-tiering-guides
+    type: grid
+    grid-columns: 3
+    max-description-length: 250
+    sort: false
+    fields: [title, description]
+    contents:
+      - manage-risk-tier-templates.qmd
+      - configure-risk-tier-calculation.qmd
+      - manage-risk-tier-assessments.qmd
+---
+
+Risk tiering gives your organization a structured, auditable way to classify AI models and other inventory records into discrete risk categories. Instead of relying on informal judgment calls, risk classification follows a defined methodology — configured once by administrators and applied consistently across every record in your inventory.
+
+## Overview
+
+The Risk Tier Engine has two sides that work together:
+
+- **Risk tier templates** define the methodology. Administrators configure the tier levels, risk factors, scoring rules, and assignment logic. Templates are versioned and published, giving your organization a full, immutable history of how its risk classification methodology has evolved.
+- **Risk tier assessments** are the evaluations. Developers apply a published template to a specific record, enter the required field values, review the computed tier suggestion, and publish a final determination. Assessments are also versioned, giving each record a complete history of how its risk tier has changed over time.
+
+## Key concepts
+
+**Risk tier template**
+The complete methodology for evaluating a record's risk. A template defines tier levels, risk factors, components, scoring rules, and the logic used to assign a final tier. Templates follow a Draft → Active → Archived lifecycle and are versioned — every published version is retained for audit purposes.
+
+**Risk tier assessment**
+A formal evaluation of a specific record against a risk tier template. An assessment records the field values entered, the computed scores, the system's suggested tier, any override rules that applied, and the final published determination.
+
+**Tier calculation method**
+Controls how risk factor scores roll up into a final tier:
+
+- **Scorecard (Sum)** — factor scores are summed into a total that falls into a threshold band mapped to a tier.
+- **Scorecard (Weighted)** — same as Sum, but each factor carries a weight (0–1); factor scores are multiplied by their weights before summing. Factor weights are required.
+- **Risk Matrix** — each factor is independently classified into a discrete risk level, and the combination of all factor levels is looked up in a matrix to determine the final tier.
+
+**Risk tier**
+A discrete risk classification outcome — for example: Low, Medium, High, Critical. Risk tiers are defined as part of a template and represent the possible outputs of an assessment.
+
+**Scoring level**
+Scoring levels define the numeric scale used to score each risk factor within a template — for example: Very Low (1), Low (2), Medium (3), High (4), Very High (5).
+
+**Risk factor**
+A dimension of risk being evaluated within a template — for example: Materiality, Complexity, Data Sensitivity. Each factor groups one or more components that feed into it.
+
+**Factor component**
+A specific inventory field that contributes to a risk factor's score. Each factor component includes scoring rules that map field values — or ranges of values — to a numeric scoring level.
+
+**Override rule**
+An optional rule on a template that forces a specific tier outcome when certain field conditions are met, bypassing the computed score entirely.
+
+**Factor aggregation method**
+A per-factor setting that controls how component scores within a factor combine into a single factor score:
+
+- **Sum** — all component scores are added together.
+- **Max** — only the highest component score is used.
+
+**Assessed Risk Tier**
+A system-managed, read-only inventory field that surfaces the risk tier of a record's most recently published assessment. It is automatically updated when an assessment is published and is visible to anyone with access to the record.
+
+## Lifecycle
+
+Both templates and assessments follow the same three lifecycle statuses:
+
+| Status | Description |
+|---|---|
+| **Draft** | Being created or edited. Not yet in effect. Can be freely modified. |
+| **Active** | Published and currently in effect. Read-only. Only one version can be Active at a time. |
+| **Archived** | Superseded or retired. Read-only. Retained permanently for audit purposes. |
+
+Version history is append-only — once a version is published, its configuration is immutable. A new version must be created to make changes. Only one version of a given template can be Active at a time per record type. Only one assessment can be Active per record at a time.
+
+## Who does what
+
+| Role | Responsibilities |
+|---|---|
+| **Governance Admin / Validator** | Creates and publishes risk tier templates; defines tier levels, factors, components, scoring rules, thresholds, and override rules; manages template versions |
+| **Developer** | Creates and publishes risk tier assessments for specific records; enters factor values; reviews the suggested tier; manages assessment versions |
+
+## Where to access risk tiering
+
+- **Risk tier templates** — navigate to **Settings → Governance → Risk Tier Templates**.
+- **Risk tier assessments** — open any record in the model inventory and select the **Risk Tier Assessments** tab.
+
+## What's next
+
+:::{#risk-tiering-guides .intro-listing}
+:::

From 14a95d9961d0a1629539e2e5beda612d546ed34f Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Wed, 22 Jul 2026 16:33:09 +0000
Subject: [PATCH 2/2] chore: refresh chatbot product map

---
 site/llm/chatbot-product-map.md | 36 ++++++++++++++++-----------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/site/llm/chatbot-product-map.md b/site/llm/chatbot-product-map.md
index c161b0a8b5..e30b6eb798 100644
--- a/site/llm/chatbot-product-map.md
+++ b/site/llm/chatbot-product-map.md
@@ -84,6 +84,8 @@
 
 **Docs (related):**
 
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+  - Sections: Prerequisites; Access risk tier templates; Create a template; Select a tier calculation method; Define risk tier levels; Publish a template; Create a new version; Duplicate a template
 - `/guide/templates/customize-document-checker.html`
   - Sections: Prerequisites; Manage regulations and policies; Manage assessments; Default assessments provided by } cannot be edited, only cloned.; Add or clone assessments; Add or edit assessment questions; Add assessment questions; Edit assessment questions
 - `/guide/templates/customize-document-templates.html`
@@ -94,8 +96,6 @@
   - Sections: Prerequisites; Add document types; Edit or delete document types; Development, Validation, and Monitoring document types are stock types and cannot be deleted.
 - `/guide/templates/manage-documents.html`
   - Sections: Prerequisites; Add record documents; How do I get the best results when converting PDFs into editable documents?; How can I trust that the conversion is accurate?; Troubleshooting; My PDF conversion is stuck. What can I do?; Edit record documents; Delete record documents
-- `/guide/templates/managing-documents.html`
-  - Sections: Manage document defaults; Manage document types and documents; What's next
 
 ### Main navigation
 
@@ -117,6 +117,8 @@
 
 **Docs (related):**
 
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+  - Sections: Prerequisites; Access risk tier templates; Create a template; Select a tier calculation method; Define risk tier levels; Publish a template; Create a new version; Duplicate a template
 - `/guide/templates/customize-document-checker.html`
   - Sections: Prerequisites; Manage regulations and policies; Manage assessments; Default assessments provided by } cannot be edited, only cloned.; Add or clone assessments; Add or edit assessment questions; Add assessment questions; Edit assessment questions
 - `/guide/templates/customize-document-templates.html`
@@ -127,13 +129,13 @@
   - Sections: Prerequisites; Add record documents; How do I get the best results when converting PDFs into editable documents?; How can I trust that the conversion is accurate?; Troubleshooting; My PDF conversion is stuck. What can I do?; Edit record documents; Delete record documents
 - `/guide/templates/manage-text-block-library.html`
   - Sections: Prerequisites; Add text blocks; Add existing text blocks to library; Duplicate text blocks; Edit text blocks; Delete text blocks
-- `/guide/templates/managing-documents.html`
-  - Sections: Manage document defaults; Manage document types and documents; What's next
 
 #### `/settings/documents/general` — General
 
 **Docs (related):**
 
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+  - Sections: Prerequisites; Access risk tier templates; Create a template; Select a tier calculation method; Define risk tier levels; Publish a template; Create a new version; Duplicate a template
 - `/guide/templates/customize-document-checker.html`
   - Sections: Prerequisites; Manage regulations and policies; Manage assessments; Default assessments provided by } cannot be edited, only cloned.; Add or clone assessments; Add or edit assessment questions; Add assessment questions; Edit assessment questions
 - `/guide/templates/customize-document-templates.html`
@@ -144,8 +146,6 @@
   - Sections: Prerequisites; Add document types; Edit or delete document types; Development, Validation, and Monitoring document types are stock types and cannot be deleted.
 - `/guide/templates/manage-documents.html`
   - Sections: Prerequisites; Add record documents; How do I get the best results when converting PDFs into editable documents?; How can I trust that the conversion is accurate?; Troubleshooting; My PDF conversion is stuck. What can I do?; Edit record documents; Delete record documents
-- `/guide/templates/manage-text-block-library.html`
-  - Sections: Prerequisites; Add text blocks; Add existing text blocks to library; Duplicate text blocks; Edit text blocks; Delete text blocks
 
 - *No direct help link in frontend; related docs inferred from keywords.*
 
@@ -174,6 +174,8 @@
 
 **Docs (related):**
 
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+  - Sections: Prerequisites; Access risk tier templates; Create a template; Select a tier calculation method; Define risk tier levels; Publish a template; Create a new version; Duplicate a template
 - `/guide/templates/customize-document-checker.html`
   - Sections: Prerequisites; Manage regulations and policies; Manage assessments; Default assessments provided by } cannot be edited, only cloned.; Add or clone assessments; Add or edit assessment questions; Add assessment questions; Edit assessment questions
 - `/guide/templates/customize-document-templates.html`
@@ -184,8 +186,6 @@
   - Sections: Prerequisites; Add document types; Edit or delete document types; Development, Validation, and Monitoring document types are stock types and cannot be deleted.
 - `/guide/templates/manage-documents.html`
   - Sections: Prerequisites; Add record documents; How do I get the best results when converting PDFs into editable documents?; How can I trust that the conversion is accurate?; Troubleshooting; My PDF conversion is stuck. What can I do?; Edit record documents; Delete record documents
-- `/guide/templates/manage-text-block-library.html`
-  - Sections: Prerequisites; Add text blocks; Add existing text blocks to library; Duplicate text blocks; Edit text blocks; Delete text blocks
 
 #### `/settings/finding-severities` — Artifact Severities
 
@@ -196,6 +196,8 @@
 
 **Docs (related):**
 
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+  - Sections: Prerequisites; Access risk tier templates; Create a template; Select a tier calculation method; Define risk tier levels; Publish a template; Create a new version; Duplicate a template
 - `/guide/templates/customize-document-checker.html`
   - Sections: Prerequisites; Manage regulations and policies; Manage assessments; Default assessments provided by } cannot be edited, only cloned.; Add or clone assessments; Add or edit assessment questions; Add assessment questions; Edit assessment questions
 - `/guide/templates/customize-document-templates.html`
@@ -206,8 +208,6 @@
   - Sections: Prerequisites; Add document types; Edit or delete document types; Development, Validation, and Monitoring document types are stock types and cannot be deleted.
 - `/guide/templates/manage-documents.html`
   - Sections: Prerequisites; Add record documents; How do I get the best results when converting PDFs into editable documents?; How can I trust that the conversion is accurate?; Troubleshooting; My PDF conversion is stuck. What can I do?; Edit record documents; Delete record documents
-- `/guide/templates/manage-text-block-library.html`
-  - Sections: Prerequisites; Add text blocks; Add existing text blocks to library; Duplicate text blocks; Edit text blocks; Delete text blocks
 
 #### `/settings/finding-types` — Artifact Types
 
@@ -218,6 +218,8 @@
 
 **Docs (related):**
 
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+  - Sections: Prerequisites; Access risk tier templates; Create a template; Select a tier calculation method; Define risk tier levels; Publish a template; Create a new version; Duplicate a template
 - `/guide/templates/customize-document-checker.html`
   - Sections: Prerequisites; Manage regulations and policies; Manage assessments; Default assessments provided by } cannot be edited, only cloned.; Add or clone assessments; Add or edit assessment questions; Add assessment questions; Edit assessment questions
 - `/guide/templates/customize-document-templates.html`
@@ -228,8 +230,6 @@
   - Sections: Prerequisites; Add document types; Edit or delete document types; Development, Validation, and Monitoring document types are stock types and cannot be deleted.
 - `/guide/templates/manage-documents.html`
   - Sections: Prerequisites; Add record documents; How do I get the best results when converting PDFs into editable documents?; How can I trust that the conversion is accurate?; Troubleshooting; My PDF conversion is stuck. What can I do?; Edit record documents; Delete record documents
-- `/guide/templates/manage-text-block-library.html`
-  - Sections: Prerequisites; Add text blocks; Add existing text blocks to library; Duplicate text blocks; Edit text blocks; Delete text blocks
 
 ### Users & Access
 
@@ -392,6 +392,8 @@
 
 **Docs (related):**
 
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+  - Sections: Prerequisites; Access risk tier templates; Create a template; Select a tier calculation method; Define risk tier levels; Publish a template; Create a new version; Duplicate a template
 - `/guide/templates/customize-document-checker.html`
   - Sections: Prerequisites; Manage regulations and policies; Manage assessments; Default assessments provided by } cannot be edited, only cloned.; Add or clone assessments; Add or edit assessment questions; Add assessment questions; Edit assessment questions
 - `/guide/templates/customize-document-templates.html`
@@ -402,8 +404,6 @@
   - Sections: Prerequisites; Add document types; Edit or delete document types; Development, Validation, and Monitoring document types are stock types and cannot be deleted.
 - `/guide/templates/manage-documents.html`
   - Sections: Prerequisites; Add record documents; How do I get the best results when converting PDFs into editable documents?; How can I trust that the conversion is accurate?; Troubleshooting; My PDF conversion is stuck. What can I do?; Edit record documents; Delete record documents
-- `/guide/templates/manage-text-block-library.html`
-  - Sections: Prerequisites; Add text blocks; Add existing text blocks to library; Duplicate text blocks; Edit text blocks; Delete text blocks
 
 - *No direct help link in frontend; related docs inferred from keywords.*
 
@@ -450,6 +450,8 @@
 
 **Docs (related):**
 
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+  - Sections: Prerequisites; Access risk tier templates; Create a template; Select a tier calculation method; Define risk tier levels; Publish a template; Create a new version; Duplicate a template
 - `/guide/templates/customize-document-checker.html`
   - Sections: Prerequisites; Manage regulations and policies; Manage assessments; Default assessments provided by } cannot be edited, only cloned.; Add or clone assessments; Add or edit assessment questions; Add assessment questions; Edit assessment questions
 - `/guide/templates/manage-document-templates.html`
@@ -460,8 +462,6 @@
   - Sections: Prerequisites; Add record documents; How do I get the best results when converting PDFs into editable documents?; How can I trust that the conversion is accurate?; Troubleshooting; My PDF conversion is stuck. What can I do?; Edit record documents; Delete record documents
 - `/guide/templates/manage-text-block-library.html`
   - Sections: Prerequisites; Add text blocks; Add existing text blocks to library; Duplicate text blocks; Edit text blocks; Delete text blocks
-- `/guide/templates/managing-documents.html`
-  - Sections: Manage document defaults; Manage document types and documents; What's next
 
 ### Your Account
 
@@ -555,6 +555,8 @@
 
 **Docs (related):**
 
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+  - Sections: Prerequisites; Access risk tier templates; Create a template; Select a tier calculation method; Define risk tier levels; Publish a template; Create a new version; Duplicate a template
 - `/guide/templates/customize-document-checker.html`
   - Sections: Prerequisites; Manage regulations and policies; Manage assessments; Default assessments provided by } cannot be edited, only cloned.; Add or clone assessments; Add or edit assessment questions; Add assessment questions; Edit assessment questions
 - `/guide/templates/customize-document-templates.html`
@@ -565,8 +567,6 @@
   - Sections: Prerequisites; Add document types; Edit or delete document types; Development, Validation, and Monitoring document types are stock types and cannot be deleted.
 - `/guide/templates/manage-documents.html`
   - Sections: Prerequisites; Add record documents; How do I get the best results when converting PDFs into editable documents?; How can I trust that the conversion is accurate?; Troubleshooting; My PDF conversion is stuck. What can I do?; Edit record documents; Delete record documents
-- `/guide/templates/manage-text-block-library.html`
-  - Sections: Prerequisites; Add text blocks; Add existing text blocks to library; Duplicate text blocks; Edit text blocks; Delete text blocks
 
 - *No direct help link in frontend; related docs inferred from keywords.*