---
title: Provenance & freshness
description: Machine-legible last_updated / last_verified dates that earn agent trust, plus thally check --drift to catch stale pages against the code they document.
url: http://localhost:3040/guides/provenance
---

# Provenance & freshness

Machine-legible last_updated / last_verified dates that earn agent trust, plus thally check --drift to catch stale pages against the code they document.

Agents (and people) trust docs more when they can tell *how current* a page is. Thally surfaces a **machine-legible freshness signal** on every projection, and gives you a deterministic way to catch pages that have drifted from the code they document.

There are two layers, with two different audiences.

## Public: freshness dates

Add either date to a page's frontmatter and it appears in every public projection — the page metadata, `?format=json`, the `.md` mirror, and `/api/docs-index`:

```yaml
---
title: Swap tokens
lastUpdated: 2026-06-30      # the bytes last changed
lastVerified: 2026-07-01     # a human last confirmed it's still accurate
verifiedVersion: "2.3.0"     # optional: the product version it was verified against
---
```

`lastUpdated` and `lastVerified` mean different things. **Updated** is when the page changed; **verified** is when someone last confirmed it's still correct against the product. A page can be verified without being edited — that's the strongest freshness signal, and no other docs platform ships it in a form agents can read.

## Internal: sources & drift

The mechanism behind `lastVerified` is a set of **sources** — the code a page documents — and the commit it was last checked against. These live in frontmatter but are **never published**: a consuming agent can't interpret a file path from a repo it can't see, so Thally strips them from every public projection.

```yaml
---
title: Swap tokens
lastVerified: 2026-07-01
# Internal — read only by `thally check --drift`, never served publicly:
sources:
  - src/networks.ts
  - "openapi.yaml#/paths/~1swap"
verifiedCommit: 9f2c1a7
---
```

Reference files in the same repo directly (`src/networks.ts`). A `#fragment` (e.g. an OpenAPI path) narrows *what* it documents — drift is still evaluated against the whole file.

## `thally check --drift`

Run the drift check to flag any page whose `sources` changed since its `verifiedCommit`:

```bash
thally check --drift
```

It's deterministic and needs no AI — just git history. A page is flagged **stale** when a source file has new commits since it was verified. Combine with `--ci` for GitHub annotations:

```bash
thally check --drift --ci
```

> **Warning:**
`--drift` needs the **full git history**. GitHub Actions checks out `fetch-depth: 1` by default, so old `verifiedCommit`s won't be present — set `fetch-depth: 0`:

```yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
```

If a `verifiedCommit` isn't in history, the check reports it as **indeterminate** ("cannot verify freshness") rather than silently passing — a false "fresh" is the dangerous direction.

## The verify flow

When you've confirmed a page is still accurate, stamp both layers together — set `lastVerified` to today's date and `verifiedCommit` to the current commit (`git rev-parse HEAD`). The public date moves forward and the drift baseline resets. Scheduling `thally check --drift` on a cron turns this into a safety net: drift found → a docs task → a reviewed pull request.