Document evidence freshness in compiled Context briefs

SI
5d ago
+1-1

Summary

Documents the evidence-freshness attribution added to compiled Context briefs in the companion API PR. The /api/context 200 response description now covers the additive input_manifest.freshness object: oldestRetrievedAt/newestRetrievedAt bounds across every dated source of the selected documents, documentsWithoutRetrievalDate, and per-document oldestRetrievedAt/newestRetrievedAt. It also covers the Retrieved: line that ends each document section of the Markdown text (one timestamp, an oldest-to-newest range, or unknown, never a source location), and states that compilerVersion stays context-brief-v1 and freshness is reported, not enforced. This is a single anchored sentence insertion; MDX pages stay frontmatter-only and docs.json is unchanged.

Refs recoupable/app#2130 (child of epic recoupable/app#2116).

Merge sequencing

docs → api. Merge this docs PR first (contract first), then the companion API PR recoupable/api#1003 (branch claude/ctx-2130-brief-freshness). This slice has no database or app change.

This PR no longer touches the company_onboarding purpose. That catch-up belongs to recoupable/docs#365 (#2134), with an overlapping enum edit in recoupable/docs#358 (#2118). An earlier revision of this PR edited the same enum, description and example lines, so it would have conflicted with both. This PR still changes the 200 response description string, and docs#365 also rewrites it. Whichever PR merges second needs a one-line rebase that keeps both sets of sentences.

Verification

  • Ran: python3 -c "import json;json.load(open('api-reference/openapi/context.json'))" → parses.
  • Ran: git diff --stat origin/main → 1 file, 1 insertion, 1 deletion (only the 200 response description). grep -c company_onboarding api-reference/openapi/context.json → 0, so there is no overlap with docs#358/#365.
  • Red → green: not applicable (documentation only). The described contract is exercised by lib/context/__tests__/twoSongBriefCheckpoint.test.ts and compileContextBrief.test.ts in api#1003.
  • Not verified: Mintlify render/preview (mintlify dev not run), hosted docs deployment, live providers, production database.

Out of scope / known gaps

  • company_onboarding purpose documentation (owned by docs#365 / docs#358).
  • No freshness-based restriction: the API reports retrieval dates but does not drop stale evidence.
  • The live two-track run, failure/resume cost reconciliation and the human-review dossier for #2130 remain deferred. They are gated on #2127/#2128/#2129 and approval.

🤖 Generated with Claude Code