@gmickel/gno 1.12.4 → 1.14.0

package/README.md

@@ -92,9 +92,18 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 
 ## What's New
 
-> Latest release: [v1.8.0](./CHANGELOG.md#180---2026-06-05)  
+<!-- public-truth:current-version -->
+
+> Current release: **v1.14.0** — see [CHANGELOG.md](./CHANGELOG.md)
+
+<!-- /public-truth -->
+
 > Full release history: [CHANGELOG.md](./CHANGELOG.md)
 
+- **Retrieval-proven activation**: `gno status`, `gno doctor`, REST, and the
+  Web/Desktop dashboard now share a per-folder lexical retrieval proof. Local
+  semantic readiness remains independent, and installed MCP targets can run an
+  explicit read-only retrieval smoke from Connectors.
 - **Second-brain capture**: `gno capture`, REST `/api/capture`, SDK
   `client.capture()`, MCP `gno_capture`, and Web UI Quick Capture write
   provenance-rich notes from text, stdin, or files, including typed presets for
@@ -105,7 +114,9 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 - **Publish to [gno.sh](https://gno.sh/publish)**: new `gno publish export` CLI and Web UI action produce a self-contained artifact you upload to the hosted reader — public, secret, invite-only, or locally encrypted before upload
 - **Retrieval Quality Upgrade**: stronger BM25 lexical handling, code-aware chunking, terminal result hyperlinks, and per-collection model overrides
 - **Code Embedding Benchmarks**: new benchmark workflow across canonical, real-GNO, and pinned OSS slices for comparing alternate embedding models
-- **Default Embed Model**: built-in presets now use `Qwen3-Embedding-0.6B-GGUF` after it beat `bge-m3` on both code and multilingual prose benchmark lanes
+<!-- public-truth:default-embed-model -->
+- **Default Embed Model**: all four built-in presets use `Qwen3-Embedding-0.6B-GGUF`; see the dated, fixture-scoped evidence below
+<!-- /public-truth -->
 - **Regression Fixes**: tightened phrase/negation/hyphen/underscore BM25 behavior, cleaned non-TTY hyperlink output, improved `gno doctor` chunking and embedding fingerprint visibility, and fixed the embedding autoresearch harness
 
 ### Upgrading Existing Collections
@@ -197,7 +208,11 @@ Manage the detached process with `gno daemon --status` and `gno daemon --stop`.
 
 ### Install GNO
 
-Requires [Bun](https://bun.sh/) >= 1.3.0.
+<!-- public-truth:runtime -->
+
+Requires [Bun](https://bun.sh/) >=1.3.0.
+
+<!-- /public-truth -->
 
 ```bash
 bun install -g @gmickel/gno
@@ -209,16 +224,27 @@ bun install -g @gmickel/gno
 brew install sqlite3
 ```
 
-Verify everything works:
+Verify the local installation and corpus-derived lexical retrieval:
 
 ```bash
 gno doctor
+gno status --json
 ```
 
-**Windows**: current validated target is `windows-x64`, with a packaged
+`gno status` is passive with respect to models and connectors and exits 0 even
+when its structured activation state is degraded. `gno doctor` exits 2 when any
+configured folder fails the lexical proof; semantic models may still be pending
+without blocking BM25 search.
+
+<!-- public-truth:supported-platforms -->
+
+GNO supports macOS, Linux, and Windows. The current validated Windows target is
+`windows-x64`, with a packaged
 desktop beta zip now published on GitHub Releases. See
 [docs/WINDOWS.md](./docs/WINDOWS.md) for support scope and validation notes.
 
+<!-- /public-truth -->
+
 Keep an index fresh continuously without opening the Web UI:
 
 ```bash
@@ -248,9 +274,16 @@ gno mcp install --target codex       # OpenAI Codex CLI
 gno mcp install --target opencode    # OpenCode
 gno mcp install --target amp         # Amp
 gno mcp install --target lmstudio    # LM Studio
-gno mcp install --target librechat   # LibreChat
+gno mcp install --target librechat --scope project # LibreChat
 ```
 
+Each install records an absolute Bun/package entrypoint plus the active index,
+config, data directory, and model cache, so desktop clients open the same GNO
+workspace without relying on shell `PATH` or `GNO_*` inheritance. Inspect the
+exact command, arguments, and workspace values with
+`gno mcp install --dry-run --json`. If GNO is already configured in that
+target, add `--force` to preview the replacement without writing it.
+
 Check status: `gno mcp status`
 
 #### Skills (Claude Code, Codex, OpenCode, OpenClaw)
@@ -340,6 +373,7 @@ import { createGnoClient } from "@gmickel/gno";
 
 const client = await createGnoClient({
   configPath: "/Users/me/.config/gno/index.yml",
+  indexName: "research",
 });
 
 // Fast exact search
@@ -372,7 +406,7 @@ await client.close();
 
 Core SDK surface:
 
-- `createGnoClient({ config | configPath, dbPath? })`
+- `createGnoClient({ config | configPath, dbPath?, indexName? })`
 - `search`, `vsearch`, `query`, `ask`
 - `get`, `multiGet`, `list`, `status`
 - `update`, `embed`, `index`
@@ -514,7 +548,9 @@ Connect GNO to Claude Desktop, Cursor, Raycast, and more:
 
 ![GNO MCP](./assets/screenshots/mcp.jpg)
 
-GNO exposes tools via [Model Context Protocol](https://modelcontextprotocol.io):
+GNO exposes 17 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
+including the core retrieval tools below. Starting MCP with `--enable-write`
+adds 11 opt-in mutation tools, for 28 total.
 
 | Tool            | Description                           |
 | :-------------- | :------------------------------------ |
@@ -529,7 +565,9 @@ GNO exposes tools via [Model Context Protocol](https://modelcontextprotocol.io):
 | `gno_graph`     | Get knowledge graph (nodes and edges) |
 | `gno_status`    | Index health check                    |
 
-**Design**: MCP tools are retrieval-only. Your AI assistant (Claude, GPT-4) synthesizes answers from retrieved context. Best retrieval (GNO) + best reasoning (your LLM).
+**Design**: Default MCP mode is read-only: retrieval, graph, status, and job
+inspection. Your AI assistant synthesizes answers from retrieved context. Write
+tools are available only through the explicit `--enable-write` opt-in.
 
 [MCP setup guide →](https://gno.sh/docs/MCP/)
 
@@ -556,7 +594,11 @@ Open `http://localhost:3000` to:
 - **Same capture contract everywhere**: CLI, MCP `gno_capture`, REST `/api/capture`, SDK `client.capture()`, and Web UI Quick Capture return the same provenance receipt shape
 - **Ask**: AI-powered Q&A with citations
 - **Manage Collections**: Add, remove, and re-index collections
-- **Connect agents**: Install core Skill/MCP integrations from the app
+- **Verify retrieval**: See each folder's lexical proof, exact failed stage,
+  and remediation without waiting for semantic models
+- **Connect agents**: Install core Skill/MCP integrations; explicitly verify
+  configured MCP retrieval without changing client config. Skill installation
+  is visible, but client runtime execution cannot be proven automatically
 - **Manage files safely**: Rename, reveal, or move editable files to Trash with explicit index-vs-disk semantics
 - **Refactor files safely**: Move, duplicate, and organize editable notes with reference warnings
 - **Switch presets**: Change models live without restart
@@ -622,7 +664,10 @@ Interactive visualization of document connections. Wiki links, markdown links, a
 
 Ask questions in natural language. GNO searches your documents and synthesizes answers with inline citations linking to sources.
 
-Everything runs locally. No cloud, no accounts, no data leaving your machine.
+The Web UI and local-model path run on your machine with no account or
+telemetry. Network access occurs when GNO downloads models, when you configure
+an HTTP model backend, or when you explicitly upload an exported artifact to
+gno.sh.
 
 > **Detailed docs**: [Web UI Guide](https://gno.sh/docs/WEB-UI/)
 
@@ -697,32 +742,37 @@ curl -X POST http://localhost:3000/api/ask \
 
 # Index status
 curl http://localhost:3000/api/status
+
+# Process liveness only
+curl http://localhost:3000/api/health
 ```
 
-| Endpoint                      | Method | Description                 |
-| :---------------------------- | :----- | :-------------------------- |
-| `/api/query`                  | POST   | Hybrid search (recommended) |
-| `/api/search`                 | POST   | BM25 keyword search         |
-| `/api/ask`                    | POST   | AI-powered Q&A              |
-| `/api/docs`                   | GET    | List documents              |
-| `/api/docs`                   | POST   | Create document             |
-| `/api/docs/:id`               | PUT    | Update document content     |
-| `/api/docs/:id/move`          | POST   | Move editable document      |
-| `/api/docs/:id/duplicate`     | POST   | Duplicate editable document |
-| `/api/docs/:id/refactor-plan` | POST   | Preview file-op warnings    |
-| `/api/docs/:id/deactivate`    | POST   | Remove from index           |
-| `/api/doc`                    | GET    | Get document content        |
-| `/api/doc/:id/sections`       | GET    | Get document sections       |
-| `/api/collections`            | POST   | Add collection              |
-| `/api/collections/:name`      | DELETE | Remove collection           |
-| `/api/folders`                | POST   | Create folder               |
-| `/api/sync`                   | POST   | Trigger re-index            |
-| `/api/status`                 | GET    | Index statistics            |
-| `/api/note-presets`           | GET    | List note presets           |
-| `/api/presets`                | GET    | List model presets          |
-| `/api/presets`                | POST   | Switch preset               |
-| `/api/models/pull`            | POST   | Download models             |
-| `/api/models/status`          | GET    | Download progress           |
+| Endpoint                      | Method | Description                  |
+| :---------------------------- | :----- | :--------------------------- |
+| `/api/query`                  | POST   | Hybrid search (recommended)  |
+| `/api/search`                 | POST   | BM25 keyword search          |
+| `/api/ask`                    | POST   | AI-powered Q&A               |
+| `/api/docs`                   | GET    | List documents               |
+| `/api/docs`                   | POST   | Create document              |
+| `/api/docs/:id`               | PUT    | Update document content      |
+| `/api/docs/:id/move`          | POST   | Move editable document       |
+| `/api/docs/:id/duplicate`     | POST   | Duplicate editable document  |
+| `/api/docs/:id/refactor-plan` | POST   | Preview file-op warnings     |
+| `/api/docs/:id/deactivate`    | POST   | Remove from index            |
+| `/api/doc`                    | GET    | Get document content         |
+| `/api/doc/:id/sections`       | GET    | Get document sections        |
+| `/api/collections`            | POST   | Add collection               |
+| `/api/collections/:name`      | DELETE | Remove collection            |
+| `/api/folders`                | POST   | Create folder                |
+| `/api/sync`                   | POST   | Trigger re-index             |
+| `/api/status`                 | GET    | Index and activation state   |
+| `/api/health`                 | GET    | Process liveness only        |
+| `/api/connectors/verify`      | POST   | Explicit read-only MCP proof |
+| `/api/note-presets`           | GET    | List note presets            |
+| `/api/presets`                | GET    | List model presets           |
+| `/api/presets`                | POST   | Switch preset                |
+| `/api/models/pull`            | POST   | Download models              |
+| `/api/models/status`          | GET    | Download progress            |
 
 No authentication. No rate limits. Build custom tools, automate workflows, integrate with any language.
 
@@ -775,13 +825,13 @@ graph TD
 | **REST API**         | HTTP API for custom tools and integrations                                     |
 | **Multi-Format**     | Markdown, PDF, DOCX, XLSX, PPTX, plain text                                    |
 | **Local LLM**        | AI answers via llama.cpp, no API keys                                          |
-| **Remote Inference** | Offload to GPU servers via HTTP (llama-server, Ollama, LocalAI)                |
-| **Privacy First**    | 100% offline, zero telemetry, your data stays yours                            |
-| **MCP Server**       | Works with Claude Desktop, Cursor, Zed, + 8 more                               |
+| **Remote Inference** | Optional HTTP endpoints for embedding, reranking, expansion, and generation    |
+| **Privacy First**    | Local by default; no telemetry; network use is explicit or model provisioning  |
+| **MCP Server**       | 10 automatic client targets; 17 read-only tools, 28 with writes enabled        |
 | **Collections**      | Organize sources with patterns, excludes, contexts                             |
 | **Tag Filtering**    | Frontmatter tags with hierarchical paths, filter via `--tags-any`/`--tags-all` |
 | **Note Linking**     | Wiki links, backlinks, related notes, cross-collection navigation              |
-| **Multilingual**     | 30+ languages, auto-detection, cross-lingual search                            |
+| **Multilingual**     | Query classification, 7-language document detection, multilingual embeddings   |
 | **Incremental**      | SHA-256 tracking, only changed files re-indexed                                |
 | **Keyboard First**   | ⌘N capture, ⌘K search, ⌘/ shortcuts, ⌘S save                                   |
 
@@ -791,20 +841,20 @@ graph TD
 
 Models auto-download on first use to `~/.cache/gno/models/`. GNO validates cached GGUF files before loading and removes intercepted HTML/non-GGUF cache entries with a clear recovery error. For deterministic startup, set `GNO_NO_AUTO_DOWNLOAD=1` and use `gno models pull` explicitly. Alternatively, offload to a GPU server on your network using HTTP backends.
 
-| Model                  | Purpose                               | Size         |
-| :--------------------- | :------------------------------------ | :----------- |
-| Qwen3-Embedding-0.6B   | Embeddings (multilingual)             | ~640MB       |
-| Qwen3-Reranker-0.6B    | Cross-encoder reranking (32K context) | ~700MB       |
-| Qwen3 / Qwen2.5 family | Query expansion + AI answers          | ~600MB-2.5GB |
+| Model                  | Purpose                                          |
+| :--------------------- | :----------------------------------------------- |
+| Qwen3-Embedding-0.6B   | Embeddings                                       |
+| Qwen3-Reranker-0.6B    | Best-chunk-per-document cross-encoder reranking  |
+| Qwen3 / Qwen2.5 family | Query expansion and standalone answer generation |
 
 ### Model Presets
 
-| Preset       | Disk   | Best For                                                |
-| :----------- | :----- | :------------------------------------------------------ |
-| `slim-tuned` | ~1GB   | Current default, tuned retrieval in a compact footprint |
-| `slim`       | ~1GB   | Fast, good quality                                      |
-| `balanced`   | ~2GB   | Slightly larger model                                   |
-| `quality`    | ~2.5GB | Best answers                                            |
+| Preset       | Best For                                     |
+| :----------- | :------------------------------------------- |
+| `slim-tuned` | Current default; tuned query expansion       |
+| `slim`       | Untuned slim query expansion                 |
+| `balanced`   | Qwen2.5 3B expansion and answers             |
+| `quality`    | Qwen3 4B expansion and standalone AI answers |
 
 ```bash
 gno models use slim-tuned
@@ -822,7 +872,9 @@ GNO now has a published promoted retrieval model for the default slim path:
 
 Use it when you want the tuned retrieval expansion path immediately, without running local fine-tuning yourself.
 
-For private/internal products, use the same workflow but keep the final GGUF private and point `gen:` at a `file:` URI instead of publishing to Hugging Face.
+For private/internal products, use the same workflow but keep the final GGUF
+private and point `expand:` at a `file:` URI instead of publishing it to
+Hugging Face. The `gen:` role remains the standalone answer model.
 
 See:
 
@@ -846,7 +898,10 @@ models:
       gen: "http://192.168.1.100:8083/v1/chat/completions#qwen3-4b"
 ```
 
-Works with llama-server, Ollama, LocalAI, vLLM, or any OpenAI-compatible server.
+The HTTP adapter expects the OpenAI-compatible endpoint shapes documented in
+[Configuration](./docs/CONFIGURATION.md). Remote servers receive the query,
+chunk, or answer context sent to their configured model role; they are outside
+GNO's local trust boundary.
 
 > **Configuration**: [Model Setup](https://gno.sh/docs/CONFIGURATION/)
 
@@ -962,16 +1017,28 @@ bun run bench:general-embeddings --candidate bge-m3-incumbent --write
 bun run bench:general-embeddings --candidate qwen3-embedding-0.6b --write
 ```
 
-Current signal on the public multilingual FastAPI-docs fixture:
+<!-- public-truth:general-embedding-benchmark -->
+
+The immutable April 2026 FastAPI-docs run used 15 documents in five corpus
+languages (`en`, `de`, `fr`, `es`, `zh`) and 13 queries:
 
-- `bge-m3`: vector nDCG@10 `0.3508`, hybrid nDCG@10 `0.6756`
-- `Qwen3-Embedding-0.6B-GGUF`: vector nDCG@10 `0.9891`, hybrid nDCG@10 `0.9891`
+- [bge-m3 incumbent](./evals/fixtures/general-embedding-benchmark/2026-04-06-bge-m3-incumbent.md): vector nDCG@10 `0.3503`, hybrid nDCG@10 `0.642`
+- [Qwen3 Embedding 0.6B](./evals/fixtures/general-embedding-benchmark/2026-04-06-qwen3-embedding-0-6b.md): vector nDCG@10 `0.8594`, hybrid nDCG@10 `0.947`
+<!-- /public-truth -->
 
-Interpretation:
+A separate [July 2026 Nemotron screen](./research/embeddings/2026-07-21-nemotron-3-embed-1b.md)
+reran the same 13-query multilingual lane after runtime/profile changes. It
+measured Qwen at `0.9891` vector / `0.9891` hybrid nDCG@10 and Nemotron 3 Embed
+1B at `0.9023` / `0.9461`. Nemotron used a temporary PyTorch HTTP adapter;
+Qwen used GNO's production GGUF path. Their timings are not comparable, and no
+official production GGUF was validated for Nemotron.
 
-- Qwen is now the strongest general multilingual embedding model we have tested
-- built-in presets now use Qwen by default
-- existing users may need to run `gno embed` again after upgrading so current collections catch up
+These small fixture results support keeping Qwen as the built-in default; they
+do not establish general language superiority. Query-language classification
+supports a broader set than the indexed-document detector (`en`, `de`, `fr`,
+`it`, `zh`, `ja`, `ko`), and the committed fixture covers only five languages.
+The BM25-only multilingual eval remains a legacy sanity lane; dedicated lexical
+CJK benchmarking is pending.
 
 ---
 

package/assets/skill/SKILL.md

@@ -6,7 +6,9 @@ allowed-tools: Bash(gno:*) Read
 
 # GNO - Local Knowledge Engine
 
-Fast local semantic search. Index once, search instantly. No cloud, no API keys.
+Fast local semantic search. Index once, search instantly. Local inference needs
+no API key; configured HTTP backends and explicit gno.sh publishing are separate
+network boundaries.
 
 ## When to Use This Skill
 
@@ -226,6 +228,11 @@ gno graph --from gno://notes/a.md --to gno://notes/b.md
 --no-pager        Disable paging
 ```
 
+Index names follow the CLI filesystem-identity contract: 1–64 UTF-16 code
+units, letter/number first, no trailing space or `.`, no `..`, separators, or
+platform-invalid punctuation. NFC/case-equivalent names share one identity.
+See `docs/CLI.md` under Global Options for the complete byte limits.
+
 Non-default index search results may include `?index=<name>` on `gno://` URIs.
 Keep that query string when passing the URI to `gno get`, SDK `get()`, MCP
 `gno_get`, or an MCP resource read: it selects the named database. Batch reads

package/assets/skill/cli-reference.md

@@ -17,6 +17,11 @@ All commands accept:
 | `--no-pager`      | Disable automatic paging                 |
 | `--offline`       | Use cached models only                   |
 
+Index names use 1–64 UTF-16 code units, start with a letter or number, and
+reject trailing space/dot, `..`, separators, controls, and platform-invalid
+punctuation. NFC/case-equivalent spellings share one identity. See
+`docs/CLI.md` under Global Options for the complete canonical-byte contract.
+
 ## Initialization
 
 ### gno init
@@ -448,7 +453,8 @@ gno models list [--json|--md]
 gno models use <preset>
 ```
 
-Presets: `slim` (~1GB), `balanced` (~2GB), `quality` (~2.5GB)
+Built-ins: `slim-tuned` (default), `slim`, `balanced`, `quality`. Actual
+download/cache use depends on the selected artifacts and existing shared cache.
 
 ### gno models pull
 
@@ -523,12 +529,17 @@ Install GNO as MCP server in client configurations.
 gno mcp install [options]
 ```
 
-| Option         | Default        | Description                                      |
-| -------------- | -------------- | ------------------------------------------------ |
-| `-t, --target` | claude-desktop | Target: `claude-desktop`, `claude-code`, `codex` |
-| `-s, --scope`  | user           | Scope: `user`, `project`                         |
-| `-f, --force`  | false          | Overwrite existing config                        |
-| `--dry-run`    | false          | Preview changes                                  |
+| Option         | Default        | Description               |
+| -------------- | -------------- | ------------------------- |
+| `-t, --target` | claude-desktop | Target client (see below) |
+| `-s, --scope`  | target default | Scope: `user`, `project`  |
+| `-f, --force`  | false          | Overwrite existing config |
+| `--dry-run`    | false          | Preview changes           |
+
+Targets: `claude-desktop`, `claude-code`, `codex`, `cursor`, `zed`,
+`windsurf`, `opencode`, `amp`, `lmstudio`, and `librechat`. Project scope is
+supported by Claude Code, Codex, Cursor, OpenCode, and LibreChat.
+LibreChat is project-only; all other targets default to user scope.
 
 Examples:
 

package/assets/skill/mcp-reference.md

@@ -21,14 +21,27 @@ gno mcp install --enable-write
 
 ### Claude Desktop
 
-Add to `claude_desktop_config.json`:
+Run `gno mcp install --dry-run --json`, then add the reported absolute values to
+`claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "gno": {
-      "command": "gno",
-      "args": ["mcp"]
+      "command": "/absolute/path/to/bun",
+      "args": [
+        "run",
+        "/absolute/path/to/@gmickel/gno/src/index.ts",
+        "--index",
+        "default",
+        "--config",
+        "/absolute/path/to/index.yml",
+        "mcp"
+      ],
+      "env": {
+        "GNO_DATA_DIR": "/absolute/path/to/data",
+        "GNO_CACHE_DIR": "/absolute/path/to/cache"
+      }
     }
   }
 }
@@ -47,6 +60,12 @@ gno mcp install -t claude-code -s user    # User scope
 gno mcp install -t claude-code -s project # Project scope
 ```
 
+Installed entries deliberately pin the current Bun/package entrypoint, active
+index, absolute config, data directory, and model cache. Standard clients use
+`env`; OpenCode uses `environment`; Codex uses `~/.codex/config.toml` or project
+`.codex/config.toml` with `[mcp_servers.gno]` and `[mcp_servers.gno.env]`.
+Do not shorten a generated entry to `gno mcp`.
+
 ## Check Status
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.12.4",
+  "version": "1.14.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -118,6 +118,7 @@
     "research:finetune:mlx:fuse": "bun research/finetune/scripts/fuse-mlx.ts",
     "research:finetune:mlx:smoke": "bun research/finetune/scripts/smoke-mlx.ts",
     "reset": "bun run src/index.ts reset --confirm",
+    "docs:truth": "bun run scripts/public-truth.ts",
     "docs:verify": "bun run scripts/docs-verify.ts",
     "website:install": "cd website && bundle install",
     "website:dev": "cd website && make serve",
@@ -160,6 +161,7 @@
     "commander": "14.0.3",
     "embla-carousel-react": "8.6.0",
     "franc": "6.2.0",
+    "jsonc-parser": "3.3.1",
     "lucide-react": "1.8.0",
     "markitdown-ts": "0.0.9",
     "minimatch": "10.2.3",

package/src/app/constants.ts

@@ -10,6 +10,11 @@ import { basename, join } from "node:path";
 
 // Bun supports JSON imports natively - version single source of truth
 import pkg from "../../package.json";
+import {
+  assertValidIndexName,
+  indexNamesMatch,
+  resolveIndexDbFilename,
+} from "./index-name";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Brand / Product Identity
@@ -218,7 +223,26 @@ export function getIndexDbPath(
   indexName: string = DEFAULT_INDEX_NAME,
   dirs: ResolvedDirs = resolveDirs()
 ): string {
-  return join(dirs.data, `index-${indexName}.sqlite`);
+  assertValidIndexName(indexName);
+  let existingFilenames: string[] = [];
+  try {
+    existingFilenames = [
+      ...new Bun.Glob("index-*.sqlite").scanSync({
+        cwd: dirs.data,
+        onlyFiles: false,
+      }),
+    ];
+  } catch (error) {
+    if (
+      !error ||
+      typeof error !== "object" ||
+      !("code" in error) ||
+      error.code !== "ENOENT"
+    ) {
+      throw error;
+    }
+  }
+  return join(dirs.data, resolveIndexDbFilename(indexName, existingFilenames));
 }
 
 /**
@@ -265,8 +289,12 @@ export function buildUri(
     .map((segment) => encodeURIComponent(segment))
     .join("/");
   const uri = `${URI_PREFIX}${collection}/${encodedPath}`;
-  const indexName = options.indexName?.trim();
-  if (!indexName || indexName === DEFAULT_INDEX_NAME) {
+  const indexName = options.indexName;
+  if (indexName === undefined) {
+    return uri;
+  }
+  assertValidIndexName(indexName);
+  if (indexNamesMatch(indexName, DEFAULT_INDEX_NAME)) {
     return uri;
   }
   return `${uri}?index=${encodeURIComponent(indexName)}`;
@@ -287,8 +315,8 @@ export function parseUri(uri: string): ParsedGnoUri | null {
   if (slashIndex === -1) {
     // gno://collection (no path)
     const [collectionWithQuery, query = ""] = rest.split("?", 2);
-    const indexName = new URLSearchParams(query).get("index")?.trim();
-    return indexName
+    const indexName = new URLSearchParams(query).get("index");
+    return indexName !== null
       ? {
           collection: collectionWithQuery ?? rest,
           path: "",
@@ -307,8 +335,10 @@ export function parseUri(uri: string): ParsedGnoUri | null {
   // decodeURIComponent throws on malformed percent-encoding
   try {
     const path = decodeURIComponent(encodedPath);
-    const indexName = new URLSearchParams(query).get("index")?.trim();
-    return indexName ? { collection, path, indexName } : { collection, path };
+    const indexName = new URLSearchParams(query).get("index");
+    return indexName !== null
+      ? { collection, path, indexName }
+      : { collection, path };
   } catch {
     return null;
   }
@@ -319,12 +349,15 @@ export function parseUri(uri: string): ParsedGnoUri | null {
  */
 export function decorateUriForIndex(uri: string, indexName?: string): string {
   const parsed = parseUri(uri);
-  const normalizedIndex = indexName?.trim();
-  if (!parsed || !normalizedIndex || normalizedIndex === DEFAULT_INDEX_NAME) {
+  if (!parsed || indexName === undefined) {
+    return stripUriIndex(uri);
+  }
+  assertValidIndexName(indexName);
+  if (indexNamesMatch(indexName, DEFAULT_INDEX_NAME)) {
     return stripUriIndex(uri);
   }
   return buildUri(parsed.collection, parsed.path, {
-    indexName: normalizedIndex,
+    indexName,
   });
 }