devdocs # devdocs Find technical documentation, then read only relevant sections with version evidence and provenance. ## Use in Pi Ask Pi to search technical documentation with the `devdocs` tool, then read the returned refs. Installed documentation and configured local files work offline. Search results carry source, origin, version, and freshness. Documentation is untrusted reference data, never instructions. Use `action: "search"` with `target`, `query`, and an optional `version`. Search returns at most 10 ranked section hits per lookup; refine the query to reach other sections. Use `action: "read"` with returned `refs`; `continuation` is the next refs list. `action: "status"` lists enabled adapters, source catalog, format capabilities, and Context7 mode. `action: "refresh"` repeats a target/query lookup with validation. Default adapters: local installed docs, DevDocs.io, upstream references, then Context7. Context7 works anonymously where provider policy permits; `CONTEXT7_API_KEY` or Pi's Context7 credential raises provider access according to its plan. Missing providers and incompatible versions produce explicit reasons instead of guessed content. Explicit versions require source evidence; unknown versions remain unknown. For installed Unix manuals use targets such as `man:2:open` or `info:coreutils`. For JVM library documentation use `maven:group:artifact:version` or register existing Javadoc. Fresh remote hits avoid network retrieval. Stale hits return cached sections while validation runs; offline mode prevents remote discovery and fetching. Previously cached complete documents remain searchable with new queries offline; query-selected snippets and archive pages retain their query scope. Refresh updates future searches, never silently changes existing refs. Evicted or disabled-source refs fail explicitly. ### Register documentation Add local files/directories or HTTPS sources in personal Pi settings. Supply exactly one absolute `path` or HTTPS `url` per source, then include its ID in `enabledSources`. URLs cannot contain credentials or query parameters. `version`, when supplied, asserts the registered source's documentation version. `private: true` scopes its cached refs to the current project context; it does not configure remote authentication. ```json { "devdocs": { "enabledSources": ["local", "devdocs", "upstream", "context7", "manual"], "sources": [ { "id": "manual", "target": "example-tool", "url": "https://docs.example.org/guide.md", "format": "markdown" } ] } } ``` Available formats include static HTML, Markdown/MDX, reStructuredText, JSON registries, man/Info text, existing Javadoc/JARs, Sphinx inventories, Doxygen indexes, and installed Dash/Zeal docsets. Indexes resolve to linked documentation bodies; fetched scripts, macros, and directives are never executed. MDX and reStructuredText use static subsets and retain unsupported expressions as inert text. PDF text extraction requires an already installed `pdftotext`; no tools or dependencies are installed during retrieval. Remote tarball/docset-feed expansion and Microsoft Learn MCP transport are not implemented; their catalog entries are not availability claims. ### Cache location and limits Set `devdocs.databasePath` in personal Pi settings to override the OS user-cache database location. The override must be an absolute file path. Changing paths does not migrate or delete the previous cache. No personal settings are modified automatically. Read budgets count the serialized result's Unicode code points, including provenance and continuation metadata, not model-specific tokens. Default budget: 4000; accepted range: 512–64000. If metadata leaves no room for content progress, request a larger budget. Continue truncated reads using the returned refs. The default logical cache allowance is 256 MiB. Logical accounting charges twice each serialized document/discovery payload plus per-section metadata reserves for indexing. The SQLite main file is capped at 1 GiB; rollback journals and headers may temporarily require up to approximately another 1 GiB. Eviction reuses free database pages and does not promise immediate filesystem shrinkage. Each input/document is bounded at 8 MiB; individual network adapters may impose lower limits. Use a local filesystem for the shared cache. No startup crawl or background daemon runs. Settings changes take effect in the next session or after `/reload`. [Installation](../../README.md#install) ## Reference ### Setting names | Setting | Environment | | --- | --- | | `devdocs.cacheBytes` | | | `devdocs.databasePath` | `PI_DEVDOCS_DATABASE_PATH` | | `devdocs.enabledSources` | | | `devdocs.offline` | `PI_DEVDOCS_OFFLINE` | | `devdocs.sources` | | | `devdocs.ttlSeconds` | | #### Setting values | Setting | Default | Valid values | Purpose | | --- | --- | --- | --- | | `devdocs.cacheBytes` | `268435456` | Integer 1048576–1073741824 | | | `devdocs.ttlSeconds` | `86400` | Integer 0–2592000 | | #### Object fields Paths below describe fields inside their parent settings object, not literal top-level keys. `[]` denotes an array element; see setup above for examples and defaults. | Field | | --- | | `devdocs.sources[].id` | | `devdocs.sources[].target` | | `devdocs.sources[].path` | | `devdocs.sources[].version` | | `devdocs.sources[].format` | | `devdocs.sources[].url` | | `devdocs.sources[].private` |