@xenonbyte/da-vinci-workflow 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 - No unreleased changes yet.
 
+## v0.1.11 - 2026-03-27
+
+### Changed
+- Da Vinci now documents `design-source checkpoint` between design review and page-to-Pencil mapping so project-local `.pen` persistence is verified before implementation work proceeds
+- project-local `.pen` paths in `design-registry.md` are now defined more explicitly as workflow-owned state rather than user-authored config
+- Pencil workflow guidance now requires the registered `.pen` path, the active editor source, and the shell-visible project file to reconcile before mapping or implementation is treated as safe
+- workflow examples and mode guides now show project-local `.pen` reconciliation as part of redesign execution rather than an optional cleanup step
+
 ## v0.1.10 - 2026-03-27
 
 ### Changed

package/README.md

@@ -252,9 +252,10 @@ Da Vinci uses these checkpoints:
 1. `discovery checkpoint`
 2. `spec checkpoint`
 3. `design checkpoint`
-4. `mapping checkpoint`
-5. `task checkpoint`
-6. `execution checkpoint`
+4. `design-source checkpoint`
+5. `mapping checkpoint`
+6. `task checkpoint`
+7. `execution checkpoint`
 
 Checkpoint outcomes:
 
@@ -299,6 +300,10 @@ Rules:
 - `pencil-bindings.md` is the source of truth for implementation page -> Pencil page mapping
 - in `redesign-from-code`, existing code is behavior truth, not layout truth
 - complex pages should be decomposed into subpages, states, overlays, and implementation surfaces before Pencil redesign is treated as final
+- the preferred `.pen` path recorded in `design-registry.md` is workflow-owned state, not user-authored config
+- when Pencil work starts, Da Vinci should use or create that exact project-local `.pen` path instead of relying on whichever Pencil document happens to be active
+- if Pencil MCP edits a live document but does not materialize the shell-visible project file automatically, the workflow should reconstruct and write the `.pen` file under the registered path before treating the design pass as traceable
+- before `pencil-bindings.md` or implementation tasks are treated as safe, `design-source checkpoint` should confirm that the registered path, the active Pencil source, and the shell-visible `.pen` file converge on the same project-local source
 
 Optional visual-adapter policy:
 
@@ -318,18 +323,19 @@ When a relevant mapping already exists:
 
 - iterate on the mapped Pencil source
 - prefer the project-local `.pen` path already registered in `design-registry.md`
+- do not silently switch to a different active editor path without reconciling `design-registry.md`
 
 When mappings do not exist but local code exists:
 
 - reconstruct the baseline from the local project
 - rebuild inventory, page map, and design registry
 - decompose complex containers into real design surfaces before broad Pencil generation
-- save or export the rebuilt Pencil baseline into `.da-vinci/designs/` when possible
+- resolve an exact project-local `.pen` target and materialize that file under `.da-vinci/designs/`
 
 When neither mappings nor usable design sources exist:
 
 - create a new Pencil baseline from the current local source of truth
-- persist that baseline under `.da-vinci/designs/` when possible and record the exact path in `design-registry.md`
+- persist that baseline under `.da-vinci/designs/` and record the exact path in `design-registry.md`
 
 ## Design input collection
 
@@ -508,6 +514,7 @@ Continue into full-delivery.
 See:
 
 - `docs/prompt-entrypoints.md`
+- `docs/prompt-presets/`
 - `docs/codex-natural-language-usage.md`
 - `docs/visual-adapters.md`
 - `docs/visual-assist-presets/`
@@ -519,6 +526,7 @@ See:
 Chinese companion documents are included in this repository:
 
 - `README.zh-CN.md`
+- `docs/zh-CN/prompt-presets/`
 - `docs/zh-CN/visual-adapters.md`
 - `docs/zh-CN/visual-assist-presets/`
 - `docs/zh-CN/`

package/README.zh-CN.md

@@ -252,6 +252,10 @@ project/
 - `pencil-bindings.md` 是实现页面到 Pencil 页面绑定的真相源
 - 在 `redesign-from-code` 里，现有代码只是真相行为，不是真相布局
 - 复杂页面在 Pencil 重设计前应该先拆成 subpage、state、overlay 和 implementation surface
+- `design-registry.md` 里登记的首选 `.pen` 路径属于工作流自动维护的状态，不应该依赖用户手工填写
+- 一旦进入 Pencil 设计，Da Vinci 应该使用或创建这个项目内 `.pen` 路径，而不是继续沿用当前随手打开的 Pencil 文档
+- 如果 Pencil MCP 修改了 live 文档但没有自动把项目内 `.pen` 文件落到磁盘，工作流应该先把该 `.pen` 文件补写到登记路径，再把这轮设计当成可追踪结果
+- 在进入 `pencil-bindings.md` 和实现任务前，应该先通过 `design-source checkpoint`，确认登记路径、当前设计源和 shell 可见 `.pen` 文件已经收敛成同一个项目级来源
 
 可选 visual adapter 规则：
 
@@ -271,18 +275,19 @@ project/
 
 - 优先复用已绑定的 Pencil 设计源
 - 如果 `design-registry.md` 里已经登记了 `.da-vinci/designs/` 下的本地 `.pen` 路径，优先使用它
+- 不要在没有同步 `design-registry.md` 的情况下，悄悄切到另一个当前活动编辑器路径继续设计
 
 当已有代码存在但还没有映射时：
 
 - 先从当前项目重建设计基线
 - 重建 inventory、page-map、design-registry
 - 先把复杂容器拆成真实的设计 surface，再进入大规模 Pencil 设计
-- 在可行时把新的 Pencil 基线保存或导出到 `.da-vinci/designs/`
+- 先解析出明确的项目内 `.pen` 目标路径，再把新的 Pencil 基线真正落到 `.da-vinci/designs/`
 
 当既没有映射也没有可用设计源时：
 
 - 基于当前本地真相源创建新的 Pencil 基线
