# dartwork-mpl

> Publication-quality matplotlib utilities: free-form physical-width
> API (`width="13cm"`), ten aspect tokens, curated style presets, an
> OKLCH color system, content-aware layout (`simple_layout`), visual
> validation, and an MCP server for AI coding assistants.

For agents using dartwork-mpl: run `python -m dartwork_mpl.skills install`
in the project to load the bundled skill (`SKILL.md` + references) into
Claude Code (`.claude/skills`) and Codex (`.agents/skills`), or read
`dm.get_agent_doc("AGENTS")` for the short consumer entry. The repo-root
`CLAUDE.md` / `AGENTS.md` are for contributors to this repository. For a
single-file ingestion of the canonical docs, fetch `llms-full.txt`. The
anti-pattern catalog (`02-anti-patterns.yaml`) and the prompt corpus are
bundled in the wheel under `dartwork_mpl/asset/prompt/`.

## Docs

- [Quickstart](https://dartworklabs.github.io/dartwork-mpl/usage_guide/quickstart.html): 5-minute tour — install, first figure, save.
- [Layout & geometry](https://dartworklabs.github.io/dartwork-mpl/usage_guide/layout.html): width / aspect tokens, content-aware `simple_layout`, multi-panel.
- [Design system](https://dartworklabs.github.io/dartwork-mpl/design_system/index.html): the color/font token catalogs — one rule: the name is a family, `n` picks the form (`dm.colors`, `dm.set_colors`, `cmap="dc.*"`, 900+ named colors incl. `oc.*`/`tw.*`).
- [Migration guide](https://dartworklabs.github.io/dartwork-mpl/migration.html): old → new mapping for removed names (incl. the Model B color API).
- [API reference](https://dartworklabs.github.io/dartwork-mpl/api/index.html): autosummary of every public function and class.

## AI integration

- [AI integration overview](https://dartworklabs.github.io/dartwork-mpl/ai/index.html): three integration tiers (MCP, file-based prompts, plain Python).
- [MCP server setup](https://dartworklabs.github.io/dartwork-mpl/integrations/mcp_server.html): setup and trusted-code artifact delivery/retrieval, explicit Copy/Retained input choices and input-set deletion: 19 tools, 10 static resources, 9 resource templates, 2 prompts. Operator-selected private server-host storage; unset policy denies inputs. Historical receipts do not prove current availability/freshness; clients handle per-input choices.
- [Anti-pattern catalog (raw YAML)](https://raw.githubusercontent.com/dartworklabs/dartwork-mpl/main/src/dartwork_mpl/asset/prompt/02-anti-patterns.yaml): SSOT used by `dm.lint` / MCP `lint_dartwork_mpl_code`.
- [Plot templates index](https://dartworklabs.github.io/dartwork-mpl/examples_gallery/09_ai_templates/index.html): 18 ready-to-use scripts — bar, line, scatter, heatmap, etc.

## Optional

- [Repository (GitHub)](https://github.com/dartworklabs/dartwork-mpl): source, issues, releases.
- [Changelog](https://github.com/dartworklabs/dartwork-mpl/blob/main/CHANGELOG.md): release notes.
- [0.4 design spec](https://dartworklabs.github.io/dartwork-mpl/superpowers/specs/2026-04-29-dartwork-mpl-ai-readiness-design.html): rationale for the 0.4 API surface.
- [0.5+ roadmap spec](https://dartworklabs.github.io/dartwork-mpl/superpowers/specs/2026-05-01-ai-readiness-0.5-roadmap.html): plan for closing remaining AI affordance gaps.

## Installed Python route

Install the skill (`python -m dartwork_mpl.skills install`) or read
`dm.get_agent_doc("AGENTS")`; `dm.get_prompt("00-index")` covers bundled
basic/advanced template source retrieval, then `dm.get_prompt("03-recipes")`
for native multi-panel containers and the full lint/validate/export/image-review
revision loop. `find_template.source_path` is repo-relative metadata, not an
installed path. `save_formats` returns None, not validation evidence; preserve
NaN gaps intentionally with separate shape/domain checks.
- [Installed Python workflow](https://dartworklabs.github.io/dartwork-mpl/ai/installed_python.html): core package, full reports, actual PNG/PDF review and separate-stem revisions.
