feat: build-generate AI retrieval layer (knowledge graph + index)

[eugenia-scandit]

Add a Docusaurus postBuild plugin that turns the rendered docs into an AI-consumable layer, generated at build time:

/assets/knowledge-retrieval-index.json  (fast lookup)
/assets/knowledge-graph.jsonld          (concept graph)

Parses the final rendered HTML (so imported partials/MDX are captured in full), splits each page of the version served at the root into ~1400-char knowledge modules, and derives per-chunk metadata: summary (from the frontmatter description), rule-based intents/audiences, framework, product, and the real URL. The graph mines real edges — BelongsToProduct, CitesApi, SeeAlso, and per-product AvailableOn / NotAvailableOn. Per-page extraction failures are non-fatal - one bad page is skipped with a warning and the build continues. Systemic failures are deliberately the opposite: zero pages extracted, a page-error ratio above 50%, a missing or malformed customFields.knowledgeIndexIgnoreFiles, an ignore glob using an unsupported character, and a broken excerpt invariant (a dangling code fence, or an excerpt ending on a heading with nothing under it) all throw and fail docusaurus build, matching the config's onBrokenLinks: "throw" convention. Publishing an empty or malformed index over a good one is the failure this is guarding against.

Division of labour with docusaurus-plugin-llms

Both plugins export for AI consumers, so the boundary is worth stating. Figures are from a current build.

docusaurus-plugin-llms ships the prose, for context-stuffing: llms.txt as a link index (0.08 MiB) and llms-full.txt as the text (2.28 MiB).

This plugin ships typed metadata and edges, for deciding what to read: intents, audiences, channels, frameworks, products, cites-API, see-also, availability — none of which a flat text dump can express. It publishes only an excerpt of the prose — the index is around 10 MiB and the graph around 11 — plus a url; the full text is the page itself. (Exact sizes drift with chunking and are deliberately not pinned in the source comment; read baseline.json or measure the built artifacts.)

Neither replaces the other. Publishing the prose per module would add roughly 6 MiB to a 10 MiB artifact to restate text that is already published beside it, so CHUNK_TARGET_CHARS is a granularity knob rather than a payload size: it decides which links land in which module's references and api_refs, so changing it changes the edges.

Shared scope, one deliberate difference. Both apply the same curation decision — assistantIgnoreFiles in docusaurus.config.ts, covering deprecated platforms, features a platform lacks, redirect-only stubs and non-route partials — so what an assistant may see is decided once. Each takes its own list as a plugin option (options.ignoreFiles here, ignoreFiles on the llms plugin) rather than through customFields: a customFields key is a second name to keep in step with the list it mirrors, and it had already drifted once. They differ only on llmsDedupedToWeb: a flat corpus wants a single copy of prose repeated across frameworks, while a routing index needs the module that points at the framework the reader is actually on. Applying that dedup here removed ~1,400 modules along with the ability to answer "where in the Flutter docs does this live".

Known limits

• 10 MiB is large to fetch whole. Nothing consumes the index that way today; if something does, it needs a served index or a split by framework rather than a smaller excerpt.
• On a frozen-at-root build most modules share one last_verified — the snapshot commit's, because that is when those files were created. Accurate, but close to a constant.
• --auto self-retrieval is gated as a regression against a recorded baseline, not an absolute floor. scripts/retrieval-evals/baseline.json holds the last measured run (page-success@3 0.8596, page-MRR 0.7750, over 520 pages / 4,228 modules); a run fails if either metric drops more than AUTO_TOLERANCE (0.03) below it, with absolute backstops of 0.60 / 0.40 underneath. An absolute floor was the wrong instrument: this corpus is ~11 near-duplicate copies of the same prose, so every page competes with its own siblings and adding an SDK would have failed the gate for a reason unrelated to retrieval quality. Re-record with --update-baseline after any change to what is indexed, and say so in the commit.
• One glob divergence from minimatch, unreachable today: * and whole-segment ** here also match a segment beginning with ., where minimatch defaults to dot: false. No doc source is dot-prefixed.

---

Scoring (updated after review)

The proxy retriever originally ranked on overlap / sqrt(|q| * |d|). |q| is constant across the documents of one query, so that reduced to overlap / sqrt(|d|) - which pays a document for being short: a 10-token stub matching one query term scored 0.316 against 0.200 for a 100-token page matching two.

It now uses BM25 over the same binary term representation: IDF weighs a rare term above a common one, and the length term normalises against the corpus average with b=0.75. Term frequency stays binary because docText() is read as a Set - the fields it concatenates already repeat the title and slug, so a raw count would measure field layout rather than aboutness.

The --auto half carried a second copy of the old formula in fastScore, and that is the half the baseline and the gate are computed from - so fixing only score() would have changed nothing that is measured. Both now call one makeScorer.

Measured on one index, changing only the scorer:

	old	new
page-success@3	0.7962	0.8423	+0.0461
page-MRR	0.6981	0.7696	+0.0715
pages missed	106	82	-24

The 20-query gold set is unchanged at success@3 0.95 / precision@3 0.8667 / MRR 0.95, with the same single miss - it is too small to register a ranking change of this size, which is itself worth knowing about what that set can detect.

Freshness

run.cjs reports last_verified coverage on every run (currently 4228/4228 dated, 2025-12-12 to 2026-09-18, 2 older than 180 days), so the full clone docs-retrieval-evals.yml takes buys a signal that is actually read. Passing --require-freshness - which only that workflow does - turns a fully dateless index into a failure, which is what losing fetch-depth: 0 would look like. It is deliberately not a ranking input: last_verified is a date, and the scorer tokenises on [a-z0-9]{2,}, so it would enter the term stream as 2026/09/18 and match any query mentioning those numbers.

build-docs.yml is shallow on pull_request: that job builds and verifies but never publishes, so the freshness signal there was computed and discarded on every PR to the repo.

Two later corrections to the gate (after review)

Ranking unit. --auto counted competing chunks while search() spends one slot per page, so three chunks of one rival page consumed all three slots and scored a miss that the gold-set path scores a hit. That is the half baseline.json and the CI gate are computed from, and it moved with chunk counts - re-chunking a rival page changed the score with no change in retrieval quality. Both halves now count distinct pages, verified by an independent harness that computes each page rank through both paths: 120 sampled pages, 120 agree, 0 disagree. The corrected figures are 0.8596 / 0.7750 with 73 misses, against 0.8404 / 0.7676 and 82 before, so the old metric understated page retrieval by about two points.

