From 54abb2e5793fc25f5734de4a927dac3fce022df2 Mon Sep 17 00:00:00 2001
From: Thomas Lin Pedersen <thomasp85@gmail.com>
Date: Thu, 23 Apr 2026 13:22:35 +0200
Subject: [PATCH 1/5] Dynamically build docs for cli during built

---
 Cargo.lock          | 196 ++++++++++++++++-
 doc/vendor/SKILL.md | 497 ++++++++++++++++++++++++++++++++++++++++++++
 src/Cargo.toml      |   8 +
 src/build.rs        | 380 +++++++++++++++++++++++++++++++++
 src/cli.rs          | 277 +++++++++++++++++++++++-
 5 files changed, 1356 insertions(+), 2 deletions(-)
 create mode 100644 doc/vendor/SKILL.md
 create mode 100644 src/build.rs

diff --git a/Cargo.lock b/Cargo.lock
index 58958f31..aa649b2b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -911,7 +911,7 @@ checksum = "e0d05af1e006a2407bedef5af410552494ce5be9090444dbbcb57258c1af3d56"
 dependencies = [
  "strum 0.26.3",
  "strum_macros 0.26.4",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -991,6 +991,24 @@ version = "0.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3d52eff69cd5e647efe296129160853a42795992097e8af39800e1060caeea9b"
 
+[[package]]
+name = "convert_case"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "633458d4ef8c78b72454de2d54fd6ab2e60f9e02be22f3c6104cdc8a4e0fceb9"
+dependencies = [
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "coolor"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "980c2afde4af43d6a05c5be738f9eae595cff86dce1f38f88b95058a98c027f3"
+dependencies = [
+ "crossterm",
+]
+
 [[package]]
 name = "core-foundation"
 version = "0.9.4"
@@ -1080,6 +1098,45 @@ dependencies = [
  "cfg-if",
 ]
 
+[[package]]
+name = "crokey"
+version = "1.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "04a63daf06a168535c74ab97cdba3ed4fa5d4f32cb36e437dcceb83d66854b7c"
+dependencies = [
+ "crokey-proc_macros",
+ "crossterm",
+ "once_cell",
+ "serde",
+ "strict",
+]
+
+[[package]]
+name = "crokey-proc_macros"
+version = "1.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "847f11a14855fc490bd5d059821895c53e77eeb3c2b73ee3dded7ce77c93b231"
+dependencies = [
+ "crossterm",
+ "proc-macro2",
+ "quote",
+ "strict",
+ "syn 2.0.117",
+]
+
+[[package]]
+name = "crossbeam"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1137cd7e7fc0fb5d3c5a8678be38ec56e819125d8d7907411fe24ccb943faca8"
+dependencies = [
+ "crossbeam-channel",
+ "crossbeam-deque",
+ "crossbeam-epoch",
+ "crossbeam-queue",
+ "crossbeam-utils",
+]
+
 [[package]]
 name = "crossbeam-channel"
 version = "0.5.15"
@@ -1123,6 +1180,33 @@ version = "0.8.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
+[[package]]
+name = "crossterm"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8b9f2e4c67f833b660cdb0a3523065869fb35570177239812ed4c905aeff87b"
+dependencies = [
+ "bitflags 2.11.1",
+ "crossterm_winapi",
+ "derive_more",
+ "document-features",
+ "mio",
+ "parking_lot",
+ "rustix 1.1.4",
+ "signal-hook",
+ "signal-hook-mio",
+ "winapi",
+]
+
+[[package]]
+name = "crossterm_winapi"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "acdd7c62a3665c7f6830a51635d9ac9b23ed385797f70a83bb8bafe9c572ab2b"
+dependencies = [
+ "winapi",
+]
+
 [[package]]
 name = "crunchy"
 version = "0.2.4"
@@ -1232,6 +1316,28 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "derive_more"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d751e9e49156b02b44f9c1815bcb94b984cdcc4396ecc32521c739452808b134"
+dependencies = [
+ "derive_more-impl",
+]
+
+[[package]]
+name = "derive_more-impl"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "799a97264921d8623a957f6c3b9011f3b5492f557bbb7a5a19b7fa6d06ba8dcb"
+dependencies = [
+ "convert_case",
+ "proc-macro2",
+ "quote",
+ "rustc_version",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "digest"
 version = "0.10.7"
@@ -1302,6 +1408,15 @@ dependencies = [
  "libloading",
 ]
 
+[[package]]
+name = "document-features"
+version = "0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4b8a88685455ed29a21542a33abd9cb6510b6b129abadabdcef0f4c55bc8f61"
+dependencies = [
+ "litrs",
+]
+
 [[package]]
 name = "dpi"
 version = "0.1.2"
@@ -1815,6 +1930,7 @@ dependencies = [
  "serde_json",
  "sprintf",
  "tempfile",
+ "termimad",
  "thiserror 1.0.69",
  "toml_edit 0.22.27",
  "tree-sitter",
@@ -2486,6 +2602,29 @@ version = "0.2.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a4933f3f57a8e9d9da04db23fb153356ecaf00cbd14aee46279c33dc80925c37"
 
+[[package]]
+name = "lazy-regex"
+version = "3.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6bae91019476d3ec7147de9aa291cadb6d870abf2f3015d2da73a90325ac1496"
+dependencies = [
+ "lazy-regex-proc_macros",
+ "once_cell",
+ "regex",
+]
+
+[[package]]
+name = "lazy-regex-proc_macros"
+version = "3.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4de9c1e1439d8b7b3061b2d209809f447ca33241733d9a3c01eabf2dc8d94358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "regex",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "lazy_static"
 version = "1.5.0"
@@ -2635,6 +2774,12 @@ version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
 
+[[package]]
+name = "litrs"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
+
 [[package]]
 name = "lock_api"
 version = "0.4.14"
@@ -2709,6 +2854,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "minimad"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9c5d708226d186590a7b6d4a9780e2bdda5f689e0d58cd17012a298efd745d2"
+dependencies = [
+ "once_cell",
+]
+
 [[package]]
 name = "miniz_oxide"
 version = "0.8.9"
@@ -2726,6 +2880,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "50b7e5b27aa02a74bac8c3f23f448f8d87ff11f92d3aac1a6ed369ee08cc56c1"
 dependencies = [
  "libc",
+ "log",
  "wasi 0.11.1+wasi-snapshot-preview1",
  "windows-sys 0.61.2",
 ]
@@ -5051,6 +5206,17 @@ dependencies = [
  "signal-hook-registry",
 ]
 
+[[package]]
+name = "signal-hook-mio"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b75a19a7a740b25bc7944bdee6172368f988763b744e3d4dfe753f6b4ece40cc"
+dependencies = [
+ "libc",
+ "mio",
+ "signal-hook",
+]
+
 [[package]]
 name = "signal-hook-registry"
 version = "1.4.8"
@@ -5227,6 +5393,12 @@ version = "0.2.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fe895eb47f22e2ddd4dabc02bce419d2e643c8e3b585c78158b349195bc24d82"
 
+[[package]]
+name = "strict"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f42444fea5b87a39db4218d9422087e66a85d0e7a0963a439b07bcdf91804006"
+
 [[package]]
 name = "stringprep"
 version = "0.1.5"
@@ -5362,6 +5534,22 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "termimad"
+version = "0.31.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7301d9c2c4939c97f25376b70d3c13311f8fefdee44092fc361d2a98adc2cbb6"
+dependencies = [
+ "coolor",
+ "crokey",
+ "crossbeam",
+ "lazy-regex",
+ "minimad",
+ "serde",
+ "thiserror 2.0.18",
+ "unicode-width 0.1.14",
+]
+
 [[package]]
 name = "thiserror"
 version = "1.0.69"
@@ -5814,6 +6002,12 @@ version = "1.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9629274872b2bfaf8d66f5f15725007f635594914870f65218920345aa11aa8c"
 
+[[package]]
+name = "unicode-width"
+version = "0.1.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
+
 [[package]]
 name = "unicode-width"
 version = "0.2.2"
diff --git a/doc/vendor/SKILL.md b/doc/vendor/SKILL.md
new file mode 100644
index 00000000..9397ecae
--- /dev/null
+++ b/doc/vendor/SKILL.md
@@ -0,0 +1,497 @@
+---
+name: ggsql
+description: Write ggsql queries — a grammar of graphics for SQL. Use when the user wants to create, modify, or understand a ggsql visualization query.
+allowed-tools: Bash(ggsql:*)
+argument-hint: "[description of desired visualization]"
+metadata:
+  author: George Stagg (@georgestagg)
+  version: "1.0"
+license: MIT
+---
+
+# ggsql Query Writer
+
+ggsql is a SQL extension for declarative data visualization based on Grammar of Graphics principles. It lets users combine SQL data queries with visualization specifications in a single, composable syntax.
+
+When the user describes a visualization they want, write a valid ggsql query. Use ONLY syntax documented below. NEVER invent clauses, settings, aesthetics, or layer types.
+
+## Query structure
+
+A ggsql query has two parts:
+
+1. **SQL part** (optional): Standard SQL executed on the backend. Any tables, CTEs, or SELECT results are available to the visualization.
+2. **VISUALISE part** (required): Begins with `VISUALISE` (or `VISUALIZE`). Everything after this is the visualization query.
+
+There are two patterns for combining SQL with VISUALISE:
+
+### Pattern A: SELECT → VISUALISE
+
+The last SQL statement is a SELECT. Data flows from its result set into VISUALISE, which has no `FROM` clause.
+
+```ggsql
+SELECT name, score_a, score_b FROM 'dataset.csv' WHERE value > 50
+VISUALISE score_a AS x, score_b AS y
+[DRAW / PLACE / SCALE / FACET / PROJECT / LABEL clauses]
+```
+
+Works with any SQL that ends in a SELECT: bare SELECT, WITH...SELECT, UNION/INTERSECT/EXCEPT.
+
+### Pattern B: VISUALISE FROM
+
+VISUALISE provides its own data source via `FROM`. Use when referencing a table, file, CTE, or built-in dataset directly without a trailing SELECT.
+
+```ggsql
+VISUALISE score_a AS x, score_b AS y FROM 'dataset.csv'
+DRAW point
+```
+
+```ggsql
+WITH summary AS (SELECT category, COUNT(*) AS n FROM 'dataset.csv' GROUP BY category)
+VISUALISE category AS x, n AS y FROM summary
+DRAW bar
+```
+
+## Data sources
+
+Data sources can appear in `VISUALISE ... FROM` or `DRAW ... MAPPING ... FROM`:
+
+- **Table/CTE name** (unquoted): `FROM sales`, `FROM my_cte`
+- **File path** (single-quoted string): `FROM 'data.parquet'`, `FROM 'data.csv'`
+- **Built-in datasets**: `FROM ggsql:penguins`, `FROM ggsql:airquality`
+
+## VISUALISE clause
+
+Marks the start of the visualization. Optionally defines global mappings inherited by all layers.
+
+```
+VISUALISE <mapping>, ... FROM <data-source>
+```
+
+### Mapping forms
+
+- **Explicit**: `column AS aesthetic` — e.g. `revenue AS y`
+- **Implicit**: `column` — column name must match aesthetic name, e.g. `x` maps to `x`
+- **Wildcard**: `*` — all columns with names matching aesthetics are mapped
+- **Constants**: `'red' AS fill`, `42 AS size` — literal values mapped to aesthetic
+
+```ggsql
+VISUALISE bill_len AS x, bill_dep AS y, species AS fill FROM ggsql:penguins
+VISUALISE * FROM my_table
+VISUALISE FROM ggsql:penguins
+```
+
+## DRAW clause
+
+Defines a layer. Multiple DRAW clauses stack layers (first = bottom, last = top).
+
+```
+DRAW <layer-type>
+  MAPPING <mapping>, ... FROM <data-source>
+  REMAPPING <stat-property> AS <aesthetic>, ...
+  SETTING <param> => <value>, ...
+  FILTER <condition>
+  PARTITION BY <column>, ...
+  ORDER BY <column>, ...
+```
+
+All subclauses are optional if VISUALISE provides global mappings and data.
+
+### MAPPING
+
+Same syntax as VISUALISE mappings. Layer mappings merge with global mappings (layer takes precedence). Can include `FROM` for layer-specific data.
+
+- Use `null` to prevent inheriting a global mapping: `MAPPING null AS color`
+
+### REMAPPING
+
+For statistical layers (histogram, density, boxplot, violin, smooth, bar without y). Maps calculated statistics to aesthetics. Each layer documents its available stats and default remapping.
+
+```ggsql
+DRAW histogram
+  MAPPING body_mass AS x
+  REMAPPING density AS y  -- use density instead of default count
+```
+
+### SETTING
+
+Set literal aesthetic values or layer parameters. Aesthetics set here bypass scales.
+
+```ggsql
+DRAW point
+  SETTING size => 5, opacity => 0.7, stroke => 'red'
+```
+
+**Position adjustment** is a special setting:
+```ggsql
+SETTING position => 'identity'   -- no adjustment (default for most)
+SETTING position => 'stack'      -- stack (default for bar, histogram, area)
+SETTING position => 'dodge'      -- side by side (default for boxplot, violin)
+SETTING position => 'jitter'     -- random offset
+```
+
+### FILTER
+
+SQL WHERE condition applied to layer data. Content is passed to the database:
+```ggsql
+DRAW point
+  FILTER sex = 'female' AND body_mass > 4000
+```
+
+### PARTITION BY
+
+Additional grouping columns beyond mapped discrete aesthetics:
+```ggsql
+DRAW line
+  MAPPING Day AS x, Temp AS y
+  PARTITION BY Month
+```
+
+### ORDER BY
+
+Controls record order (important for path layers):
+```ggsql
+DRAW path
+  ORDER BY timestamp
+```
+
+## PLACE clause
+
+Creates annotation layers with literal values only (no data mappings). Supports tuples for multiple annotations.
+
+```
+PLACE <layer-type>
+  SETTING <aesthetic/param> => <value>, ...
+```
+
+```ggsql
+PLACE point SETTING x => 5, y => 10, color => 'red'
+PLACE rule SETTING y => 70, linetype => 'dotted'
+PLACE text SETTING x => (34, 44), y => (66, 49), label => ('Mean = 34', 'Mean = 44')
+```
+
+## SCALE clause
+
+Controls how data values are translated to aesthetic values. Sensible defaults are always provided.
+
+```
+SCALE <type> <aesthetic> FROM <input-range> TO <output-range> VIA <transform>
+  SETTING <param> => <value>, ...
+  RENAMING <value> => <label>, ...
+```
+
+All parts except `aesthetic` are optional.
+
+### Scale types (optional, placed before aesthetic)
+
+- `CONTINUOUS` — continuous numeric/temporal data
+- `DISCRETE` — categorical/string data
+- `BINNED` — bin continuous data into discrete groups (never auto-selected, must be explicit)
+- `ORDINAL` — ordered discrete data (never auto-selected, must be explicit)
+- `IDENTITY` — pass data through unchanged (no legend created)
+
+If omitted, type is inferred from data.
+
+### Aesthetic names
+
+Use the base name: `x`, `y`, `fill`, `stroke`, `color` (sets both fill and stroke), `opacity`, `size`, `linewidth`, `linetype`, `shape`, `panel` (facet), `row`, `column`.
+
+For position families (xmin/xmax/xend/ymin/ymax/yend), scale with the base name: `SCALE x ...`
+
+### FROM (input range)
+
+- Continuous: `FROM (min, max)` — use `null` to infer from data: `FROM (0, null)`
+- Discrete: `FROM ('A', 'B', 'C')` — controls order, omitted values are nulled
+- Include null explicitly: `FROM ('Torgersen', 'Biscoe', null)`
+
+### TO (output range)
+
+- Array of values: `TO ('red', 'blue', 'green')`, `TO (1, 6)`
+- Named palette: `TO viridis`, `TO dark2`, `TO tableau10`
+
+### VIA (transform)
+
+Continuous transforms: `linear`, `log`, `log2`, `ln`, `exp10`, `exp2`, `exp`, `sqrt`, `square`, `asinh`, `pseudo_log`, `pseudo_log2`, `pseudo_ln`, `integer`
+
+Temporal transforms: `date`, `datetime`, `time` — automatically chosen for date/datetime/time columns.
+
+Discrete transforms: `string`, `bool`
+
+```ggsql
+SCALE x VIA date        -- treat x as temporal
+SCALE y VIA log         -- log transform
+SCALE size VIA square   -- scale by radius not area
+```
+
+### SETTING
+
+Continuous/binned scales:
+- `expand` — expansion factor, scalar or `(mult, add)`. Default `0.05`. Only for x/y.
+- `oob` — out-of-bounds: `'keep'` (default for x/y), `'censor'` (default for others), `'squish'`
+- `breaks` — integer count, array of values, or interval string for temporal (e.g. `'2 months'`, `'week'`)
+- `pretty` — boolean, default `true`. Use Wilkinson's algorithm for nice breaks.
+- `reverse` — boolean, default `false`. Reverse scale direction.
+
+Binned scales additionally:
+- `closed` — `'left'` (default) or `'right'`
+
+Discrete/ordinal scales:
+- `reverse` — boolean
+
+```ggsql
+SCALE x SETTING breaks => '2 months'
+SCALE y FROM (0, 100) SETTING oob => 'squish'
+SCALE BINNED x SETTING breaks => 10, pretty => false
+```
+
+### RENAMING
+
+Rename break labels. Direct renaming, wildcard formatting, or both (direct takes priority):
+
+```ggsql
+RENAMING 'Adelie' => 'Pygoscelis adeliae', 'adelie' => null  -- direct / suppress
+RENAMING * => '{} mm'                -- string interpolation
+RENAMING * => '{:Title}'             -- formatters: Title, UPPER, lower, time %B %Y, num %.1f
+```
+
+## FACET clause
+
+Split data into small multiples.
+
+```
+FACET <column> BY <column>
+  SETTING <param> => <value>, ...
+```
+
+- 1D: `FACET region` — wrap layout, aesthetic name is `panel`
+- 2D: `FACET region BY category` — grid layout, aesthetics are `row` and `column`
+
+### Settings
+
+- `free` — `null` (default/fixed), `'x'`, `'y'`, or `('x', 'y')` for independent scales
+- `missing` — `'repeat'` (default, show layer in all panels) or `'null'` (only show in null panel)
+- `ncol`/`nrow` — layout dimensions for 1D faceting (only one allowed)
+
+### Customizing strip labels
+
+Use SCALE on the facet aesthetic:
+```ggsql
+FACET region
+SCALE panel
+  RENAMING 'N' => 'North', 'S' => 'South'
+```
+
+### Filtering panels
+
+Use SCALE FROM to select which panels to show:
+```ggsql
+FACET island
+SCALE panel FROM ('Biscoe', 'Dream')
+```
+
+## PROJECT clause
+
+Controls the coordinate system.
+
+```
+PROJECT <aesthetic>, ... TO <coord-type>
+  SETTING <param> => <value>, ...
+```
+
+### Coordinate types
+
+**cartesian** (default) — horizontal x, vertical y
+- Settings: `clip` (boolean, default true), `ratio` (aspect ratio number or null)
+- Default aesthetics: `x`, `y`
+
+**polar** — angle + radius from center
+- Settings: `clip`, `start` (degrees, default 0 = 12 o'clock), `end` (degrees, default start+360), `inner` (0-1 proportion for donut hole, default 0)
+- Default aesthetics: `radius` (primary), `angle` (secondary)
+
+Swap aesthetic order to flip axes: `PROJECT y, x TO cartesian`. If no PROJECT clause, coordinate type is inferred from mappings (x/y = cartesian, radius/angle = polar).
+
+```ggsql
+PROJECT TO polar SETTING inner => 0.5  -- donut chart
+PROJECT TO polar SETTING start => -90, end => 90  -- half-circle gauge
+```
+
+## LABEL clause
+
+Override default axis/legend labels and add titles.
+
+```
+LABEL
+  <aesthetic/title> => <string>, ...
+```
+
+Available labels:
+- `title` — main title
+- `subtitle` — subtitle below title
+- `caption` — text below the plot
+- Any aesthetic name — axis/legend title: `x`, `y`, `fill`, `color`, etc.
+- Use `null` to suppress a label: `fill => null`
+
+```ggsql
+LABEL
+  title => 'Sales by Region',
+  subtitle => 'Q4 2024 data',
+  x => 'Date',
+  y => 'Revenue (USD)',
+  fill => 'Region',
+  caption => 'Source: internal sales database'
+```
+
+---
+
+## Layer types
+
+### point
+Scatterplot. Required: x, y. Optional: size, colour, stroke, fill, opacity, shape.
+
+### line
+Line plot sorted along primary axis. Required: x, y. Optional: colour/stroke, opacity, linewidth, linetype. Settings: `position`, `orientation` (`'aligned'`/`'transposed'`).
+
+### path
+Like line but connects points in data order (not sorted). Same aesthetics as line.
+
+### bar
+Bar chart. Auto-counts if y not provided. Optional: x (categories), y (height), fill, colour, stroke. Stats: `count`, `proportion`. Properties: `weight`. Settings: `position` (default `'stack'`), `width` (0-1). Orientation inferred from mapping (categories on x = vertical, on y = horizontal).
+
+```ggsql
+DRAW bar MAPPING species AS x                              -- auto-count
+DRAW bar MAPPING species AS x, total AS y                  -- pre-computed
+DRAW bar MAPPING species AS x, sex AS fill                 -- stacked (default)
+  SETTING position => 'dodge'                              -- side by side
+```
+
+### histogram
+Bins continuous data. Required: x. Stats: `count`, `density`. Default remapping: `count AS <secondary>`. Settings: `position` (default `'stack'`), `bins` (default 30), `binwidth`, `closed` (`'left'`/`'right'`).
+
+```ggsql
+DRAW histogram MAPPING body_mass AS x SETTING binwidth => 100
+DRAW histogram MAPPING body_mass AS x REMAPPING density AS y  -- density instead of count
+```
+
+### density
+Kernel density estimation. Required: x. Stats: `density`, `intensity`. Settings: `position` (default `'identity'`), `bandwidth`, `adjust` (default 1), `kernel` (`'gaussian'` default, `'epanechnikov'`, `'triangular'`, `'rectangular'`, `'biweight'`, `'cosine'`).
+
+### boxplot
+Five-number summary with outliers. Required: x (categorical), y (continuous). Stats: `type`, `value`. Settings: `position` (default `'dodge'`), `outliers` (default true), `coef` (whisker IQR multiple, default 1.5), `width` (default 0.9).
+
+### violin
+Mirrored kernel density for groups. Required: x (categorical), y (continuous). Stats: `density`, `intensity`. Default remapping: `density AS offset`. Settings: `position` (default `'dodge'`), `bandwidth`, `adjust`, `kernel` (same as density), `width` (default 0.9), `side` (`'both'`/`'left'`/`'bottom'`/`'right'`/`'top'`), `tails` (number or null, default 3).
+
+### smooth
+Trendline. Required: x, y. Stats: `intensity`. Settings: `method` (`'nw'` default, `'ols'`, `'tls'`), `bandwidth`, `adjust`, `kernel` (same as density, nw only).
+
+### area
+Area chart anchored at zero. Required: x, y. Settings: `position` (default `'stack'`), `orientation`, `total` (normalize stacks), `center` (boolean, for steamgraph).
+
+### ribbon
+Like area but with explicit ymin/ymax (unanchored). Required: x, ymin, ymax.
+
+### segment
+Line segments between two endpoints. Required: x, y, and at least one of xend or yend.
+
+### rule
+Reference lines spanning the full panel. Required: x or y. Optional: `slope` (for diagonal: `y = a + slope * x`).
+
+### text
+Text labels. Required: x, y, label. Settings: `offset` (number or `(h, v)`), `format` (string interpolation like RENAMING). `hjust`: `'left'`/`'right'`/`'centre'` or 0-1. `vjust`: `'top'`/`'bottom'`/`'middle'` or 0-1.
+
+### rect
+Rectangles. Required: pick 2 per axis from center (x/y), min (xmin/ymin), max (xmax/ymax), width, height. Or just center (defaults width/height to 1).
+
+### polygon
+Closed shapes from ordered coordinates. Required: x, y. Use PARTITION BY to separate distinct polygons.
+
+### errorbar
+Interval display. Required: x, ymin, ymax. Settings: `width` (hinge width in points, default 10, null to hide).
+
+All layers accept common optional aesthetics (colour/stroke, fill, opacity, linewidth, linetype) and `position` setting where applicable.
+
+---
+
+## Named color palettes
+
+- **Discrete**: `ggsql10` (default), `tableau10`, `category10`, `set1`, `set2`, `set3`, `dark2`, `paired`, `pastel1`, `pastel2`, `accent`, `kelly22`
+- **Sequential**: `sequential` (default), `viridis`, `plasma`, `magma`, `inferno`, `cividis`, `blues`, `greens`, `oranges`, `reds`, `purples`, `greys`, `ylgnbu`, `ylorbr`, `ylorrd`, `batlow`, `hawaii`, `lajolla`, `turku`, and more
+- **Diverging**: `vik`/`diverging`, `rdbu`, `rdylbu`, `rdylgn`, `spectral`, `brbg`, `prgn`, `piyg`, `puor`, `berlin`, `roma`, and more
+- **Cyclic**: `romao`/`cyclic`, `bamo`, `broco`, `corko`, `viko`
+
+---
+
+## Common patterns
+
+```ggsql
+-- Pie chart
+VISUALISE species AS fill FROM ggsql:penguins
+DRAW bar
+PROJECT TO polar
+
+-- Horizontal bar chart
+DRAW bar MAPPING species AS y
+
+-- Multi-series line chart
+VISUALISE Date AS x
+DRAW line MAPPING Temp AS y, 'Temperature' AS color
+DRAW line MAPPING Ozone AS y, 'Ozone' AS color
+SCALE x VIA date
+
+-- Lollipop chart
+SELECT ROUND(bill_dep) AS bill_dep, COUNT(*) AS n FROM ggsql:penguins GROUP BY 1
+VISUALISE bill_dep AS x, n AS y
+DRAW segment MAPPING 0 AS yend
+DRAW point
+
+-- Ridgeline / joy plot
+VISUALISE Temp AS x, Month AS y FROM ggsql:airquality
+DRAW violin SETTING width => 4, side => 'top'
+SCALE ORDINAL y
+
+-- Bar labels
+SELECT island, COUNT(*) AS n FROM ggsql:penguins GROUP BY island
+VISUALISE island AS x, n AS y
+DRAW bar
+DRAW text MAPPING n AS label SETTING vjust => 'top', offset => (0, -11), fill => 'white'
+
+-- CTEs with separate layer data
+WITH temps AS (SELECT Date, Temp as value FROM ggsql:airquality),
+ozone AS (SELECT Date, Ozone as value FROM ggsql:airquality WHERE Ozone IS NOT NULL)
+VISUALISE
+DRAW line MAPPING Date AS x, value AS y, 'Temperature' AS color FROM temps
+DRAW point MAPPING Date AS x, value AS y, 'Ozone' AS color FROM ozone
+SCALE x VIA date
+```
+
+---
+
+## CLI
+
+The `ggsql` CLI should be on the PATH. Subcommands: `exec <QUERY>`, `run <FILE>`, `validate <QUERY>`, `parse <QUERY>`. Common options: `--reader <URI>` (default `duckdb://memory`), `--writer <FORMAT>` (default `vegalite`), `--output <PATH>`, `-v` (verbose).
+
+```bash
+ggsql validate "VISUALISE x, y FROM data DRAW point"
+ggsql exec "VISUALISE bill_len AS x, bill_dep AS y FROM ggsql:penguins DRAW point" -v
+ggsql run query.sql --output chart.vl.json
+```
+
+---
+
+## Additional References
+
+* https://ggsql.org/syntax/index.llms.md — Online documentation with the latest syntax
+
+---
+
+## Instructions for responding
+
+1. Write a complete, valid ggsql query matching the user's request.
+2. Use SQL CTEs/queries before VISUALISE when data shaping is needed.
+3. Choose the simplest layer types and settings that achieve the goal.
+4. Include SCALE clauses when the defaults are insufficient (e.g. date formatting, custom palettes, range limits).
+5. Include LABEL for titles when the context warrants it.
+6. Briefly explain your choices after the query.
+7. NEVER invent syntax, settings, aesthetics, layer types, or palette names not documented above.
+8. If unsure whether a feature exists, say so rather than guessing.
+9. Use `ggsql:penguins` or `ggsql:airquality` as example data when no specific data is mentioned.
+10. When the user wants to validate a query, use `ggsql validate "<query>"`. When the user wants to see the output, use `ggsql exec "<query>" -v`.
diff --git a/src/Cargo.toml b/src/Cargo.toml
index 97ffaaa5..75623e9d 100644
--- a/src/Cargo.toml
+++ b/src/Cargo.toml
@@ -7,6 +7,7 @@ license.workspace = true
 repository.workspace = true
 homepage.workspace = true
 description.workspace = true
+build = "build.rs"
 
 [lib]
 name = "ggsql"
@@ -62,6 +63,13 @@ sprintf = "0.4"
 const_format.workspace = true
 uuid.workspace = true
 
+# Terminal markdown rendering for `ggsql docs`
+termimad = "0.31"
+
+[build-dependencies]
+regex.workspace = true
+ureq = "3"
+
 [dev-dependencies]
 jsonschema = "0.44"
 proptest.workspace = true
diff --git a/src/build.rs b/src/build.rs
new file mode 100644
index 00000000..94c72214
--- /dev/null
+++ b/src/build.rs
@@ -0,0 +1,380 @@
+use regex::Regex;
+use std::env;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+struct DocEntry {
+    category: Option<String>,
+    topic: String,
+    title: String,
+    body: String,
+}
+
+fn main() {
+    let manifest_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap());
+    let doc_dir = manifest_dir.parent().unwrap().join("doc");
+    let syntax_dir = doc_dir.join("syntax");
+    let quarto_yml = doc_dir.join("_quarto.yml");
+    let skill_cache = doc_dir.join("vendor").join("SKILL.md");
+
+    println!("cargo:rerun-if-changed={}", syntax_dir.display());
+    println!("cargo:rerun-if-changed={}", quarto_yml.display());
+    println!("cargo:rerun-if-changed={}", skill_cache.display());
+    println!("cargo:rerun-if-env-changed=GGSQL_SKIP_SKILL_FETCH");
+
+    let site_url = read_site_url(&quarto_yml)
+        .unwrap_or_else(|| "https://ggsql.org".to_string())
+        .trim_end_matches('/')
+        .to_string();
+
+    let mut entries: Vec<DocEntry> = Vec::new();
+
+    for qmd_path in walk_qmd(&syntax_dir) {
+        let rel = qmd_path.strip_prefix(&syntax_dir).unwrap().to_path_buf();
+        let parts: Vec<String> = rel
+            .iter()
+            .map(|c| c.to_string_lossy().into_owned())
+            .collect();
+
+        if parts.is_empty() {
+            continue;
+        }
+        let filename = parts.last().unwrap();
+        if filename == "index.qmd" {
+            continue;
+        }
+        let Some(stem) = filename.strip_suffix(".qmd") else {
+            continue;
+        };
+
+        let Some((category, topic)) = classify(&parts, stem) else {
+            continue;
+        };
+
+        let content = fs::read_to_string(&qmd_path)
+            .unwrap_or_else(|e| panic!("failed to read {}: {}", qmd_path.display(), e));
+        let (title, body) = split_frontmatter(&content, stem);
+
+        let file_dir_rel = match rel.parent() {
+            Some(p) if p.as_os_str().is_empty() => "syntax".to_string(),
+            Some(p) => format!(
+                "syntax/{}",
+                p.to_string_lossy().replace(std::path::MAIN_SEPARATOR, "/")
+            ),
+            None => "syntax".to_string(),
+        };
+
+        let body = normalize(&body, &site_url, &file_dir_rel);
+
+        entries.push(DocEntry {
+            category,
+            topic,
+            title,
+            body,
+        });
+    }
+
+    entries.sort_by(|a, b| {
+        let ac = a.category.as_deref().unwrap_or("");
+        let bc = b.category.as_deref().unwrap_or("");
+        ac.cmp(bc).then(a.topic.cmp(&b.topic))
+    });
+
+    let skill = load_skill(&skill_cache);
+
+    let out_dir = PathBuf::from(env::var("OUT_DIR").unwrap());
+    let out_path = out_dir.join("docs_data.rs");
+    let mut out = String::new();
+    out.push_str("pub struct DocEntry {\n");
+    out.push_str("    pub category: Option<&'static str>,\n");
+    out.push_str("    pub topic: &'static str,\n");
+    out.push_str("    pub title: &'static str,\n");
+    out.push_str("    pub body: &'static str,\n");
+    out.push_str("}\n\n");
+    out.push_str("pub const DOCS: &[DocEntry] = &[\n");
+    for e in &entries {
+        out.push_str("    DocEntry {\n");
+        match &e.category {
+            Some(c) => out.push_str(&format!("        category: Some({:?}),\n", c)),
+            None => out.push_str("        category: None,\n"),
+        }
+        out.push_str(&format!("        topic: {:?},\n", e.topic));
+        out.push_str(&format!("        title: {:?},\n", e.title));
+        out.push_str(&format!("        body: {:?},\n", e.body));
+        out.push_str("    },\n");
+    }
+    out.push_str("];\n\n");
+
+    out.push_str("pub struct SkillContent {\n");
+    out.push_str("    pub name: &'static str,\n");
+    out.push_str("    pub description: &'static str,\n");
+    out.push_str("    pub body: &'static str,\n");
+    out.push_str("    pub available: bool,\n");
+    out.push_str("}\n\n");
+    out.push_str("pub const SKILL: SkillContent = SkillContent {\n");
+    out.push_str(&format!("    name: {:?},\n", skill.name));
+    out.push_str(&format!("    description: {:?},\n", skill.description));
+    out.push_str(&format!("    body: {:?},\n", skill.body));
+    out.push_str(&format!("    available: {},\n", skill.available));
+    out.push_str("};\n");
+
+    fs::write(&out_path, out)
+        .unwrap_or_else(|e| panic!("failed to write {}: {}", out_path.display(), e));
+}
+
+struct SkillData {
+    name: String,
+    description: String,
+    body: String,
+    available: bool,
+}
+
+const SKILL_URL: &str =
+    "https://raw.githubusercontent.com/posit-dev/skills/main/ggsql/ggsql/SKILL.md";
+
+fn load_skill(cache_path: &Path) -> SkillData {
+    let fetched = if env::var("GGSQL_SKIP_SKILL_FETCH").is_ok() {
+        None
+    } else {
+        fetch_skill()
+    };
+
+    let raw = match fetched {
+        Some(body) => {
+            write_if_changed(cache_path, body.as_bytes());
+            body
+        }
+        None => match fs::read_to_string(cache_path) {
+            Ok(s) => s,
+            Err(_) => {
+                println!(
+                    "cargo:warning=SKILL.md not available (fetch failed and no cached copy at {}); `ggsql skill` will report unavailable.",
+                    cache_path.display()
+                );
+                return SkillData {
+                    name: "ggsql".to_string(),
+                    description: String::new(),
+                    body: String::new(),
+                    available: false,
+                };
+            }
+        },
+    };
+
+    parse_skill(&raw)
+}
+
+fn fetch_skill() -> Option<String> {
+    let config = ureq::Agent::config_builder()
+        .timeout_global(Some(std::time::Duration::from_secs(15)))
+        .build();
+    let agent: ureq::Agent = config.into();
+
+    match agent.get(SKILL_URL).call() {
+        Ok(resp) => match resp.into_body().read_to_string() {
+            Ok(body) => Some(body),
+            Err(e) => {
+                println!(
+                    "cargo:warning=Failed to read SKILL.md body from {}: {}",
+                    SKILL_URL, e
+                );
+                None
+            }
+        },
+        Err(e) => {
+            println!(
+                "cargo:warning=Failed to fetch SKILL.md from {}: {}",
+                SKILL_URL, e
+            );
+            None
+        }
+    }
+}
+
+fn parse_skill(raw: &str) -> SkillData {
+    let raw = raw.trim_start_matches('\u{FEFF}');
+    let (fm, body) = if let Some(rest) = raw.strip_prefix("---\n") {
+        match rest.find("\n---\n") {
+            Some(end) => (&rest[..end], &rest[end + 5..]),
+            None => ("", raw),
+        }
+    } else if let Some(rest) = raw.strip_prefix("---\r\n") {
+        match rest.find("\r\n---\r\n") {
+            Some(end) => (&rest[..end], &rest[end + 7..]),
+            None => ("", raw),
+        }
+    } else {
+        ("", raw)
+    };
+
+    let name = extract_yaml_scalar(fm, "name").unwrap_or_else(|| "ggsql".to_string());
+    let description = extract_yaml_scalar(fm, "description").unwrap_or_default();
+    let body = body.trim_start_matches(['\n', '\r']).to_string();
+    let available = !body.is_empty();
+
+    SkillData {
+        name,
+        description,
+        body,
+        available,
+    }
+}
+
+fn extract_yaml_scalar(frontmatter: &str, key: &str) -> Option<String> {
+    let prefix = format!("{}:", key);
+    for line in frontmatter.lines() {
+        let trimmed = line.trim_start();
+        if trimmed.starts_with(&prefix) {
+            let value = trimmed[prefix.len()..].trim();
+            let value = value.trim_matches('"').trim_matches('\'');
+            return Some(value.to_string());
+        }
+    }
+    None
+}
+
+fn write_if_changed(path: &Path, content: &[u8]) {
+    if let Ok(existing) = fs::read(path) {
+        if existing == content {
+            return;
+        }
+    }
+    if let Some(parent) = path.parent() {
+        let _ = fs::create_dir_all(parent);
+    }
+    if let Err(e) = fs::write(path, content) {
+        println!(
+            "cargo:warning=Failed to update skill cache at {}: {}",
+            path.display(),
+            e
+        );
+    }
+}
+
+fn walk_qmd(dir: &Path) -> Vec<PathBuf> {
+    let mut out = Vec::new();
+    if !dir.is_dir() {
+        return out;
+    }
+    for entry in fs::read_dir(dir).unwrap() {
+        let entry = entry.unwrap();
+        let path = entry.path();
+        if path.is_dir() {
+            out.extend(walk_qmd(&path));
+        } else if path.extension().is_some_and(|ext| ext == "qmd") {
+            out.push(path);
+        }
+    }
+    out
+}
+
+fn classify(parts: &[String], stem: &str) -> Option<(Option<String>, String)> {
+    match parts.len() {
+        2 => match parts[0].as_str() {
+            "clause" => Some((None, stem.to_string())),
+            "coord" => Some((Some("coord".to_string()), stem.to_string())),
+            _ => None,
+        },
+        3 => match (parts[0].as_str(), parts[1].as_str()) {
+            ("layer", "type") => Some((Some("layer".to_string()), stem.to_string())),
+            ("layer", "position") => Some((Some("position".to_string()), stem.to_string())),
+            ("scale", "type") => Some((Some("scale".to_string()), stem.to_string())),
+            ("scale", "aesthetic") => {
+                let topic = strip_ordering_prefix(stem);
+                Some((Some("aesthetic".to_string()), topic))
+            }
+            _ => None,
+        },
+        _ => None,
+    }
+}
+
+fn strip_ordering_prefix(stem: &str) -> String {
+    let Some(idx) = stem.find('_') else {
+        return stem.to_string();
+    };
+    let prefix = &stem[..idx];
+    if prefix.is_empty() {
+        return stem.to_string();
+    }
+    let is_digits = prefix.chars().all(|c| c.is_ascii_digit());
+    let is_single_letter = prefix.len() == 1 && prefix.chars().next().unwrap().is_ascii_uppercase();
+    if is_digits || is_single_letter {
+        stem[idx + 1..].to_string()
+    } else {
+        stem.to_string()
+    }
+}
+
+fn split_frontmatter(content: &str, fallback_title: &str) -> (String, String) {
+    let content = content.trim_start_matches('\u{FEFF}');
+    let (fm_body, rest) = if let Some(rest) = content.strip_prefix("---\n") {
+        if let Some(end) = rest.find("\n---\n") {
+            (&rest[..end], &rest[end + 5..])
+        } else if let Some(end) = rest.find("\n---\r\n") {
+            (&rest[..end], &rest[end + 6..])
+        } else {
+            return (fallback_title.to_string(), content.to_string());
+        }
+    } else if let Some(rest) = content.strip_prefix("---\r\n") {
+        if let Some(end) = rest.find("\r\n---\r\n") {
+            (&rest[..end], &rest[end + 7..])
+        } else {
+            return (fallback_title.to_string(), content.to_string());
+        }
+    } else {
+        return (fallback_title.to_string(), content.to_string());
+    };
+
+    let title = extract_title(fm_body).unwrap_or_else(|| fallback_title.to_string());
+    (title, rest.trim_start_matches(['\n', '\r']).to_string())
+}
+
+fn extract_title(frontmatter: &str) -> Option<String> {
+    for line in frontmatter.lines() {
+        let trimmed = line.trim();
+        if let Some(rest) = trimmed.strip_prefix("title:") {
+            let val = rest.trim();
+            let val = val.trim_matches('"').trim_matches('\'');
+            return Some(val.to_string());
+        }
+    }
+    None
+}
+
+fn normalize(body: &str, site_url: &str, file_dir_rel: &str) -> String {
+    let xref_re = Regex::new(r"\[([^\]]*)\]\(([^)]*?\.qmd)(?:#[^)]*)?\)").unwrap();
+    let body = xref_re.replace_all(body, "$1").to_string();
+
+    let fence_re = Regex::new(r"```\{ggsql\}").unwrap();
+    let body = fence_re.replace_all(&body, "```ggsql").to_string();
+
+    let img_re = Regex::new(r"!\[([^\]]*)\]\(([^)]+)\)(?:\{[^}]*\})?").unwrap();
+    let body = img_re
+        .replace_all(&body, |caps: &regex::Captures| {
+            let alt = &caps[1];
+            let url = &caps[2];
+            if url.starts_with("http://") || url.starts_with("https://") || url.starts_with('/') {
+                format!("![{}]({})", alt, url)
+            } else {
+                format!("![{}]({}/{}/{})", alt, site_url, file_dir_rel, url)
+            }
+        })
+        .to_string();
+
+    body
+}
+
+fn read_site_url(path: &Path) -> Option<String> {
+    let content = fs::read_to_string(path).ok()?;
+    for line in content.lines() {
+        let trimmed = line.trim();
+        if let Some(rest) = trimmed.strip_prefix("site-url:") {
+            let val = rest.trim().trim_matches('"').trim_matches('\'').to_string();
+            if !val.is_empty() {
+                return Some(val);
+            }
+        }
+    }
+    None
+}
diff --git a/src/cli.rs b/src/cli.rs
index 049d679e..1e3ff3cf 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -4,15 +4,20 @@ ggsql Command Line Interface
 Provides commands for executing ggsql queries with various data sources and output formats.
 */
 
-use clap::{Parser, Subcommand};
+use clap::{Parser, Subcommand, ValueEnum};
 use ggsql::reader::{Reader, Spec};
 use ggsql::validate::validate;
 use ggsql::{parser, VERSION};
+use std::io::IsTerminal;
 use std::path::PathBuf;
 
 #[cfg(feature = "vegalite")]
 use ggsql::writer::{VegaLiteWriter, Writer};
 
+mod docs {
+    include!(concat!(env!("OUT_DIR"), "/docs_data.rs"));
+}
+
 #[derive(Parser)]
 #[command(name = "ggsql")]
 #[command(about = "SQL extension for declarative data visualization")]
@@ -87,6 +92,44 @@ pub enum Commands {
         #[arg(long)]
         reader: Option<String>,
     },
+
+    /// Show documentation for ggsql syntax (clauses, layers, scales, aesthetics, coords)
+    ///
+    /// Run `ggsql docs` with no arguments for an index of available topics.
+    /// Clauses are looked up by name directly (e.g. `ggsql docs draw`).
+    /// Other topics take a category first (e.g. `ggsql docs layer point`,
+    /// `ggsql docs position stack`, `ggsql docs scale continuous`,
+    /// `ggsql docs aesthetic color`, `ggsql docs coord cartesian`).
+    Docs {
+        /// Clause name (e.g. "draw") or category (e.g. "layer", "scale")
+        first: Option<String>,
+
+        /// Topic within the category (e.g. "point" when first is "layer")
+        second: Option<String>,
+
+        /// Output format. Defaults to rendered text on a TTY, raw markdown when piped.
+        #[arg(long, value_enum)]
+        format: Option<DocsFormat>,
+    },
+
+    /// Show the ggsql skill — a usage guide intended for AI assistants and humans
+    ///
+    /// The content is synced from https://github.com/posit-dev/skills at build time.
+    Skill {
+        /// Output format. Defaults to rendered text on a TTY, raw markdown when piped.
+        #[arg(long, value_enum)]
+        format: Option<DocsFormat>,
+    },
+}
+
+#[derive(ValueEnum, Clone, Copy, Debug, PartialEq, Eq)]
+pub enum DocsFormat {
+    /// Markdown rendered to ANSI for terminal display
+    Text,
+    /// Raw markdown (ideal for piping or for agents)
+    Markdown,
+    /// Structured JSON with metadata and body
+    Json,
 }
 
 fn main() -> anyhow::Result<()> {
@@ -126,6 +169,18 @@ fn main() -> anyhow::Result<()> {
         Commands::Validate { query, reader } => {
             cmd_validate(query, reader);
         }
+
+        Commands::Docs {
+            first,
+            second,
+            format,
+        } => {
+            cmd_docs(first, second, format);
+        }
+
+        Commands::Skill { format } => {
+            cmd_skill(format);
+        }
     }
 
     Ok(())
@@ -430,3 +485,223 @@ fn print_table_fallback<R: Reader>(query: &str, reader: &R, max_rows: usize) {
     let output = rows.join("\n");
     println!("{}", output);
 }
+
+fn cmd_docs(first: Option<String>, second: Option<String>, format: Option<DocsFormat>) {
+    let fmt = format.unwrap_or_else(|| {
+        if std::io::stdout().is_terminal() {
+            DocsFormat::Text
+        } else {
+            DocsFormat::Markdown
+        }
+    });
+
+    match (first.as_deref(), second.as_deref()) {
+        (None, _) => print_docs_index(fmt),
+        (Some(arg), None) => {
+            let arg_lc = arg.to_lowercase();
+            if let Some(entry) = find_doc(None, &arg_lc) {
+                render_doc(entry, fmt);
+                return;
+            }
+            if is_category(&arg_lc) {
+                print_category_listing(&arg_lc, fmt);
+                return;
+            }
+            eprintln!("Unknown topic: {}", arg);
+            eprintln!();
+            print_docs_index_to(&mut std::io::stderr(), DocsFormat::Markdown);
+            std::process::exit(1);
+        }
+        (Some(cat), Some(topic)) => {
+            let cat_lc = cat.to_lowercase();
+            let topic_lc = topic.to_lowercase();
+            if let Some(entry) = find_doc(Some(&cat_lc), &topic_lc) {
+                render_doc(entry, fmt);
+            } else {
+                eprintln!("Unknown topic: {} {}", cat, topic);
+                eprintln!();
+                print_category_listing_to(&mut std::io::stderr(), &cat_lc, DocsFormat::Markdown);
+                std::process::exit(1);
+            }
+        }
+    }
+}
+
+const CATEGORY_ORDER: &[(&str, &str)] = &[
+    ("layer", "Layer types"),
+    ("position", "Position adjustments"),
+    ("scale", "Scale types"),
+    ("aesthetic", "Aesthetics"),
+    ("coord", "Coordinate systems"),
+];
+
+fn is_category(name: &str) -> bool {
+    CATEGORY_ORDER.iter().any(|(cat, _)| *cat == name)
+}
+
+fn find_doc(category: Option<&str>, topic: &str) -> Option<&'static docs::DocEntry> {
+    docs::DOCS.iter().find(|e| {
+        e.category == category && e.topic.eq_ignore_ascii_case(topic)
+    })
+}
+
+fn topics_in(category: Option<&str>) -> Vec<&'static str> {
+    docs::DOCS
+        .iter()
+        .filter(|e| e.category == category)
+        .map(|e| e.topic)
+        .collect()
+}
+
+fn render_doc(entry: &docs::DocEntry, fmt: DocsFormat) {
+    match fmt {
+        DocsFormat::Text => {
+            let skin = termimad::MadSkin::default();
+            skin.print_text(entry.body);
+        }
+        DocsFormat::Markdown => {
+            print!("{}", entry.body);
+            if !entry.body.ends_with('\n') {
+                println!();
+            }
+        }
+        DocsFormat::Json => {
+            let obj = serde_json::json!({
+                "category": entry.category,
+                "topic": entry.topic,
+                "title": entry.title,
+                "body": entry.body,
+            });
+            match serde_json::to_string_pretty(&obj) {
+                Ok(s) => println!("{}", s),
+                Err(e) => {
+                    eprintln!("Failed to serialize docs entry: {}", e);
+                    std::process::exit(1);
+                }
+            }
+        }
+    }
+}
+
+fn print_docs_index(fmt: DocsFormat) {
+    let mut stdout = std::io::stdout();
+    print_docs_index_to(&mut stdout, fmt);
+}
+
+fn print_docs_index_to<W: std::io::Write>(out: &mut W, fmt: DocsFormat) {
+    if fmt == DocsFormat::Json {
+        let mut sections = serde_json::Map::new();
+        let clauses = topics_in(None);
+        sections.insert("clauses".to_string(), serde_json::json!(clauses));
+        for (cat, _) in CATEGORY_ORDER {
+            sections.insert((*cat).to_string(), serde_json::json!(topics_in(Some(cat))));
+        }
+        let _ = writeln!(
+            out,
+            "{}",
+            serde_json::to_string_pretty(&serde_json::Value::Object(sections)).unwrap()
+        );
+        return;
+    }
+
+    let clauses = topics_in(None);
+    let _ = writeln!(out, "ggsql syntax reference");
+    let _ = writeln!(out);
+    let _ = writeln!(
+        out,
+        "Clauses         ggsql docs <name>"
+    );
+    let _ = writeln!(out, "                {}", clauses.join(", "));
+    let _ = writeln!(out);
+    for (cat, label) in CATEGORY_ORDER {
+        let topics = topics_in(Some(cat));
+        if topics.is_empty() {
+            continue;
+        }
+        let _ = writeln!(
+            out,
+            "{:<15} ggsql docs {} <name>",
+            label, cat
+        );
+        let _ = writeln!(out, "                {}", topics.join(", "));
+        let _ = writeln!(out);
+    }
+    let _ = writeln!(
+        out,
+        "Use `--format markdown` for raw markdown or `--format json` for structured output."
+    );
+}
+
+fn print_category_listing(category: &str, fmt: DocsFormat) {
+    let mut stdout = std::io::stdout();
+    print_category_listing_to(&mut stdout, category, fmt);
+}
+
+fn print_category_listing_to<W: std::io::Write>(out: &mut W, category: &str, fmt: DocsFormat) {
+    let topics = topics_in(Some(category));
+    if fmt == DocsFormat::Json {
+        let _ = writeln!(
+            out,
+            "{}",
+            serde_json::json!({ "category": category, "topics": topics })
+        );
+        return;
+    }
+    if topics.is_empty() {
+        let _ = writeln!(out, "No topics in category `{}`.", category);
+        return;
+    }
+    let label = CATEGORY_ORDER
+        .iter()
+        .find(|(c, _)| *c == category)
+        .map(|(_, l)| *l)
+        .unwrap_or(category);
+    let _ = writeln!(out, "{} — ggsql docs {} <name>", label, category);
+    for topic in &topics {
+        let _ = writeln!(out, "  {}", topic);
+    }
+}
+
+fn cmd_skill(format: Option<DocsFormat>) {
+    if !docs::SKILL.available {
+        eprintln!(
+            "The ggsql skill is not available in this build (network fetch failed and no cached copy was present at build time)."
+        );
+        std::process::exit(1);
+    }
+
+    let fmt = format.unwrap_or_else(|| {
+        if std::io::stdout().is_terminal() {
+            DocsFormat::Text
+        } else {
+            DocsFormat::Markdown
+        }
+    });
+
+    match fmt {
+        DocsFormat::Text => {
+            let skin = termimad::MadSkin::default();
+            skin.print_text(docs::SKILL.body);
+        }
+        DocsFormat::Markdown => {
+            print!("{}", docs::SKILL.body);
+            if !docs::SKILL.body.ends_with('\n') {
+                println!();
+            }
+        }
+        DocsFormat::Json => {
+            let obj = serde_json::json!({
+                "name": docs::SKILL.name,
+                "description": docs::SKILL.description,
+                "body": docs::SKILL.body,
+            });
+            match serde_json::to_string_pretty(&obj) {
+                Ok(s) => println!("{}", s),
+                Err(e) => {
+                    eprintln!("Failed to serialize skill: {}", e);
+                    std::process::exit(1);
+                }
+            }
+        }
+    }
+}

From ef3476ddd3c5b811aa0a16aab0006b59edd41d20 Mon Sep 17 00:00:00 2001
From: Thomas Lin Pedersen <thomasp85@gmail.com>
Date: Thu, 23 Apr 2026 13:37:49 +0200
Subject: [PATCH 2/5] show images as pure links

---
 src/cli.rs | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/src/cli.rs b/src/cli.rs
index 1e3ff3cf..201d30bb 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -553,11 +553,18 @@ fn topics_in(category: Option<&str>) -> Vec<&'static str> {
         .collect()
 }
 
+fn strip_images(markdown: &str) -> String {
+    use std::sync::OnceLock;
+    static IMG_RE: OnceLock<regex::Regex> = OnceLock::new();
+    let re = IMG_RE.get_or_init(|| regex::Regex::new(r"!\[[^\]]*\]\(([^)]*)\)").unwrap());
+    re.replace_all(markdown, "$1").to_string()
+}
+
 fn render_doc(entry: &docs::DocEntry, fmt: DocsFormat) {
     match fmt {
         DocsFormat::Text => {
             let skin = termimad::MadSkin::default();
-            skin.print_text(entry.body);
+            skin.print_text(&strip_images(entry.body));
         }
         DocsFormat::Markdown => {
             print!("{}", entry.body);
@@ -681,7 +688,7 @@ fn cmd_skill(format: Option<DocsFormat>) {
     match fmt {
         DocsFormat::Text => {
             let skin = termimad::MadSkin::default();
-            skin.print_text(docs::SKILL.body);
+            skin.print_text(&strip_images(docs::SKILL.body));
         }
         DocsFormat::Markdown => {
             print!("{}", docs::SKILL.body);

From ff5d5bbc251c65382d05c5399a3695e6ec334fcb Mon Sep 17 00:00:00 2001
From: Thomas Lin Pedersen <thomasp85@gmail.com>
Date: Thu, 23 Apr 2026 17:47:05 +0200
Subject: [PATCH 3/5] update changelog

---
 CHANGELOG.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2fd15e31..5d22733b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,8 @@
 ### Added
 
 - ODBC is now turned on for the CLI as well (#344)
+- CLI now has built-in documentation through the `docs` command as well as a
+skill for llms through the `skill` command (#361)
 
 ### Fixed
 

From 858533eee50fb8d18ae60e6bd1c313b50f6abe41 Mon Sep 17 00:00:00 2001
From: Thomas Lin Pedersen <thomasp85@gmail.com>
Date: Thu, 23 Apr 2026 17:47:23 +0200
Subject: [PATCH 4/5] reformat

---
 src/cli.rs | 17 +++++------------
 1 file changed, 5 insertions(+), 12 deletions(-)

diff --git a/src/cli.rs b/src/cli.rs
index c442f4f3..f6348d8a 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -537,9 +537,9 @@ fn is_category(name: &str) -> bool {
 }
 
 fn find_doc(category: Option<&str>, topic: &str) -> Option<&'static docs::DocEntry> {
-    docs::DOCS.iter().find(|e| {
-        e.category == category && e.topic.eq_ignore_ascii_case(topic)
-    })
+    docs::DOCS
+        .iter()
+        .find(|e| e.category == category && e.topic.eq_ignore_ascii_case(topic))
 }
 
 fn topics_in(category: Option<&str>) -> Vec<&'static str> {
@@ -611,10 +611,7 @@ fn print_docs_index_to<W: std::io::Write>(out: &mut W, fmt: DocsFormat) {
     let clauses = topics_in(None);
     let _ = writeln!(out, "ggsql syntax reference");
     let _ = writeln!(out);
-    let _ = writeln!(
-        out,
-        "Clauses         ggsql docs <name>"
-    );
+    let _ = writeln!(out, "Clauses         ggsql docs <name>");
     let _ = writeln!(out, "                {}", clauses.join(", "));
     let _ = writeln!(out);
     for (cat, label) in CATEGORY_ORDER {
@@ -622,11 +619,7 @@ fn print_docs_index_to<W: std::io::Write>(out: &mut W, fmt: DocsFormat) {
         if topics.is_empty() {
             continue;
         }
-        let _ = writeln!(
-            out,
-            "{:<15} ggsql docs {} <name>",
-            label, cat
-        );
+        let _ = writeln!(out, "{:<15} ggsql docs {} <name>", label, cat);
         let _ = writeln!(out, "                {}", topics.join(", "));
         let _ = writeln!(out);
     }

From 4038b541c958a3de08a962029a5e9db551d5b975 Mon Sep 17 00:00:00 2001
From: Thomas Lin Pedersen <thomasp85@gmail.com>
Date: Thu, 23 Apr 2026 23:09:44 +0200
Subject: [PATCH 5/5] fixed CI

---
 Cargo.lock     | 4 ++--
 src/Cargo.toml | 4 +++-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index c10073f1..76519327 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2351,9 +2351,9 @@ dependencies = [
 
 [[package]]
 name = "libc"
-version = "0.2.185"
+version = "0.2.186"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
 
 [[package]]
 name = "libduckdb-sys"
diff --git a/src/Cargo.toml b/src/Cargo.toml
index 71932850..30b893c5 100644
--- a/src/Cargo.toml
+++ b/src/Cargo.toml
@@ -58,7 +58,9 @@ sprintf = "0.4"
 const_format.workspace = true
 uuid.workspace = true
 
-# Terminal markdown rendering for `ggsql docs`
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+# Terminal markdown rendering for `ggsql docs` (native targets only;
+# crossterm 0.29 doesn't compile on wasm32)
 termimad = "0.31"
 
 [build-dependencies]