# @witooh/pi-semble-docs

A [Pi](https://pi.dev) package that exposes one semantic-search tool for project documentation. Searches are permanently scoped to `docs/**/*` and use [Semble](https://github.com/MinishLab/semble) with its `docs` content type.

## Requirements

- Pi 0.80.6 or later
- [Semble](https://github.com/MinishLab/semble) 0.5.1 or later available as `semble` on `PATH`

Install Semble with `uv`:

```bash
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:

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

For a project-local npm installation:

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

From GitHub:

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

From a local checkout:

```bash
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:

```text
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:

```text
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

```bash
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.