dirsql 0.3.109 → 0.3.110

package/docs/getting-started.md

@@ -92,7 +92,7 @@ open a **second terminal** for the next step.
 ## 3. Query your files
 
 You gave `dirsql` no configuration, so it serves a single default table
-named `files` ([zero-config mode](./reference/cli.md#zero-config-mode)).
+named `files` ([default mode](./reference/cli.md#default-mode)).
 Ask it how many rows it has:
 
 ```bash
@@ -167,16 +167,18 @@ Two keys define the table:
 ## 5. Restart and query the new shape
 
 Config is read at startup, so go back to the **first terminal**, stop the
-server with `Ctrl-C`, and start it again:
+server with `Ctrl-C`, and start it again — this time pointing `dirsql` at
+your config with `-c` (`dirsql` does not auto-load a `.dirsql.toml` from the
+current directory; you always pass it explicitly):
 
 ::: code-group
 
 ```bash [npm]
-npx dirsql
+npx dirsql -c .dirsql.toml
 ```
 
 ```bash [PyPI]
-uvx dirsql
+uvx dirsql -c .dirsql.toml
 ```
 
 :::
@@ -185,7 +187,7 @@ uvx dirsql
 Running at localhost:7117
 ```
 
-This time `dirsql` found your `.dirsql.toml` and served the `notes` table
+This time `dirsql` loaded your `.dirsql.toml` and served the `notes` table
 you defined instead of the default `files` table. Query it from the second
 terminal:
 

package/docs/howto/columns-from-paths.md

@@ -29,8 +29,11 @@ within one path segment) are in
 
 ## 2. Query the captured columns
 
+Pass the config with [`-c`](../reference/cli.md#flags) (`dirsql` does not
+auto-load a `.dirsql.toml` from the current directory):
+
 ```bash
-dirsql query "SELECT year, month, basename FROM photos ORDER BY year, month"
+dirsql -c ./.dirsql.toml query "SELECT year, month, basename FROM photos ORDER BY year, month"
 ```
 
 ```json
@@ -40,7 +43,7 @@ dirsql query "SELECT year, month, basename FROM photos ORDER BY year, month"
 Captures are real SQL columns, so aggregation works:
 
 ```bash
-dirsql query "SELECT year, COUNT(*) AS photos FROM photos GROUP BY year"
+dirsql -c ./.dirsql.toml query "SELECT year, COUNT(*) AS photos FROM photos GROUP BY year"
 ```
 
 ```json

package/docs/howto/define-tables.md

@@ -2,7 +2,7 @@
 
 Map a glob of files to a named SQL table so you query exactly the files you
 care about, with exactly the columns you care about — instead of the
-catch-all `files` table that [zero-config mode](../reference/cli.md#zero-config-mode)
+catch-all `files` table that [default mode](../reference/cli.md#default-mode)
 serves.
 
 ## 1. Create a config next to your files
@@ -26,10 +26,12 @@ glob = "posts/**/*.md"
 
 ## 2. Query the table
 
-Each matched file is one row:
+Pass the config with [`-c`](../reference/cli.md#flags) — `dirsql` does not
+auto-load a `.dirsql.toml` from the current directory. Each matched file is
+one row:
 
 ```bash
-dirsql query "SELECT path, size FROM posts ORDER BY path"
+dirsql -c ./.dirsql.toml query "SELECT path, size FROM posts ORDER BY path"
 ```
 
 ```json
@@ -37,8 +39,8 @@ dirsql query "SELECT path, size FROM posts ORDER BY path"
 ```
 
 Files that don't match the glob (a `README.txt` next to `posts/`, say) are
-simply not in the table. Once a config file exists, it fully replaces the
-zero-config default — only the tables you define are served.
+simply not in the table. Passing a config with `-c` fully replaces the
+default `files` table — only the tables you define are served.
 
 ## Multiple tables
 

package/docs/howto/extract-from-contents.md

@@ -31,8 +31,11 @@ by every hook.
 
 ## 2. Query the extracted columns
 
+Pass the config with [`-c`](../reference/cli.md#flags) (`dirsql` does not
+auto-load a `.dirsql.toml` from the current directory):
+
 ```bash
-dirsql query "SELECT title, author, year, path FROM books ORDER BY year"
+dirsql -c ./.dirsql.toml query "SELECT title, author, year, path FROM books ORDER BY year"
 ```
 
 ```json
@@ -57,7 +60,7 @@ on-file = "jq -c -s '.' {path}"
 ```
 
 ```bash
-dirsql query "SELECT event, user FROM events"
+dirsql -c ./.dirsql.toml query "SELECT event, user FROM events"
 ```
 
 ```json

package/docs/howto/load-extension.md

@@ -23,10 +23,11 @@ overrides the init symbol when it doesn't match the filename-derived
 default — `sqlite-vec` is exactly such a case
 ([reference](../reference/config.md#dirsql-extension)).
 
-The extension's functions are callable:
+The extension's functions are callable (pass the config with
+[`-c`](../reference/cli.md#flags) so its `[[dirsql.extension]]` entry loads):
 
 ```bash
-dirsql query "SELECT vec_version() AS vec_version"
+dirsql -c ./.dirsql.toml query "SELECT vec_version() AS vec_version"
 ```
 
 ```json
@@ -52,7 +53,7 @@ entrypoint = "sqlite3_vec_init"
 ```
 
 ```bash
-uvx --with sqlite-vec dirsql
+uvx --with sqlite-vec dirsql -c ./.dirsql.toml
 ```
 
 **Node (`npx dirsql`, TypeScript SDK).** Use the *npm package name* — but

package/docs/howto/search-by-meaning.md

@@ -103,10 +103,12 @@ runtime — and the literal-path alternative that works everywhere — are in
 
 Run with `sqlite-vec` available to the launcher's environment. The initial
 scan runs `embed.py` once per note, then the query argument goes straight to
-`pre-query`, exactly as a `POST /query` body would:
+`pre-query`, exactly as a `POST /query` body would. Pass the config with
+[`-c`](../reference/cli.md#flags) — `dirsql` does not auto-load a
+`.dirsql.toml` from the current directory:
 
 ```bash
-uvx --with sqlite-vec dirsql query '{"q": "how do I cook pasta?"}'
+uvx --with sqlite-vec dirsql -c ./.dirsql.toml query '{"q": "how do I cook pasta?"}'
 ```
 
 ```json
@@ -114,7 +116,7 @@ uvx --with sqlite-vec dirsql query '{"q": "how do I cook pasta?"}'
 ```
 
 ```bash
-uvx --with sqlite-vec dirsql query '{"q": "reviewing code on github"}'
+uvx --with sqlite-vec dirsql -c ./.dirsql.toml query '{"q": "reviewing code on github"}'
 ```
 
 ```json

package/docs/howto/skip-files.md

@@ -31,8 +31,11 @@ ignored file never reaches any table — even one whose glob would match it.
 
 ## 2. Confirm what made it in
 
+Pass the config with [`-c`](../reference/cli.md#flags) (`dirsql` does not
+auto-load a `.dirsql.toml` from the current directory):
+
 ```bash
-dirsql query "SELECT path FROM notes ORDER BY path"
+dirsql -c ./.dirsql.toml query "SELECT path FROM notes ORDER BY path"
 ```
 
 ```json
@@ -42,7 +45,7 @@ dirsql query "SELECT path FROM notes ORDER BY path"
 ## Notes
 
 - `ignore` lives in a config file, so it needs one:
-  [zero-config mode](../reference/cli.md#zero-config-mode) indexes
+  [default mode](../reference/cli.md#default-mode) indexes
   everything with no ignores.
 - The top-level `.dirsql/` directory is always excluded, ignore list or
   not — it is reserved for `dirsql`'s own metadata

package/docs/reference/cli.md

@@ -45,7 +45,7 @@ requests, closes open `/events` streams, and exits.
 
 | Flag | Default | Description |
 |---|---|---|
-| `-c, --config <path>` | `./.dirsql.toml` | Path to a [config file](./config.md). **Repeatable** (`-c a -c b`): the configs load and merge in argv order — see [Composing multiple configs](./config.md#composing-multiple-configs). The index is always rooted at the **invocation directory** (the current working directory), regardless of where a config lives — so `--config /elsewhere/.dirsql.toml` still indexes the directory you ran `dirsql` from. With none given, `./.dirsql.toml` is used; when it does not exist, the server runs in [zero-config mode](#zero-config-mode). |
+| `-c, --config <path>` | baked-in default | Path to a [config file](./config.md). **Repeatable** (`-c a -c b`): the configs load and merge in argv order — see [Composing multiple configs](./config.md#composing-multiple-configs). The index is always rooted at the **invocation directory** (the current working directory), regardless of where a config lives — so `--config /elsewhere/.dirsql.toml` still indexes the directory you ran `dirsql` from. With none given, the [baked-in default](#default-mode) `files` table is served — a `./.dirsql.toml` on disk is **not** auto-loaded; pass it explicitly. A `-c` naming a file that does not exist is an [error](#degraded-mode), not a silent fallback to the default. |
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
 | `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches at `<root>/.dirsql/cache.db`; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Global — also honored by [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
@@ -61,11 +61,14 @@ requests, closes open `/events` streams, and exits.
   **30-second** timeout each, overridable with the config key
   [`[dirsql].hook-timeout`](./config.md#dirsql-keys).
 
-### Zero-config mode
+### Default mode
 
-When the config file named by `--config` does not exist, the server indexes
-the directory that would have contained it (the current directory for the
-default `./.dirsql.toml`) with a single table named `files`:
+With no `-c/--config`, the server serves the **baked-in default** — the
+shipped config compiled into the binary, indexing the invocation directory
+with a single table named `files`. This is a fixed default, *not* a
+`.dirsql.toml` read from disk: a `./.dirsql.toml` sitting in the current
+directory is **not** auto-loaded (pass it with `-c ./.dirsql.toml` to use
+it). The default `files` table:
 
 - Glob: `**/*` — every file under the root, at any depth, no ignores.
 - One row per file, with all seven
@@ -77,21 +80,25 @@ curl -s localhost:7117/query -H 'content-type: application/json' \
   -d '{"sql":"SELECT basename, size FROM files ORDER BY size DESC LIMIT 5"}'
 ```
 
-A config file, when present, fully overrules this default. A *missing*
-config is not an error; only a config that exists but fails to load is (see
-below).
+Passing a config with `-c` fully overrules this default. A `-c` naming a file
+that does not exist is an error (not a fallback to the default); a config that
+exists but fails to load degrades the server (see below).
 
 ### Degraded mode
 
-When the config file exists but cannot be resolved or loaded (unreadable
-path, invalid TOML, schema errors), the server still starts and binds, but
-every request to `/query` and `/events` returns `503 Service Unavailable`
-with a JSON body describing the failure:
+When a config passed with `-c` cannot be resolved or loaded — the file does
+not exist, is unreadable, or has invalid TOML / schema errors — the server
+still starts and binds, but every request to `/query` and `/events` returns
+`503 Service Unavailable` with a JSON body describing the failure (the
+diagnostic names the offending path or key):
 
 ```json
 {"error": "failed to load config: ..."}
 ```
 
+The one-shot [`dirsql query`](#dirsql-query) surfaces the same failure as a
+non-zero exit with the diagnostic on stderr.
+
 ### Exit codes
 
 | Code | Meaning |
@@ -104,10 +111,12 @@ with a JSON body describing the failure:
 Run a SQL query from the shell:
 
 ```bash
+# No -c: the baked-in default `files` table.
 dirsql query "SELECT basename, size FROM files ORDER BY size DESC LIMIT 5"
 # [{"basename":"model.bin","size":104857600}, …]
 
-dirsql query "SELECT COUNT(*) AS n FROM posts" | jq '.[0].n'
+# A config table (`posts`) needs its config passed explicitly.
+dirsql -c ./.dirsql.toml query "SELECT COUNT(*) AS n FROM posts" | jq '.[0].n'
 ```
 
 The subcommand builds the index, runs the SQL, prints the result rows as a
@@ -117,9 +126,9 @@ response body), and exits `0`.
 `dirsql query` is a thin adapter over the **same query pipeline the server
 uses**, so behavior is identical to `POST /query` by construction:
 
-- **Config discovery** honors `--config` (default `./.dirsql.toml`),
-  [zero-config mode](#zero-config-mode), and `--extension` overrides,
-  exactly as server mode does.
+- **Config discovery** honors `--config` (with none given, the
+  [baked-in default](#default-mode)), and `--extension` overrides, exactly as
+  server mode does.
 - **`--persist [<path>]`** is honored, so a repeated `dirsql query` reuses the
   on-disk cache. Because its value is optional, place a bare `--persist` after
   the SQL (`dirsql query "SELECT …" --persist`) or use the `=` form
@@ -144,13 +153,19 @@ stderr, with exit code `1`.
 
 ## `dirsql init`
 
-Writes a starter `.dirsql.toml`:
+Writes a starter `.dirsql.toml` — the same table the [baked-in
+default](#default-mode) serves — as a scaffold to edit:
 
 ```bash
 dirsql init
 ```
 
-You can further tweak this config as needed.
+The output does **not** auto-load. Once you've tweaked it, pass it explicitly
+to run against it:
+
+```bash
+dirsql -c ./.dirsql.toml
+```
 
 ### Flags
 

package/docs/reference/config.md

@@ -7,9 +7,10 @@ all-defaults one. Unknown keys are a parse error at every level (top level,
 `[dirsql]`, `[[table]]`, `[[dirsql.extension]]`) — a typo or a removed key
 fails loudly, naming the offending key, rather than silently no-opping.
 
-The [CLI](./cli.md) loads `./.dirsql.toml` by default (`--config <path>`
-overrides). The [SDKs](./sdk.md) load a config via the `config` constructor
-parameter.
+The [CLI](./cli.md) loads a config only when you pass it with `-c/--config`;
+with none given it serves the [baked-in default](./cli.md#default-mode) (a
+`./.dirsql.toml` on disk is **not** auto-loaded). The [SDKs](./sdk.md) load a
+config via the `config` constructor parameter.
 
 **Path resolution.** Relative paths in the config (`[[dirsql.extension]]`
 `path`) resolve against the config file's parent
@@ -160,8 +161,9 @@ The configs load and merge in **argv order**:
   error**, naming the table.
 
 The index [root](./cli.md#flags) is the invocation directory regardless of where
-any config lives. With no `-c`, `./.dirsql.toml` is used; a single `-c` behaves
-exactly as before.
+any config lives. With no `-c`, the [baked-in default](./cli.md#default-mode) is
+served (no `./.dirsql.toml` auto-discovery); a single `-c` behaves exactly as
+before.
 
 ## Parse errors
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.3.109",
+  "version": "0.3.110",
   "description": "Ephemeral SQL index over a local directory",
   "license": "MIT",
   "repository": "https://github.com/thekevinscott/dirsql",
@@ -212,15 +212,15 @@
     ]
   },
   "optionalDependencies": {
-    "@dirsql/lib-linux-x64-gnu": "0.3.109",
-    "@dirsql/lib-linux-arm64-gnu": "0.3.109",
-    "@dirsql/lib-darwin-x64": "0.3.109",
-    "@dirsql/lib-darwin-arm64": "0.3.109",
-    "@dirsql/lib-win32-x64-msvc": "0.3.109",
-    "@dirsql/cli-linux-x64-gnu": "0.3.109",
-    "@dirsql/cli-linux-arm64-gnu": "0.3.109",
-    "@dirsql/cli-darwin-x64": "0.3.109",
-    "@dirsql/cli-darwin-arm64": "0.3.109",
-    "@dirsql/cli-win32-x64-msvc": "0.3.109"
+    "@dirsql/lib-linux-x64-gnu": "0.3.110",
+    "@dirsql/lib-linux-arm64-gnu": "0.3.110",
+    "@dirsql/lib-darwin-x64": "0.3.110",
+    "@dirsql/lib-darwin-arm64": "0.3.110",
+    "@dirsql/lib-win32-x64-msvc": "0.3.110",
+    "@dirsql/cli-linux-x64-gnu": "0.3.110",
+    "@dirsql/cli-linux-arm64-gnu": "0.3.110",
+    "@dirsql/cli-darwin-x64": "0.3.110",
+    "@dirsql/cli-darwin-arm64": "0.3.110",
+    "@dirsql/cli-win32-x64-msvc": "0.3.110"
   }
 }