dirsql 0.3.5__tar.gz → 0.3.7__tar.gz

{dirsql-0.3.5 → dirsql-0.3.7}/Cargo.lock

@@ -499,7 +499,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.3.5"
+version = "0.3.7"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.3.5 → dirsql-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.5
+Version: 0.3.7
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-describe>=2 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
@@ -12,7 +12,7 @@ Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index
 Author: Kevin Scott
 License-Expression: MIT
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 
 # `dirsql` (Python SDK)
@@ -64,13 +64,13 @@ async def main():
             Table(
                 ddl="CREATE TABLE comments (id TEXT, body TEXT, author TEXT)",
                 glob="comments/**/index.jsonl",
-                extract=lambda path, content: [
+                extract=lambda path: [
                     {
                         "id": os.path.basename(os.path.dirname(path)),
                         "body": row["body"],
                         "author": row["author"],
                     }
-                    for line in content.splitlines()
+                    for line in open(path, encoding="utf-8").read().splitlines()
                     for row in [json.loads(line)]
                 ],
             ),
@@ -94,12 +94,12 @@ db = DirSQL(
         Table(
             ddl="CREATE TABLE posts (title TEXT, author_id TEXT)",
             glob="posts/*.json",
-            extract=lambda path, content: [json.loads(content)],
+            extract=lambda path: [json.loads(open(path, encoding="utf-8").read())],
         ),
         Table(
             ddl="CREATE TABLE authors (id TEXT, name TEXT)",
             glob="authors/*.json",
-            extract=lambda path, content: [json.loads(content)],
+            extract=lambda path: [json.loads(open(path, encoding="utf-8").read())],
         ),
     ],
 )
@@ -139,7 +139,7 @@ async def main():
             Table(
                 ddl="CREATE TABLE items (name TEXT)",
                 glob="**/*.json",
-                extract=lambda path, content: [json.loads(content)],
+                extract=lambda path: [json.loads(open(path, encoding="utf-8").read())],
             ),
         ],
     )
@@ -165,7 +165,7 @@ Defines how files map to a SQL table.
 
 - **`ddl`** (`str`): A `CREATE TABLE` statement defining the schema.
 - **`glob`** (`str`): A glob pattern matched against file paths relative to root.
-- **`extract`** (`Callable[[str, str], list[dict]]`): A function receiving `(relative_path, file_content)` and returning a list of row dicts. Each dict's keys must match the DDL column names.
+- **`extract`** (`Callable[[str], list[dict]]`): A function receiving the matched file's absolute filesystem path and returning a list of row dicts. dirsql does not read file contents; a callback that needs the file body reads it itself (e.g. `open(path, encoding="utf-8").read()`). Each dict's keys must match the DDL column names.
 
 ### `DirSQL(root=None, *, tables=None, ignore=None, config=None)`
 

{dirsql-0.3.5/packages/python → dirsql-0.3.7}/README.md

@@ -47,13 +47,13 @@ async def main():
             Table(
                 ddl="CREATE TABLE comments (id TEXT, body TEXT, author TEXT)",
                 glob="comments/**/index.jsonl",
-                extract=lambda path, content: [
+                extract=lambda path: [
                     {
                         "id": os.path.basename(os.path.dirname(path)),
                         "body": row["body"],
                         "author": row["author"],
                     }
-                    for line in content.splitlines()
+                    for line in open(path, encoding="utf-8").read().splitlines()
                     for row in [json.loads(line)]
                 ],
             ),
@@ -77,12 +77,12 @@ db = DirSQL(
         Table(
             ddl="CREATE TABLE posts (title TEXT, author_id TEXT)",
             glob="posts/*.json",
-            extract=lambda path, content: [json.loads(content)],
+            extract=lambda path: [json.loads(open(path, encoding="utf-8").read())],
         ),
         Table(
             ddl="CREATE TABLE authors (id TEXT, name TEXT)",
             glob="authors/*.json",
-            extract=lambda path, content: [json.loads(content)],
+            extract=lambda path: [json.loads(open(path, encoding="utf-8").read())],
         ),
     ],
 )
@@ -122,7 +122,7 @@ async def main():
             Table(
                 ddl="CREATE TABLE items (name TEXT)",
                 glob="**/*.json",
-                extract=lambda path, content: [json.loads(content)],
+                extract=lambda path: [json.loads(open(path, encoding="utf-8").read())],
             ),
         ],
     )
