paintress 0.5.2 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
   <img src="assets/icon-512-wordmark.webp" width="200" alt="paintress">
-  <p>Design-document operation layer for AI agents</p>
+  <p>A UI design tool for AI agents</p>
   <p><a href="README.zh-CN.md">中文</a></p>
 </div>
 
@@ -8,16 +8,31 @@
 
 ## What it is
 
-paintress reads and writes structured design documents — JSON files with a documented schema. **`.ptr` is paintress's standard format**: everything paintress creates is `.ptr`. **`.pen` is compatible**: read, edited and rendered the same way, never converted behind your back. It renders documents to HTML, serves a local viewer, and exposes the same operations as MCP tools and as a CLI.
+paintress is a UI design tool for AI agents. You describe a screen in chat, the agent draws it into a design file, and you watch it appear in your browser — no canvas to drag, no design app to learn.
 
-It is not an editor. There is no canvas, no drag-and-drop, no property panel. A human looks at the design in a browser and clicks nodes to point at them; the agent does the reading and writing.
+You point instead of describing: click any element in the viewer and it gets a short number (`#1`), so "make #1 blue" changes exactly that element.
+
+Designs are plain JSON files inside your project, so they diff and commit like code.
+
+The agent does the reading and writing, through MCP tools or the CLI. The browser viewer is for looking, clicking and marking.
 
 | Part | Purpose |
 | --- | --- |
-| MCP tools | create, query, read, update, insert, delete, move, batch, validate, render, screenshot |
+| MCP tools | paintress_viewer, paintress_new, paintress_doc_info, paintress_query, paintress_get, paintress_update, paintress_insert, paintress_delete, paintress_move, paintress_batch, paintress_validate, paintress_convert, paintress_preset, paintress_project, paintress_font, paintress_audit, paintress_establish, paintress_adjust, paintress_component, paintress_render, paintress_screenshot, paintress_marks |
 | CLI | the same operations plus the viewer process, for use without an agent |
 | Viewer | local web server: renders a document, highlights changes, hands back clicked nodes as `#1`, `#2`, … |
