forgegraph 0.2.0__tar.gz → 0.3.0__tar.gz

{forgegraph-0.2.0 → forgegraph-0.3.0}/.gitignore

@@ -19,3 +19,9 @@ dist/
 htmlcov/
 .ipynb_checkpoints/
 .cache/
+
+# Claude Code's local settings
+.claude/
+
+# The skill evals' image sheets: kept locally, or attached to their PR
+review/*/skill-eval-graphs/

{forgegraph-0.2.0 → forgegraph-0.3.0}/.pre-commit-config.yaml

@@ -5,12 +5,12 @@ repos:
       - id: check-yaml
       - id: check-toml
       - id: end-of-file-fixer
-        exclude: \.md$|^(review|catalog)/
+        exclude: \.md$|^(review|catalog|docs/visual-changelog)/
       - id: trailing-whitespace
-        exclude: \.md$|^(review|catalog)/
+        exclude: \.md$|^(review|catalog|docs/visual-changelog)/
       - id: check-added-large-files
         args: [--maxkb=600]
-        exclude: ^(review|catalog)/  # self-contained HTML pages embed their images
+        exclude: ^(review|catalog|docs/visual-changelog)/  # self-contained HTML pages embed images
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.17.1
     hooks:

forgegraph-0.3.0/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+ForgeGraph follows [semantic versioning](https://semver.org). Before 1.0, a minor version may change how graphs look or how specs are written. From 0.2.0 on, each release's entry links its visual changelog: before and after images of every catalog card and regression graph that changed, made with `scripts/visual_changelog.py`.
+
+## 0.3.0 (2026-10-25)
+
+Images that changed: the [visual changelog](docs/visual-changelog/0.3.0.html).
+
+### Added
+
+- `fg.blank` takes `registry=`, as `fg.render` does, and a blank canvas's `save` path is optional, as a graph's is: with none, it saves `canvas.png` and the format's other file types.
+
+### Changed
+
+- **Breaking for existing specs:** parameters follow one naming system. `_` joins words that name one thing (`error_bar`, `plot_area`), `.` goes from a thing to its parts and properties (`line.width`), an on/off switch is the thing's `.show`, and nothing is abbreviated. A spec still using an old name is an error that suggests the new one; an old name that's now a category, such as `encoding.color`, suggests that category's parameters. The Python API's keyword arguments (`fg.xy`'s `color=`, `line_style=`, `marker_shape=`, `marker_fill=`, `detail=`) are unchanged and set the new paths. Graphs draw the same as before. The renames, old → new:
+  1. `grid.line_style` → `grid.line.style`; `grid.line_width` → `grid.line.width`
+  2. `plot_area.line_color` → `plot_area.line.color`; `plot_area.line_width` → `plot_area.line.width`
+  3. `layer.error_bar.line_width` → `layer.error_bar.line.width`; `layer.error_bar.cap_size` → `layer.error_bar.cap.width`
+  4. `layer.reference_line.line_style` → `layer.reference_line.line.style`; `layer.reference_line.line_width` → `layer.reference_line.line.width`
+  5. `series.marker.edge_color`, `series.marker.edge_width` → `series.marker.edge.color`, `series.marker.edge.width`, and the same in `series.bar`, `series.benchmark.marker` and `series.benchmark.bar`
+  6. `legend.key.frame_width` → `legend.key.frame.width`
+  7. `legend.key.sample.marker_size` → `legend.key.sample.marker.size`
+  8. `legend.key.frame` → `legend.key.frame.show`
+  9. `series.value_label.total` → `series.value_label.total.show`
+  10. `axis.tick.minor.num` → `axis.tick.minor.count`
+  11. `encoding.color` → `encoding.color.column`; `encoding.color_type` → `encoding.color.type`; `encoding.line_style` → `encoding.line.style.column`; `encoding.marker_shape` → `encoding.marker.shape.column`; `encoding.marker_fill` → `encoding.marker.fill.column`; `encoding.detail` → `encoding.detail.column` (`encoding.order` is unchanged)
+  12. Layouts: `separators.line.border` → `separators.border.show`
+  13. Schedules: `freshness.stamp` → `freshness.stamp.show`; `cadence.interval` → `cadence.interval.count`; `cadence.interval_unit` → `cadence.interval.unit`
+- **Breaking for packs' catalog files:** a catalog's cards are chosen by a rule, not by hand. Every parameter gets one card, its value taken from its range and the baseline's data, drawn on the first baseline where it changes the drawing; the page shows the variable parameters' cards. A catalog file lists only its baselines, and a layer's settings: `variations`, `no_card` and the `{value, from, with}` forms are gone. A pack's catalog page draws with the pack's own theme and format values.
+- Drawing and saving are about 3.7 times faster. Graphs and their files are the same as before.
+- A pack's fonts are registered when a file drawn uses one of its specs, not whenever a config lists the pack.
+- `forgegraph --help` gives each command a one-sentence summary, and `forgegraph catalog --help` names every kind it lists.
+- The internal package `forgegraph.catalog` is `forgegraph.catalog_build`. The API is unchanged.
+- One name is one pack. A config can't give a built-in pack's name, or a name the main config already gives, to another folder. Before, a folder config's copy of a pack replaced the one the main config lists, and what it drew wasn't marked non-standard.
+- ForgeGraph needs matplotlib 3.11.2 and typer 0.15.4 or later; earlier versions installed but didn't work.
+- The package's description and classifiers say what it is now: released, in alpha.
+
+### Fixed
+
+- Error bars on a date axis stand on their points, and error bars of aggregated rows on a date axis draw.
+- Times with a time zone are drawn at the times their clocks show. Before, they raised an error.
+- A reference line at a column's sum or standard deviation counts each row once when several y columns are drawn.
+- Value labels written with format auto use the value axis's tick label format when it's set, as reference lines do.
+- The catalog's record of what it was built from covers every module it draws with, so a change to the drawing code marks the catalog out of date.
+- The package's metadata lists the bundled fonts' licences.
+- A GraphSpec naming a list as its theme, format or graph type gets the error "must be a single value", not a crash.
+- A config naming a pack that can't be found, or another pack problem, stops `catalog`, `pack-notes`, `schema` and `explain` with its problems listed (`error:` lines, exit 1), not a traceback; with `--json`, one problem each, not one joined line.
+
+## 0.2.0 (2026-10-24)
+
+Images that changed: the [visual changelog](docs/visual-changelog/0.2.0.html).
+
+### Changed
+
+- Error bars are black by default in both built-in themes, and their color (`layer.error_bar.color`) is a variable parameter: a GraphSpec may set `series` or any hex color.
+- Three internal modules are renamed so none shares a name with the API: `forgegraph.render` is `forgegraph.drawing`, `forgegraph.layout` is `forgegraph.layouts` and `forgegraph.blank` is `forgegraph.canvas`. `import forgegraph.layouts as m` now gives the module, not `fg.layout`. The API is unchanged.
+
+### Fixed
+
+- `forgegraph --version` and `--help` no longer load matplotlib and pandas, so they answer at once, even on a new install. The API loads on first use.
+- The README and the skill's reference say when the main config is written: the first time a command reads the configs, such as `catalog` or `render`.
+- Error bars on side-by-side bars (`series.offset: side_by_side`) are drawn on their own bars. Before, every series but the middle one had its error bars drawn where they were first placed, before layout, usually off the axes.
+
+## 0.1.0 (2026-10-24)
+
+The first public release.
+
+### Added
+
+- **GraphSpecs:** a graph described in YAML or as a Python dict, drawn with `forgegraph render` or `fg.render`; `fg.xy` draws straight from a DataFrame.
+- **The `xy` graph type:**
+  - lines, markers and bars: grouped, stacked, 100 % stacked and horizontal;
+  - dates and log axes, value labels, a benchmark series;
+  - series named beside their lines or in a key.
+- **Layers:** reference lines, notes and error bars, from the data or given.
+- **Themes and formats:** a theme fixes what must stay the same and gives defaults for the rest; a format sets size, base font size, file types and resolution.
+- **Packs and configs:**
+  - every named spec comes from a pack, named `pack/name`; ForgeGraph's own is `forgegraph_base`, and `forgegraph_base_2` is a second look in this repository;
+  - the main config (written on first use, or named by `FORGEGRAPH_CONFIG`) and folder configs (`forgegraph.toml`) say which packs may be used;
+  - a pack only a folder config lists is non-standard: it works, and what's drawn with it is watermarked.
+- **Lint on every render:** overlapping or clipped text, a key covering data, fonts too small for the format, missing fonts, dropped rows and more.
+- **Provenance:** every saved file (PNG, JPEG, TIFF, SVG, PDF and HTML) records its GraphSpec and the specs it was drawn with, at the format's provenance level; `forgegraph load` reads it back.
+- **Layouts:** several GraphSpecs in one figure, with spanning tiles, blank cells and set widths; tabs, and HTML dashboards.
+- **Scheduled renders:** schedule files, `forgegraph job run`, a status file, `on_failure` and `on_success` hooks, a "data as of" footnote and a stale banner.
+- **The themed canvas:** `forgegraph.blank(theme, format)` for what no graph type can draw, always watermarked as non-standard.
+- **The agent skill** for Claude Code, installed with `forgegraph skill install`, with reference notes for themes, formats and configs, and for filing requests.
+- **Commands:** `render`, `explain`, `catalog`, `schema`, `pack-notes`, `load`, `job run` and `skill install`, each with `--json`.
+- **Catalogs:** a page for each pack in this repository, with a card for every parameter.
+
+## 0.0.1 (2026-10-17)
+
+The name, reserved on PyPI. No functionality.

forgegraph-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Contributions are welcome. For a bug or a feature request, open an [issue](https://github.com/sskaye/forgegraph/issues). For a change, open a pull request with tests, after running the checks below.
+
+## Development setup
+
+```bash
+uv sync
+uv run pre-commit install
+```
+
+While you work, `uv run pytest` runs the development suite: every test not marked slow, in parallel. The full suite adds the slow ones (every catalog card drawn, the image baselines, the catalog pages, and any test over a second). CI runs it on every pull request, and it's the one to run before a release:
+
+```bash
+uv run pytest --full && uv run ruff check . && uv run ruff format --check && uv run pyright
+```
+
+Mark a new test `@pytest.mark.slow` if it takes over a second (`uv run pytest --durations=20` lists the slowest).
+
+## After changing a definition or how graphs are drawn
+
+Every parameter gets one catalog card, its value and baseline chosen by a rule (`src/forgegraph/catalog_build/cards.py`), so a new parameter needs no card of its own; the page shows the variable parameters' cards, and the perturbation test draws them all. It needs a baseline that shows it only if none does: the build (for a variable parameter) or the perturbation test (for any) names a parameter that changes no baseline's drawing, and the fix is a generic scenario added to the baselines in the matching catalog file under `src/forgegraph/catalogs/` (or a pack's `catalogs/`).
+
+Rebuild the catalogs (it keeps its review comments; Node 18+ is needed once it has some), and the image baselines if graphs look different on purpose:
+
+```bash
+uv run forgegraph catalog build
+uv run forgegraph catalog build --pack forgegraph_base_2
+uv run python scripts/mirror_specs.py
+uv run python scripts/build_recreations.py --baselines
+```
+
+`uv run python scripts/visual_changelog.py main` then shows every image that changed.
+
+## Requesting a graph type
+
+Open a GitHub issue describing the graph you need, ideally with an example image or sketch and a little sample data. No code is needed.
+
+## Releasing
+
+1. Set the new version in pyproject.toml and in each built-in pack's pack.yaml.
+2. Rebuild the catalogs and mirrors (above).
+3. Write the visual changelog, `uv run python scripts/visual_changelog.py v<last version>`, and the CHANGELOG entry, linking it.
+4. Merge with CI green, and tag the merge commit `v<version>`.
+5. Run the Publish workflow.

forgegraph-0.2.0/README.md → forgegraph-0.3.0/PKG-INFO

@@ -1,6 +1,36 @@
+Metadata-Version: 2.5
+Name: forgegraph
+Version: 0.3.0
+Summary: Fast, consistent, publication-quality graphs from pandas DataFrames, usable by people and AI agents.
+Project-URL: Repository, https://github.com/sskaye/forgegraph
+Project-URL: Issues, https://github.com/sskaye/forgegraph/issues
+Project-URL: Changelog, https://github.com/sskaye/forgegraph/blob/main/CHANGELOG.md
+Author: Steven Kaye
+License-Expression: MIT AND OFL-1.1
+License-File: LICENSE
+License-File: src/forgegraph/fonts/OFL-IBMPlexSerif.txt
+License-File: src/forgegraph/fonts/OFL-Roboto.txt
+License-File: src/forgegraph/fonts/OFL-SourceSans3.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.12
+Requires-Dist: matplotlib>=3.11.2
+Requires-Dist: packaging>=23
+Requires-Dist: pandas>=2.2
+Requires-Dist: pyarrow>=17
+Requires-Dist: pydantic>=2.7
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: typer>=0.15.4
+Description-Content-Type: text/markdown
+
 # ForgeGraph
 
-Fast, consistent, publication-quality graphs from pandas DataFrames, useable by people and AI agents.
+Fast, consistent, publication-quality graphs from pandas DataFrames, usable by people and AI agents.
 
 You describe a graph in a **GraphSpec**. ForgeGraph draws it in a house style set by a **theme** and a **format**. It checks what it drew, and records how the graph was made inside the saved file. An agent skill lets agents make and revise graphs the same way.
 
@@ -18,7 +48,7 @@ You describe a graph in a **GraphSpec**. ForgeGraph draws it in a house style se
 - **Configs:** control which packs may be used, per user or folder. Used to enforce use of style pack(s) and watermark non-standard graphs.
 - **Lint:** Graphs are linted on rendering, with warnings for issues including overlapping or clipped text, a key covering data, or fonts too small.
 
-**Status:** 0.x.  `xy` graph type (lines, markers, & bars), reference lines, error bars, and notes layers, initial style packs. More graph types coming soon. If there’s specific ones you want, [open an issue](https://github.com/sskaye/forgegraph/issues).
+**Status:** 0.x.  `xy` graph type (lines, markers, & bars), reference lines, error bars, and notes layers, initial style packs. More graph types are planned. If there’s specific ones you want, [open an issue](https://github.com/sskaye/forgegraph/issues).
 
 ## Install
 
@@ -59,6 +89,16 @@ g = fg.xy(runs, x="hours", y="voltage", color="cell", title="Cell voltage")
 g.save("voltage")  # voltage.png, with its GraphSpec inside
 ```
 
+The Python API (each function has a docstring):
+
+- `fg.xy(df, x, y, ...)`: draw y against x from a DataFrame.
+- `fg.render(spec, data=None)`: draw a GraphSpec, given as a file or a document.
+- `fg.graphspec(name, graph_type, ...)`: write a GraphSpec document.
+- `fg.layout(spec, data=None)`: draw a layout.
+- `fg.load(path)`: a saved graph's record; its GraphSpec is under `"graphspec"`.
+- `fg.blank(theme, format)`: a themed canvas for drawing with matplotlib what no graph type can; what's drawn on it is watermarked.
+- A `Graph` has `.save(path)`, `.figure` and `.axes` (matplotlib's), `.issues` (the lint) and `.check()`.
+
 From the command line, with the DataFrame saved as runs.parquet and a GraphSpec, voltage.yaml:
 
 ```yaml
@@ -85,7 +125,8 @@ variable_parameters:
             data:
                 column: voltage
     encoding:
-        color: cell
+        color:
+            column: cell
 ```
 
 ```bash
@@ -102,11 +143,15 @@ A **config** lists the packs that may be used:
 - A folder config, `forgegraph.toml`, applies to the files in its folder and every folder below it. A file may use only the packs it lists.
 - A pack that a folder config lists but the main config doesn't still works, but it's non-standard: graphs drawn with it are watermarked, and ForgeGraph's commands say so. That way you can make and try a pack without changing an organization's main config.
 
+To write a pack, start from the example pack in [examples/packs/acme](https://github.com/sskaye/forgegraph/blob/main/examples/packs/acme); `forgegraph schema theme`, `format`, `pack` and `config` list every parameter.
+
+On macOS, a scheduled render that writes into a cloud-synced folder needs Full Disk Access.
+
 ## Commands
 
 - `forgegraph render <graphspec or layout>`: draw and save, and report lint.
 - `forgegraph explain <graphspec or layout>`: every value it's drawn with, and which file set it.
-- `forgegraph catalog`: the packs, graph types, layer types, themes, formats and reference notes available here.
+- `forgegraph catalog`: the packs, graph types, layer types, themes, formats, GraphSpecs, layouts, schedules and reference notes available here.
 - `forgegraph schema graphspec --graph-type <type> --theme <theme> --format <format>`: every parameter a GraphSpec can set.
 - `forgegraph schema <kind>`: every parameter of a theme, format, layer, layout, schedule, pack or config.
 - `forgegraph pack-notes`: the reference notes of the packs available here.
@@ -118,48 +163,41 @@ Every command takes `--help`, and `--json` for agents.
 
 ## Catalogs
 
-Each pack in this repository has a catalog: a page with a card for each parameter, showing what changing it does.
+Each pack in this repository has a catalog: a page with a card for each parameter, showing what changing it does. Download a page and open it in a browser.
 
-- forgegraph_base: ForgeGraph's own pack, with its graph types and layer types.
-- forgegraph_base_2: its own theme and format, and the same graph types and layer types drawn in them.
+- [forgegraph_base](https://github.com/sskaye/forgegraph/blob/main/catalog/forgegraph_base.html): ForgeGraph's own pack, with its graph types and layer types.
+- [forgegraph_base_2](https://github.com/sskaye/forgegraph/blob/main/catalog/forgegraph_base_2.html): its own theme and format, and the same graph types and layer types drawn in them.
 
 ## Your graphs are yours
 
-ForgeGraph is [MIT-licensed](LICENSE). Graphs and other output you make with it are yours: no attribution or licence terms apply to them. See TRADEMARKS.md for use of the name.
+ForgeGraph is [MIT-licensed](https://github.com/sskaye/forgegraph/blob/main/LICENSE). Graphs and other output you make with it are yours: no attribution or licence terms apply to them. See [TRADEMARKS.md](https://github.com/sskaye/forgegraph/blob/main/TRADEMARKS.md) for use of the name.
 
 ## Documentation
 
-- Architecture: how ForgeGraph is designed, and why.
-- Decisions: decisions that refine the architecture.
-- Specifications: every spec, a folder per kind.
-- [Changelog](CHANGELOG.md).
-- Build plan: how ForgeGraph is being built, phase by phase.
+- [Specifications](https://github.com/sskaye/forgegraph/blob/main/docs/specs): every spec, a folder per kind.
+- [Changelog](https://github.com/sskaye/forgegraph/blob/main/CHANGELOG.md).
+- [Contributing](https://github.com/sskaye/forgegraph/blob/main/CONTRIBUTING.md): working on ForgeGraph itself.
+- Design record, in [docs/design](https://github.com/sskaye/forgegraph/blob/main/docs/design):
+  - [Architecture](https://github.com/sskaye/forgegraph/blob/main/docs/design/architecture.md): how ForgeGraph is designed, and why.
+  - [To do](https://github.com/sskaye/forgegraph/blob/main/docs/design/todo.md): what's still planned.
 
 ## Contributing
 
-Feature requests and bug reports go to [GitHub issues](https://github.com/sskaye/forgegraph/issues); the skill can file them for you. CONTRIBUTING.md covers working on ForgeGraph itself. In short:
-
-```bash
-uv sync && uv run pre-commit install
-```
-
-```bash
-uv run pytest --full && uv run ruff check . && uv run pyright
-```
+Feature requests and bug reports go to [GitHub issues](https://github.com/sskaye/forgegraph/issues); the skill can file them for you. [CONTRIBUTING.md](https://github.com/sskaye/forgegraph/blob/main/CONTRIBUTING.md) covers working on ForgeGraph itself: setup, the checks to run, and regenerating the catalogs.
 
 ## Repository map
 
 - **src/forgegraph/**: the package.
-  - `graph.py`: the Python API (`fg.xy`, `fg.render`, `fg.graphspec`, `fg.load`) and the `Graph` object; `canvas.py`: the themed canvas.
+  - `graph.py`: the Python API (`fg.xy`, `fg.render`, `fg.graphspec`, `fg.load`) and the `Graph` object; `canvas.py`: `fg.blank`, the themed canvas; `drawn.py`: what they and layouts share once drawn; `data.py`: reading a GraphSpec's data.
   - **cli/**: the `forgegraph` command.
   - **spec/**: reading, checking and resolving specs, and the provenance record.
-  - **drawing/**: drawing, layout and lint. **layouts/**: layouts. **jobs/**: scheduled renders.
+  - **drawing/**: drawing, layout and lint. **layouts/**: `fg.layout` and layouts. **jobs/**: scheduled renders.
   - **packs/**: packs and configs, and the built-in packs `forgegraph_base` and `forgegraph_base_2`. **fonts/**: bundled fonts and their licences.
-  - **graph_types/**, **layers/**: the graph type and layer type definitions. **catalog/**, **catalogs/**: the catalog builder, and each definition's catalog file.
-  - **skill/forgegraph/**: the agent skill.
+  - **graph_types/**, **layers/**: the graph type and layer type definitions. **catalog_build/**: the catalog builder. **catalogs/**: each definition's catalog file.
+  - **skill/forgegraph/**: the agent skill. `forgemark.py`: Forgemark's review-comment format, and its pinned tool.
 - **catalog/**: the generated catalog pages.
-- **examples/**: sample data, and `packs/acme`, an example pack in a deliberately different style.
+- **examples/**: sample data; `packs/acme`, an example pack in a deliberately different style; and `layouts/`, a paper figure and a dashboard.
 - **evals/skill/**: the skill's eval cases, run by `scripts/run_skill_evals.py`.
 - **tests/**, **scripts/**: tests, and build and maintenance scripts.
-- **docs/**: the documents above. **review/**: each build phase's review pages.
+- **docs/**: the specifications, the design record and the visual changelogs. **review/**: each build phase's review pages.
 

forgegraph-0.2.0/PKG-INFO → forgegraph-0.3.0/README.md

@@ -1,31 +1,6 @@
-Metadata-Version: 2.5
-Name: forgegraph
-Version: 0.2.0
-Summary: Consistent, high-quality graphs from pandas DataFrames, for people and AI agents. Early development.
-Project-URL: Repository, https://github.com/sskaye/forgegraph
-Author: Steven Kaye
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 1 - Planning
-Classifier: Intended Audience :: Science/Research
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Scientific/Engineering :: Visualization
-Requires-Python: >=3.12
-Requires-Dist: matplotlib>=3.9
-Requires-Dist: packaging>=23
-Requires-Dist: pandas>=2.2
-Requires-Dist: pyarrow>=17
-Requires-Dist: pydantic>=2.7
-Requires-Dist: ruamel-yaml>=0.18
-Requires-Dist: typer>=0.12
-Description-Content-Type: text/markdown
-
 # ForgeGraph
 
-Fast, consistent, publication-quality graphs from pandas DataFrames, useable by people and AI agents.
+Fast, consistent, publication-quality graphs from pandas DataFrames, usable by people and AI agents.
 
 You describe a graph in a **GraphSpec**. ForgeGraph draws it in a house style set by a **theme** and a **format**. It checks what it drew, and records how the graph was made inside the saved file. An agent skill lets agents make and revise graphs the same way.
 
@@ -43,7 +18,7 @@ You describe a graph in a **GraphSpec**. ForgeGraph draws it in a house style se
 - **Configs:** control which packs may be used, per user or folder. Used to enforce use of style pack(s) and watermark non-standard graphs.
 - **Lint:** Graphs are linted on rendering, with warnings for issues including overlapping or clipped text, a key covering data, or fonts too small.
 
-**Status:** 0.x.  `xy` graph type (lines, markers, & bars), reference lines, error bars, and notes layers, initial style packs. More graph types coming soon. If there’s specific ones you want, [open an issue](https://github.com/sskaye/forgegraph/issues).
+**Status:** 0.x.  `xy` graph type (lines, markers, & bars), reference lines, error bars, and notes layers, initial style packs. More graph types are planned. If there’s specific ones you want, [open an issue](https://github.com/sskaye/forgegraph/issues).
 
 ## Install
 
@@ -84,6 +59,16 @@ g = fg.xy(runs, x="hours", y="voltage", color="cell", title="Cell voltage")
 g.save("voltage")  # voltage.png, with its GraphSpec inside
 ```
 
+The Python API (each function has a docstring):
+
+- `fg.xy(df, x, y, ...)`: draw y against x from a DataFrame.
+- `fg.render(spec, data=None)`: draw a GraphSpec, given as a file or a document.
+- `fg.graphspec(name, graph_type, ...)`: write a GraphSpec document.
+- `fg.layout(spec, data=None)`: draw a layout.
+- `fg.load(path)`: a saved graph's record; its GraphSpec is under `"graphspec"`.
+- `fg.blank(theme, format)`: a themed canvas for drawing with matplotlib what no graph type can; what's drawn on it is watermarked.
+- A `Graph` has `.save(path)`, `.figure` and `.axes` (matplotlib's), `.issues` (the lint) and `.check()`.
+
 From the command line, with the DataFrame saved as runs.parquet and a GraphSpec, voltage.yaml:
 
 ```yaml
@@ -110,7 +95,8 @@ variable_parameters:
             data:
                 column: voltage
     encoding:
-        color: cell
+        color:
+            column: cell
 ```
 
 ```bash
@@ -127,11 +113,15 @@ A **config** lists the packs that may be used:
 - A folder config, `forgegraph.toml`, applies to the files in its folder and every folder below it. A file may use only the packs it lists.
 - A pack that a folder config lists but the main config doesn't still works, but it's non-standard: graphs drawn with it are watermarked, and ForgeGraph's commands say so. That way you can make and try a pack without changing an organization's main config.
 
+To write a pack, start from the example pack in [examples/packs/acme](https://github.com/sskaye/forgegraph/blob/main/examples/packs/acme); `forgegraph schema theme`, `format`, `pack` and `config` list every parameter.
+
+On macOS, a scheduled render that writes into a cloud-synced folder needs Full Disk Access.
+
 ## Commands
 
 - `forgegraph render <graphspec or layout>`: draw and save, and report lint.
 - `forgegraph explain <graphspec or layout>`: every value it's drawn with, and which file set it.
-- `forgegraph catalog`: the packs, graph types, layer types, themes, formats and reference notes available here.
+- `forgegraph catalog`: the packs, graph types, layer types, themes, formats, GraphSpecs, layouts, schedules and reference notes available here.
 - `forgegraph schema graphspec --graph-type <type> --theme <theme> --format <format>`: every parameter a GraphSpec can set.
 - `forgegraph schema <kind>`: every parameter of a theme, format, layer, layout, schedule, pack or config.
 - `forgegraph pack-notes`: the reference notes of the packs available here.
@@ -143,48 +133,41 @@ Every command takes `--help`, and `--json` for agents.
 
 ## Catalogs
 
-Each pack in this repository has a catalog: a page with a card for each parameter, showing what changing it does.
+Each pack in this repository has a catalog: a page with a card for each parameter, showing what changing it does. Download a page and open it in a browser.
 
-- forgegraph_base: ForgeGraph's own pack, with its graph types and layer types.
-- forgegraph_base_2: its own theme and format, and the same graph types and layer types drawn in them.
+- [forgegraph_base](https://github.com/sskaye/forgegraph/blob/main/catalog/forgegraph_base.html): ForgeGraph's own pack, with its graph types and layer types.
+- [forgegraph_base_2](https://github.com/sskaye/forgegraph/blob/main/catalog/forgegraph_base_2.html): its own theme and format, and the same graph types and layer types drawn in them.
 
 ## Your graphs are yours
 
-ForgeGraph is [MIT-licensed](LICENSE). Graphs and other output you make with it are yours: no attribution or licence terms apply to them. See TRADEMARKS.md for use of the name.
+ForgeGraph is [MIT-licensed](https://github.com/sskaye/forgegraph/blob/main/LICENSE). Graphs and other output you make with it are yours: no attribution or licence terms apply to them. See [TRADEMARKS.md](https://github.com/sskaye/forgegraph/blob/main/TRADEMARKS.md) for use of the name.
 
 ## Documentation
 
-- Architecture: how ForgeGraph is designed, and why.
-- Decisions: decisions that refine the architecture.
-- Specifications: every spec, a folder per kind.
-- [Changelog](CHANGELOG.md).
-- Build plan: how ForgeGraph is being built, phase by phase.
+- [Specifications](https://github.com/sskaye/forgegraph/blob/main/docs/specs): every spec, a folder per kind.
+- [Changelog](https://github.com/sskaye/forgegraph/blob/main/CHANGELOG.md).
+- [Contributing](https://github.com/sskaye/forgegraph/blob/main/CONTRIBUTING.md): working on ForgeGraph itself.
+- Design record, in [docs/design](https://github.com/sskaye/forgegraph/blob/main/docs/design):
+  - [Architecture](https://github.com/sskaye/forgegraph/blob/main/docs/design/architecture.md): how ForgeGraph is designed, and why.
+  - [To do](https://github.com/sskaye/forgegraph/blob/main/docs/design/todo.md): what's still planned.
 
 ## Contributing
 
-Feature requests and bug reports go to [GitHub issues](https://github.com/sskaye/forgegraph/issues); the skill can file them for you. CONTRIBUTING.md covers working on ForgeGraph itself. In short:
-
-```bash
-uv sync && uv run pre-commit install
-```
-
-```bash
-uv run pytest --full && uv run ruff check . && uv run pyright
-```
+Feature requests and bug reports go to [GitHub issues](https://github.com/sskaye/forgegraph/issues); the skill can file them for you. [CONTRIBUTING.md](https://github.com/sskaye/forgegraph/blob/main/CONTRIBUTING.md) covers working on ForgeGraph itself: setup, the checks to run, and regenerating the catalogs.
 
 ## Repository map
 
 - **src/forgegraph/**: the package.
-  - `graph.py`: the Python API (`fg.xy`, `fg.render`, `fg.graphspec`, `fg.load`) and the `Graph` object; `canvas.py`: the themed canvas.
+  - `graph.py`: the Python API (`fg.xy`, `fg.render`, `fg.graphspec`, `fg.load`) and the `Graph` object; `canvas.py`: `fg.blank`, the themed canvas; `drawn.py`: what they and layouts share once drawn; `data.py`: reading a GraphSpec's data.
   - **cli/**: the `forgegraph` command.
   - **spec/**: reading, checking and resolving specs, and the provenance record.
-  - **drawing/**: drawing, layout and lint. **layouts/**: layouts. **jobs/**: scheduled renders.
+  - **drawing/**: drawing, layout and lint. **layouts/**: `fg.layout` and layouts. **jobs/**: scheduled renders.
   - **packs/**: packs and configs, and the built-in packs `forgegraph_base` and `forgegraph_base_2`. **fonts/**: bundled fonts and their licences.
-  - **graph_types/**, **layers/**: the graph type and layer type definitions. **catalog/**, **catalogs/**: the catalog builder, and each definition's catalog file.
-  - **skill/forgegraph/**: the agent skill.
+  - **graph_types/**, **layers/**: the graph type and layer type definitions. **catalog_build/**: the catalog builder. **catalogs/**: each definition's catalog file.
+  - **skill/forgegraph/**: the agent skill. `forgemark.py`: Forgemark's review-comment format, and its pinned tool.
 - **catalog/**: the generated catalog pages.
-- **examples/**: sample data, and `packs/acme`, an example pack in a deliberately different style.
+- **examples/**: sample data; `packs/acme`, an example pack in a deliberately different style; and `layouts/`, a paper figure and a dashboard.
 - **evals/skill/**: the skill's eval cases, run by `scripts/run_skill_evals.py`.
 - **tests/**, **scripts/**: tests, and build and maintenance scripts.
-- **docs/**: the documents above. **review/**: each build phase's review pages.
+- **docs/**: the specifications, the design record and the visual changelogs. **review/**: each build phase's review pages.