@@ -148,7 +148,7 @@ Defines how files map to a SQL table.
 
 - **`ddl`** (`str`): A `CREATE TABLE` statement defining the schema.
 - **`glob`** (`str`): A glob pattern matched against file paths relative to root.
-- **`extract`** (`Callable[[str, str], list[dict]]`): A function receiving `(relative_path, file_content)` and returning a list of row dicts. Each dict's keys must match the DDL column names.
+- **`extract`** (`Callable[[str], list[dict]]`): A function receiving the matched file's absolute filesystem path and returning a list of row dicts. dirsql does not read file contents; a callback that needs the file body reads it itself (e.g. `open(path, encoding="utf-8").read()`). Each dict's keys must match the DDL column names.
 
 ### `DirSQL(root=None, *, tables=None, ignore=None, config=None)`
 

dirsql-0.3.7/docs/.vitepress/config.ts

@@ -0,0 +1,83 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'dirsql',
+  description: 'Ephemeral SQL index over a local directory. Watches a filesystem, ingests structured files into an in-memory SQLite database, and exposes a SQL query interface.',
+  base: '/dirsql/',
+
+  themeConfig: {
+    search: {
+      provider: 'local'
+    },
+
+    nav: [
+      { text: 'Getting Started', link: '/getting-started' },
+      { text: 'Guide', link: '/guide/tables' },
+      { text: 'CLI', link: '/cli/' },
+      { text: 'Reference', link: '/api/' },
+      { text: 'Migrations', link: '/migrations' },
+      { text: 'GitHub', link: 'https://github.com/thekevinscott/dirsql' }
+    ],
+
+    sidebar: {
+      '/cli/': [
+        {
+          text: 'CLI',
+          items: [
+            { text: 'Overview & Installation', link: '/cli/' },
+            { text: 'Running the Server', link: '/cli/server' },
+            { text: 'Generating a Config (`init`)', link: '/cli/init' },
+            { text: 'Configuration File', link: '/cli/config' },
+            { text: 'HTTP API', link: '/cli/http-api' }
+          ]
+        }
+      ],
+      '/': [
+        {
+          text: 'Tutorials',
+          items: [
+            { text: 'Getting Started', link: '/getting-started' }
+          ]
+        },
+        {
+          text: 'How-to Guides',
+          items: [
+            { text: 'Defining Tables', link: '/guide/tables' },
+            { text: 'Querying', link: '/guide/querying' },
+            { text: 'File Watching', link: '/guide/watching' },
+            { text: 'Persistence', link: '/guide/persistence' },
+            { text: 'Async API', link: '/guide/async' },
+            { text: 'Collaboration with CRDTs', link: '/guide/crdt' }
+          ]
+        },
+        {
+          text: 'CLI',
+          items: [
+            { text: 'Using `dirsql` from the CLI', link: '/cli/' }
+          ]
+        },
+        {
+          text: 'Reference',
+          items: [
+            { text: 'API Reference', link: '/api/' },
+            { text: 'Migrations', link: '/migrations' }
+          ]
+        }
+      ]
+    },
+
+    outline: {
+      level: [2, 3],
+      label: 'On this page'
+    },
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/thekevinscott/dirsql' }
+    ],
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright 2024-present'
+    }
+  }
+})

{dirsql-0.3.5 → dirsql-0.3.7}/docs/AGENTS.md

