docs(config_guide): add graduation guides and update scoring

docs/config_guide/entitlement_formulas/cash_calculations.md

@@ -86,22 +86,17 @@ To scale the amount by a beneficiary field:
 | Field | Value |
 |-------|-------|
 | Amount | `100` |
-| Multiplier Field | `z_ind_grp_num_individuals` |
+| Multiplier Field | (select an integer field from the registrant model) |
 | Max Multiplier | `10` |
 
-**Result:** $100 per household member, maximum 10 members = $1,000 max.
+**Result:** $100 multiplied by the selected field value, maximum 10 = $1,000 max.
 
-### Common multiplier fields
+### How multiplier fields work
 
-| Field | Description |
-|-------|-------------|
-| `z_ind_grp_num_individuals` | Total household members |
-| `z_ind_grp_num_children` | Number of children |
-| `z_ind_grp_num_adults` | Number of adults |
-| `z_ind_grp_num_elderly` | Number of elderly members |
+The **Multiplier Field** dropdown shows all integer fields available on the registrant model (`res.partner`). Common examples include household member counts, but the specific fields available depend on your deployment's custom field configuration.
 
 ```{note}
-Field names depend on your registry configuration. Check your registrant model for available fields.
+If you don't see the fields you need in the dropdown, ask your administrator to create computed integer fields on the registrant model (e.g., via Studio or a custom module) that count household members by category.
 ```
 
 ## Maximum amount cap
@@ -139,7 +134,7 @@ Combine multiple items for complex calculations:
 | Field | Value |
 |-------|-------|
 | Amount | `50` |
-| Multiplier Field | `z_ind_grp_num_children_under_5` |
+| Multiplier Field | (select a field that counts children under 5) |
 | Max Multiplier | `5` |
 
 **Result for household with 3 children under 5:**

docs/config_guide/entitlement_formulas/dynamic_entitlements.md

@@ -30,28 +30,26 @@ Dynamic entitlements adjust benefit amounts based on beneficiary characteristics
 
 ### Using multiplier fields
 
-The simplest approach uses a multiplier field:
+The simplest approach uses a multiplier field — any integer field on the registrant model:
 
 | Field | Value |
 |-------|-------|
 | Amount | `100` |
-| Multiplier Field | `z_ind_grp_num_individuals` |
+| Multiplier Field | (select an integer field, e.g., household member count) |
 
 ```{figure} /_images/en-us/config_guide/entitlement_formulas/10-multiplier-field-configuration.png
 :alt: Multiplier field configuration in entitlement item
 
 Set the **Multiplier Field** to scale the amount by a beneficiary attribute.
 ```
 
-### Common multiplier fields
+### About multiplier fields
 
-| Field | Description | Typical use |
-|-------|-------------|-------------|
-| `z_ind_grp_num_individuals` | Total household members | Per-capita benefits |
-| `z_ind_grp_num_children` | Number of children | Child grants |
-| `z_ind_grp_num_children_under_5` | Children under 5 | Early childhood programs |
-| `z_ind_grp_num_adults` | Adult members | Labor programs |
-| `z_ind_grp_num_elderly` | Elderly members (60+) | Pension supplements |
+The **Multiplier Field** dropdown shows all integer fields available on the registrant model. Typical deployments create computed fields for member counts by category (e.g., total members, children, adults, elderly). The specific fields available depend on your deployment's configuration.
+
+```{note}
+If you don't see the fields you need, ask your administrator to create computed integer fields on the registrant model via Studio or a custom module.
+```
 
 ### Capping multipliers
 
@@ -60,7 +58,7 @@ Prevent excessive amounts with **Max Multiplier**:
 | Field | Value |
 |-------|-------|
 | Amount | `100` |
-| Multiplier Field | `z_ind_grp_num_individuals` |
+| Multiplier Field | (select household member count field) |
 | Max Multiplier | `8` |
 
 **Result:** Maximum 8 × $100 = $800, even for larger households
@@ -83,7 +81,7 @@ Combine multiple entitlement items for complex calculations:
 | Field | Value |
 |-------|-------|
 | Amount | `50` |
-| Multiplier Field | `z_ind_grp_num_children_under_5` |
+| Multiplier Field | (select children under 5 count field) |
 | Max Multiplier | `5` |
 
 **Result for household with 3 children under 5:**

docs/config_guide/entitlement_formulas/formula_library.md

@@ -37,37 +37,43 @@ Using a formula for documentation clarity:
 
 ### Per household member
 
-Amount scales with household size.
+Amount scales with household size. You can use either a multiplier field or a formula.
+
+**Using multiplier field:**
 
 | Field | Value |
 |-------|-------|
 | Amount | `100` |
-| Multiplier Field | `z_ind_grp_num_individuals` |
+| Multiplier Field | (select household member count field) |
 
-**Or using formula:**
+**Using formula (with CEL variables):**
 
 ```cel
-100 * me.z_ind_grp_num_individuals
+100 * household_size
 ```
 
 **Example:** 5-member household = $500
 
