> ## Documentation Index
> Fetch the complete documentation index at: https://village-docs.villagelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PlanRules Guide

> A deep dive into the PlanRules object, the legal framework of your ESOP.

## Overview

The `PlanRules` object is where you define the stable, legal framework of your ESOP, as specified in your plan document. These rules change infrequently and typically require a formal plan amendment.

Getting the `PlanRules` right is the first and most important step in accurately modeling your ESOP.

<Info>
  **Source of Truth:** Your ESOP's Plan Document.
</Info>

## Complete Field Reference

Below is a detailed walkthrough of each field in the `PlanRules` object.

### `plan_name`

* **Type:** `string`
* **Required:** Yes
* **Description:** The official name of your ESOP plan.
* **Example:** `"Acme Corp Employee Stock Ownership Plan"`

### `plan_year_end`

* **Type:** `string` (MM/DD format)
* **Required:** Yes
* **Description:** The end date of your plan year. This is a critical field that affects the timing of many calculations.
* **Example:** `"12/31"`

### `vesting_schedule`

* **Type:** `object`
* **Required:** Yes
* **Description:** Defines how participants earn ownership of their ESOP shares over time.

<AccordionGroup>
  <Accordion title="`type`">
    - **Type:** `string`
    - **Values:** `"graded"`, `"cliff"`
    - **Description:** The type of vesting schedule. "Graded" vesting increases gradually over time, while "cliff" vesting happens all at once.
  </Accordion>

  <Accordion title="`schedule`">
    * **Type:** `array` of numbers
    * **Description:** Required for `graded` vesting. An array representing the percentage of shares vested at each year of service.
    * **Example:** `[0, 0, 20, 40, 60, 80, 100]` for a 6-year graded schedule where vesting begins after 2 years.
    * **Validation:** Must start at 0, end at 100, and be monotonically increasing.
  </Accordion>

  <Accordion title="`years_to_full_vesting`">
    * **Type:** `integer`
    * **Description:** Required for `cliff` vesting. The number of years of service required to become 100% vested.
    * **Example:** `3` for a 3-year cliff.
  </Accordion>
</AccordionGroup>

### `distribution_policy`

* **Type:** `object`
* **Required:** Yes
* **Description:** Defines when and how participants receive their vested account balances after termination.

<AccordionGroup>
  <Accordion title="`timing`">
    - **Type:** `string`
    - **Values:** `"immediate"`, `"termination_plus_1_year"`, etc.
    - **Description:** When distributions begin after a termination event.
  </Accordion>

  <Accordion title="`form`">
    * **Type:** `string`
    * **Values:** `"lump_sum"`, `"installments"`
    * **Description:** How distributions are paid out.
  </Accordion>
</AccordionGroup>

### `cash_usage_policy`

* **Type:** `array` of strings
* **Required:** No
* **Description:** The priority order for using different sources of cash within the trust to fund distributions and repurchases.
* **Example:** `["unallocated_company_contributions", "unallocated_forfeiture_cash", "participant_cash_accounts"]`

### `diversification_rules`

* **Type:** `object`
* **Required:** No
* **Description:** Defines the rules for statutory diversification. The engine can model this automatically if this section is included.

## Complete Example

```json theme={null}
{
  "plan_name": "Acme Corp ESOP",
  "plan_year_end": "12/31",
  "vesting_schedule": {
    "type": "graded",
    "schedule": [0, 0, 20, 40, 60, 80, 100]
  },
  "distribution_policy": {
    "timing": "termination_plus_1_year",
    "form": "lump_sum"
  },
  "cash_usage_policy": [
    "unallocated_company_contributions",
    "unallocated_forfeiture_cash",
    "participant_cash_accounts"
  ],
  "diversification_rules": {
    "min_age": 55,
    "min_service": 10
  }
}
```