# Paper Figure

**Describe the figure. Refine a preview. Say “use this”. Get editable SVG, PDF and PPTX.**

[中文](README.zh-CN.md) · [Quickstart](QUICKSTART.md) · [Example](docs/demo/figure.pdf) · [Validation](TEST_REPORT.md)

Paper Figure is a small Codex skill backed by local build tools. It keeps design,
confirmation and reconstruction in one conversation, without asking you to fill
forms, move files between chats, or configure a separate image API.

> **v2.1.1 · Preview release.** Local export, state and safety checks are tested.
> Native Codex image generation and arbitrary scientific-figure reconstruction
> are **not** covered by these automated tests. A host image tool is required for
> generated concepts; this skill cannot grant a tool the client does not provide.

This project focuses on repeatable revisions and same-source delivery. It is not a claim
of a unique drawing method or superior figure quality. See [related work](docs/RELATED_WORK.md).

## Use it

In a Codex conversation with the skill installed:

```text
$paper-figure Create a method overview: short video → geometry prediction →
future spatial answers. Keep the scientific labels editable. Show me a concept first.
```

The explicit skill name is useful at the start; it is not required in every message.
Then speak normally:

```text
Make the right panel less crowded. Keep the furniture unchanged.
Use v2. Rebuild it.
Change “Prediction” to “Geometry Encoder”; keep everything else unchanged.
```

A supplied, already-approved image can go directly to reconstruction. Simple
block diagrams can start as native drafts rather than spend an image generation.
Image edits stay on the selected version. After reconstruction, label/layout
changes edit native objects—not a regenerated full image.

## Install once

Give Codex the published skill URL:

```text
$skill-installer https://github.com/GuangSTrip/paper-figure/tree/main/skills/paper-figure
```

Or, from a reviewed local checkout:

```sh
python3 install.py --replace --with-deps
```

`--replace` backs up any previous installation. `--with-deps` explicitly authorizes
pip downloads into a private runtime under `~/.cache/paper-figure/2.1.0/venv`.
It does not change global Python, Codex config or account credentials. This local installer defaults to `~/.agents/skills/paper-figure/`; Codex skill-installer
may use `~/.codex/skills/paper-figure/`. Update the existing location with `--target`
instead of creating a second installation. Refresh skill discovery if needed.

**System requirement:** Python 3.10+. PDF export also needs Inkscape. On macOS:

```sh
brew install --cask inkscape
```

LibreOffice is optional for PPTX previews; otherwise review the PPTX in PowerPoint.
On macOS, restricted execution can abort Inkscape before export; see
[renderer troubleshooting](docs/INSTALL.md#macos-restricted-execution).
For Ubuntu, project-local installation and manual dependency setup, see
[installation](docs/INSTALL.md). Install on the machine where Codex actually runs.

## What is actually implemented?

| Component | Implementation |
|---|---|
| Concept generation/editing | Host Codex image tool; capability-checked instructions, not a hidden API client |
| Version history | Immutable local image copies, parent IDs, notes, hashes and current selection |
| Approval | Pins a version/hash; a new concept invalidates approval; managed exports enforce this |
| Local revision | Stable-ID patching; checkpoints detect out-of-scope native/asset changes |
| Comparison | Side-by-side and pixel-difference previews; **not** a semantic similarity score |
| Export | Common scene → native SVG/PPTX; Inkscape → PDF; independent raster assets |
| Checks | Native text/geometry, labels, fonts, raster DPI, screenshot wrapping, stale files |
| Publication | Offline-reviewed snapshot → authenticated GitHub CLI → new public repo and prerelease |

![Synthetic native figure example](docs/demo/figure.preview.png)

The example is a **synthetic software fixture**, not a real experiment, recorded
video or proof of image-model reconstruction quality. [SVG](docs/demo/figure.editable.svg) ·
[PDF](docs/demo/figure.pdf) · [PPTX](docs/demo/figure.editable.pptx)

## Why not just a prompt?

The model owns design and scientific interpretation. The skill owns workflow
routing. Scripts own repeatable export and checks. Deleting the skill does not
make a model unable to draw; it removes the reusable state, approval and build
infrastructure. There is one `skills/paper-figure/` source tree, not mirrored copies.

```text
Intent → selected concept → user approval → scene + independent assets
                                             ↓
                                  SVG + PDF + native PPTX
                                             ↓
                                machine checks + actual review
```

The user supplies intent and feedback. Codex maintains `brief.json`, native scene,
concept history and QA records internally. [Architecture](docs/ARCHITECTURE.md)

## Boundaries that matter

The built-in scene supports groups, ordinary text, common shapes, straight
connectors, polygons/polylines and PNG/JPEG assets. It is **not** a general
SVG-to-PPTX converter. Complex formulas, arbitrary paths, native charts and
advanced gradients need an explicit custom source/backend, not silent flattening.

PDF is a submission export; SVG and PPTX retain native objects. Fonts must be
available to an editor. Raster assets remain resolution-limited. PowerPoint edits
do not automatically sync back; the exporter protects edited outputs from
unacknowledged replacement. Machine checks do not certify scientific correctness,
accessibility, exact renderer parity, or conference compliance.

No browser-cookie access, implicit paid API fallback, telemetry or public preview
server is bundled. Host model calls still follow that provider's policies/usage
limits. [Privacy](PRIVACY.md) · [Security](SECURITY.md)

## Develop and share

```sh
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.txt
python scripts/validate_repo.py
python -m unittest discover -s tests -v
python scripts/package.py --refresh-manifest
```

The root `plugin.json` uses the portable Agent Plugins format. The compatibility
manifest `.codex-plugin/plugin.json` references the **same** skill tree. Local
marketplace metadata is included for supported Codex clients. Public-directory
review is separate from a GitHub release; this project does not claim a listing
or official verification. [Publishing](docs/PUBLISHING.md)

Research and implementation decisions are documented in [references](docs/REFERENCES.md).
Contributions: [guide](CONTRIBUTING.md) · [live-evaluation plan](evals/README.md).

MIT for project code; third-party dependencies retain their licenses. No font files
are distributed. See [third-party notices](docs/THIRD_PARTY.md).