-| Screenshot | PNG of a whole canvas, for agents that can look at images |
+| Screenshot | PNG of a canvas or one board; scale 0.2–2 (default 0.8), either edge capped to 8192px |
+
+## Files and formats
+
+New files are `.ptr` — paintress's own flavor of the same JSON design document. Existing `.pen` files open, edit and render unchanged; only the extension differs.
+
+Two project-level files keep a project consistent. They live at the **registered project root** — the directory you watch, not the folder of an individual design file — and they belong in version control next to the designs. `paintress_project` (and the viewer's `designSystem` block) returns their exact paths and reports any nested duplicate that would split the design system:
+
+| File | Holds |
+| --- | --- |
+| `__preset.ptr` | design tokens (colors, radii, spacing, font sizes, font families), preset groups and the font registry |
+| `__components.ptr` | reusable components (nodes marked `reusable`) |
 
 ## Requirements
 
@@ -45,8 +60,9 @@ paintress install pi cursor # or only the ones you name
 paintress mcp                                              start the stdio MCP server
 paintress new <file> [--name n] [--width n] [--height n] [--fill c]
                       [--layout vertical|horizontal|none] [--padding n] [--gap n] [--force]
-                                                           create a .ptr (one empty board)
+                                                           create a design file (one empty board)
 paintress info <file>                                      document summary
+paintress convert <file.pen> [out.ptr] [--force]          convert .pen to .ptr (source untouched)
 paintress query <file> [--type t] [--name n|--regex]    find nodes
 paintress get <file> <id> [--depth n]                   read a node subtree
 paintress update <file> <id> '<patch-json>'             shallow-merge attributes
@@ -55,12 +71,19 @@ paintress delete <file> <id>                            remove a node
 paintress move <file> <id> <parent> [--index n]         reparent a node
 paintress batch <file> '<ops-json>'                     several operations at once
 paintress validate <file>                               check against the format spec
+paintress preset list|set|remove|seed|set-group|remove-group ...
+                                                           tokens, groups and the starter scale
+paintress font list|add|remove|default ...                project font registry
+paintress audit <file>                               read-only design-system audit
+paintress establish <file> [--apply]                propose tokens / preset groups (dry-run by default)
+paintress adjust <file> --key k --value v [--apply] preview or apply a design-system adjustment
+paintress component list|insert|add ...                  project component library
 paintress render <file> <out.html>                      write the canvas as HTML
-paintress shot <file> <out.png> [--scale n] [--board id|name]  render to PNG (one board or the whole canvas)
+paintress shot <file> <out.png> [--scale 0.2..2] [--board id|name]  render to PNG (default 0.8)
 
-paintress web [--port n] [--idle ms] [--daemon]         start the viewer
+paintress web [--port n] [--idle ms] [--foreground]   ensure the viewer is running (idempotent, returns at once)
 paintress ping | status | stop                          viewer control
-paintress watch <name> <dir> | unwatch <name>           register a directory to browse
+paintress watch <name> <dir> [--depth n] | unwatch <name>  register a directory to browse
 paintress attach <name>                                 keep the viewer alive while an agent works
 
 paintress install [client...] [--dry-run]               write MCP config entries
@@ -71,20 +94,50 @@ paintress mcp-config <client>                           print the config snippet
 ## Viewer
 
 ```bash
-paintress web --daemon --idle 3600000
+paintress web
 paintress watch demo ./demo
-# open http://localhost:3316/demo?file=hello.ptr
+# open http://localhost:3316/demo
 ```
 
-Canvas navigation: wheel zooms at the pointer, space / middle button / empty area drags to pan, `Ctrl/Cmd+0` returns to 100%, `Shift+1` fits the window. Files with more than one board get a board strip. Edits made through the CLI or MCP are highlighted in the viewer, and clicks assign short ids that the agent can read back with `paintress_marks`.
+`paintress web` is idempotent and returns immediately: if a viewer is already running it prints that process's `pid` / `port` / `http`, otherwise it starts one and opens the viewer window on it. Either way the command is safe to run before every drawing session — there is never a second instance, and the window is opened by the program, in the desktop browser (`--foreground` keeps the process attached to your shell when you want its log; `paintress stop` is how you replace a running viewer, e.g. on another port). Under WSL the window lands in the Windows browser, never in a browser inside the distro.
+
+Agents get the same guarantee from the MCP side: `paintress_viewer` ensures the viewer and registers the current project, and the MCP server re-checks it before every write, so the viewer is up before the first edit instead of after someone asks.
+
+A design file that has a sibling Markdown file of the same name (`home.ptr` → `home.md`) gets a notes button in the top-left corner of the canvas. Click it and the canvas narrows to make room for the note: what the design is for, what is still open, which requirement it answers. The note is a plain Markdown file next to the design — write it yourself or let the agent write it; the panel is read-only.
+
+The rail in the top-right corner holds the project's design system. **Presets** are the project's colors, corner radii, spacing and font values: the agent references them (`$color-brand`) instead of pasting values, and you can change one here and watch the canvas update — no more "a bit bluer". Nodes can also reference a whole preset group; groups are shown read-only in the panel. **Components** is a read-only gallery of everything reusable the agent has built so far, so you can see progress and the agent can look before rebuilding something that already exists. A font badge next to the version shows how many families loaded; when one is missing its tooltip names the substitute.
+
+Canvas navigation: wheel zooms at the pointer, space / middle button / empty area drags to pan, `Ctrl/Cmd+0` returns to 100%, `Shift+1` fits the window, and `Ctrl/Cmd+K` quickly switches design files. Selecting a node opens a read-only inspector. Files with more than one board get a board strip; the active board can be exported as PNG at 0.5x / 1x / 2x (1x means its design pixels; the file is `<design>-<board>@<scale>x.png` and is scaled back when either edge exceeds 8192px). Edits made through the CLI or MCP are highlighted in the viewer, and clicks assign short ids that the agent can read back with `paintress_marks`; each mark carries the file and node id, so a shorthand resolves to one element in one file.
 
 Projects are named after their directory path (`c-thun/raybend`), so the URL reads like the path: `http://localhost:3316/c-thun/raybend?file=design/editor.pen`. Project rows have an **×** on hover that unbinds the project (design files are untouched; an agent re-registers on its next start), and **Stop server** in the sidebar footer shuts the viewer process down — both ask for confirmation first.
 
-The viewer follows the agent instead of asking you to manage it. When an agent starts the viewer it opens the browser on its own project; projects appear and leave with a short animation as agents come and go; when the last project is gone a 10-second countdown closes the window and the process. A browser that nobody is looking at no longer keeps the process alive.
+The viewer follows the agent instead of asking you to manage it. When an agent starts the viewer it opens your browser on that agent's own project — nothing for the agent to run twice, nothing for you to open by hand; projects appear and leave with a short animation as agents come and go. When the last project is gone **or the server is stopped** (the sidebar's Stop server, an idle exit), the page counts down ten seconds and closes its own window — you never have to close the tab by hand. A browser that nobody is looking at no longer keeps the process alive.
 
 When npm has a newer release than the running one, the version badge in the header grows a second line in rust red; clicking it opens the upgrade prompt (one copyable sentence) and the GitHub link. The check is client-optional on the daemon side: if npm is unreachable, the badge simply stays as it is.
 
