forgegraph 0.4.0__tar.gz → 0.6.0__tar.gz

{forgegraph-0.4.0 → forgegraph-0.6.0}/.gitignore

@@ -20,6 +20,9 @@ htmlcov/
 .ipynb_checkpoints/
 .cache/
 
+# The documentation site, as mkdocs builds it
+/site/
+
 # Claude Code's local settings
 .claude/
 

{forgegraph-0.4.0 → forgegraph-0.6.0}/CHANGELOG.md

@@ -1,40 +1,70 @@
 # 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`.
+ForgeGraph follows [semantic versioning](https://semver.org). Before 1.0, a minor version may change how graphs look or how specs are written.
+
+## 0.6.0 (2026-10-30)
+
+### New Features
+
+- **Values on hover.** Pointing at a data point on a graph in an HTML page, or tapping it, shows its values: each axis's value, with its error bar where it has one, and its series' group. A value with an error bar is rounded to the error's last digit, as in 8.0 ± 0.4 (95%CI). It works on markers, lines and bars, and in every tile of a layout.
+- **Feature requests from the agent.** When the agent makes a graph ForgeGraph can't draw, or one that's watermarked, it asks whether you'd like to file a feature request for what was missing.
+- **A documentation site.** Getting started, and a reference for every specification, command and Python function, built from the repository.
+
+### Changes
+
+- **HTML pages are larger.** Each HTML page now carries its graphs' points and the font their values are written in, about 0.2 MB more for the font.
+- **Issue forms.** Feature requests and bug reports on GitHub now have forms, and the agent writes requests under their headings.
+
+### Bug Fixes
+
+- A negative error bar distance is now an error when the spec is read, instead of when the graph is drawn.
+- The specifications' descriptions now match what ForgeGraph does.
+
+## 0.5.0 (2026-10-29)
+
+### New Features
+
+- **Nested tabs.** A tab in a layout can now hold tabs of its own, to any depth. The HTML page shows a row of tabs for each level, and switching to another group keeps the same chart showing.
+- **Tick labels per axis.** `axis.x.tick.label` and `axis.y.tick.label` set the size, weight and color of each axis's tick labels separately. Anything they don't set comes from `axis.tick.label`.
+- **Tabs without scripts.** The tabs on a layout's HTML page now work where the page's scripts don't run, such as in a browser with JavaScript turned off. Before, such a page showed every tab, one below another.
+- **Tab bar style.** A layout's `tab_bar.label` and `tab_bar.line` set the look of the tab names and of the line under them on the HTML page. By default they follow the first graph's theme.
+
+### Changes
+
+- **Titles.** Titles now sit `title.gap` above the plot, measured from the line the letters sit on, so titles side by side line up whatever their letters. The default theme's `title.gap` is now 0.41, which keeps its titles where they were. A theme that sets its own `title.gap` will see its titles sit a little higher than in 0.4.
+- **Notes above the plot.** A note placed outside the plot at the top now goes between the title and the plot, instead of above the title.
+- **Tab names on the page.** The tab names are written in the theme's font and color, instead of the browser's font in dark grey.
+
+### Bug Fixes
+
+- Tick labels now use the theme's tick label font and weight. Before, only their size and color were applied.
+- A y-axis title reading upward now sits the same distance from the tick labels whatever its letters.
 
 ## 0.4.0 (2026-10-27)
 
-Images that changed: the [visual changelog](docs/visual-changelog/0.4.0.html).
+### New Features
 
-### Changed
+- **Multiple Series.** GraphSpecs can now have independent Series, enabling full control over the marker, line, and bar properties and not just variation by a palette.
+- **Reference bands.** The `reference_line` layer is now `reference` and has been augmented to also draw lines per element of the series and bands. It also can now compute a value plus offset (e.g. a line at mean + 3 s.d.). This enables drawing of error bands, confidence intervals of model fits, and other more complex references.
+- **More aggregations.** Series, reference lines, and error bars can show the mean, median, percentile, standard deviation, standard error or confidence intervals.
+- **Stepped and smooth lines.** `line.interpolate` can now be steps or a smooth curve in addition to a direct line.
+- **Dates as values.** Dates, such as `2025-08-25`, can now be used directly in all relevant parameters.
 
-- **Breaking for existing specs and configs:** one built-in pack, `forgegraph_default`, replaces `forgegraph_base` and `forgegraph_base_2`. Its specs are `light_theme` (in place of `forgegraph_base/base_theme`), `compact_format` (`base_format`), `wide_format` (`base_layout_format`), `layout` (`layout_example`), `schedule` (`base_schedule`) and `graphspec_example`; `forgegraph_base_2` has no replacement. A main config listing `forgegraph_base` or `forgegraph_base_2` is an error: list `forgegraph_default` instead. light_theme draws 0.3's look. It fixes every text's font and gap, the palettes (the colors, line styles, marker shapes and fills that series take in turn), the ticks' direction, sides and algorithms, and the grid, so a GraphSpec that sets `grid.x.show` needs a theme that leaves it variable; a series may still set its own color, line style, marker shape and line width. The default layout draws no line between tiles and leaves 0.25 × the base size at the figure's edges.
-- The specification files, which define each kind, are in `src/forgegraph/specifications/`, and their pages in `docs/specifications/`; no spec can name or extend them. The built-in pack's pages are in `docs/packs/forgegraph_default/`, and the catalog page is `catalog/forgegraph_default.html`.
-- A category's brackets in a specification file say what the code reads about it, from a fixed set: its style, `same as <sibling>` for a category with a sibling's parameters, and `look from <theme category>` for a layer category whose look comes from the theme. Anything else there is an error, and descriptions are never read, so rewording one changes nothing.
-- A style's member that no file tags, itself or through a category inside `parameters`, is fixed or variable as its general parameter is: a fixed `text.font` fixes every text style's font, even where the theme sets the style's own.
-- `forgegraph schema <kind>` no longer says whether a parameter is fixed: it shows the kind's specification, which isn't what graphs are drawn with. `forgegraph schema graphspec` lists what a GraphSpec can set, and `forgegraph explain` shows what's fixed.
-- A reference layer's `fill.color` may be None: two lines with values make a band only when it isn't.
-- **Breaking for existing specs:** a GraphSpec lists its series by name under `series`, each drawn from its own column (by default, the column of its name) with its own settings: `aggregation`, `split`, `order`, `color`, `color_scale`, `line`, `marker`, `bar` and `value_label`, and the theme's variable series parameters it sets for itself. They replace `axis.*.data.aggregation`, `encoding.*` and `mark.*`; the value axis's `data.column` is None. `arrangement.base_axis`, `arrangement.stacking`, `arrangement.offset` and `arrangement.total.show` replace `series.base_axis`, `series.aggregation`, `series.offset` and `series.value_label.total.show`. A series' color, line style, marker shape and fill take `first`, `series`, a value or a column; series take palette colors in the order they're listed.
-- **Breaking for existing specs:** the `reference` layer replaces `reference_line`: `line_1` and `line_2`, each at a value or from a column, with its own `aggregation` and `offset` (aggregation styles), `scope`, line and label (with `label.inside`), and the `fill` of a band between them. The theme's `layer.reference` replaces `layer.reference_line`.
-- An aggregation style (`function`, `multiplier`, `percentile`) for a series, a reference line and error bars; functions include `percentile`, `stddev`, `stderr` and `ci`.
-- `line.interpolate` draws a series' line straight, in steps (`step_after`, `step_before`, `step_center`) or as a smooth curve that never overshoots its points.
-- A note and a reference layer's lines, labels and fill may set the theme's variable look for themselves.
-- A style key (one from `encoding.line.style.column`, `encoding.marker.shape.column` or `encoding.marker.fill.column`) follows `legend.key.title.text`, as the series' key does: `column_name`, the default, gives each key its own column's name, so default graphs are unchanged; `None` removes every key's title; a text titles one key, and with more than one key drawn it's an error. With no `encoding.color.column`, a style key's samples are drawn in the one series color, not the text color. `render --json` reports `style_keys`, the column each style key drawn explains (for a layout, each tile's), beside `labelling`.
-- A range type `date`: a date, or a date and time, as YAML's bare date (`2025-08-25`, `2025-08-25 06:00:00`) or ISO 8601 text (`"2025-08-25T06:00"`); a time with a zone is at its clock time, as the data's are. `axis.x.min`, `axis.x.max`, `axis.y.min` and `axis.y.max`, a reference line's `value` and `benchmark.value` take it: on a datetime axis or column, a date is drawn exactly where its day number is, and numbers keep working as day numbers. A date on an axis that isn't dates is an error naming the axis's type. Text that reads as a date is a reference line's column only if the data has a column of that name. Provenance records write dates as ISO 8601 text.
-- On a date value axis, what would draw nonsense is an error that says what to do: stacking (`series.aggregation` sum or percent), adding up rows (`axis.*.data.aggregation` sum), bars (`mark.bar.show`, which would start at 1970), and value labels without a date format. A reference line at a date column's aggregate is on a date axis only, at its mean, median, min or max, with multiplier 1. A date axis's `tick.label.format` must have a date directive.
+### Changes
 
