dirsql 0.4.67__tar.gz → 0.4.68__tar.gz

{dirsql-0.4.67 → dirsql-0.4.68}/Cargo.lock

@@ -552,7 +552,7 @@ checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8"
 
 [[package]]
 name = "dirsql"
-version = "0.4.67"
+version = "0.4.68"
 dependencies = [
  "assert_cmd",
  "axum",
@@ -600,7 +600,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.4.67"
+version = "0.4.68"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.4.67 → dirsql-0.4.68}/PKG-INFO

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

{dirsql-0.4.67 → dirsql-0.4.68}/dirsql/cli/discover_plugins/with_discovered_plugins.py

@@ -22,8 +22,8 @@ from .user_passed_config import user_passed_config
 def with_discovered_plugins(argv: list[str]) -> list[str]:
     """Return ``argv`` with each installed plugin's fragment appended as ``-c``
     (plus ``--include-default`` when the user passed no ``-c``). ``--no-plugin``
-    / ``DIRSQL_NO_PLUGIN`` skip discovery, consuming the flag. ``init`` takes no
-    config, so it is left untouched. Raises if a declared plugin is missing its
+    / ``DIRSQL_NO_PLUGIN`` skip discovery, consuming the flag. ``init`` and ``context`` take no
+    config, so they are left untouched. Raises if a declared plugin is missing its
     module or fragment (the launcher surfaces a clean error).
 
     Appending is safe because config flags are subcommand-local (#609): the
@@ -34,7 +34,7 @@ def with_discovered_plugins(argv: list[str]) -> list[str]:
     """
     if discovery_disabled(argv):
         return [a for a in argv if a != NO_PLUGIN_FLAG]
-    if argv and argv[0] == "init":
+    if argv and argv[0] in ("init", "context"):
         return argv
     fragments = discovered_fragments()
     if not fragments:

{dirsql-0.4.67 → dirsql-0.4.68}/dirsql/cli/resolve_config_extensions.py

@@ -27,7 +27,7 @@ def with_resolved_extensions(argv: list[str]) -> list[str]:
     """Return ``argv`` plus ``--extension`` flags when a TOML config names an
     extension by package name; otherwise return ``argv`` unchanged. Raises if a
     package name cannot be resolved (the launcher surfaces a clean error)."""
