> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humic.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Paper

> Manually sync Humic foundation and semantic colors with a Paper file through Codex or another MCP agent.

<Warning>
  Paper color sync requires the Humic MCP rollout to be active in **Settings → Connect AI clients**.
</Warning>

Paper Desktop exposes a local read/write MCP for the currently open document.
Humic remains the source of truth; an agent connects to both Paper and Humic and
always previews changes before writing.

## Set up Codex or Conductor

Install Paper's official user-level plugin once:

```bash theme={null}
codex plugin marketplace add paper-design/agent-plugins
codex plugin add paper-desktop@paper
```

Keep Paper Desktop open with the target file selected. Paper's local MCP is
`http://127.0.0.1:29979/mcp`. No Paper credential or repository `mcp.json` is
needed.

## Sync colors

Ask the agent to use the explicit Paper `fileId`, read the file's `contentHash`
and all color tokens, then preview one direction:

* **Humic → Paper:** latest published Humic base/default foundation and semantic
  colors create or update matching Paper tokens.
* **Paper → Humic:** matching Paper colors update existing Humic draft base
  values only.

Colors without a foundation or semantic role are ignored until they are
classified in Humic.

The mapping is fixed: `color.neutral.500` becomes
`--color-neutral-500`. Humic `{color.neutral.500}` aliases become Paper
`var(--color-neutral-500)` aliases and map back only to an exact known Humic
color.

Review the create/update/skip/conflict diff and approve it explicitly. The agent
must recheck Paper's `contentHash` before a Paper write and Humic's draft
fingerprint before a Humic write; if either changed, make a new preview.

V1 syncs colors only. It never deletes or renames tokens, creates Humic tokens,
changes Humic mode overrides, publishes, watches the file or runs in the
background. Paper does not currently support Humic modes.