freshdocs 0.4.0

Freshdocs no longer loads a library's documentation just because the project uses it. It loads what the reading model cannot already know.

The idea

A model trained on hono 4.13.5 does not need its documentation pasted back. Spending the prompt on it is not merely redundant, it crowds out the two cases that actually cause wrong code.

Give Freshdocs the model id and it compares each installed version's publication date against that model's training cutoff:

freshdocs gap --project . --model claude-sonnet-4-5

model: claude-sonnet-4-5 (matched claude-sonnet-4, cutoff 2025-01-01)
  LOAD  hono               4.13.5   training gap (released 2026-08-26, after cutoff 2025-01-01)
  skip  zod                3.22.4   covered by training (released 2023-08-01, cutoff 2025-01-01)

Verdict	Meaning	Action
ahead	Released after the cutoff. The model cannot know it.	full context
behind	The project pins an older release than the model most likely learned, so it may write an API that exists upstream but not here.	full context
covered	Model knowledge and project agree.	short confirmation
unknown	Any input is missing.	full context, with the reason

behind is the verdict worth having. A model that learned a newer release than the checkout pins will confidently call a function that does not exist yet in this project, and nothing in a version number alone reveals that.

Effect

Passing --model to context spends the budget on the gaps, and --sync-stale refetches only those libraries instead of every detected one:

freshdocs context "bearer auth" --project . --model claude-sonnet-4-5 --sync-stale
export FRESHDOCS_MODEL=claude-sonnet-4-5   # or set it once

On a two-library project where the model already covers both, the pack drops from 4812 to 1639 characters and no library is refetched. Where it covers neither, nothing is withheld.

Failing safe

Skipping documentation on a bad guess would be a worse failure than sending too much, so every uncertain path resolves to unknown and loads the full pack: an unrecognised model, a version with no publication date, an offline registry, an unregistered library, a version released inside a 45-day margin before the cutoff, or a prerelease. freshdocs doctor re-proves that invariant on every run:

gap mode: on for claude-sonnet-4-5 (matched claude-sonnet-4, cutoff 2025-01-01)
  unknown release dates fail safe to a full context pack

Release dates are cached, so gap detection costs no network call per prompt, and a failed refresh keeps the previous answer instead of degrading into a guess.

Cutoffs are yours to correct

Built-in cutoffs are approximate, matched by longest prefix, and deliberately conservative: too early only costs tokens, too late would withhold something needed.

freshdocs models
freshdocs models --set my-local-model 2025-06-01

Also fixed: the registry silently dropped user-owned top-level keys, including these overrides, whenever it was rebuilt from the shipped defaults.

Install

uv tool install git+https://github.com/Supersynergy/freshdocs@v0.4.0