teunbrand · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
@@ -57,7 +57,7 @@ jobs:
       - name: Install Rust
         # Stable, not the MSRV — clippy reads `rust-version` from /Cargo.toml,
         # so running it here still guards the 1.86 floor. Why the default
-        # cannot be 1.86 itself: /CLAUDE.md, "Rust version (MSRV)".
+        # cannot be 1.86 itself: /AGENTS.md, "Rust version (MSRV)".
         uses: dtolnay/rust-toolchain@stable
         with:
           components: rustfmt, clippy
@@ -98,7 +98,7 @@ jobs:
         # MSRV silently rots. Keep the two flags: `--ignore-rust-version`
         # bypasses `parley`'s *declared* 1.88, and library-only keeps the
         # dev-dependency graph out of the check.
-        # Background: /CLAUDE.md, "Rust version (MSRV)".
+        # Background: /AGENTS.md, "Rust version (MSRV)".
         run: cargo +1.86 check --ignore-rust-version -p ggsql
 
       - name: Run tree-sitter tests
@@ -156,7 +156,7 @@ jobs:
     # The Python suite under ggsql-jupyter/tests/ that drives the kernel over
     # a real ZMQ connection — the one thing the Rust unit tests above cannot
     # reach (wire framing, HMAC signing, busy/idle ordering). See
-    # ggsql-jupyter/CLAUDE.md, "Testing".
+    # ggsql-jupyter/AGENTS.md, "Testing".
     runs-on: ubuntu-latest
     # continue-on-error until posit-dev/ggsql#556 (a heartbeat-socket panic
     # in the vendored zeromq crate, unrelated to this suite) is fixed: that
@@ -177,7 +177,7 @@ jobs:
       - name: Install tree-sitter-cli
         # parser.c is generated from grammar.js by the tree-sitter-ggsql
         # build script and is not committed, so this is needed on every
-        # fresh checkout — see /CLAUDE.md, "Building".
+        # fresh checkout — see /AGENTS.md, "Building".
         run: npm install -g tree-sitter-cli
 
       - name: Install Rust

diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml
@@ -41,7 +41,7 @@ jobs:
 
       - name: Install Rust
         # Stable. The 1.86 MSRV is checked by its own step in build.yaml
-        # rather than by pinning here; see /CLAUDE.md, "Rust version (MSRV)".
+        # rather than by pinning here; see /AGENTS.md, "Rust version (MSRV)".
         uses: dtolnay/rust-toolchain@stable
 
       - name: Caching

diff --git a/.github/workflows/release-packages.yml b/.github/workflows/release-packages.yml
@@ -527,7 +527,7 @@ jobs:
         run: npm install -g tree-sitter-cli
 
       - name: Install Rust toolchain
-        # Stable. wasm is exempt from the MSRV (see /CLAUDE.md, "Rust version
+        # Stable. wasm is exempt from the MSRV (see /AGENTS.md, "Rust version
         # (MSRV)"), and ggsql-wasm/rust-toolchain.toml selects stable anyway.
         uses: dtolnay/rust-toolchain@stable
 

diff --git a/.github/workflows/test-extension.yaml b/.github/workflows/test-extension.yaml
@@ -108,7 +108,7 @@ jobs:
       - name: Install Rust toolchain
         # Stable, matching every other job that builds a real binary — and the
         # kernel released to PyPI. The 1.86 MSRV covers the library only and is
-        # checked in build.yaml; see /CLAUDE.md, "Rust version (MSRV)".
+        # checked in build.yaml; see /AGENTS.md, "Rust version (MSRV)".
         uses: dtolnay/rust-toolchain@stable
 
       # Use publish.yaml's cargo cache with `save-if: false`.

diff --git a/.gitignore b/.gitignore
@@ -117,3 +117,6 @@ ggsql.Rcheck/
 
 # Superpowers SDD scratch (ledger, briefs, review packages)
 .superpowers/
+
+# Posit Assistant project config (per-user)
+.posit/
diff --git a/CLAUDE.md → AGENTS.md b/CLAUDE.md → AGENTS.md
@@ -13,21 +13,21 @@ The user-facing site is at <https://ggsql.org>. The README at [`README.md`](READ
 
 ## Authoritative docs
 
