feat: lockdocs 0.3 - docs sites pinned to your major, heading-aware ranking, held-out questions

[shtse8]

Quality round for lockdocs 0.3.0: close the gap to Context7 on the newest majors and on tokio with general fixes, guard against overfitting with held-out questions, add the owner-standard product docs, and release.

Results (CI, GitHub-hosted runner, run)

	correct	older majors	newer majors	tokio	held-out	median tokens	median latency
lockdocs + lockdocs fetch	96/105	38/45	53/55	5/5	16/18	866	97 ms
lockdocs, package files only	60/105	27/45	29/55	4/5	6/18	903	52 ms
Context7 (anonymous)	77/105	19/45	53/55	5/5	15/18	908	2,583 ms

Before (0.2.1, 70 questions): 55/70 vs 49/70; newer majors 29/34 vs 34/34; tokio 2/3 vs 3/3. Every column is now won or tied. On the original 70 questions: 65/70.

Context7 answers are reused from the previous run only when question, grading and version are unchanged (103 of 105 this run; 8 HTTP calls).

What changed

Sources

• Docs-site repositories follow the pinned major: the default branch for the latest major; for older majors a vN / N.x branch (Tailwind CSS v3, Prisma v6) or the last commit before the next major's N+1.0.0 tag. React keeps latest-only (react.dev documents APIs before they ship). Pages about a later major are skipped. tokio's website is added; docs sites work for crates and PyPI too.
• Docs pages written as React components are indexed (Tailwind installation guides).
• MDX HTML headings split sections; export const title names the page; MDX heading ids are dropped.
• Bug fix: Django's docs (reStructuredText in .txt) were downloaded but never indexed.
• GitHub API redirects keep the token (prisma/prisma moved); docs-site errors appear in the fetch note; upstream::FORMAT makes lockdocs fetch refresh old copies.

Ranking and answers

• A second BM25 over heading/name and first sentence (weight 0.25 of the keyword score).
• Question words naming a documented top-level API count as identifiers.
• Generic headings (Parameters, Returns, Examples) take their topic from the heading above; capitalized words in headings stay whole.
• Upgrade guides to an older major and pages titled "(Deprecated)" rank lower unless the question is about changes.
• Code-only sections are embedded with their code; readable titles for untitled pages.
• Stemmer: -ation/-ate, -ability/-able; synonyms parameter/param, JavaScript/JS, TypeScript/TS, database/DB.
• The top result quotes its page and parent section leads (with the list or code that follows) when they add something.
• Weights were swept on CI (dense 0.35/0.40/0.45/0.55, head 0/0.15/0.25/0.35). The defaults (dense 0.45, head 0.25) score as well as or better than every other setting on the tuning set; lower dense weights lose tokio select!, a higher head weight loses axum and Django questions.

Benchmark

• 105 questions (was 70). 17 first held-out questions were used for diagnosis after their first run (lockdocs 11/17, Context7 12/17) and moved to the main set with a history note; 18 new held-out questions, written before the second round of changes, are reported separately.
• Grader fix: pydantic 1 questions reject the v2 idiom model_config = ConfigDict (pydantic 1.10 also ships a ConfigDict TypedDict, so the old reject failed correct v1 answers).
• Context7: on HTTP 404 the next search result is tried, as an agent would.
• bench.yml variants input for weight sweeps.

Owner standards

• docs/vision.md, docs/capabilities.md, and a CI check that every named code path exists (scripts/check-capabilities.ts).

Release: 0.3.0; merging publishes through release.yml.

Net LOC: +3,746 overall (+4,935 / -1,189, mostly benchmark data); +1,065 excluding bench-results.json, questions.json, Cargo.lock and the generated benchmark page (+1,227 / -162).