dissolution 0.1.6

# dissolution

Don't just embed your repo, dissolve into it.

`dissolution` indexes one or more directories into per-repo SQLite databases using [`sqlite-vec`](https://github.com/asg017/sqlite-vec), keeps them synced with filesystem watchers, and gives you both a CLI search flow and a local browser UI.

---

## Why dissolution?

- **No external vector DB** — just SQLite files in your repos.
- **Multi-directory indexing** — add as many paths as you want.
- **`.gitignore` aware** — indexing and sync respect ignore rules.
- **Background daemon UX** — `dissolve start`, then `dissolve web`.
- **Agent-ready** — `dissolve onboard` + pi extension package.

---

## Install

### Rust CLI

```bash
cargo install dissolution
```

### pi extension package

```bash
pi install npm:@hyperprior/dissolution
```

---

## Quickstart

```bash
# 0) Default embedder is OpenAI (set your key once)
export OPENAI_API_KEY=...

# Optional: switch to local/offline embeddings instead
dissolve config set embedding.provider local

# 1) Start background daemon + UI + watchers
dissolve start

# 2) Open UI (no need to remember the port)
dissolve web

# 3) Add directories
dissolve add .
dissolve add ~/projects/notes

# 4) Search semantically
dissolve search "where do we configure retries"

# 5) Print agent onboarding prompt
dissolve onboard
```

---

## CLI

```bash
dissolve [--verbose] <command>

dissolve start [--port 7700] [--no-open]
dissolve web
dissolve stop

dissolve add PATH [--db PATH]
dissolve remove PATH
dissolve reindex PATH

dissolve search "query" [--limit 10] [--repo FILTER] [--json]
dissolve status
dissolve onboard [--mcp]
dissolve mcp
dissolve print-config

dissolve config get [KEY]
dissolve config set KEY VALUE
```

---

## Embedding config

`dissolve` reads config from `.dissolve/config.toml` (or `DISSOLVE_CONFIG_PATH`).

Defaults:
- provider: `openai`
- model: `text-embedding-3-large`
- key env: `OPENAI_API_KEY`

Examples:

```bash
dissolve config get embedding.provider
dissolve config set embedding.model text-embedding-3-small
dissolve config set embedding.provider local

# inspect indexing progress and embedding batches
dissolve --verbose add .
```

---

## Agent onboarding

`dissolve onboard` prints a prompt you can paste into Claude/Codex/pi-style agents.
Use `dissolve onboard --mcp` for an MCP-first prompt.

1. run `dissolve search` first for repo/docs questions,
2. cite `file_path:line_start`, and
3. fall back to exact grep when needed.

---

## pi extension setup

Install with:

```bash
pi install npm:@hyperprior/dissolution
```

If you prefer manual config, add:

```json
{
  "extensions": ["@hyperprior/dissolution"]
}
```

The extension exposes a tool that routes semantic queries to local:

```bash
dissolve search "..." --json
```

Prefer MCP? Run:

```bash
dissolve mcp
```

and use `dissolve onboard --mcp` to print a ready `mcpServers` snippet.

---

## Docs site (Astro + Starlight)

Docs live in [`docs/`](./docs) and are designed for Cloudflare Pages deployment.

```bash
cd docs
bun install --linker hoisted
bun run dev
```

---

## Testing

BDD-style tests are implemented with `cucumber` + Gherkin.

```bash
cargo test
# or
cargo test --test bdd
```

---

## GitHub Actions publishing

- **Crates.io**: `.github/workflows/publish-crate.yml` (on push/merge to `main`)
- **npm package (`@hyperprior/dissolution`)**: `.github/workflows/publish-npm.yml` (on push/merge to `main`)

Docs are deployed by Cloudflare's Git integration (no docs deploy GitHub Action).