dirsql 0.3.4__tar.gz → 0.3.6__tar.gz

{dirsql-0.3.4 → dirsql-0.3.6}/Cargo.lock

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

{dirsql-0.3.4 → dirsql-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.4
+Version: 0.3.6
 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)
@@ -33,7 +33,7 @@ Each wheel also bundles the `dirsql` HTTP-server CLI as a console script, so `pi
 
 ## Publishing (maintainers)
 
-Handled by `.github/workflows/publish.yml` (invoked from `minor-release.yml` / `patch-release.yml`). For each target triple the `build` job `cargo build`s the Rust CLI with `--features cli`, stages the binary into `python/dirsql/_binary/`, runs `maturin build` (which picks the binary up via the `[tool.maturin] include` rule in `pyproject.toml`), and the wheels + sdist are then trusted-published to PyPI.
+Handled by `.github/workflows/publish.yml` (invoked from `minor-release.yml` / `patch-release.yml`). For each target triple the `build` job `cargo build`s the Rust CLI with `--features cli`, stages the binary into `dirsql/_binary/`, runs `maturin build` (which picks the binary up via the `[tool.maturin] include` rule in `pyproject.toml`), and the wheels + sdist are then trusted-published to PyPI.
 
 ## Quick Start
 

{dirsql-0.3.4/packages/python → dirsql-0.3.6}/README.md

@@ -16,7 +16,7 @@ Each wheel also bundles the `dirsql` HTTP-server CLI as a console script, so `pi
 
 ## Publishing (maintainers)
 
-Handled by `.github/workflows/publish.yml` (invoked from `minor-release.yml` / `patch-release.yml`). For each target triple the `build` job `cargo build`s the Rust CLI with `--features cli`, stages the binary into `python/dirsql/_binary/`, runs `maturin build` (which picks the binary up via the `[tool.maturin] include` rule in `pyproject.toml`), and the wheels + sdist are then trusted-published to PyPI.
+Handled by `.github/workflows/publish.yml` (invoked from `minor-release.yml` / `patch-release.yml`). For each target triple the `build` job `cargo build`s the Rust CLI with `--features cli`, stages the binary into `dirsql/_binary/`, runs `maturin build` (which picks the binary up via the `[tool.maturin] include` rule in `pyproject.toml`), and the wheels + sdist are then trusted-published to PyPI.
 
 ## Quick Start
 

dirsql-0.3.6/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.4/packages/python → dirsql-0.3.6}/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.4/packages/rust/docs/guide → dirsql-0.3.6/docs/cli}/config.md

@@ -1,10 +1,10 @@
 ---
-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
@@ -16,7 +16,7 @@ filesystem facts:
 
 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`
+contents, register a programmatic [`Table`](../guide/tables.md) whose `extract`
 function does the parsing in your host language.
 
 ## Basic Example
@@ -131,7 +131,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 +144,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 +163,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 +188,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.4/docs/guide/cli.md → dirsql-0.3.6/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.6/docs/cli/index.md

@@ -0,0 +1,71 @@
+---
+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. Point it at a directory, give it a [`.dirsql.toml`](./config.md)
+config, and query your files over HTTP.
+
+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. The CLI
+  defines tables exclusively through this file.
+- **[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.4/packages/python/docs/guide → dirsql-0.3.6/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.6/docs/cli/server.md

@@ -0,0 +1,41 @@
+---
+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`.
+
+## 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.4 → dirsql-0.3.6}/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
 
@@ -182,5 +182,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`

{dirsql-0.3.4/packages/python → dirsql-0.3.6}/docs/guide/querying.md

@@ -8,6 +8,10 @@ canonical: https://thekevinscott.github.io/dirsql/guide/querying
 
 Once a `DirSQL` instance is created, the initial directory scan is complete and you can run SQL queries against the indexed data.
 
+::: tip From the CLI
+The `dirsql` HTTP server exposes the same query interface over [`POST /query`](../cli/http-api.md#post-query). Send `{"sql": "..."}` and get back the same JSON array of row objects. See the [CLI section](../cli/) for the full server setup.
+:::
+
 ## Basic queries
 
 ::: code-group

{dirsql-0.3.4/packages/rust → dirsql-0.3.6}/docs/guide/watching.md

@@ -8,6 +8,10 @@ canonical: https://thekevinscott.github.io/dirsql/guide/watching
 
 `dirsql` can monitor the filesystem for changes and emit events when rows are inserted, updated, or deleted. This is useful for building reactive applications that respond to file changes in real time.
 
+::: tip From the CLI
+The `dirsql` HTTP server streams the same events over [`GET /events`](../cli/http-api.md#get-events) as a [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) stream. Each `data:` payload uses the same JSON schema described in [Event types](#event-types) below. See the [CLI section](../cli/) for the full server setup.
+:::
+
 ## Starting a watch stream
 
 ::: code-group

dirsql-0.3.6/docs/tests/unit/config.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import config from '../../.vitepress/config'
+
+type SidebarItem = { text?: string; link?: string; items?: SidebarItem[] }
+
+describe('vitepress config', () => {
+  it('has the expected site title and base path', () => {
+    expect(config.title).toBe('dirsql')
+    expect(config.base).toBe('/dirsql/')
+  })
+
+  // Regression guard: CLI docs live in their own `/cli/` section, not
+  // interleaved with the SDK how-to guides (see #179).
+  it('keeps CLI pages out of the How-to Guides group', () => {
+    const sidebar = config.themeConfig!.sidebar as Record<string, SidebarItem[]>
+    const howTo = sidebar['/'].find((group) => group.text === 'How-to Guides')
+    const links = (howTo!.items ?? []).map((item) => item.link)
+    expect(links).not.toContain('/guide/cli')
+    expect(links).not.toContain('/guide/init')
+    expect(links).not.toContain('/guide/config')
+  })
+})

{dirsql-0.3.4 → dirsql-0.3.6}/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.3.4"
+version = "0.3.6"
 edition.workspace = true
 publish = false
 readme = "README.md"

{dirsql-0.3.4 → dirsql-0.3.6/packages/python}/README.md

@@ -16,7 +16,7 @@ Each wheel also bundles the `dirsql` HTTP-server CLI as a console script, so `pi
 
 ## Publishing (maintainers)
 
-Handled by `.github/workflows/publish.yml` (invoked from `minor-release.yml` / `patch-release.yml`). For each target triple the `build` job `cargo build`s the Rust CLI with `--features cli`, stages the binary into `python/dirsql/_binary/`, runs `maturin build` (which picks the binary up via the `[tool.maturin] include` rule in `pyproject.toml`), and the wheels + sdist are then trusted-published to PyPI.
+Handled by `.github/workflows/publish.yml` (invoked from `minor-release.yml` / `patch-release.yml`). For each target triple the `build` job `cargo build`s the Rust CLI with `--features cli`, stages the binary into `dirsql/_binary/`, runs `maturin build` (which picks the binary up via the `[tool.maturin] include` rule in `pyproject.toml`), and the wheels + sdist are then trusted-published to PyPI.
 
 ## Quick Start
 

dirsql-0.3.6/packages/python/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.4 → dirsql-0.3.6/packages/python}/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.4/packages/python/docs/guide → dirsql-0.3.6/packages/python/docs/cli}/config.md

@@ -1,10 +1,10 @@
 ---
-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
@@ -16,7 +16,7 @@ filesystem facts:
 
 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`
+contents, register a programmatic [`Table`](../guide/tables.md) whose `extract`
 function does the parsing in your host language.
 
 ## Basic Example
@@ -131,7 +131,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 +144,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 +163,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 +188,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.