From f5f8a42fa580a768ab5c18b4ea07d5dd5b490f43 Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Fri, 23 Oct 2026 13:46:53 +0200 Subject: [PATCH 1/4] rename CLAUDE.md to AGENTS.md --- CLAUDE.md => AGENTS.md | 46 +++++++++---------- doc/{CLAUDE.md => AGENTS.md} | 12 ++--- ggsql-cli/{CLAUDE.md => AGENTS.md} | 6 +-- ggsql-jupyter/{CLAUDE.md => AGENTS.md} | 8 ++-- ggsql-vscode/{CLAUDE.md => AGENTS.md} | 8 ++-- ggsql-wasm/{CLAUDE.md => AGENTS.md} | 6 +-- src/{CLAUDE.md => AGENTS.md} | 22 ++++----- src/plot/{CLAUDE.md => AGENTS.md} | 6 +-- .../hephaestus/{CLAUDE.md => AGENTS.md} | 12 ++--- src/writer/vegalite/{CLAUDE.md => AGENTS.md} | 0 tree-sitter-ggsql/{CLAUDE.md => AGENTS.md} | 4 +- 11 files changed, 65 insertions(+), 65 deletions(-) rename CLAUDE.md => AGENTS.md (81%) rename doc/{CLAUDE.md => AGENTS.md} (92%) rename ggsql-cli/{CLAUDE.md => AGENTS.md} (97%) rename ggsql-jupyter/{CLAUDE.md => AGENTS.md} (98%) rename ggsql-vscode/{CLAUDE.md => AGENTS.md} (99%) rename ggsql-wasm/{CLAUDE.md => AGENTS.md} (98%) rename src/{CLAUDE.md => AGENTS.md} (94%) rename src/plot/{CLAUDE.md => AGENTS.md} (96%) rename src/writer/hephaestus/{CLAUDE.md => AGENTS.md} (99%) rename src/writer/vegalite/{CLAUDE.md => AGENTS.md} (100%) rename tree-sitter-ggsql/{CLAUDE.md => AGENTS.md} (95%) diff --git a/CLAUDE.md b/AGENTS.md similarity index 81% rename from CLAUDE.md rename to AGENTS.md index a4d83652f..d69d7b202 100644 --- a/CLAUDE.md +++ b/AGENTS.md @@ -13,21 +13,21 @@ The user-facing site is at . 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/doc/CLAUDE.md b/doc/AGENTS.md similarity index 92% rename from doc/CLAUDE.md rename to doc/AGENTS.md index 2189821d8..ac894d69f 100644 --- a/doc/CLAUDE.md +++ b/doc/AGENTS.md @@ -1,6 +1,6 @@ # `doc/` — Quarto documentation site -Source for the public ggsql documentation at . **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 . **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 b/ggsql-cli/AGENTS.md similarity index 97% rename from ggsql-cli/CLAUDE.md rename to ggsql-cli/AGENTS.md index cf78d13b4..b4ac4da01 100644 --- a/ggsql-cli/CLAUDE.md +++ b/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-jupyter/CLAUDE.md b/ggsql-jupyter/AGENTS.md similarity index 98% rename from ggsql-jupyter/CLAUDE.md rename to ggsql-jupyter/AGENTS.md index c770aef65..4cde53c91 100644 --- a/ggsql-jupyter/CLAUDE.md +++ b/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. diff --git a/ggsql-vscode/CLAUDE.md b/ggsql-vscode/AGENTS.md similarity index 99% rename from ggsql-vscode/CLAUDE.md rename to ggsql-vscode/AGENTS.md index aca8e758f..5cd314e17 100644 --- a/ggsql-vscode/CLAUDE.md +++ b/ggsql-vscode/AGENTS.md @@ -99,7 +99,7 @@ The extension declares `contributes.languageRuntimes` for `ggsql` (see `package. - **`createKernelSpec` appends `--session-mode `** from `sessionMetadata.sessionMode`. The kernel keys every output decision off that: a console session gets the comm, a notebook session gets a static image in its cell, and background gets the standalone path. Without the flag the kernel falls back to guessing from its session id, which works but is a heuristic. `restoreSession` deliberately does *not* rebuild the spec — the supervisor replays the argv the session was created with, and a session's mode never changes. - **`uiSubscriptions: ['did_change_plots_render_settings']`** on the runtime metadata. Without it the frontend never tells the kernel how large the Plots pane is, and the kernel needs that for exactly one thing: rendering a *new* plot at the right size so its `comm_open` can carry it, and the pane shows it immediately instead of blank. Every other render carries its own size on the request. -Both live in `manager.ts`. The kernel side of the contract — why the comm alone creates the pane entry, and why an output bundle alongside it would show the plot twice — is in [`/ggsql-jupyter/CLAUDE.md`](../ggsql-jupyter/CLAUDE.md). +Both live in `manager.ts`. The kernel side of the contract — why the comm alone creates the pane entry, and why an output bundle alongside it would show the plot twice — is in [`/ggsql-jupyter/AGENTS.md`](../ggsql-jupyter/AGENTS.md). Outside Positron there is no way to execute a query: `activate()` returns early, so every command that runs code stays unregistered. To avoid offering actions that cannot work, everything execution-related gates on Positron's built-in **`isPositron`** context key ([extension development docs](https://positron.posit.co/extension-development.html#option-1-context-keys)): @@ -249,7 +249,7 @@ Assertion lines are stripped before tokenization, so they never tokenize as ggsq ## See also -- [`/CLAUDE.md`](../CLAUDE.md) — workspace overview. -- [`/ggsql-jupyter/CLAUDE.md`](../ggsql-jupyter/CLAUDE.md) — the kernel this extension drives. -- [`/tree-sitter-ggsql/CLAUDE.md`](../tree-sitter-ggsql/CLAUDE.md) — grammar that powers more advanced editor highlighting. +- [`/AGENTS.md`](../AGENTS.md) — workspace overview. +- [`/ggsql-jupyter/AGENTS.md`](../ggsql-jupyter/AGENTS.md) — the kernel this extension drives. +- [`/tree-sitter-ggsql/AGENTS.md`](../tree-sitter-ggsql/AGENTS.md) — grammar that powers more advanced editor highlighting. - [`/doc/get_started/tooling.qmd`](../doc/get_started/tooling.qmd) — user-facing tooling docs. diff --git a/ggsql-wasm/CLAUDE.md b/ggsql-wasm/AGENTS.md similarity index 98% rename from ggsql-wasm/CLAUDE.md rename to ggsql-wasm/AGENTS.md index 3a584f39a..b5b62e9d3 100644 --- a/ggsql-wasm/CLAUDE.md +++ b/ggsql-wasm/AGENTS.md @@ -195,6 +195,6 @@ package: a context built on the glue's own `init` has no converters, and ## See also -- [`/CLAUDE.md`](../CLAUDE.md) — workspace overview. -- [`/src/CLAUDE.md`](../src/CLAUDE.md) — the underlying `ggsql` library. -- [`/doc/CLAUDE.md`](../doc/CLAUDE.md) — docs and playground embedding. +- [`/AGENTS.md`](../AGENTS.md) — workspace overview. +- [`/src/AGENTS.md`](../src/AGENTS.md) — the underlying `ggsql` library. +- [`/doc/AGENTS.md`](../doc/AGENTS.md) — docs and playground embedding. diff --git a/src/CLAUDE.md b/src/AGENTS.md similarity index 94% rename from src/CLAUDE.md rename to src/AGENTS.md index 8fe6d0466..d1d912956 100644 --- a/src/CLAUDE.md +++ b/src/AGENTS.md @@ -2,7 +2,7 @@ The core library. Crate name: `ggsql`. Workspace member, declared in `/Cargo.toml`. The `ggsql` CLI binary lives separately in [`/ggsql-cli/`](../ggsql-cli/) and depends on this crate. -For ggsql language semantics, see [`/doc/syntax/`](../doc/syntax/). For Vega-Lite renderer internals, see [`writer/vegalite/CLAUDE.md`](writer/vegalite/CLAUDE.md). For AST types, see [`plot/CLAUDE.md`](plot/CLAUDE.md). +For ggsql language semantics, see [`/doc/syntax/`](../doc/syntax/). For Vega-Lite renderer internals, see [`writer/vegalite/AGENTS.md`](writer/vegalite/AGENTS.md). For AST types, see [`plot/AGENTS.md`](plot/AGENTS.md). ## Entry points @@ -22,10 +22,10 @@ src/ ├── fonts.rs Font registration, for hosts with no font database │ ├── parser/ Tree-sitter integration → typed AST (Plot) -├── plot/ AST: Plot, Layer, Geom, Scale, Facet, Projection, Mappings (see plot/CLAUDE.md) +├── plot/ AST: Plot, Layer, Geom, Scale, Facet, Projection, Mappings (see plot/AGENTS.md) ├── reader/ Reader trait + drivers (DuckDB, SQLite, ODBC, Snowflake, …) ├── execute/ Pipeline that turns Plot + Reader → executed Spec -├── writer/ Writer trait + Vega-Lite implementation (see writer/vegalite/CLAUDE.md) +├── writer/ Writer trait + Vega-Lite implementation (see writer/vegalite/AGENTS.md) ├── data/ Bundled sample datasets (penguins, airquality) └── doc/ API.md — public Rust API reference ``` @@ -73,8 +73,8 @@ The pipeline that takes a parsed `Plot` plus a `Reader` and produces a fully-res `Writer` trait in `mod.rs` (associated `Output` type so writers can return text or bytes, and `from_options` for configuration a frontend collects as key–value pairs — `options.rs`'s `WriterOptions`, parsed from the CLI's `--writer-option`). Two families: -- **Vega-Lite** (`vegalite` feature, default) — emits Vega-Lite JSON. Deep-dive: [`writer/vegalite/CLAUDE.md`](writer/vegalite/CLAUDE.md). -- **The renderer-backed writers** (seven of them; `svg`, `pdf` and `hep` default, the four raster ones not) — all live in `writer/hephaestus/`, named after the renderer they wrap; that name is internal, and the module is private so only the writers, `Canvas` and `RasterRenderer` are public. They share their whole pipeline — `Canvas` for configuration, `compose` for the plot composition, then either `raster` for pixels or `vector` for drawing commands — and differ only in what they do with the result. Deep-dive (architecture + known gaps): [`writer/hephaestus/CLAUDE.md`](writer/hephaestus/CLAUDE.md). +- **Vega-Lite** (`vegalite` feature, default) — emits Vega-Lite JSON. Deep-dive: [`writer/vegalite/AGENTS.md`](writer/vegalite/AGENTS.md). +- **The renderer-backed writers** (seven of them; `svg`, `pdf` and `hep` default, the four raster ones not) — all live in `writer/hephaestus/`, named after the renderer they wrap; that name is internal, and the module is private so only the writers, `Canvas` and `RasterRenderer` are public. They share their whole pipeline — `Canvas` for configuration, `compose` for the plot composition, then either `raster` for pixels or `vector` for drawing commands — and differ only in what they do with the result. Deep-dive (architecture + known gaps): [`writer/hephaestus/AGENTS.md`](writer/hephaestus/AGENTS.md). | Feature | Default | Writer | Output | GPU | | --- | --- | --- | --- | --- | @@ -84,7 +84,7 @@ The pipeline that takes a parsed `Plot` plus a `Reader` and produces a fully-res Plus `PlotViewer` behind the `window` feature — not a writer, since it returns no output, blocks, and must run on the main thread. It shows the same composition in a native window, re-laying-out on resize. - The three GPU-free writers go through the same composition and the same `render` call (which takes `&mut dyn SceneBuilder`), so they need no adapter and pull in no wgpu. **That is why they are default**: nothing about them has to be opted into, including on Linux, where `fontconfig-dlopen` removes the build-time `libfontconfig1-dev` requirement (see [`writer/hephaestus/CLAUDE.md`](writer/hephaestus/CLAUDE.md)). They also still compile on the CRAN MSRV — `cargo +1.86 check --ignore-rust-version -p ggsql`, where the flag is needed only because `parley` *declares* 1.88 while compiling fine on 1.86. Only the raster writers need an adapter and are genuinely 1.88+, and a raster dimension is capped at what the GPU grants, up to 16384 px. + The three GPU-free writers go through the same composition and the same `render` call (which takes `&mut dyn SceneBuilder`), so they need no adapter and pull in no wgpu. **That is why they are default**: nothing about them has to be opted into, including on Linux, where `fontconfig-dlopen` removes the build-time `libfontconfig1-dev` requirement (see [`writer/hephaestus/AGENTS.md`](writer/hephaestus/AGENTS.md)). They also still compile on the CRAN MSRV — `cargo +1.86 check --ignore-rust-version -p ggsql`, where the flag is needed only because `parley` *declares* 1.88 while compiling fine on 1.86. Only the raster writers need an adapter and are genuinely 1.88+, and a raster dimension is capped at what the GPU grants, up to 16384 px. Three **internal** features carry the split, enabled by the writer features rather than named directly: `graphics` is the shared composition layer, and `raster = graphics + hephaestus/vello-hybrid` adds the GPU rasteriser. Only `raster` pulls in wgpu, vello_hybrid and pollster, which is what lets a vector-only build skip them — `cargo tree --features graphics` shows none of the three, `--features png` shows 19. `raster-writer` then narrows `raster` once more, to "some writer actually reads pixels back" — the viewer needs the rasteriser without ever doing that. `graphics` is the single module gate for `writer/hephaestus/`, so adding a format needs no change there. @@ -102,7 +102,7 @@ registering nothing is a silent failure. ### `plot/` -Sufficiently large to have its own [`plot/CLAUDE.md`](plot/CLAUDE.md). It holds the AST types and the registries for geoms, scale types, transforms, positions, and coords. +Sufficiently large to have its own [`plot/AGENTS.md`](plot/AGENTS.md). It holds the AST types and the registries for geoms, scale types, transforms, positions, and coords. ### `doc/` @@ -175,10 +175,10 @@ The caching layer has its own equivalence suite, [`reader/cache_equivalence.rs`] ## See also -- [`/CLAUDE.md`](../CLAUDE.md) — workspace overview, build/test for everything. -- [`plot/CLAUDE.md`](plot/CLAUDE.md) — AST types. -- [`writer/vegalite/CLAUDE.md`](writer/vegalite/CLAUDE.md) — Vega-Lite renderer internals. +- [`/AGENTS.md`](../AGENTS.md) — workspace overview, build/test for everything. +- [`plot/AGENTS.md`](plot/AGENTS.md) — AST types. +- [`writer/vegalite/AGENTS.md`](writer/vegalite/AGENTS.md) — Vega-Lite renderer internals. - [`/doc/syntax/`](../doc/syntax/) — authoritative ggsql syntax reference. - [`doc/API.md`](doc/API.md) — Rust public API reference. -- [`/ggsql-cli/CLAUDE.md`](../ggsql-cli/CLAUDE.md) — the `ggsql` CLI binary that wraps this library. +- [`/ggsql-cli/AGENTS.md`](../ggsql-cli/AGENTS.md) — the `ggsql` CLI binary that wraps this library. - [`/INSTALLERS.md`](../INSTALLERS.md) — cross-platform installer build (driven from `ggsql-cli`). diff --git a/src/plot/CLAUDE.md b/src/plot/AGENTS.md similarity index 96% rename from src/plot/CLAUDE.md rename to src/plot/AGENTS.md index 3add30935..d17aa879c 100644 --- a/src/plot/CLAUDE.md +++ b/src/plot/AGENTS.md @@ -81,10 +81,10 @@ Docs: [`/doc/syntax/clause/facet.qmd`](../../doc/syntax/clause/facet.qmd), [`/do 3. **Transform**: add `scale/transform/.rs` implementing `TransformTrait`; register in `scale/transform/mod.rs` and `ALL_TRANSFORM_NAMES`. 4. **Coord**: add `projection/coord/.rs` implementing `CoordTrait`; register in `projection/coord/mod.rs` (`CoordKind`). Doc page under `/doc/syntax/coord/`. -In every case the writer (`src/writer/vegalite/`) needs corresponding rendering support — see [`src/writer/vegalite/CLAUDE.md`](../writer/vegalite/CLAUDE.md). +In every case the writer (`src/writer/vegalite/`) needs corresponding rendering support — see [`src/writer/vegalite/AGENTS.md`](../writer/vegalite/AGENTS.md). ## See also -- [`src/CLAUDE.md`](../CLAUDE.md) — module overview for the whole crate. -- [`src/writer/vegalite/CLAUDE.md`](../writer/vegalite/CLAUDE.md) — how the AST is rendered. +- [`src/AGENTS.md`](../AGENTS.md) — module overview for the whole crate. +- [`src/writer/vegalite/AGENTS.md`](../writer/vegalite/AGENTS.md) — how the AST is rendered. - [`/doc/syntax/`](../../doc/syntax/) — authoritative ggsql syntax reference. diff --git a/src/writer/hephaestus/CLAUDE.md b/src/writer/hephaestus/AGENTS.md similarity index 99% rename from src/writer/hephaestus/CLAUDE.md rename to src/writer/hephaestus/AGENTS.md index 3e7e716e7..4830cca7f 100644 --- a/src/writer/hephaestus/CLAUDE.md +++ b/src/writer/hephaestus/AGENTS.md @@ -61,7 +61,7 @@ extend them. For how the writer's behaviour got here, read deliberately not done yet is in [Known gaps](#known-gaps) below. For ggsql language semantics see [`/doc/syntax/`](../../../doc/syntax/); for the -sibling writer's internals, [`../vegalite/CLAUDE.md`](../vegalite/CLAUDE.md). +sibling writer's internals, [`../vegalite/AGENTS.md`](../vegalite/AGENTS.md). ## The governing principle @@ -507,7 +507,7 @@ claiming it writes anything. It lives in this crate rather than in `ggsql-cli` because the CLI uses only public `ggsql::*` API and has no renderer dependency — see -[`/ggsql-cli/CLAUDE.md`](../../../ggsql-cli/CLAUDE.md). So the *behaviour* goes +[`/ggsql-cli/AGENTS.md`](../../../ggsql-cli/AGENTS.md). So the *behaviour* goes public as a type instead of `build_composition` going public. Two things follow from what a window is: @@ -643,7 +643,7 @@ open target/visual-test/index.html It never stops on a failure — an error or a panic is captured against its cell — so one run inventories every gap at once. Implementation notes: -[`/ggsql-cli/CLAUDE.md`](../../../ggsql-cli/CLAUDE.md). +[`/ggsql-cli/AGENTS.md`](../../../ggsql-cli/AGENTS.md). ## Operational constraints @@ -734,8 +734,8 @@ Deliberately not done, in rough order of how likely they are to bite: ## See also -- [`../vegalite/CLAUDE.md`](../vegalite/CLAUDE.md) — the sibling writer to mirror. -- [`../../CLAUDE.md`](../../CLAUDE.md) — the core crate: feature flags, pipeline. -- [`../../plot/CLAUDE.md`](../../plot/CLAUDE.md) — the AST and scale types this +- [`../vegalite/AGENTS.md`](../vegalite/AGENTS.md) — the sibling writer to mirror. +- [`../../AGENTS.md`](../../AGENTS.md) — the core crate: feature flags, pipeline. +- [`../../plot/AGENTS.md`](../../plot/AGENTS.md) — the AST and scale types this writer consumes. - [`/doc/syntax/`](../../../doc/syntax/) — authoritative ggsql syntax reference. diff --git a/src/writer/vegalite/CLAUDE.md b/src/writer/vegalite/AGENTS.md similarity index 100% rename from src/writer/vegalite/CLAUDE.md rename to src/writer/vegalite/AGENTS.md diff --git a/tree-sitter-ggsql/CLAUDE.md b/tree-sitter-ggsql/AGENTS.md similarity index 95% rename from tree-sitter-ggsql/CLAUDE.md rename to tree-sitter-ggsql/AGENTS.md index 4c6ea1b75..9f7504ed8 100644 --- a/tree-sitter-ggsql/CLAUDE.md +++ b/tree-sitter-ggsql/AGENTS.md @@ -71,6 +71,6 @@ In editors with tree-sitter support: `npx tree-sitter playground` to interactive ## See also -- [`/CLAUDE.md`](../CLAUDE.md) — workspace overview. -- [`/src/parser/`](../src/parser/) (covered in [`/src/CLAUDE.md`](../src/CLAUDE.md)) — the consumer that turns the CST into typed `Plot` values. +- [`/AGENTS.md`](../AGENTS.md) — workspace overview. +- [`/src/parser/`](../src/parser/) (covered in [`/src/AGENTS.md`](../src/AGENTS.md)) — the consumer that turns the CST into typed `Plot` values. - [`/doc/syntax/`](../doc/syntax/) — authoritative ggsql syntax reference. From b4e503d4ed1ebe317cfd33cc5ce20e04f85d8ff7 Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Fri, 23 Oct 2026 13:51:27 +0200 Subject: [PATCH 2/4] keep PA config private --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 2fbb77588..5cbf0962e 100644 --- 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/ From 414fbd79a41fb878c6f7c6845c7755db5549aa98 Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Fri, 23 Oct 2026 13:54:25 +0200 Subject: [PATCH 3/4] update references from CLAUDE.md to AGENTS.md --- .github/workflows/build.yaml | 8 ++++---- .github/workflows/publish.yaml | 2 +- .github/workflows/release-packages.yml | 2 +- .github/workflows/test-extension.yaml | 2 +- ggsql-cli/Cargo.toml | 2 +- ggsql-cli/examples/visual_test.rs | 4 ++-- src/Cargo.toml | 2 +- src/writer/hephaestus/mod.rs | 2 +- src/writer/hephaestus/wiring.rs | 2 +- 9 files changed, 13 insertions(+), 13 deletions(-) diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 0c705ad87..b47aeaa1f 100644 --- 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 index 4120f2796..eafefd935 100644 --- 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 index fd0ca9822..adcdf979c 100644 --- 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 index 89ed7fa84..d99ed45d7 100644 --- 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/ggsql-cli/Cargo.toml b/ggsql-cli/Cargo.toml index 49b9f5904..09de24518 100644 --- 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 index bbe054e7d..6d93da758 100644 --- 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/src/Cargo.toml b/src/Cargo.toml index 56fa6974f..34f4209cd 100644 --- a/src/Cargo.toml +++ b/src/Cargo.toml @@ -131,7 +131,7 @@ svg = ["graphics", "hephaestus/svg"] pdf = ["graphics", "hephaestus/pdf"] # The plot-document writer. Named after the format, which ggsql does not own — -# see `src/writer/hephaestus/CLAUDE.md` on why that is accurate rather than a +# see `src/writer/hephaestus/AGENTS.md` on why that is accurate rather than a # leak. `hep-read` is test-only: it is what lets the round trip be asserted. hep = ["graphics", "hephaestus/document-write"] hep-read = ["hep", "hephaestus/document-read"] diff --git a/src/writer/hephaestus/mod.rs b/src/writer/hephaestus/mod.rs index 32720e656..1949fb23e 100644 --- a/src/writer/hephaestus/mod.rs +++ b/src/writer/hephaestus/mod.rs @@ -28,7 +28,7 @@ //! //! Architecture — the abstractions and the invariants they keep — and the //! inventory of deferred work are documented in -//! `src/writer/hephaestus/CLAUDE.md`. +//! `src/writer/hephaestus/AGENTS.md`. mod canvas; mod channels; diff --git a/src/writer/hephaestus/wiring.rs b/src/writer/hephaestus/wiring.rs index 35d3758f8..834d3dab0 100644 --- a/src/writer/hephaestus/wiring.rs +++ b/src/writer/hephaestus/wiring.rs @@ -41,7 +41,7 @@ use crate::{AestheticValue, DataFrame, GgsqlError, Layer, Plot, Result}; /// titles and break labels cascade the flag too but shape through /// `TextRun::new` regardless, so they still draw their markers; they start /// parsing with no change here once hephaestus reads the flag at those sites -/// (see [Known gaps](CLAUDE.md)). +/// (see [Known gaps](AGENTS.md)). pub fn ggsql_theme() -> Theme { let mut theme = Theme::default(); theme.legend.bar.frame = Element::Set(RectElement { From 9d25ac950799860848ee98fd2b70a3b82c1ae10b Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Fri, 23 Oct 2026 13:56:11 +0200 Subject: [PATCH 4/4] add news bullet --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 82477a5fc..62a81ed94 100644 --- 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