# paper mono

## install

for a one-command trial without a global install: npx paper-mono mono.

## start

1. 01
   open the reference

   open Paper Desktop and the document you want to use. if it came from Paper Snapshot, select the relevant page or artboard before continuing.

2. 02
   check the connection

   run paper doctor. Paper Mono will tell you if Paper, its local MCP bridge, or a required tool is unavailable.

3. 03
   start from the project

   open the destination repository root and run paper mono. on first use, enter /login and choose a model provider.

## reference to code

1. 01confirm the exact Paper file, page, artboard, and relevant nodes
2. 02inspect the reference and destination project without mutation
3. 03produce a specific brief with scope, uncertainty, and verification
4. 04wait for the exact APPROVE PAPER BRIEF <brief-id> phrase
5. 05implement only the approved scope through the project’s design system
6. 06verify the real route, viewport, state, and interaction

## a brief, not a guess

the first deliverable is a reference-specific implementation brief. an illustrative shape looks like this:

reference

<paper file> / <page> / <artboard> / <relevant node ids>

observed

hierarchy, type, spacing, color, assets, and interaction evidence

adaptation

reuse the destination’s components and tokens; borrow structure, not branding or CSS

scope

named routes, files, allowed paths, and exact project commands

states

desktop, mobile, hover, focus, loading, and reduced-motion behavior where relevant

verification

focused tests plus rendered product proof at the required viewports and states

status

locked until the brief id, target, and session are explicitly approved

## approval is the boundary

paper mono starts locked. before approval it can inspect Paper and the project, but it cannot edit project files, run an approved project command, or make a live Paper change. the one explicit pre-approval file output is a deterministic screenshot path you requested yourself.

approval is bound to the brief, target, project, and session. target drift or resume relocks the tools. --audit-only is permanently read-only. approved shell commands are exact-string gated, but still run in your normal host shell, so read them before approving.

## Paper Snapshot

Paper Snapshot is Paper's separate Chrome extension. it brings a web reference into Paper; Paper Mono reads the resulting nodes. it does not run the extension, control Chrome, or treat a reference screenshot as proof that the destination product is correct.

## requirements and compatibility

• Node.js 22.19.0 or newer
• Paper Desktop running with a document open
• fd (or fdfind) and rg already installed on PATH
• a supported model-provider login for paper mono

clean installation and offline CLI behavior are proven on Apple-silicon macOS. the package declares no OS restriction, but live Paper integration on Linux and Windows remains unproven.

## authentication and privacy

run paper mono, enter /login, and choose a provider. credentials, settings, and sessions stay under ~/.paper/agent by default. prompts and the code/reference context needed for reasoning go to the provider you select, so its privacy terms apply.

Paper reads stay on the local loopback bridge. Paper Mono needs no account, public Convex backend, hosted workspace, or product telemetry, and it disables the inherited install and version phone-home paths.

## when it does not work

Paper is closed

open Paper and a document, then rerun paper doctor --json. reinstalling is unnecessary.

the Snapshot is too large

select one artboard, inspect a bounded subtree, use a scale-1 screenshot, and request JSX or styles only where needed.

the wrong target is active

run paper info --json and paper selection --json, switch targets in Paper, and request a fresh brief.

model auth is missing

start paper mono and enter /login. headless failures return guidance instead of a stack trace.

## links

• paper-mono on npmversion 0.62.0
• support and private security reportsnever send keys or private document contents

public npm distribution comes first. curated public source will follow after the installed product stabilizes, so there is no repository link yet.

remove the package with npm uninstall -g paper-mono. local sessions remain until you choose to remove them.