-The toolbar's right side has two viewer-only controls. **Canvas background** switches Light / Gray / Dark for the design surface without touching the rest of the UI. **Language** switches the interface between 中文 and EN; on first load it follows the browser, and anything that is not Chinese gets English. Both are per-browser and remembered locally. Registering a project, or dropping a new `.ptr` / `.pen` into a watched directory, updates every open viewer without a reload.
+The toolbar's right side has two viewer-only controls. **Canvas background** switches Light / Gray / Dark for the design surface without touching the rest of the UI. **Language** switches the interface between 中文 and EN; on first load it follows the browser, and anything that is not Chinese gets English. Both are per-browser and remembered locally. Registering a project, or dropping a new design file into a watched directory, updates every open viewer without a reload.
+
+## Design system
+
+One source of truth per project, so a change lands everywhere instead of on one screen:
+
+- **Tokens** live in `__preset.ptr` and are referenced as `$color-brand` — never pasted. Kinds: `color`, `radius`, `spacing`, `fontSize`, `font`.
+- **Preset groups** apply a set of token references to one node type; a node opts in with `preset: "card"`.
+- **Components** live in `__components.ptr`; the agent copies one in, so a design is not rebuilt from scratch.
+- **Fonts** are registered per family with a source (`web` CSS URL, a project `css`/`file`, a `system` font, or `bundle` for app-only fonts) and, when the source cannot be verified, a design-time `preview`. Every read reports which families loaded and which fell back.
+
+`paintress_preset seed` (dry-run by default) fills a coherent starter scale — 27 tokens, 6 preset groups and the two web fonts. `audit` finds drift, `establish` proposes tokens from repeated values, and `adjust` shows the blast radius before changing anything.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `PTR_BROWSER` | Browser executable used for screenshots and PNG export |
+| `PAINTRESS_HOME` | State directory (daemon registry, Chromium font cache); default `~/.paintress` |
+| `PAINTRESS_NO_OPEN` | `1` never opens a browser window |
+| `PAINTRESS_NO_AUTO_WEB` | `1` stops the MCP server from ensuring the viewer before writes |
+| `PAINTRESS_NO_WEB_FONTS` | `1` skips the built-in web fonts (offline / CI) |
+| `CI` | `true` behaves like `PAINTRESS_NO_OPEN` |
 
 ## MCP clients
 
@@ -106,16 +159,18 @@ paintress mcp-config cursor   # print the exact snippet instead of editing files
 
 ## Skill
 
