lmgrep 0.1.17 → 0.2.0

package/README.md

@@ -8,12 +8,14 @@ lmgrep uses [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) to parse s
 
 - **Any embedding provider** — works with Ollama, OpenAI, Google, or any provider supported by the [Vercel AI SDK](https://sdk.vercel.ai/)
 - **Tree-sitter chunking** — splits code at AST boundaries so search results are complete, meaningful units
+- **The index lives in the repo** — under `.git/lmgrep/`, so `du` finds it, `rm -rf` removes it, and deleting a clone deletes its index
+- **One index per model** — switching embedding models selects a different database instead of invalidating the one you have; switching back is instant
+- **Ask (research mode)** — `lmgrep ask` runs a local model that searches, reads, and synthesizes a cited answer, so agents spend one call instead of many searches
 - **MCP server** — built-in MCP server (`lmgrep mcp`) for integration with Claude Code, Cursor, and other AI tools
 - **File watching** — `lmgrep serve` watches for changes and incrementally re-indexes
 - **P2P sharing** — share your index with teammates via direct peer-to-peer transfer
 - **Cross-project search** — search across multiple indexed projects
-- **Git-aware** — respects `.gitignore`, deduplicates across worktrees sharing the same remote
-- **Configurable** — global or per-project config, custom ignore patterns, extension filtering
+- **Git-aware** — respects `.gitignore`, and every worktree of a repository shares one index
 
 ## Quick start
 
@@ -25,19 +27,24 @@ pnpm install -g lmgrep
 
 ### 2. Set up an embedding model
 
-The fastest way to get started is with [Ollama](https://ollama.com/):
+Start a local inference server, then let lmgrep configure itself.
+
+With [Ollama](https://ollama.com/):
 
 ```sh
-# Install Ollama
 curl -fsSL https://ollama.com/install.sh | sh
-
-# Pull an embedding model
 ollama pull nomic-embed-text
-
-# Auto-detect and write config
 lmgrep init
 ```
 
+Or with [LM Studio](https://lmstudio.ai): install an embedding model, enable
+the local server, and run `lmgrep init`.
+
+`init` detects whichever server is running, picks an embedding model, and
+writes the provider, base URL and any prefixes that model requires. Where the
+server also reports a chat model it configures `chatModel` too, which is what
+enables `lmgrep ask`.
+
 This creates a config file at `~/.config/lmgrep/config.yml` (Linux) or `~/Library/Application Support/lmgrep/config.yml` (macOS).
 
 ### 3. Index your project
@@ -49,55 +56,178 @@ lmgrep index
 
 ### 4. Search
 
+A bare query searches — `search` is the default command:
+
 ```sh
-lmgrep search "how are users authenticated"
+lmgrep how are users authenticated
 lmgrep search "database connection pooling" --limit 5
-lmgrep search "error handling" --file-prefix src/lib --language .ts
+lmgrep search "error handling" --under src/lib --language .ts
 ```
 
 ## CLI commands
 
+Two of these are the product; the rest you run once.
+
 | Command | Description |
 |---|---|
-| `lmgrep index` | Index the current directory |
-| `lmgrep search <query>` | Search using natural language |
-| `lmgrep status` | Show index stats, embedding connectivity, and running processes |
-| `lmgrep serve` | Watch for changes and re-index automatically |
+| `lmgrep <query>` | Search using natural language (`search` is the default command) |
+| `lmgrep ask <question>` | Answer a question with a local research loop (search → read → cited answer) |
+| `lmgrep index` | Index this project, and keep it current |
+| `lmgrep status` | Report whether search works, and why not |
+| `lmgrep projects` | List every index on this machine, and reclaim their space |
+| `lmgrep init` | Detect your local models and write the machine config |
+| `lmgrep config` | Open the machine config in your editor |
 | `lmgrep mcp` | Start the MCP server (stdio transport) |
-| `lmgrep init` | Detect embedding setup and create config |
-| `lmgrep config` | Open the global config in your editor |
-| `lmgrep repair` | Detect and fix index inconsistencies |
-| `lmgrep migrate` | Rename existing index directories to match the current slug scheme |
-| `lmgrep compact` | Compact the index to reclaim disk space |
-| `lmgrep export` | Share this project's index with a peer via P2P |
-| `lmgrep import [source]` | Import from a peer (share code) or local database |
-| `lmgrep prune` | Delete the index for the current directory |
+| `lmgrep serve` | Watch this project and re-index as files change |
+| `lmgrep share` | Offer this project's index to a peer over P2P |
+| `lmgrep import <source>` | Import from a peer (share code) or another database (path) |
 | `lmgrep completions zsh` | Output or install zsh completions |
 
+There is no `repair`, `compact`, or `migrate`. Reconciling the manifest,
+dropping duplicate rows, compacting fragments and training the vector index all
+happen inside `lmgrep index`, which is the one moment you are already waiting.
+`prune` became `lmgrep projects rm`, which can see what it is deleting.
+
 ### Search options
 
 ```
---limit <n>          Max results (default: 25)
---file-prefix <path> Only search files under this path
---language <exts>    Filter by file extension (e.g. .ts,.py)
---type <types>       Filter by AST node type (e.g. function_declaration)
---not <query>        Exclude results similar to this query
---scores             Show relevance scores
---compact            Show file paths only
---json               Output as JSON
---project <path>     Search a different project's index
---across <paths>     Search multiple projects (comma-separated)
+--limit <n>       Max results (default: 25)
+--under <path>    Only search files under this path
+--language <exts> Only search these extensions (e.g. .ts,.py)
+--compact         Print matching file paths only
+--json            Print results as JSON
+--in <target>     Repeatable: a project directory, or a standalone index name
 ```
 
 ### Index options
 
 ```
---reset       Rebuild the entire index from scratch
---since <dur> Only re-index files modified within duration (e.g. 10m, 2h, 1d)
---force       Force re-embed even if file hash is unchanged
---dry         Show what would be indexed without doing it
+--reset       Discard the index and rebuild from scratch
+--since <dur> Only consider files modified within duration (e.g. 10m, 2h, 1d)
+--dry         Report what would be indexed, and stop
 --verbose     Show file-by-file progress
+--in <target> A project directory, or a standalone index name
+```
+
+## Ask (research mode)
+
+`lmgrep ask` answers a question *about the codebase* instead of returning raw chunks. A local chat model runs a short agentic loop — it searches the index, reads the matching code, and writes a concise answer where every claim is cited as `[n] → file:line`. This is aimed at AI agents: one `ask` call replaces several searches and pages of chunks, so it's far cheaper on the agent's context.
+
+It requires a generative `chatModel` in addition to your embedding `model`. On a local runtime (LM Studio, Ollama) it reuses the same provider and `baseURL`, so one extra config line is enough:
+
+```yaml
+# ~/.config/lmgrep/config.yml
+model: lmstudio:text-embedding-nomic-embed-code   # embeddings (retrieval)
+chatModel: lmstudio:google/gemma-4-e2b            # generation (the research loop)
+```
+
+```sh
+lmgrep ask "how does the file watcher trigger reindexing"
+lmgrep ask "where are webhooks authenticated and what token format" --json
+```
+
+The answer, its `Sources:` list, and a one-line trace (queries run, steps, time) are printed; the live search trace streams to stderr (silence it with `--quiet`). When configured, `ask` is also exposed as an MCP tool alongside `search`.
+
+```
+--json   Print the full result (answer, sources, trace) as JSON
+--quiet  Suppress the live research trace on stderr
+--in     A project directory, or a standalone index name
+```
+
+Config keys: `chatModel` (required for `ask`), `chatProvider` / `chatBaseURL` (default to the embedding `provider` / `baseURL`), `chatMaxSteps` (default 8), `chatTimeoutMs` (per model call, default 240000).
+
+## The vector index
+
+Above a few thousand chunks lmgrep trains an ANN index over the embeddings.
+Without one, every search brute-force scans the whole table: roughly the
+index's own size in peak memory per query, and an order of magnitude more
+latency. `lmgrep status` reports which mode you are in.
+
+It is built automatically by `lmgrep index`, and by `lmgrep serve` / the MCP
+server on their first catch-up pass. Training briefly needs several GB, so it
+happens once rather than on every incremental update — and never behind a
+background watcher that has not caught up yet. If `status` reports it missing,
+`lmgrep index` builds it.
+
+## Where the index lives
+
+Inside the repository it indexes:
+
 ```
+<repo>/.git/lmgrep/<model>/
+```
+
+Git resolves `.git` to the main checkout even from a linked worktree, so every
+worktree of a repository shares one index automatically — no registry, nothing
+to keep in sync. Git never walks its own directory, so the index is never
+committed and never indexed. And because it is *there*, `du -sh` finds it,
+`rm -rf` removes it, and deleting a clone deletes its index with it.
+
+Each embedding model gets its own subdirectory. Changing `model` in your config
+selects a different database rather than invalidating the one you have, so
+trying another model costs one re-index and switching back costs nothing.
+
+### Changing your embedding model
+
+The new model has no index yet, so lmgrep says so and names what you already
+have:
+
+```
+$ lmgrep how are webhooks authenticated
+This project has no index for "qwen3-embedding-4b" — but it is indexed with
+"nomic-embed-code".
+Set `model` back to lmstudio:nomic-embed-code to use that index immediately, or
+run `lmgrep index` to embed this project with the new model (the other index is
+kept).
+```
+
+`status` gives the same answer, and `lmgrep index` says what it is about to do
+before it starts — embedding a large repository takes a while, and trying a
+model out should not commit you to it by accident. Both indexes then coexist,
+and `model` decides which one answers.
+
+Note that `serve` and the MCP server read configuration once, at startup. A
+server already running keeps using the model it started with — self-consistent,
+but it will disagree with the CLI until you restart it. `lmgrep status
+--verbose` prints the database each running process is holding.
+
+Projects outside a git repository, and indexes you name yourself, live under
+`~/.local/state/lmgrep/db/`. Lock files and a small pointer registry live
+beside it — that registry is what `lmgrep projects` and cross-project search
+read, since an index inside a repository cannot be found by listing a
+directory.
+
+### Targeting another index
+
+`--in` takes a project directory or the name of a standalone index, and repeats:
+
+```sh
+# A standalone index, for a corpus that is not a repository
+lmgrep index --in notes
+lmgrep search "retry policy" --in notes
+
+# Another project
+lmgrep search "retry policy" --in ../other-repo
+
+# Several at once; `.` includes the current project
+lmgrep search "retry policy" --in . --in ../other-repo
+```
+
+For write commands the files indexed still come from the current directory;
+only the database identity changes. A standalone index is flat — branch-agnostic,
+so switching git branches never hides results.
+
+### Seeing and reclaiming
+
+```sh
+lmgrep projects            # every index, largest first, with its model and size
+lmgrep projects adopt      # move a pre-0.2 index into this repository, no re-embed
+lmgrep projects rm         # delete this project's index
+lmgrep projects gc         # delete indexes whose project no longer exists
+```
+
+`rm` and `gc` refuse to recurse into anything that is not recognizably an
+lmgrep database.
 
 ## P2P index sharing
 
@@ -105,7 +235,7 @@ Share your index with a teammate without any server or infrastructure. Uses [Hyp
 
 ```sh
 # On your machine — start sharing
-lmgrep export
+lmgrep share
 # → Share code: lmgrepoceantiger7f3a
 # → Waiting for peer...
 
@@ -164,18 +294,6 @@ gemini mcp add lmgrep -- lmgrep mcp
 gemini mcp add lmgrep -- npx -y lmgrep mcp
 ```
 
-### Pi coding agent
-
-Pi doesn't speak MCP — it uses TypeScript extensions instead. lmgrep ships one at [`pi-extension/`](./pi-extension) that registers two tools: `lmgrep_search` and `lmgrep_list_other_indexed_projects`. It imports lmgrep directly, runs an in-process file watcher to keep the index fresh, and gates tool visibility on embedder health — if lmgrep isn't configured, or the embedding provider is unreachable, the tools stay hidden so you get a clean tool surface instead of a broken one. Configure lmgrep first (`lmgrep init`) before relying on it inside Pi.
-
-Install via Pi's package manager:
-
-```sh
-pi install git:github.com/Aetherall/lmgrep
-```
-
-Update with `pi update`, remove with `pi remove git:github.com/Aetherall/lmgrep`, and list installed extensions with `pi list`.
-
 ### OpenCode
 
 OpenCode has no one-shot install flag — add an entry to `~/.config/opencode/opencode.json` (or project-level `opencode.json`):
@@ -200,13 +318,27 @@ The MCP server exposes a `search` tool and a `list_other_indexed_projects` tool.
 
 ## Configuration
 
-lmgrep looks for configuration in this order:
+There are two kinds of setting, split by what they describe.
+
+**Machine settings** — which model to embed with, which to answer with, where
+those servers listen — describe this computer. They live in one file:
+
+- `~/.config/lmgrep/config.yml` (Linux) or `~/Library/Application Support/lmgrep/config.yml` (macOS)
+- `~/.lmgrep.yml` still works, as a deprecated location
 
-1. `.lmgrep.yml` in the project root (per-project)
-2. `~/.config/lmgrep/config.yml` (global, Linux) or `~/Library/Application Support/lmgrep/config.yml` (macOS)
-3. `~/.lmgrep.yml` (legacy fallback)
+**Project settings** — what to ignore, which extensions to index — describe a
+repository, are worth committing, and go in a `.lmgrep.yml` inside it.
 
-### Example config
+A machine setting written in a project file is reported and ignored. The model
+decides what a stored vector *means*, so a project file able to change it was
+the single most confusing thing about lmgrep: two files could set `model`, and
+`status` would print the winner without saying which file it came from. If you
+want a different model for one corpus, index it under `--in <name>` — the model
+is a property of an index, not of a directory.
+
+`lmgrep status` prints exactly which file supplied which keys.
+
+### Machine config
 
 ```yaml
 # Embedding model in "provider:model" format
@@ -218,7 +350,10 @@ baseURL: http://localhost:11434/v1
 # Batch size for embedding API calls
 batchSize: 100
 
-# Optional: embedding dimensions (if model supports it)
+# Generative model for `lmgrep ask`. Optional — without it, `ask` is hidden.
+# chatModel: lmstudio:qwen/qwen3.5-9b
+
+# Optional: embedding dimensions (if the model supports it)
 # dimensions: 384
 
 # Optional: max tokens per chunk (estimated at 4 chars/token)
@@ -227,16 +362,20 @@ batchSize: 100
 # Optional: prefixes for asymmetric embedding models
 # queryPrefix: "search_query: "
 # documentPrefix: "search_document: "
+```
 
-# Optional: additional ignore patterns (merged with .gitignore)
-# ignore:
-#   - "*.generated.ts"
-#   - "fixtures/"
+### Project config — `.lmgrep.yml`
 
-# Optional: file extension control
-# extensions:
-#   include: [".sql", ".graphql", ".proto"]
-#   exclude: [".json"]
+```yaml
+# Additional ignore patterns (merged with .gitignore)
+ignore:
+  - "*.generated.ts"
+  - "fixtures/"
+
+# File extension control
+extensions:
+  include: [".sql", ".graphql", ".proto"]
+  exclude: [".json"]
 ```
 
 ### Using other providers
@@ -262,6 +401,30 @@ pnpm dev          # watch mode
 pnpm check        # format and lint (Biome)
 ```
 
+### Architecture
+
+The source is layered, with dependencies pointing inward only:
+
+```
+src/
+  domain/          entities, value objects, and the port interfaces
+  application/     use cases that orchestrate the domain
+  infrastructure/  adapters: LanceDB, filesystem, git, AI SDK, tree-sitter, p2p
+  presentation/    the CLI and the MCP server
+```
+
+`domain/` knows nothing outside itself. `application/` depends on domain ports,
+never on a concrete adapter. `LmgrepFactory` is the single place that wires the
+graph together, so no entry point needs to know the assembly order.
+
+### Conventions
+
+- **No free functions.** Behaviour lives on the type that owns it. Constant
+  tables and pure helpers land as static-only classes, which is why Biome's
+  `noStaticOnlyClass` rule is disabled — the shape is intended here.
+- **Comments explain why, not what.** A measured constant records what the
+  measurement was; a non-obvious ordering records what breaks if it changes.
+
 ## License
 
 GPL-3.0

package/completions/_lmgrep

@@ -1,19 +1,23 @@
 #compdef lmgrep
 
+# Regenerate by hand when commands change; `lmgrep completions zsh` prints this
+# file verbatim.
+
 _lmgrep() {
   local -a commands
   commands=(
-    'index:Index the current directory for semantic search'
     'search:Search the codebase using natural language'
-    'status:Show index stats and check embedding connectivity'
-    'repair:Detect and fix index inconsistencies'
-    'serve:Watch the current directory and re-index on changes'
-    'init:Detect your embedding setup and create config'
-    'config:Open the global config file in your editor'
-    'compact:Compact the index to reclaim disk space'
-    'prune:Delete the index database for the current directory'
-    'import:Import chunks and file hashes from another lmgrep database'
+    'ask:Answer a question with a local research loop'
+    'index:Index this project for semantic search'
+    'status:Report whether search works, and why not'
+    'projects:List indexes on this machine, and reclaim their space'
+    'init:Detect your local models and write the machine config'
+    'config:Open the machine config in your editor'
+    'mcp:Start the MCP server (stdio transport)'
     'completions:Output shell completions'
+    'serve:Watch this project and re-index as files change'
+    'share:Offer this project index to a peer over P2P'
+    'import:Import chunks from a peer or another lmgrep database'
   )
 
   _arguments -C \
@@ -30,55 +34,60 @@ _lmgrep() {
       case "$words[1]" in
         index)
           _arguments \
-            '(-r --reset)'{-r,--reset}'[Reset and rebuild the entire index]' \
+            '(-r --reset)'{-r,--reset}'[Discard the index and rebuild from scratch]' \
             '(-v --verbose)'{-v,--verbose}'[Show file-by-file progress]' \
             '(-s --since)'{-s,--since}'[Only consider files modified within duration]:duration' \
-            '(-f --force)'{-f,--force}'[Force re-embed even if file hash unchanged]' \
-            '(-d --dry)'{-d,--dry}'[Show what would be indexed without actually doing it]'
+            '(-d --dry)'{-d,--dry}'[Report what would be indexed, and stop]' \
+            '*--in[Project directory, or the name of a standalone index]:project or name:_files -/'
           ;;
         search)
           _arguments \
-            '1:query' \
-            '(-m --limit)'{-m,--limit}'[Max results]:number' \
-            '--scores[Show relevance scores]' \
-            '--compact[Show file paths only]' \
-            '--json[Output results as JSON]' \
-            '--min-score[Minimum score threshold]:score' \
-            '--file-prefix[Only search files matching this path prefix]:prefix:_files -/' \
-            '--not[Exclude results similar to this query]:query' \
-            '--type[Only return chunks of these AST types]:types' \
-            '--language[Only return chunks from files with these extensions]:extensions' \
-            '--project[Search a different project index]:path:_files -/' \
-            '--across[Search multiple project indexes]:paths'
+            '(-m --limit)'{-m,--limit}'[Max results]:count' \
+            '--under[Only search files under this path]:path:_files -/' \
+            '--language[Only search these file extensions]:extensions' \
+            '--compact[Print matching file paths only]' \
+            '--json[Print results as JSON]' \
+            '*--in[Project directory, or the name of a standalone index]:project or name:_files -/'
           ;;
-        status)
+        ask)
           _arguments \
-            '(-c --changes)'{-c,--changes}'[Scan for changed files since last index]' \
-            '--json[Output status as JSON]'
+            '--json[Print the full result as JSON]' \
+            '--quiet[Suppress the live research trace on stderr]' \
+            '*--in[Project directory, or the name of a standalone index]:project or name:_files -/'
           ;;
-        repair)
+        status)
           _arguments \
-            '(-d --dry)'{-d,--dry}'[Show what would be repaired without making changes]' \
-            '--json[Output repair results as JSON]'
+            '(-v --verbose)'{-v,--verbose}'[Also show index statistics and probes]' \
+            '(-c --changes)'{-c,--changes}'[Scan for files changed since the last index]' \
+            '--json[Print status as JSON]' \
+            '*--in[Project directory, or the name of a standalone index]:project or name:_files -/'
+          ;;
+        projects)
+          local -a subcommands
+          subcommands=(
+            'list:Show every index, largest first'
+            'adopt:Move this project index from the state directory into the repository'
+            'rm:Delete an index'
+            'gc:Delete indexes whose project no longer exists'
+          )
+          _describe 'subcommand' subcommands
           ;;
         init)
-          _arguments \
-            '--force[Overwrite existing config]' \
-            '--local[Write a project-local .lmgrep.yml instead of the global config]'
+          _arguments '--force[Overwrite the existing config]'
           ;;
-        prune)
+        serve|mcp)
           _arguments \
-            '--force[Skip confirmation]'
+            '*--in[Project directory, or the name of a standalone index]:project or name:_files -/'
           ;;
         import)
           _arguments \
-            '1:database path:_files' \
-            '--reset[Reset the current index before importing]'
+            '--reset[Reset the current index before importing]' \
+            '1:share code or database path:_files -/'
           ;;
         completions)
-          _arguments \
-            '1:shell:(zsh)' \
-            '--install[Install to site-functions]'
+          local -a shells
+          shells=('zsh:Output zsh completions')
+          _describe 'shell' shells
           ;;
       esac
       ;;

package/dist/application/Lmgrep.d.ts

@@ -0,0 +1,107 @@
+import type { LmgrepConfig } from "../domain/config/LmgrepConfig.js";
+import type { FileManifest } from "../domain/corpus/SourceFile.js";
+import type { ChunkerPort } from "../domain/ports/ChunkerPort.js";
+import type { ChunkRepositoryPort } from "../domain/ports/ChunkRepositoryPort.js";
+import type { DatabaseSessionPort } from "../domain/ports/DatabaseSessionPort.js";
+import type { EmbedderPort } from "../domain/ports/EmbedderPort.js";
+import type { FileManifestRepositoryPort } from "../domain/ports/FileManifestRepositoryPort.js";
+import type { DedupeReport, IndexMaintenancePort, OptimizeReport } from "../domain/ports/IndexMaintenancePort.js";
+import type { IndexMetadataPort } from "../domain/ports/IndexMetadataPort.js";
+import type { LoggerPort } from "../domain/ports/LoggerPort.js";
+import type { ProjectRegistryPort } from "../domain/ports/ProjectRegistryPort.js";
+import type { DatabaseLocation } from "../domain/project/DatabaseLocation.js";
+import type { ProjectId } from "../domain/project/ProjectId.js";
+import type { ProjectLocator } from "../domain/project/ProjectLocator.js";
+import type { TraceEntry } from "../domain/research/ResearchTrace.js";
+import type { HitList } from "../domain/retrieval/HitList.js";
+import type { BranchManifestSweeper } from "./indexing/BranchManifestSweeper.js";
+import type { IndexBuilder } from "./indexing/IndexBuilder.js";
+import type { IndexBuildOptions, IndexBuildResult } from "./indexing/IndexingProgress.js";
+import type { IndexAlternatives } from "./operations/IndexAlternatives.js";
+import type { StatusInfo, StatusService } from "./operations/StatusService.js";
+import type { WatchService } from "./operations/WatchService.js";
+import type { ResearchAgent, ResearchResult } from "./research/ResearchAgent.js";
+import { type SearchOptions } from "./search/SearchCriteria.js";
+import type { SearchService } from "./search/SearchService.js";
+/** What a maintenance pass changed. */
+export interface TidyReport {
+    deduped: DedupeReport;
+    optimized: OptimizeReport;
+}
+/** Everything an Lmgrep instance owns, assembled by the composition root. */
+export interface LmgrepServices {
+    cwd: string;
+    config: LmgrepConfig;
+    location: DatabaseLocation;
+    locator: ProjectLocator;
+    logger: LoggerPort;
+    tables: DatabaseSessionPort;
+    chunks: ChunkRepositoryPort;
+    manifest: FileManifestRepositoryPort;
+    maintenance: IndexMaintenancePort;
+    metadata: IndexMetadataPort;
+    registry: ProjectRegistryPort;
+    alternatives: IndexAlternatives;
+    embedder: EmbedderPort;
+    chunker: ChunkerPort;
+    builder: IndexBuilder;
+    sweeper: BranchManifestSweeper;
+    searcher: SearchService;
+    statusReporter: StatusService;
+    watcher: WatchService;
+    researcher: ResearchAgent;
+    projectId: () => ProjectId;
+}
+/**
+ * The application façade: one object exposing every operation the CLI, the MCP
+ * server and the Pi extension need.
+ *
+ * It holds no logic of its own — each method delegates to the service that
+ * owns that behaviour. Its job is to be the single place where a caller
+ * acquires a working, wired-up lmgrep, so no entry point has to know the
+ * assembly order.
+ */
+export declare class Lmgrep {
+    private readonly services;
+    constructor(services: LmgrepServices);
+    get cwd(): string;
+    get config(): LmgrepConfig;
+    get location(): DatabaseLocation;
+    build(options?: IndexBuildOptions): Promise<IndexBuildResult>;
+    search(query: string, options?: SearchOptions): Promise<HitList>;
+    ask(question: string, onTrace?: (entry: TraceEntry) => void): Promise<ResearchResult>;
+    status(): Promise<StatusInfo>;
+    /** Start watching; returns a function that stops it. */
+    watch(): () => void;
+    /** The current branch's file manifest, for change previews. */
+    currentManifest(): Promise<FileManifest>;
+    /**
+     * Everything the index needs done to it that is not indexing: drop dead
+     * branches' manifests, remove duplicate and superseded rows, compact the
+     * fragments, and train the vector index if the table has grown into
+     * wanting one.
+     *
+     * These were three separate commands. They are one call because they are
+     * one intent and because the order between them is not optional: `dedupe`
+     * keeps any chunk version some manifest still references, so sweeping dead
+     * branches has to happen first or their leftover rows shield their own
+     * orphaned chunks from collection.
+     */
+    tidy(): Promise<TidyReport>;
+    get maintenance(): IndexMaintenancePort;
+    /** Every index this machine knows about. */
+    get registry(): ProjectRegistryPort;
+    /** This project's indexes under other embedding models. */
+    get alternatives(): IndexAlternatives;
+    get projectId(): ProjectId;
+    /**
+     * Whether this working directory has a usable index.
+     *
+     * An indexed ancestor counts: running from a subdirectory of an indexed
+     * tree is ordinary, and reporting it as unindexed would disable search for
+     * no reason. A manually targeted database is flat, so only its own path
+     * matters.
+     */
+    isIndexed(): boolean;
+    close(): Promise<void>;
+}