Problem
Developers are getting unreliable answers from the docs AI. The reported failure mode is that answers cite outdated sources, link to moved code, or confidently answer from stale material.
One concrete example from Pioneer feedback:
- Asking about
AccountId surfaced an old protocol source path under crates/miden-objects/src/account/account_id/....
- The current code has moved into
crates/miden-protocol/src/account/account_id/....
The current site also embeds Cookbook docsbot via @cookbookdev/docsbot/react in src/theme/SearchBar.tsx. Given the poor answer quality, we should remove this integration rather than continue exposing it while we clean up source material.
There are also stale LLM-facing files in the docs repo:
static/skill.md still identifies itself as version 0.13.
static/skill.md still contains old protocol limits and terminology.
static/llms.txt includes stale page descriptions and older docs paths.
Why this matters
The docs AI is currently risky for developers because it can send them toward old APIs or moved source files. For Miden this is especially costly because many breaking changes landed across v0.13, v0.14, and current next, and the wrong answer can look plausible while being impossible to use.
Until the source/indexing story is reliable, the site should not ship a chatbot that can create false confidence. Local search plus accurate LLM-facing files is a safer baseline.
Proposed scope
- Remove the Cookbook docsbot integration from the Docusaurus site.
- Remove the
@cookbookdev/docsbot dependency if it is no longer used.
- Refresh
static/skill.md for the currently supported docs version.
- Refresh
static/llms.txt so it points at current canonical pages and does not advertise stale SDK/reference versions.
- Remove or clearly version any stale source references that remain useful only for older docs snapshots.
- Add a release/docs checklist item so LLM-facing source files are updated when a new docs version is cut.
Acceptance criteria
- The site no longer renders the Cookbook docsbot widget.
@cookbookdev/docsbot is removed from dependencies if unused.
/skill.md reflects the current stable docs version and current protocol/client concepts.
/llms.txt points to valid current docs pages and does not describe removed paths as current.
- The docs maintenance workflow documents when and how to refresh LLM-facing files.
Related context
- Pioneer feedback from Zoro via Domi.
src/theme/SearchBar.tsx currently uses @cookbookdev/docsbot/react.
static/skill.md
static/llms.txt
Problem
Developers are getting unreliable answers from the docs AI. The reported failure mode is that answers cite outdated sources, link to moved code, or confidently answer from stale material.
One concrete example from Pioneer feedback:
AccountIdsurfaced an old protocol source path undercrates/miden-objects/src/account/account_id/....crates/miden-protocol/src/account/account_id/....The current site also embeds Cookbook docsbot via
@cookbookdev/docsbot/reactinsrc/theme/SearchBar.tsx. Given the poor answer quality, we should remove this integration rather than continue exposing it while we clean up source material.There are also stale LLM-facing files in the docs repo:
static/skill.mdstill identifies itself as version0.13.static/skill.mdstill contains old protocol limits and terminology.static/llms.txtincludes stale page descriptions and older docs paths.Why this matters
The docs AI is currently risky for developers because it can send them toward old APIs or moved source files. For Miden this is especially costly because many breaking changes landed across v0.13, v0.14, and current
next, and the wrong answer can look plausible while being impossible to use.Until the source/indexing story is reliable, the site should not ship a chatbot that can create false confidence. Local search plus accurate LLM-facing files is a safer baseline.
Proposed scope
@cookbookdev/docsbotdependency if it is no longer used.static/skill.mdfor the currently supported docs version.static/llms.txtso it points at current canonical pages and does not advertise stale SDK/reference versions.Acceptance criteria
@cookbookdev/docsbotis removed from dependencies if unused./skill.mdreflects the current stable docs version and current protocol/client concepts./llms.txtpoints to valid current docs pages and does not describe removed paths as current.Related context
src/theme/SearchBar.tsxcurrently uses@cookbookdev/docsbot/react.static/skill.mdstatic/llms.txt