-`skills/paintress/SKILL.md` is a short instruction file for agents: when to reach for these tools, how `#1` markers map to node ids, and which tool to use for what. Copy it into your agent's skill directory if it supports one.
+`skills/paintress/SKILL.md` is a short instruction file for agents: when to reach for these tools, **to bring the viewer up before drawing** (idempotently), how `#1` markers map to node ids, and which tool to use for what. Copy it into your agent's skill directory if it supports one.
 
 ## Documentation
 
 - `specs/PLAN.md` — roadmap and open questions
-- `format/spec.yaml` — the document format spec (the `.pen` profile is frozen; `.ptr` evolves)
-- `format/README.md` — how the two layers relate, and why `.ptr` is the standard format
+- `format/spec.yaml` — the design file format spec
+- `format/README.md` — how the format layers relate
 - `.agents/memory/ARCHITECTURE.md` — design decisions and their rationale
 - `.agents/implementations/` — per-change records with measurements
 
+paintress also opens existing `.pen` design files as-is; `paintress convert` turns one into `.ptr` when you ask for it.
+
 ## Release (maintainers)
 
 Publishing is tag-driven: a `v*` tag makes `.github/workflows/publish.yml` first check that **ci passed for the same commit**, then build, verify the package contents and run `npm publish --provenance` through OIDC trusted publishing. Tests run once, in `ci.yml`; publishing does not re-run them. Do not publish from a laptop.
@@ -233,7 +288,7 @@ paintress doctor                                        # entry present, command
 printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}\n' | paintress mcp
 ```
 
-The second command must answer with a `result` containing `"serverInfo": {"name": "paintress", …}`. After a session restart, `paintress_doc_info` on any `.ptr` or `.pen` file is the end-to-end check.
+The second command must answer with a `result` containing `"serverInfo": {"name": "paintress", …}`. After a session restart, `paintress_doc_info` on any design file is the end-to-end check.
 
 ### 5. Multi-agent rules
 

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 <div align="center">
   <img src="assets/icon-512-wordmark.webp" width="200" alt="paintress">
-  <p>面向 AI agent 的设计稿操作层</p>
+  <p>给 AI agent 用的界面设计工具</p>
   <p><a href="README.md">English</a></p>
 </div>
 
@@ -8,16 +8,31 @@
 
 ## 这是什么
 
-paintress 读写结构化的设计稿——带公开 schema 的 JSON 文件。**`.ptr` 是 paintress 的标准格式**：paintress 创建的一切都是 `.ptr`。**`.pen` 兼容**：读取、编辑、渲染完全一致，绝不在背后悄悄转换。它把设计稿渲染成 HTML，起一个本地查看器，并把同一套操作同时暴露为 MCP 工具和 CLI。
+paintress 是一个给 AI agent 用的界面设计工具。你在对话里说要什么界面，agent 把它画进设计文件，你在浏览器里看到结果——没有画布要拖，也没有设计软件要学。
 
-它不是编辑器：没有画布、没有拖拽、没有属性面板。人在浏览器里看设计稿并点击节点指认目标，agent 负责读写。
+你点，它改：在查看器里点一下元素，它就得到一个短号（`#1`），说「#1 改成蓝色」改的就是那一个。
+
+设计稿是项目里的普通 JSON 文件，能 diff、能评审、能提交。
+
+读写由 agent 通过 MCP 工具或命令行完成；浏览器里的查看器只负责看、点、标。
 
 | 组成 | 作用 |
 | --- | --- |
-| MCP 工具 | 新建、查询、读取、更新、插入、删除、移动、批量、校验、渲染、截图 |
+| MCP 工具 | paintress_viewer、paintress_new、paintress_doc_info、paintress_query、paintress_get、paintress_update、paintress_insert、paintress_delete、paintress_move、paintress_batch、paintress_validate、paintress_convert、paintress_preset、paintress_project、paintress_font、paintress_audit、paintress_establish、paintress_adjust、paintress_component、paintress_render、paintress_screenshot、paintress_marks |
 | CLI | 同样的操作，外加查看器进程；不接 agent 也能用 |
 | 查看器 | 本地 web 服务：渲染设计稿、高亮变更、把点击的节点变成 `#1`、`#2`… |
-| 截图 | 整张画布的 PNG，给能看图的 agent 用 |
+| 截图 | 整张画布或单个画板的 PNG；倍率 0.2–2、默认 0.8，单边最多 8192px |
+
+## 文件与格式
+
+新建的文件是 `.ptr`——同一套 JSON 设计稿的 paintress 风味。已有的 `.pen` 文件照样打开、编辑、渲染，区别只在扩展名。
+
+项目根下有两份文件保证整个项目一致。它们在**注册的项目根**（也就是你 watch 的目录，不是某张设计稿所在的子目录），注册项目时会自动创建，和设计稿一样**应该进版本库**；`paintress_project`（以及查看器返回的 `designSystem`）会给出确切路径，并报告任何会把设计系统拆开的嵌套副本：
+
+| 文件 | 装什么 |
+| --- | --- |
+| `__preset.ptr` | 设计 token（颜色、倒角、间距、字号、字体族）、preset 组与字体注册表 |
+| `__components.ptr` | 可复用组件（标了 `reusable` 的节点） |
 
 ## 环境要求
 
@@ -45,8 +60,9 @@ paintress install pi cursor # 或只写指定的客户端
 paintress mcp                                             启动 stdio MCP server
 paintress new <file> [--name n] [--width n] [--height n] [--fill c]
                     [--layout vertical|horizontal|none] [--padding n] [--gap n] [--force]
-                                                          新建 .ptr（一个空画板）
+                                                          新建设计稿（一个空画板）
 paintress info <file>                                     文档摘要
+paintress convert <file.pen> [out.ptr] [--force]         把 .pen 转成 .ptr（源文件不动）
 paintress query <file> [--type t] [--name n|--regex]   条件查询节点
 paintress get <file> <id> [--depth n]                  读取节点子树
 paintress update <file> <id> '<patch-json>'            浅合并更新属性
@@ -55,12 +71,19 @@ paintress delete <file> <id>                           删除节点
 paintress move <file> <id> <parent> [--index n]        移动节点
 paintress batch <file> '<ops-json>'                    一次执行多个操作
 paintress validate <file>                              按格式规格校验
+paintress preset list|set|remove|seed|set-group|remove-group ...
+                                                           token、组与整套起步尺度
+paintress font list|add|remove|default ...               项目字体注册表
+paintress audit <file>                            画谱审计（只读）
+paintress establish <file> [--apply]             提取 token / preset 组（默认只给建议）
+paintress adjust <file> --key k --value v [--apply]  调整画谱（默认只看影响面）
+paintress component list|insert|add ...                 项目组件库
 paintress render <file> <out.html>                     渲染为 HTML
-paintress shot <file> <out.png> [--scale n]            渲染为 PNG
+paintress shot <file> <out.png> [--scale 0.2..2] [--board id|name]  渲染为 PNG（默认 0.8）
 
-paintress web [--port n] [--idle ms] [--daemon]        启动查看器
+paintress web [--port n] [--idle ms] [--foreground]  确保查看器在跑（幂等，立刻返回）
 paintress ping | status | stop                         查看器控制
-paintress watch <name> <dir> | unwatch <name>          注册/移除要浏览的目录
+paintress watch <name> <dir> [--depth n] | unwatch <name>  注册/移除要浏览的目录
 paintress attach <name>                                agent 工作期间保持查看器存活
 
 paintress install [client...] [--dry-run]              写入 MCP 配置条目
@@ -71,14 +94,46 @@ paintress mcp-config <client>                          打印单个客户端的
 ## 查看器
 
 ```bash
-paintress web --daemon --idle 3600000
+paintress web
 paintress watch demo ./demo
-# 打开 http://localhost:3316/demo?file=hello.ptr
+# 打开 http://localhost:3316/demo
 ```
 