-- 在可行时把基线保存到 `.da-vinci/designs/`
+- 把基线落到 `.da-vinci/designs/`
 - 并在 `design-registry.md` 里记录准确路径
 
 如果项目声明了 visual adapter：
@@ -422,6 +427,7 @@ Continue into full-delivery.
 
 - `docs/codex-natural-language-usage.md`
 - `docs/prompt-entrypoints.md`
+- `docs/prompt-presets/`
 - `docs/visual-adapters.md`
 - `docs/visual-assist-presets/`
 - `docs/workflow-examples.md`
@@ -431,6 +437,7 @@ Continue into full-delivery.
 中文文档：
 
 - `README.zh-CN.md`
+- `docs/zh-CN/prompt-presets/`
 - `docs/zh-CN/visual-adapters.md`
 - `docs/zh-CN/visual-assist-presets/`
 - `docs/zh-CN/`

package/SKILL.md

@@ -400,6 +400,18 @@ Use `design-registry.md` as the project-level inventory of `.pen` sources.
 
 Use `.da-vinci/designs/` as the default project-local location for persisted Pencil files when the workflow creates or updates them.
 
+Treat the project-local `.pen` path recorded in `design-registry.md` as workflow-owned state.
+
+- users may provide external references or existing `.pen` files
+- the workflow, not the user, resolves and maintains the preferred project-local `.pen` path
+- do not treat `design-registry.md` as a user-authored config file
+
+Resolve one exact project-local target before broad Pencil work begins:
+
+- `.da-vinci/designs/project-baseline.pen` for shared baseline reconstruction
+- `.da-vinci/designs/<change-id>.pen` for change-specific redesign work
+- `.da-vinci/designs/<change-id>/main.pen` only when the project truly needs a nested design bundle
+
 Use `DA-VINCI.md` as the project-level visual source of truth for:
 
 - theme and palette
@@ -420,6 +432,7 @@ When a relevant mapping already exists:
 - iterate on the mapped Pencil source
 - prefer the project-local `.pen` file under `.da-vinci/designs/` when one is already registered
 - do not create a new design baseline unless there is a reason
+- do not silently keep designing in an unrelated active Pencil document when `design-registry.md` already names a preferred path
 
 When `DA-VINCI.md` already exists:
 
@@ -431,6 +444,7 @@ When page-to-Pencil bindings already exist:
 
 - update the mapped Pencil page for the affected implementation page
 - keep the exact `.pen` file path recorded in `design-registry.md`
+- if the active Pencil editor path differs from that recorded path, switch to the recorded path or explicitly reconstruct the project-local file before continuing
 
 When project mappings do not exist but existing code exists:
 
@@ -438,21 +452,22 @@ When project mappings do not exist but existing code exists:
 - reconstruct `project-inventory.md`
 - reconstruct `page-map.md`
 - create or rebuild `design-registry.md`
+- resolve the exact project-local `.pen` target path before broad Pencil work starts
 - generate a new Pencil baseline only after the inventory is stable
-- save or export that baseline into `.da-vinci/designs/` when possible
+- materialize that baseline into the resolved `.da-vinci/designs/` path and record the exact file in `design-registry.md`
 
 When neither mappings nor usable design sources exist:
 
 - state that the project is entering baseline reconstruction
 - create a new Pencil baseline from the current local source of truth
 - generate `DA-VINCI.md` from inferred or user-provided design rules before generating many unrelated pages
-- persist the resulting `.pen` file in `.da-vinci/designs/` when possible and record the path in `design-registry.md`
+- persist the resulting `.pen` file at the resolved `.da-vinci/designs/` path and record that exact path in `design-registry.md`
 
 When a Pencil session cannot yet be exported locally:
 
 - record the live or external source in `design-registry.md`
-- record why local persistence is pending
-- do not hide the lack of a project-local `.pen` path
+- reconstruct and write the project-local `.pen` file from MCP-readable document data before closing mapping or implementation work
+- if the project-local file still cannot be materialized, record the reason and treat the missing file as a checkpoint issue instead of silently continuing
 
 When visual adapters are requested:
 
@@ -499,6 +514,8 @@ When creating or editing Pencil designs:
 - Build the pages required by the current scope, not an abstract moodboard
 - follow `page-map.md` as the canonical page list
 - follow `design-brief.md` for form factor and visual direction when it exists
+- use the workflow-owned `.pen` path from `design-registry.md` as the active design target
+- do not keep designing in whichever Pencil document happens to be open unless it already matches the registered project-local path
 - use the resolved visual adapter, when available, for composition, hierarchy, restraint, and motion guidance
 - before broad page generation, write a visual thesis, a content plan, and an interaction thesis for the current surface
 - Keep page names, section names, and labels aligned with the specs
@@ -513,18 +530,24 @@ When multiple pages exist:
 - keep one canonical Pencil page or screen per implementation page
 - record the `.pen` file in `design-registry.md`
 - record the mapping in `pencil-bindings.md`
-- persist the active `.pen` file into `.da-vinci/designs/` before closing design work when possible
+- ensure the active Pencil design is materialized into the registered `.da-vinci/designs/` file before closing design work
 
 ## Pencil MCP Rules
 
 When Pencil is available through MCP:
 
 - Prefer the project-local `.pen` file under `.da-vinci/designs/` when one is registered
+- Treat the registered `.pen` path as authoritative; do not rely on the current active editor if its path does not match `design-registry.md`
+- If the registered file exists, read and edit that exact file
+- If the registered file does not yet exist, create or reconstruct the project-local file before treating the design pass as traceable
 - Read the active `.pen` file and page structure before coding
 - read the bound Pencil page for the current implementation page
 - Use Pencil data to extract layout, text, hierarchy, panels, buttons, and content regions
 - Use screenshots only as a secondary visual check
 - Treat Pencil as the design data source for presentation, spacing, and layout grouping