-### Fixed
+- **One built-in pack, `forgegraph_default`.** `forgegraph_base` is renamed `forgegraph_default` and its specifications have been renamed. `forgegraph_base_2` has been removed. Please update your config and any GraphSpecs or packs referencing the old packs. The default theme has been tuned slightly to fix more parameters, reducing complexity of graph design.
+- **Themes, formats and GraphSpecs are written differently.** Each has one `parameters` tree, and `!fix` and `!var` tags are used to set what a GraphSpec can change, in place of the `fixed_parameters` and `variable_parameters` blocks. A theme sets the parameters of all text and all lines once, under `text` and `line`, and each category that uses them, such as the title or the tick labels, only needs to modify the parameters that are different from that default.
+- **Simplified Specifications.** Numerous simplifications to the way specifications are written, making them easier to read and modify.
 
-- In a theme whose text is light, powers of ten on a log axis and superscripts in labels no longer give a `font-fallback` lint issue. They were always drawn in the theme's font and weight; the issue came from the faces matplotlib loads for maths but doesn't draw these with.
-- The `outside-limits` and `log-axis-values` lint checks count only data points. A reference line's ends and an error bar's ends no longer count as points outside a set axis limit, or as values of 0 or below on a log axis.
-- A style key on the benchmark's column matches the drawing: its entries are the groups the series are styled by, so a value after the benchmark no longer gets the next value's style, and the benchmark, drawn in its own style, has no style sample and is named once, by `legend.method`. When `legend.method: key` doesn't fit, the error says why: every position in `legend.key.positions` is taken or covers data, naming the position each style key took.
-- YAML's null (`null`, `~` or nothing) is None everywhere a spec can say None. `extends: null` failed with `KeyError: None`, and a file extending null wasn't required to list every parameter.
-- Computed values are compared with an axis's limits allowing for float noise: a value is past a limit only if it's past by more than 1e-9 of the axis's span, measured in powers of ten on a log axis. A stack that totals `axis.y.max` but for its last digits isn't reported by `outside-limits`; a reference line at a computed value that equals a set limit isn't an error; bars whose values are 0 but for float noise still stand on the axis; and a tick a hair past the end of the view, which matplotlib draws, is measured for layout and lint and counts when log labels choose between plain numbers and powers of ten.
-- Dates and times draw the same on y as on x: every value placed on an axis (the data, its aggregates, stacks, reference lines, error bars and limits) becomes a number the same way, so a date y axis has date ticks, a reference line at a date column's aggregate lands on it, and error bars from a date column's spread are in days. With value labels off, a date `tick.label.format` such as `"%H:%M"` on y is no longer refused as a number format; value labels and a reference line's value on a date axis are written in a date format.
+### Bug Fixes
 
