hyperdb-mcp 0.7.2 → 1.0.0-rc.1

package/README.md

@@ -1,6 +1,6 @@
 # hyperdb-mcp
 
-> **Note:** This crate is AI-assisted but human-directed — much of the code was written by AI coding assistants under close review, with the design and engineering trade-offs decided by an experienced developer. The pre-1.0 (0.x) line may still undergo large breaking changes; the public API won't settle until the 1.0.0 release.
+> **Note:** This crate is AI-assisted but human-directed — much of the code was written by AI coding assistants under close review, with the design and engineering trade-offs decided by an experienced developer. As of 1.0.0 the public API is stable and follows [semantic versioning](https://semver.org/), so breaking changes require a major release.
 
 An MCP (Model Context Protocol) server that turns the Hyper columnar database into an instant SQL analytics engine. Data flows in from other MCP plugins or files, lands in Hyper automatically, and becomes queryable with SQL — no setup, no schema files, no database management.
 
@@ -17,13 +17,14 @@ LLMs are powerful at reasoning but cannot natively crunch millions of rows. This
 Unlike flat-text memory systems that store blobs and retrieve by similarity search, HyperDB gives LLMs **structured, queryable long-term memory**. The persistent database survives across sessions — anything the LLM stores there can be JOINed, filtered, aggregated, and reasoned over with full SQL in any future conversation.
 
 This means an LLM can:
+
 - **Accumulate knowledge over time** — store reference tables, project decisions, user preferences, learned facts
 - **Cross-reference across sessions** — JOIN today's analysis against historical data from last week
 - **Answer complex recall questions** — "Which projects had budget overruns in Q1?" is a SQL query, not a fuzzy text search
 - **Build on prior work** — load yesterday's cleaned dataset and extend it without re-processing from scratch
 - **Maintain structured context** — store relationship graphs, timelines, or decision logs as proper tables with typed columns
 
-The ephemeral database is scratch space (think: a whiteboard). The persistent database is long-term memory (think: a filing cabinet you can query). Multiple AI clients sharing the same daemon see the same persistent data — so Claude Code, Cursor, and VS Code Copilot can all read from and contribute to the same knowledge base.
+The local database is ephemeral scratch space (think: a whiteboard). The persistent database is long-term memory (think: a filing cabinet you can query). Multiple AI clients sharing the same daemon see the same persistent data — so Claude Code, Cursor, and VS Code Copilot can all read from and contribute to the same knowledge base.
 
 **Table or key-value store?** For a handful of small facts, notes, or flags, prefer the built-in key-value store (`kv_set` with `persist: true`) over `CREATE TABLE` + `load_data` — it needs no schema and no DDL. Reach for a real table when you need typed columns, JOINs, or aggregation. See [Working with both databases](#working-with-both-databases) for the `persist` / `database` mechanics that apply to both paths.
 
@@ -48,9 +49,9 @@ The ephemeral database is scratch space (think: a whiteboard). The persistent da
 - **Smart schema inference** — exact (Arrow/Parquet), structural (JSON), heuristic (CSV) with full-file numeric widening
 - **Pre-ingest file inspection** — `inspect_file` dry-runs the same inference without touching Hyper so LLMs can build safe schema overrides in one shot
 - **Partial schema overrides** — supply just the columns you want to correct (e.g. `{"population":"BIGINT"}`) — the rest keep their inferred type
-- **Rich resource surface** — workspace readme, per-table JSON and CSV samples, and one JSON + one CSV resource per table so LLMs can orient themselves via `resources/list` without any tool calls
+- **Rich resource surface** — database overview, per-table JSON and CSV samples, and one JSON + one CSV resource per table so LLMs can orient themselves via `resources/list` without any tool calls
 - **Saved queries** — register named read-only SQL with `save_query`; each query becomes `hyper://queries/{name}/definition` (metadata) + `hyper://queries/{name}/result` (live re-run). Persisted in the persistent attachment, session-only when `--ephemeral-only`
-- **Key-value scratchpad** — lightweight `kv_set` / `kv_get` / `kv_list` / `kv_delete` / `kv_pop` / `kv_size` / `kv_clear` / `kv_list_stores` store for small notes and state without a `CREATE TABLE`. Ephemeral by default (lost on restart); pass `persist: true` (or `database: "persistent"`) to make a store durable across sessions
+- **Key-value scratchpad** — lightweight `kv_set` / `kv_set_many` / `kv_get` / `kv_list` / `kv_delete` / `kv_pop` / `kv_size` / `kv_clear` / `kv_list_stores` store for small notes and state without a `CREATE TABLE`. Ephemeral by default (lost on restart); pass `persist: true` (or `database: "persistent"`) to make a store durable across sessions
 - **Live resource-update notifications** — MCP clients can `resources/subscribe` to any `hyper://...` URI; the server fires `notifications/resources/updated` after every ingest, DDL, watcher event, or saved-query mutation
 
 ---
@@ -76,6 +77,7 @@ The npm package bundles both the `hyperdb-mcp` binary and the `hyperd` database
 `nvm` (Node Version Manager) makes it easy to install and switch between Node.js versions.
 
 **macOS / Linux** ([nvm-sh/nvm](https://github.com/nvm-sh/nvm)):
+
 ```bash
 # install nvm if you don't have it
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
@@ -87,6 +89,7 @@ node --version    # should report v22.x.x or newer
 ```
 
 **Windows** ([coreybutler/nvm-windows](https://github.com/coreybutler/nvm-windows)): download the installer, then in a new shell:
+
 ```powershell
 nvm install lts
 nvm use lts
@@ -118,12 +121,16 @@ export HYPERD_PATH="$PWD/.hyperd/current" # or pass via your MCP config
 `hyperdb-bootstrap` also has a library API if you'd rather wire the
 download into your own build script — see its
 [README](../hyperdb-bootstrap/README.md). If you already have `hyperd`
-elsewhere (Tableau Hyper API for C++/Python/Java ships one), point
-`HYPERD_PATH` at it or add it to your `PATH`.
+elsewhere (Tableau Hyper API for C++/Python/Java ships one), set
+`HYPERD_PATH` to either the executable or its containing directory.
+When that variable is absent or non-UTF-8, the runtime walks upward from its
+current directory for `.hyperd/current/hyperd`; it does not perform a general
+`PATH` lookup.
 
 ### MCP Client Configuration
 
 Each AI tool reads MCP server config from a different file but uses the same JSON shape. The base config block using npx (recommended):
+
 ```json
 {
   "mcpServers": {
@@ -137,6 +144,7 @@ Each AI tool reads MCP server config from a different file but uses the same JSO
 ```
 
 Or if you built from source:
+
 ```json
 {
   "mcpServers": {
@@ -152,17 +160,24 @@ Or if you built from source:
 ```
 
 By default, persistent storage lives at the platform data dir (`~/Library/Application Support/hyperdb/workspace.hyper` on macOS, `~/.local/share/hyperdb/workspace.hyper` on Linux, `%APPDATA%\hyperdb\workspace.hyper` on Windows). To use a custom path:
+
 ```json
 "args": ["--persistent-db", "/path/to/my-project.hyper"]
 ```
 
-Multiple MCP clients can point at the **same** persistent file simultaneously — they all connect through the shared `hyperd` daemon and use Hyper's MVCC transaction isolation. See [Operating Modes](#operating-modes) below.
+Multiple MCP clients can point at the **same** persistent file simultaneously
+when they reuse the shared `hyperd` daemon; Hyper's MVCC transaction isolation
+coordinates their connections. A separate private `hyperd`, Tableau, or another
+process trying to attach the same file can instead receive contextual
+`RESOURCE_BUSY`. See [Operating Modes](#operating-modes) and
+[Error Handling](#error-handling).
 
 #### Claude Code / AI Suite
 
 Create or edit `~/.claude/.mcp.json` (global) or `.mcp.json` in the project root (project-scoped). Use the base config block above.
 
 After adding the config:
+
 1. Start a new Claude Code session. You'll be prompted to approve the server on first use.
 2. **Auto-approve tools (optional):** Add `"mcp__HyperDB__*"` to the `permissions.allow` array in `~/.claude/settings.json`.
 
@@ -182,7 +197,7 @@ Any tool that supports the MCP stdio transport can use this server. Point it at
 
 ## Operating Modes
 
-Each session has **two databases**: an ephemeral primary (scratch space — always created fresh per session, deleted on exit) and a persistent database (queryable long-term memory — stored at the platform-default location or a path you supply, survives indefinitely). Unqualified SQL targets the ephemeral primary; the persistent database is reachable as the `"persistent"` alias.
+Each session has **two databases**: the ephemeral **local** primary (scratch space — always created fresh per session, deleted on exit) and a **persistent** database (queryable long-term memory — stored at the platform-default location or a path you supply, survives indefinitely). Unqualified SQL targets local; the durable database is reachable as the `"persistent"` alias. Additional `.hyper` files are **attached databases** under user-chosen aliases.
 
 ### Hyper engine
 
@@ -197,15 +212,15 @@ The shared daemon is the bigger win for users running multiple AI clients (Claud
 
 | Mode | Flag | Behavior |
 |---|---|---|
-| **Default** | *(none)* | Ephemeral primary in `$TMPDIR/hyperdb-mcp-<pid>-<n>/scratch.hyper` + persistent attachment at the platform data dir (e.g. `~/Library/Application Support/hyperdb/workspace.hyper` on macOS). |
+| **Default** | *(none)* | Ephemeral local database in `$TMPDIR/hyperdb-mcp-<pid>-<n>/scratch.hyper` + persistent attachment at the platform data dir (e.g. `~/Library/Application Support/hyperdb/workspace.hyper` on macOS). |
 | **Custom persistent path** | `--persistent-db <PATH>` | Same as default but the persistent file lives at `<PATH>`. The deprecated `--workspace <PATH>` is accepted as an alias with a stderr warning. |
-| **Ephemeral-only** | `--ephemeral-only` | No persistent attachment; the session has only the ephemeral primary plus any user-attached databases via `attach_database`. Saved queries fall back to in-memory storage and disappear when the session ends. |
+| **Ephemeral-only** | `--ephemeral-only` | No persistent attachment; the session has only the local database plus any user-attached databases via `attach_database`. Saved queries fall back to in-memory storage and disappear when the session ends. |
 
 `HYPERDB_PERSISTENT_DB` overrides the default persistent path the same way `--persistent-db` does.
 
 ### Working with both databases
 
-Tool calls default to the ephemeral primary — that's the LLM's scratch space for exploratory work that doesn't need to outlive the session. To store data in long-term memory (the persistent database), there are two ways to reach it:
+Tool calls default to the local database — that's the LLM's ephemeral scratch space for exploratory work that doesn't need to outlive the session. To store data in long-term memory (the persistent database), there are two ways to reach it:
 
 **1. Per-tool `database` parameter** (preferred for ergonomic LLM workflows):
 
@@ -222,7 +237,12 @@ describe({ database: "persistent" })
 sample({ table: "customers", database: "persistent" })
 ```
 
-The `database` parameter is available on `query`, `execute`, `load_data`, `load_file`, `load_files`, `watch_directory`, `describe`, `sample`, `chart`, `export`, and `set_table_metadata`. The shorthand `persist: true` (sugar for `database: "persistent"`) is available on `load_data`, `load_file`, `load_files`, and `watch_directory`. Pass any user-attached writable alias (created via `attach_database`) to target a custom database.
+The `database` parameter is available on `query`, `execute`, `load_data`, `load_file`, `load_files`, `watch_directory`, `describe`, `sample`, `chart`, `export`, and `set_table_metadata`. The shorthand `persist: true` (sugar for `database: "persistent"`) is available on `load_data`, `load_file`, `load_files`, and `watch_directory`. Read tools generally accept a read-only user attachment; write tools require a writable one. The exception is the KV family: every `kv_*` call to a user attachment requires it to be writable because the backing table may need initialization.
+
+Every successful database-routed response includes the canonical
+`resolved_database`: `"local"`, `"persistent"`, or the lowercase attached
+alias after precedence is applied. An explicit `database` wins over
+`persist: true`; `copy_query` additionally retains `target_database`.
 
 (`query_data` and `query_file` are one-shot tools that materialize the inline data into their own temp table and query it — they do not accept a `database` parameter because the data isn't in a persisted database to begin with.)
 
@@ -237,7 +257,12 @@ CREATE TABLE "persistent"."public"."revenue_2026" AS
   SELECT region, SUM(amount) FROM scratch_orders GROUP BY region;
 ```
 
-**Per-database `_table_catalog`:** every writable database — persistent and any user-attached writable file — gets its own `_table_catalog` lazily seeded on first ingest. MCP-managed metadata (load tool, params, timestamps, prose fields set via `set_table_metadata`) lives alongside the data file, so opening a `.hyper` file later as a primary workspace finds the catalog ready. If you want a pristine `.hyper` file for export with no MCP bookkeeping, run `DROP TABLE "<alias>"."public"."_table_catalog"` once and subsequent sessions opening that file will leave it dropped.
+**Metadata catalogs:** local and persistent tables share the persistent
+`_table_catalog`, keyed by table name across their union. `set_table_metadata`
+therefore targets an existing catalog entry rather than re-checking that the
+table exists in a selected local/persistent database. Each writable
+user-attached database has its own per-database catalog; read-only attachments
+cannot be metadata targets.
 
 **Detach safety:** `detach_database` rejects with `InvalidArgument` if any active watcher targets the alias — call `unwatch_directory` first. This prevents the watcher's pool from silently writing into a now-detached file (or worse, the wrong file if the alias is later re-attached to a different path).
 
@@ -255,7 +280,29 @@ hyperdb-mcp daemon          # Run as a daemon explicitly (rarely needed)
 
 State files live at `~/.hyperdb/` by default (override with `HYPERDB_STATE_DIR`).
 
-**Port discovery.** The daemon binds a TCP health/lock port — by default it scans upward from **7485** (16 ports) and uses the first free one; set `HYPERDB_DAEMON_PORT` to pin an exact port (no scan). The health port doubles as a single-instance lock and an identity check: clients send `PING` and require a `PONG hyperdb-mcp <version>` reply before trusting a daemon, so an unrelated process occupying the port is skipped rather than mistaken for the daemon.
+For installation and configuration diagnostics that also work before MCP can start, use the native doctor command:
+
+```bash
+hyperdb-mcp doctor
+hyperdb-mcp doctor --json
+```
+
+Doctor is side-effect-free: it creates no directories, does not start a daemon
+or `hyperd`, and does not open or create a database. Its native executable, MCP build,
+and compiled Rust API identities are authoritative; npm wrapper/platform
+details are bounded, optional launcher-reported provenance. A live daemon is
+attributed only after a fresh `STATUS` response is verified. Reports contain
+local paths; review them before sharing.
+
+**Port discovery.** MCP auto-spawn discovers a live daemon first, then scans
+upward from **7485** across 16 candidates before starting one at the selected
+exact port. Setting `HYPERDB_DAEMON_PORT` pins auto-spawn to one candidate.
+In contrast, a manually launched foreground `hyperdb-mcp daemon` never scans:
+`--port <PORT>` binds that exact port, while an omitted `--port` binds the
+configured/base port exactly. The health port doubles as a single-instance
+lock and identity check: clients send `PING` and require a
+`PONG hyperdb-mcp <version>` reply before trusting a daemon, so an unrelated
+process is not mistaken for HyperDB.
 
 **Staying resident.** By default the daemon never idle-shuts-down — keeping `hyperd` warm means the next tool call connects immediately instead of triggering a "restarting, please retry" round-trip. To opt into auto-shutdown (e.g. on CI), pass `--idle-timeout <SECS>` or set `HYPERDB_DAEMON_IDLE_TIMEOUT`.
 
@@ -273,7 +320,7 @@ If hyperd repeatedly fails to start (3 attempts within 60 seconds — e.g., misc
 
 | Flag | Behavior |
 |---|---|
-| `--read-only` | Disables `execute`, `load_data`, `load_file`, `watch_directory`, `save_query`, `delete_query`, and the KV mutators (`kv_set`, `kv_delete`, `kv_pop`, `kv_clear`). Export (including `.hyper`) stays allowed — it's a read-only file copy. See [Read-Only Mode](#read-only-mode). |
+| `--read-only` | Guards `execute`, all four `load_*` tools, `watch_directory`, saved-query mutations, `set_table_metadata`, `copy_query`, `kv_set`, `kv_set_many`, `kv_delete`, `kv_pop`, `kv_clear`, and writable/create attachment. Read-only attachment, `unwatch_directory`, and export (including `.hyper`) stay available. See [Read-Only Mode](#read-only-mode). |
 
 ---
 
@@ -312,11 +359,11 @@ query_file(path: '/tmp/sales.parquet', sql: 'SELECT TOP 10 * FROM sales ORDER BY
 | `table_name` | string | no | Table name — defaults to filename stem |
 | `schema` | object | no | Partial column-name → type map (see [Schema Overrides](#schema-overrides)) |
 
-### Workspace Tools
+### Database Tools
 
 #### `load_data`
 
-Load inline data into a named workspace table.
+Load inline data into a named local, persistent, or attached-database table.
 
 ```
 load_data(table: 'customers', data: '[{"id":1,"name":"Alice"},...]')
@@ -332,7 +379,7 @@ load_data(table: 'customers', data: '[{"id":1,"name":"Alice"},...]')
 
 #### `load_file`
 
-Load a file into a named workspace table.
+Load a file into a named local, persistent, or attached-database table.
 
 ```
 load_file(table: 'orders', path: '/tmp/orders.csv')
@@ -346,14 +393,14 @@ load_file(table: 'orders', path: '/tmp/orders.csv')
 | `schema` | object | no | Partial column-name → type map (see [Schema Overrides](#schema-overrides)) |
 
 When you're unsure of the right types — or recovering from a previous
-`SCHEMA_MISMATCH` — call [`inspect_file`](#inspect-file) first. It reports the
+`SCHEMA_MISMATCH` — call [`inspect_file`](#inspect_file) first. It reports the
 exact schema `load_file` would use plus per-column `min` / `max` / `null_count`
 so you can build a minimal, correct override in one shot.
 
 #### `load_iceberg`
 
 Load an [Apache Iceberg](https://iceberg.apache.org/) table into a named
-workspace table. Pass the absolute path to the Iceberg table root (the
+local table. Pass the absolute path to the Iceberg table root (the
 directory containing `metadata/` and `data/`); hyperd's native Iceberg
 reader derives the schema and resolves the snapshot.
 
@@ -374,7 +421,7 @@ Iceberg table metadata.
 
 #### `query`
 
-Run a **read-only** SQL query against the workspace. Accepts `SELECT`, `WITH`, `EXPLAIN`, `SHOW`, `VALUES`. For DDL/DML use `execute`.
+Run a **read-only** SQL query against local (default), persistent, or an attached database. Accepts `SELECT`, `WITH`, `EXPLAIN`, `SHOW`, `VALUES`. For DDL/DML use `execute`.
 
 ```
 query(sql: 'SELECT c.name, SUM(o.amount) FROM orders o JOIN customers c ON o.customer_id = c.id GROUP BY c.name')
@@ -397,6 +444,7 @@ execute(sql: [
 ```
 
 Validation rules enforced before any SQL hits the server:
+
 - Array must be non-empty; no element may be empty / whitespace-only / comment-only.
 - No element may be read-only — use `query` for SELECT/WITH/EXPLAIN.
 - DDL and DML cannot be mixed in one batch (Hyper aborts mixed transactions with SQLSTATE 0A000).
@@ -405,7 +453,7 @@ Validation rules enforced before any SQL hits the server:
 
 #### `describe`
 
-List all workspace tables with their schemas, column types, and row counts.
+List all tables in the selected database with their schemas, column types, and row counts.
 
 #### `sample`
 
@@ -510,23 +558,24 @@ delete_query(name: 'top_5_customers')
 Returns `{ "deleted": true }` when the query existed, `{ "deleted": false }`
 when it did not (no error on unknown names). Disabled in read-only mode.
 
-### Key-Value Store
+### Key-Value Scratchpad
 
 Lightweight named scratchpad for stashing a value under `store` + `key` and
 recalling it later — remember a variable, a summary, a JSON config, or a
 work-queue entry without creating a table or running `load_data`.
 
-> **Stores default to the EPHEMERAL database and are LOST on server restart.**
+> **Stores default to the local database and are LOST on server restart.**
 > Pass `database="persistent"` (or `persist=true`) to make a store durable
 > across restarts, or an attached alias to target that database. Each database
 > has its own isolated set of stores; a store in one database is invisible from
 > another.
 
-Eight tools cover the surface:
+Nine tools cover the surface:
 
 | Tool | Purpose | Parameters |
 |---|---|---|
 | `kv_set` | Write/overwrite a value (upsert) | `store`, `key`, `value`, `database`, `persist` |
+| `kv_set_many` | Atomically write an `entries` batch, optionally skipping existing keys | `store`, `entries`, `overwrite`, `database`, `persist` |
 | `kv_get` | Read a value by store + key (`value` is null when absent, not an error) | `store`, `key`, `database`, `persist` |
 | `kv_delete` | Remove one key (`{deleted: true/false}`, no error on unknown key) | `store`, `key`, `database`, `persist` |
 | `kv_list` | List all keys in a store, sorted ascending | `store`, `database`, `persist` |
@@ -541,7 +590,13 @@ kv_get(store: 'session', key: 'last_report')
 ```
 
 Key properties:
-- **Read-only mode** — the four mutators (`kv_set`, `kv_delete`, `kv_pop`, `kv_clear`) are disabled and return `READ_ONLY_VIOLATION`; the four readers (`kv_get`, `kv_list`, `kv_size`, `kv_list_stores`) always work.
+
+- **Read-only mode** — the five mutators (`kv_set`, `kv_set_many`, `kv_delete`, `kv_pop`, `kv_clear`) are disabled and return `READ_ONLY_VIOLATION`; the global guard leaves the four readers (`kv_get`, `kv_list`, `kv_size`, `kv_list_stores`) available.
+- **Attached-database access** — every attached target must have been attached
+  with `writable=true`, even for readers, because a KV call may need to
+  initialize its backing table. The global `--read-only` guard still blocks
+  only the five mutators; an allowed reader can use local/persistent storage but
+  cannot use a read-only user attachment.
 - **Pop order** — `kv_pop` removes and returns the **lowest-keyed** entry in lexicographic key order (not insertion order), making a store usable as a simple work queue.
 - **No store registry** — a store that becomes empty simply **drops out** of `kv_list_stores`; there is no separate registry of store names.
 - **Backing table** — values live in `_hyperdb_kv_store(store_name, key, value)`, which is indexless (Hyper has no indexes) and hidden from `describe` by its `_hyperdb_` prefix, but is directly queryable — e.g. `LEFT JOIN` it to enrich an analytical table (always filter on `kv.store_name`). Uniqueness of `(store_name, key)` is enforced by the tool layer's upsert, atomic within a single server process. See the `hyper://schema/kv` resource for the schema and join pattern.
@@ -564,13 +619,16 @@ export(sql: 'SELECT ...', path: '~/Desktop/analysis.hyper', format: 'hyper')
 | `path` | string | yes | Output file path |
 | `format` | string | yes | `"csv"`, `"parquet"`, `"iceberg"`, `"arrow_ipc"`, or `"hyper"` |
 
-The `"hyper"` format produces a `.hyper` file that opens directly in **Tableau Desktop**.
+The `"hyper"` format produces a `.hyper` file that opens directly in **Tableau
+Desktop**. It does not mutate the source database; it creates or replaces the
+destination and materializes every user table from the selected source into it.
 
 ### Visualization
 
 #### `chart`
 
-Render a chart from a SQL query and return it inline as an image.
+Render a bounded quick diagnostic from a SQL query. This convenience tool is
+for inspecting or sharing one chart, not for dashboard/layout composition.
 
 ```
 chart(sql: 'SELECT product, SUM(revenue) as total FROM sales GROUP BY product', chart_type: 'bar', x: 'product', y: 'total', title: 'Revenue by Product')
@@ -579,17 +637,46 @@ chart(sql: 'SELECT product, SUM(revenue) as total FROM sales GROUP BY product',
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `sql` | string | yes | Read-only SQL query returning the data to plot |
+| `database` | string | no | Route SQL to `local` (default), `persistent`, or an attached alias |
 | `chart_type` | string | yes | `bar`, `line`, `scatter`, or `histogram` |
 | `x` | string | yes* | X-axis column (for histogram, the value column) |
 | `y` | string | yes* | Y-axis column (not required for histogram) |
 | `series` | string | no | Grouping column for multi-series plots |
+| `color_map` | object | no | Map series names to hex colors such as `{"East":"#e41a1c"}` |
+| `label_points` | bool | no | Label line/scatter points by series and suppress their legend |
 | `title` | string | no | Chart title |
 | `format` | string | no | `png` (default) or `svg` |
 | `width` | int | no | Pixels (default 800, clamped 200..4096) |
 | `height` | int | no | Pixels (default 480, clamped 150..4096) |
 | `bins` | int | no | Histogram bins (default 20, clamped 1..500) |
-
-Returns an `ImageContent` (base64 PNG or SVG) plus a stats JSON block.
+| `output_path` | string | no | Destination file; parent directories are created |
+| `inline` | bool | no | Return image bytes inline (default `true`) |
+| `overwrite` | bool | no | Permit replacing `output_path` (default `true`) |
+| `bar_orientation` | string | no | `vertical` (default) or `horizontal`; bars only |
+| `label_values` | bool | no | Draw each original y scalar beside its bar |
+| `show_legend` | bool | no | Show series legend (default `true`) |
+| `y_scale` | string | no | `linear` (default) or positive `log`; no log histograms |
+| `x_as_category` | bool | no | Force even categorical spacing on line/scatter x values |
+| `x_range` / `y_range` | number pair | no | Explicit finite, strictly increasing bounds |
+
+With neither path nor delivery override, the PNG (or requested SVG) is returned
+inline and no file is written. `output_path` means write plus inline; set
+`inline=false` for disk-only output, with an auto-generated temp path when no
+path is supplied. Explicit `format` and the path extension must agree. The
+result ends with a stats JSON block containing `resolved_database` and, when
+written, `output_path`.
+
+Line/scatter DATE, TIMESTAMP, and TIMESTAMPTZ x columns use proportional
+temporal spacing automatically; TEXT is categorical. Set `x_as_category=true`
+only when even spacing is deliberate. Bars always treat x as categorical.
+Horizontal rankings preserve SQL row order with the first row at the top.
+Long or Unicode labels are accepted but not auto-sized, so increase width or
+height when needed.
+
+All explicit ranges must be finite, strictly increasing, and representable.
+Log y values and bounds must also be positive and the explicit range must
+contain every plotted value. Log bars begin at the effective positive lower
+bound, never zero.
 
 ### Incremental Ingest
 
@@ -611,6 +698,7 @@ unwatch_directory(path: '/tmp/inbox')
 On success, both files are deleted. On failure, both are moved to `failed/` with a `.error` JSON file.
 
 Key properties:
+
 - **One directory, one table, append mode** — files must match the target schema.
 - **Initial sweep** — pre-existing `.ready` files are processed immediately.
 - **Read-only mode** — `watch_directory` is blocked; `unwatch_directory` is always allowed.
@@ -620,27 +708,32 @@ Key properties:
 
 #### `status`
 
-Returns plugin health, workspace mode, table count, total rows, disk usage, read-only flag, and active directory watchers with per-watcher stats.
+Returns MCP/native/API installation identity, daemon and Hyper connection facts,
+`default_database: "local"`, persistent-path state, table/row/disk statistics,
+read-only state, attachments, and active watchers. A full response has
+`engine_busy: false`. When `engine_busy: true`, the prompt response is partial:
+SQL-dependent statistics are intentionally omitted and `hyperd_running: false`
+is inconclusive. Retry `status` after the in-progress operation completes.
 
 ---
 
 ## MCP Resources
 
-The server exposes workspace state as MCP **Resources**, discoverable via
+The server exposes local and persistent database state as MCP **Resources**, discoverable via
 `resources/list`. Each resource advertises its own MIME type so clients
 can route it appropriately (LLM context vs. file download vs. chart).
 
 | URI | MIME | Content |
 |-----|------|---------|
-| `hyper://workspace` | `application/json` | Workspace mode, table count, total rows, disk usage |
+| `hyper://workspace` | `application/json` | Local/persistent state, table count, total rows, disk usage |
 | `hyper://tables` | `application/json` | Full list of tables with schemas and row counts |
-| `hyper://readme` | `text/markdown` | Workspace overview as markdown: table catalog, related resources per table, and tool hints for a cold-started LLM |
+| `hyper://readme` | `text/markdown` | Database overview as markdown: table catalog, related resources per table, and tool hints for a cold-started LLM |
 | `hyper://tables/{name}/schema` | `application/json` | Columns, types, nullability, and row count for one table |
 | `hyper://tables/{name}/sample` | `application/json` | First 5 rows of a table as JSON, with schema |
 | `hyper://tables/{name}/csv-sample` | `text/csv` | First 20 rows of a table as CSV, header-first |
 | `hyper://queries/{name}/definition` | `application/json` | Stored SQL + metadata for a saved query |
 | `hyper://queries/{name}/result` | `application/json` | Live result of a saved query — re-runs on every read |
-| `hyper://schema/kv` | `text/plain` | KV scratchpad schema: the `_hyperdb_kv_store(store_name, key, value)` backing table, its indexless shape, the ephemeral-vs-persistent durability rule, and the `LEFT JOIN` enrichment pattern |
+| `hyper://schema/kv` | `text/plain` | KV scratchpad schema: backing table and `LEFT JOIN` pattern, local-vs-persistent durability, global read-only guards, and writable user-attachment requirement (including readers) |
 
 Resource templates (discoverable via `resources/templates/list`):
 
@@ -670,8 +763,8 @@ of mutation:
 | `load_data` / `load_file` (replace mode) | `hyper://workspace`, `hyper://tables`, `hyper://readme`, per-table schema + sample + csv-sample | Yes |
 | `load_data` / `load_file` (append mode) | Same per-table + summary URIs | No &sup1; |
 | `watch_directory` ingest of a `.ready` pair | Same per-table + summary URIs | No &sup1; |
-| `execute` (INSERT / UPDATE / DELETE) | Workspace summary URIs | No |
-| `execute` (CREATE / DROP / ALTER / TRUNCATE / RENAME) | Workspace summary URIs | Yes |
+| `execute` (INSERT / UPDATE / DELETE) | Database-summary URIs | No |
+| `execute` (CREATE / DROP / ALTER / TRUNCATE / RENAME) | Database-summary URIs | Yes |
 | `save_query` | (none per-URI) | Yes — two new `hyper://queries/{name}/...` resources |
 | `delete_query` | `hyper://queries/{name}/definition`, `hyper://queries/{name}/result` | Yes — two resources disappeared |
 
@@ -706,8 +799,8 @@ Four guided analytical workflows registered as MCP **Prompts**.
 hyperdb-mcp --persistent-db ~/analytics.hyper --read-only
 ```
 
-- **Allowed:** `query`, `query_data`, `query_file`, `describe`, `sample`, `inspect_file`, `status`, `export`, and the KV readers `kv_get`, `kv_list`, `kv_size`, `kv_list_stores`
-- **Blocked:** `execute`, `load_data`, `load_file`, `watch_directory`, `save_query`, `delete_query`, and the KV mutators `kv_set`, `kv_delete`, `kv_pop`, `kv_clear` — return `READ_ONLY_VIOLATION`
+- **Allowed:** `query`, `query_data`, `query_file`, `describe`, `sample`, `inspect_file`, `status`, `chart`, `export` in every format including Hyper, read-only `attach_database`, `detach_database`, `list_attached_databases`, `unwatch_directory`, `get_readme`, and the KV readers `kv_get`, `kv_list`, `kv_size`, `kv_list_stores`
+- **Blocked:** `execute`, `load_data`, `load_file`, `load_files`, `load_iceberg`, `watch_directory`, `save_query`, `delete_query`, `set_table_metadata`, `copy_query`, `kv_set`, `kv_set_many`, `kv_delete`, `kv_pop`, and `kv_clear` — return `READ_ONLY_VIOLATION`. `attach_database` is also guarded when `writable: true` or `on_missing: "create"`; ordinary read-only attachment remains available.
 - **Resources, prompts, and resource subscriptions** work normally — read-only clients can still subscribe to `hyper://...` URIs and receive notifications when other (non-read-only) connections mutate state
 
 The `query` tool also enforces read-only at the SQL level — only `SELECT`/`WITH`/`EXPLAIN`/`SHOW`/`VALUES` are accepted.
@@ -823,6 +916,7 @@ Both statements run inside a single Hyper transaction — they commit together o
 The Hyper Rust API supports `BEGIN` / `COMMIT` / `ROLLBACK` plus an RAII `Transaction` guard (see [`docs/TRANSACTIONS.md`](../docs/TRANSACTIONS.md)). The MCP `execute` tool surfaces this as the `sql` array shape: pass multiple statements and they run atomically.
 
 Hyper-specific limits worth remembering when batching:
+
 - **DDL after DML in the same transaction is rejected** with SQLSTATE 0A000. The `execute` tool catches this up front — mixing CREATE/DROP/ALTER with INSERT/UPDATE/DELETE in one batch is rejected with an actionable error.
 - **DDL is auto-committed** even inside a transaction. `execute` rejects multi-element all-DDL batches because the "atomic" promise can't be honored — issue each DDL call as its own one-element array.
 - **After any error inside a transaction**, the connection enters aborted state and only ROLLBACK is accepted next. The `execute` tool handles this for you — on any per-statement failure the wrapper issues ROLLBACK before surfacing the error.
@@ -837,7 +931,8 @@ Full reference: [Data Cloud SQL Reference](https://developer.salesforce.com/docs
 hyperdb-mcp [OPTIONS] [COMMAND]
 
 Commands:
-  daemon                  Run as a background daemon managing a shared hyperd process
+  daemon                  Run a foreground daemon managing a shared hyperd process
+  doctor                  Inspect identities/configuration without starting Hyper
 
 Options:
   --persistent-db <PATH>  Path to the persistent .hyper file. Defaults to the platform
@@ -847,8 +942,8 @@ Options:
                           the HYPERDB_PERSISTENT_DB env var.
   --ephemeral-only        Skip the persistent attachment entirely. Disables save_query
                           persistence (queries fall back to session storage).
-  --read-only             Disable mutating tools (execute, load_data, load_file,
-                          save_query, delete_query, watch_directory)
+  --read-only             Guard all load/mutation tools and writable/create attachment;
+                          read-only attachment, unwatch, and all export formats stay allowed
   --no-daemon             Disable the shared daemon and spawn a private hyperd
 
 Deprecated:
@@ -856,19 +951,21 @@ Deprecated:
                           stderr warning, and will be removed in a future release.
 
 Daemon subcommand:
-  hyperdb-mcp daemon                          Start the daemon (usually auto-spawned)
+  hyperdb-mcp daemon                          Start foreground on the configured/base port exactly
   hyperdb-mcp daemon stop                     Gracefully stop the running daemon
   hyperdb-mcp daemon status                   Show running daemon info
-  hyperdb-mcp daemon --port <PORT>            Pin the health/lock port. When omitted,
-                                              scans upward from 7485 for a free port.
+  hyperdb-mcp daemon --port <PORT>            Bind this exact health/lock port; foreground
+                                              startup never performs the auto-spawn scan.
   hyperdb-mcp daemon --idle-timeout <SECS>    Opt into idle shutdown after SECS idle.
                                               When omitted, the daemon stays resident.
 
 Environment:
-  HYPERD_PATH                  Path to hyperd binary (auto-detected if on PATH)
+  HYPERD_PATH                  Hyperd executable or containing directory; when absent or
+                               non-UTF-8, walk upward for .hyperd/current/hyperd (no PATH lookup)
   HYPERDB_PERSISTENT_DB        Override the default persistent-db path
   HYPERDB_STATE_DIR            Override daemon state directory (default ~/.hyperdb/)
-  HYPERDB_DAEMON_PORT          Pin daemon health/lock port (default: scan from 7485)
+  HYPERDB_DAEMON_PORT          Pin auto-spawn discovery to one health/lock candidate;
+                               foreground startup binds this configured/base port exactly
   HYPERDB_DAEMON_IDLE_TIMEOUT  Opt into idle shutdown (seconds); default: stay resident
 ```
 
@@ -887,6 +984,7 @@ Errors include a machine-readable code and a suggestion:
 | `SQL_ERROR` | Invalid SQL | Fix the query |
 | `TABLE_NOT_FOUND` | Table doesn't exist | Use `describe` to list tables |
 | `READ_ONLY_VIOLATION` | Mutating op in read-only mode | Use `query_*` / `inspect_file`, or restart without `--read-only` |
+| `RESOURCE_BUSY` | The reserved persistent attachment hit file contention (SQLSTATE 55006) | Run `hyperdb-mcp doctor`; compare client/daemon identities; close the possible owner (Hyper, Tableau, or another process), or copy/select another `.hyper` file; retry |
 | `CONNECTION_LOST` | `hyperd` crashed or wire protocol desynchronized | Retry — the server tears down the engine and reconnects on the next call |
 
 Server-returned errors include a machine-readable `code`, a `message`, and a
@@ -895,6 +993,12 @@ an overflow names the workflow directly: "call `inspect_file`, then retry with
 a partial schema override", so the LLM does not need to infer the recovery
 steps from the SQLSTATE alone.
 
+`RESOURCE_BUSY` is contextual: only contention while attaching the configured
+persistent file gets this classification. The error preserves the effective
+path, raw Hyper diagnostic, and SQLSTATE; unrelated `55006` SQL errors remain
+`SQL_ERROR`. Doctor compares evidence but does not claim which possible owner
+holds the file and never kills a process.
+
 ---
 
 ## Troubleshooting
@@ -903,7 +1007,9 @@ steps from the SQLSTATE alone.
 
 **Server registered but tools not callable (Claude Code)** — Add `"mcp__HyperDB__*"` to the `permissions.allow` array in `~/.claude/settings.json`.
 
-**hyperd not found** — Set `HYPERD_PATH` in the MCP server's `env` config, or place `hyperd` on your `PATH`.
+**hyperd not found** — Set `HYPERD_PATH` in the MCP server's `env` config to
+the executable or its containing directory, or install it under an ancestor's
+`.hyperd/current/` directory. The runtime does not search the general `PATH`.
 
 ---
 

package/bin.js

@@ -2,7 +2,7 @@
 // Copyright (c) 2026, Salesforce, Inc. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
-const { execFileSync } = require('child_process')
+const { spawnSync } = require('child_process')
 const { join, dirname } = require('path')
 const { existsSync } = require('fs')
 
@@ -39,20 +39,39 @@ function findBinary() {
 
   // Try resolving from the installed platform package
   try {
-    const pkgDir = dirname(require.resolve(`${pkg}/package.json`))
+    const packagePath = require.resolve(`${pkg}/package.json`)
+    const pkgDir = dirname(packagePath)
     const bin = join(pkgDir, getBinaryName())
-    if (existsSync(bin)) return { bin, dir: pkgDir }
+    if (existsSync(bin)) return { bin, dir: pkgDir, pkg, packagePath }
   } catch (_) {}
 
   // Fallback: binary in platform subdirectory (local dev / assemble-npm.sh)
   const platformDir = pkg.replace('hyperdb-mcp-', '')
   const subdir = join(__dirname, platformDir)
   const subdirBin = join(subdir, getBinaryName())
-  if (existsSync(subdirBin)) return { bin: subdirBin, dir: subdir }
+  const sourcePackagePath = join(subdir, 'package.json')
+  if (existsSync(subdirBin)) {
+    return {
+      bin: subdirBin,
+      dir: subdir,
+      pkg,
+      packagePath: sourcePackagePath,
+    }
+  }
 
   // Fallback: binary in same directory
   const localBin = join(__dirname, getBinaryName())
-  if (existsSync(localBin)) return { bin: localBin, dir: __dirname }
+  if (existsSync(localBin)) {
+    return {
+      bin: localBin,
+      dir: __dirname,
+      pkg,
+      // The manifest sits next to the binary in this branch — not in the
+      // platform subdirectory `sourcePackagePath` points at (that path does
+      // not exist here), so recompute it relative to __dirname.
+      packagePath: join(__dirname, 'package.json'),
+    }
+  }
 
   throw new Error(
     `Could not find hyperdb-mcp binary for ${platform}-${arch}. ` +
@@ -60,24 +79,91 @@ function findBinary() {
   )
 }
 
-const { bin, dir } = findBinary()
+function packageIdentity(packagePath, fallbackName) {
+  let manifest = {}
+  try {
+    manifest = require(packagePath)
+  } catch (_) {}
+
+  return {
+    name: typeof manifest.name === 'string' ? manifest.name : fallbackName,
+    version: typeof manifest.version === 'string' ? manifest.version : null,
+    package_path: packagePath,
+  }
+}
+
+function buildLauncherInfo({ wrapper, platform, executable_path }) {
+  return {
+    wrapper: {
+      name: wrapper.name,
+      version: wrapper.version ?? null,
+      package_path: wrapper.package_path,
+    },
+    platform: {
+      name: platform.name,
+      version: platform.version ?? null,
+      package_path: platform.package_path,
+    },
+    executable_path,
+  }
+}
+
+function prepareLauncherEnvironment({
+  inherited_env,
+  configured_hyperd,
+  bundled_hyperd,
+  launcher_info,
+}) {
+  const env = { ...inherited_env }
+  if (!configured_hyperd && bundled_hyperd !== undefined) {
+    env.HYPERD_PATH = bundled_hyperd
+  }
+  env.HYPERDB_MCP_LAUNCHER_INFO = JSON.stringify(launcher_info)
+  return env
+}
+
+function launch({ executable_path, args, env, spawnSync }) {
+  const result = spawnSync(executable_path, args, {
+    stdio: 'inherit',
+    env,
+  })
 
-// Point hyperdb-mcp at the bundled hyperd if not already set
-if (!process.env.HYPERD_PATH) {
-  const hyperd = join(dir, getHyperdName())
-  if (existsSync(hyperd)) {
-    process.env.HYPERD_PATH = hyperd
+  if (result.error) {
+    throw result.error
   }
+
+  return result.status ?? 1
 }
 
-// Spawn the MCP server, inheriting stdio for MCP protocol communication
-const result = require('child_process').spawnSync(bin, process.argv.slice(2), {
-  stdio: 'inherit',
-  env: process.env,
-})
+function main() {
+  const { bin, dir, pkg, packagePath } = findBinary()
+  const configuredHyperd = process.env.HYPERD_PATH
+
+  // Point hyperdb-mcp at the bundled hyperd if not already set
+  const bundledHyperd = join(dir, getHyperdName())
+  const launcherInfo = buildLauncherInfo({
+    wrapper: packageIdentity(join(__dirname, 'package.json'), 'hyperdb-mcp'),
+    platform: packageIdentity(packagePath, pkg),
+    executable_path: bin,
+  })
+  const env = prepareLauncherEnvironment({
+    inherited_env: process.env,
+    configured_hyperd: configuredHyperd,
+    bundled_hyperd: existsSync(bundledHyperd) ? bundledHyperd : undefined,
+    launcher_info: launcherInfo,
+  })
+
+  // Spawn the MCP server, inheriting stdio for MCP protocol communication
+  return launch({
+    executable_path: bin,
+    args: process.argv.slice(2),
+    env,
+    spawnSync,
+  })
+}
 
-if (result.error) {
-  throw result.error
+if (require.main === module) {
+  process.exit(main())
 }
 
-process.exit(result.status ?? 1)
+module.exports = { buildLauncherInfo, prepareLauncherEnvironment, launch }

package/package.json

@@ -29,10 +29,10 @@
   "engines": {
     "node": ">= 21"
   },
-  "version": "0.7.2",
+  "version": "1.0.0-rc.1",
   "optionalDependencies": {
-    "hyperdb-mcp-darwin-arm64": "0.7.2",
-    "hyperdb-mcp-linux-x64-gnu": "0.7.2",
-    "hyperdb-mcp-win32-x64-msvc": "0.7.2"
+    "hyperdb-mcp-darwin-arm64": "1.0.0-rc.1",
+    "hyperdb-mcp-linux-x64-gnu": "1.0.0-rc.1",
+    "hyperdb-mcp-win32-x64-msvc": "1.0.0-rc.1"
   }
 }