Freshness

updatedAt says when a piece last changed. It does not say whether anybody thinks it is still true — fixing a typo bumps it and tells a reader the page was checked.

The distinction matters more for a machine than for a person. Somebody who sees a 2024 date discounts what they read; a model answers with total confidence out of a page describing a flow that was removed two years ago.

Two facts, two fields

{
  "id": "8f2c…",
  "updatedAt": "2026-08-18T04:12:09Z",
  "freshness": {
    "verifiedAt": "2026-06-01T10:00:00Z",
    "ageDays": 78,
    "stale": false,
    "confidence": 0.7
  }
}

• verifiedAt — when somebody deliberately said "this is still correct". Set by POST …/items/{itemId}/verify, never by editing.

• ageDays — since that, or since the last change where nobody has ever verified it.

• stale — whether that exceeds the space's policy (docs.staleness_days, default 180; 0 turns it off).

• confidence — 0 to 1, decaying over the policy window rather than falling off a cliff at it. Multiply it into your own ranking.

At query time

POST /api/orgs/{orgId}/search carries the same object on every chunk it returns, and takes maxStalenessDays to refuse anything older.

That is what lets an assistant say "the documentation covering this has not been verified since March, so I am handing you to a human" — which is a better support experience than a confident wrong answer, and impossible against a platform that only reports when a file was touched.

Being told rather than going to look

item.stale fires when a published piece crosses the line, once per crossing — not every morning afterwards, because a webhook that repeats every day is one somebody turns off.