dirsql 0.4.95__tar.gz → 0.4.96__tar.gz

{dirsql-0.4.95 → dirsql-0.4.96}/Cargo.lock

@@ -550,9 +550,30 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8"
 
+[[package]]
+name = "dirs"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3e8aa94d75141228480295a7d0e7feb620b1a5ad9f12bc40be62411e38cce4e"
+dependencies = [
+ "dirs-sys",
+]
+
+[[package]]
+name = "dirs-sys"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e01a3366d27ee9890022452ee61b2b63a67e6f13f58900b651ff5665f0bb1fab"
+dependencies = [
+ "libc",
+ "option-ext",
+ "redox_users",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "dirsql"
-version = "0.4.95"
+version = "0.4.96"
 dependencies = [
  "assert_cmd",
  "axum",
@@ -561,6 +582,7 @@ dependencies = [
  "clap",
  "console",
  "criterion",
+ "dirs",
  "eventsource-client",
  "futures",
  "futures-channel",
@@ -603,7 +625,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.4.95"
+version = "0.4.96"
 dependencies = [
  "dirsql",
  "pyo3",
@@ -1710,6 +1732,12 @@ version = "0.1.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d05e27ee213611ffe7d6348b942e8f942b37114c00cc03cec254295a4a17852e"
 
+[[package]]
+name = "option-ext"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
+
 [[package]]
 name = "parking_lot"
 version = "0.12.5"
@@ -2119,6 +2147,16 @@ dependencies = [
  "bitflags 2.11.1",
 ]
 
+[[package]]
+name = "redox_users"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60dc65c0ff1a7ae1294b0c67b9f14baf70b644404010370171787bfac1038fc0"
+dependencies = [
+ "libredox",
+ "thiserror",
+]
+
 [[package]]
 name = "reedline"
 version = "0.49.0"

{dirsql-0.4.95 → dirsql-0.4.96}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.4.95
+Version: 0.4.96
 Requires-Dist: bin-shim>=0.1
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index

{dirsql-0.4.95 → dirsql-0.4.96}/dirsql/_async.py

@@ -79,7 +79,7 @@ class DirSQL:
     apply.
 
     Pass ``persist=True`` to keep an on-disk SQLite cache (default location:
-    ``<root>/.dirsql/cache.db``). Override the location with ``persist_path``.
+    the platform cache directory, outside ``<root>``). Override the location with ``persist_path``.
 
     Pass ``extensions`` -- a list of ``{"path": ..., "entrypoint": ...}`` dicts
     (``entrypoint`` optional) -- to load SQLite extensions onto the connection

{dirsql-0.4.95/packages/python → dirsql-0.4.96}/docs/howto/persist.md

@@ -17,9 +17,11 @@ why it is a CLI flag, not a config key.
 dirsql --persist
 ```
 
-That's the whole change. On the next run the cache is written to
-`.dirsql/cache.db` under the root; runs after that start from it. To put
-the cache elsewhere (a CI cache dir, a tmpfs), pass a path:
+That's the whole change. On the next run the cache is written to your platform cache directory
+(`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux, `~/Library/Caches`
+on macOS, `%LOCALAPPDATA%` on Windows), outside the scanned tree; runs after
+that start from it. To put the cache elsewhere (a CI cache dir, a tmpfs), pass
+a path:
 
 ```bash
 dirsql --persist /var/cache/dirsql.db
@@ -30,20 +32,13 @@ put a bare `--persist` after the SQL there so it does not consume the query
 argument. Embedding `dirsql`? The SDK constructors expose the same switch —
 see [_Embedding `dirsql`?_](#embedding-dirsql) below.
 
-## 2. Keep the cache out of git
+## 2. Nothing to ignore in git
 
-The cache is derived data — reproducible from the tree and frequently
-large. Add it to `.gitignore`:
-
-```
-.dirsql/
-```
-
-The top-level `.dirsql/` directory is reserved for `dirsql`'s metadata and
-is never scanned as data, so the cache can't index itself
-([config reference](../reference/config.md#dirsql-keys)). While running,
-`dirsql` also creates transient `cache.db-wal` and `cache.db-shm` sidecar
-files next to the cache; the `.dirsql/` ignore already covers all three.
+The default cache lives outside the scanned tree, so there is nothing to add
+to `.gitignore` and the cache can't index itself. With `--persist <path>`, keep
+that path out of the scanned tree too, or ignore it. While running, `dirsql`
+also creates transient `cache.db-wal` and `cache.db-shm` sidecar files next to
+the cache.
 
 ## What survives, what rebuilds
 

{dirsql-0.4.95/packages/rust → dirsql-0.4.96}/docs/howto/search-indexes.md

@@ -224,7 +224,7 @@ Rows are embedded once, at ingest, and cached on disk by content and model
 ::: warning Editing `ddl` wedges a persisted `vec0` cache
 Under `--persist`, editing any part of a `ddl` batch whose cache holds a
 `vec0` table currently fails with `SQLite error: no such module: vec0`, and
-keeps failing until the cache is deleted (`rm -rf <root>/.dirsql`). Tracked in
+keeps failing until the cache is deleted (delete it, or pass a fresh `--persist <path>`). Tracked in
 [#1008](https://github.com/thekevinscott/dirsql/issues/1008); FTS5 is
 unaffected.
 :::

{dirsql-0.4.95 → dirsql-0.4.96}/docs/howto/skip-files.md

@@ -51,9 +51,6 @@ dirsql query "SELECT basename FROM notes ORDER BY basename" -c ./.dirsql.toml
   list, though its path-tables still apply the built-in
   [skip rules](../reference/path-tables.md#skip-rules) and respect
   `.gitignore`.
-- The top-level `.dirsql/` directory is always excluded, ignore list or
-  not — it is reserved for `dirsql`'s own metadata
-  ([config reference](../reference/config.md#dirsql-keys)).
 - Narrow table globs are the other half of the story: a file matching no
   table's glob contributes no rows either. Use `ignore` for things that
   should never be looked at; use precise globs to shape what each table

{dirsql-0.4.95 → dirsql-0.4.96}/docs/reference/cli.md

@@ -248,7 +248,7 @@ Config flags are subcommand-local: pass them after `server`
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
 | `--cors-origin <origin>` | off | Let browser pages on `<origin>` (an exact origin such as `http://localhost:3202`, or `*` for any) call `/query` and open `/events`. See [Cross-origin requests](#cross-origin-requests). |
-| `--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). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
+| `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches under the platform cache directory (`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux), outside the root; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
 | `--no-ignore` | off | Scan files a `.gitignore` would hide. [Path-tables](./path-tables.md#skip-rules) respect `.gitignore` files by default; this flag restores the full walk. The built-in `.git` skip and configured `ignore` patterns still apply. Also available on [`dirsql query`](#dirsql-query). |
 | `--extension <path>` | none | Load a SQLite extension by literal path, overriding the config's `[[dirsql.extension]]` entries. Repeatable. Format: `<path>` or `<path>::<entrypoint>`. Internal plumbing for the pip/npm launchers, which resolve package-name extensions and pass the resolved paths here — not intended for direct use. When any `--extension` is present, the config file's own extension entries are not loaded. |
 | `--version` | | Print the version and exit. |

{dirsql-0.4.95/packages/rust → dirsql-0.4.96}/docs/reference/config.md

@@ -34,12 +34,6 @@ A config that still declares the removed `hook-timeout` key fails to load with
 an error naming that replacement. [`[[dirsql.function]]`](#dirsql-function)
 worker calls have their own per-call `timeout` key (default 30 seconds).
 
-The top-level `.dirsql/` directory under the root is always excluded from
-scanning, whether or not it appears in `ignore` — it is reserved for
-`dirsql`'s own metadata (the persist cache lives there by default). Only the
-top-level `.dirsql/` is reserved; a nested `sub/.dirsql/` is an ordinary
-directory.
-
 ```toml
 [dirsql]
 ignore = ["node_modules/**", ".git/**"]

{dirsql-0.4.95/packages/rust → dirsql-0.4.96}/docs/reference/path-tables.md

@@ -228,8 +228,7 @@ The table itself is per-connection: it lives in `temp`, so it cannot leak into
 `sqlite_master` or survive a restart. Under `--persist` a *parsed* table's rows
 outlive the connection in the cache (above), but the table is still minted
 fresh each run and the scan still decides what exists. A `.dirsql/` directory
-at the top of the directory the scan starts in is reserved and excluded, as
-everywhere else.
+is an ordinary dot directory.
 
 ### When to promote to a declared table
 

{dirsql-0.4.95 → dirsql-0.4.96}/docs/reference/sdk.md

@@ -86,7 +86,7 @@ DirSQL::builder()
     .config(config_toml_path)       // optional; repeatable — call again to
                                     //   merge another config in call order
     .persist(cache_path)            // optional; Some(path), or None for the
-                                    //   default <root>/.dirsql/cache.db
+                                    //   platform cache dir
     .extensions(extensions)         // optional; append one with .extension(e)
     .poll_interval(duration)        // optional; watch-loop cadence, default 200ms
     .build()                        // -> Result<DirSQL>  (synchronous scan)
@@ -139,8 +139,8 @@ shortcut was removed in #603 — use
   accumulate; a duplicate table name across configs errors), mirroring the
   CLI's repeatable [`-c/--config`](./cli.md#flags).
 - `persist` — Keep the SQLite index on disk between runs (default off:
-  ephemeral, rebuilt every startup). The cache lives at
-  `<root>/.dirsql/cache.db` by default; on restart, only files whose stat
+  ephemeral, rebuilt every startup). The cache lives in the
+  platform cache directory by default (outside `<root>`); on restart, only files whose stat
   changed are re-parsed. (The CLI exposes the same switch as the
   [`--persist [PATH]`](./cli.md#dirsql-server) flag; it is not a config key.)
 - `persist_path` / `persistPath` — Override the cache location. Ignored when

{dirsql-0.4.95 → dirsql-0.4.96}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.4.95"
+version = "0.4.96"
 # abi3 note: the `abi3-py310` pyo3 feature (below) builds ONE stable-ABI
 # `cp310-abi3` wheel per platform that loads on every CPython >= 3.10
 # (matching `pyproject.toml`'s `requires-python = ">=3.10"`), instead of

dirsql-0.4.96/packages/python/changelog.d/2026-10-07-persist-cache-outside-root.md

@@ -0,0 +1,7 @@
+**Changed**
+
+- **The default `--persist` cache moves out of the scanned tree.** Bare `--persist` now writes `cache.db` under the platform cache directory (`$XDG_CACHE_HOME/dirsql/<root hash>/` on Linux, `~/Library/Caches` on macOS, `%LOCALAPPDATA%` on Windows) instead of `<root>/.dirsql/`. `--persist <path>` is unchanged.
+
+**Removed**
+
+- **The reserved `.dirsql/` directory.** The scan no longer skips a top-level `.dirsql/`; it is an ordinary dot directory, matched like bash.

{dirsql-0.4.95/packages/rust → dirsql-0.4.96/packages/python}/docs/howto/persist.md

@@ -17,9 +17,11 @@ why it is a CLI flag, not a config key.
 dirsql --persist
 ```
 
-That's the whole change. On the next run the cache is written to
-`.dirsql/cache.db` under the root; runs after that start from it. To put
-the cache elsewhere (a CI cache dir, a tmpfs), pass a path:
+That's the whole change. On the next run the cache is written to your platform cache directory
+(`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux, `~/Library/Caches`
+on macOS, `%LOCALAPPDATA%` on Windows), outside the scanned tree; runs after
+that start from it. To put the cache elsewhere (a CI cache dir, a tmpfs), pass
+a path:
 
 ```bash
 dirsql --persist /var/cache/dirsql.db
@@ -30,20 +32,13 @@ put a bare `--persist` after the SQL there so it does not consume the query
 argument. Embedding `dirsql`? The SDK constructors expose the same switch —
 see [_Embedding `dirsql`?_](#embedding-dirsql) below.
 
-## 2. Keep the cache out of git
+## 2. Nothing to ignore in git
 
-The cache is derived data — reproducible from the tree and frequently
-large. Add it to `.gitignore`:
-
-```
-.dirsql/
-```
-
-The top-level `.dirsql/` directory is reserved for `dirsql`'s metadata and
-is never scanned as data, so the cache can't index itself
-([config reference](../reference/config.md#dirsql-keys)). While running,
-`dirsql` also creates transient `cache.db-wal` and `cache.db-shm` sidecar
-files next to the cache; the `.dirsql/` ignore already covers all three.
+The default cache lives outside the scanned tree, so there is nothing to add
+to `.gitignore` and the cache can't index itself. With `--persist <path>`, keep
+that path out of the scanned tree too, or ignore it. While running, `dirsql`
+also creates transient `cache.db-wal` and `cache.db-shm` sidecar files next to
+the cache.
 
 ## What survives, what rebuilds
 

{dirsql-0.4.95 → dirsql-0.4.96/packages/python}/docs/howto/search-indexes.md

@@ -224,7 +224,7 @@ Rows are embedded once, at ingest, and cached on disk by content and model
 ::: warning Editing `ddl` wedges a persisted `vec0` cache
 Under `--persist`, editing any part of a `ddl` batch whose cache holds a
 `vec0` table currently fails with `SQLite error: no such module: vec0`, and
-keeps failing until the cache is deleted (`rm -rf <root>/.dirsql`). Tracked in
+keeps failing until the cache is deleted (delete it, or pass a fresh `--persist <path>`). Tracked in
 [#1008](https://github.com/thekevinscott/dirsql/issues/1008); FTS5 is
 unaffected.
 :::

{dirsql-0.4.95/packages/rust → dirsql-0.4.96/packages/python}/docs/howto/skip-files.md

@@ -51,9 +51,6 @@ dirsql query "SELECT basename FROM notes ORDER BY basename" -c ./.dirsql.toml
   list, though its path-tables still apply the built-in
   [skip rules](../reference/path-tables.md#skip-rules) and respect
   `.gitignore`.
-- The top-level `.dirsql/` directory is always excluded, ignore list or
-  not — it is reserved for `dirsql`'s own metadata
-  ([config reference](../reference/config.md#dirsql-keys)).
 - Narrow table globs are the other half of the story: a file matching no
   table's glob contributes no rows either. Use `ignore` for things that
   should never be looked at; use precise globs to shape what each table

{dirsql-0.4.95/packages/rust → dirsql-0.4.96/packages/python}/docs/reference/cli.md

@@ -248,7 +248,7 @@ Config flags are subcommand-local: pass them after `server`
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
 | `--cors-origin <origin>` | off | Let browser pages on `<origin>` (an exact origin such as `http://localhost:3202`, or `*` for any) call `/query` and open `/events`. See [Cross-origin requests](#cross-origin-requests). |
-| `--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). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
+| `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches under the platform cache directory (`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux), outside the root; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
 | `--no-ignore` | off | Scan files a `.gitignore` would hide. [Path-tables](./path-tables.md#skip-rules) respect `.gitignore` files by default; this flag restores the full walk. The built-in `.git` skip and configured `ignore` patterns still apply. Also available on [`dirsql query`](#dirsql-query). |
 | `--extension <path>` | none | Load a SQLite extension by literal path, overriding the config's `[[dirsql.extension]]` entries. Repeatable. Format: `<path>` or `<path>::<entrypoint>`. Internal plumbing for the pip/npm launchers, which resolve package-name extensions and pass the resolved paths here — not intended for direct use. When any `--extension` is present, the config file's own extension entries are not loaded. |
 | `--version` | | Print the version and exit. |

{dirsql-0.4.95 → dirsql-0.4.96/packages/python}/docs/reference/config.md

@@ -34,12 +34,6 @@ A config that still declares the removed `hook-timeout` key fails to load with
 an error naming that replacement. [`[[dirsql.function]]`](#dirsql-function)
 worker calls have their own per-call `timeout` key (default 30 seconds).
 
-The top-level `.dirsql/` directory under the root is always excluded from
-scanning, whether or not it appears in `ignore` — it is reserved for
-`dirsql`'s own metadata (the persist cache lives there by default). Only the
-top-level `.dirsql/` is reserved; a nested `sub/.dirsql/` is an ordinary
-directory.
-
 ```toml
 [dirsql]
 ignore = ["node_modules/**", ".git/**"]

{dirsql-0.4.95 → dirsql-0.4.96/packages/python}/docs/reference/path-tables.md

@@ -228,8 +228,7 @@ The table itself is per-connection: it lives in `temp`, so it cannot leak into
 `sqlite_master` or survive a restart. Under `--persist` a *parsed* table's rows
 outlive the connection in the cache (above), but the table is still minted
 fresh each run and the scan still decides what exists. A `.dirsql/` directory
-at the top of the directory the scan starts in is reserved and excluded, as
-everywhere else.
+is an ordinary dot directory.
 
 ### When to promote to a declared table
 

{dirsql-0.4.95/packages/rust → dirsql-0.4.96/packages/python}/docs/reference/sdk.md

@@ -86,7 +86,7 @@ DirSQL::builder()
     .config(config_toml_path)       // optional; repeatable — call again to
                                     //   merge another config in call order
     .persist(cache_path)            // optional; Some(path), or None for the
-                                    //   default <root>/.dirsql/cache.db
+                                    //   platform cache dir
     .extensions(extensions)         // optional; append one with .extension(e)
     .poll_interval(duration)        // optional; watch-loop cadence, default 200ms
     .build()                        // -> Result<DirSQL>  (synchronous scan)
@@ -139,8 +139,8 @@ shortcut was removed in #603 — use
   accumulate; a duplicate table name across configs errors), mirroring the
   CLI's repeatable [`-c/--config`](./cli.md#flags).
 - `persist` — Keep the SQLite index on disk between runs (default off:
-  ephemeral, rebuilt every startup). The cache lives at
-  `<root>/.dirsql/cache.db` by default; on restart, only files whose stat
+  ephemeral, rebuilt every startup). The cache lives in the
+  platform cache directory by default (outside `<root>`); on restart, only files whose stat
   changed are re-parsed. (The CLI exposes the same switch as the
   [`--persist [PATH]`](./cli.md#dirsql-server) flag; it is not a config key.)
 - `persist_path` / `persistPath` — Override the cache location. Ignored when

dirsql-0.4.96/packages/python/e2e-attestations/bot-1431-persist-cache-dir.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/query_contract_test.py tests/e2e/fanout_test.py tests/e2e/use_case_transcripts_test.py tests/e2e/glob_speed_dotfiles_test.py tests/e2e/glob_speed_recursive_test.py tests/e2e/glob_speed_one_level_test.py tests/e2e/stat_speed_test.py -x -q",
+  "ran_at": 1791391233,
+  "exit_code": 0,
+  "commit": "83e889b9041e8e071128c2334d98bf645ec52581",
+  "branch": "bot/1431-persist-cache-dir"
+}

dirsql-0.4.96/packages/python/migrations.d/2026-10-07-persist-cache-outside-root.md

@@ -0,0 +1,35 @@
+### Default persist cache moves to the platform cache directory
+
+#### Summary
+
+Bare `--persist` (and `.persist(None)` / `persist=True` / `persist: true` in the
+SDKs) no longer writes `<root>/.dirsql/cache.db`. It writes
+`cache.db` under the platform cache directory, keyed by a hash of the root. The
+scan no longer reserves `.dirsql/`.
+
+#### Required changes
+
+| Before | After |
+| --- | --- |
+| `.gitignore` entry `.dirsql/` for the cache | Not needed |
+| `rm -rf <root>/.dirsql` to reset the cache | Delete the file under the platform cache directory, or pass `--persist <path>` |
+
+#### Deprecations removed
+
+_None._
+
+#### Behavior changes without code changes
+
+- The first `--persist` run after upgrading rebuilds the cache once.
+- An old `<root>/.dirsql/cache.db` is left behind and, being an ordinary dot directory, is now scannable by a glob that spells `.dirsql`. Delete it.
+- A top-level `.dirsql/` directory is no longer excluded from the scan.
+
+#### Verification
+
+```bash
+cd "$(mktemp -d)"
+echo 'a' > a.txt
+dirsql query "SELECT path FROM './*'" --persist
+ls -A
+# expected: only a.txt; no .dirsql/ in the root
+```

{dirsql-0.4.95 → dirsql-0.4.96}/packages/rust/Cargo.toml

@@ -6,7 +6,7 @@ description = "Ephemeral SQL index over a local directory"
 # version stays for the binding crates (publish = false). The literal
 # intentionally lags the published version: putitoutthere rewrites it to
 # the planned release version at build time and never commits it back.
-version = "0.4.95"
+version = "0.4.96"
 edition.workspace = true
 # Literal `license` (not `license.workspace = true`) because
 # putitoutthere's preflight check reads `[package].license` directly
@@ -63,6 +63,7 @@ base64 = "0.22"
 blake3 = "1"
 clap = { version = "4", features = ["derive"], optional = true }
 console = "0.16.6"
+dirs = "6"
 futures = { version = "0.3", optional = true }
 futures-channel.workspace = true
 globset = "0.4"

{dirsql-0.4.95 → dirsql-0.4.96/packages/rust}/docs/howto/persist.md

@@ -17,9 +17,11 @@ why it is a CLI flag, not a config key.
 dirsql --persist
 ```
 
-That's the whole change. On the next run the cache is written to
-`.dirsql/cache.db` under the root; runs after that start from it. To put
-the cache elsewhere (a CI cache dir, a tmpfs), pass a path:
+That's the whole change. On the next run the cache is written to your platform cache directory
+(`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux, `~/Library/Caches`
+on macOS, `%LOCALAPPDATA%` on Windows), outside the scanned tree; runs after
+that start from it. To put the cache elsewhere (a CI cache dir, a tmpfs), pass
+a path:
 
 ```bash
 dirsql --persist /var/cache/dirsql.db
@@ -30,20 +32,13 @@ put a bare `--persist` after the SQL there so it does not consume the query
 argument. Embedding `dirsql`? The SDK constructors expose the same switch —
 see [_Embedding `dirsql`?_](#embedding-dirsql) below.
 
-## 2. Keep the cache out of git
+## 2. Nothing to ignore in git
 
-The cache is derived data — reproducible from the tree and frequently
-large. Add it to `.gitignore`:
-
-```
-.dirsql/
-```
-
-The top-level `.dirsql/` directory is reserved for `dirsql`'s metadata and
-is never scanned as data, so the cache can't index itself
-([config reference](../reference/config.md#dirsql-keys)). While running,
-`dirsql` also creates transient `cache.db-wal` and `cache.db-shm` sidecar
-files next to the cache; the `.dirsql/` ignore already covers all three.
+The default cache lives outside the scanned tree, so there is nothing to add
+to `.gitignore` and the cache can't index itself. With `--persist <path>`, keep
+that path out of the scanned tree too, or ignore it. While running, `dirsql`
+also creates transient `cache.db-wal` and `cache.db-shm` sidecar files next to
+the cache.
 
 ## What survives, what rebuilds
 

{dirsql-0.4.95/packages/python → dirsql-0.4.96/packages/rust}/docs/howto/search-indexes.md

@@ -224,7 +224,7 @@ Rows are embedded once, at ingest, and cached on disk by content and model
 ::: warning Editing `ddl` wedges a persisted `vec0` cache
 Under `--persist`, editing any part of a `ddl` batch whose cache holds a
 `vec0` table currently fails with `SQLite error: no such module: vec0`, and
-keeps failing until the cache is deleted (`rm -rf <root>/.dirsql`). Tracked in
+keeps failing until the cache is deleted (delete it, or pass a fresh `--persist <path>`). Tracked in
 [#1008](https://github.com/thekevinscott/dirsql/issues/1008); FTS5 is
 unaffected.
 :::

{dirsql-0.4.95/packages/python → dirsql-0.4.96/packages/rust}/docs/howto/skip-files.md

@@ -51,9 +51,6 @@ dirsql query "SELECT basename FROM notes ORDER BY basename" -c ./.dirsql.toml
   list, though its path-tables still apply the built-in
   [skip rules](../reference/path-tables.md#skip-rules) and respect
   `.gitignore`.
-- The top-level `.dirsql/` directory is always excluded, ignore list or
-  not — it is reserved for `dirsql`'s own metadata
-  ([config reference](../reference/config.md#dirsql-keys)).
 - Narrow table globs are the other half of the story: a file matching no
   table's glob contributes no rows either. Use `ignore` for things that
   should never be looked at; use precise globs to shape what each table

{dirsql-0.4.95/packages/python → dirsql-0.4.96/packages/rust}/docs/reference/cli.md

@@ -248,7 +248,7 @@ Config flags are subcommand-local: pass them after `server`
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
 | `--cors-origin <origin>` | off | Let browser pages on `<origin>` (an exact origin such as `http://localhost:3202`, or `*` for any) call `/query` and open `/events`. See [Cross-origin requests](#cross-origin-requests). |
-| `--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). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
+| `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches under the platform cache directory (`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux), outside the root; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
 | `--no-ignore` | off | Scan files a `.gitignore` would hide. [Path-tables](./path-tables.md#skip-rules) respect `.gitignore` files by default; this flag restores the full walk. The built-in `.git` skip and configured `ignore` patterns still apply. Also available on [`dirsql query`](#dirsql-query). |
 | `--extension <path>` | none | Load a SQLite extension by literal path, overriding the config's `[[dirsql.extension]]` entries. Repeatable. Format: `<path>` or `<path>::<entrypoint>`. Internal plumbing for the pip/npm launchers, which resolve package-name extensions and pass the resolved paths here — not intended for direct use. When any `--extension` is present, the config file's own extension entries are not loaded. |
 | `--version` | | Print the version and exit. |

{dirsql-0.4.95/packages/python → dirsql-0.4.96/packages/rust}/docs/reference/config.md

@@ -34,12 +34,6 @@ A config that still declares the removed `hook-timeout` key fails to load with
 an error naming that replacement. [`[[dirsql.function]]`](#dirsql-function)
 worker calls have their own per-call `timeout` key (default 30 seconds).
 
-The top-level `.dirsql/` directory under the root is always excluded from
-scanning, whether or not it appears in `ignore` — it is reserved for
-`dirsql`'s own metadata (the persist cache lives there by default). Only the
-top-level `.dirsql/` is reserved; a nested `sub/.dirsql/` is an ordinary
-directory.
-
 ```toml
 [dirsql]
 ignore = ["node_modules/**", ".git/**"]

{dirsql-0.4.95/packages/python → dirsql-0.4.96/packages/rust}/docs/reference/path-tables.md

@@ -228,8 +228,7 @@ The table itself is per-connection: it lives in `temp`, so it cannot leak into
 `sqlite_master` or survive a restart. Under `--persist` a *parsed* table's rows
 outlive the connection in the cache (above), but the table is still minted
 fresh each run and the scan still decides what exists. A `.dirsql/` directory
-at the top of the directory the scan starts in is reserved and excluded, as
-everywhere else.
+is an ordinary dot directory.
 
 ### When to promote to a declared table
 

{dirsql-0.4.95/packages/python → dirsql-0.4.96/packages/rust}/docs/reference/sdk.md

@@ -86,7 +86,7 @@ DirSQL::builder()
     .config(config_toml_path)       // optional; repeatable — call again to
                                     //   merge another config in call order
     .persist(cache_path)            // optional; Some(path), or None for the
-                                    //   default <root>/.dirsql/cache.db
+                                    //   platform cache dir
     .extensions(extensions)         // optional; append one with .extension(e)
     .poll_interval(duration)        // optional; watch-loop cadence, default 200ms
     .build()                        // -> Result<DirSQL>  (synchronous scan)
@@ -139,8 +139,8 @@ shortcut was removed in #603 — use
   accumulate; a duplicate table name across configs errors), mirroring the
   CLI's repeatable [`-c/--config`](./cli.md#flags).
 - `persist` — Keep the SQLite index on disk between runs (default off:
-  ephemeral, rebuilt every startup). The cache lives at
-  `<root>/.dirsql/cache.db` by default; on restart, only files whose stat
+  ephemeral, rebuilt every startup). The cache lives in the
+  platform cache directory by default (outside `<root>`); on restart, only files whose stat
   changed are re-parsed. (The CLI exposes the same switch as the
   [`--persist [PATH]`](./cli.md#dirsql-server) flag; it is not a config key.)
 - `persist_path` / `persistPath` — Override the cache location. Ignored when

{dirsql-0.4.95 → dirsql-0.4.96}/packages/rust/src/cli/run.rs

@@ -121,7 +121,7 @@ struct ConfigArgs {
 
     /// Keep the SQLite index on disk between runs so a restart only re-parses
     /// files that actually changed. Bare `--persist` caches at the default
-    /// location (`<root>/.dirsql/cache.db`); `--persist <path>` caches there.
+    /// location (the platform cache directory); `--persist <path>` caches there.
     /// Off by default (ephemeral index).
     #[arg(long, num_args = 0..=1)]
     persist: Option<Option<PathBuf>>,

{dirsql-0.4.95 → dirsql-0.4.96}/packages/rust/src/lib.rs

@@ -1669,7 +1669,7 @@ impl DirSQLBuilder {
     }
 
     /// Enable persistent on-disk storage. `None` writes the SQLite database to
-    /// the default `<root>/.dirsql/cache.db`; `Some(path)` writes it to `path`.
+    /// the default location in the platform cache directory; `Some(path)` writes it to `path`.
     /// Either way, subsequent startups only re-parse files that have actually
     /// changed. See `docs/howto/persist.md` for the reconcile contract.
     pub fn persist(mut self, path: Option<impl AsRef<Path>>) -> Self {