+- Before mapping or implementation closes, verify both:
+  - the `.pen` path is readable through MCP
+  - the same path exists as a shell-visible file inside the project
 
 When Pencil is not available:
 
@@ -564,15 +587,19 @@ Run these checkpoints:
    - after Pencil design exists, before implementation tasks are locked
    - verify the design covers the required pages, states, and key interactions
 
-4. `mapping checkpoint`
+4. `design-source checkpoint`
+   - after `design-registry.md` resolves the preferred project-local `.pen` path and active Pencil work exists
+   - verify the registered `.pen` path, the active Pencil editor, and shell-visible persistence agree before mapping continues
+
+5. `mapping checkpoint`
    - after `design-registry.md` and `pencil-bindings.md`
    - verify implementation pages and Pencil pages are bound correctly
 
-5. `task checkpoint`
+6. `task checkpoint`
    - before implementation starts
    - verify tasks cover both requirements and Pencil-backed UI work
 
-6. `execution checkpoint`
+7. `execution checkpoint`
    - after each top-level task group during implementation
    - verify code still matches requirements and Pencil structure
 

package/docs/codex-natural-language-usage.md

@@ -69,6 +69,10 @@ Supported modes:
 
 ## Scenario Recipes
 
+For surface-specific prompt starting points, also see:
+
+- `docs/prompt-presets/`
+
 ### 1. New project with clear requirements
 
 ```text

package/docs/mode-use-cases.md

@@ -129,7 +129,7 @@ Generate DA-VINCI.md, proposal, specs, page map, Pencil-backed launch pages, bin
    - define the canonical pages and page responsibilities
 
 6. create `design-registry.md`
-   - register the active `.pen` source once Pencil work starts
+   - resolve the workflow-owned project-local `.pen` path once Pencil work starts
    - prefer a project-local `.pen` path under `.da-vinci/designs/`
 
 7. create `design.md`
@@ -137,7 +137,7 @@ Generate DA-VINCI.md, proposal, specs, page map, Pencil-backed launch pages, bin
 
 8. create `pencil-design.md`
    - record the generated Pencil screens
-   - save or export the active `.pen` file into `.da-vinci/designs/` when possible
+   - ensure the active design is materialized into the registered `.pen` path under `.da-vinci/designs/`
 
 9. create `pencil-bindings.md`
    - map implementation pages to Pencil pages
@@ -226,7 +226,7 @@ First synthesize the product direction, then generate DA-VINCI.md, specs, page m
    - `pencil-design.md`
    - `pencil-bindings.md`
    - `tasks.md`
-   - persist the active `.pen` file into `.da-vinci/designs/` when possible
+   - persist the active design into the registered `.pen` path under `.da-vinci/designs/`
 
 ### Where this mode differs from `greenfield-spec`
 
@@ -313,6 +313,7 @@ Register the design sources, extract DA-VINCI.md from them, bind covered pages,
 
 3. create or update `design-registry.md`
    - register old and new `.pen` sources
+   - resolve one workflow-owned project-local `.pen` path for the redesign
    - mark the preferred project-local `.pen` file under `.da-vinci/designs/` when available
 
 4. create or update `page-map.md`
@@ -323,7 +324,7 @@ Register the design sources, extract DA-VINCI.md from them, bind covered pages,
 
 6. create or update `pencil-design.md`
    - build the new redesign baseline in Pencil
-   - persist that baseline into `.da-vinci/designs/` when possible
+   - persist that baseline into the registered `.da-vinci/designs/` file
 
 7. create or update `pencil-bindings.md`
    - bind pages to redesign screens
@@ -351,6 +352,12 @@ Fresh-layout rule:
 - do not treat the old UI as the design baseline unless the user explicitly asks to preserve the layout skeleton
 - a recolor, light rearrangement, or minor spacing pass on the old UI is not enough for a true redesign
 
+Project-local `.pen` rule:
+
+- the preferred `.pen` path in `design-registry.md` is owned by the workflow, not by user hand-editing
+- do not keep redesign work inside an unrelated active Pencil editor just because it is currently open
+- if Pencil MCP does not materialize the registered shell-visible file automatically, reconstruct and write that `.pen` file before mapping or implementation is treated as complete
+
 Complex-surface rule:
 
 - if one screen contains multiple fragments, tabs, overlays, or materially different states, split it into multiple design surfaces

package/docs/prompt-entrypoints.md

@@ -76,6 +76,10 @@ Do not default this sequence to `build`.
 
 ## Platform Syntax
 
+For ready-to-copy surface-specific starting prompts, see:
+
+- `docs/prompt-presets/`
+
 ### Codex
 
 Use:

package/docs/prompt-presets/README.md

@@ -0,0 +1,27 @@
+# Prompt Presets
+
+Use these presets when you want a copy-ready starting prompt for a specific product surface.
+
+These presets are designed to pair with:
+
+- `docs/visual-assist-presets/`
+
+Recommended flow:
+
+1. choose the prompt preset closest to the product surface
+2. choose the matching `Visual Assist` preset
+3. copy both into your workflow setup
+4. tighten the prompt further only when the project has unusual truth sources or platform constraints
+
+Available presets:
+
+- `mobile-app.md`
+- `desktop-app.md`
+- `web-app.md`
+- `tablet-app.md`
+
+Design rule:
+
+- prompt presets define workflow intent, decomposition rules, and truth-source handling
+- visual-assist presets define UI-design helper preferences
+- use both together for the strongest result

package/docs/prompt-presets/desktop-app.md

@@ -0,0 +1,46 @@
+# Desktop App Prompt Preset
+
+Recommended when the product is a desktop-first tool or workspace.
+
+Pair with:
+
+- `docs/visual-assist-presets/desktop-app.md`
+
+Use this when the workflow needs:
+
+- dense workspace hierarchy
+- clear tool panels and primary working surfaces
+- disciplined modal and secondary-panel treatment
+- decomposition of complex screens into meaningful surfaces
+
+Recommended prompt:
+
+```text
+$da-vinci use redesign-from-code to redesign this existing desktop product.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve behavior, flows, integrations, and validation rules unless explicitly required otherwise.
+Inventory primary workspaces, side panels, secondary panels, dialogs, settings flows, overlays, and important states before broad Pencil work.
+Decompose complex screens into primary surfaces, secondary surfaces, overlays, and materially different states.
+Use the Visual Assist preferences declared in DA-VINCI.md.
+Do not pass design checkpoint if the result is just a boxed-up recolor of the old UI or if panel hierarchy remains unclear.
+Persist project-local Pencil files under .da-vinci/designs/.
+```
+
+When to switch to `intake` first:
+
+- the desktop architecture is large
+- modules and workspace boundaries are unclear
+- there are multiple existing design references or mixed product surfaces
+
+`intake` variant:
+
+```text
+$da-vinci use intake for this existing desktop product.
+
+I need to redesign the UI while preserving current behavior.
+Existing code is the behavior source of truth, not the layout truth.
+Inventory workspaces, panels, dialogs, overlays, settings flows, and important states.
+Decompose complex screens before Pencil work.
+Generate the best executable Da Vinci workflow prompt for the next step.
+```

package/docs/prompt-presets/mobile-app.md

@@ -0,0 +1,46 @@
+# Mobile App Prompt Preset
+
+Recommended when the project is a phone-first product surface.
+
+Pair with:
+
+- `docs/visual-assist-presets/mobile-app.md`
+
+Use this when the workflow needs:
+
+- app-first hierarchy
+- touch-first interaction surfaces
+- strong state decomposition
+- clear treatment of sheets, dialogs, tabs, and nested navigation
+
+Recommended prompt:
+
+```text
+$da-vinci use redesign-from-code to redesign this existing mobile app.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve business logic, navigation, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
+Inventory routes, screens, tabs, dialogs, bottom sheets, nested flows, and important states before broad Pencil work.
+Decompose complex screens into subpages, overlays, materially different states, and implementation surfaces.
+Use the Visual Assist preferences declared in DA-VINCI.md.
+Do not pass design checkpoint if the result is a skin-swap of the old UI, a generic card grid, or a weak mobile hierarchy.
+Persist project-local Pencil files under .da-vinci/designs/.
+```
+
+When to switch to `intake` first:
+
+- the project has multiple truth sources
+- the UI stack is unclear
+- the redesign spans many modules and the first workflow prompt is hard to phrase
+
+`intake` variant:
+
+```text
+$da-vinci use intake for this existing mobile app.
+
+I need to redesign the UI while preserving current behavior.
+Existing code is the behavior source of truth, not the layout truth.
+Inventory screens, tabs, dialogs, bottom sheets, nested flows, and important states.
+Decompose complex screens before Pencil work.
+Generate the best executable Da Vinci workflow prompt for the next step.
+```

package/docs/prompt-presets/tablet-app.md

@@ -0,0 +1,46 @@
+# Tablet App Prompt Preset
+
+Recommended when the product is tablet-first or relies on expanded touch surfaces.
+
+Pair with:
+
+- `docs/visual-assist-presets/tablet-app.md`
+
+Use this when the workflow needs:
+
+- split-pane or multi-column composition
+- orientation-aware design thinking
+- decomposition of tool surfaces, side regions, and overlays
+- treatment of both touch-first and canvas-first interaction patterns
+
+Recommended prompt:
+
+```text
+$da-vinci use redesign-from-code to redesign this existing tablet product.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve behavior, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
+Inventory split-pane regions, sidebars, expanded canvases, dialogs, sheets, orientation-driven changes, and important states before broad Pencil work.
+Decompose complex pages into multi-region surfaces, overlays, materially different states, and implementation surfaces.
+Use the Visual Assist preferences declared in DA-VINCI.md.
+Do not pass design checkpoint if the result ignores tablet-scale composition or collapses into a stretched phone layout.
+Persist project-local Pencil files under .da-vinci/designs/.
+```
+
+When to switch to `intake` first:
+
+- the product has both phone and tablet surfaces
+- orientation or multi-pane logic is complicated
+- the design references do not map cleanly to the real implementation surfaces
+
+`intake` variant:
+
+```text
+$da-vinci use intake for this existing tablet product.
+
+I need to redesign the UI while preserving current behavior.
+Existing code is the behavior source of truth, not the layout truth.
+Inventory split-pane regions, sidebars, dialogs, sheets, orientation changes, and important states.
+Decompose complex pages before Pencil work.
+Generate the best executable Da Vinci workflow prompt for the next step.
+```

package/docs/prompt-presets/web-app.md

@@ -0,0 +1,47 @@
+# Web App Prompt Preset
+
+Recommended when the product is a browser-based application or product website with app-like surfaces.
+
+Pair with:
+
+- `docs/visual-assist-presets/web-app.md`
+
+Use this when the workflow needs:
+
+- responsive page hierarchy
+- separation between marketing and product surfaces
+- careful handling of empty, loading, error, and authenticated states
+- decomposition of complex flows into real surfaces instead of one oversized page
+
+Recommended prompt:
+
+```text
+$da-vinci use redesign-from-code to redesign this existing web product.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve current business logic, routes, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
+Inventory responsive surfaces, authenticated areas, settings pages, dialogs, drawers, overlays, and important states before broad Pencil work.
+Separate marketing-style surfaces from product-workflow surfaces when they require different visual treatment.
+Decompose complex pages into subpages, overlays, materially different states, and implementation surfaces.
+Use the Visual Assist preferences declared in DA-VINCI.md.
+Do not pass design checkpoint if the result is a generic SaaS card grid or a recolor of the old interface.
+Persist project-local Pencil files under .da-vinci/designs/.
+```
+
+When to switch to `intake` first:
+
+- the product mixes marketing, auth, onboarding, and app surfaces
+- the first workflow prompt is hard to phrase cleanly
+- there are external design references that must stay subordinate to existing behavior
+
+`intake` variant:
+
+```text
+$da-vinci use intake for this existing web product.
+
+I need to redesign the UI while preserving current behavior.
+Existing code is the behavior source of truth, not the layout truth.
+Inventory product surfaces, marketing surfaces, overlays, and important states.
+Decompose complex pages before Pencil work.
+Generate the best executable Da Vinci workflow prompt for the next step.
+```

package/docs/visual-assist-presets/README.md

@@ -9,6 +9,10 @@ Each preset is intentionally conservative:
 - clear scope boundaries
 - non-blocking behavior by default
 
+Use them together with:
+
+- `docs/prompt-presets/`
+
 If the project is design-critical or previous outputs were weak, generic, or too close to the old UI:
 
 - keep the same preset family

package/docs/workflow-examples.md

@@ -80,9 +80,10 @@ Expected flow:
 5. split broad redesign work into `specs/<slice>/spec.md` files when one large `ui-refresh` spec would be too coarse
 6. rebuild or refine `page-map.md`, including subpages, overlays, and materially different states
 7. create new or updated Pencil pages from fresh composition rather than a recolor of the old UI, preferring persistence under `.da-vinci/designs/`
-8. bind routes and pages to Pencil screens
-9. generate tasks aligned to the redesign slices
-10. build and verify
+8. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
+9. bind routes and pages to Pencil screens
+10. generate tasks aligned to the redesign slices
+11. build and verify
 
 ### Complex Android example
 

package/docs/zh-CN/codex-natural-language-usage.md

@@ -70,6 +70,10 @@ $da-vinci use <mode> to <goal>
 
 ## 场景模板
 
+如果你想直接按产品形态选提示词，也可以看：
+
+- `docs/zh-CN/prompt-presets/`
+
 ### 1. 新项目，需求清晰
 
 ```text

