> ## 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. # Mintlify Setup & Conventions > Single source of truth for the Mintlify docs site at docs/. Conventions, components, MCP usage, deploy, and the live coverage page. **Last curated:** *set by the encore-mintlify-curator skill* Single source of truth for the Mintlify docs site at `docs/`. Everything in this document is binding; if you change the conventions, update this file in the same PR. > If documents conflict, `constitution.md` wins. *** ## 1. Local development ```bash theme={null} npm run docs:dev # = cd docs && mint dev — serves the site at http://localhost:3000 ``` Hot-reload triggers on `*.md`, `*.mdx`, and `docs.json` edits. The Mintlify CLI is bundled — no separate `npm install mintlify` is needed. To debug a single page without booting the full site, copy the page into `docs/_drafts/.mdx` (gitignored via `.mintignore`) and navigate to `http://localhost:3000/_drafts/`. If `mint dev` fails with a node-version error, check `.nvmrc` (currently `24`). *** ## 2. `docs.json` shape The `docs.json` schema is `https://mintlify.com/docs.json` (line 1 of the file). Top-level keys we use: | Key | Purpose | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `theme` | Set to `mint` | | `name` | `Encore OS` | | `logo`, `favicon` | SVG paths under `docs/logo/` | | `colors` | `primary: #101F41`, `light: #26B2F2`, `dark: #0A7DB2` — change these here, not in any other token file | | `appearance.default` | `system` | | `contextual.options` | Mintlify v2 AI menu — exposes Copy / View as Markdown / Open in ChatGPT / Open in Claude buttons on every page | | `banner` | Site-wide alpha-state banner with `content` (markdown) + `dismissible: true` | | `integrations.mcp.enabled` | `true` — publishes an MCP endpoint at `docs.encoreos.io/.well-known/mcp.json` so AI agents can query the docs as a tool | | `footer` | `socials` + `links` (Company / Compliance / Developers columns) rendered site-wide | | `navigation.tabs` | Top-level tab list (Product, Engineering, Changelog, Operations) | | `search.prompt` | Placeholder text in the search input | | `redirects` | Source → destination mappings; immutable URL contract for legacy paths | | `seo.metatags` + `seo.indexing` | Open Graph / Twitter Card metadata; `navigable` = crawlable but not 3rd-party-indexed beyond Mintlify-native AI | Each tab has a `groups` array. Each group has a `group` label, an optional `icon`, and a `pages` array. Pages can be either: * A bare string referencing a `.md` or `.mdx` file (without extension): `"cl/note-templates"` * A nested group object: `{ "group": "Charting & Documentation", "icon": "notes-medical", "pages": [...] }` **`expanded: false`** is the default for nested groups (the user clicks to expand). Set `expanded: true` only for the user's primary landing-page group inside a tab. **Icons** come from Font Awesome free names. The full mapping policy lives in scripts/docs/icon-rules.yaml. *** ## 3. Frontmatter contract Every published page MUST have: ```yaml theme={null} --- title: A short, sentence-case title description: One sentence describing what the page covers. --- ``` Strongly recommended: ```yaml theme={null} audience: user | admin | dev # drives audience-aware nav slotting core: cl | pm | fa | hr | … # the core that owns this page icon: file-lines # Font Awesome free name spec: CL-15 # spec traceability (non-rendered); REQUIRED when the page documents a spec noindex: true # REQUIRED on Engineering/Reference-tab pages (internal surface, kept out of search engines) ``` Validated by `npm run docs:check-frontmatter`. The curator skill (`encore-mintlify-curator`) runs this on every sweep. The `description` is rendered in search results and below the title — keep it under \~120 chars and avoid duplicating the `title`. **No spec IDs in human-visible text:** `title`, `sidebarTitle`, `description`, and the first H1 of Product/Guides/Trust-tab pages must not contain spec IDs (`CL-15`, `HR-09-P5-4`, …) — that's what the `spec:` field is for. Engineering/Reference tabs are exempt. See `docs/DOCUMENTATION_STANDARDS.md` § Editorial Rules for Published Pages. Enforced by `docs:check-frontmatter` (blocking) and healed by the `denumber` curator sweep. **Redirects are born permanent:** when a cleanup/restructure retires a path, add its `docs.json` redirect with `"permanent": true` (301). Only genuinely transitional redirects (an A/B move you expect to revert) stay temporary. *** ## 4. Naming conventions | Pattern | Use | | ---------------------- | -------------------------------------------------------------------------------- | | `*-user-guide.md` | End-user task-oriented guides | | `*-admin-guide.md` | Tenant-admin / operator guides | | `*-API-REFERENCE.md` | Developer API reference (capitalized to match `docs/DOCUMENTATION_STANDARDS.md`) | | `*-MODULE-SETTINGS.md` | Module settings reference | | `index.md` | Mintlify nav landing page | | `README.md` | Non-published directory readme (never appears in nav) | Files use kebab-case with the exception of the all-caps `*-API-REFERENCE.md` and `*-MODULE-SETTINGS.md` suffixes. The Phase 1 coverage scorecard (`/docs-coverage`) checks A1 against these exact patterns. Renaming them requires updating both this doc and `scripts/docs/check-spec-doc-trio.ts`. *** ## 5. MDX components — when to use which Mintlify ships a set of MDX components. Pick semantic > plain markdown wherever the page would otherwise reach for ASCII workarounds. | Component | When to use | | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `` / `` | Landing pages with sibling-page navigation. Each card has a `title`, `icon`, optional `href`. | | `` | Any procedure with **≥3 numbered steps**. Wraps the entire `1./2./3.` list. | | `` / `` | Per-audience splits ("End user" vs "Admin") or per-environment code samples | | `` / `` | FAQs, edge cases, troubleshooting that should default to collapsed | | `` | Multi-language or multi-env code blocks (e.g. cURL + JS + Python on the same example) | | `` / `` / `` / `` | Semantic callouts — **always prefer over plain blockquotes** beginning with `**Note:**`, `**Warning:**`, etc. The curator flags these. | | `` | Wrap every screenshot. Captions and dark-mode rendering require it. | | `` / `` | Less common; see Mintlify docs | Lint enforces three of these (``, `///`, ``). Run `npm run docs:lint-mdx -- docs/` to surface opportunities. *** ## 6. `.mintignore` policy `.mintignore` (at `docs/.mintignore`) tells Mintlify which paths NOT to publish. Patterns use gitignore syntax, relative to `docs/`. Leading `/` anchors to the docs root. Currently excluded: | Path | Why | | ------------------- | --------------------------------------------------------------------------------------------------------------------- | | `/archive/` | Historical / superseded docs kept for audit | | `/plans/` | Working planning notes | | `/recommendations/` | Internal review/recommendation docs | | `/research/` | Research artifacts | | `/superpowers/` | Brainstorming and plan artifacts | | `/ehr_pm/` | Ingest corpus for EHR/PM research | | `/templates/` | Template files (not user-facing) | | `/reports/` | Audit reports (the `docs-health.json` is committed but the per-date `DOCS_HEALTH_*.md` files are noise for end users) | | Specific files | Internal reviews, audits, gap analyses (see the file for the full list) | **Rule:** every new internal-only tree under `docs/` MUST be added here AND to the curator's exclusion list. If a path appears in `.mintignore` but is referenced from a published page, the link will 404. *** ## 7. Mintlify MCP — three usage patterns The `plugin:mintlify:Mintlify` MCP server provides two tools. Skills use them in three named patterns documented here so they don't drift. ### Pattern A — "Does this doc already exist?" Tool: `mcp__plugin_mintlify_Mintlify__search_mintlify` Used by: `encore-docs-pipeline` (Phase 1) before flagging an A1 doc missing. Reason: a doc may exist under a non-conventional name (e.g. `docs/cl/encounter.md` instead of `docs/cl/cl-05-user-guide.md`). The pipeline searches before declaring "missing" to avoid false positives. If a search hit returns a page that looks like the missing artifact, flag it as a **naming-convention drift**, not a hard miss. ### Pattern B — "Where does this page live in nav?" Tool: `mcp__plugin_mintlify_Mintlify__query_docs_filesystem_mintlify` Used by: `encore-mintlify-curator` (nav placement, audience-track adjacency) and `encore-docs-pipeline` (verify the trio is reachable from nav). Reason: parsing `docs.json` ourselves loses context (Mintlify's own filesystem view knows about its overrides and groupings). Always go through this tool instead of re-implementing nav lookup. ### Pattern C — "What's the Mintlify-correct way to do X?" Tool: `mcp__plugin_mintlify_Mintlify__search_mintlify` (with query targeting Mintlify's own docs) Used by: `encore-mintlify-curator` when proposing MDX component upgrades or `docs.json` changes. Reason: Mintlify ships new components and config options frequently. Always consult the current Mintlify docs before recommending a structural change. ### Wiring rule Every "is X documented?" check goes through Pattern A first. Every nav-shape check goes through Pattern B. No skill re-implements either lookup against raw `docs.json` or `fs.readdir`. *** ## 8. Three audience tracks in nav Three audiences (per the design spec): **end users (clinicians, staff)**, **tenant admins / operators**, and **internal devs & AI agents**. Today's nav uses topic-grouped tabs (Product, Operations) rather than per-audience tabs. Per-audience differentiation happens via the `audience:` frontmatter field; the curator skill enforces that user/admin/dev variants of the same feature live in adjacent nav slots within the same group (e.g. `cl/note-user-guide`, `cl/note-admin-guide`, `cl/note-API-REFERENCE` are sorted together). A future Phase 3 may split into per-audience tabs; for Phase 2 we keep the topic structure and rely on the audience tag for ordering. *** ## 9. Deploy The Mintlify-hosted production site is connected to this repo. Pushing to the configured branch triggers a redeploy. PR previews are auto-attached as a check. The curator skill's "last published commit" check compares the local `HEAD` to the live site's deployed commit (via the Mintlify dashboard or the `mcp__plugin_mintlify_Mintlify__*` tools). If they're more than \~7 days apart, the curator's PR body flags it. *** ## 10. Coverage page `docs/operations/docs-health.mdx` is regenerated by `npm run docs:coverage -- --all` and published under the Operations tab. Source of truth for the data is `docs/reports/docs-health.json`. The page is intentionally simple — it surfaces the same scorecard as the per-date `DOCS_HEALTH_.md` reports but as a live page that auditors and the on-call dev can bookmark. To change what the page shows, edit `renderHealthMdx()` in `scripts/docs/docs-health-writer.ts` — do NOT hand-edit the `.mdx` file (your changes will be overwritten on the next coverage run). *** ## 11. Troubleshooting `mint dev` Common failures and the fast fix: | Symptom | Cause | Fix | | ----------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `Error: Icon "" not found` | Icon name isn't a Font Awesome free name | Check `scripts/docs/icon-rules.yaml`; pick a valid free name | | `YAMLException: bad indentation in frontmatter` | Invalid YAML in `---` block | Run `npm run docs:check-frontmatter` to surface; usually a stray tab or unquoted colon | | `Cannot resolve module '/snippets/foo.mdx'` | Snippet path is wrong | Paths are relative to `docs/snippets/`; `` resolves to `docs/snippets/canonical/constitution.md` | | `MDX compilation error: unclosed tag` | JSX-like component missing closing tag | Self-close `` or close `…` | | `node:internal/process/promises` ESM error | Wrong Node version | `nvm use` (reads `.nvmrc`, currently `24`) | | Site stuck on stale content | `.mint` cache | Delete `docs/.mintlify-cache` and restart | | `docs.json` rejected by build | Schema violation | Run `npm run docs:audit-nav`; locally `npx ajv-cli@5 validate -s https://mintlify.com/docs.json -d docs/docs.json --strict=false` | If you've checked the above and it still fails, copy the failing page into `docs/_drafts/.mdx` (gitignored) and bisect from there. *** ## 12. Mintlify Cloud dashboard checklist These settings live in the Mintlify Cloud UI ([https://dashboard.mintlify.com](https://dashboard.mintlify.com)) and are not in this repo. Confirm them after each major site change: | Setting | Value | Why | | ---------------------------------- | ---------------------------------------------- | ----------------------------------------------------- | | Project → Settings → Monorepo path | `/docs` | Tells Mintlify the content root | | Project → Settings → AI Chat | enabled | Doc-grounded chat widget; reads `llms-full.txt` | | Project → Settings → Search | AI-powered search on | Beyond the prompt string in `docs.json` | | Analytics → Search insights | enabled | Drives weekly export of top-misses for `docs:gapfill` | | Webhooks → Deploy failure | team chat URL | Surface broken Cloud builds | | Custom domain | `docs.encoreos.io` SSL green | Add `www.` alias if needed | | Privacy → Indexing | matches `docs.json` `seo.indexing: navigable` | No 3rd-party crawl of PHI fixture pages | | Team | `@encore-os/docs` GitHub team with Editor role | Reviewers preview drafts without local `mint dev` | *** ## 13. Canonical AI-governance file sync The repo-root files (`/constitution.md`, `/AGENTS.md`, `/AI_GUIDE.md`) are the single source of truth for AI governance. They're mirrored into `docs/governance/canonical/{constitution,agents,ai-guide}.md` so Mintlify can publish them as browsable pages — but the mirrors are **generated**, not authored. ```bash theme={null} npm run docs:sync-canonical # copy and report changes npm run docs:sync-canonical:check # fail if any mirror is stale (CI / pre-commit) ``` The script prepends per-file frontmatter (title, description, icon) and a sync-source banner so the published page reads cleanly. The CI workflow `docs-coverage.yml` runs `:check` before the Mintlify build, so drift between the repo-root canonical files and the published mirrors is caught before merge. **Never hand-edit `docs/governance/canonical/*.md`** — edits made there will be overwritten on the next sync. Edit the canonical source at the repo root. *** ## References * Design spec: docs/superpowers/specs/2026-05-23-docs-site-improvement-design.md * Phase 1 plan: docs/archive/superpowers-plans-2026-05/2026-05-23-docs-coverage-scorecard-phase1.md * Phase 2 plan: docs/archive/superpowers-plans-2026-05/2026-05-23-docs-coverage-scorecard-phase2.md * `encore-docs-pipeline` skill: .claude/skills/encore-docs-pipeline/SKILL.md * `encore-mintlify-curator` skill: .claude/skills/encore-mintlify-curator/SKILL.md * Documentation standards (parent): docs/DOCUMENTATION\_STANDARDS.md