# figpilot

figpilot checks a figure the way a reviewer would, before you submit it.

It is a Claude Code skill, an opt-in hook and an MCP server that drive [structfig](https://github.com/danilkotelnikov/structfig), a toolkit that builds structure-biology figures from HTML pages and measures them against a list of checkable rules.

## What you get

- **A skill** (`skill/figpilot`) that knows the six steps: study, one object, two prototypes and a gate, build by page, independent reads, QA. It also knows what never to do: heredocs for HTML, invented palettes, ranges for lists, hover-only legends.
- **An MCP server** (`mcp/server.mjs`) with seven tools: `list_templates`, `new_figure`, `build_figure`, `qa_figure`, `palette_sample`, `palette_check`, `render_structure`. They call structfig's scripts, so figpilot carries no copy of them.
- **A hook** (`hook/figpilot_hook.mjs`) that, after you write a page, reads the QA marks of its last build and says them in one line. It is off until you add it, and silent in any project without a control file.

## Start

```
git clone https://github.com/danilkotelnikov/structfig
git clone https://github.com/danilkotelnikov/figpilot
cd figpilot
npm ci
node scripts/install-notes.mjs
```

The last command prints the exact commands for your machine: where to link the skill, the `claude mcp add` line, the hook entry for `settings.json`. It runs none of them. You paste what you want.

figpilot finds structfig through `FIGPILOT_STRUCTFIG`, or the folder `../structfig` next to it.

## One session, in short

You ask for the contact map of a nanobody and its antigen. figpilot lists the templates, copies `contacts` into your project with a notes stub, fetches the entry from the RCSB if you allow it, renders it in ChimeraX, builds the page, and runs the marks. Then it hands the PNG, and only the PNG, to a fresh reader and asks three questions. The reader usually finds a problem. You fix it, rebuild, ask again. The notes file keeps the dates and the answers.

## Settings

Copy `figpilot.example.json` to `figpilot.json` in your figure project. It has the same keys as structfig's `structfig.example.json`: `strictness`, `palette`, `typeLadder`, `words`, `widthMm`, `review`, `claimBoundary`, `chimerax`, `art`, plus two for the hook, `hook` and `hookBlocks`. Either file name works for the hook and for structfig's build.

| Hook setting | Effect |
|---|---|
| `hook: false` | silent |
| `hookBlocks: true` | a failed strict check exits with code 2 and the reason; otherwise the hook never blocks |

To turn the hook off for good, delete the control file or remove the entry from your settings.

## What the server checks

Every argument is checked before it reaches a command or a path.

- `entry` is a four-character PDB code, or the path of a `.pdb` or `.cif` file inside your project.
- `chains` takes only the keys that structfig's renderer reads (`binder`, `antigen`, `light`, `drop`, `cdr`, `light_cdr`, `seed`, `sigma`, `t`, `assign`). Values use letters, digits and `_ , . : = + -`. A semicolon, space, quote or line break is refused.
- `key`, `name` and `template` use letters, digits, `_` and `-`, up to 64 characters.
- `dir`, `out`, `art` and the file arguments must lie inside the project folder. That is the folder of the nearest `figpilot.json` or `structfig.json`, else the working directory. `art`, `tokens`, `dir` of `qa_figure` and the palette inputs may also lie inside structfig. Files are written only inside the project folder.
- `render_structure` does not use the network. If the entry is not in structfig's `data/pdb`, it stops and tells you to pass `fetch=true`. With `fetch=true` it downloads the file and its record from the RCSB into `data/pdb` of the structfig folder.

The hook exits 0 and prints nothing when the control file or its input is malformed.

## Tests

```
npm test
```

They start the server over stdio and call its tools, fire the hook with fake payloads, and compare the skill's copied references with structfig's docs. They need structfig next to figpilot. The test that renders with ChimeraX runs only when `STRUCTFIG_CHIMERAX` is set.

## Keeping the skill current

The skill's references are copies of structfig's docs. After you change a doc there, run `node scripts/sync-references.mjs`; `--check` fails if a copy is stale.

## Licence

Code: MIT, see `LICENSE`. The files in `skill/figpilot/references` are copies of structfig documents, which are CC BY 4.0, copied from [structfig](https://github.com/danilkotelnikov/structfig) with attribution. See `skill/figpilot/references/LICENSE.md`.