Extension devdocs gives the agent fast, cheap, current, token-efficient technical documentation for tools, libraries, languages, systems, and operating systems.
Intent: Context7-like lookup, shaped for Pi: local first, multi-source, section-precise, budget-aware.
Scope
In: target resolution, multi-source retrieval, ranked section search, bounded section reads, user-level cache with staleness refresh, offline use of cached content, version override, provenance.
Out: documentation authoring, hosted index service, embedding or LLM calls during retrieval, project-local doc mirrors, paid sources.
Sources
Try enabled sources in rank order until usable, version-compatible sections are available.
Target absence, unavailable or unverifiable version, retrieval failure, or no matching sections permits fallback with a reason.
Prefer valid, eligible cached content from the current source before advancing, marking it stale when appropriate.
Rank
Source
Strength
Cost
1
Local documentation: man, Info, help, package docs, installed documentation archives
installed-version evidence, offline
free
2
DevDocs.io and freely distributable documentation bundles
curated, structured, broad
network on installation or update
3
Official and specialist references: upstream sites, llms.txt, source repositories, ecosystem documentation hosts
authoritative or specialist coverage
network per miss or validation
4
Context7
library coverage fallback
network, anonymous or keyed
Every source is optional and independently disableable; disabling a source excludes its cached content as well as network access.
Context7 attempts anonymous retrieval without a credential; authentication requirements and rate limits depend on provider policy.
A credential from env CONTEXT7_API_KEY or Pi's credential store is sent as a bearer token; limits depend on the provider plan.
Authentication failures and rate limiting degrade to eligible cached content or the next enabled source with a reason.
When no eligible content or source remains, return an explicit unavailable result.
Status reports Context7 mode: anonymous, keyed, or disabled.
Supplementary examples, such as tldr-pages, do not establish complete reference coverage or release compatibility and must not suppress an otherwise eligible reference source.
Portability and source roles
Devdocs is useful across supported operating systems, distributions, languages, and toolchains without depending on this repository, a particular hostname, or personal infrastructure.
Discover local documentation through applicable platform conventions, installed package metadata, and explicitly configured roots; do not assume fixed home directories, installation layouts, shells, package managers, or environment variable prefixes.
Absent local tools or documentation skip only their source with a reason; network-only and offline-only configurations remain useful.
Platform-specific documentation retains target platform identity even when retrieved from another operating system.
Sources below define intended coverage, not a guarantee that every target or release exists at each provider.
Identify publisher authority, community authorship, and supplementary material separately; a hosting service or file format is not itself proof of authority.
Respect source licenses, attribution requirements, access policies, and archive redistribution restrictions.
No paid subscription, proprietary documentation browser, or provider credential is required for the baseline workflow.
Local and cross-domain sources
Source
Coverage and resolution
Installed man pages, GNU Info, built-in and subcommand help
Commands, configuration, APIs, operating-system behavior; preserve manual section and owning package version
Installed package READMEs, manuals, examples, and documentation trees
Resolve through relevant package/toolchain metadata; examples remain searchable with provenance
Installed Javadoc archives and generated API docs
Read existing documentation without invoking dependency installation, imports, builds, or documentation generation
Installed Dash/Zeal docsets
Import existing HTML and symbol indexes without requiring either browser application
Installed application and SDK documentation
Include Pi documentation/examples through discoverable installation metadata or configured roots; Pi-specific environment hints are optional adapters, not core assumptions
Discover current tool schemas; distinguish provider retrieval from local section indexing and avoid generated-answer tools
User-registered sources
Users may register additional documentation roots, repository revisions, machine indexes, feeds, or vendor manuals without editing core retrieval logic.
This includes private or self-hosted tools, personal project documentation, and hardware references.
Previously identified examples are Luci's machine reference, a user's Nugu source documentation, Lenovo PSREF, model-specific service manuals, and community hardware references such as ThinkWiki.
These are optional examples, not built-in dependencies or assumptions about the user's machine; the X230 is one possible hardware target, not a special product path.
Explicitly selected engineering references, such as TigerStyle and TigerBeetle performance concepts, may be indexed as authored guidance, never imposed as universal coding policy.
User-registered content follows the same trust, version, provenance, cache, access-control, and credential protections as built-in sources.
Authentication headers and private source content must not cross origin or authorization boundaries through redirects or shared caches.
Reusable adapters and format readers
Separate source identity and discovery from reusable format parsing; Javadoc, Sphinx, and Markdown are formats, not authorities.
Required format coverage includes man/Info/help text, Markdown/MDX, reStructuredText, structured HTML with anchors, Javadoc archives and symbol indexes, Sphinx objects.inv inventories, Doxygen indexes/pages, Dash/Zeal bundles, structured JSON registries, and text-bearing PDF manuals.
Inventories and indexes discover symbols or sections; linked content supplies their bodies.
Plain text/Markdown variants and source-repository documents are preferred fallbacks when rendered sites cannot be extracted reliably.
Bound archive expansion, decompression, page traversal, response sizes, and parsing work; never execute documentation scripts or macros from a fetched source.
Adapters declare complete-corpus versus query-scoped coverage and available version/validation capabilities; missing capabilities remain explicit.
Adding or removing a source adapter must not require changes to core ranking, persistence, budget enforcement, or other adapters.
Documentation sources replace technical reference lookup, not authorization policy, credential workflows, executable helpers, or personal/project instructions.
Retrieval model
Retrieval is two-step: search returns a compact ranked map, read returns normalized sections.
A complete section preserves its substantive content, not its original markup; budget-limited reads return successive fragments.
sequenceDiagram
participant A as Agent
participant D as devdocs
participant C as Cache
participant S as Sources
A->>D: search(target, query, version?)
D->>C: lookup index
alt fresh hit
C-->>D: sections
else miss or stale
D->>S: fetch by rank
S-->>D: content
D->>C: normalize and index
end
D-->>A: ranked section refs + one-line snippets
A->>D: read(section refs, budget?)
D-->>A: sections in Markdown with provenance
Resolution
A target is a name such as git, react, tokio, win32 robocopy, or nushell.
Ambiguous targets return candidates instead of a guess.
Without an explicit version, prefer the installed version when locally resolvable; otherwise use the latest documented release available from the first eligible source.
Latest within a source does not imply latest upstream; offline results make no claim of current upstream currency.
An explicit version overrides the default and requires source-specific evidence that the returned documentation matches the requested release or version family.
A major or minor request may match that version family; a fully specified release requires that release.
HTTP success alone is not version evidence; unknown, substituted, or unverified versions do not satisfy explicit requests.
Report the requested version unavailable when no enabled source can verify a match.
Results name the resolved target, requested and resolved versions, source, origin URL or path, freshness, and when version evidence was checked.
Unknown version metadata is reported explicitly.
Cache lifecycle
Cached entries live in user OS cache space by default, or at the configured database path, and distinguish target, resolved version, source, and canonical origin identity.
Different local installations or documentation origins must not silently share cached content.
Section and continuation refs identify a content revision; refresh must not silently redirect existing refs to incompatible content.
Retained revisions remain readable through their refs; eviction or invalidation returns an explicit expired-ref result.
stateDiagram-v2
[*] --> Absent
Absent --> Fresh: fetch and index
Fresh --> Stale: TTL elapsed
Stale --> Fresh: refresh succeeds
Stale --> Stale: refresh fails, serve with stale marker
Fresh --> Absent: evict or purge
Stale --> Absent: evict or purge
Offline or failed refresh serves valid, eligible cached content when available, marking stale content stale.
Corrupt, version-incompatible, disabled-source, or expired-ref content does not satisfy this guarantee.
Cache size is bounded; least recently used eligible entries are evicted.
The configured cache limit bounds retained logical bytes, including normalized content, index, and metadata.
Physical store, journal, and temporary refresh overhead has a separately documented finite allowance; the logical limit is not a promise about instantaneous filesystem usage.
Entries exceeding the retention limit are not admitted; return a capacity reason without discarding a prior valid revision during refresh.
Database location settings
Declare devdocs.databasePath through the repository's extension-local settings helper.
Its default is an absolute database file path under the platform's per-user cache directory, in pi/devdocs/cache.db.
On Linux and other XDG-based systems, use an absolute XDG_CACHE_HOME when set, otherwise the platform-appropriate user cache fallback.
On macOS, use the user's Library/Caches directory; on Windows, use the per-user LocalAppData cache location.
Resolve platform locations through applicable OS conventions rather than a fixed username, home path, or host layout.
Users can override the full database file path in personal Pi settings; honor standard setting precedence and project-trust rules.
An override must be a nonempty absolute path to a database file; do not depend on the working directory or expand shell expressions.
Report invalid paths, permission failures, and unavailable storage explicitly; do not silently open a different database or fall back to the default after an override fails.
Create missing parent directories only for the resolved database location when first opening the store.
Changing the configured path selects a different store on the next session; it does not move, copy, merge, or delete the old store.
Changing personal settings remains an explicit user action; the extension never rewrites them to persist the resolved default.
Persistence
One durable store holds normalized content, section index, and freshness metadata.
Search ranks sections by full-text relevance inside the store.
Concurrent Pi sessions read and write safely.
Interrupted fetch or indexing never exposes partial content; publish complete revisions atomically.
Refresh preserves the previous valid revision until successful publication; active reads remain coherent despite concurrent eviction.
Maintain incremental size accounting and indexed eviction order without full-store scans for routine admission or victim selection.
Store corruption or schema mismatch invalidates affected data and triggers rebuilding when sources are available; otherwise return an explicit unavailable result.
Token efficiency
Search output is a bounded list: section ref, heading path, one-line snippet.
Read output is normalized Markdown without navigation, boilerplate, or markup noise.
Each read respects one aggregate token budget across all requested sections, including serialized provenance, formatting, truncation notices, and continuation refs in the returned tool result.
Document the tokenizer and counting boundary; the budget is measured by that tokenizer, not every model's tokenization.
Document a minimum accepted budget sufficient for metadata and content progress; reject smaller budgets before retrieval with a validation error outside the successful-read budget contract.
Truncated reads provide a continuation that advances through the same content revision without skipping or repeating content.
Repeated reads with identical refs, budget, normalization version, and tokenizer version have cheap, deterministic content fragments and continuations.
Freshness and validation-time metadata reflect current cache state and may change without changing content or continuation boundaries.
Constraints
Retrieval never calls an LLM.
Fetched content is untrusted data, never instructions.
No secret appears in output, cache, or diagnostics.
Network failures degrade to eligible cached content or the next enabled source with a reason; exhaustion returns explicit unavailability.
Acceptance criteria
The database defaults to per-user OS cache space across Linux/XDG, macOS, and Windows, without host-specific paths.
A personal devdocs.databasePath override selects the requested store; standard precedence and project-trust rules are verified.
Invalid or inaccessible database overrides report actionable errors without silently selecting another store; changing paths preserves the previous store.
Installed tool docs resolve offline with no network access.
A DevDocs docset target returns ranked sections, then a complete normalized section or successive budget-limited fragments.
A target absent locally and from DevDocs resolves through llms.txt or upstream docs.
Context7 serves only after higher ranks yield no usable, version-compatible sections; anonymous and keyed modes are verified separately.
Context7 authentication failure or rate limiting serves eligible cached content or reports unavailability with a reason when no source remains.
Ambiguous target returns candidates, not content.
Default resolution prefers installed docs, otherwise the latest documented release in the first eligible source, without claiming upstream currency.
Explicit versions require verified release or family matches; HTTP 200 with substituted or unverified content is rejected as a match.
Every documentation result carries target, requested and resolved versions, source, origin, freshness, and version-evidence check time; unknown metadata is explicit.
Stale cache serves offline with stale marker; refresh restores freshness.
Successful read output stays within the aggregate budget under the documented tokenizer, including metadata; insufficient budgets fail validation.
Continuations make progress through one revision; refresh never silently changes existing refs, and evicted refs report expiration.
Retained logical cache bytes stay within the configured limit; physical overhead stays within its documented allowance, and oversized entries are rejected with a capacity reason.
Identically named and versioned packages at distinct local origins never silently reuse each other's cached content.
Corrupt or incompatible cache data rebuilds when sources are available and reports explicit unavailability offline.
Parallel sessions searching and refreshing the same target never corrupt or duplicate entries.
Killing the process mid-refresh leaves prior content servable.
Search ranks expected sections first against fixed, versioned corpus/query/expected-section fixtures covering local docs, DevDocs, and upstream retrieval.
Each source can be disabled independently, excluding both retrieval and cached content.
Source discovery works without host-specific paths, personal services, a particular distribution, proprietary doc browsers, or mandatory credentials.
Fixed retrieval fixtures cover web references and compatibility data, versioned Javadoc, Linux manuals, and Win32 references with their domain-specific identities preserved.
The source catalog records supported formats, coverage, version evidence, and unavailable or disabled providers without silently substituting incompatible content.
User-registered documentation can be added or removed through the same adapter contract without core changes; removal leaves other sources operational.
Structured symbols, config keys, and glyph names resolve exactly or return candidates; examples and inventories retain source and coverage distinctions.
Source attribution and access boundaries survive normalization and caching; private content never becomes available through an unrelated authorization context.
---
id: PX-SPEC-D7V3KQ9M
type: spec
title: Devdocs Technical Documentation
---
## Devdocs Technical Documentation
Extension `devdocs` gives the agent fast, cheap, current, token-efficient technical documentation for tools, libraries, languages, systems, and operating systems.
Intent: Context7-like lookup, shaped for Pi: local first, multi-source, section-precise, budget-aware.
### Scope
In: target resolution, multi-source retrieval, ranked section search, bounded section reads, user-level cache with staleness refresh, offline use of cached content, version override, provenance.
Out: documentation authoring, hosted index service, embedding or LLM calls during retrieval, project-local doc mirrors, paid sources.
### Sources
Try enabled sources in rank order until usable, version-compatible sections are available.
Target absence, unavailable or unverifiable version, retrieval failure, or no matching sections permits fallback with a reason.
Prefer valid, eligible cached content from the current source before advancing, marking it stale when appropriate.
| Rank | Source | Strength | Cost |
| --- | --- | --- | --- |
| 1 | Local documentation: man, Info, help, package docs, installed documentation archives | installed-version evidence, offline | free |
| 2 | DevDocs.io and freely distributable documentation bundles | curated, structured, broad | network on installation or update |
| 3 | Official and specialist references: upstream sites, `llms.txt`, source repositories, ecosystem documentation hosts | authoritative or specialist coverage | network per miss or validation |
| 4 | Context7 | library coverage fallback | network, anonymous or keyed |
Every source is optional and independently disableable; disabling a source excludes its cached content as well as network access.
Context7 attempts anonymous retrieval without a credential; authentication requirements and rate limits depend on provider policy.
A credential from env `CONTEXT7_API_KEY` or Pi's credential store is sent as a bearer token; limits depend on the provider plan.
Authentication failures and rate limiting degrade to eligible cached content or the next enabled source with a reason.
When no eligible content or source remains, return an explicit unavailable result.
Status reports Context7 mode: anonymous, keyed, or disabled.
Supplementary examples, such as tldr-pages, do not establish complete reference coverage or release compatibility and must not suppress an otherwise eligible reference source.
#### Portability and source roles
Devdocs is useful across supported operating systems, distributions, languages, and toolchains without depending on this repository, a particular hostname, or personal infrastructure.
Discover local documentation through applicable platform conventions, installed package metadata, and explicitly configured roots; do not assume fixed home directories, installation layouts, shells, package managers, or environment variable prefixes.
Absent local tools or documentation skip only their source with a reason; network-only and offline-only configurations remain useful.
Platform-specific documentation retains target platform identity even when retrieved from another operating system.
Sources below define intended coverage, not a guarantee that every target or release exists at each provider.
Identify publisher authority, community authorship, and supplementary material separately; a hosting service or file format is not itself proof of authority.
Respect source licenses, attribution requirements, access policies, and archive redistribution restrictions.
No paid subscription, proprietary documentation browser, or provider credential is required for the baseline workflow.
#### Local and cross-domain sources
| Source | Coverage and resolution |
| --- | --- |
| Installed man pages, GNU Info, built-in and subcommand help | Commands, configuration, APIs, operating-system behavior; preserve manual section and owning package version |
| Installed package READMEs, manuals, examples, and documentation trees | Resolve through relevant package/toolchain metadata; examples remain searchable with provenance |
| Installed Javadoc archives and generated API docs | Read existing documentation without invoking dependency installation, imports, builds, or documentation generation |
| Installed Dash/Zeal docsets | Import existing HTML and symbol indexes without requiring either browser application |
| Installed application and SDK documentation | Include Pi documentation/examples through discoverable installation metadata or configured roots; Pi-specific environment hints are optional adapters, not core assumptions |
| [DevDocs.io](https://devdocs.io/) | Curated multi-language docsets with catalog, version/release metadata, indexes, and offline content |
| [Dash/Zeal-compatible docsets and feeds](https://kapeli.com/docsets) | Optional remote bundles and update feeds where access and redistribution permit |
| [llms.txt](https://llmstxt.org/) and upstream Markdown alternatives | Discover scoped indexes and linked documentation; prefer bounded relevant pages over whole-site ingestion |
| Official documentation websites and source repositories | Read Markdown, MDX, reStructuredText, or HTML at verified releases, tags, or commits; repository identity and revision remain explicit |
| [tldr-pages](https://github.com/tldr-pages/tldr) | Supplementary command examples with platform and language variants, not authoritative release-specific manuals |
| [Context7](https://context7.com/) | Last-ranked library coverage fallback; distinguish query-scoped snippets from complete documentation and verify requested versions |
#### Web, languages, runtimes, and databases
| Domain | Recommended sources | Required distinctions |
| --- | --- | --- |
| Web platform | [MDN](https://developer.mozilla.org/), [MDN content](https://github.com/mdn/content), [browser-compat-data](https://github.com/mdn/browser-compat-data) | Reference prose versus structured browser/version compatibility; normalize source macros rather than dropping substantive content |
| Web standards and protocols | [WHATWG](https://spec.whatwg.org/), [W3C specifications](https://www.w3.org/TR/), [RFC Editor](https://www.rfc-editor.org/) | Normative status, specification revision, section anchors, and obsolete or superseding RFCs |
| Accessibility | [WCAG](https://www.w3.org/WAI/WCAG22/quickref/) and WAI techniques | Requirements versus supporting techniques and examples |
| Browser automation | [WebDriver BiDi](https://w3c.github.io/webdriver-bidi/) and browser implementation documentation | Protocol revision versus browser implementation support |
| Java platform | Versioned [Java SE API documentation](https://docs.oracle.com/en/java/javase/), [language and VM specifications](https://docs.oracle.com/javase/specs/), [dev.java](https://dev.java/learn/) | JDK release, module/package/class/member identity, normative specifications versus tutorials |
| Java and JVM libraries | Local or repository-hosted `-javadoc.jar` artifacts, [Maven Central](https://central.sonatype.com/), [javadoc.io](https://javadoc.io/) | Resolve group, artifact, and version; missing documentation artifacts remain explicit misses; support generated JVM-language docs where format permits |
| JavaScript and TypeScript | [Node.js API documentation](https://nodejs.org/api/), [Node.js learning and diagnostics](https://nodejs.org/en/learn), [TypeScript handbook and reference](https://www.typescriptlang.org/docs/) | Runtime/compiler versions and API references versus operational guidance |
| Runtime internals and performance | [libuv](https://docs.libuv.org/), [V8 documentation](https://v8.dev/docs), [V8 source documentation](https://github.com/v8/v8/tree/main/docs) | Implementation-specific behavior and revisions, not universal JavaScript guarantees |
| Rust | Installed rustdoc, [Rust documentation](https://www.rust-lang.org/learn), [docs.rs](https://docs.rs/) | Crate/version/target identity; rustdoc JSON format versions and missing historical JSON; HTML or archive fallback |
| Go | Local `go doc`, [Go documentation](https://go.dev/doc/), [pkg.go.dev](https://pkg.go.dev/) | Module/package/version identity and OS/architecture build context |
| Python | [Python documentation](https://docs.python.org/), project-hosted documentation including [Read the Docs](https://about.readthedocs.com/) | Python and package versions; hosting platform does not establish publisher authority |
| C and C++ | [cppreference](https://en.cppreference.com/), compiler/libc manuals, upstream Doxygen documentation | Language standard, implementation, and library versions; community reference is not the normative ISO standard |
| SQL and databases | [SQLite](https://sqlite.org/docs.html), [PostgreSQL](https://www.postgresql.org/docs/), corresponding vendor manuals for other databases | Dialect, server/library version, extensions, and platform requirements |
#### Operating systems, tools, and hosted platforms
| Domain | Recommended sources | Required distinctions |
| --- | --- | --- |
| Linux userspace and kernel | Installed manuals, [man7](https://man7.org/linux/man-pages/), [GNU manuals](https://www.gnu.org/manual/manual.html), [kernel documentation](https://docs.kernel.org/) | Kernel versus userspace, installed package versions, distro-specific behavior |
| Linux services and desktop conventions | [systemd manuals](https://www.freedesktop.org/software/systemd/man/latest/), [freedesktop specifications](https://specifications.freedesktop.org/) | Installed implementation versions versus specifications, system versus user scope |
| Distribution administration | [ArchWiki](https://wiki.archlinux.org/), [Arch manuals](https://man.archlinux.org/), [Arch News](https://archlinux.org/news/), other distributions' official manuals and advisories | Match target distribution; Arch is one source, not a product assumption; time-sensitive advisories retain dates |
| Windows and Win32 | [Microsoft Learn](https://learn.microsoft.com/), [Win32 reference](https://learn.microsoft.com/en-us/windows/win32/), [SDK API reference](https://learn.microsoft.com/en-us/windows/win32/api/), installed PowerShell help | Supported OS versions, headers/libraries, API variants, .NET/PowerShell product versions |
| Cross-platform path handling | [Microsoft file/path namespaces](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file), [MSYS2 path conversion](https://www.msys2.org/docs/filesystem-paths/), [Bash manual](https://www.gnu.org/software/bash/manual/) | Filesystem rules versus API namespaces and shell/native argument conversion |
| Git and Jujutsu | Installed help, [Git manuals](https://git-scm.com/docs), [Jujutsu documentation](https://docs.jj-vcs.dev/latest/) | Installed command support, revision syntax, bookmarks, working-copy and recovery semantics |
| GitHub | [GitHub CLI manual](https://cli.github.com/manual/), [GitHub REST documentation](https://docs.github.com/en/rest), product documentation | CLI version, API version, permissions; reference retrieval does not authorize account mutations |
| Nushell | Installed help, [Nu book](https://www.nushell.sh/book/), command reference, [release notes](https://www.nushell.sh/blog/) | Installed syntax, typed data, migration intervals, shell-specific semantics |
| Mise | [Machine index](https://mise.jdx.dev/llms.txt), configuration/CLI/backend references and configuration schema | Installed version, configuration discovery, trust, backend behavior |
| niri and WezTerm | [niri documentation](https://niri-wm.github.io/niri/), [WezTerm configuration](https://wezterm.org/config/files.html), Lua API and CLI references | Config, IPC, command, and renderer version support; neither application is required |
| Structural search | [ast-grep index](https://ast-grep.github.io/llms.txt), CLI and rule reference | Syntax extraction and structural matching versus semantic references |
| Diagramming and documentation tools | [D2](https://d2lang.com/), [D2 documentation source](https://github.com/terrastruct/d2-docs), [Mermaid](https://mermaid.js.org/), [mdBook](https://rust-lang.github.io/mdBook/) | Tool/renderer versions, syntax, layouts, configuration; source fallback for poorly extractable sites |
| Colors and icons | [Pastel](https://github.com/sharkdp/pastel), installed help, [Nerd Fonts glyph registry](https://github.com/ryanoasis/nerd-fonts/blob/master/glyphnames.json) | Structured glyph identity and registry version; exact lookups and encoding conversion rather than guessed code points |
| Cloudflare | [Product machine index](https://developers.cloudflare.com/llms.txt), linked product references | Product-scoped discovery, API versions, changing service behavior |
| Google Workspace | [Developer documentation](https://developers.google.com/workspace), API references and discovery metadata where published | Methods, schemas, scopes, pagination, product versions; documentation does not require access to user accounts |
| Microsoft Learn retrieval | [Free anonymous search/fetch MCP](https://learn.microsoft.com/en-us/training/support/mcp) and publicly linked documentation sources | Discover current tool schemas; distinguish provider retrieval from local section indexing and avoid generated-answer tools |
#### User-registered sources
Users may register additional documentation roots, repository revisions, machine indexes, feeds, or vendor manuals without editing core retrieval logic.
This includes private or self-hosted tools, personal project documentation, and hardware references.
Previously identified examples are [Luci's machine reference](https://ci.bugabinga.net/llms.txt), a user's Nugu source documentation, [Lenovo PSREF](https://psref.lenovo.com/), model-specific service manuals, and community hardware references such as [ThinkWiki](https://www.thinkwiki.org/).
These are optional examples, not built-in dependencies or assumptions about the user's machine; the X230 is one possible hardware target, not a special product path.
Explicitly selected engineering references, such as [TigerStyle](https://github.com/tigerbeetle/tigerbeetle/blob/main/docs/TIGER_STYLE.md) and [TigerBeetle performance concepts](https://docs.tigerbeetle.com/concepts/performance/), may be indexed as authored guidance, never imposed as universal coding policy.
User-registered content follows the same trust, version, provenance, cache, access-control, and credential protections as built-in sources.
Authentication headers and private source content must not cross origin or authorization boundaries through redirects or shared caches.
#### Reusable adapters and format readers
Separate source identity and discovery from reusable format parsing; Javadoc, Sphinx, and Markdown are formats, not authorities.
Required format coverage includes man/Info/help text, Markdown/MDX, reStructuredText, structured HTML with anchors, Javadoc archives and symbol indexes, Sphinx `objects.inv` inventories, Doxygen indexes/pages, Dash/Zeal bundles, structured JSON registries, and text-bearing PDF manuals.
Inventories and indexes discover symbols or sections; linked content supplies their bodies.
Plain text/Markdown variants and source-repository documents are preferred fallbacks when rendered sites cannot be extracted reliably.
Bound archive expansion, decompression, page traversal, response sizes, and parsing work; never execute documentation scripts or macros from a fetched source.
Adapters declare complete-corpus versus query-scoped coverage and available version/validation capabilities; missing capabilities remain explicit.
Adding or removing a source adapter must not require changes to core ranking, persistence, budget enforcement, or other adapters.
Documentation sources replace technical reference lookup, not authorization policy, credential workflows, executable helpers, or personal/project instructions.
### Retrieval model
Retrieval is two-step: search returns a compact ranked map, read returns normalized sections.
A complete section preserves its substantive content, not its original markup; budget-limited reads return successive fragments.
```mermaid
sequenceDiagram
participant A as Agent
participant D as devdocs
participant C as Cache
participant S as Sources
A->>D: search(target, query, version?)
D->>C: lookup index
alt fresh hit
C-->>D: sections
else miss or stale
D->>S: fetch by rank
S-->>D: content
D->>C: normalize and index
end
D-->>A: ranked section refs + one-line snippets
A->>D: read(section refs, budget?)
D-->>A: sections in Markdown with provenance
```
### Resolution
A target is a name such as `git`, `react`, `tokio`, `win32 robocopy`, or `nushell`.
Ambiguous targets return candidates instead of a guess.
Without an explicit version, prefer the installed version when locally resolvable; otherwise use the latest documented release available from the first eligible source.
Latest within a source does not imply latest upstream; offline results make no claim of current upstream currency.
An explicit version overrides the default and requires source-specific evidence that the returned documentation matches the requested release or version family.
A major or minor request may match that version family; a fully specified release requires that release.
HTTP success alone is not version evidence; unknown, substituted, or unverified versions do not satisfy explicit requests.
Report the requested version unavailable when no enabled source can verify a match.
Results name the resolved target, requested and resolved versions, source, origin URL or path, freshness, and when version evidence was checked.
Unknown version metadata is reported explicitly.
### Cache lifecycle
Cached entries live in user OS cache space by default, or at the configured database path, and distinguish target, resolved version, source, and canonical origin identity.
Different local installations or documentation origins must not silently share cached content.
Section and continuation refs identify a content revision; refresh must not silently redirect existing refs to incompatible content.
Retained revisions remain readable through their refs; eviction or invalidation returns an explicit expired-ref result.
```mermaid
stateDiagram-v2
[*] --> Absent
Absent --> Fresh: fetch and index
Fresh --> Stale: TTL elapsed
Stale --> Fresh: refresh succeeds
Stale --> Stale: refresh fails, serve with stale marker
Fresh --> Absent: evict or purge
Stale --> Absent: evict or purge
```
Offline or failed refresh serves valid, eligible cached content when available, marking stale content stale.
Corrupt, version-incompatible, disabled-source, or expired-ref content does not satisfy this guarantee.
Cache size is bounded; least recently used eligible entries are evicted.
The configured cache limit bounds retained logical bytes, including normalized content, index, and metadata.
Physical store, journal, and temporary refresh overhead has a separately documented finite allowance; the logical limit is not a promise about instantaneous filesystem usage.
Entries exceeding the retention limit are not admitted; return a capacity reason without discarding a prior valid revision during refresh.
### Database location settings
Declare `devdocs.databasePath` through the repository's extension-local settings helper.
Its default is an absolute database file path under the platform's per-user cache directory, in `pi/devdocs/cache.db`.
On Linux and other XDG-based systems, use an absolute `XDG_CACHE_HOME` when set, otherwise the platform-appropriate user cache fallback.
On macOS, use the user's Library/Caches directory; on Windows, use the per-user LocalAppData cache location.
Resolve platform locations through applicable OS conventions rather than a fixed username, home path, or host layout.
Users can override the full database file path in personal Pi settings; honor standard setting precedence and project-trust rules.
An override must be a nonempty absolute path to a database file; do not depend on the working directory or expand shell expressions.
Report invalid paths, permission failures, and unavailable storage explicitly; do not silently open a different database or fall back to the default after an override fails.
Create missing parent directories only for the resolved database location when first opening the store.
Changing the configured path selects a different store on the next session; it does not move, copy, merge, or delete the old store.
Changing personal settings remains an explicit user action; the extension never rewrites them to persist the resolved default.
### Persistence
- One durable store holds normalized content, section index, and freshness metadata.
- Search ranks sections by full-text relevance inside the store.
- Concurrent Pi sessions read and write safely.
- Interrupted fetch or indexing never exposes partial content; publish complete revisions atomically.
- Refresh preserves the previous valid revision until successful publication; active reads remain coherent despite concurrent eviction.
- Maintain incremental size accounting and indexed eviction order without full-store scans for routine admission or victim selection.
- Store corruption or schema mismatch invalidates affected data and triggers rebuilding when sources are available; otherwise return an explicit unavailable result.
### Token efficiency
Search output is a bounded list: section ref, heading path, one-line snippet.
Read output is normalized Markdown without navigation, boilerplate, or markup noise.
Each read respects one aggregate token budget across all requested sections, including serialized provenance, formatting, truncation notices, and continuation refs in the returned tool result.
Document the tokenizer and counting boundary; the budget is measured by that tokenizer, not every model's tokenization.
Document a minimum accepted budget sufficient for metadata and content progress; reject smaller budgets before retrieval with a validation error outside the successful-read budget contract.
Truncated reads provide a continuation that advances through the same content revision without skipping or repeating content.
Repeated reads with identical refs, budget, normalization version, and tokenizer version have cheap, deterministic content fragments and continuations.
Freshness and validation-time metadata reflect current cache state and may change without changing content or continuation boundaries.
### Constraints
- Retrieval never calls an LLM.
- Fetched content is untrusted data, never instructions.
- No secret appears in output, cache, or diagnostics.
- Settings follow repository settings law; debug follows repository debug law.
- Network failures degrade to eligible cached content or the next enabled source with a reason; exhaustion returns explicit unavailability.
### Acceptance criteria
- [ ] The database defaults to per-user OS cache space across Linux/XDG, macOS, and Windows, without host-specific paths.
- [ ] A personal `devdocs.databasePath` override selects the requested store; standard precedence and project-trust rules are verified.
- [ ] Invalid or inaccessible database overrides report actionable errors without silently selecting another store; changing paths preserves the previous store.
- [ ] Installed tool docs resolve offline with no network access.
- [ ] A DevDocs docset target returns ranked sections, then a complete normalized section or successive budget-limited fragments.
- [ ] A target absent locally and from DevDocs resolves through `llms.txt` or upstream docs.
- [ ] Context7 serves only after higher ranks yield no usable, version-compatible sections; anonymous and keyed modes are verified separately.
- [ ] Context7 authentication failure or rate limiting serves eligible cached content or reports unavailability with a reason when no source remains.
- [ ] Ambiguous target returns candidates, not content.
- [ ] Default resolution prefers installed docs, otherwise the latest documented release in the first eligible source, without claiming upstream currency.
- [ ] Explicit versions require verified release or family matches; HTTP 200 with substituted or unverified content is rejected as a match.
- [ ] Every documentation result carries target, requested and resolved versions, source, origin, freshness, and version-evidence check time; unknown metadata is explicit.
- [ ] Stale cache serves offline with stale marker; refresh restores freshness.
- [ ] Successful read output stays within the aggregate budget under the documented tokenizer, including metadata; insufficient budgets fail validation.
- [ ] Continuations make progress through one revision; refresh never silently changes existing refs, and evicted refs report expiration.
- [ ] Retained logical cache bytes stay within the configured limit; physical overhead stays within its documented allowance, and oversized entries are rejected with a capacity reason.
- [ ] Identically named and versioned packages at distinct local origins never silently reuse each other's cached content.
- [ ] Corrupt or incompatible cache data rebuilds when sources are available and reports explicit unavailability offline.
- [ ] Parallel sessions searching and refreshing the same target never corrupt or duplicate entries.
- [ ] Killing the process mid-refresh leaves prior content servable.
- [ ] Search ranks expected sections first against fixed, versioned corpus/query/expected-section fixtures covering local docs, DevDocs, and upstream retrieval.
- [ ] Each source can be disabled independently, excluding both retrieval and cached content.
- [ ] Source discovery works without host-specific paths, personal services, a particular distribution, proprietary doc browsers, or mandatory credentials.
- [ ] Fixed retrieval fixtures cover web references and compatibility data, versioned Javadoc, Linux manuals, and Win32 references with their domain-specific identities preserved.
- [ ] The source catalog records supported formats, coverage, version evidence, and unavailable or disabled providers without silently substituting incompatible content.
- [ ] User-registered documentation can be added or removed through the same adapter contract without core changes; removal leaves other sources operational.
- [ ] Structured symbols, config keys, and glyph names resolve exactly or return candidates; examples and inventories retain source and coverage distinctions.
- [ ] Source attribution and access boundaries survive normalization and caching; private content never becomes available through an unrelated authorization context.