-**Anything about ggsql syntax or semantics belongs in [`doc/`](doc/), not in any CLAUDE.md file.** That includes clause behaviour (`VISUALISE`, `DRAW`, `PLACE`, `SCALE`, `FACET`, `PROJECT`, `LABEL`), layer types, scales, aesthetics, and coordinate systems. CLAUDE.md files describe the implementation around those features — they should link to `doc/syntax/` rather than restate.
+**Anything about ggsql syntax or semantics belongs in [`doc/`](doc/), not in any AGENTS.md file.** That includes clause behaviour (`VISUALISE`, `DRAW`, `PLACE`, `SCALE`, `FACET`, `PROJECT`, `LABEL`), layer types, scales, aesthetics, and coordinate systems. AGENTS.md files describe the implementation around those features — they should link to `doc/syntax/` rather than restate.
 
 **Writing ggsql queries:** when you need to author or modify a ggsql query, use the vendored skill at [`doc/vendor/SKILL.md`](doc/vendor/SKILL.md). It is the source of truth for the syntax Claude should produce; do not invent clauses, settings, aesthetics, or layer types beyond what it documents.
 
 ## Workspace layout
 
-| Folder | Role | Type | Per-folder CLAUDE.md |
+| Folder | Role | Type | Per-folder AGENTS.md |
 | --- | --- | --- | --- |
-| [`src/`](src/) | Core Rust library (crate `ggsql`) | Cargo workspace member | [`src/CLAUDE.md`](src/CLAUDE.md) |
-| [`ggsql-cli/`](ggsql-cli/) | `ggsql` command-line binary | Cargo workspace member | [`ggsql-cli/CLAUDE.md`](ggsql-cli/CLAUDE.md) |
-| [`tree-sitter-ggsql/`](tree-sitter-ggsql/) | Tree-sitter grammar + multi-language bindings | Cargo workspace member (also npm + PyPI) | [`tree-sitter-ggsql/CLAUDE.md`](tree-sitter-ggsql/CLAUDE.md) |
-| [`ggsql-jupyter/`](ggsql-jupyter/) | Jupyter kernel | Cargo workspace member (also PyPI via maturin) | [`ggsql-jupyter/CLAUDE.md`](ggsql-jupyter/CLAUDE.md) |
-| [`ggsql-wasm/`](ggsql-wasm/) | WebAssembly bindings + browser playground | Cargo workspace member | [`ggsql-wasm/CLAUDE.md`](ggsql-wasm/CLAUDE.md) |
-| [`ggsql-vscode/`](ggsql-vscode/) | VS Code / Positron extension | Standalone TypeScript / npm | [`ggsql-vscode/CLAUDE.md`](ggsql-vscode/CLAUDE.md) |
-| [`doc/`](doc/) | Quarto documentation site (ggsql.org) | Quarto project | [`doc/CLAUDE.md`](doc/CLAUDE.md) |
+| [`src/`](src/) | Core Rust library (crate `ggsql`) | Cargo workspace member | [`src/AGENTS.md`](src/AGENTS.md) |
+| [`ggsql-cli/`](ggsql-cli/) | `ggsql` command-line binary | Cargo workspace member | [`ggsql-cli/AGENTS.md`](ggsql-cli/AGENTS.md) |
+| [`tree-sitter-ggsql/`](tree-sitter-ggsql/) | Tree-sitter grammar + multi-language bindings | Cargo workspace member (also npm + PyPI) | [`tree-sitter-ggsql/AGENTS.md`](tree-sitter-ggsql/AGENTS.md) |
+| [`ggsql-jupyter/`](ggsql-jupyter/) | Jupyter kernel | Cargo workspace member (also PyPI via maturin) | [`ggsql-jupyter/AGENTS.md`](ggsql-jupyter/AGENTS.md) |
+| [`ggsql-wasm/`](ggsql-wasm/) | WebAssembly bindings + browser playground | Cargo workspace member | [`ggsql-wasm/AGENTS.md`](ggsql-wasm/AGENTS.md) |
+| [`ggsql-vscode/`](ggsql-vscode/) | VS Code / Positron extension | Standalone TypeScript / npm | [`ggsql-vscode/AGENTS.md`](ggsql-vscode/AGENTS.md) |
+| [`doc/`](doc/) | Quarto documentation site (ggsql.org) | Quarto project | [`doc/AGENTS.md`](doc/AGENTS.md) |
 
 The Cargo workspace (`/Cargo.toml`) has five members: `tree-sitter-ggsql`, `src`, `ggsql-cli`, `ggsql-jupyter`, `ggsql-wasm`. Default workspace members exclude `ggsql-wasm` (it needs the wasm32 target and is built separately).
 