package/docs/zh-CN/mode-use-cases.md

@@ -86,10 +86,11 @@ Da Vinci 应该：
 4. 生成 `specs/<capability>/spec.md`
 5. 生成 `page-map.md`
 6. 生成 `design-registry.md`
+   - 先解析出工作流自动维护的项目内 `.pen` 路径
    - 优先登记 `.da-vinci/designs/` 下的本地 `.pen` 路径
 7. 生成 `design.md`
 8. 生成 `pencil-design.md`
-   - 在可行时把当前 `.pen` 文件保存或导出到 `.da-vinci/designs/`
+   - 确保当前设计真正落到登记好的 `.da-vinci/designs/` 路径
 9. 生成 `pencil-bindings.md`
 10. 生成 `tasks.md`
 11. 进入实现
@@ -110,7 +111,7 @@ Da Vinci 应该：
 5. 生成 `specs/<capability>/spec.md`
 6. 生成 `page-map.md`
 7. 继续到设计、绑定、任务和实现
-   - 在可行时把当前 `.pen` 文件保存或导出到 `.da-vinci/designs/`
+   - 把当前设计真正落到登记好的 `.da-vinci/designs/` 路径
 
 ## 3. `redesign-from-code`
 
@@ -126,13 +127,14 @@ Da Vinci 应该：
 2. 生成或对齐 `DA-VINCI.md`
 3. 生成 `design-registry.md`
    - 如已有本地 `.pen` 文件，优先登记 `.da-vinci/designs/` 下的路径