+```{note}
+The formula examples below use CEL variables like `household_size`, `adult_count`, `child_count`, `elderly_count`. These must be defined and activated in **Studio → Variables** before use. See the {doc}`/config_guide/variables/index` guide.
+```
+
 ### Per adult member
 
 ```cel
-base_amount * me.z_ind_grp_num_adults
+base_amount * adult_count
 ```
 
 ### Per child
 
 ```cel
-base_amount * me.z_ind_grp_num_children
+base_amount * child_count
 ```
 
 ### Per elderly member
 
 ```cel
-base_amount * me.z_ind_grp_num_elderly
+base_amount * elderly_count
 ```
 
 ## Capped calculations

docs/config_guide/graduation/criteria.md

@@ -0,0 +1,102 @@
+---
+openspp:
+  doc_status: draft
+  products: [core]
+---
+
+# Graduation criteria
+
+This guide is for **implementers** defining the conditions beneficiaries must meet for program graduation.
+
+## Criteria configuration
+
+Each criterion within a pathway has:
+
+| Field | What it means |
+|-------|---------------|
+| **Name** | Criterion label (e.g., "Income Threshold") |
+| **Pathway** | Which graduation pathway this belongs to |
+| **Weight** | Importance (default 1.0, higher = more important) |
+| **Assessment Method** | How the criterion is verified |
+| **Required** | Must be met for graduation (vs. optional) |
+
+### Assessment methods
+
+| Method | How it works | Best for |
+|--------|-------------|----------|
+| **Self-report** | Beneficiary provides information | Income, savings, livelihood status |
+| **Verification Required** | Third-party or document verification | Employment, bank account, asset ownership |
+| **Computed** | System calculates from data | Program attendance, payment history |
+| **Field Observation** | Case worker observes during visit | Housing quality, livelihood activity |
+
+### Pre-configured criteria examples
+
+| Criterion | Method | Weight | Description |
+|-----------|--------|--------|-------------|
+| Income threshold | Verification Required | 1.0 | Monthly income above poverty line |
+| Livelihood activity | Field Observation | 1.0 | Has active income-generating activity |
+| Savings account | Verification Required | 0.8 | Has functional savings account |
+| Training completion | Computed | 0.6 | Completed required training sessions |
+| Debt level | Self-report | 0.5 | Manageable debt-to-income ratio |
+
+## Setting up criteria
+
+### Step 1: Plan your graduation conditions
+
+Determine what beneficiaries must achieve:
+- Which criteria are mandatory vs. optional?
+- How will each criterion be verified?
+- What weights reflect your program's priorities?
+
+### Step 2: Create criteria
+
+1. Navigate to **Graduation > Graduation Criteria**
+2. Click **Create**
+3. Select the **Pathway**
+4. Set the **Name**, **Weight**, and **Assessment Method**
+5. Mark as **Required** if mandatory
+6. Save
+
+### Step 3: Run assessments
+
+1. Open a beneficiary's graduation assessment
+2. For each criterion, record whether it is met
+3. The system calculates an overall readiness score based on weights
+4. If all required criteria are met, the beneficiary is eligible for graduation
+
+## Monitoring duration
+
+After graduation, beneficiaries enter a monitoring period:
+
+| Setting | What it means |
+|---------|-------------|
+| **Monitoring Duration (months)** | How long to track post-graduation |
+
+During monitoring:
+- The system continues tracking the graduated beneficiary
+- If key indicators fall below thresholds, they can be flagged for re-enrollment
+- At the end of monitoring, the graduation is confirmed as final
+
+## Are You Stuck?
+
+**Criteria weights - how are they used?**
+
+Weights contribute to an overall graduation readiness score. A criterion with weight 1.0 has twice the impact of one with weight 0.5. The exact threshold for "ready to graduate" depends on your program policy.
+
+**Can I have different criteria for different pathways?**
+
+Yes. Each criterion is linked to a specific pathway. Standard Graduation might require 5 criteria while Early Graduation requires 3.
+
+**How do I handle computed criteria?**
+
+Computed criteria pull data from the system automatically (e.g., attendance records, payment history). The computation is based on existing program data.
+
+**Beneficiary meets criteria but supervisor disagrees?**
+
+If the pathway has **Approval Required** enabled, the supervisor can reject the graduation even if criteria are met, with a documented reason.
+
+## Next steps
+
+- {doc}`overview` - Graduation pathway fundamentals
+- {doc}`/config_guide/scoring/overview` - Use scoring models for graduation assessment
+- {doc}`/config_guide/session_tracking/overview` - Track training completion for criteria

docs/config_guide/graduation/index.md

