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

# Policy Library

> Browse and create organizational policies — searchable list, 4-step creation wizard, and tabbed detail for versions and acknowledgments.

The Policy Library page (`/gr/policies`) renders `PolicyLibrary`, the central browsing and management surface for all `gr_policies` records in the organization.

## Overview

`PolicyLibrary` calls `usePolicyList({ filters })` with pagination. It provides:

* **Search** — text input for policy title search (deferred value pattern for performance).
* **Filters** — category and status selects derived from `PolicyListFilters`.
* **View toggle** — grid (`LayoutGrid`) and list (`List`) view modes.
* **Pagination** — sliding-window page number navigation.
* **Create policy** — opens `PolicyCreationWizardDialog` (4-step wizard); visible to users with the appropriate permission checked inside `PolicyLibrary` using `useHasPermission(GR_PERMISSIONS...)`.
* **Guided tour** — `policyManagementTour` launched via `useTour`; starts automatically if `?tour=policy-management-tour` is in the URL.

Each policy card renders via `PolicyCard`. Clicking a card navigates to `/gr/policies/:id`.

## Who it's for

Access follows your organization's role and module configuration. Any authenticated user can browse the policy library. The create action inside the page is conditionally rendered based on the user's permissions.

## Before you start

* No special permission is required to browse policies.
* To create a policy, the appropriate GR admin permission is required (checked within the component).

## Finding a policy

1. Navigate to `/gr/policies`. The library loads with the first page of policies.
2. Type in the search box to filter policies by title. The list updates with a deferred search.
3. Use the Category and Status selects to narrow the list.
4. Click the grid or list icon to toggle between card grid and tabular list views.
5. Click a `PolicyCard` to navigate to `/gr/policies/:id` for full detail.
6. Append `?tour=policy-management-tour` to the URL or click the help button to start the guided tour.

**usePolicyList** — hook with pagination and filter support for `gr_policies` records.

**PolicyListFilters** — typed filter object with `category`, `status`, `review_due`, and other fields.

**Sliding-window pagination** — `getPageNumbers` helper that generates page numbers with ellipsis around the current page.

## Viewing a policy

The Policy Details page (`/gr/policies/:id`) renders `PolicyDetail`, a tabbed view for a single `gr_policies` record with full lifecycle management capabilities for authorized users.

`PolicyDetail` loads a policy via `usePolicyDetail(id)` and renders four tabs:

| Tab                 | Content                                                                                                                                   |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Overview**        | Policy metadata: title, category, status badge, owner, approved-by, site, description                                                     |
| **Versions**        | `PolicyVersionHistory` — version list with download support                                                                               |
| **Acknowledgments** | `PolicyAcknowledgmentTable` — admin view of all assignments for this policy (loaded via `usePolicyAcknowledgmentList` in `mode: 'admin'`) |
| **Assignments**     | `PolicyAssignmentList` + `PolicyAssignmentDialog` — role/group assignments                                                                |

Header actions (conditionally rendered by permission):

* **Approve** — available to users with `gr.policies.approve` (`canApprove`); calls `updatePolicy` to set status to approved.
* **Deprecate** — available to users with `gr.policies.deprecate` (`canDeprecate`); calls `deprecatePolicy`.
* **Edit** — opens `PolicyFormDialog`.
* **New Version** — opens `PolicyVersionDialog`.
* **Assign** — opens `PolicyAssignmentDialog`.

The active tab syncs to the URL via `useTabUrlState` (`?tab=`).

Viewing a policy detail requires only authentication and organization membership. Specific actions within the page require `gr.policies.approve`, `gr.policies.deprecate`, or admin-level permissions.

1. Navigate to `/gr/policies/:id`. The overview tab is displayed by default.
2. Read the policy metadata: category badge, status badge, owner, approved-by, site association, and description.
3. Click the **Versions** tab to see all `gr_policy_versions` records. Documents can be downloaded.
4. Click **Acknowledgments** to see the admin view of all policy acknowledgment assignments and their completion status.
5. Click **Assignments** to see and modify which roles or groups are assigned to acknowledge this policy.
6. If you hold `gr.policies.approve`, click **Approve** to mark the policy approved. If you hold `gr.policies.deprecate`, click **Deprecate**.

**gr.policies.approve / gr.policies.deprecate** — permissions gating the approve and deprecate header actions.

**useTabUrlState** — syncs the active tab to `?tab=` in the URL.

## Creating a policy

Policy creation is performed via `PolicyCreationWizardDialog`, a dialog-based 4-step wizard launched from this page. There is no standalone `/gr/policies/new` route.

`PolicyCreationWizardDialog` is a `DialogWizardShell`-based 4-step wizard:

| Step | ID          | Description                                     |
| ---- | ----------- | ----------------------------------------------- |
| 1    | `details`   | Title, category, owner (4 fields)               |
| 2    | `document`  | Attach policy file (1 field)                    |
| 3    | `lifecycle` | Review schedule and regulatory links (3 fields) |
| 4    | `review`    | Confirm and create                              |

Wizard events are tracked with template ID `'gr-policy-creation-wizard'`.

Before you start: navigate to `/gr/policies` and locate the create policy action. Have the policy title, category, owner, relevant document file, and intended review schedule ready.

1. Navigate to `/gr/policies`. Click the action to create a new policy. The `PolicyCreationWizardDialog` opens.
2. **Step 1 — Policy Details:** enter the policy title, select a category, and assign an owner.
3. **Step 2 — Document:** attach the policy document file.
4. **Step 3 — Lifecycle:** set the review schedule and any regulatory links.
5. **Step 4 — Review and create:** review the entered information. Click submit to create the policy. You will be navigated to the new policy's detail page.

**DialogWizardShell** — platform dialog component that manages step navigation within a modal.

**STEP\_DEFS** — static step configuration array in `PolicyCreationWizardDialog` defining step IDs, titles, descriptions, and icons.

**GrPolicyWizardFormData** — typed form data structure for the creation wizard.

**PolicyCreationWizardDialog** — 4-step dialog wizard launched from this page for new policy creation.

## Related

<Columns cols={2}>
  <Card title="Governance & Compliance" icon="scale-balanced" href="/gr/overview">
    Governance & Compliance core overview.
  </Card>

  <Card title="Governance & parity" icon="clipboard-check" href="/governance/index" />
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/gr.tsx
  * src/cores/gr/pages/PolicyLibrary.tsx
  * src/cores/gr/pages/PolicyDetail.tsx
  * src/cores/gr/hooks/usePolicyList.ts
  * src/cores/gr/hooks/usePolicyDetail.ts
  * src/cores/gr/hooks/usePolicyAcknowledgmentList.ts
  * src/cores/gr/wizards/policy-creation/PolicyCreationWizardDialog.tsx
</Accordion>