+   - 为这次重设计解析一个工作流自动维护的项目内 `.pen` 路径
 4. 生成 `proposal.md`
 5. 按 redesign slice 拆分 `specs/`
 6. 重建或更新 `page-map.md`
    - 把复杂页面拆成 subpage、state、overlay、fragment surface
 7. 生成 `design.md`
 8. 生成 `pencil-design.md`
-   - 在可行时把新的 Pencil 基线持久化到 `.da-vinci/designs/`
+   - 把新的 Pencil 基线真正落到登记好的 `.da-vinci/designs/` 路径
 9. 生成 `pencil-bindings.md`
 10. 生成 `tasks.md`
 11. 进入实现
@@ -143,6 +145,9 @@ Da Vinci 应该：
 - `redesign-from-code` 默认应该基于页面职责和状态重新构图
 - 不能把“旧页面换个配色、换点间距、挪一点位置”当成真正的重设计
 - 一个实现页如果包含多个 Fragment、多个 tab、多个状态或多个 overlay，应该拆成多个设计 surface
+- `design-registry.md` 里的首选 `.pen` 路径由工作流自动维护，不应该依赖用户手工填写
+- 不要因为当前 Pencil 里正好打开了一个文档，就直接在那个文档上继续做重设计
+- 如果 Pencil MCP 没有自动把登记路径的 `.pen` 文件落到磁盘，就应该先补写这个项目内文件，再把 mapping 或 implementation 视为完成
 
 ## 4. `feature-change`
 
@@ -158,7 +163,7 @@ Da Vinci 应该：
 4. 复用或更新 `design-registry.md`
    - 如果已有项目内 `.pen` 文件，优先登记 `.da-vinci/designs/` 下的路径
 5. 生成 `pencil-design.md` 增量
-   - 在可行时把更新后的 `.pen` 文件保存或导出到 `.da-vinci/designs/`
+   - 把更新后的 `.pen` 文件真正落到登记好的 `.da-vinci/designs/` 路径
 6. 更新 `pencil-bindings.md`
 7. 生成 `tasks.md`
 8. 进入实现

package/docs/zh-CN/prompt-entrypoints.md

@@ -77,6 +77,10 @@
 
 ## 平台语法
 
