diff --git a/docs/development/contributing.md b/docs/development/contributing.md
index 2dbf3ad8a..3b7d2971c 100644
--- a/docs/development/contributing.md
+++ b/docs/development/contributing.md
@@ -55,6 +55,10 @@ bun run check
- **Functions/variables** — camelCase
- **Types/interfaces** — PascalCase
+### AI Agent Conventions
+
+See [`AGENTS.md`](https://github.com/dannote/open-pencil/blob/master/AGENTS.md) in the repo root for detailed coding conventions tailored to AI agents. Covers rendering, scene graph, components & instances, layout, UI, file format, Tauri, and known issues.
+
## Making Changes
1. Check existing [openspec specs](/development/openspec) for the capability you're modifying
diff --git a/docs/development/roadmap.md b/docs/development/roadmap.md
index 98fc400df..371298342 100644
--- a/docs/development/roadmap.md
+++ b/docs/development/roadmap.md
@@ -85,10 +85,12 @@ Components, instances, overrides, variants, variables, collections, modes/themes
### Phase 5: AI Integration 🔲
-MCP server, design guidelines, screenshot verification loop.
+MCP server, CLI & headless mode, design guidelines, screenshot verification loop.
**Planned:**
- Port MCP server from figma-use (117 tools)
+- CLI & Headless Mode: attached mode (WebSocket to running editor for eval, create, export, screenshot) and headless mode (engine in Bun/Node for lint, analysis, .fig validation in CI)
+- Package extraction: core/ (engine without rendering), cli/, mcp/
- Design guidelines system
- AI-driven design workflow via MCP
- Screenshot verification loop
diff --git a/docs/guide/features.md b/docs/guide/features.md
index 6eb0d5bf9..fa6552420 100644
--- a/docs/guide/features.md
+++ b/docs/guide/features.md
@@ -126,7 +126,7 @@ Right-clicking a node selects it first. Right-clicking empty canvas clears selec
## Desktop App
-Tauri v2 shell (~5MB vs Electron's ~100MB). Native menu bar with File/Edit/View/Object/Window/Help menus on all platforms. macOS gets an app-level submenu. Native Save/Open dialogs via Tauri plugin-dialog. Zstd compression offloaded to Rust for .fig export performance. Developer Tools accessible via ⌘⌥I.
+Tauri v2 shell (~5MB vs Electron's ~100MB). Works fully offline — no account, no server, no internet required. Native menu bar with File/Edit/View/Object/Window/Help menus on all platforms. macOS gets an app-level submenu. Native Save/Open dialogs via Tauri plugin-dialog. Zstd compression offloaded to Rust for .fig export performance. Developer Tools accessible via ⌘⌥I.
## ScrubInput
diff --git a/docs/guide/figma-comparison.md b/docs/guide/figma-comparison.md
index 07e84504b..b17d71b4d 100644
--- a/docs/guide/figma-comparison.md
+++ b/docs/guide/figma-comparison.md
@@ -208,7 +208,7 @@ Feature-by-feature comparison of Figma Design capabilities with Open Pencil's cu
| Code Connect | 🔲 | Link design components to code |
| Code snippets | 🔲 | Auto-generated code from layers |
| Figma for VS Code | 🔲 | Editor plugin integration |
-| MCP server | 🔲 | Planned for Phase 5; 117-tool MCP server from figma-use |
+| MCP server | 🔲 | Planned for Phase 5; 117-tool MCP server from figma-use. CLI & headless mode planned for AI agent and CI integration |
## Figma Draw
diff --git a/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/.openspec.yaml b/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/.openspec.yaml
new file mode 100644
index 000000000..b51d4740b
--- /dev/null
+++ b/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/.openspec.yaml
@@ -0,0 +1 @@
+type: change
diff --git a/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/design.md b/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/design.md
new file mode 100644
index 000000000..69e77f0c7
--- /dev/null
+++ b/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/design.md
@@ -0,0 +1,15 @@
+# Design: Sync AGENTS.md, CLI Plan, Identifier Fix
+
+## Approach
+
+Documentation-only change. Update specs and docs to match master.
+
+## Delta-Specs
+
+### desktop-app
+- Update app identifier to `net.dannote.open-pencil`
+
+### vitepress-docs
+- Add AGENTS.md mention to contributing docs
+- Add CLI & Headless Mode to roadmap as planned feature
+- Update docs index hero or features to align with README messaging
diff --git a/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/proposal.md b/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/proposal.md
new file mode 100644
index 000000000..520852ee3
--- /dev/null
+++ b/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/proposal.md
@@ -0,0 +1,16 @@
+# Proposal: Sync AGENTS.md, CLI Plan, Identifier Fix
+
+## Why
+
+8 commits merged from master (70c88dd..7ff16f7) add AI agent conventions (AGENTS.md), CLI & Headless Mode plan in PLAN.md, README updates (screenshot, feature list, offline messaging), and a Tauri app identifier fix.
+
+## What Changes
+
+### Implemented
+1. **App identifier fix** — changed from `com.dannote.open-pencil-app` to `net.dannote.open-pencil` in tauri.conf.json
+2. **AGENTS.md** — coding conventions file for AI agents (commands, code style, rendering, scene graph, components, layout, UI, file format, Tauri conventions, figma-use reference, known issues)
+3. **README updates** — added screenshot, components & instances in feature list, system fonts, gradients, ~5 MB offline messaging
+
+### Planned (in PLAN.md, not yet implemented)
+4. **CLI & Headless Mode** — attached mode (WebSocket to running editor) and headless mode (engine in Bun/Node without GUI). Package structure: core/, cli/, mcp/. Commands: eval, find, lint, export, node get/tree, create, set, analyze, screenshot.
+5. **Yoga CSS Grid tracking** — upstream PR details (facebook/yoga#1893–#1902)
diff --git a/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/specs/desktop-app/spec.md b/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/specs/desktop-app/spec.md
new file mode 100644
index 000000000..ceb341c29
--- /dev/null
+++ b/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/specs/desktop-app/spec.md
@@ -0,0 +1,6 @@
+# desktop-app Specification (delta)
+
+## Modified Requirements
+
+### Requirement: Tauri v2 desktop shell (updated)
+The app identifier SHALL be `net.dannote.open-pencil` (was `com.dannote.open-pencil-app`).
diff --git a/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/specs/vitepress-docs/spec.md b/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/specs/vitepress-docs/spec.md
new file mode 100644
index 000000000..39db5d691
--- /dev/null
+++ b/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/specs/vitepress-docs/spec.md
@@ -0,0 +1,9 @@
+# vitepress-docs Specification (delta)
+
+## New Requirements
+
+### Requirement: AGENTS.md reference in contributing docs
+The contributing documentation SHALL mention AGENTS.md as the AI agent coding conventions reference. Developers and agents working on the codebase should read AGENTS.md for rendering, scene graph, component, layout, UI, and file format conventions.
+
+### Requirement: CLI & Headless Mode in roadmap
+The roadmap SHALL include CLI & Headless Mode as a planned feature under Phase 5 (AI Integration): attached mode (WebSocket to running editor for eval, create, export, screenshot) and headless mode (engine in Bun/Node for lint, analysis, validation in CI). Package extraction: core/ (engine without rendering), cli/, mcp/.
diff --git a/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/tasks.md b/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/tasks.md
new file mode 100644
index 000000000..b903ec76c
--- /dev/null
+++ b/openspec/changes/archive/2026-03-01-sync-agents-cli-plan/tasks.md
@@ -0,0 +1,18 @@
+# Tasks: Sync AGENTS.md, CLI Plan, Identifier Fix
+
+Reference: 8 commits from master (70c88dd..7ff16f7).
+
+## 1. Update OpenSpec Specs
+
+- [x] 1.1 Update `openspec/specs/desktop-app/spec.md` — update app identifier to `net.dannote.open-pencil`.
+
+## 2. Update VitePress Docs
+
+- [x] 2.1 Update `docs/development/contributing.md` — add AGENTS.md reference for AI agent conventions.
+- [x] 2.2 Update `docs/development/roadmap.md` — add CLI & Headless Mode to Phase 5 Planned (attached + headless modes, core/ extraction, CLI commands).
+- [x] 2.3 Update `docs/guide/features.md` — add offline/lightweight messaging to Desktop App section to align with README.
+- [x] 2.4 Update `docs/guide/figma-comparison.md` — update "Keyboard shortcuts" notes to reflect fixed Mac modifier shortcuts. Add AGENTS.md/CLI note under "MCP server" row.
+
+## 3. Verify
+
+- [x] 3.1 Run `bun run docs:build` to verify VitePress build passes.
diff --git a/openspec/specs/desktop-app/spec.md b/openspec/specs/desktop-app/spec.md
index a0d3b229e..f8d330ed4 100644
--- a/openspec/specs/desktop-app/spec.md
+++ b/openspec/specs/desktop-app/spec.md
@@ -4,7 +4,7 @@
Tauri v2 desktop shell. Cross-platform native menu bar with wired events, Developer Tools access, and `desktop/` directory structure for Tauri configuration and Rust source.
## Requirements
### Requirement: Tauri v2 desktop shell
-The editor SHALL run as a native desktop app via Tauri v2 with the web frontend loaded in a webview.
+The editor SHALL run as a native desktop app via Tauri v2 with the web frontend loaded in a webview. The app identifier SHALL be `net.dannote.open-pencil`.
#### Scenario: Desktop app launch
- **WHEN** user runs `bun run tauri dev`