-## 0.3.0 (2026-10-25)
+- Dates on the y axis draw as they do on x: date ticks, reference lines at a date column's mean or median, and error bars in days.
+- The lint no longer counts reference lines and error bars as data points outside the axis limits, or as values of 0 or below on a log axis.
+- Values that differ from an axis limit only by rounding are no longer reported as outside it.
+- In a theme with a light font weight, powers of ten on a log axis no longer give a `font-fallback` lint issue.
+- `null` and `~` are accepted everywhere a spec can say None.
 
-Images that changed: the [visual changelog](docs/visual-changelog/0.3.0.html).
+## 0.3.0 (2026-10-25)
 
 ### Added
 
@@ -78,8 +108,6 @@ Images that changed: the [visual changelog](docs/visual-changelog/0.3.0.html).
 
 ## 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.

forgegraph-0.6.0/CITATION.cff

@@ -0,0 +1,16 @@
+cff-version: 1.2.0
+message: If you use ForgeGraph in your work, please cite it as below.
+title: ForgeGraph
+abstract: Fast, consistent, publication-quality graphs from pandas DataFrames, for people and AI agents.
+type: software
+authors:
+  - given-names: Steven
+    family-names: Kaye
+repository-code: https://github.com/sskaye/forgegraph
+url: https://pypi.org/project/forgegraph/
+license: MIT
+keywords:
+  - data visualization
+  - plotting
+  - matplotlib
+  - scientific visualization