@@ -0,0 +1,29 @@
+---
+openspp:
+  doc_status: draft
+  products: [core]
+---
+
+# Graduation
+
+This guide is for **implementers** configuring program exit pathways, graduation criteria, and assessment processes for time-bound social protection programs.
+
+## What you'll find here
+
+- **{doc}`overview`** - Graduation concepts, pathways, and navigation
+- **{doc}`criteria`** - Assessment criteria, weights, methods, and monitoring
+
+```{toctree}
+:hidden:
+:maxdepth: 1
+
+overview
+criteria
+```
+
+## Quick start
+
+1. Navigate to **Graduation > Graduation Pathways**
+2. Create **Pathways** for each exit type (e.g., Standard Graduation, Early Exit, Administrative Exit)
+3. Define **Criteria** for each pathway (e.g., income threshold, savings account)
+4. Configure assessment requirements and monitoring duration

docs/config_guide/graduation/overview.md

@@ -0,0 +1,109 @@
+---
+openspp:
+  doc_status: draft
+  products: [core]
+---
+
+# Graduation overview
+
+This guide is for **implementers** configuring program exit pathways in OpenSPP. You should understand your program's graduation policy but don't need programming knowledge.
+
+## Mental model
+
+Graduation in OpenSPP has three layers:
+
+| Layer | What it does | Example |
+|-------|--------------|---------|
+| **Pathway** | Defines the type of exit | "Standard Graduation" (positive), "Administrative Exit" (neutral) |
+| **Criteria** | Conditions that must be met | "Monthly income > $200", "Has savings account" |
+| **Assessment** | Individual evaluation against criteria | "Maria meets 4/5 criteria - ready for graduation" |
+
+Think of it like a school graduation: **pathways** are the degree programs (with honors, standard, early exit), **criteria** are the course requirements, and **assessments** are the final exams.
+
+## Key concepts
+
+### Graduation pathways
+
+| Field | What it means |
+|-------|---------------|
+| **Name** | Pathway label (e.g., "Standard Graduation") |
+| **Exit Type** | Positive or Negative |
+| **Assessment Required** | Whether formal assessment is needed before exit |
+| **Approval Required** | Whether graduation needs supervisor approval |
+| **Monitoring Duration** | Months of post-graduation monitoring |
+
+#### Exit types
+
+| Type | Meaning | Example |
+|------|---------|---------|
+| **Positive** | Beneficiary achieved program goals | Completed training, above poverty line |
+| **Negative** | Exit without achieving goals | Relocated, deceased, administrative removal |
+
+### Pre-configured pathways
+
+```{figure} /_images/en-us/config_guide/graduation/02-graduation-pathway-form.png
+:alt: Graduation pathway form showing criteria, assessment methods, and weights
+Graduation pathway form showing criteria, assessment methods, and weights.
+```
+
+OpenSPP includes three default pathways:
+
+| Pathway | Exit Type | Assessment | Approval |
+|---------|-----------|-----------|----------|
+| Standard Graduation | Positive | Yes | Yes |
+| Early Graduation | Positive | Yes | Yes |
+| Administrative Exit | Negative | No | No |
+
+## Navigation
+
+| Menu | Purpose |
+|------|---------|
+| **Graduation > Graduation Pathways** | Define exit pathways |
+| **Graduation > Graduation Criteria** | Configure assessment criteria |
+| **Graduation > Assessments** | View individual assessments |
+
+```{figure} /_images/en-us/config_guide/graduation/01-graduation-pathways-list.png
+:alt: Graduation pathways list showing exit type and assessment requirements
+Graduation pathways list showing exit type and assessment requirements.
+```
+
+## Common use cases
+
+### Use case 1: Poverty graduation program
+
+**Goal:** Graduate beneficiaries who achieve economic self-sufficiency.
+
+**Setup:**
+1. Use the "Standard Graduation" pathway
+2. Set criteria: income threshold, savings, livelihood activity
+3. Require assessment and supervisor approval
+4. Set 6-month post-graduation monitoring
+
+### Use case 2: Emergency program exit
+
+**Goal:** Administrative exit when emergency response concludes.
+
+**Setup:**
+1. Use the "Administrative Exit" pathway
+2. No assessment or approval required
+3. Set 0 months monitoring
+4. Bulk-process exits for all remaining beneficiaries
+
+## Are You Stuck?
+
+**Where do I configure graduation?**
+
+Navigate to **Graduation** in the main menu. If you don't see it, ask your administrator to install the **Graduation** module.
+
+**What happens during post-graduation monitoring?**
+
+The system tracks graduated beneficiaries for the configured duration. This allows re-enrollment if they fall back below thresholds.
+
+**Can I customize the default pathways?**
+
+Yes. Edit or create new pathways to match your program's exit policies.
+
+## Next steps
+
+- {doc}`criteria` - Configure assessment criteria
+- {doc}`/config_guide/eligibility/index` - Connect graduation to eligibility rules

docs/config_guide/scoring/index.md

@@ -1,5 +1,4 @@
 ---
-orphan: true
 openspp:
   doc_status: draft
   products: [core]