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

# Template Settings

> Manage letterheads, document templates, and approval chain templates for professional PDF output; create and edit each template type.

The Template Settings page provides a tabbed interface for managing all document-related templates: letterheads, document templates, approval chain templates, and starter templates. It is reached at `/settings/templates`.

## Overview

The page is wrapped in `RequirePermission` for `pf.templates.view`. It uses a tab-based layout with the active tab synced to the `?tab=` query parameter. The four tabs are:

* **Letterheads** — manage organization letterheads with logo and branding (`LetterheadListPage`).
* **Documents** — manage document templates with rich-text editing (`DocumentTemplateListPage`). Linked sub-routes: `/settings/templates/documents/new`, `/settings/templates/documents/:id`.
* **Approvals** — manage approval chain templates (`ApprovalChainTemplateListPage`). Linked sub-routes: `/settings/templates/approvals/new`, `/settings/templates/approvals/:id`.
* **Starter** — browse pre-built starter templates (`StarterTemplatesBrowser`).

## Who it's for

Requires `pf.templates.view` (route guard via `RequirePermission`).

## Before you start

* No prerequisites for viewing. Content appears immediately on load.
* Creating or editing templates may require additional permissions.

## Steps

1. Navigate to **Settings → Templates** (`/settings/templates`).
2. Select the appropriate tab: **Letterheads**, **Documents**, **Approvals**, or **Starter**.
3. Use the **New** button within each tab to create a template.
4. Edit or delete existing templates using the actions on each card.

## Key concepts

**Letterhead** — branded page header/footer layout used in PDF output, including logo, address, and color scheme.

**Document template** — rich-text template with variable insertion points for generating populated PDFs.

**Approval chain template** — a configured sequence of approvers for use in approval workflows.

## Creating or editing a letterhead

The Letterhead editor (`/settings/templates/letterheads/new` and `/settings/templates/letterheads/:id`) renders `LetterheadEditor`, which handles both new and edit modes.

Fields include name, description, organization name display, full mailing address, phone, email, and website. A `LogoUpload` component handles logo uploads with configurable position (`left`, `center`, `right`) and max-height. Header configuration controls visibility of logo, org name, address, and contact info, plus a custom bar color. Footer configuration controls page numbers, confidentiality notice text, and its display. A live `LetterheadPreview` shows the result. The editor uses `useLetterheadMutation()` for save operations.

1. Navigate to **Settings > Templates > Letterheads** and select **New**, or click an existing letterhead to edit.
2. Enter a **Name** and optional description.
3. Fill in the organization details (name, address, phone, email, website).
4. Upload a logo and set its position and maximum height.
5. Configure header and footer display options.
6. Review the live preview and save.

**Header config** — Controls which elements appear in the document header: logo, org name, address, and contact info. The `barColor` field sets the accent bar color.

**Footer config** — Controls page number display and the confidentiality notice text shown at the bottom of each page.

## Creating or editing a document template

The Document Template editor (`/settings/templates/documents/new` and `/settings/templates/documents/:id`) renders `DocumentTemplateEditor`, which handles both new and edit modes.

Templates have a name, description, type (`policy`, `procedure`, `letter`, `report_cover`, `other`), status (`draft`, `active`, `deprecated`), and an optional letterhead assignment from `useOrgLetterheads()`. The template body is composed of sections via `SectionEditor`. An AI-assisted `SectionSuggester` can propose additional sections. Version history is accessible via `DocumentTemplateVersionDiff`. A PDF preview can be generated via `useGenerateTemplatedPdf()`.

1. Navigate to **Settings > Templates > Documents** and select **New**, or click an existing template to edit.
2. Enter a **Name** and optional **Description**.
3. Select a **Type** and **Status**.
4. Optionally assign a **Letterhead**.
5. Add and order sections using the section editor. Use the AI suggester if enabled.
6. Preview the PDF output if needed.
7. Save the template.

**Template status** — `draft` templates are not available for document generation; `active` templates are available; `deprecated` templates are hidden from new use but preserved for existing documents.

**Sections** — Ordered content blocks that define the structure of generated documents. Each section has a name and editable body.

## Creating or editing an approval template

The Approval Chain Template editor (`/settings/templates/approvals/new` and `/settings/templates/approvals/:id`) renders `ApprovalChainTemplateEditor`, which handles both new and edit modes.

The page uses `react-hook-form` with Zod validation (`approvalChainSchema`). The form collects `name`, `description`, `category` (policy, document, financial, hr, compliance, general), and a `steps` array. Each step has a `step_order`, `name`, `approver_type` (user, role, dynamic, field), `approver_config`, `parallel_mode` (any/all), `timeout_hours`, and `reminder_hours`. Steps are managed via `ApprovalStepEditor`. At least one step is required. A back button navigates to `/settings/templates`.

1. Navigate to **Settings > Templates > Approvals** and select **New**, or click an existing template to edit.
2. Enter a name (required, max 200 characters) and optional description (max 1000 characters).
3. Select a **Category** from: policy, document, financial, hr, compliance, or general.
4. Add at least one approval step using `ApprovalStepEditor`. For each step, set the name, approver type, approver config, parallel mode, timeout hours, and reminder hours.
5. Click **Save**. Validation errors are shown inline.

<AccordionGroup>
  <Accordion title="Approver types">
    `user` requires a specific `user_id`. `role` requires a `role` string. `dynamic` uses a `resolver` enum (`manager` or `department_head`). `field` uses a `field` string to resolve the approver at runtime.
  </Accordion>

  <Accordion title="Parallel mode">
    `any` means only one approver in the step needs to approve. `all` requires every approver to approve before the chain advances.
  </Accordion>

  <Accordion title="Timeout and reminder">
    `timeout_hours` sets when the step escalates or fails if no approval is given. `reminder_hours` sets how many hours before the timeout to send a reminder notification.
  </Accordion>
</AccordionGroup>

## 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/templates/pages/TemplatesSettingsPage.tsx
  * src/platform/templates/pages/LetterheadListPage.tsx
  * src/platform/templates/pages/LetterheadEditor.tsx
  * src/platform/templates/pages/DocumentTemplateEditor.tsx
  * src/platform/templates/pages/ApprovalChainTemplateEditor.tsx
  * src/platform/templates/hooks/index.ts
</Accordion>