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

# Phase 2b Authoring Guide

> How to author code-grounded, SME-gated Product docs from the gap backlog.

How to turn a gap-backlog route into an accurate, on-brand, SME-signed Product page.

<Note>
  Source of truth is shipped code in `src/`. Never invent clinical, compliance,
  or billing behavior. If behavior is not unambiguous from code, leave a
  specific `SME REVIEW` warning — do not guess. The `phase2b: true` frontmatter
  marker is **permanent**: it must never be removed to bypass the sign-off gate.
  Removing it is a policy violation and is detectable in git history.
</Note>

## The pipeline

<Steps>
  <Step title="Scaffold">
    Run `npm run docs:gapfill --core=<core> --limit=<n>` to create safe
    Draft/hidden stubs in the holding nav group.
  </Step>

  <Step title="Draft from code">
    For each stub, resolve its route via `src/platform/navigation/route-labels.ts`
    to the screen component in `src/`. Read the component and the feature module
    it calls. Fill the template using ONLY observable behavior. Record every
    `src/` file you used in the "Documentation sources" accordion.
  </Step>

  <Step title="Flag ambiguity">
    Anything not unambiguous from code stays a specific `<Warning>` SME-review
    callout naming the open question.
  </Step>

  <Step title="Gate">
    Run `npm run docs:authoring-status -- --check`. It must pass: every
    Phase 2b page is `tag: "Draft"` + `hidden: true` with citations until signed.
  </Step>

  <Step title="Sign-off">
    Owner verifies the page against the product, adds its path to
    `scripts/docs/phase2b-signoff.yaml`, then removes `tag: "Draft"` and
    `hidden: true` so it goes live. The `phase2b: true` marker stays. Re-run
    `npm run docs:parity-audit`.
  </Step>
</Steps>

## Canonical page template

Copy this exactly. It is the only approved structure; the spacing is
part of the contract — see [MDX safety](#mdx-safety-build-breaking).

```mdx theme={null}
---
title: "<Screen Label>"
description: "<one factual sentence, <=155 chars, no spec numbers>"
icon: "<font-awesome-free icon>"
tag: "Draft"
audience: "<user|admin>"
phase2b: true
hidden: true
---

<One sentence: what this screen is + the in-app route `<route>`>.

<Warning>
  SME REVIEW REQUIRED — drafted from shipped code, pending verification. Do not
  rely on this for clinical, billing, payroll, or compliance decisions.
  Route: `<route>`.
  <One "SME: confirm ..." bullet per item not determinable from code.>
</Warning>

## Overview

<2-5 sentences, observable UI/workflow only>

## Who it's for

<the exact RequirePermission string from the route file, or
"Access follows your organization's role and module configuration. ">

## Before you start

<preconditions visible in code, else just the permission>

## Steps

<Steps>
  <Step title="<real action>"><from JSX></Step>
</Steps>

## Key concepts

<only terms literally in code/UI; omit the section if nothing concrete>

## Related

<Columns cols={2}>
  <Card title="<Core>" icon="<icon>" href="/<core>/<CORE_OVERVIEW>">
    <Core> core overview.
  </Card>
  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

import PhiDisclaimer from "/snippets/phi-disclaimer.mdx";

<PhiDisclaimer />

<Accordion title="Documentation sources">
- src/routes/<core>.tsx
- src/<every file you actually opened>.<ext>
</Accordion>
```

### Frontmatter rules

* Seven keys, in the order shown. `title` double-quoted; `description`
  155 chars or fewer, no spec numbers (`PM-13`, `(PF-51)`).
* `audience` is **authoritative** — it drives the sidebar split (User
  Guides / Admin Guides / Reference & Overview) via `docs:nav-regroup`.
  Use `"admin"` for settings/config/rules/templates/policies/wizard/
  setup/admin/import/permissions screens; else `"user"`.
* `tag: "Draft"` + `hidden: true` are removed **only** at sign-off.
  `phase2b: true` is **permanent** — never remove it to bypass the gate
  (detectable in git history; a policy violation).

## MDX safety (build-breaking)

Mintlify compiles every `.md` page as **MDX**. A compile failure makes
the page silently vanish from the build and surfaces as "referenced in
docs.json but file does not exist". Non-negotiable:

1. **Blank line after every `import`.** `import PhiDisclaimer ...;` MUST
   be followed by a blank line before `<PhiDisclaimer />`. With no blank
   line MDX parses the JSX as a JS statement and the whole page fails
   (`Unexpected ExpressionStatement ... only import/exports are
   supported`). This one mistake broke 310 pages once.
2. **No raw `<` or `{` in prose.** `<` before a digit/space/punctuation
   (`(<25%)`, `value < 0`) reads as a malformed JSX tag. Use `&lt;`,
   reword ("below 25%"), or wrap in `` `code` ``. Same for `{`.
3. **No body `#` H1.** Mintlify renders the frontmatter `title` as the
   page hero; a body H1 duplicates it. The body starts at the intro line.
4. Self-closing components keep the space: `<PhiDisclaimer />`.

## Citations the gate parses

The "Documentation sources" accordion must contain **bare repo-relative
paths**, one per line — the gate regex is `^src/\S+\.\w+$`:

```
<Accordion title="Documentation sources">
- src/routes/cl.tsx
- src/cores/cl/pages/FooPage.tsx
</Accordion>
```

Prose-wrapped lines (`- Component: \`src/Foo.tsx\``,
`- src/Foo.tsx (line 42)`) do **not** count; a live page with zero
parsed citations is a gate violation. Always include the route file plus
every `src/\` file you actually opened.

## Sign-off transform (owner-gated)

A page goes live only after the owner verifies it against the running
product: remove the `<Warning>` SME block; delete the `tag: "Draft"` and
`hidden: true` frontmatter lines (keep `phase2b: true` and `audience:`);
add the path to `scripts/docs/phase2b-signoff.yaml`; scrub any residual
literal `SME REVIEW` left in body prose; re-run
`docs:authoring-status -- --check` (0 violations) and `docs:parity-audit`.
Reviewers cross-check against the relevant `specs/<core>` user story at
review time — specs are review input only, never cited in the page.

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

## Related

<Columns cols={2}>
  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Where the gap backlog and parity audit governance lives.
  </Card>

  <Card title="AI platform parity" icon="robot" href="/development/AI_PLATFORM_PARITY">
    Platform parity context for documentation coverage.
  </Card>
</Columns>