# 4 · Front matter

Every file opens with a short header between two `---` lines. It tells an agent what the file is, whether it's current, how it may be handled, and where its facts come from, before the agent reads a word of the body.

```yaml
---
title: Annual Conference
type: program-reference
description: One sentence on what this file covers.
owner: Director of Meetings
last_updated: 2026-10-27
status: current
sensitivity: public
auto_update: drafts-only
auto_update_sources: conference website, source-material/registration-faq.pdf, inbox
last_verified: 2026-10-20
review_frequency: quarterly
---
```

The first fields (`title`, `type`, `description`, and the idea of one topic per file) follow the Open Knowledge Format (OKF), an open convention for knowledge files. OKF doesn't cover who may change a file or how sensitive it is. `sensitivity`, `auto_update`, `auto_update_sources` and the review fields are a governance layer you add on top.

## The fields

**`title`**: the file's name in plain words.

**`type`**: what kind of file it is, from a short fixed list. Agents and other tools use it to filter without reading the body. A list that works: `organization-reference`, `member-reference`, `program-reference`, `system-reference`, `policy`, `operations-reference`, `faq`, `glossary`, `library-meta`.

**`description`**: one sentence saying what the file covers. Search results and folder indexes show it, so an agent can decide whether to open the file.

**`owner`**: the one person (or role) responsible for the file being right. Every proposed change to the file goes to them, or to the library owner if you start with one owner for everything.

**`last_updated`**: the date of the last edit.

**`status`**: `draft` (written, not yet checked), `current` (checked and in use), `needs-review` (flagged for the next review), `archived` (kept for history, not to be relied on). Agents tell the user when an answer rests on a draft.

**`sensitivity`**: how the file may be handled, set by the most sensitive thing in it.

- `public`: nothing in it needs protecting.
- `internal`: staff only; use it in approved AI tools, never in public ones.
- `restricted`: board, financial or personnel material; only in tools with contractual data protection, and written by talking it through rather than uploading source documents.

If the field is missing, agents treat the file as the more restrictive tier.

**`auto_update`**: how far an agent may go when it proposes a change to this file.

<!-- PENDING Scott: auto_update framing -->

- `yes-with-review`: the agent may draft the exact edit for the owner to approve.
- `drafts-only`: the agent may draft a proposed edit as an inbox note.
- `none`: the agent may only flag that the file looks wrong or stale.

Whatever the value, **every change is reviewed and approved by a person before it is applied.** No agent changes the library on its own.

**`auto_update_sources`**: where this file's facts come from. It lists the sources the file is checked against and refreshed from: a web page, a document in `source-material/`, another library file, the word `inbox` (notes filed by agents and staff), or `manual` when the facts come from conversation with the owner and no document holds them.

It does three jobs:

1. **It's a pointer an agent can follow.** When a question needs more than the file's summary (an exact date, the full wording, a figure), the agent opens the source the file names. If the file and the source disagree, the source wins, and the agent files a note.
2. **It's the checklist for a fact-check.** A review run reads the file, opens each source, and proposes changes wherever they no longer match.
3. **It tells the owner where to look** when they update the file by hand.

Keep two rules. Every source must be something each authorized person can open; a path that only works on one person's computer is a note to self, not a source. And for things that change each cycle (dates, prices, deadlines), name the live source and say in the file that it wins.

**`last_verified`**: the date a person last confirmed the file is still true. It's different from `last_updated`: a file can be edited without being checked, or checked and found fine with no edit. Empty means never verified.

**`review_frequency`**: how often the file should be checked: `monthly`, `quarterly`, `semiannual`, `annual`, or `as-needed`. Use `annual` as the default and shorter cycles for files that change with an event or a contract. A review run flags files whose `last_verified` (or `last_updated`) is older than this.

## Fields for later

Add these once you need them, not before:

- **Member-safe tags** in the body (`<!-- member-safe -->` … `<!-- /member-safe -->`) around text members could already read on your website, if you build a member-facing assistant from the same files.
- **A field naming any tool that keeps a cached copy of the file**, so whoever edits it knows to refresh that copy.