Product keys. detectProduct returned the raw URL segment, but a route does not always spell its product key. 609 modules shipped under label-capture and matrixscan, neither of which exists in products.json, while the real smart-label-capture and matrixscan-batch had no pages at all. The alias map is now derived from the registry own frameworks[].apiUrl rather than listed.

baseline.json is current at 0.8596 / 0.7750.

[lucatorella]

🤖 Two build/deploy-integrity findings inline.

[lucatorella]

🤖 Re-reviewed 65676e09..d948727b. One finding on the new metric; notes on the two earlier threads.

[raffaelefarinaro]

🤖 This review was AI-assisted. I verified each blocking finding by hand against the code and a local build before posting.

Starting with what works, because it is genuinely careful. The exclusion logic is correct, and I checked it against the built output rather than reading it: zero URLs from the frozen versions, the external data-capture-sdk reference, or any of the 235 *.html redirect stubs make it into the index. Build cost is not a regression, Build Documentation on this branch ran 3m29s to 4m08s against 3m36s to 4m00s on recent main. And the eval gates sit far above chance, since a random retriever over this corpus would score success@3 = 0.158 against your floor of 0.8, with 0.900 actual.

Your three open threads are already fixed, so close them

You have probably been looking at three red threads for six days. They are stale, not outstanding:

• cheerio and gray-matter are both declared in dependencies as of 1748eaf, with matching entries in both lockfiles.
• The zero-modules floor check at index.ts:697 and the .tmp plus rename writes at index.ts:712 landed in the same commit, which is exactly what the thread asked for.
• Recall was removed and replaced with an honestly named MIN_PRECISION in 972e6cb, plus a comment explaining the algebra.

Luca's re-confirm was against d948727b, which is six commits behind the current head 2a6edd5. I checked the recall claim against the built corpus rather than taking it on trust, and he was right: every one of the 20 gold entries resolves to between 31 and 1075 relevant modules against K = 3, so capped recall did reduce to precision. The fix is the right one.

Rebase before responding to anything else here