@@ -42,6 +42,12 @@ The docs follow the [Diataxis](https://diataxis.fr/) framework:
 - **Reference** (`api/`) -- information-oriented, API details
 - **Explanation** (`architecture.md`) -- understanding-oriented, design decisions
 
+The **CLI** (`cli/`) is a self-contained section reachable from its own
+top-level `CLI` nav tab, with a path-scoped sidebar (`/cli/` key in
+`config.ts`). Everything a CLI user needs -- installation, running the server,
+`init`, the `.dirsql.toml` config file, and the HTTP API -- lives under
+`cli/`. Do not move CLI pages back into `guide/`.
+
 ## Conventions
 
 - Wrap `dirsql` in backticks in all prose text

{dirsql-0.3.5 → dirsql-0.3.7}/docs/api/index.md

@@ -168,15 +168,15 @@ import { Table } from 'dirsql';
 ::: code-group
 
 ```python [Python]
-Table(*, ddl: str, glob: str, extract: Callable[[str, str], list[dict]])
+Table(*, ddl: str, glob: str, extract: Callable[[str], list[dict]])
 ```
 
 ```rust [Rust]
-Table::new(ddl: &str, glob: &str, extract: fn(&str, &str) -> Vec<Value>)
+Table::new(ddl: &str, glob: &str, extract: fn(&str) -> Vec<Value>)
 ```
 
 ```typescript [TypeScript]
-new Table({ ddl: string, glob: string, extract: (path: string, content: string) => Record<string, unknown>[] })
+new Table({ ddl: string, glob: string, extract: (path: string) => Record<string, unknown>[] })
 ```
 
 :::
@@ -187,7 +187,7 @@ Defines a mapping from files to SQLite table rows.
 
 - `ddl` -- A `CREATE TABLE` statement. The table name is parsed from this DDL.
 - `glob` -- A glob pattern matched against file paths relative to the root directory.
-- `extract` -- A callable `(path, content) -> list[dict]`. Receives the relative file path and file content as strings. Returns a list of dicts/maps mapping column names to values. Return an empty list to skip a file.
+- `extract` -- A callable `(path) -> list[dict]`. Receives the absolute filesystem path of the matched file. `dirsql` does not read file contents; a callback that needs the file body reads `path` itself. Returns a list of dicts/maps mapping column names to values. Return an empty list to skip a file.
 
 **Attributes:**
 

{dirsql-0.3.5/packages/python/docs/guide → dirsql-0.3.7/docs/cli}/config.md

@@ -1,23 +1,12 @@
 ---
-canonical: https://thekevinscott.github.io/dirsql/guide/config
+canonical: https://thekevinscott.github.io/dirsql/cli/config
 ---
 
 # Configuration File
 
-> Online: <https://thekevinscott.github.io/dirsql/guide/config>
+> Online: <https://thekevinscott.github.io/dirsql/cli/config>
 
-`dirsql` can be configured with a `.dirsql.toml` file. Tables defined this
-way produce **one row per matched file**. Each row's columns come from
-filesystem facts:
-
-- **Glob path captures** — named `{placeholder}` segments in the glob.
-- **Stat virtuals** — reserved `_`-prefixed columns for path-derived and
-  stat-derived metadata.
-
-Content interpretation (parsing JSON, CSV, frontmatter, etc.) is **not**
-configured in `.dirsql.toml`. If you need columns derived from file
-contents, register a programmatic [`Table`](./tables.md) whose `extract`
-function does the parsing in your host language.
+`dirsql` can be configured with an optional `.dirsql.toml` file (if omitted, server falls back to [defaults](./server.md#defaults)). `.dirsql.toml` defines how files are parsed into SQL tables.
 
 ## Basic Example
 
@@ -30,8 +19,7 @@ ddl  = "CREATE TABLE posts (_path TEXT, _basename TEXT, _size INTEGER, _mtime IN
 glob = "posts/*.md"
 ```
 
-Each `posts/*.md` file produces one row. The DDL declares which stat
-virtuals are surfaced as SQL columns.
+Each `posts/*.md` file produces one row in the `posts` table.
 
 ## Loading a Config File
 
@@ -131,7 +119,7 @@ ignore = ["node_modules/**", ".git/**", "*.pyc", "__pycache__/**"]
 
 The top-level `.dirsql/` directory is always excluded, whether you list it
 or not — it is a reserved namespace for `dirsql`'s own metadata (see
-[Persistence](./persistence.md)).
+[Persistence](../guide/persistence.md)).
 
 ## Persistence
 
@@ -144,7 +132,7 @@ persist = true
 # persist_path = ".dirsql/cache.db"   # optional; this is the default
 ```
 
-See [Persistence](./persistence.md) for the full reconcile algorithm,
+See [Persistence](../guide/persistence.md) for the full reconcile algorithm,
 storage layout, and limitations.
 
 ## Strict Mode
@@ -163,7 +151,7 @@ strict = true
 Strict mode does **not** apply to auto-injected stat virtuals — those are
 always filtered to the DDL's declared columns regardless. Strict mode
 applies only to keys produced by an extract callback (relevant for
-programmatic [tables](./tables.md)).
+programmatic [tables](../guide/tables.md)).
 
 ## Full Example
 
@@ -188,6 +176,6 @@ glob = "logs/*.csv"
 
 `.dirsql.toml` does not parse file contents. For columns derived from the
 *inside* of files (frontmatter keys, JSON values, CSV cells, etc.),
-register a programmatic [`Table`](./tables.md) instead, and parse the
+register a programmatic [`Table`](../guide/tables.md) instead, and parse the
 bytes in your host language. Glob captures and stat virtuals are still
 auto-injected into rows produced by your extract.

dirsql-0.3.5/docs/guide/cli.md → dirsql-0.3.7/docs/cli/http-api.md

@@ -1,65 +1,16 @@
 ---
-canonical: https://thekevinscott.github.io/dirsql/guide/cli
+canonical: https://thekevinscott.github.io/dirsql/cli/http-api
 ---
 
-# Command-Line Interface
+# HTTP API
 
-> Online: <https://thekevinscott.github.io/dirsql/guide/cli>
+> Online: <https://thekevinscott.github.io/dirsql/cli/http-api>
 
-`dirsql` starts an HTTP server that exposes identical SDK functionality.
+Once the [server is running](./server.md), `dirsql` exposes two HTTP
+endpoints: `POST /query` for SQL queries and `GET /events` for a real-time
+change stream.
 
-## Installation
-
-::: code-group
-
-```bash [npm]
-npx dirsql
-```
-
-```bash [PyPI]
-uvx dirsql
-```
-
-```bash [Cargo]
-# Installs the binary only (non-default feature)
-cargo install dirsql --features cli
-dirsql
-```
-
-:::
-
-::: tip For Rust library consumers
-The `cli` feature is **opt-in**. Adding `dirsql` as a library dependency (`cargo add dirsql`) pulls no CLI dependencies — only the core library. See the [Rust library README](https://github.com/thekevinscott/dirsql/tree/main/packages/rust) for details.
-:::
-
-## Subcommands
-
-| Command | Purpose |
-|---|---|
-| `dirsql` (no subcommand) | Start the long-lived HTTP server (default behavior, see below). |
-| `dirsql init` | Generate a starter `.dirsql.toml` from the contents of a directory. See [Generating a Config](./init.md). |
-
-## Running the server
-
-Run `dirsql` from the directory containing your files:
-
-```bash
-dirsql
-
-$ Running at localhost:7117
-```
-
-### Flags
-
-| Flag | Default | Description |
-|---|---|---|
-| `--config <path>` | `./.dirsql.toml` | Path to the config file. The index is rooted at the directory containing this file. |
-| `--host <addr>` | `localhost` | Bind address |
-| `--port <n>` | `7117` | TCP port to bind |
-
-## HTTP API
-
-### `POST /query`
+## `POST /query`
 
 Run a SQL query. Request body is JSON:
 
@@ -91,9 +42,12 @@ curl -s http://localhost:7117/query \
   | jq
 ```
 
-### `GET /events`
+The query interface is the same one the SDK exposes; see [Querying](../guide/querying.md)
+for SQL semantics, the read-only restriction, and the return format.
+
+## `GET /events`
 
-Opens a [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) stream of change events. Each `data:` payload is the same JSON schema the SDK emits from [`db.watch()`](./watching.md#event-types):
+Opens a [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) stream of change events. Each `data:` payload is the same JSON schema the SDK emits from [`db.watch()`](../guide/watching.md#event-types):
 
 ```
 event: row

dirsql-0.3.7/docs/cli/index.md

@@ -0,0 +1,73 @@
+---
+canonical: https://thekevinscott.github.io/dirsql/cli/
+---
+
+# Using `dirsql` from the CLI
+
+> Online: <https://thekevinscott.github.io/dirsql/cli/>
+
+`dirsql` ships a command-line interface that starts an HTTP server exposing
+the same indexing, querying, and watching functionality as the SDK — no host
+language required. Run it in any directory to query your files over HTTP:
+with no config it serves a default `files` table, and a
+[`.dirsql.toml`](./config.md) config defines custom tables.
+
+Everything you need to run `dirsql` as a CLI lives in this section:
+
+- **[Installation](#installation)** — get the `dirsql` binary.
+- **[Running the Server](./server.md)** — subcommands and flags.
+- **[Generating a Config (`init`)](./init.md)** — scaffold a `.dirsql.toml`.
+- **[Configuration File](./config.md)** — the `.dirsql.toml` format. Custom
+  tables are defined exclusively through this file; without it, the server
+  runs in [zero-config mode](./server.md#zero-config-mode).
+- **[HTTP API](./http-api.md)** — the `POST /query` and `GET /events`
+  endpoints, status codes, and event streaming.
+
+## Installation
+
+::: code-group
+
+```bash [npm]
+npx dirsql
+```
+
+```bash [PyPI]
+uvx dirsql
+```
+
+```bash [Cargo]
+# Installs the binary only (the `cli` feature is non-default)
+cargo install dirsql --features cli
+dirsql
+```
+
+:::
+
+::: tip For Rust library consumers
+The `cli` feature is **opt-in**. Adding `dirsql` as a library dependency
+(`cargo add dirsql`) pulls no CLI dependencies — only the core library. See the
+[Rust library README](https://github.com/thekevinscott/dirsql/tree/main/packages/rust)
+for the library-vs-CLI feature split.
+:::
+
+## Quick start
+
+From a directory containing your files and a [`.dirsql.toml`](./config.md):
+
+```bash
+dirsql
+
+$ Running at localhost:7117
+```
+
+Then query it over HTTP:
+
+```bash
+curl -s http://localhost:7117/query \
+  -H 'content-type: application/json' \
+  -d '{"sql":"SELECT COUNT(*) AS n FROM posts"}' \
+  | jq
+```
+
+See [Running the Server](./server.md) for flags and [HTTP API](./http-api.md)
+for the full endpoint reference.

{dirsql-0.3.5/docs/guide → dirsql-0.3.7/docs/cli}/init.md

@@ -1,14 +1,14 @@
 ---
-canonical: https://thekevinscott.github.io/dirsql/guide/init
+canonical: https://thekevinscott.github.io/dirsql/cli/init
 ---
 
 # Generating a config with `dirsql init`
 
-> Online: <https://thekevinscott.github.io/dirsql/guide/init>
+> Online: <https://thekevinscott.github.io/dirsql/cli/init>
 
-`dirsql init` generates a `.dirsql.toml` by running `claude` over the target directory.
+`dirsql init` generates a [`.dirsql.toml`](./config.md) by running `claude` over the target directory.
 
-The output is limited to filesystem-fact tables. For content-aware schemas, see [Defining Tables](./tables.md).
+The output is limited to filesystem-fact tables. For content-aware schemas, see [Defining Tables](../guide/tables.md).
 
 ## Examples
 

dirsql-0.3.7/docs/cli/server.md

@@ -0,0 +1,59 @@
+---
+canonical: https://thekevinscott.github.io/dirsql/cli/server
+---
+
+# Running the Server
+
+> Online: <https://thekevinscott.github.io/dirsql/cli/server>
+
+The `dirsql` CLI is an HTTP server that exposes identical SDK functionality
+over [`POST /query`](./http-api.md#post-query) and [`GET /events`](./http-api.md#get-events).
+
+## Subcommands
+
+| Command | Purpose |
+|---|---|
+| `dirsql` (no subcommand) | Start the long-lived HTTP server (default behavior, see below). |
+| `dirsql init` | Generate a starter `.dirsql.toml` from the contents of a directory. See [Generating a Config](./init.md). |
+
+## Running the server
+
+Run `dirsql` from the directory containing your files:
+
+```bash
+dirsql
+
+$ Running at localhost:7117
+```
+
+The server reads tables from a [`.dirsql.toml`](./config.md) config file. By
+default it looks for `./.dirsql.toml`; override the path with `--config`.
+
+## Defaults
+
+If no config file is found, `dirsql` serves a single table named `files`, with one row per file under the directory
+
+```bash
+cd ~/some/directory   # no .dirsql.toml here
+dirsql
+
+$ Running at localhost:7117
+```
+
+```bash
+curl -s localhost:7117/query -H 'content-type: application/json' \
+  -d '{"sql":"SELECT _basename, _size FROM files ORDER BY _size DESC LIMIT 5"}'
+```
+
+A `.dirsql.toml` file will override the default.
+
+## Flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--config <path>` | `./.dirsql.toml` | Path to the config file. The index is rooted at the directory containing this file. |
+| `--host <addr>` | `localhost` | Bind address |
+| `--port <n>` | `7117` | TCP port to bind |
+
+Once the server is running, see the [HTTP API](./http-api.md) for the request
+and response formats.

{dirsql-0.3.5/packages/python → dirsql-0.3.7}/docs/getting-started.md

@@ -31,7 +31,7 @@ cargo install dirsql --features cli
 
 :::
 
-See the [CLI guide](./guide/cli.md) for details on the command-line interface, and the [Rust library README](https://github.com/thekevinscott/dirsql/tree/main/packages/rust) for the library-vs-CLI feature split.
+See the [CLI section](./cli/) for details on the command-line interface, and the [Rust library README](https://github.com/thekevinscott/dirsql/tree/main/packages/rust) for the library-vs-CLI feature split.
 
 ## Quick start
 
@@ -63,12 +63,12 @@ async def main():
             Table(
                 ddl="CREATE TABLE posts (title TEXT, author TEXT)",
                 glob="posts/*.json",
-                extract=lambda path, content: [json.loads(content)],
+                extract=lambda path: [json.loads(open(path, encoding="utf-8").read())],
             ),
             Table(
                 ddl="CREATE TABLE authors (id TEXT, name TEXT)",
                 glob="authors/*.json",
-                extract=lambda path, content: [json.loads(content)],
+                extract=lambda path: [json.loads(open(path, encoding="utf-8").read())],
             ),
         ],
     )
@@ -120,12 +120,12 @@ let db = DirSQL::new(
         Table::new(
             "CREATE TABLE posts (title TEXT, author TEXT)",
             "posts/*.json",
-            |_path, content| vec![row_from_json(content)],
+            |path| vec![row_from_json(&std::fs::read_to_string(path).unwrap())],
         ),
         Table::new(
             "CREATE TABLE authors (id TEXT, name TEXT)",
             "authors/*.json",
-            |_path, content| vec![row_from_json(content)],
+            |path| vec![row_from_json(&std::fs::read_to_string(path).unwrap())],
         ),
     ],
 )?;
@@ -139,18 +139,19 @@ let results = db.query(
 ```
 
 ```typescript [TypeScript]
+import { readFileSync } from 'node:fs';
 import { DirSQL, type TableDef } from 'dirsql';
 
 const tables: TableDef[] = [
   {
     ddl: 'CREATE TABLE posts (title TEXT, author TEXT)',
     glob: 'posts/*.json',
-    extract: (_path, content) => [JSON.parse(content)],
+    extract: (path) => [JSON.parse(readFileSync(path, 'utf8'))],
   },
   {
     ddl: 'CREATE TABLE authors (id TEXT, name TEXT)',
     glob: 'authors/*.json',
-    extract: (_path, content) => [JSON.parse(content)],
+    extract: (path) => [JSON.parse(readFileSync(path, 'utf8'))],
   },
 ];
 
@@ -169,8 +170,8 @@ const results = await db.query(`
 ## What happens at startup
 
 1. `dirsql` walks the directory tree
-2. Files matching each table's glob pattern are read
-3. The `extract` function converts file content into rows
+2. Files matching each table's glob pattern are identified
+3. The `extract` function receives each matched file's absolute path and returns rows
 4. Rows are inserted into an in-memory SQLite database
 5. SQL queries run against that database
 
@@ -182,5 +183,5 @@ The filesystem is always the source of truth. The database is rebuilt from files
 - [Querying](./guide/querying.md) -- SQL queries and return format
 - [File Watching](./guide/watching.md) -- real-time change events
 - [Async API](./guide/async.md) -- async ready(), query(), and watch()
-- [Command-Line Interface](./guide/cli.md) -- `dirsql` runs an HTTP server (`POST /query`, `GET /events` SSE)
+- [Using `dirsql` from the CLI](./cli/) -- `dirsql` runs an HTTP server (`POST /query`, `GET /events` SSE)
 - [Collaboration with CRDTs](./guide/crdt.md) -- multi-writer document merging alongside `dirsql`