freshdocs 0.3.0

Freshdocs keeps coding agents from confidently using an API that no longer exists.

This release fixes the thing that made it unreliable: it indexed only README and CHANGELOG, so a question about auth middleware could come back with a feature list or a table of contents. It now retrieves actual documentation prose.

Retrieval

• Fetches the repository docs/ tree instead of the README alone.
• Resolves llms.txt into the pages it links to, rather than storing the link index itself.
• Scores link density per chunk and ranks navigation below real prose, so a query returns an answer and not a table of contents.
• Requires every query term to match before falling back to a partial match.
• New --docs-gh and --docs-branch for libraries whose prose lives in a separate website repository, preregistered for hono, astro, tailwindcss, biome, and drizzle-orm.

The bundled corpus grows from 5027 to 12809 chunks across the same 35 libraries, 7633 of them documentation prose that was previously unreachable.

Honest misses

A miss now names its cause, gives the command that closes it, and tells the agent not to retry reworded queries against a cache that cannot answer them:

RESULT: no matching documentation in the local cache.
CAUSE: no cached chunk for hono matched this question.
This is a cache gap, not a bad query. Do not retry reworded queries.
FIX:
  1. freshdocs context "cookie auth" --project . --sync-stale
  2. if it still misses, the docs do not cover this API: say so instead of guessing

Fixes

• GitHub tree requests were rejected with HTTP 403 because they sent no User-Agent.
• Registry merging replaced entries instead of merging them, so libraries registered earlier never received fields added to the shipped registry later.
• Release-tag detection missed projects tagging as <name>-v<version>, which had forced bun onto branch-fallback.
• Cached versions built by an older indexer now refresh on the next sync instead of serving thin pre-upgrade chunks forever; freshdocs doctor reports how many are affected.
• The per-library cache bound is 500k characters, enough for a full documentation site.

Note on versions

status shows the newest version Freshdocs has checked; context shows the version your project installs and serves docs fetched at that release tag. A project pinned to ruff 0.14.14 gets 0.14.14 docs even when the cache also holds 0.16.6. That is the point.

Install

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