{forgegraph-0.4.0 → forgegraph-0.6.0}/CONTRIBUTING.md

@@ -9,7 +9,7 @@ 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:
+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 that changes more than pages no test reads (`review/`, `CHANGELOG.md`, `CONTRIBUTING.md`, and `docs/` other than the spec and pack pages), 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
@@ -31,14 +31,26 @@ uv run python scripts/build_recreations.py --baselines
 
 `uv run python scripts/visual_changelog.py main` then shows every image that changed.
 
+## The documentation site
+
+The site is built with MkDocs from docs/site. Its Reference pages are generated as it's built: the commands from the CLI, the specifications and the built-in pack from their files, and the Python API from the docstrings (scripts/docs_site.py). To build it and read it while you work:
+
+```bash
+uv run --group docs mkdocs serve
+```
+
+CI builds it on every pull request, and a broken link fails the build. Publishing a GitHub release deploys it to GitHub Pages.
+
 ## 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 the built-in pack's pack.yaml, and for a new minor version, its `requires` (`">=0.4, <0.5"` for 0.4).
+1. Set the new version in pyproject.toml, in the built-in pack's pack.yaml and in the definitions' (src/forgegraph/specifications/pack.yaml), and for a new minor version, their `requires` (`">=0.4, <0.5"` for 0.4).
 2. Rebuild the catalog 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.
+3. Write the CHANGELOG entry: the key features a user would want to know were added, changed or removed, and the bugs fixed.
+4. Write the visual changelog: `uv run python scripts/visual_changelog.py v<previous version>`, which saves docs/visual-changelog/<version>.html.
+5. Merge with CI green, and tag the merge commit `v<version>`.
+6. Run the Publish workflow, then create the GitHub release with the CHANGELOG entry as its notes.
+

