Frontmatter Schema

Every .md file in docs/ must open with a YAML frontmatter block. Each field has exactly one primary consumer: Docusaurus, the doc-update bot, or the UI component that renders the verified bar on every page.

Canonical template

---
title: ""
description: ""
relates_to: []
last_verified: YYYY-MM-DD
verified_by: github-username
---

Paste this at the top of every new page. last_verified and verified_by are set automatically by the GitHub Action on merge to main — do not fill them by hand.

---

Fields

title

Consumer: Docusaurus Required: yes

The page title as it appears in the browser tab, search index, and link previews. Must agree with the H1 heading on the page.

Conventions per doc type:

Doc type	Convention	Example
Reference	Feature or component name	"Token Manager"
How-to	Action phrase starting with a verb	"Add a REST Endpoint"
Runbook	Incident or procedure name	"Sevalla Deployment Rollback"
ADR	ADR-NNNN: prefix + short title	"ADR-0003: Migrate from MkDocs to Docusaurus"

Malformed if: missing, empty string, or an ADR page whose title does not match ADR-\d{4}:.

---

description

Consumer: doc-update bot + search engines Required: yes (empty string is valid during authoring)

One sentence summarising what this page covers. The bot reads this to understand a page's scope without reading the full content — it is a token budget, not decoration. Search engines use it as the meta description.

Fill it before setting last_verified. Keep it under 160 characters. Do not use newlines.

Malformed if: longer than 160 characters, or contains a newline.

---

relates_to

Consumer: doc-update bot Required: yes ([] for cross-cutting pages)

Array of glob patterns pointing to the source code paths this page documents. When a PR in the backend or workers repo touches a file matching one of these globs, the bot opens a PR flagging this page for review.

Use [] for pages that do not map to specific source paths — ADRs, architecture overviews, onboarding guides.

Glob syntax (minimatch semantics):

Pattern	Matches
internal/features/auth/**	every file under auth/, at any depth
internal/features/auth/*.go	.go files directly inside auth/ only
internal/platform/livekit/**	everything under the LiveKit platform client
{internal/features/chat,internal/features/room}/**	chat or room feature, any depth
cmd/api/main.go	exact file match

Rules:

• Paths are relative to the target repo root. No leading /.
• Prefer ** — wide globs survive internal refactors.
• One entry per line.

Malformed if: any entry contains a leading /, or the field is absent entirely.

---

last_verified

Consumer: UI (verified bar rendered at the bottom of every page) Required: yes — set automatically by the GitHub Action on merge to main

ISO 8601 date (YYYY-MM-DD) of the last merge to main that touched this file. Represents the point at which a human confirmed the page is accurate — either the author of the original PR or the approver of a bot-generated PR.

Do not set by hand. Leave empty on first draft; the Action fills it on merge.

Malformed if: present but not in YYYY-MM-DD format, or set to a future date.

---

verified_by

Consumer: UI (verified bar rendered at the bottom of every page) Required: yes — set automatically by the GitHub Action on merge to main

GitHub username (no @ prefix) of the person whose approval last verified this page:

• Human-authored PR → the PR author
• Bot-generated PR → the human who approved and merged it

Do not set by hand.

Malformed if: contains @, or is a non-string value.

---

Docusaurus system fields

These are consumed by Docusaurus only. The bot ignores them.

Field	Type	When to use
sidebar_position	integer	Override alphabetical ordering within a category. Lower = higher.
sidebar_label	string	Override the title in the sidebar when the full title is too long.
slug	string	URL path override. Only used on docs/index.md (slug: /). Do not use elsewhere.

---

CI validation rules

A GitHub Actions workflow runs on every PR that touches docs/. It parses the frontmatter of every changed .md file and fails the check if any field is missing or invalid. The intent is to catch malformed pages before they reach main — a page with a broken relates_to glob will never trigger the doc-update bot correctly, and a page with a missing description degrades bot output quality on every subsequent run.

A page is malformed if any of the following is true:

1. No frontmatter block present.
2. title is missing or an empty string.
3. description is longer than 160 characters or contains a newline.
4. relates_to is absent (must be [] at minimum).
5. last_verified is present but not in YYYY-MM-DD format, or is a future date.
6. verified_by contains @ or is a non-string value.
7. The page lives under docs/adr/ and title does not match ADR-\d{4}:.