The last four commits, which add the entire frontmatter-ingestion feature, have zero CI runs. Here is why. main deleted package-lock.json in f23a28f (#416), and this branch still edits it, so git merge-tree reports a modify/delete conflict on package-lock.json plus a content conflict in package.json. GitHub cannot build the refs/pull/418/merge ref for a conflicted PR, so no pull_request run gets created. Runs exist and are green for the first five commits and then stop dead on 2026-08-05 at 12:53Z. gh pr checks 418 reports "no checks" because it queries head 2a6edd5 specifically.

A rebase onto main plus deleting package-lock.json fixes the conflict, restores CI, and picks up docs-gate.yml, which does not exist on this branch at all. Do that first, because CI will probably surface more than any human reader can, and it would be wasteful to work through review comments against a head that has never been built.

Provenance of the numbers

The corpus statistics below (4523 records, 89% at the 400-character cap, 219 Titanium modules, 26.9 MB, the random-retriever baseline) come from my own local build on Node 26 with npm ci, not from CI on Node 18 with yarn. My counts came out at 4523 modules against CI's 4526 at 972e6cb, a 0.07% difference I attribute to the four intervening commits. Treat the figures as indicative of magnitude, not exact.

What is in the inline comments

Five blocking: the package-lock.json conflict, the Titanium trees, the chunk truncation, the contradictory core availability edges, and the division of labour with docusaurus-plugin-llms. Three smaller ones: a substring match in pickIntents, MIN_AUTO_SUCCESS defaulting to zero, and last_verified being the build timestamp.

Two of these are product decisions more than defects, so I have put them as questions about intent rather than verdicts. I also could not see who consumes these artifacts, so my point about truncation argues from the plugin's own stated purpose in its header comment, not from a requirement I can verify. If a consumer exists that only needs pointers plus a snippet, that finding weakens a lot and I would rather hear that from you than assume it.

I have left a longer writeup with the non-blocking observations out of this review to keep it readable. Happy to walk through it whenever suits.

[raffaelefarinaro]

🤖 Automated review, posted on Raffa's behalf and not yet read by him. Treat the findings as a starting point, not a verdict. Anything that looks wrong probably is, so push back.

Cheapest fix that unblocks the most. The current head (c8308df) has never actually run through CI. gh pr checks 418 reports zero checks, and commits/c8308df/check-runs confirms it: no check-runs at all. The PR is CONFLICTING with main (mergeable_state: dirty), and git merge-tree shows exactly one real textual conflict in the whole diff, in package.json's scripts block (main added four api-reference-seo scripts at the same insertion point this branch adds docs:retrieval-evals). A conflicted PR gets no pull_request run because GitHub can't build the merge ref, so the last green CI run on record is for be5c0a04, two commits behind head — the per-page search dedup fix and the chip-announce fix haven't been through CI at all yet. Inline comment on the exact spot.

What's good. The knowledge-extractor is unusually disciplined for a build-time HTML-to-text pipeline: it fails the build loudly (not silently) on empty extraction, a >50% page-error ratio, or a broken excerpt invariant (dangling code fence, or an excerpt ending on a heading/label with nothing under it), and nearly every one of those guards cites a specific measured incident in its own comment rather than a hypothetical. The last_verified handling — shallow-clone detection via git rev-parse, %ct instead of %cI to dodge cross-timezone string sorting — is the kind of detail that's easy to get subtly wrong, and it isn't here.

PR description vs. what's actually committed — question about intent, not a defect. "Known limits" says --auto self-retrieval is "gated at 0.80, against a measured 0.8493 over 531 pages / 4,386 modules." scripts/retrieval-evals/baseline.json on this head is dated the same day (2026-09-18) and records page_success_at_k: 0.7876, page_mrr: 0.6895, 532 pages / 4364 modules — and the gating in run.cjs isn't a static 0.80 floor anymore, it's a regression-against-baseline check (AUTO_TOLERANCE 0.03) with a 0.60 backstop (AUTO_FLOOR). Is the description meant to be refreshed before merge, or is there a newer baseline that hasn't landed?

"Extraction failures are non-fatal" is broader than what the code does. Several classes of failure are deliberately fatal by design: zero pages extracted, a >50% page-error ratio, a missing or malformed customFields.assistantIgnoreFiles, an ignore-glob using an unsupported character, and a broken excerpt invariant all throw and fail docusaurus build — on purpose, per the comments ("fail LOUD ... matches the config's onBrokenLinks:"throw" convention"). That's a reasonable design, but it's the opposite of "never block a deploy." Worth tightening the description to say per-page failures are non-fatal, since systemic ones are intentionally not?

Existing threads, checked against head:

• src/components/FeatureList/styles.module.css:135 (Raffa, aria-disabled / screen-reader announcement) — fixed by c8308df ("Announce the unavailable chip as unavailable"). Current index.tsx adds aria-disabled="true", a title, and a visuallyHidden "(not available)" suffix exactly as asked. moritzhartmeier's "this seems to be unaddressed" ping (14:41) landed 5 minutes before that commit (15:46 UTC+1) — stale, recommend closing.
• scripts/retrieval-evals/run.cjs (moritzhartmeier, search() has no per-URL dedup) — fixed by 4a4a63b ("Give the gold-set search one slot per page, not per chunk"), committed ~15:39, after the 14:30 comment. GitHub already marked the thread outdated; recommend closing too.
• scripts/retrieval-evals/run.cjs:121 (moritzhartmeier, score()'s length normalization makes small-vocabulary pages universal attractors) — still open and still accurate at head; no commit has touched score() since. Not stale, leave it.

Full non-blocking list, including a couple of smaller reuse/cost notes, is in the linked vault doc.

[raffaelefarinaro]

Blocking for merge (not a code defect): this conflicts with main. Main added verify:api-reference-seo / test:api-reference-seo / test:api-reference-seo-verdicts / discover:api-reference-lines at this same insertion point, and git merge-tree $(git merge-base origin/main HEAD) origin/main HEAD shows a genuine <<<<<<< conflict right here — the only one anywhere in the diff. This is also why CI shows zero checks on the current head (c8308df): a conflicted PR gets no pull_request run because GitHub can't compute a merge ref. The last green CI run on record is for be5c0a04, two commits back — so the two newest commits (the per-page search dedup and the chip aria-announce fix) haven't actually been validated by CI. Four lines to combine once this rebases onto main.

[eugenia-scandit]

Resolved in the 77d5651 merge commit — both the package.json script-block conflict and the earlier package-lock.json modify/delete. git merge-tree $(git merge-base origin/main HEAD) origin/main HEAD is clean at this head, and the concurrency group on docs-retrieval-evals.yml went in with the same commit.

Closing this thread.

[raffaelefarinaro]

Non-blocking, reuse question: docs-preview.yml already has concurrency: { group: docs-preview-${{ github.event.number }}, cancel-in-progress: true } for exactly this situation. This workflow's pull_request trigger has no concurrency group, and each run does a full yarn build plus two eval passes. This PR alone has ~30 commits touching paths this workflow watches, so without a concurrency group those are ~30 overlapping full builds queued rather than superseded. Worth the same pattern here?

[eugenia-scandit]

Added in the 77d5651 merge commit — docs-retrieval-evals.yml now carries the same concurrency group as docs-preview.yml.

Closing this thread.

[raffaelefarinaro]

🤖 Automated review, posted on Raffa's behalf and not yet read by him. Treat the findings as a starting point, not a verdict. Anything that looks wrong probably is, so push back.

CI is green and the head is mergeable against main. The most useful thing right now: the two conflict threads that were blocking review (the package.json script-block conflict and the earlier package-lock.json modify/delete conflict) are both resolved as of the merge commit 77d5651, which explicitly documents resolving the one remaining conflict and also adds the concurrency group to docs-retrieval-evals.yml. git merge-tree $(git merge-base origin/main HEAD) origin/main HEAD shows a clean merge, no conflict markers. Both threads can close.

What's good: the postBuild fail-loud guards (zero-extraction, <50% page success ratio, assertArtifactInvariants) now live in the plugin itself with no swallowing catch around them, so a selector-drift regression fails the build instead of silently shipping an empty index. The SYNTHETIC_PRODUCTS fix is also solid: excluding "core"/"general" from availability-edge generation, driven off products.json rather than a path-shape guess, closes the self-contradicting AvailableOn/NotAvailableOn edges cleanly. And the amount of measured verification in the comments (module counts, blast radius before/after a regex change, timing) is the right level of rigor for a plugin that gates every docs build.

Status of existing threads at this head (77d5651), so the still-open ones aren't lost in the noise:

Resolved, recommend closing:

• cheerio undeclared dependency: cheerio and gray-matter are now real package.json dependencies with exact versions, and yarn.lock carries a matching pinned resolution.
• "Nothing asserts extraction succeeded": fully fixed, not just partially as the Aug 11 follow-up said. The empty-index and low-success-ratio throws are in the plugin's own postBuild now, not only in the separate eval script.
• recall@k == precision@k: recall was dropped entirely (commit 972e6cb).
• " auth" substring match: fixed with a word-boundary regex, verified against the built HTML (27 document-verification false positives vs 2 real security mentions).
• Titanium tree indexed despite the repo's own curation decision: fixed via a shared assistantIgnoreFiles export consumed by both AI-export plugins; corpus dropped from 4,637 to 4,386 modules with zero from /sdks/titanium/.
• docusaurus-plugin-llms division of labour: now stated in the plugin header, next to the config registration, and in the PR description.
• servesCurrent / frozen-version branch: re-verified with DOCS_LAST_VERSION actually set, after two rounds of the author catching their own gaps.
• --min-auto-success defaulting to 0: now derives a real floor from baseline.json with tolerance, and --auto is actually wired into docs-retrieval-evals.yml.
• FeatureList unavailable chip not announced to screen readers: fixed by c8308df ("Announce the unavailable chip as unavailable"). Worth noting the timing: the Sept 18 "this seems unaddressed" ping landed at 14:41:53Z, and the fix commit landed at 14:46:54Z, five minutes later. Nobody was wrong, just crossed in flight.
• No per-URL dedup in the gold-set search(): fixed by 4a4a63b (one slot per page).
• package.json/package-lock.json conflicts and the missing concurrency group on docs-retrieval-evals.yml: both fixed in the 77d5651 merge commit itself, as above.

Still open, not re-flagged inline since the threads already exist:

• The score() length-normalization issue (moritzhartmeier, Sept 18): unchanged at scripts/retrieval-evals/run.cjs:116-122. The gate still uses overlap / sqrt(|q| * |d|), so a small-vocabulary page can still win on denominator alone rather than actual relevance. This only affects the eval script's own signal quality, not production data, but as long as it stands the gate's precision numbers are a weaker check than they look.
• The excerpt-truncation design question (Aug 11 / Sept 8, with eugenia's pushback): still an open disagreement rather than a bug at this point, since the author's counter-argument (api_refs/references/keywords are derived from the full chunk, not discarded) is partly right and partly not. api_refs and references do come from parsing the chunk's HTML links, so that part holds. keywords, though, is built from the page slug, product, framework, contentType and frontmatter (src/plugins/knowledge-extractor/index.ts:1490-1494), not from the chunk prose at all, so it doesn't actually support "the chunk isn't discarded." Is 400/300-char excerpts intentionally the final design, or a placeholder pending a consumer that wants more?

One new item, inline: build-docs.yml's checkout now always does fetch-depth: 0, on pull_request, push, schedule, and workflow_dispatch alike, and this job has no path filter, so it runs on every PR to the repo. But this job never publishes the generated index (no deploy step, just build + verify), so last_verified accuracy only matters on the actual deploy path. docs-preview.yml already draws exactly this distinction and stays at fetch-depth: 1 because "a full clone would buy a freshness signal nobody computes" there. Measured checkout time on the current head's CI run (job 105649872300): 14 seconds. Not alarming on its own, but it's a cost paid forever, on every PR, for a value only the push-to-main run needs. Worth asking whether this should follow the preview workflow's precedent and stay shallow except on push to main.

Non-blocking notes and the rest of the thread audit are in the full write-up: memory-vault/work/projects/active/docs-improvement/review-pr418.md in the ciao repo.

[raffaelefarinaro]

Non-blocking, cost/reuse question: this job (pull_request on main and release/**, push to main, schedule, workflow_dispatch, no path filter) runs on every PR to the repo, but it never publishes the generated index (build + verify steps only, no deploy). last_verified accuracy only matters on the actual deploy path.

docs-preview.yml already draws this line and stays at fetch-depth: 1 specifically because "a full clone would buy a freshness signal nobody computes" on a build that doesn't publish. Measured on the current head's CI run (job 105649872300): the checkout step took 14 seconds. Small, but it's paid on every PR/schedule/workflow_dispatch run forever, for a value only the push-to-main run needs.

Is fetch-depth: 0 here deliberate for all triggers, or should it follow the same pattern as docs-preview.yml and stay shallow except on push to main?

[eugenia-scandit]

You're right on both halves, and the second half is worse than you put it.

Checked before changing anything:

1. This job really does not publish. Its steps are checkout, setup, install, build, then test:search-facets, test:api-reference-seo, test:api-reference-seo-verdicts, verify:search-tags, verify canonical tags. No deploy step — and in fact no workflow in the repo publishes the index. So last_verified accuracy here buys nothing on any trigger, not just on PRs.

2. A shallow clone cannot turn this job red. knowledge-extractor/index.ts:1080 checks git rev-parse --is-shallow-repository, warns, and returns empty dates. Nothing asserts on last_verified — not assertArtifactInvariants, not any verify step. So going shallow costs the freshness signal and nothing else.

Fixed by making it conditional rather than flat:

fetch-depth: ${{ github.event_name == 'pull_request' && 1 || 0 }}

Shallow on PRs, which is the trigger with no path filter that pays the 14s on every PR to the repo; full on push, schedule and workflow_dispatch, where the artifact is what a deploy or a hand-run inspection reads and the cost is paid once.

Separately, your comment exposed a stale claim in the precedent you cited. docs-preview.yml said:

build-docs.yml, which does publish the artifact, still fetches full history - do not copy this value there.

build-docs.yml does not publish the artifact. That comment was instructing future readers not to make exactly the change you're asking for, on a false premise. Corrected in the same commit.

One I noticed and am deliberately not changing without a second opinion: docs-retrieval-evals.yml:62 also sets fetch-depth: 0, and the eval scorer reads title, summary, docs_excerpt, assistant_excerpt, keywords, intents — never last_verified. So that one appears to be over-fetching too. It has a path filter and runs far less often, and it's outside what you flagged, so I'd rather ask than widen the diff: want it shallow as well?

[eugenia-scandit]

Follow-up on the docs-retrieval-evals.yml question I left open above — resolved the other way, and I think it's the better answer.

Rather than making that job shallow too, the full clone now buys something. run.cjs reports freshness coverage on every run:

Freshness: 4228/4228 modules carry a last_verified date.
  oldest 2025-12-12, newest 2026-09-18, 2 older than 180 days (before 2026-03-25).

And it guards the setting that produces it. If not one module carries a date — exactly what a shallow clone yields, since the extractor emits "" rather than a constant that looks like data — the run fails in CI and names the workflow and the line that must have been lost. Locally it warns and carries on, because a shallow clone is a legitimate state to develop in. Verified both ways against an index with every date blanked: exit 1 under CI, exit 0 without it.

That turns your observation into a check: the cost is now justified, and dropping fetch-depth: 0 there can no longer be silent.

build-docs.yml still goes shallow on pull_request as described above — that job genuinely has no use for the signal, and this is what the difference between the two looks like now.

One thing I deliberately did not do, since it was suggested and is worth recording as rejected: feed last_verified into the ranking. It's a date, and the scorer tokenises on [a-z0-9]{2,}, so 2026-09-18 enters the term stream as 2026, 09, 18 — a query like "scandit 18 digit barcode" would then match every page verified on the 18th. Recency is not relevance, and mixing them would degrade the metric while looking like an improvement. It stays a report.

Retrieval numbers unchanged by this commit: gold set 0.95 / 0.8667 / 0.95, auto 0.8423 / 0.7696.

[raffaelefarinaro]

🤖 Automated review, posted on Raffa's behalf and not yet read by him. Treat the findings as a starting point, not a verdict. Anything that looks wrong probably is, so push back.

Cheapest fix that unblocks the most: the checked-numeric-flag fix in scripts/retrieval-evals/run.cjs (this branch, "refuse a threshold that is not a number") only converted some of the --auto flags. AUTO_FLOOR, AUTO_MRR_FLOOR, and MIN_AUTO_MRR are still bare parseFloat, sitting three lines below the num() reader that was written specifically to close this hole. Inline comment below with the exact lines.

What's good, concretely: the BM25 rewrite is real and its numbers check out against the actual CI run, not just the PR description — I pulled the Docs Retrieval Evals log for this head (run 35617057715) and it prints page-success@3 = 0.8596 / page-MRR = 0.775 over 520 pages / 4228 modules, matching baseline.json exactly. The drift-guard fix (excluding plugin-client-redirects' meta-refresh stubs from both terms of the page-success ratio) is a legitimate postBuild-race bug caught and fixed with a measured before/after (0.843 vs 0.391 against a 0.5 threshold) rather than asserted. And detectProduct's alias map is genuinely derived from products.json's own frameworks[].apiUrl rather than a second hardcoded list — I checked it against the registry directly and it produces exactly the two aliases the commit claims (matrixscan→matrixscan-batch, label-capture→smart-label-capture) and identity for the other eleven.

Thread audit against the current head (8a55edd), so nothing already fixed gets re-litigated:

Resolved, safe to close:

• cheerio/gray-matter undeclared deps (lucatorella) — both are real package.json dependencies now.
• Empty-extraction / low-success-ratio not asserted (lucatorella) — both throw in the plugin's own postBuild, verified at lines ~2201 and ~2231.
• recall@k == precision@k (lucatorella) — recall was dropped entirely.
• Titanium indexed despite llmsIgnoredSdkTrees (Aug 11) — fixed via the shared assistantIgnoreFiles export, verified 4,637→4,386 modules with zero from /sdks/titanium/.
• " auth" / "fix" bare-substring intent matches (Aug 11, and the same defect found again in pickIntents's troubleshoot test on this branch) — both now word-bounded.
• MIN_AUTO_SUCCESS defaulting to 0 (Aug 11) — now derives a real floor from baseline.json with tolerance, and --auto is wired into CI.
• score()'s length-normalization letting the feature-availability matrix win single-product queries, and search() having no per-page dedup (moritzhartmeier, Sept 18) — both fixed by the BM25 rewrite and the page-level dedup in search(); the ranking-unit fix (chunks vs. pages) on the --auto side landed in the same round and was verified with an independent 120-page harness (120 agree, 0 disagree).
• package.json/package-lock.json conflicts and the missing concurrency group on docs-retrieval-evals.yml (Sept 18/19) — resolved in the referenced merge commit; current mergeable: true (state blocked only on the pending review, not a conflict).
• build-docs.yml full-cloning on every trigger with no path filter (Sept 19 finding) — now shallow (fetch-depth: 1) on every trigger, with the rationale that this job never publishes what a full clone would improve.

Still open, on purpose — not re-flagged inline since the thread exists:

• The FeatureList table-view accessibility thread, reopened by eugenia on this head. The display:none removal and container layout are correct given the code as fixed, but she's right that the whole table path is dead code (50/50 call sites use displayMode="compact"). Worth deciding as a product question rather than in this PR: does the non-compact table view need to exist at all, or should it (and the a11y work riding on it) be deleted until something calls it?

One more non-blocking finding, inline: a latent alias-collision gap in the same product-canonicalization commit.

Full write-up, including the items above with commit references and a couple of lower-priority notes (a markdown-link regex that truncates on a literal ) in an href), is in memory-vault/work/projects/active/docs-improvement/review-pr418.md in the ciao repo.

[raffaelefarinaro]

This line and the next two are still bare parseFloat(arg(...)), not routed through the num() checked reader defined a few lines up in this same commit ("Parsed through a checked reader, NOT bare parseFloat" / "refuse a threshold that is not a number"). AUTO_TOLERANCE right above got the fix; AUTO_FLOOR, AUTO_MRR_FLOOR, and MIN_AUTO_MRR didn't.

Concretely: --auto-mrr-floor abc (or any non-numeric value) yields NaN, and metrics.page_mrr < mrrFloor at line 418 is then always false — the gate reports "ok" regardless of the real score, which is the exact hazard this commit's own header comment says was closed. Not live today since no workflow passes these flags with a bad value, same as the MIN_AUTO_SUCCESS-defaults-to-0 issue from the Aug 11 thread — but it's a one-line fix (num("auto-floor", "0.60", parseFloat) etc.) and the checked reader is already sitting right above it.

[eugenia-scandit]

Right, and it's a bad miss — I wrote num() in that commit specifically to close this, converted the line above these three, and stopped. A header comment claiming the hazard was closed while three lines beneath it left it open is worse than not having written the reader, because it tells the next reader not to check.

Fixed in 74b5eec. All three now go through num():

const AUTO_FLOOR = num("auto-floor", "0.60", parseFloat);
const AUTO_MRR_FLOOR = num("auto-mrr-floor", "0.40", parseFloat);
const MIN_AUTO_MRR = num("min-auto-mrr", "0", parseFloat);

Verified each one rather than assuming the shared reader covers them:

--auto-floor abc      -> retrieval-evals: --auto-floor is "abc", which is not a number.      exit 1
--auto-mrr-floor abc  -> retrieval-evals: --auto-mrr-floor is "abc", which is not a number.  exit 1
--min-auto-mrr abc    -> retrieval-evals: --min-auto-mrr is "abc", which is not a number.    exit 1
valid args            -> page-success@3 = 0.8596, delta +0                                   exit 0

That is now every numeric flag the script takes — I checked the file for remaining parseFloat(arg( / parseInt(arg( call sites and there are none.

[raffaelefarinaro]

Non-blocking. The guard here (!PRODUCT_KEYS.has(seg)) stops a route segment from hijacking another product's real key, but it doesn't stop two different products from deriving the same alias segment — aliases.set(seg, key) would just overwrite with whichever product is later in products.json's array, silently, with no signal that it happened. Not reachable with the current registry (checked: only two aliases exist today, matrixscan→matrixscan-batch and label-capture→smart-label-capture, on disjoint segments), but a third product adopting an ambiguous URL segment later would misattribute pages rather than fail loud — which is the opposite of how every other silent-failure path in this file is handled (e.g. the ignore-glob and missing-ignoreFiles throws a few hundred lines down).

[eugenia-scandit]

Agreed, and fixed in 74b5eec rather than left as a note — the argument that it is unreachable today is the same argument that would have justified leaving the original misattribution alone.

The guard checked that a segment does not collide with a real key, but not that two products do not derive the same alias. aliases.set() is last-write-wins, so the segment would go to whichever product sits later in products.json, every page under it would be reattributed, and nothing would record that a choice was made. Misattributing a product is precisely what this map was added to fix, so resolving it by array order reintroduces the bug in a form that is harder to see than the one it replaced.

It now throws and names both products, matching the ignore-glob and missing-ignoreFiles checks a few hundred lines down:

products.json: the route segment "label-capture" is claimed by both
"smart-label-capture" and "matrixscan-batch" through their frameworks[].apiUrl.

Throw rather than warn for the reason you give: reaching it means products.json is ambiguous about which product owns a route, and there is no fallback this plugin can pick that is the right answer to that.

Verified against the real registry, including the case that must not trip it:

case	result
real products.json	exactly matrixscan -> matrixscan-batch, label-capture -> smart-label-capture, no throw
one product repeating a segment across 11 frameworks	no throw — this is the ordinary case, and a naive collision check would have broken every build
two products claiming one segment	throws, naming both

That middle row was the thing worth checking: every product emits the same segment once per framework, so a guard that fired on any repeat would have failed on the current registry immediately.

[raffaelefarinaro]

🤖 Automated review, posted on Raffa's behalf and not yet read by him. Treat the findings as a starting point, not a verdict. Anything that looks wrong probably is, so push back.

Cheapest fix that unblocks the most: the PR has a fresh merge conflict with main again, in package.json's scripts block. git merge-tree $(git merge-base origin/main HEAD) origin/main HEAD on the current head (b5c57d3) shows one real conflict: main's #430 (same author, merged at 804180a, about 37 minutes after this branch's last commit) added verify:frameworks/test:frameworks/test:docs-gate at the same insertion point this branch adds docs:retrieval-evals. The GitHub API confirms it, mergeable: false and mergeable_state: "dirty", checked twice a few minutes apart. Same shape of conflict that blocked review twice before, just a new instance because main moved again. CI on the current head is green across all 6 checks, so this is a rebase, not a code problem. Inline comment on the exact spot.

What's good, concretely. I pulled the actual Docs Retrieval Evals log for the current head (run 35713917584) rather than trusting the PR description: it prints page-success@3 = 0.8596 and page-MRR = 0.775 over 520 pages / 4228 modules, matching baseline.json exactly, delta +0. The newest commit, b5c57d3, is careful work: it caught a real regression in the commit right before it. The alias-collision throw added in 74b5eec sat inside loadProducts's bare try, so the check meant to fail loud on a contradictory products.json would instead have been swallowed, leaving PRODUCT_KEYS empty and collapsing every /sdks/ page's product onto "core" or "general" on a green build - worse than the last-write-wins bug it replaced. I checked the restructuring: reading the registry is now the only thing inside the try, so a missing or unparseable file still degrades gracefully, but a genuinely contradictory products.json now throws and reaches the surface. The other four fixes in that commit also check out: shared fence-balancing between clipMarkdown's two early-return paths, a readBaseline deadlock where --update-baseline could never reach the write that repairs a bad baseline, and unguarded versions.json parsing that would have silently mislabeled frozen-version pages as duplicates of current.

Thread audit against this head. Everything previously open is resolved:

• cheerio/gray-matter undeclared deps (lucatorella) - both are real package.json dependencies with matching yarn.lock entries.
• Empty-extraction / low page-success-ratio not asserted (lucatorella) - postBuild throws directly now (the pagesProcessed === 0 || index.length === 0 check around line 2304, the 50% ratio check around line 2335), not just the eval script.
• recall@k algebraically equal to precision@k (lucatorella) - the metric was removed rather than patched.
• AUTO_FLOOR/AUTO_MRR_FLOOR/MIN_AUTO_MRR left as bare parseFloat (flagged two rounds ago) - fixed in 74b5eec, all three now go through the checked num() reader.
• Titanium indexed despite llmsIgnoredSdkTrees, the bare-substring " auth"/"fix" intent matches, the llms-plugin division-of-labor question, build-docs.yml full-cloning with no concurrency group, and the earlier package-lock.json conflict - all confirmed resolved in earlier rounds and still hold on this head.

Still legitimately open, not stale: the FeatureList table-view accessibility thread. Eugenia's reopening of it holds up under an independent check - every <FeatureList> call site in docs/, versioned_docs/ and src/ passes displayMode="compact", so renderTableView (and the aria-disabled plus visually-hidden fix on its chip) never runs today. That's a real open product question, not a defect: does the table view need to exist at all, or is the honest cleanup deleting it along with the accessibility work riding on it? Worth leaving open until that's answered rather than closing as stale.

One new, non-blocking finding inline: classifyLinks's link regex truncates any href containing a literal ) before the link's real closing paren. Small blast radius, plausible for both external URLs and API-reference fragments, worth a one-line fix.

Full write-up, including this at more length, is in memory-vault/work/projects/active/docs-improvement/review-pr418.md in the ciao repo.

[raffaelefarinaro]

Blocking for merge, not a code defect: fresh conflict with main. git merge-tree $(git merge-base origin/main HEAD) origin/main HEAD on this head (b5c57d3) shows a real conflict right here - main's #430 (same author, merged at 804180a, ~37 min after this branch's last commit) added verify:frameworks/test:frameworks/test:docs-gate at the same insertion point this branch adds docs:retrieval-evals. gh api pulls/418 confirms mergeable: false, mergeable_state: "dirty", checked twice a few minutes apart. CI on the current head is green, so this is a rebase, not a regression - same shape of conflict as the two earlier rounds in this PR, just a fresh instance because main advanced again since the last sync.

[raffaelefarinaro]

Non-blocking: this capture group stops at the first literal ), not the one that actually closes the markdown link. Verified: [Data Matrix](https://en.wikipedia.org/wiki/Data_Matrix_(symbology)) captures href as https://en.wikipedia.org/wiki/Data_Matrix_(symbology - truncated, missing the real closing paren and anything after it. External links like that will usually just fail the site// prefix checks below and get dropped silently, but the same shape hits an API-reference fragment like #init(context:), which would land in api.add() already truncated. A balanced-paren match, or matching up to the last ) on the line, would close it.

[raffaelefarinaro]

🤖 Automated review, posted on Raffa's behalf and not yet read by him. Treat the findings as a starting point, not a verdict. Anything that looks wrong probably is, so push back.

Cheapest fix that unblocks the most: there isn't one today, because both blocking items from yesterday's round are already fixed on this head. 06dfdd3 merges main (resolving the package.json scripts-block conflict as a real union - all four script sets coexist at the same insertion point, none overwriting another) and fixes the link-regex truncation flagged yesterday. gh api pulls/418 now reports mergeable: true, CI is 6/6 green on this exact head, and the retrieval-evals log for this head (run 35836621420) prints page-success@3 = 0.8596 / page-MRR = 0.775 over 520 pages / 4228 modules, matching baseline.json exactly, delta +0.

What's good, concretely. The paren-balancing regex fix is correct, not just plausible - I traced both corpus examples cited in the commit message by hand (Data_Matrix_(symbology) and ns-scan.html#init(context:)) and the new pattern captures the full href in both cases, stopping at the real closing paren instead of the first literal one. And the package.json merge is a genuine union rather than a pick-one-side resolution: the scripts #430 added and docs:retrieval-evals from this branch all survive at the same insertion point.

Two small, non-blocking doc-accuracy findings, inline. The plugin's own header comment has drifted from the code it describes: it still says the two AI-export plugins share customFields.assistantIgnoreFiles, but the actual mechanism (both docusaurus.config.ts's own comment and the plugin code itself) deliberately moved to a per-plugin options.ignoreFiles, specifically to avoid a customFields key that has to be kept in step. The PR description repeats the same stale claim ("Both read customFields.assistantIgnoreFiles"). Separately, the header cites "4,386 modules" for the corpus - true before the Sept 22 BM25/freshness round, but the current number, in both baseline.json and this head's own CI run, is 4,228. Neither affects behavior, but both are exactly what a future maintainer will grep for and not find.

Thread audit against this head. Every previously open thread is now resolved:

• cheerio/gray-matter undeclared deps (lucatorella) - both real package.json dependencies with matching yarn.lock entries.
• Empty-extraction / low page-success-ratio not asserted (lucatorella) - postBuild throws directly; confirmed the zero-extraction check and the 50% ratio check are both there, not behind a swallowing catch.
• recall@k algebraically equal to precision@k (lucatorella) - the metric was removed, not patched.
• AUTO_FLOOR/AUTO_MRR_FLOOR/MIN_AUTO_MRR left as bare parseFloat (flagged two rounds ago) - confirmed all three now go through the checked num() reader.
• Alias-collision guard not stopping two products from claiming the same route segment (flagged as non-blocking two rounds ago) - confirmed fixed in b5c57d3: the collision throw now sits outside the file-read try, so a genuinely contradictory products.json reaches the surface instead of silently degrading to an empty PRODUCT_KEYS.
• Both package.json conflicts (Sept 18 and Sept 23 instances) and the link-regex truncation (Sept 23) - all fixed on this head, as above.
• Everything from the Aug 11 / Sept 8 / Sept 9 / Sept 18 / Sept 19 rounds (Titanium exclusion, bare " auth" substring match, last_verified build-timestamp bug, MIN_AUTO_SUCCESS defaulting to 0, FeatureList screen-reader announcement, score() length normalization, search() per-page dedup, docs-retrieval-evals.yml concurrency group, build-docs.yml shallow clone) - all re-checked and still hold, nothing regressed.

Still legitimately open, not stale: the FeatureList table-view accessibility thread. All 50 <FeatureList> call sites in the repo pass displayMode="compact", so renderTableView - and the aria-disabled/visually-hidden fix riding on it - never executes today. That's a real product question, not a defect: does the table view need to exist at all, or should it (and the accessibility work on it) be deleted until something actually calls it?

Also still open, as an acknowledged tradeoff rather than a bug: the 400/300-char excerpt truncation. The header now states the pointer-index design explicitly and correctly (api_refs/references come from the chunk's own links, not discarded), so this is answered as intentional - but nobody in the thread has named a concrete consumer that needs more than a pointer plus a snippet. Worth a firmer answer before merge if one exists.

Full write-up, including the header-comment drift at more length, is in memory-vault/work/projects/active/docs-improvement/review-pr418.md in the ciao repo.

[raffaelefarinaro]

Non-blocking, doc-accuracy: this cites "4,386 modules" for the corpus, which was the real count before the Sept 22 BM25/freshness round. baseline.json and this head's own CI run (page-success@3 = 0.8596, page-MRR = 0.775) both say 520 pages / 4228 modules. Small, but this header is where someone will look to understand the current shape of the index.

[raffaelefarinaro]

Non-blocking, doc-accuracy: this says the two AI-export plugins share customFields.assistantIgnoreFiles, but neither actually reads it. docusaurus.config.ts's own comment ("Neither assistantIgnoreFiles nor knowledgeIndexIgnoreFiles is exported [via customFields] here... each consumer takes its own list as a plugin option instead") and this file's code (options?.ignoreFiles and the "the ignoreFiles option is missing" error a few hundred lines down) confirm the real mechanism is a per-plugin option, not a customFields key. This sentence predates that refactor, and the PR description repeats the same stale claim ("Both read customFields.assistantIgnoreFiles").

[raffaelefarinaro]

🤖 Automated review, posted on Raffa's behalf and not yet read by him. Treat the findings as a starting point, not a verdict. Anything that looks wrong probably is, so push back.

Cheapest fix first: the PR description's first paragraph still says a missing or malformed customFields.knowledgeIndexIgnoreFiles is one of the throw conditions. That's stale. The mechanism changed during review (commit 59fbb07) to a plugin option instead (options.ignoreFiles here, ignoreFiles on docusaurus-plugin-llms), specifically so each consumer has one name rather than a customFields key that drifts from the list it mirrors. The code comment got fixed; the top-level description still repeats the exact claim thread #4090540829 flagged. One-line edit, and it saves the next reader from looking for a customFields entry that no longer exists.

What's good here: the plugin fails loud in the right places (empty extraction, a page-error ratio over 50%, an unbalanced excerpt fence) matching the repo's own onBrokenLinks: "throw" convention, and the artifact write rolls the index back to its previous content if the paired graph write fails, rather than leaving a mismatched pair on disk. The review trail is also unusually honest with itself - several replies walk back a prior claim once it didn't hold up under measurement (the "keywords are chunk-derived" claim, the llms-full.txt per-module correspondence claim), which is exactly the discipline the file's own comments ask of the next person touching it.

CI is green, 6/6, at the current head (2feeee1). One thing worth a sanity check before merge: gh api pulls/418 currently reports mergeable: false, mergeable_state: "dirty", but git merge-tree $(git merge-base origin/main HEAD) origin/main HEAD against the latest origin/main (875c305) shows zero conflict markers, and the pull_request-triggered checks (Build Docusaurus Site, Docs Retrieval Evals, etc.) did run and pass at this exact head - which they couldn't do if GitHub had failed to build the merge ref. Reads like a stale mergeability cache rather than a real conflict; worth refreshing rather than trusting the flag as-is.

Five inline threads look fixed but were never closed, so they're still showing red:

• #3720310854 / #3720500695 (cheerio imported but not a declared dependency): fixed same day in 1748eaf - cheerio is in dependencies in the current package.json. "Still open at d948727" is the last word posted in that thread, about an hour before the fix landed.
• #4079526048 (fresh conflict with main at b5c57d3): resolved by the 06dfdd36 merge-main commit; confirmed no conflict against current origin/main above.
• #4079526062 (link regex truncates at the first literal paren): the balanced-paren pattern is in the current code at index.ts:1176; 2feeee19 additionally walked back an oversold claim in the comment about what the truncation could have broken.
• #4090540817 (header citing a stale "4,386 modules"): fixed in 59fbb07, which stopped pinning exact figures in the comment and pointed at baseline.json / the build's own success-line output instead.
• #4090540829: same commit fixed the code comment's customFields claim - see the PR-description note above, since that part is still live.

One new item, non-blocking: build-docs.yml has no concurrency group, unlike docs-preview.yml and the new docs-retrieval-evals.yml, both of which got one during this review for the same reason - a full yarn build plus several test steps queuing on every push instead of the newest one superseding the rest. This job has no paths: filter, so it runs on every PR to the repo, not just this one; a PR with this many commits queues that many redundant full builds here too. Left an inline note on the touched line.

Also non-blocking: the extractor is about 2,456 lines of glob compiling, regex classification, chunk clipping and graph mining, and its correctness today is established by measuring against the real corpus during review (counts pasted into replies) plus the retrieval evals, not by anything that pins a behavior and fails fast on a regression. The repo already has the pattern for this (test:frameworks, test:docs-gate, test:search-facets, test:api-reference-seo) - a handful of deterministic cases for the glob compiler and the intent classifiers would catch the next word-boundary-style regression (like the two pickIntents substring bugs this thread already found) without needing a full rebuild and a manual count to notice it.

Left open by design, not re-asking: whether FeatureList's non-compact view (the one the accessibility fix in this PR made internally coherent) should exist at all, given all current usages pass displayMode="compact". Already on the thread; flagging only that it's still an open call, not a resolved one.

[raffaelefarinaro]

Non-blocking, reuse: this job has no concurrency group, unlike docs-preview.yml and the new docs-retrieval-evals.yml, both of which got one during this review for the same reason (a full yarn build plus several test steps queuing on every push rather than the latest one winning). This workflow has no paths: filter, so every PR to the repo pays for that, not just this one - and this PR alone has roughly 30 commits that would have triggered it. Worth the same pattern, e.g. concurrency: { group: build-docs-${{ github.event.number || github.sha }}, cancel-in-progress: true }.

[raffaelefarinaro]

🤖 Automated review, posted on Raffa's behalf and not yet read by him. Treat the findings as a starting point, not a verdict. Anything that looks wrong probably is, so push back.

Cheapest fix that unblocks the most, and a correction to yesterday's review: this PR has a real merge conflict against main right now, in three files (package.json, scripts/test-search-facets.cjs, docusaurus.config.ts). I checked with git merge-tree --write-tree origin/main HEAD, which runs git's actual merge algorithm rather than just diffing blobs, and it reports CONFLICT in all three. Two are trivial: package.json is the same recurring shape as before, main added test:robots at the same insertion point this branch adds docs:retrieval-evals (line 22), keep both lines. scripts/test-search-facets.cjs:184 is a real double-fix: PR #446 (merged yesterday, the 7.6.15 version bump) independently fixed the same hardcoded-tag bug this branch fixed, but via frozen[0] instead of this branch's LEGACY.replace("docusaurus_tag:", "") — since LEGACY = tag(frozen[0]) two lines up, they're the same value reached two ways, so either wins. docusaurus.config.ts is the substantive one: PR #436 ("Add robots.txt", merged 2026-09-24) added a robotsTxtPlugin and its own config additions in the same neighborhood this branch edits (the ignore-list refactor around line 105-160, and the plugins array around line 871). The two sets of changes don't actually overlap in what they do, just in where they land, so this should resolve to keeping both blocks, but it needs a human to do that.

On the correction itself: yesterday's review checked mergeability with the legacy two/three-argument git merge-tree and read "zero conflict markers" as evidence that the mergeable: false GitHub was reporting was a stale cache. I ran that same legacy form again today and it also comes back clean for docusaurus.config.ts and test-search-facets.cjs — but git merge-tree --write-tree against that exact same main commit (875c305) shows the conflict was already there yesterday. The legacy form doesn't do a real three-way text merge, so it's the wrong tool to clear a mergeable: false with; --write-tree (or just trusting the GitHub flag) is the one to use here going forward.

What's good, concretely: CI is still 6/6 green, verified against this exact head SHA (2feeee19..., matches every check run's own head_sha, not just the branch name). Nothing in the code changed since yesterday's round (last commit is still 2feeee1, from 2026-09-24), so the six earlier rounds' fixes all still hold — I re-checked the cheerio dependency, the balanced-paren link regex, the empty-extraction and page-error-ratio guards, and the FeatureList contrast fix, and all are exactly where the last review said they'd be.

Two threads from previous rounds are still legitimately open, not stale, since nothing has changed to resolve them: whether build-docs.yml should get a concurrency group like its two siblings now have (thread from yesterday, #4101679788, still unaddressed), and whether FeatureList's non-compact table view should exist at all given every one of the 50 call sites in the repo passes displayMode="compact" (re-verified this count directly against the source rather than trusting the prior number).

Full write-up, including the merge-conflict detail and the tool-choice correction at more length, is in memory-vault/work/projects/active/docs-improvement/review-pr418.md in the ciao repo.

[raffaelefarinaro]

Fresh instance of the recurring conflict, confirmed with git merge-tree --write-tree origin/main HEAD (git's real merge algorithm): main added test:robots at the same insertion point this branch adds docs:retrieval-evals. Mechanical to resolve, keep both script lines, but it's blocking the merge button right now and needs a rebase.

[raffaelefarinaro]

This line conflicts against current origin/main. PR #446 (merged yesterday, the 7.6.15 version bump) independently fixed the exact same hardcoded-tag problem this line fixes, but via a different route: main uses frozen[0] directly, this branch uses LEGACY.replace("docusaurus_tag:", ""). Since LEGACY = tag(frozen[0]) at line 123, the two expressions are the same value reached two ways — low risk to reconcile, either survives, but it is a genuine textual conflict and not an artifact of a stale mergeability flag.

[raffaelefarinaro]

This whole file now conflicts against current origin/main, confirmed with git merge-tree --write-tree (the legacy 3-arg git merge-tree used in earlier rounds under-reports this and reads clean, which is worth knowing for next time). PR #436 (robots.txt, merged 2026-09-24) added a robotsTxtPlugin function and wired it into the same plugins array and nearby ignore-list region this PR edits (assistantIgnoreFiles/llmsIgnoreFiles/knowledgeIndexIgnoreFiles around line 105-160, and the [knowledgeExtractor, ...] registration around line 871). The two additions don't overlap logically, each owns its own consts and its own plugin entry, so this should resolve to keeping both blocks — but git can't do that automatically given how close the insertion points are. Worth rebasing before a third file joins the conflict list.

[eugenia-scandit]

Closing this. Based on our testing, it isn't needed: Agent Skills, together with an MCP server that reads the live docs, retrieve information very well, so a build-time knowledge graph and retrieval index would have no consumer.

Thank you @raffaelefarinaro and everyone who reviewed it. The review rounds were thorough, and several findings (the llmsIgnoredSdkTrees mismatch, the truncated excerpts, last_verified) are worth keeping in mind for the docusaurus-plugin-llms export, which remains the AI-facing layer.

The one change here that stands on its own, the FeatureList chip for a framework with no API reference, moved to #451. The test-search-facets.cjs fix already reached main through #446.