@witooh/pi-semble-docs

A Pi package that exposes one semantic-search tool for project documentation. Searches are permanently scoped to docs/**/* and use Semble with its docs content type.

Requirements

• Pi 0.80.6 or later
• Semble 0.5.1 or later available as semble on PATH

Install Semble with uv:

uv tool install semble

Semble may download its embedding model on the first search. It runs locally and does not require an API key.

Install

From npm:

pi install npm:@witooh/pi-semble-docs

For a project-local npm installation:

pi install -l npm:@witooh/pi-semble-docs

From GitHub:

pi install git:github.com/witooh/pi-semble-docs

From a local checkout:

pi install /absolute/path/to/pi-semble-docs

Restart Pi after installation, or use /reload when loading the extension from an auto-discovered location.

Usage

Ask Pi to search project documentation by meaning or intent:

Find the documented authentication flow.
Search the docs for deployment rollback guidance.
Where do the docs describe API pagination?

Pi can call the semble_docs_search tool with:

| Argument | Required | Description | | -------- | -------: | ---------------------------------------------- | | query | Yes | Natural-language or text query | | topK | No | Number of results, from 1 to 20; defaults to 5 |

Scope guarantee

The extension invokes Semble equivalent to:

semble search <query> <current-working-directory>/docs --top-k <N> --content docs

The tool does not accept path, repo, or content arguments. Consequently, neither the model nor the caller can redirect this tool outside the current project's docs/ directory.

--content docs searches formats that Semble classifies as documentation, including Markdown, reStructuredText, and HTML. It intentionally excludes source-code and configuration formats even when those files are under docs/. Semble also respects .gitignore and .sembleignore rules and does not follow symbolic links.

For exact literal matching, use Pi's built-in grep tool instead.

Output and errors

• The agent receives the complete Semble JSON so search quality is unchanged.
• The TUI stays compact: collapsed results show only the match count; expanded results show file and line locations without repeating document snippets.
• Output sent to the agent is limited to Pi's standard 2,000-line or 50KB boundary.
• When truncated, the complete result is written to a temporary file and its path is returned.
• Missing docs/, a missing Semble executable, cancellation, and Semble failures are reported as tool errors.

Development

npm install
npm test
npm run typecheck
npm run format:check
npm pack --dry-run

The test command enforces at least 80% line, function, and branch coverage.