# Freshness Tiers

Pages in this vault age at different rates. A summary of an article describes a fixed source and does not go stale on its own — the article said what it said. A toolbox page describes a moving target: the repository gets releases, changes license, or dies. A concept page about LLM agents describes something that is rewritten every few months. Treating all of them alike means either re-reading summaries that cannot have changed or never noticing that a tool page is two years behind its repository.

The `freshness:` list in the frontmatter above is the machine-readable half. `warren lint --src .` reads it from whichever page carries it, computes a tier for every page in `wiki/`, `toolbox/`, `books/` and `talks/`, and reports each page whose `updated:` is older than its tier allows. This page is the only place the tiers are written, so the table below and the check cannot disagree. [[planned-pages]] does the same job for deliberate gaps.

## How a page gets its tier

The base comes from the page's `type:`, then from its section directory, then from `default`. A tag can shorten a finite base but never lengthen it, and never revives `never`. So a `concept` page tagged `ai-agents` ages in nine months rather than two years, while a `summary` page with the same tag does not age at all: the summary is about the article, and the article is not going to change.

| Tier | Applies to | Why |
|------|-----------|-----|
| `never` | `summary`, `book`, `talk` (via `default`) | They describe a fixed source. What can go stale is a *claim* the vault repeats elsewhere, which is the judgment half of the lint, not this check. |
| `2y` | `concept` | Ideas hold; the examples and the tools named around them do not. |
| `18m` | `entity` | Companies, products and people change state — acquired, renamed, discontinued. |
| `1y` | `toolbox`, `comparison`, `analysis`, `overview` | A tool page is a snapshot of a repository; a comparison is a snapshot of several. |
| `9m` | tags `ai-agents`, `agentic-coding`, `coding-agent`, `llm`, `local-models`, `mcp` | The fastest-moving area in the vault. A concept page written about agent frameworks in one spring is describing a different field by the next. |
| `6m` | tag `claude-code` | A product with weekly releases; page-level claims about its features and hooks go wrong fastest of all. |

Ages are written as `<n>d`, `<n>w`, `<n>m` (months, 30 days) or `<n>y` (365 days), or the word `never`. `warren lint` rejects anything else with a `front-freshness` error on this page, because a typo here would silently exempt a whole tier.

The [[toolbox/watchlist]] keeps its own cadence — a next-check date per row, 90 days by default — and is not duplicated here. A watchlist tool is on the toolbox tier like any other; the row is the finer schedule.

## What to do with a stale finding

A `stale` finding is a review request, not a defect. Re-read the page, check it against what has happened since — a release, a newer source in the vault, the repository's current README — and then do one of two things. Revise the page if something changed, or confirm it if nothing did. Both end with bumping `updated:`, because a review that changed nothing is still the date the page was last known to be right, and that is what the check measures. Bumping `updated:` without looking is the one move that defeats the purpose.

If the check is being run ahead of a review — "what will be stale by December?" — `warren lint --as-of 2026-12-01` measures against that date instead of today.