Skip to main content
A knowledge page (knowledge/global/<id>.md or knowledge/user/<id>/<id>.md) is Markdown with YAML frontmatter, validated against KnowledgePage at load time. Every field is optional with a sensible default, so a page with empty frontmatter is valid. See Knowledge for the concepts behind these fields. 
---
summary: "Why test accounts are excluded from active-customer counts."
tags: [customers, definitions]
sl_refs:
  - warehouse_pg.customers
  - warehouse_pg.orders.total_revenue
refs: [test-account-policy]
usage_mode: caveat
meta:
  provenance: human_curated
  last_validated_at: "2026-06-14T00:00:00Z"
  bound_fingerprints:
    "warehouse_pg.orders.total_revenue": "sha256:…"
  frozen: false
---

​
Frontmatter fields

FieldTypeDefaultGoverns
summarystr""One-line summary; indexed and shown in search results, boosted over body-only matches.
tagslist[str][]Free-form tags; indexed and boosted in lexical search.
sl_refslist[str][]Fully-qualified semantic entity references (e.g. orders.revenue). Each must resolve to a live semantic entity at write time, or the write is rejected.
refslist[str][]References to other pages by id/slug. Each must point at an existing page in a visible scope, or the write is rejected.
usage_modeUsageModereferencereference | caveat | policy | definition; see below.
metaKnowledgePageMeta{provenance: inferred}System-managed; see below.
id, path, and scope are derived from the filesystem path, never accepted from frontmatter — knowledge/global/<id>.md gives scope: global; knowledge/user/<user-id>/<id>.md gives scope: user. The Markdown body after the frontmatter fence is stored verbatim as body.

​
usage_mode

ModeBehavior
referenceFound by search/traversal only. The default.
caveatAuto-surfaced whenever a bound sl_ref entity appears in a result, even if nobody searched for it.
policyA business rule/definition page; ranked like reference but tagged distinguishably.
definitionThe canonical prose definition for a term; collisions follow the strict-additive rule (global wins, user pages annotate rather than override).

​
meta

System-managed — not hand-edited; reconciliation and the loader write these fields.
FieldTypeDefaultGoverns
provenanceProvenanceinferredboard_approved | human_curated | inferred.
last_validated_atdatetime | nullnullWhen this page’s references were last checked against live entities; drives a staleness signal at query time.
bound_fingerprintsdict[str, str]{}Measure-definition fingerprints this page’s prose depends on, keyed by fully-qualified entity name. When a bound fingerprint changes, the page is flagged for review.
frozenboolfalseHuman-owned freeze marker; reconciliation flags conflicts but never edits a frozen page.
Inline {{ sl:<entity>.expr }} in the body renders the live value of a semantic field at read time, so prose can’t fall out of sync with the definition it describes; [[slug]] or [[slug|alias]] resolves an inline link the same way refs does.