-    if argv and argv[0] == "init":
+    if argv and argv[0] in ("init", "context"):
         return argv
     config_paths = [
         p for p in config_paths_from_argv(argv) if not p.endswith(_NATIVE_SUFFIXES)

{dirsql-0.4.67 → dirsql-0.4.68}/docs/.vitepress/config.ts

@@ -5,6 +5,9 @@ export default defineConfig({
   description: 'Ephemeral SQL index over a local directory. Watches a filesystem, ingests structured files into an ephemeral SQLite database, and exposes a SQL query interface.',
   base: '/',
 
+  // The guide `dirsql context` prints, compiled into the binary; not site pages.
+  srcExclude: ['context/**'],
+
   // Vite blocks dev-server requests whose Host header isn't allowlisted, so
   // `pnpm dev --host` reached by a network hostname (e.g. a Tailscale
   // `*.ts.net` name) 400s. Allow extra hosts from the environment so a

dirsql-0.4.68/docs/context/.gitattributes

@@ -0,0 +1,2 @@
+# include_str! embeds these verbatim; a CRLF checkout would print a mixed-ending guide.
+*.md text eol=lf

dirsql-0.4.68/docs/context/recipes.md

@@ -0,0 +1,103 @@
+## Recipes
+
+Each query runs as written from the directory in question and prints a JSON array of row objects.
+
+### Largest files
+
+```sh
+uvx dirsql "SELECT path, size FROM './**' ORDER BY size DESC LIMIT 10" --format json
+```
+
+### Count and total size by extension
+
+```sh
+uvx dirsql "SELECT ext, COUNT(*) AS files, SUM(size) AS bytes FROM './**' GROUP BY ext ORDER BY files DESC" --format json
+```
+
+`ext` is `NULL` for files with no extension and keeps its case; group by `LOWER(ext)` to fold `JPG` into `jpg`.
+
+### Files per directory
+
+```sh
+uvx dirsql "SELECT dir, COUNT(*) AS files FROM './**' GROUP BY dir ORDER BY files DESC" --format json
+```
+
+`dir` is the empty string for files at the top level.
+
+### Stale files
+
+Not modified in the last 90 days:
+
+```sh
+uvx dirsql "SELECT path, datetime(mtime, 'unixepoch') AS modified FROM './**' WHERE mtime < strftime('%s', 'now') - 90 * 86400 ORDER BY mtime" --format json
+```
+
+Most recently modified markdown:
+
+```sh
+uvx dirsql "SELECT path, datetime(mtime, 'unixepoch') AS modified FROM './**/*.md' ORDER BY mtime DESC LIMIT 10" --format json
+```
+
+### The same JSON field from many files
+
+```sh
+uvx dirsql "SELECT path, content ->> 'name' AS name, content ->> 'version' AS version FROM './**/metadata.json' WHERE json_valid(content) ORDER BY name" --format json
+```
+
+`json_valid(content)` keeps one empty or malformed file from failing the whole query. Nested keys are JSON paths, still quoted: `content ->> '$.runtime.engine'`. Booleans arrive as `1` and `0`:
+
+```sh
+uvx dirsql "SELECT path FROM './**/metadata.json' WHERE json_valid(content) AND content ->> 'disabled' = 0" --format json
+```
+
+Count across an array field with `json_each`, guarded the same way:
+
+```sh
+uvx dirsql "SELECT t.value AS tag, COUNT(*) AS n FROM './**/metadata.json' AS m, json_each(m.content, '$.tags') AS t WHERE json_valid(m.content) GROUP BY tag ORDER BY n DESC, tag" --format json
+```
+
+### Frontmatter
+
+Files whose frontmatter contains a given line (`%` matches across newlines):
+
+```sh
+uvx dirsql "SELECT path FROM './**/*.md' WHERE content LIKE '---%status: draft%'" --format json
+```
+
+One frontmatter field from every file:
+
+```sh
+uvx dirsql "WITH fm AS (SELECT path, substr(content, instr(content, 'title:') + 6) AS rest FROM './**/*.md' WHERE content LIKE '---%title:%') SELECT path, trim(substr(rest, 1, instr(rest, char(10)) - 1)) AS title FROM fm ORDER BY path" --format json
+```
+
+### Occurrences of a string per file
+
+grep stops at matching lines; SQL can count them:
+
+```sh
+uvx dirsql "SELECT path, (length(content) - length(replace(content, 'TODO', ''))) / length('TODO') AS todos FROM './**/*.md' WHERE todos > 0 ORDER BY todos DESC" --format json
+```
+
+### Join two directories
+
+Source modules with no matching doc page:
+
+```sh
+uvx dirsql "SELECT s.path FROM './src/*.py' AS s LEFT JOIN './docs/**/*.md' AS d ON replace(d.basename, '.md', '') = replace(s.basename, '.py', '') WHERE d.path IS NULL ORDER BY s.path" --format json
+```
+
+### Top-k by meaning
+
+Needs the embeddings plugin. The first run downloads a model of roughly a hundred megabytes, with progress on stderr:
+
+```sh
+uvx --with dirsql-plugin-embeddings dirsql "
+  SELECT path,
+         vec_distance_cosine(emb, embed('how do I cook pasta?')) AS distance
+  FROM (SELECT path, embed(content) AS emb FROM './notes/*.md')
+  WHERE emb IS NOT NULL
+  ORDER BY distance
+  LIMIT 3" --format json
+```
+
+`WHERE emb IS NOT NULL` matters: an unreadable file embeds to `NULL`, and SQLite sorts `NULL` first. For ranked paths only, `uvx dirsql-plugin-embeddings './notes/*.md' "how do I cook pasta?" -k 3` prints `path<TAB>distance` lines.

dirsql-0.4.68/docs/context/troubleshooting.md

@@ -0,0 +1,64 @@
+## Troubleshooting
+
+Diagnostics go to stderr and the exit code is `1`.
+
+### `no such table: **/*.md; did you mean './**/*.md'?`
+
+A bare glob. Paths relative to the directory you run in start with `./`:
+
+```sh
+uvx dirsql "SELECT path FROM './**/*.md'" --format json
+```
+
+### `near ".": syntax error` and `hint: paths used as table names must be quoted`
+
+`FROM ./` reaches SQLite's parser as punctuation. Quote the path:
+
+```sh
+uvx dirsql "SELECT COUNT(*) AS files FROM './'" --format json
+```
+
+### `no such column: disabled`
+
+`content ->> disabled` names a column. The key is a string literal:
+
+```sh
+uvx dirsql "SELECT path, content ->> 'disabled' AS disabled FROM './**/metadata.json' WHERE json_valid(content)" --format json
+```
+
+### `SQLite error: malformed JSON`
+
+One matched file is not valid JSON (an empty file counts), and that fails the whole query. Guard with `json_valid`:
+
+```sh
+uvx dirsql "SELECT path, content ->> 'name' AS name FROM './**/*.json' WHERE json_valid(content)" --format json
+```
+
+### `no such table: files; did you mean FROM './**'?`
+
+There is no implicit table. Query the tree directly:
+
+```sh
+uvx dirsql "SELECT path FROM './**'" --format json
+```
+
+### Empty `[]` for files you can see
+
+- **You named a directory**, which lists one level only. `'./**'` and `'./docs/**'` are the recursive forms.
+- **The files are gitignored.** `--no-ignore` scans them:
+
+  ```sh
+  uvx dirsql "SELECT path FROM './**'" --format json --no-ignore
+  ```
+
+  Naming the directory outright also works: `'./build'` scans `build/` even when it is ignored.
+- **The files are under `node_modules`**, which is skipped unless the path names it: `'./node_modules/**'`.
+- **The files start with a dot, or sit under a directory that does.** Spell the dot: `'./.git/**'`, `'./**/.env'`.
+
+### `table ./ may not be modified`
+
+dirsql is read-only. Mutations belong in a script that consumes the query's JSON.
+
+### A table appeared, not JSON
+
+`--format json` was not passed and stdout was a terminal. Pass it.

dirsql-0.4.68/docs/context/usage.md

@@ -0,0 +1,54 @@
+## Usage
+
+dirsql answers a question about a directory tree with SQL. Nothing to install; run it from the directory in question:
+
+```sh
+uvx dirsql "SELECT basename, size FROM './**' ORDER BY size DESC LIMIT 5" --format json
+```
+
+Always pass `--format json`. Without it the output depends on stdout: a terminal gets a table, a pipe gets JSON, and you cannot know which you have. With it, stdout is one JSON array of row objects. Errors go to stderr with exit code `1`.
+
+### Path-tables
+
+A quoted path stands in for a table name. Paths are relative to the directory you run in.
+
+| You write | dirsql scans |
+| --- | --- |
+| `'./'` | files directly here, no deeper |
+| `'./docs'` | files directly inside `docs/`, no deeper |
+| `'./*.md'` | markdown directly here |
+| `'./**'` | every file, any depth |
+| `'./docs/**'` | every file under `docs/`, any depth |
+| `'./**/*.md'` | markdown at any depth |
+| `'./notes/today.md'` | that one file |
+
+`*` matches within one directory level and `**` matches any depth. A directory name lists one level, like `ls docs`, so write `'./**'` to scan the whole tree. Rows are files only, never directories. `'/var/log/*.log'`, `'../notes'` and `'~/notes/*.md'` also resolve; those report absolute `path` values.
+
+Two mistakes fail every time:
+
+1. **The path must be quoted.** `FROM ./` is a syntax error; write `FROM './'`.
+2. **`content ->> 'key'` takes a string literal.** `content ->> key` fails with `no such column: key`.
+
+### Columns
+
+Every row has `path`, `basename`, `dir`, `ext` (no dot, `NULL` when absent), `size` (bytes), `mtime` and `ctime` (Unix seconds). A hidden `content` column holds the file's text: it is left out of `SELECT *`, read only when you name it, and `NULL` for unreadable or non-UTF-8 files.
+
+### What a scan skips
+
+- **`.gitignore` is respected.** Pass `--no-ignore` to scan gitignored files too, or name the ignored directory outright: `'./build'` scans `build/`.
+- **`node_modules` is skipped** unless the path names it: `'./node_modules/**'`.
+- **`'./**'` does not enter `.git`.** Naming it scans it: `'./.git/**'`.
+- **To match dotfiles, spell the dot:** `'./.github/**'`, `'./**/.env'`.
+
+### Escalation
+
+1. A path-table, as above. Fits a question you ask once.
+2. The same tree queried repeatedly, or a parser you want to keep: declare a table in a `.dirsql.toml` and pass it with `-c .dirsql.toml`. See [config](https://dirsql.dev/reference/config).
+3. One row per record inside each file, inline: `--on-file <command>` attaches a parser to every path-table in the query, and its output replaces the stat columns. See [hooks](https://dirsql.dev/reference/hooks).
+4. Search by meaning: `uvx --with dirsql-plugin-embeddings dirsql "<sql>" --format json` adds `embed()` and `vec_distance_cosine()`. See [search by meaning](https://dirsql.dev/howto/search-by-meaning).
+
+### Read-only
+
+dirsql never writes to, moves or changes the files it scans, and it rejects mutating SQL. Do not pass `--persist`: it writes a cache database into the directory.
+
+Full docs: [dirsql.dev](https://dirsql.dev/) ([path-tables](https://dirsql.dev/reference/path-tables), [columns](https://dirsql.dev/reference/columns), [CLI](https://dirsql.dev/reference/cli), [query JSON](https://dirsql.dev/howto/query-json)).

{dirsql-0.4.67 → dirsql-0.4.68}/docs/reference/cli.md

@@ -11,6 +11,7 @@ The `dirsql` binary has these modes:
 | `dirsql query "<sql>"` | Explicit synonym for the default one-shot query. |
 | `dirsql server` | Start a long-lived HTTP server exposing a SQL view of a directory. See [HTTP API](./http-api.md). |
 | `dirsql init` | Generate a `.dirsql.toml`. |
+| `dirsql context` | Print the usage guide for this version, for an agent to read. |
 | `dirsql` (bare) | Open a [REPL](#the-repl) over the current directory, reading statements until EOF. |
 
 Bare `dirsql` does **not** start the server — that is `dirsql server`.
@@ -441,6 +442,17 @@ All failures exit `1` with a message on stderr:
 
 On success, `init` exits `0`.
 
+## `dirsql context`
+
+```sh
+uvx dirsql context
+```
+
+Prints a markdown guide for an agent that is about to query files: the
+first line is `dirsql <version>`, then sections on usage, recipes and
+troubleshooting. The guide is compiled into the binary, so it describes the
+version that prints it. It takes no flags and exits `0`.
+
 ## Plugins
 
 A **plugin** is an ordinary Python package that ships a `dirsql.toml` config

{dirsql-0.4.67/packages/python → dirsql-0.4.68}/docs/reference/path-tables.md

@@ -37,14 +37,16 @@ indexing, not your shell's working directory.
 
 **A directory name is one level, like `ls`.** Naming a directory lists the
 files directly inside it and no deeper; `*` matches one level and `**` any
-depth, as in the shell.
+depth, as in the shell. A trailing `/` is `*` appended, so `'./*/'` is
+`'./*/*'`: the files directly inside each top-level directory, like `ls */`.
 
 | You write | dirsql scans |
 | --- | --- |
 | `'./'` | files directly inside the index root, and no deeper |
 | `'./docs'`, `'./docs/'` | files directly inside `docs/` |
 | `'./*'` | the same as `'./'` |
-| `'./**'` | every file under the index root, recursively |
+| `'./**'`, `'./**/'` | every file under the index root, recursively |
+| `'./*/'` | the same as `'./*/*'`: files directly inside each top-level directory |
 | `'./docs/*.md'` | markdown files directly inside `docs/` |
 | `'./docs/**/*.md'` | markdown files at any depth under `docs/` |
 | `'./notes/today.md'` | exactly that one file — one file is one row |
@@ -108,7 +110,8 @@ Three other prefixes resolve, with their usual shell meanings:
 | `'../notes'` | relative to the index root's parent |
 | `'~/notes/*.md'` | relative to your home directory |
 
-A directory named this way is one level too; `'../notes/**'` descends.
+A directory named this way is one level too; `'../notes/**'` descends. The
+trailing-`/` rule holds here as well: `'~/*/'` is `'~/*/*'`.
 `..` is folded out textually, not followed through symlinks, so the directory
 scanned is a function of the string you wrote.
 

{dirsql-0.4.67 → dirsql-0.4.68}/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.67"
+version = "0.4.68"
 # 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.68/packages/python/changelog.d/2026-10-05-cli-context.md

@@ -0,0 +1,3 @@
+**Added**
+
+- **`dirsql context` prints a usage guide for agents.** The first line is `dirsql <version>`, then markdown sections on usage, recipes, and fixes for common errors, matched to the installed version. The launcher passes `context` through without adding plugin or extension flags, as it does for `init`. (#1264)

dirsql-0.4.68/packages/python/changelog.d/2026-10-05-path-table-trailing-slash.md

@@ -0,0 +1,5 @@
+**Fixed** A trailing `/` on a path-table is `*` appended. `'./*/'` now lists
+the files directly inside each top-level directory, the same rows as
+`'./*/*'` (like `ls */`); it used to drop the slash and list the top-level
+files. `'./'`, `'./docs/'` and `'./**/'` return the same rows as before. The
+rule applies to absolute, `../` and `~/` path-tables too.

{dirsql-0.4.67 → dirsql-0.4.68}/packages/python/docs/.vitepress/config.ts

@@ -5,6 +5,9 @@ export default defineConfig({
   description: 'Ephemeral SQL index over a local directory. Watches a filesystem, ingests structured files into an ephemeral SQLite database, and exposes a SQL query interface.',
   base: '/',
 
+  // The guide `dirsql context` prints, compiled into the binary; not site pages.
+  srcExclude: ['context/**'],
+
   // Vite blocks dev-server requests whose Host header isn't allowlisted, so
   // `pnpm dev --host` reached by a network hostname (e.g. a Tailscale
   // `*.ts.net` name) 400s. Allow extra hosts from the environment so a

dirsql-0.4.68/packages/python/docs/context/.gitattributes

@@ -0,0 +1,2 @@
+# include_str! embeds these verbatim; a CRLF checkout would print a mixed-ending guide.
+*.md text eol=lf

dirsql-0.4.68/packages/python/docs/context/recipes.md

@@ -0,0 +1,103 @@
+## Recipes
+
+Each query runs as written from the directory in question and prints a JSON array of row objects.
+
+### Largest files
+
+```sh
+uvx dirsql "SELECT path, size FROM './**' ORDER BY size DESC LIMIT 10" --format json
+```
+
+### Count and total size by extension
+
+```sh
+uvx dirsql "SELECT ext, COUNT(*) AS files, SUM(size) AS bytes FROM './**' GROUP BY ext ORDER BY files DESC" --format json
+```
+
+`ext` is `NULL` for files with no extension and keeps its case; group by `LOWER(ext)` to fold `JPG` into `jpg`.
+
+### Files per directory
+
+```sh
+uvx dirsql "SELECT dir, COUNT(*) AS files FROM './**' GROUP BY dir ORDER BY files DESC" --format json
+```
+
+`dir` is the empty string for files at the top level.
+
+### Stale files
+
+Not modified in the last 90 days:
+
+```sh
+uvx dirsql "SELECT path, datetime(mtime, 'unixepoch') AS modified FROM './**' WHERE mtime < strftime('%s', 'now') - 90 * 86400 ORDER BY mtime" --format json
+```
+
+Most recently modified markdown:
+
+```sh
+uvx dirsql "SELECT path, datetime(mtime, 'unixepoch') AS modified FROM './**/*.md' ORDER BY mtime DESC LIMIT 10" --format json
+```
+
+### The same JSON field from many files
+
+```sh
+uvx dirsql "SELECT path, content ->> 'name' AS name, content ->> 'version' AS version FROM './**/metadata.json' WHERE json_valid(content) ORDER BY name" --format json
+```
+
+`json_valid(content)` keeps one empty or malformed file from failing the whole query. Nested keys are JSON paths, still quoted: `content ->> '$.runtime.engine'`. Booleans arrive as `1` and `0`:
+
+```sh
+uvx dirsql "SELECT path FROM './**/metadata.json' WHERE json_valid(content) AND content ->> 'disabled' = 0" --format json
+```
+
+Count across an array field with `json_each`, guarded the same way:
+
+```sh
+uvx dirsql "SELECT t.value AS tag, COUNT(*) AS n FROM './**/metadata.json' AS m, json_each(m.content, '$.tags') AS t WHERE json_valid(m.content) GROUP BY tag ORDER BY n DESC, tag" --format json
+```
+
+### Frontmatter
+
+Files whose frontmatter contains a given line (`%` matches across newlines):
+
+```sh
+uvx dirsql "SELECT path FROM './**/*.md' WHERE content LIKE '---%status: draft%'" --format json
+```
+
+One frontmatter field from every file:
+
+```sh
+uvx dirsql "WITH fm AS (SELECT path, substr(content, instr(content, 'title:') + 6) AS rest FROM './**/*.md' WHERE content LIKE '---%title:%') SELECT path, trim(substr(rest, 1, instr(rest, char(10)) - 1)) AS title FROM fm ORDER BY path" --format json
+```
+
+### Occurrences of a string per file
+
+grep stops at matching lines; SQL can count them:
+
+```sh
+uvx dirsql "SELECT path, (length(content) - length(replace(content, 'TODO', ''))) / length('TODO') AS todos FROM './**/*.md' WHERE todos > 0 ORDER BY todos DESC" --format json
+```
+
+### Join two directories
+
+Source modules with no matching doc page:
+
+```sh
+uvx dirsql "SELECT s.path FROM './src/*.py' AS s LEFT JOIN './docs/**/*.md' AS d ON replace(d.basename, '.md', '') = replace(s.basename, '.py', '') WHERE d.path IS NULL ORDER BY s.path" --format json
+```
+
+### Top-k by meaning
+
+Needs the embeddings plugin. The first run downloads a model of roughly a hundred megabytes, with progress on stderr:
+
+```sh
+uvx --with dirsql-plugin-embeddings dirsql "
+  SELECT path,
+         vec_distance_cosine(emb, embed('how do I cook pasta?')) AS distance
+  FROM (SELECT path, embed(content) AS emb FROM './notes/*.md')
+  WHERE emb IS NOT NULL
+  ORDER BY distance
+  LIMIT 3" --format json
+```
+
+`WHERE emb IS NOT NULL` matters: an unreadable file embeds to `NULL`, and SQLite sorts `NULL` first. For ranked paths only, `uvx dirsql-plugin-embeddings './notes/*.md' "how do I cook pasta?" -k 3` prints `path<TAB>distance` lines.

dirsql-0.4.68/packages/python/docs/context/troubleshooting.md

@@ -0,0 +1,64 @@
+## Troubleshooting
+
+Diagnostics go to stderr and the exit code is `1`.
+
+### `no such table: **/*.md; did you mean './**/*.md'?`
+
+A bare glob. Paths relative to the directory you run in start with `./`:
+
+```sh
+uvx dirsql "SELECT path FROM './**/*.md'" --format json
+```
+
+### `near ".": syntax error` and `hint: paths used as table names must be quoted`
+
+`FROM ./` reaches SQLite's parser as punctuation. Quote the path:
+
+```sh
+uvx dirsql "SELECT COUNT(*) AS files FROM './'" --format json
+```
+
+### `no such column: disabled`
+
+`content ->> disabled` names a column. The key is a string literal:
+
+```sh
+uvx dirsql "SELECT path, content ->> 'disabled' AS disabled FROM './**/metadata.json' WHERE json_valid(content)" --format json
+```
+
+### `SQLite error: malformed JSON`
+
+One matched file is not valid JSON (an empty file counts), and that fails the whole query. Guard with `json_valid`:
+
+```sh
+uvx dirsql "SELECT path, content ->> 'name' AS name FROM './**/*.json' WHERE json_valid(content)" --format json
+```
+
+### `no such table: files; did you mean FROM './**'?`
+
+There is no implicit table. Query the tree directly:
+
+```sh
+uvx dirsql "SELECT path FROM './**'" --format json
+```
+
+### Empty `[]` for files you can see
+
+- **You named a directory**, which lists one level only. `'./**'` and `'./docs/**'` are the recursive forms.
+- **The files are gitignored.** `--no-ignore` scans them:
+
+  ```sh
+  uvx dirsql "SELECT path FROM './**'" --format json --no-ignore
+  ```
+
+  Naming the directory outright also works: `'./build'` scans `build/` even when it is ignored.
+- **The files are under `node_modules`**, which is skipped unless the path names it: `'./node_modules/**'`.
+- **The files start with a dot, or sit under a directory that does.** Spell the dot: `'./.git/**'`, `'./**/.env'`.
+
+### `table ./ may not be modified`
+
+dirsql is read-only. Mutations belong in a script that consumes the query's JSON.
+
+### A table appeared, not JSON
+
+`--format json` was not passed and stdout was a terminal. Pass it.

dirsql-0.4.68/packages/python/docs/context/usage.md

@@ -0,0 +1,54 @@
+## Usage
+
+dirsql answers a question about a directory tree with SQL. Nothing to install; run it from the directory in question:
+
+```sh
+uvx dirsql "SELECT basename, size FROM './**' ORDER BY size DESC LIMIT 5" --format json
+```
+
+Always pass `--format json`. Without it the output depends on stdout: a terminal gets a table, a pipe gets JSON, and you cannot know which you have. With it, stdout is one JSON array of row objects. Errors go to stderr with exit code `1`.
+
+### Path-tables
+
+A quoted path stands in for a table name. Paths are relative to the directory you run in.
+
+| You write | dirsql scans |
+| --- | --- |
+| `'./'` | files directly here, no deeper |
+| `'./docs'` | files directly inside `docs/`, no deeper |
+| `'./*.md'` | markdown directly here |
+| `'./**'` | every file, any depth |
+| `'./docs/**'` | every file under `docs/`, any depth |
+| `'./**/*.md'` | markdown at any depth |
+| `'./notes/today.md'` | that one file |
+
+`*` matches within one directory level and `**` matches any depth. A directory name lists one level, like `ls docs`, so write `'./**'` to scan the whole tree. Rows are files only, never directories. `'/var/log/*.log'`, `'../notes'` and `'~/notes/*.md'` also resolve; those report absolute `path` values.
+
+Two mistakes fail every time:
+
+1. **The path must be quoted.** `FROM ./` is a syntax error; write `FROM './'`.
+2. **`content ->> 'key'` takes a string literal.** `content ->> key` fails with `no such column: key`.
+
+### Columns
+
+Every row has `path`, `basename`, `dir`, `ext` (no dot, `NULL` when absent), `size` (bytes), `mtime` and `ctime` (Unix seconds). A hidden `content` column holds the file's text: it is left out of `SELECT *`, read only when you name it, and `NULL` for unreadable or non-UTF-8 files.
+
+### What a scan skips
+
+- **`.gitignore` is respected.** Pass `--no-ignore` to scan gitignored files too, or name the ignored directory outright: `'./build'` scans `build/`.
+- **`node_modules` is skipped** unless the path names it: `'./node_modules/**'`.
+- **`'./**'` does not enter `.git`.** Naming it scans it: `'./.git/**'`.
+- **To match dotfiles, spell the dot:** `'./.github/**'`, `'./**/.env'`.
+
+### Escalation
+
+1. A path-table, as above. Fits a question you ask once.
+2. The same tree queried repeatedly, or a parser you want to keep: declare a table in a `.dirsql.toml` and pass it with `-c .dirsql.toml`. See [config](https://dirsql.dev/reference/config).
+3. One row per record inside each file, inline: `--on-file <command>` attaches a parser to every path-table in the query, and its output replaces the stat columns. See [hooks](https://dirsql.dev/reference/hooks).
+4. Search by meaning: `uvx --with dirsql-plugin-embeddings dirsql "<sql>" --format json` adds `embed()` and `vec_distance_cosine()`. See [search by meaning](https://dirsql.dev/howto/search-by-meaning).
+
+### Read-only
+
+dirsql never writes to, moves or changes the files it scans, and it rejects mutating SQL. Do not pass `--persist`: it writes a cache database into the directory.
+
+Full docs: [dirsql.dev](https://dirsql.dev/) ([path-tables](https://dirsql.dev/reference/path-tables), [columns](https://dirsql.dev/reference/columns), [CLI](https://dirsql.dev/reference/cli), [query JSON](https://dirsql.dev/howto/query-json)).

{dirsql-0.4.67/packages/rust → dirsql-0.4.68/packages/python}/docs/reference/cli.md

@@ -11,6 +11,7 @@ The `dirsql` binary has these modes:
 | `dirsql query "<sql>"` | Explicit synonym for the default one-shot query. |
 | `dirsql server` | Start a long-lived HTTP server exposing a SQL view of a directory. See [HTTP API](./http-api.md). |
 | `dirsql init` | Generate a `.dirsql.toml`. |
+| `dirsql context` | Print the usage guide for this version, for an agent to read. |
 | `dirsql` (bare) | Open a [REPL](#the-repl) over the current directory, reading statements until EOF. |
 
 Bare `dirsql` does **not** start the server — that is `dirsql server`.
@@ -441,6 +442,17 @@ All failures exit `1` with a message on stderr:
 
 On success, `init` exits `0`.
 
+## `dirsql context`
+
+```sh
+uvx dirsql context
+```
+
+Prints a markdown guide for an agent that is about to query files: the
+first line is `dirsql <version>`, then sections on usage, recipes and
+troubleshooting. The guide is compiled into the binary, so it describes the
+version that prints it. It takes no flags and exits `0`.
+
 ## Plugins
 
 A **plugin** is an ordinary Python package that ships a `dirsql.toml` config