+如果你只想直接复制不同场景的起始提示词，也可以看：
+
+- `docs/zh-CN/prompt-presets/`
+
 ### Codex
 
 ```text

package/docs/zh-CN/prompt-presets/README.md

@@ -0,0 +1,27 @@
+# 场景提示词模板
+
+这些模板用于在不同产品形态下，快速拿到可直接执行的起始提示词。
+
+它们建议和下面这组文档配合使用：
+
+- `docs/zh-CN/visual-assist-presets/`
+
+推荐使用方式：
+
+1. 先选最接近产品形态的提示词模板
+2. 再选对应的 `Visual Assist` 模板
+3. 两者一起放进工作流设置
+4. 只有在项目存在特殊真相源或平台约束时，再继续收紧提示词
+
+可用模板：
+
+- `mobile-app.md`
+- `desktop-app.md`
+- `web-app.md`
+- `tablet-app.md`
+
+设计规则：
+
+- 提示词模板负责定义工作流意图、拆分规则和真相源处理方式
+- `Visual Assist` 模板负责定义 UI 设计增强偏好
+- 两者一起使用，结果通常更稳

package/docs/zh-CN/prompt-presets/desktop-app.md

@@ -0,0 +1,46 @@
+# 桌面端应用提示词模板
+
+适用于桌面优先的工具型或工作台型产品。
+
+建议搭配：
+
+- `docs/zh-CN/visual-assist-presets/desktop-app.md`
+
+适合这种需求：
+
+- 高密度工作区层级
+- 明确的工具面板和主工作面
+- 克制的 modal 和 secondary panel 处理
+- 把复杂页面拆成真正有意义的 surface
+
+推荐提示词：
+
+```text
+$da-vinci use redesign-from-code to redesign this existing desktop product.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve behavior, flows, integrations, and validation rules unless explicitly required otherwise.
+Inventory primary workspaces, side panels, secondary panels, dialogs, settings flows, overlays, and important states before broad Pencil work.
+Decompose complex screens into primary surfaces, secondary surfaces, overlays, and materially different states.
+Use the Visual Assist preferences declared in DA-VINCI.md.
+Do not pass design checkpoint if the result is just a boxed-up recolor of the old UI or if panel hierarchy remains unclear.
+Persist project-local Pencil files under .da-vinci/designs/.
+```
+
+什么时候先走 `intake`：
+
+- 桌面端架构较大
+- 模块和 workspace 边界不够清晰
+- 存在多个设计参考源或混合产品形态
+
+`intake` 版本：
+
+```text
+$da-vinci use intake for this existing desktop product.
+
+I need to redesign the UI while preserving current behavior.
+Existing code is the behavior source of truth, not the layout truth.
+Inventory workspaces, panels, dialogs, overlays, settings flows, and important states.
+Decompose complex screens before Pencil work.
+Generate the best executable Da Vinci workflow prompt for the next step.
+```

package/docs/zh-CN/prompt-presets/mobile-app.md

@@ -0,0 +1,46 @@
+# 移动端 App 提示词模板
+
+适用于以手机为主的产品界面。
+
+建议搭配：
+
+- `docs/zh-CN/visual-assist-presets/mobile-app.md`
+
+适合这种需求：
+
+- app-first 的层级结构
+- touch-first 的交互界面
+- 强状态拆分
+- 明确处理 sheets、dialogs、tabs 和 nested navigation
+
+推荐提示词：
+
+```text
+$da-vinci use redesign-from-code to redesign this existing mobile app.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve business logic, navigation, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
+Inventory routes, screens, tabs, dialogs, bottom sheets, nested flows, and important states before broad Pencil work.
+Decompose complex screens into subpages, overlays, materially different states, and implementation surfaces.
+Use the Visual Assist preferences declared in DA-VINCI.md.
+Do not pass design checkpoint if the result is a skin-swap of the old UI, a generic card grid, or a weak mobile hierarchy.
+Persist project-local Pencil files under .da-vinci/designs/.
+```
+
+什么时候先走 `intake`：
+
+- 项目有多个真相源
+- UI 栈不清晰
+- 重设计跨度大，第一条提示词很难一次说对
+
+`intake` 版本：
+
+```text
+$da-vinci use intake for this existing mobile app.
+
+I need to redesign the UI while preserving current behavior.
+Existing code is the behavior source of truth, not the layout truth.
+Inventory screens, tabs, dialogs, bottom sheets, nested flows, and important states.
+Decompose complex screens before Pencil work.
+Generate the best executable Da Vinci workflow prompt for the next step.
+```

package/docs/zh-CN/prompt-presets/tablet-app.md

@@ -0,0 +1,46 @@
+# 平板应用提示词模板
+
+适用于平板优先，或强依赖扩展触控区域的产品。
+
+建议搭配：
+
+- `docs/zh-CN/visual-assist-presets/tablet-app.md`
+
+适合这种需求：
+
+- split-pane 或 multi-column 构图
+- orientation-aware 的设计思路
+- 拆分工具区、侧边区域和 overlays
+- 同时考虑 touch-first 和 canvas-first 的交互
+
+推荐提示词：
+
+```text
+$da-vinci use redesign-from-code to redesign this existing tablet product.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve behavior, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
+Inventory split-pane regions, sidebars, expanded canvases, dialogs, sheets, orientation-driven changes, and important states before broad Pencil work.
+Decompose complex pages into multi-region surfaces, overlays, materially different states, and implementation surfaces.
+Use the Visual Assist preferences declared in DA-VINCI.md.
+Do not pass design checkpoint if the result ignores tablet-scale composition or collapses into a stretched phone layout.
+Persist project-local Pencil files under .da-vinci/designs/.
+```
+
+什么时候先走 `intake`：
+
+- 产品同时有 phone 和 tablet surface
+- orientation 或 multi-pane 逻辑很复杂
+- 设计参考与真实实现 surface 对不上
+
+`intake` 版本：
+
+```text
+$da-vinci use intake for this existing tablet product.
+
+I need to redesign the UI while preserving current behavior.
+Existing code is the behavior source of truth, not the layout truth.
+Inventory split-pane regions, sidebars, dialogs, sheets, orientation changes, and important states.
+Decompose complex pages before Pencil work.
+Generate the best executable Da Vinci workflow prompt for the next step.
+```

package/docs/zh-CN/prompt-presets/web-app.md

@@ -0,0 +1,47 @@
+# Web 应用提示词模板
+
+适用于浏览器中的产品型界面，或带有 app surface 的 Web 产品。
+
+建议搭配：
+
+- `docs/zh-CN/visual-assist-presets/web-app.md`
+
+适合这种需求：
+
+- responsive 页面层级
+- marketing 与 product surface 的区分
+- 明确处理 empty、loading、error、authenticated states
+- 把复杂流程拆成真实的设计 surface，而不是一个大页面
+
+推荐提示词：
+
+```text
+$da-vinci use redesign-from-code to redesign this existing web product.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve current business logic, routes, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
+Inventory responsive surfaces, authenticated areas, settings pages, dialogs, drawers, overlays, and important states before broad Pencil work.
+Separate marketing-style surfaces from product-workflow surfaces when they require different visual treatment.
+Decompose complex pages into subpages, overlays, materially different states, and implementation surfaces.
+Use the Visual Assist preferences declared in DA-VINCI.md.
+Do not pass design checkpoint if the result is a generic SaaS card grid or a recolor of the old interface.
+Persist project-local Pencil files under .da-vinci/designs/.
+```
+
+什么时候先走 `intake`：
+
+- 同时混合 marketing、auth、onboarding 和 app surfaces
+- 第一条提示词很难一次说清
+- 存在外部设计参考，但它们必须服从现有行为真相
+
+`intake` 版本：
+
+```text
+$da-vinci use intake for this existing web product.
+
+I need to redesign the UI while preserving current behavior.
+Existing code is the behavior source of truth, not the layout truth.
+Inventory product surfaces, marketing surfaces, overlays, and important states.
+Decompose complex pages before Pencil work.
+Generate the best executable Da Vinci workflow prompt for the next step.
+```

package/docs/zh-CN/visual-assist-presets/README.md

@@ -9,6 +9,10 @@
 - 清晰的作用范围
 - 默认不阻塞工作流
 
+建议搭配：
+
+- `docs/zh-CN/prompt-presets/`
+
 如果项目对设计质量要求很高，或者之前结果很普通、很丑、太像旧 UI：
 
 - 仍然先选对应场景模板

package/docs/zh-CN/workflow-examples.md

@@ -91,9 +91,10 @@ $da-vinci use redesign-from-code to inventory the current app, identify current
 5. 当范围过大时，把工作拆成多个 `specs/<slice>/spec.md`
 6. 重建或细化 `page-map.md`，把 subpage、overlay、重要 state 一起拆出来
 7. 创建新的或更新后的 Pencil 页面，基于重新构图而不是旧 UI 换皮，并优先持久化到 `.da-vinci/designs/`
-8. 绑定路由和 Pencil 页面
-9. 生成和 redesign slice 对齐的任务
-10. 实现并验证
+8. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
+9. 绑定路由和 Pencil 页面
+10. 生成和 redesign slice 对齐的任务
+11. 实现并验证
 
 ### 复杂 Android 页面示例
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Requirement-to-design-to-code workflow skill for Codex, Claude, and Gemini",
   "bin": {
     "da-vinci": "bin/da-vinci.js"

package/references/artifact-templates.md

@@ -230,12 +230,14 @@ Use this structure:
 ## Active Design Sources
 - `.pen` file path
 - whether it lives under `.da-vinci/designs/`
+- whether the path is workflow-generated or external
 - status
 - purpose
 
 ## Preferred Design Source
 - Which `.pen` file is authoritative
 - Why that file should be preferred over live-only or external sources
+- whether the active Pencil editor matches that same path
 
 ## Visual Adapter Resolution
 - Requested adapters
@@ -252,7 +254,8 @@ Use this structure:
 ## Notes
 - Why a source is active
 - Whether a source is safe to iterate
-- Whether local export is still pending
+- Whether shell-visible filesystem persistence exists
+- Whether the file had to be reconstructed from MCP-readable document data
 ```
 
 Use this artifact whenever a project can have one or more Pencil sources.