@@ -44,7 +44,7 @@ ggsql query  ──►  parser  ──►  Plot AST  ──►  executor  ──
 - The executor ties the two together: SQL → DataFrame, AST resolved against actual schema, stats and scales applied per layer.
 - The writer renders the resolved `Spec` to an output format: Vega-Lite JSON (the default writer), SVG, PDF or a `.hep` plot document (all default features), or one of the four raster formats — PNG, JPEG, TIFF, WebP (non-default; they need a GPU adapter). Everything but Vega-Lite is implemented on top of the hephaestus renderer — a name that stays internal; users see the format names.
 
-For details — module layout, traits, where extension points live — see [`src/CLAUDE.md`](src/CLAUDE.md). For a specific renderer, [`src/writer/vegalite/CLAUDE.md`](src/writer/vegalite/CLAUDE.md) (Vega-Lite) or [`src/writer/hephaestus/CLAUDE.md`](src/writer/hephaestus/CLAUDE.md) (the other seven). For the AST types, [`src/plot/CLAUDE.md`](src/plot/CLAUDE.md).
+For details — module layout, traits, where extension points live — see [`src/AGENTS.md`](src/AGENTS.md). For a specific renderer, [`src/writer/vegalite/AGENTS.md`](src/writer/vegalite/AGENTS.md) (Vega-Lite) or [`src/writer/hephaestus/AGENTS.md`](src/writer/hephaestus/AGENTS.md) (the other seven). For the AST types, [`src/plot/AGENTS.md`](src/plot/AGENTS.md).
 
 ## Building
 
@@ -92,7 +92,7 @@ One thing is exempt from the 1.86 MSRV:
 
 ### Rendering plots on Linux
 
-`svg`, `pdf` and `hep` are **default features** and need no GPU adapter, no wgpu and — importantly — **no `libfontconfig1-dev`**: `src/Cargo.toml` names `fontique` directly to enable `fontconfig-dlopen`, so fontconfig is loaded at run time rather than linked at build time. That is what makes them safe to have on by default; see [`src/writer/hephaestus/CLAUDE.md`](src/writer/hephaestus/CLAUDE.md). The four raster writers (`png`, `jpeg`, `tiff`, `webp`) and `ggsql view` are **not** default and need an adapter at run time.
+`svg`, `pdf` and `hep` are **default features** and need no GPU adapter, no wgpu and — importantly — **no `libfontconfig1-dev`**: `src/Cargo.toml` names `fontique` directly to enable `fontconfig-dlopen`, so fontconfig is loaded at run time rather than linked at build time. That is what makes them safe to have on by default; see [`src/writer/hephaestus/AGENTS.md`](src/writer/hephaestus/AGENTS.md). The four raster writers (`png`, `jpeg`, `tiff`, `webp`) and `ggsql view` are **not** default and need an adapter at run time.
 
 Cross-platform installers (NSIS / MSI / DMG / Deb): see [`INSTALLERS.md`](INSTALLERS.md). Releases are tag-driven via `.github/workflows/`.
 
