smahtiepants

# smahtiepants: search current local documentation Your training data has a cutoff; library/framework/language APIs change after it. **Before answering from memory, search the local docs and ground your answer in them.** `smahtiepants` keeps a recently-mirrored copy of DevDocs (hundreds of docsets) with fast semantic + keyword search. In this repository, always invoke it as `uv run smahtiepants` from the repo root; do not call `smahtiepants` directly. Skip only when the question is conceptual/version-independent or no relevant docset exists. ## Workflow ### 1. See what documentation is available locally ```bash uv run smahtiepants docs installed ``` This lists installed docsets with their canonical `Slug` (e.g. `javascript`, `react`, `express`, `python~3.13`, `cpp`, `css`, `docker`, `git`). The slug is what you pass to `--slug`. Match the user's library/language to a slug here. If you suspect a docset exists but isn't installed, list everything available: ```bash uv run smahtiepants docs available --offline # fast, from local cache metadata uv run smahtiepants docs available # refresh the list from DevDocs (network) ``` ### 2. Install or update docs if needed ```bash uv run smahtiepants docs install react redux # install one or more docsets uv run smahtiepants docs update # update all installed docsets uv run smahtiepants docs update python # update one docset ``` Slugs accept common aliases (`js`, `ts`, `py`, `python`, `nodejs`, `c++`), which resolve to canonical docsets. Installing also builds the search index when embeddings are configured. ### 3. Search the docs ```bash uv run smahtiepants search "useEffect cleanup" --slug react --limit 5 uv run smahtiepants search "request body parsing" --slug express uv run smahtiepants search "structuredClone" --language javascript uv run smahtiepants search "cfg target_arch target_os target triple" --slug rust ``` Useful flags: - `--slug <slug>` — restrict to a docset (repeatable). Strongly prefer scoping by slug/language; it makes results far more relevant. - `--language <name>` — filter by language-like docset (repeatable). - `--limit <n>` — number of results (default 10, max 50). - `--format text|json|xml` (or `--json`) — output format. The default `text` output gives a ranked list with a query-aware **excerpt**, the matched page identity, and a **read hint** for each match. If the excerpt directly answers the question, use it; if it only identifies the right page or omits edge cases, follow the read hint before answering. Queries may be natural language or grep-like API terms; for code and language reference docs, include exact identifiers, attributes, flags, function names, and the surrounding concept words you expect to see. ### 4. Get more context when an excerpt isn't enough The CLI excerpt is a snippet. To see the **full matched chunk** (not just the trimmed excerpt), request JSON — the `text` field contains the complete chunk: ```bash uv run smahtiepants search "useEffect cleanup" --slug react --limit 3 --format json ``` For reading an entire documentation page, prefer the CLI command in the read hint: ```bash uv run smahtiepants docs page <slug> <pageId> ``` Copy `docsetSlug` and `pageId` from the search result into this command. It reads the installed Markdown page directly from the local cache; do not start `smahtiepants serve`, call REST, or try MCP for a CLI workflow. ```bash uv run smahtiepants docs page react hooks/useeffect ``` Use `--start-line` and `--end-line` for a bounded section of a large page, or `--json` when structured content and line metadata are useful. If a result looks close but the excerpt is ambiguous, read the full page before concluding the docs do not contain the answer. ### 5. Ground your answer Base your answer on what the docs actually say. If local docs contradict your prior assumption, trust the docs and say what changed. Reference the docset and page so the user can verify (e.g. "per the local `react` docs page `hooks/useeffect`…"). If no relevant docset is installed, say so rather than guessing, and offer to install it. ## Quick reference | Goal | Command | | --- | --- | | List installed docsets + slugs | `uv run smahtiepants docs installed` | | List all available docsets | `uv run smahtiepants docs available --offline` | | Install docset(s) | `uv run smahtiepants docs install <slug> [<slug>…]` | | Update docset(s) | `uv run smahtiepants docs update [<slug>]` | | Search (scoped) | `uv run smahtiepants search "<query>" --slug <slug> --limit 5` | | Full chunk text | `uv run smahtiepants search "<query>" --slug <slug> --format json` | | Full page text | `uv run smahtiepants docs page <slug> <pageId>` | | Embedding/index status | `uv run smahtiepants embeddings status` | See `references/cli.md` for the complete command surface and output details.