@@ -434,6 +437,7 @@ Use this structure:
 ## Source
 - `.pen` file path
 - project-local persisted path under `.da-vinci/designs/` when available
+- whether the active Pencil editor matched that same path
 - Active pages
 
 ## Visual Adapter Use
@@ -459,7 +463,7 @@ Use this structure:
 
 ## Implementation Notes
 - Important layout or styling constraints to preserve in code
-- Persistence notes if the live Pencil source has not yet been exported locally
+- Persistence notes if the project-local `.pen` file had to be reconstructed from MCP-readable document data
 ```
 
 Recommended path:
@@ -506,6 +510,7 @@ Use this structure:
 ## Source
 - `.pen` file path
 - project-local persisted path under `.da-vinci/designs/` when available
+- whether the active Pencil editor matched that same path
 
 ## Bindings
 - implementation page or route -> Pencil page or screen
@@ -516,7 +521,7 @@ Use this structure:
 ## Notes
 - intentional deviations
 - pages without Pencil coverage yet
-- whether bindings depend on a live-only source that still needs local export
+- whether bindings depend on a live-only source that still needs reconciliation
 ```
 
 Use this artifact whenever implementation must trace back to Pencil pages.

package/references/checkpoints.md

@@ -107,6 +107,25 @@ Result meanings:
 - `WARN`: minor design gaps exist, but the visual direction is still coherent
 - `BLOCK`: design is not ready to drive implementation, or the result is generic, cluttered, or materially below the intended visual bar
 