-画布操作：滚轮以指针为锚点缩放，空格 / 中键 / 空白处拖拽平移，`Ctrl/Cmd+0` 回到 100%，`Shift+1` 适应窗口。多画板文件会显示画板条。通过 CLI 或 MCP 做的修改会在查看器里高亮，点击会让节点获得短号，agent 用 `paintress_marks` 读回。
+`paintress web` 是幂等的、且立刻返回：已经在跑就打印那个进程的 `pid` / `port` / `http`，没跑就拉起一个并把查看器窗口开在它上面。所以每次开始作画前无条件跑一遍都没问题——永远不会出现第二个实例；窗口由程序自己开在桌面浏览器里（`--foreground` 让进程占住终端、日志直接可见；要换端口/重启，用 `paintress stop`）。在 WSL 里窗口落在 Windows 的浏览器，不会是发行版里的那个浏览器。
+
+agent 从 MCP 侧拿到同样的保证：`paintress_viewer` 确保查看器在跑并把当前项目注册进去，MCP server 还会在每次写操作前再确认一遍——于是查看器是在第一次编辑之前就起来的，而不是等人开口。
+
+设计稿旁边放一份同名 Markdown（`home.ptr` → `home.md`），画布左上角就会出现「笔记」按钮。点开后画布向右收窄、左侧切出笔记：这份设计是干什么的、还有哪些待定、对应哪条需求。笔记就是设计稿旁边的一份普通 Markdown——您自己写，或者让 agent 写；面板本身只读。
+
+右上角的浮动工具条放的是这个项目的设计系统。**预设**是项目里的颜色、倒角、间距和字体值：agent 只写引用（`$color-brand`），不贴裸值；你在这里改一个值，画布立刻变——不用再说「红一点、再蓝一点」。节点还可以用 `preset` 引用一整组属性（谱式），面板里只读展示这些组。**组件**是只读画廊，把 agent 已经做好的可复用组件摊开给你看进度，也让 agent 动手前先来这儿找。版本号旁边有字体徽章：加载了几个 family、缺的那几个用的是什么替代字体，都在它的提示里。
 
-工具条右侧有两个只影响查看的开关。**画布背景**切 Light / Gray / Dark，只改画布区底色，不动界面其它部分（点档位或拖滑块）。**界面语言**在中 / EN 之间切；首次打开跟随浏览器语言，不是中文就是英文。两者都按浏览器记住。注册新项目、或往已跟踪目录里放一个新的 `.ptr` / `.pen`，所有已打开的查看器都会自动刷新，不需要手按 F5。
+画布操作：滚轮以指针为锚点缩放，空格 / 中键 / 空白处拖拽平移，`Ctrl/Cmd+0` 回到 100%，`Shift+1` 适应窗口，`Ctrl/Cmd+K` 快速切换设计稿。点中节点会打开只读属性面板。多画板文件会显示画板条；选中具体画板后可按 0.5x / 1x / 2x 导出 PNG（1x = 画板设计像素；文件名是 `<稿名>-<画板>@<倍率>x.png`，单边超过 8192px 会等比压回）。通过 CLI 或 MCP 做的修改会在查看器里高亮，点击会让节点获得短号，agent 用 `paintress_marks` 读回；每条标记都带文件与节点 id，所以一个短号能落到唯一文件里的唯一元素。
+
+查看器跟着 agent 走，不需要人管：agent 起查看器时窗口自己开在它那个项目上；项目随 agent 来去，带进出场动画。**最后一个项目被收走、或服务被关掉（侧栏 Stop server、空闲退出）时，页面自己倒计时十秒再关窗**——不用人去点标签页的 ×。没人看的浏览器也不再拖着进程不放。
+
+工具条右侧有两个只影响查看的开关。**画布背景**切 Light / Gray / Dark，只改画布区底色，不动界面其它部分（点档位或拖滑块）。**界面语言**在中 / EN 之间切；首次打开跟随浏览器语言，不是中文就是英文。两者都按浏览器记住。注册新项目、或往已跟踪目录里放一个新的设计稿，所有已打开的查看器都会自动刷新，不需要手按 F5。
+
+## 设计系统
+
+一个项目一套事实来源，改一处全项目跟着变，而不是各画各的：
+
+- **Token** 存在 `__preset.ptr`，设计稿里写 `$color-brand`，不贴裸值。种类：`color`、`radius`、`spacing`、`fontSize`、`font`。
+- **Preset 组**把一组 token 引用套到某类节点上；节点写 `preset: "card"` 即参与。
+- **组件**存在 `__components.ptr`；agent 复制一份进来用，不从零重画。
+- **字体**按 family 登记来源（`web` 的 CSS URL、项目内的 `css`/`file`、`system` 系统字体、或只存在于安装包的 `bundle`）；来源无法本地验证时还必须给设计期 `preview`。每次读取都会报告哪些 family 加载了、哪些用了替代。
+
+`paintress_preset seed`（默认 dry-run）一次补齐一套起步尺度——27 个 token、6 个 preset 组和两个网络字体。`audit` 找漂移，`establish` 从重复值里提 token，`adjust` 改动前先给影响面。
+
+## 环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `PTR_BROWSER` | 截图与 PNG 导出用的浏览器可执行文件 |
+| `PAINTRESS_HOME` | 状态目录（daemon 注册表、Chromium 字体缓存）；默认 `~/.paintress` |
+| `PAINTRESS_NO_OPEN` | `1` 时不打开浏览器窗口 |
+| `PAINTRESS_NO_AUTO_WEB` | `1` 时 MCP 写操作前不再确保查看器在跑 |
+| `PAINTRESS_NO_WEB_FONTS` | `1` 时跳过内置网络字体（离线 / CI） |
+| `CI` | `true` 等价于 `PAINTRESS_NO_OPEN` |
 
 ## MCP 客户端
 