@@ -113,7 +113,7 @@ cd tree-sitter-ggsql && npm test
 cd ggsql-jupyter/tests && pip install -r requirements.txt && pytest
 ```
 
-Per-folder CLAUDE.md files cover component-specific test guidance.
+Per-folder AGENTS.md files cover component-specific test guidance.
 
 ## Coding style
 
@@ -125,14 +125,14 @@ Per-folder CLAUDE.md files cover component-specific test guidance.
 ## Where to ask which question
 
 - *What does clause/layer/scale X do?* → [`doc/syntax/`](doc/syntax/).
-- *How does the `ggsql` CLI work? Where do its subcommands live?* → [`ggsql-cli/CLAUDE.md`](ggsql-cli/CLAUDE.md).
-- *How does the parser work? How is a `Plot` built?* → [`src/CLAUDE.md`](src/CLAUDE.md), then `src/parser/`.
-- *How do I add a new geom / scale type / coord?* → [`src/plot/CLAUDE.md`](src/plot/CLAUDE.md).
-- *How does Vega-Lite output get assembled?* → [`src/writer/vegalite/CLAUDE.md`](src/writer/vegalite/CLAUDE.md).
-- *How do the raster, SVG, PDF and `.hep` writers work?* → [`src/writer/hephaestus/CLAUDE.md`](src/writer/hephaestus/CLAUDE.md), which also lists their known gaps.
-- *How does `ggsql view` show a plot in a window?* → [`ggsql-cli/CLAUDE.md`](ggsql-cli/CLAUDE.md), then `PlotViewer` in [`src/writer/hephaestus/window.rs`](src/writer/hephaestus/window.rs).
-- *How does a query become rendered output end-to-end?* → [`src/CLAUDE.md`](src/CLAUDE.md) (execution pipeline), then `src/execute/`.
-- *How does the Jupyter kernel route messages?* → [`ggsql-jupyter/CLAUDE.md`](ggsql-jupyter/CLAUDE.md).
-- *How does the VS Code / Positron extension talk to the kernel?* → [`ggsql-vscode/CLAUDE.md`](ggsql-vscode/CLAUDE.md).
-- *How is the wasm playground built and embedded into the docs?* → [`ggsql-wasm/CLAUDE.md`](ggsql-wasm/CLAUDE.md) and [`doc/CLAUDE.md`](doc/CLAUDE.md).
-- *How do I add new ggsql syntax?* → grammar in [`tree-sitter-ggsql/CLAUDE.md`](tree-sitter-ggsql/CLAUDE.md), then AST building in `src/parser/builder.rs` (covered in [`src/CLAUDE.md`](src/CLAUDE.md)), then docs in [`doc/CLAUDE.md`](doc/CLAUDE.md).
+- *How does the `ggsql` CLI work? Where do its subcommands live?* → [`ggsql-cli/AGENTS.md`](ggsql-cli/AGENTS.md).
+- *How does the parser work? How is a `Plot` built?* → [`src/AGENTS.md`](src/AGENTS.md), then `src/parser/`.
+- *How do I add a new geom / scale type / coord?* → [`src/plot/AGENTS.md`](src/plot/AGENTS.md).
+- *How does Vega-Lite output get assembled?* → [`src/writer/vegalite/AGENTS.md`](src/writer/vegalite/AGENTS.md).
+- *How do the raster, SVG, PDF and `.hep` writers work?* → [`src/writer/hephaestus/AGENTS.md`](src/writer/hephaestus/AGENTS.md), which also lists their known gaps.
+- *How does `ggsql view` show a plot in a window?* → [`ggsql-cli/AGENTS.md`](ggsql-cli/AGENTS.md), then `PlotViewer` in [`src/writer/hephaestus/window.rs`](src/writer/hephaestus/window.rs).
+- *How does a query become rendered output end-to-end?* → [`src/AGENTS.md`](src/AGENTS.md) (execution pipeline), then `src/execute/`.
+- *How does the Jupyter kernel route messages?* → [`ggsql-jupyter/AGENTS.md`](ggsql-jupyter/AGENTS.md).
+- *How does the VS Code / Positron extension talk to the kernel?* → [`ggsql-vscode/AGENTS.md`](ggsql-vscode/AGENTS.md).
+- *How is the wasm playground built and embedded into the docs?* → [`ggsql-wasm/AGENTS.md`](ggsql-wasm/AGENTS.md) and [`doc/AGENTS.md`](doc/AGENTS.md).
+- *How do I add new ggsql syntax?* → grammar in [`tree-sitter-ggsql/AGENTS.md`](tree-sitter-ggsql/AGENTS.md), then AST building in `src/parser/builder.rs` (covered in [`src/AGENTS.md`](src/AGENTS.md)), then docs in [`doc/AGENTS.md`](doc/AGENTS.md).
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@
   `Spec::layer_sql`/`Spec::stat_sql` were removed.
 - Scale resolution now detects and converts temporal-unit mismatches and errors
   on unrepresentable ranges instead of producing silently wrong scales (#569).
+- Replaced `CLAUDE.md` files with `AGENTS.md` files.
 
 ### Fixed
 

diff --git a/doc/CLAUDE.md → doc/AGENTS.md b/doc/CLAUDE.md → doc/AGENTS.md
@@ -1,6 +1,6 @@
 # `doc/` — Quarto documentation site
 
-Source for the public ggsql documentation at <https://ggsql.org>. **This directory is the authoritative reference for ggsql syntax and semantics.** Other CLAUDE.md files in the repo link here rather than restate.
+Source for the public ggsql documentation at <https://ggsql.org>. **This directory is the authoritative reference for ggsql syntax and semantics.** Other AGENTS.md files in the repo link here rather than restate.
 
 If you are about to document a clause, layer type, scale, or aesthetic anywhere else: stop and put it here instead.
 
@@ -67,14 +67,14 @@ quarto render      # full site build → _site/
 
 The site is published from the `gh-pages` branch (see `_quarto.yml`'s `repo-branch`). Quarto extensions live in `_extensions/`.
 
-## What goes here vs. CLAUDE.md
+## What goes here vs. AGENTS.md
 
 - **Here**: anything a ggsql user might want to read — clause syntax, layer types, scales, aesthetics, examples, CLI usage, installation.
-- **In CLAUDE.md files**: implementation details for contributors — module layouts, build pipelines, where to add a new geom, internal types.
+- **In AGENTS.md files**: implementation details for contributors — module layouts, build pipelines, where to add a new geom, internal types.
 
-If you find clause/layer/scale syntax described in any CLAUDE.md file, that is a duplication bug — move it here and link from there.
+If you find clause/layer/scale syntax described in any AGENTS.md file, that is a duplication bug — move it here and link from there.
 
 ## See also
 
-- [`/CLAUDE.md`](../CLAUDE.md) — workspace overview.
-- [`/ggsql-wasm/CLAUDE.md`](../ggsql-wasm/CLAUDE.md) — how the embedded playground at `wasm/` is built.
+- [`/AGENTS.md`](../AGENTS.md) — workspace overview.
+- [`/ggsql-wasm/AGENTS.md`](../ggsql-wasm/AGENTS.md) — how the embedded playground at `wasm/` is built.
diff --git a/ggsql-cli/CLAUDE.md → ggsql-cli/AGENTS.md b/ggsql-cli/CLAUDE.md → ggsql-cli/AGENTS.md
@@ -133,8 +133,8 @@ The report itself is plain HTML with a client-side filter and an *only problems*
 
 ## See also
 
-- [`/CLAUDE.md`](../CLAUDE.md) — workspace overview.
-- [`/src/writer/hephaestus/CLAUDE.md`](../src/writer/hephaestus/CLAUDE.md) — the PNG writer this harness is mostly used to check.
-- [`/src/CLAUDE.md`](../src/CLAUDE.md) — the underlying `ggsql` library.
+- [`/AGENTS.md`](../AGENTS.md) — workspace overview.
+- [`/src/writer/hephaestus/AGENTS.md`](../src/writer/hephaestus/AGENTS.md) — the PNG writer this harness is mostly used to check.
+- [`/src/AGENTS.md`](../src/AGENTS.md) — the underlying `ggsql` library.
 - [`/INSTALLERS.md`](../INSTALLERS.md) — cross-platform installer build (Windows/Linux from this crate's packager metadata; macOS via `pkgbuild`).
 - [`/doc/get_started/tooling.qmd`](../doc/get_started/tooling.qmd) — user-facing CLI docs.
diff --git a/ggsql-cli/Cargo.toml b/ggsql-cli/Cargo.toml
@@ -99,7 +99,7 @@ binaries = [
 ]
 
 # The default `svg`/`pdf`/`hep` writers lay text out through fontconfig, loaded
-# at run time (see /CLAUDE.md). Nothing is needed to *build* against it, but
+# at run time (see /AGENTS.md). Nothing is needed to *build* against it, but
 # without the runtime library and a font a plot renders with no labels at all
 # and no error, so the package declares both rather than degrading silently.
 [package.metadata.packager.deb]

diff --git a/ggsql-cli/examples/visual_test.rs b/ggsql-cli/examples/visual_test.rs
@@ -18,7 +18,7 @@ check wants; `svg` needs **no GPU adapter**, so it is the mode that runs on a
 headless box, and its `--baseline` comparison reads coordinates rather than
 pixels. The SVG writer also reports what it could not express, which is the
 regression signal
-[`writer/hephaestus/CLAUDE.md`](../../src/writer/hephaestus/CLAUDE.md) says
+[`writer/hephaestus/AGENTS.md`](../../src/writer/hephaestus/AGENTS.md) says
 should be empty for everything in this corpus.
 
 ```sh