+## `design-source checkpoint`
+
+Run after `design-registry.md` resolves the preferred project-local `.pen` path and after active Pencil work exists, but before mapping is treated as safe.
+
+Check:
+
+- `design-registry.md` records one specific preferred project-local `.pen` path
+- the preferred `.pen` path is workflow-owned state, not a hand-wavy placeholder
+- the active Pencil editor path matches the preferred project-local `.pen` path, or the mismatch has been reconciled explicitly
+- if the workflow created or edited Pencil work, the preferred project-local `.pen` file exists as a shell-visible file
+- if Pencil MCP only exposed a live document, the workflow reconstructed and wrote the registered project-local `.pen` file from MCP-readable document data before continuing
+- `design-registry.md`, `pencil-design.md`, and `pencil-bindings.md` describe the same active project-local `.pen` source clearly enough to map and implement from
+
+Result meanings:
+
+- `PASS`: safe to continue into mapping
+- `WARN`: the workflow is intentionally staying on an older but still shell-visible baseline, or no new Pencil edits have happened yet
+- `BLOCK`: the registered `.pen` path, the active Pencil work, and the shell-visible project-local file do not agree well enough to treat the design source as traceable
+
 ## `mapping checkpoint`
 
 Run after `design-registry.md` and `pencil-bindings.md`.
@@ -114,6 +133,9 @@ Run after `design-registry.md` and `pencil-bindings.md`.
 Check:
 
 - the correct `.pen` source is identified
+- the preferred `.pen` path in `design-registry.md` is workflow-owned and specific, not hand-wavy
+- the active Pencil editor path matches the preferred project-local `.pen` path, or the project-local file has been reconstructed explicitly
+- the preferred project-local `.pen` file exists as a shell-visible file when the workflow created or edited Pencil work
 - each implementation page has a Pencil page or an explicit exception
 - shared layouts and shared regions are bound clearly enough to implement from
 - route names and Pencil names are traceable
@@ -123,7 +145,7 @@ Result meanings:
 
 - `PASS`: safe to generate implementation tasks
 - `WARN`: some bindings are weak, but implementation can continue carefully
-- `BLOCK`: implementation would guess too much without fixing bindings
+- `BLOCK`: implementation would guess too much without fixing bindings, or the workflow edited Pencil work without producing the required project-local `.pen` source
 
 ## `task checkpoint`
 
@@ -154,12 +176,14 @@ Examples of `WARN`, not `BLOCK`:
 
 - an additional follow-up spec may be needed for currently untouched behavior
 - some legacy or out-of-scope surfaces remain intentionally excluded
-- the active Pencil source should also be saved or exported for stronger repository traceability
+- the project intentionally remains on an older but still shell-visible `.pen` baseline while a new design pass is deferred
 
 Examples of `BLOCK`:
 
 - the implementation would invent new behavior that has no spec support
 - page-to-Pencil bindings are too weak to know which redesign screen to follow
+- `design-registry.md` points to a project-local `.pen` path, but the workflow actually edited a different live editor document and did not reconcile the mismatch
+- the workflow created or edited Pencil pages but no shell-visible `.pen` file exists under the registered project-local path
 - required permissions, environment access, or protected files are unavailable
 - the implementation would overwrite the project baseline in a destructive way without an explicit go-ahead
 

package/references/design-inputs.md

@@ -12,6 +12,31 @@ Check for `DA-VINCI.md` first, then check whether the project already has persis
 - if it does not exist, generate it from the best stable inputs before broad Pencil page generation
 - avoid re-deriving the visual language page by page
 
+## Project-Local `.pen` Path Resolution
+
+The preferred `.pen` path in `design-registry.md` is workflow-owned state.
+
+- it should be generated and maintained by Da Vinci
+- it should not rely on the user manually typing a path into `design-registry.md`
+- external references may influence source priority, but the project-local path should still be resolved explicitly
+
+Use these defaults:
+
+1. `.da-vinci/designs/project-baseline.pen`
+2. `.da-vinci/designs/<change-id>.pen`
+3. `.da-vinci/designs/<change-id>/main.pen` only when a nested design bundle is truly needed
+
+Before broad Pencil work begins:
+
+- resolve the exact project-local path
+- record that path in `design-registry.md`
+- treat that path as the required target for the active design pass
+
+If Pencil MCP is currently pointing at a different active editor:
+
+- switch to the registered project-local path when possible
+- otherwise reconstruct the project-local `.pen` file from MCP-readable document data before treating the workflow as traceable
+
 ## Minimum Inputs
 
 Collect or infer:
@@ -73,7 +98,11 @@ Write stable answers into `design-brief.md`.
 
 If `DA-VINCI.md` did not already exist, generate it from those stable answers and save it as the project visual baseline.
 
-If Pencil creates or updates a baseline during the workflow, save or export the `.pen` file into `.da-vinci/designs/` when possible and register that exact path in `design-registry.md`.
+If Pencil creates or updates a baseline during the workflow:
+
+- register the exact project-local path in `design-registry.md`
+- verify that the same path is readable through MCP and shell-visible in the project filesystem
+- if Pencil MCP does not materialize the shell-visible file automatically, reconstruct and write the `.pen` file from MCP-readable document data before closing mapping or implementation work
 
 If the project requests a visual adapter:
 

package/references/pencil-design-to-code.md

@@ -17,7 +17,7 @@ Do not infer behavior from appearance alone.
 When MCP is available, read:
 
 - the preferred project-local `.pen` file under `.da-vinci/designs/` when one is registered
-- active `.pen` file
+- the active `.pen` file only after confirming it matches the registered project-local path
 - target page frame
 - child section hierarchy
 - text content
@@ -28,6 +28,12 @@ When MCP is available, read:
 
 Prefer structural reads over screenshots.
 
+If the current active Pencil editor does not match the preferred path in `design-registry.md`:
+
+- do not silently continue from the unrelated editor
+- switch to the registered file when possible
+- otherwise reconstruct the registered project-local `.pen` file from MCP-readable document data before implementation depends on it
+
 ## Visual Adapter Use
 
 If the project resolved a visual adapter: