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

# Platform Documents

> Searchable, filterable document library for viewing, uploading, and managing documents; full per-document management with versions, approvals, and permissions.

The Documents library (`/documents`) is the central repository for all organisation documents, providing search, category and status filtering, bulk actions, and document upload.

## Overview

No permission gate is present on the `/documents` route itself — access control is handled at the document level. The page provides a search input, category filter (policy, procedure, form template, training material, report, legal, marketing, other), status filter, and a sort order selector via `DocumentSortOptions`. View mode can be toggled between grid and list. Documents are fetched via `useDocumentSearch` with debounced search. Each document card links to `/documents/:id`. Bulk actions are available via `DocumentBulkActionToolbar` when documents are checked. Uploading a document opens `DocumentUploadDialog`. Deleting a document triggers an `AlertDialog` confirmation before calling `useDocumentMutation`.

## Who it's for

Access follows your organization's role and module configuration.

## Before you start

* Ensure your organisation has documents uploaded, or upload your first document using the **Upload** button.

## Steps

<Steps>
  <Step title="Open Documents">
    Navigate to `/documents`. The library loads with all documents accessible to your account.
  </Step>

  <Step title="Search for a document">
    Type in the search box to filter documents by name. Search is debounced.
  </Step>

  <Step title="Filter by category or status">
    Use the Category and Status selectors to narrow results. Combine filters with search.
  </Step>

  <Step title="Toggle view mode">
    Click the grid or list icon to switch between card grid and list views.
  </Step>

  <Step title="Open a document">
    Click a document card to navigate to `/documents/:id` for full details and actions.
  </Step>

  <Step title="Upload a document">
    Click **Upload** to open `DocumentUploadDialog` and attach a new document file.
  </Step>

  <Step title="Bulk-select and act">
    Check multiple documents to activate `DocumentBulkActionToolbar` for bulk operations.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Document categories">
    Categories include `policy`, `procedure`, `form_template`, `training_material`, `report`, `legal`, `marketing`, and `other`. These are sourced from the Supabase `document_category` enum.
  </Accordion>

  <Accordion title="Document sort and search">
    `useDocumentSearch` accepts `SortField` and `SortDirection` parameters from `DocumentSortOptions`, in addition to search query and filter criteria.
  </Accordion>
</AccordionGroup>

## Viewing a document

The Document Details page (`/documents/:id`) provides a full management interface for a single document, including its metadata, file versions, approval workflow, permissions, and a document preview. Access control depends on document-level permissions managed via `PermissionsManager`.

The page loads the document via `useDocumentDetail` with the `:id` parameter, and fetches versions via `useDocumentVersions`. It uses `useDocumentDownload` for file downloads and `useDocumentMutation` for status changes. The UI is tabbed with sections for the document preview (`DocumentPreview`), approval workflow (`ApprovalTimeline`, `ApprovalWorkflowSetup`), and permissions (`PermissionsManager`). Users can upload a new version via `UploadVersionDialog` and change the document status via a `Select` control. Approval decisions are handled via `DocumentApprovalDecisionDialog`. Status badge colours correspond to the current `DocumentStatus` enum value.

<Steps>
  <Step title="Open a document">
    From `/documents`, click a document to navigate to `/documents/:id`.
  </Step>

  <Step title="Preview the document">
    The default view shows the document preview rendered by `DocumentPreview`.
  </Step>

  <Step title="Change document status">
    Use the status `Select` control in the header to change the document's lifecycle status (e.g., from `draft` to `in_review`).
  </Step>

  <Step title="Upload a new version">
    Click the upload action to open `UploadVersionDialog` and attach a new file version.
  </Step>

  <Step title="Manage approvals">
    Switch to the Approvals tab to view the `ApprovalTimeline` and configure steps via `ApprovalWorkflowSetup`. Use `DocumentApprovalDecisionDialog` to approve or reject.
  </Step>

  <Step title="Manage permissions">
    Switch to the Permissions tab to use `PermissionsManager` to control who can view or edit the document.
  </Step>

  <Step title="Download the document">
    Click the download action to trigger `useDocumentDownload` and retrieve the file.
  </Step>
</Steps>

**Document status lifecycle** — Statuses include `draft`, `in_review`, `pending_approval`, `approved`, `rejected`, `published`, and `archived`. Each has a distinct badge colour defined in `STATUS_COLORS`.

**Version management** — Document versions are tracked separately from the base document record. Each upload creates a new version entry.

## Related

<Columns cols={2}>
  <Card title="Platform Foundation" icon="layer-group" href="/pf/overview">
    Platform Foundation 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/platform.tsx
  * src/platform/documents/DocumentLibrary.tsx
  * src/platform/documents/useDocumentSearch.ts
  * src/platform/documents/DocumentDetailPage.tsx
  * src/platform/documents/useDocumentDetail.ts
  * src/platform/documents/hooks/useApprovalWorkflow\.ts
</Accordion>