@@ -100,16 +155,18 @@ paintress mcp-config cursor   # 只打印片段，不改文件
 
 ## Skill
 
-`skills/paintress/SKILL.md` 是给 agent 的简短说明：什么时候用这些工具、`#1` 怎么映射到节点 id、哪个工具做什么。支持 skill 机制的客户端把它复制进对应目录即可。
+`skills/paintress/SKILL.md` 是给 agent 的简短说明：什么时候用这些工具、**作画前先把查看器拉起来（幂等）**、`#1` 怎么映射到节点 id、哪个工具做什么。支持 skill 机制的客户端把它复制进对应目录即可。
 
 ## 文档
 
 - `specs/PLAN.md` —— 路线与未决问题
-- `format/spec.yaml` —— 文件格式规格（`.pen` 层冻结，`.ptr` 层演进）
-- `format/README.md` —— 两层关系，以及为什么 `.ptr` 是标准格式
+- `format/spec.yaml` —— 设计稿文件格式规格
+- `format/README.md` —— 格式分层之间是什么关系
 - `.agents/memory/ARCHITECTURE.md` —— 设计决策与理由
 - `.agents/implementations/` —— 每次变更的记录与实测数据
 
+已有的 `.pen` 设计稿也能直接打开，原样渲染；需要时 `paintress convert` 把它转成 `.ptr`。
+
 ## 发版（维护者）
 
 发布由 tag 驱动：`v*` tag 会让 `.github/workflows/publish.yml` 先校验**同一提交的 ci 已通过**，再构建、自检包内容并通过 OIDC trusted publishing 执行 `npm publish --provenance`。测试只在 `ci.yml` 跑一次，发布不重跑。不要在笔记本上直接发布。
@@ -227,7 +284,7 @@ paintress doctor                                        # 条目存在、命令
 printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}\n' | paintress mcp
 ```
 
-第二条命令应当返回包含 `"serverInfo": {"name": "paintress", …}` 的 `result`。会话重启后，对任意 `.ptr` 或 `.pen` 文件调用 `paintress_doc_info` 是一次端到端验证。
+第二条命令应当返回包含 `"serverInfo": {"name": "paintress", …}` 的 `result`。会话重启后，对任意设计稿调用 `paintress_doc_info` 是一次端到端验证。
 
 ### 5. 多 agent 规则