dirsql 0.4.70 → 0.4.72

package/dist/cli/resolve-config-extensions.js

@@ -22,7 +22,7 @@ const NATIVE_CONFIG_SUFFIXES = [".py", ".js", ".mjs", ".cjs"];
  * launcher as a clean error).
  */
 export async function withResolvedExtensions(argv) {
-    if (argv[0] === "init") {
+    if (argv[0] === "init" || argv[0] === "context") {
         return argv;
     }
     const configPaths = getCore()

package/docs/howto/skip-files.md

@@ -47,8 +47,10 @@ dirsql query "SELECT basename FROM notes ORDER BY basename" -c ./.dirsql.toml
 ## Notes
 
 - `ignore` lives in a config file, so it needs one:
-  [configless mode](../reference/cli.md#configless-mode) indexes
-  everything with no ignores.
+  [configless mode](../reference/cli.md#configless-mode) has no `ignore`
+  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)).

package/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`.
@@ -269,8 +270,10 @@ defines **no named tables**. Filesystem queries go through
 scanned live. A `./.dirsql.toml` sitting in the current directory is **not**
 auto-loaded (pass it with `-c ./.dirsql.toml` to use it).
 
-`'./'` is the whole root — every file at any depth, one row per file, with
-all seven [stat columns](./columns.md): `path`, `basename`, `dir`, `ext`,
+`'./'` lists the files directly inside the root, one level, like `ls`;
+`'./**'` reaches every depth. Both scans apply the path-table
+[skip rules](./path-tables.md#skip-rules), and each returns one row per file
+with all seven [stat columns](./columns.md): `path`, `basename`, `dir`, `ext`,
 `size`, `mtime`, `ctime`.
 
 ```bash
@@ -439,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

package/docs/reference/path-tables.md

@@ -287,10 +287,25 @@ beneath it; one above it is never read.
 
 ### Hidden files
 
-Dotfiles are ordinary files: `'./'` and `'./*'` include them, with or without
-`--no-ignore`. This is a deliberate divergence from fd/ripgrep — querying
-dotfile directories (`.claude/`, …) is a first-class `dirsql` use case. Add an
-`ignore` pattern if you would rather not see them.
+A path component starting with `.` is skipped unless the path spells it, the
+rule `ls` and `fd` use. `'./'` and `'./**'` skip `.gitignore`, `.env` and
+everything under `.claude/`; naming the component lists it:
+
+| You write | dirsql scans |
+| --- | --- |
+| `'./**'` | every file, skipping dot-named files and directories at any depth |
+| `'./.claude'`, `'./.claude/**'` | the files under `.claude/` |
+| `'./.env'` | that one file |
+| `'./**/.env'` | every `.env` whose parent directories are not themselves dot-named |
+| `'~/.claude/projects/*/*.jsonl'` | the walk starts inside `.claude/`, so nothing there is hidden |
+
+A spelled component may be a glob of its own: `'./.env*'` lists `.env.local`,
+and `'./.*'` lists every dot-named entry one level down. A dot component the
+path does not spell stays hidden however deep the scan goes, so
+`'./.claude/**'` lists `.claude/sub/notes.md` but not `.claude/sub/.cache/x`.
+
+This is independent of `.gitignore`: [`--no-ignore`](./cli.md#flags) restores
+gitignored files and leaves dot-named entries hidden.
 
 ## Joining against declared tables
 

package/package.json

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