> ## 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.

# Benefits Guides

> Upload and manage benefits guide documents (admin) or browse guides as an employee.

Benefits Guides has two routes: the admin view at `/hr/benefits/guides` (requires `hr.benefits.admin`) and the employee self-service view at `/hr/my-benefits/guides` (no explicit permission gate). Alternate route: `/hr/my-benefits/guides`.

## Overview

**Admin view** (`BenefitsGuidesAdminPage` at `/hr/benefits/guides`): HR admins can upload new guide PDFs using `BenefitsGuideUploader`, associating them with optional enrollment periods. Uploaded guides are shown as `BenefitsGuideCard` components in a grid. Admins can preview a guide in a PDF viewer dialog, toggle its active/inactive status, or delete it (with confirmation dialog). Deletion removes the file from storage and the record.

**Employee view** (`BenefitsGuidesPage` at `/hr/my-benefits/guides`): Employees browse only active guides. No upload or admin actions are available.

## Who it's for

* `/hr/benefits/guides` — `hr.benefits.admin` (HR benefits administrators)
* `/hr/my-benefits/guides` — Access follows your organization's role and module configuration. (employee self-service)

## Before you start

* Admin: `hr.benefits.admin` permission required to manage guides.
* Both: guides must exist in the system for the list to be non-empty.

## Steps

<Steps>
  <Step title="Open Benefits Guides (admin)">Navigate to `/hr/benefits/guides`.</Step>
  <Step title="Upload a guide">Use the `BenefitsGuideUploader` to select a PDF, set a title, and optionally link to an enrollment period.</Step>
  <Step title="Preview a guide">Click the view action on a guide card to open the PDF viewer dialog.</Step>
  <Step title="Toggle or delete">Use guide card actions to activate/deactivate or delete a guide.</Step>
  <Step title="Employee access">Employees navigate to `/hr/my-benefits/guides` to browse active guides.</Step>
</Steps>

## Key concepts

| Term                    | Meaning in code                                                                               |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| `BenefitsGuide`         | Guide record with `id`, `title`, `storage_path`, `is_active`, optional enrollment period link |
| `BenefitsGuideUploader` | Upload component accepting PDF files                                                          |
| `is_active`             | Flag controlling employee visibility of the guide                                             |

## Related

<Columns cols={2}>
  <Card title="Human Resources" icon="users" href="/hr/overview">
    Human Resources core overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</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/hr.tsx
  * src/routes/hr/benefits-routes.tsx
  * src/cores/hr/benefits/pages/admin/BenefitsGuidesAdminPage.tsx
  * src/cores/hr/benefits/hooks/useBenefitsGuides.ts
</Accordion>