freshdocs 0.6.0 — automatic model identity

Freshdocs now identifies the active model once and automatically applies its measured per-library knowledge profile. Agents no longer repeat --model, and fresh installations no longer import benchmark data manually.

Automatic, without guessing

Identity is resolved from the strongest exact evidence available:

1. explicit override (still available for debugging),
2. hook or MCP metadata (model, model_id, modelId),
3. provider model environment,
4. a positively identified parent agent's model argv/configuration.

MCP clients may expose params._meta.model or negotiate capabilities.experimental.freshdocs.model. Older clients can identify on one tool call; the server retains the id for the connection. freshdocs_identity reports the selected id, profile, cutoff, and mode.

There is intentionally no model-name guess from a client brand. MCP does not standardize active LLM identity, and a client called “Claude” may use another model through a gateway. Missing, malformed, unknown, or contradictory evidence selects full documentation. A conflicting later MCP identity permanently locks that connection into safe/full mode.

Profiles now work on a clean install

The registry-verified benchmark evidence is packaged in the wheel and merged per model on upgrade. Local probes override only the exact same model id. No freshdocs models --import setup step is required.

freshdocs gap --project .
freshdocs context "the task" --project . --sync-stale

Both commands use the detected model automatically. freshdocs models --record '<answer JSON>' does too.

GPT-5.6-sol measured

The same blind 20-library recall probe used for the prior model was answered before registry lookup:

• 20/20 verified versions
• 0 hallucinations
• measured median cutoff: 2025-08-16
• 20 per-library dates, from ratatui 2024-10-21 to tauri 2025-09-01

Against claude-fable-5-1 in its main-session probe (2025-06-11), GPT-5.6-sol's median is 66 days newer. It was newer on 16 libraries, equal on four, and older on none. This does not establish general model superiority; it specifically refutes the claim of a two-year coding-library knowledge deficit on this panel.

Retrieval safety

• Exact dependency versions remain authoritative.
• ahead, behind, and unknown libraries receive full prose.
• covered libraries receive one source pointer without redundant prose.
• Gap libraries retain guaranteed slots and appear before covered libraries.
• Model profile matching now requires an exact or descendant id; arbitrary substring matches cannot suppress docs.

Validation

• 115 local tests pass.
• Clean Python 3.11 wheel install automatically loaded the GPT profile without import.
• MCP handshake, one-time identity reuse, conflict locking, hook metadata, environment detection, and unknown-model fallback were exercised end-to-end.
• GitHub CI passes on Ubuntu and macOS with Python 3.11–3.13.

freshdocs 0.5.0

0.4.0 loaded only the documentation a model cannot know, judged against a training cutoff copied from a vendor page. 0.5.0 measures the cutoff instead.

Measure, do not guess

freshdocs models --probe            # prints a 20-library recall question
freshdocs models --record <model-id> '<your JSON answer>'

Each answer is checked against the package registry: a real version yields its publication date, an invented one is recorded as a hallucination and does not count. The cutoff is the median of the verified dates, so one lucky late answer cannot pull it forward, and the per-library dates are kept, because coverage is uneven. An MCP client does the same in two calls to freshdocs_probe; freshdocs_gap returns the per-library verdict as JSON.

Precedence is now --cutoff > measured > models --set > shipped table.

What 16 models actually know

data/model_cutoffs.json ships measured cutoffs; data/README.md has the analysis. Three findings:

• Every measured cutoff is well behind the release date. Models shipped in 2026 recall library versions from late 2023 to mid 2025. A 2026 library is a training gap for all of them.
• Prompt wording moved the same model by a year. "Prefer an old version if unsure" pushed claude-fable-5-1 from 2025-05 to 2024-05 and minimax-m3 from 2024-11 to 2024-03, with zero hallucinations either way. Real knowledge discarded, nothing gained. The recall wording is now default; the registry check catches invention.
• Context changes recall. The same model id answered 2025-06-11 in a long session and 2025-05-16 as a fresh subagent. A measured cutoff describes a model in a context, which is why the safety margin stays and --cutoff overrides.

Retrieval fixes found while testing

• The budget is split per library by verdict. A library the model has never seen is guaranteed its share and listed first; a library that merely scores higher on the query words can no longer take every slot.
• A covered library's hit is a pointer (header and source URL, no prose). The model knows that release; the prose would repeat its training.
• Search walks a precise-to-loose plan and tops up rather than restarting, with a middle tier that requires any two query terms.
• CHANGELOG and MIGRATION rank below guide pages for usage questions; a question about upgrading lifts the penalty.

Four-library project, probed model: no --model 2430 tokens · one gap 1700 · all covered 240.

Install

uv tool install git+https://github.com/Supersynergy/freshdocs@v0.5.0
freshdocs models --import "$(python -c 'import freshdocs,os;print(os.path.dirname(freshdocs.__file__))')/../../data/model_cutoffs.json" 2>/dev/null || true

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

freshdocs 0.3.1

Follow-up to 0.3.0, closing the two caveats that release shipped with.

Documentation repositories are pinned to a commit

A separate documentation website repository carries no version tags, so 0.3.0 read it from a moving branch and labelled the result live-unversioned. That branch keeps moving, so the cited URL stopped matching what was indexed.

The branch is now resolved to a commit before fetching. The source URL is immutable, and the snippet is labelled docs-commit <sha>:

[1] hono 4.13.5 fetched 2026-09-04 docs-commit c48b858 - Bearer Auth Middleware
source: https://raw.githubusercontent.com/honojs/website/c48b858a67.../docs/middleware/builtin/bearer-auth.md

docs-commit is deliberately distinct from exact-ref: it is current documentation prose read at a fixed point, not the library's own version tag. A branch that cannot be resolved is reported as a warning.

Stale-format cache entries can be dropped

0.3.0 marked cached versions built by an older indexer as stale but offered no way to clear them, and re-indexing every historical version took hours while storing documentation nobody had asked for.

freshdocs prune            # --dry-run to preview, --include-current to go further

Pruning is instant and safe: the staleness check re-fetches a version with the current pipeline the moment a project pins to it. On a 35-library cache this dropped 149 versions and 4011 chunks in under a second, and doctor reports all cached versions at format 2.

Use freshdocs sync --outdated instead when you want those versions re-indexed up front.

Install

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

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

freshdocs 0.1.0

freshdocs 0.1.0 - local docs pre-flight for coding agents

Why This Release Matters

Freshdocs stops coding agents from guessing against stale docs. It syncs official documentation into a local cache, keeps the resolved package version visible, and prints compact context blocks with checked dates before an agent writes code.

Highlights

• Version-pinned docs context via freshdocs context.
• Local SQLite cache with explicit stale and missing-doc signals.
• CLI plus MCP tools for context, search, sync, detect, and source discovery.
• Repo dependency detection for package.json, Cargo.toml, and pyproject.toml.
• Advanced source map for language, registry, repo, and tool research.

Quick Install

uv tool install git+https://github.com/Supersynergy/freshdocs
freshdocs init
freshdocs sync --lib hono
freshdocs context "middleware auth" --lib hono

Verification

just ci

Assets

• freshdocs-0.1.0-py3-none-any.whl
• freshdocs-0.1.0.tar.gz

Breaking changes: none.