@@ -31,7 +31,7 @@ report shows every problem in the corpus at once.
 
 Pass `--compare` to render each query with the Vega-Lite writer as well and show
 the two side by side — the comparison
-[`writer/hephaestus/CLAUDE.md`](../../src/writer/hephaestus/CLAUDE.md) calls for
+[`writer/hephaestus/AGENTS.md`](../../src/writer/hephaestus/AGENTS.md) calls for
 when checking visual correctness.
 */
 

diff --git a/ggsql-jupyter/CLAUDE.md → ggsql-jupyter/AGENTS.md b/ggsql-jupyter/CLAUDE.md → ggsql-jupyter/AGENTS.md
@@ -174,7 +174,7 @@ So `RenderHints::canvas` picks a height (golden ratio, close to ggplot2's defaul
 ## Positron-specific bits
 
 - `data_explorer.rs` implements Positron's data-explorer comm channel (registered query results become explorable tables).
-- The companion VS Code extension (`ggsql-vscode/`) ships a copy of this binary and also discovers installed ones via the `ggsql.kernelPath` setting, the Jupyter kernelspec directories, the native install locations, or `PATH`. It runs each one with `--version` to name the runtime it registers, so **keep `--version` working**: a kernel that does not answer it is still offered, but without a version in the picker. See [Finding the kernel](../ggsql-vscode/CLAUDE.md#finding-the-kernel).
+- The companion VS Code extension (`ggsql-vscode/`) ships a copy of this binary and also discovers installed ones via the `ggsql.kernelPath` setting, the Jupyter kernelspec directories, the native install locations, or `PATH`. It runs each one with `--version` to name the runtime it registers, so **keep `--version` working**: a kernel that does not answer it is still offered, but without a version in the picker. See [Finding the kernel](../ggsql-vscode/AGENTS.md#finding-the-kernel).
 
 ## Build & install
 
@@ -219,7 +219,7 @@ pytest
 
 ## See also
 
-- [`/CLAUDE.md`](../CLAUDE.md) — workspace overview.
-- [`/ggsql-vscode/CLAUDE.md`](../ggsql-vscode/CLAUDE.md) — the VS Code / Positron extension that drives this kernel.
-- [`/src/CLAUDE.md`](../src/CLAUDE.md) — the underlying `ggsql` library.
+- [`/AGENTS.md`](../AGENTS.md) — workspace overview.
+- [`/ggsql-vscode/AGENTS.md`](../ggsql-vscode/AGENTS.md) — the VS Code / Positron extension that drives this kernel.
+- [`/src/AGENTS.md`](../src/AGENTS.md) — the underlying `ggsql` library.
 - [`/doc/get_started/tooling.qmd`](../doc/get_started/tooling.qmd) — user-facing notebook docs.