{forgegraph-0.4.0 → forgegraph-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgegraph
-Version: 0.4.0
+Version: 0.6.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
@@ -39,8 +39,9 @@ You describe a graph in a **GraphSpec**. ForgeGraph draws it in a house style se
 - **Themes:** fixes the look of the graph (fonts, palette, lines, keys, etc.).
 - **Formats:** sets the destination: figure size, base font size, file types and resolution, e.g. a slide, a journal column or a dashboard tile.
 - **GraphTypes:** defines the type of graph and its parameters. E.g. `xy` (lines, markers and bars).
-- **Layers:** features drawn over a graph. E.g. reference lines, notes, & error bars.
+- **Layers:** features drawn over a graph. E.g. reference lines and bands, notes, & error bars.
 - **GraphSpecs:** specify the data, theme, format, and all customizable properties.
+- **Series:** each series in a graph has its own marker, line and bar properties, and can show a summary of its data, such as the mean, a percentile or a confidence interval.
 - **Layouts:** combine multiple graphs into a larger figure or multi-tab dashboard.
 - **Scheduled renders:** re-render graphs and dashboards on a schedule set with cron, launchd, or by an agent.
 - **Provenance:** every saved file contains its specifications as metadata, enabling inspection of how the graph was made and reproduction of it.
@@ -48,7 +49,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 are planned. If there’s specific ones you want, [open an issue](https://github.com/sskaye/forgegraph/issues).
+**Status:** Until 1.0, a new minor version may change how graphs look or how specs are written; the [changelog](https://github.com/sskaye/forgegraph/blob/main/CHANGELOG.md) lists what changed in each release. `forgegraph catalog` lists the graph types, layers and packs you have. More graph types are planned. If there are specific ones you want, [open an issue](https://github.com/sskaye/forgegraph/issues).
 
 ## Install
 
@@ -131,7 +132,7 @@ forgegraph render voltage.yaml
 
 ## Packs and configs
 
-Every named theme, format, GraphSpec, layout and schedule comes from a **pack**, a folder or pip package of specs, and is named `pack/name`. ForgeGraph's built-in pack, `forgegraph_default`, is stored in src/forgegraph/packs: its theme, `light_theme`, its formats, `compact_format` for single graphs and `wide_format` for layouts, and a layout and a schedule to extend.
+Every named theme, format, GraphSpec, layout and schedule comes from a **pack**, a folder or pip package of specs, and is named `pack/name`. ForgeGraph's built-in pack, `forgegraph_default`, is stored in src/forgegraph/packs. It has a theme and formats, so a graph can always be drawn, and specs to extend; `forgegraph catalog` lists them.
 
 A **config** lists the packs that may be used:
 
@@ -145,11 +146,13 @@ On macOS, a scheduled render that writes into a cloud-synced folder needs Full D
 
 ## Commands
 
+`forgegraph --help` lists every command. The main ones:
+
 - `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, 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 schema <kind>`: every parameter of a theme, format, graph type, layer, layout, schedule, pack or config.
 - `forgegraph pack-notes`: the reference notes of the packs available here.
 - `forgegraph load <file>`: a saved graph's record, and its GraphSpec.
 - `forgegraph job run <schedule>`: render a schedule's GraphSpecs and layouts once.
@@ -173,9 +176,7 @@ ForgeGraph is [MIT-licensed](https://github.com/sskaye/forgegraph/blob/main/LICE
 - [Built-in pack](https://github.com/sskaye/forgegraph/blob/main/docs/packs/forgegraph_default): forgegraph_default's specs.
 - [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.
+- [Architecture](https://github.com/sskaye/forgegraph/blob/main/docs/design/architecture.md): how ForgeGraph is designed, and why.
 
 ## Contributing
 
@@ -196,5 +197,5 @@ Feature requests and bug reports go to [GitHub issues](https://github.com/sskaye
 - **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 specifications' and packs' pages, the design record and the visual changelogs. **review/**: each build phase's review pages.
+- **docs/**: the specifications' and packs' pages, the design record and the visual changelogs. **review/**: review pages: each build phase's, the audit's and the refactoring's, and the open issues list.
 

{forgegraph-0.4.0 → forgegraph-0.6.0}/README.md

@@ -9,8 +9,9 @@ You describe a graph in a **GraphSpec**. ForgeGraph draws it in a house style se
 - **Themes:** fixes the look of the graph (fonts, palette, lines, keys, etc.).
 - **Formats:** sets the destination: figure size, base font size, file types and resolution, e.g. a slide, a journal column or a dashboard tile.
 - **GraphTypes:** defines the type of graph and its parameters. E.g. `xy` (lines, markers and bars).
-- **Layers:** features drawn over a graph. E.g. reference lines, notes, & error bars.
+- **Layers:** features drawn over a graph. E.g. reference lines and bands, notes, & error bars.
 - **GraphSpecs:** specify the data, theme, format, and all customizable properties.
+- **Series:** each series in a graph has its own marker, line and bar properties, and can show a summary of its data, such as the mean, a percentile or a confidence interval.
 - **Layouts:** combine multiple graphs into a larger figure or multi-tab dashboard.
 - **Scheduled renders:** re-render graphs and dashboards on a schedule set with cron, launchd, or by an agent.
 - **Provenance:** every saved file contains its specifications as metadata, enabling inspection of how the graph was made and reproduction of it.
@@ -18,7 +19,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 are planned. If there’s specific ones you want, [open an issue](https://github.com/sskaye/forgegraph/issues).
+**Status:** Until 1.0, a new minor version may change how graphs look or how specs are written; the [changelog](https://github.com/sskaye/forgegraph/blob/main/CHANGELOG.md) lists what changed in each release. `forgegraph catalog` lists the graph types, layers and packs you have. More graph types are planned. If there are specific ones you want, [open an issue](https://github.com/sskaye/forgegraph/issues).
 
 ## Install
 
@@ -101,7 +102,7 @@ forgegraph render voltage.yaml
 
 ## Packs and configs
 
-Every named theme, format, GraphSpec, layout and schedule comes from a **pack**, a folder or pip package of specs, and is named `pack/name`. ForgeGraph's built-in pack, `forgegraph_default`, is stored in src/forgegraph/packs: its theme, `light_theme`, its formats, `compact_format` for single graphs and `wide_format` for layouts, and a layout and a schedule to extend.
+Every named theme, format, GraphSpec, layout and schedule comes from a **pack**, a folder or pip package of specs, and is named `pack/name`. ForgeGraph's built-in pack, `forgegraph_default`, is stored in src/forgegraph/packs. It has a theme and formats, so a graph can always be drawn, and specs to extend; `forgegraph catalog` lists them.
 
 A **config** lists the packs that may be used:
 
@@ -115,11 +116,13 @@ On macOS, a scheduled render that writes into a cloud-synced folder needs Full D
 
 ## Commands
 
+`forgegraph --help` lists every command. The main ones:
+
 - `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, 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 schema <kind>`: every parameter of a theme, format, graph type, layer, layout, schedule, pack or config.
 - `forgegraph pack-notes`: the reference notes of the packs available here.
 - `forgegraph load <file>`: a saved graph's record, and its GraphSpec.
 - `forgegraph job run <schedule>`: render a schedule's GraphSpecs and layouts once.
@@ -143,9 +146,7 @@ ForgeGraph is [MIT-licensed](https://github.com/sskaye/forgegraph/blob/main/LICE
 - [Built-in pack](https://github.com/sskaye/forgegraph/blob/main/docs/packs/forgegraph_default): forgegraph_default's specs.
 - [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.
+- [Architecture](https://github.com/sskaye/forgegraph/blob/main/docs/design/architecture.md): how ForgeGraph is designed, and why.
 
 ## Contributing
 
@@ -166,5 +167,5 @@ Feature requests and bug reports go to [GitHub issues](https://github.com/sskaye
 - **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 specifications' and packs' pages, the design record and the visual changelogs. **review/**: each build phase's review pages.
+- **docs/**: the specifications' and packs' pages, the design record and the visual changelogs. **review/**: review pages: each build phase's, the audit's and the refactoring's, and the open issues list.
 

forgegraph-0.6.0/SECURITY.md

@@ -0,0 +1,9 @@
+# Security
+
+## Supported versions
+
+Security fixes go into the latest minor release. Upgrade to it to get them.
+
+## Reporting a vulnerability
+
+Please report a vulnerability privately, through the repository's [Security tab](https://github.com/sskaye/forgegraph/security/advisories/new), not in a public issue. Say what's affected, how to reproduce it, and what it lets someone do. You'll get a reply there, and the fix is released with an advisory once it's ready.