Skip to main content

Frontmatter Schema

Every page in CBA Operations carries a YAML frontmatter block at the top. The frontmatter is what makes role-tagging, CBN-clause indexing, per-tenant filtering and PDF persona bundles possible — it is not optional cosmetic metadata.

The contract​

---
title: Cash Deposit From A Walk-In Customer        # required — page title
description: Steps to lodge cash for a customer    # required — search snippet
sidebar_position: 10                                # optional — sidebar order
personas: [teller, cso]                             # required — who this page is for
cbn_clauses:                                        # optional — regulator cites
  - "Regulatory Framework for MFBs (2006) §11.3"
  - "Clean Notes Policy §4.2"
tenant_visibility: ["*"]                            # required — which tenants see this
doc_type: walkthrough                               # required — Reference / Walkthrough / Runbook / Decision
last_verified: 2026-06-05                           # required — when staff last confirmed accuracy
---

Field-by-field​

title (required, string)​

The page title. Renders in the browser tab, sidebar, search results, and on the printed page. Use sentence case (Cash Deposit From A Walk-In Customer, not Cash Deposit from a Walk-in Customer). Keep under 60 characters.

description (required, string)​

One-sentence snippet that shows up in search results and the page meta. Should make sense out of context (don't start with "This page…"). Keep under 140 characters.

If omitted, the page goes alphabetically inside its category. Use only when you specifically need to override the order (e.g. "Get Started" should be first in a persona index).

personas (required, array of strings)​

Who this page is for. Pulled from the canonical list:

  • teller — counter staff handling cash, cheques, transfers, vault-to-till
  • cso — Customer Service Officer (account opening, KYC, customer maintenance)
  • loan_officer — application intake, underwriting, disbursement, restructure
  • branch_manager — approvals, branch-day open/close, exception handling
  • auditor — call-over, dual control, audit-trail validation
  • finance — period close, reconciliation, regulatory returns
  • contributor — documentation contributors (used on meta/ pages only)

A page may list multiple personas; the persona-PDF build (Pandoc) emits the page into every matching bundle. Cross-persona procedures should be authored once, tagged once.

cbn_clauses (optional, array of strings)​

The regulator clause(s) the procedure satisfies. Used for:

  1. Inline citation — renders a callout box at the top of the page ("Satisfies Regulatory Framework for MFBs §11.3") so the doc is itself an audit artefact.
  2. CBN audit-pack PDF — the audit-pack bundle includes only pages with this field populated, grouped by clause.
  3. CBN Clause Registry — see the registry for canonical clause names; copy verbatim, do not paraphrase.

If you're documenting an internal procedure that isn't regulator-mandated, omit the field.

tenant_visibility (required, array of strings)​

Controls which tenants see the page on their themed help portal. Values:

  • ["*"] — visible to all tenants (default for canonical procedures)
  • ["fmfb"] — visible only to FMFB
  • ["fmfb", "tenant_b"] — multi-tenant override

For Tier 1 (operator decision 2026-05-28) we ship single-portal; this field is captured now so the Tier-2 per-tenant subdomain build can use it without re-tagging existing content.

doc_type (required, string)​

One of: reference · walkthrough · runbook · decision · index.

  • reference — "What does this screen / field do?" — encyclopedic, evergreen
  • walkthrough — "How do I do X end to end?" — sequential, action-oriented
  • runbook — "Something broke — what do I do?" — action-first, time-pressure-friendly
  • decision — "Which path applies?" — branching, decision-tree shape
  • index — persona landing pages and meta/ pages (does not appear in PDFs as standalone)

Conflating doc types is the single biggest decay vector in operations docs (Stripe / Mambu split them by URL; FLEXCUBE mixes them in chapters and reads worse).

last_verified (required, ISO date)​

The date staff last validated the procedure against the live console. Pages older than 90 days surface a "verify me" badge on the rendered page; CI fails on pages older than 365 days. Update this every time you change the page content or confirm it's still accurate.

Validation​

Every push runs a CI lint that verifies:

  • All required fields present.
  • personas, doc_type, and cbn_clauses use values from the canonical lists (typos rejected).
  • last_verified is ISO YYYY-MM-DD.
  • Operator pages do not import @theme/Tabs / @theme/TabItem (those break Pandoc PDF rendering).

Lint script lives at ~/kora-docs/scripts/lint-cba-operations.mjs (added in Step 3 of the Plan A build).