Add content freshness detection in build system

Author: s1ddh-rthCreated Mar 23, 2026Updated Mar 23, 2026
Labelsenhancement

Problem

Context Hub's core value proposition is giving agents accurate, up-to-date docs. But there's no mechanism to detect when content goes stale.

Currently:

  • If updated-on is missing from frontmatter, build.js silently defaults it to today's date (line 92), hiding the problem
  • There's no visibility into how many docs in the registry haven't been touched in months
  • Issue #106 is an example — Gemini docs are 2 generations behind, and nothing in the build or CI flagged it

As the registry grows (1667 entries today, 90 open PRs adding more), stale content will accumulate silently and undermine trust in the tool.

Proposed Solution

Two non-breaking changes to chub build:

1. Warn when updated-on is missing instead of silently defaulting to today Currently line 92 of build.js does:

javascript
const updatedOn = meta['updated-on'] || new Date().toISOString().split('T')[0];

This should emit a warning (like the existing missing 'metadata.source' warning) and fall back to "unknown" instead of today's date.

2. Print a staleness summary at the end of build output After processing all entries, count how many have an updated-on older than 6 months and print an informational line: Freshness: 47 of 1667 entries not updated in 6+ months Non-blocking — just a warning, never a build error. Existing CI and contributor workflows are unaffected.

Both changes are additive warnings only. No existing builds break.

Alternatives Considered

  • Make staleness a build error: Rejected — would immediately break CI since existing stale docs are already in content/. Contributors adding new docs would be blocked by old docs they didn't write.
  • CI step checking only PR-changed files: Useful but heavier (needs git diff against base branch). Could be a follow-up.
  • Checking updated-on against real package versions via npm/PyPI APIs: Too complex, too slow, too fragile for CI. Out of scope.
  • Separate chub stale command: Unnecessary if the build already reports it.

Additional Context

  • Related: #106 (stale Gemini docs), #107 (stale OpenAI docs — now fixed)
  • The updated-on field is already documented as expected in the docs/content-guide.md and CONTRIBUTING.md, but never validated
  • All existing content entries use YYYY-MM-DD format for updated-on