@xenonbyte/da-vinci-workflow 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 - 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
+- `redesign-from-code` now documents a stricter contract: existing code is behavior truth, not layout truth
+- complex screens are now documented to decompose into subpages, overlays, materially different states, and implementation surfaces before broad Pencil redesign
+- design-checkpoint guidance now explicitly blocks skin-swap redesigns, generic card mosaics, weak visual anchors, and decorative clutter
+- `Visual Assist` documentation and README guidance now include clearer field explanations, quick-start recommendations, quality-first configuration advice, and stronger usage examples for Android-style redesign work
+
 ## v0.1.9 - 2026-03-27
 
 ### Added

package/README.md

@@ -27,10 +27,14 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.9`
+- `@xenonbyte/da-vinci-workflow@0.1.10`
 
 Release highlights:
 
+- `redesign-from-code` now states explicitly that existing code is behavior truth, not layout truth
+- complex pages are now expected to decompose into subpages, overlays, materially different states, and implementation surfaces before broad Pencil redesign
+- design-checkpoint guidance now explicitly blocks skin-swap redesigns, generic card mosaics, weak visual anchors, and decorative clutter
+- `Visual Assist` docs now include quick-start recommendations and a quality-first configuration for design-critical work
 - visual-adapter configuration is now documented explicitly, including field meanings, resolution order, and fallback behavior
 - ready-to-copy `Visual Assist` presets are now included for mobile, desktop, web, and tablet scenarios
 - the repo-local forward test now shows how `Visual Assist`, adapter resolution, and persisted `.pen` paths should be recorded
@@ -86,6 +90,67 @@ Route discipline:
 - they should not default the user into `build`
 - `build` remains a direct expert route for workflows that are already implementation-ready
 
+## Visual Assist Quick Start
+
+Use `Visual Assist` when the project wants optional help from local UI-design skills such as `frontend-skill` or `ui-ux-pro-max`.
+
+Recommended default:
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+```
+
+Use this when:
+
+- the project is an app, dashboard, desktop tool, or other product surface
+- the workflow should continue even if no local adapter is installed
+- you want better composition and hierarchy without turning adapter availability into a blocker
+
+Quality-first redesign configuration:
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - frontend-skill
+  - ui-ux-pro-max
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - motion guidance
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - true
+```
+
+Use this when:
+
+- the project is visually sensitive and plain fallback quality is not acceptable
+- prior redesign attempts drifted into generic card grids, weak anchors, or skin-swap outputs
+- you want the workflow to stop instead of silently continuing without a strong local design helper
+
+Selection rules:
+
+- keep `ui-ux-pro-max` first for dense app and dashboard surfaces when the visual bar is moderate
+- move `frontend-skill` to the first slot when art direction, composition quality, and premium visual hierarchy matter more
+- keep `Fallback: native-da-vinci` unless you explicitly want missing adapters to block the workflow
+- keep `Require Adapter: false` by default and raise it to `true` only for design-critical work
+- keep `Scope` limited to presentation quality; do not use it to delegate behavior, routes, or state truth
+
 ## Core workflow
 
 Da Vinci runs in this order:
@@ -187,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:
 
@@ -232,6 +298,12 @@ Rules:
 - `.da-vinci/designs/` is the default project-local location for persisted `.pen` files
 - `page-map.md` is the source of truth for implementation pages
 - `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:
 
@@ -241,21 +313,29 @@ Optional visual-adapter policy:
 - they must not override behavior truth, route truth, page-state truth, or acceptance rules
 - if a requested adapter is unavailable locally, Da Vinci should continue with native design rules and record the fallback in `design-registry.md`
 
+Recommended practice:
+
+- configure `Visual Assist` in `DA-VINCI.md` before broad Pencil generation begins
+- for complex Android redesigns, ask Da Vinci to decompose activities, fragments, tabs, sheets, dialogs, and materially different states before design work expands
+- if the output quality is weak, promote `frontend-skill`, tighten the design checkpoint bar, and prefer a fresh composition over a recolor of the old UI
+
 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
-- save or export the rebuilt Pencil baseline into `.da-vinci/designs/` when possible
+- decompose complex containers into real design surfaces before broad Pencil generation
+- 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
 
@@ -434,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/`
@@ -445,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

@@ -29,10 +29,14 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.9`
+- `@xenonbyte/da-vinci-workflow@0.1.10`
 
 已发布版本重点：
 
+- `redesign-from-code` 现在明确写清：现有代码只是真相行为，不是真相布局
+- 复杂页面现在明确要求在大规模 Pencil 重设计前拆成 subpage、overlay、明显不同 state 和 implementation surface
+- design checkpoint 现在明确会拦截旧 UI 换皮、通用卡片拼贴、弱视觉锚点和装饰性噪音
+- `Visual Assist` 文档现在补了快速上手建议和“设计质量优先”配置
 - visual adapter 的配置字段、解析顺序和回退行为现在有单独文档说明
 - 现在提供按移动端、桌面端、Web、平板拆分的 `Visual Assist` 可复制模板
 - 仓库内的 forward test 示例现在展示了 `Visual Assist`、adapter 解析结果和 `.pen` 持久化记录方式
@@ -91,6 +95,67 @@ Da Vinci V2 支持四种模式：
 - 它们不应该默认把用户直接导向 `build`
 - `build` 仍然保留，但它是给已经实现就绪的高级直接入口
 
+## Visual Assist 快速上手
+
+当项目想借助本地 UI 设计 skill，例如 `frontend-skill` 或 `ui-ux-pro-max`，来提升设计质量时，就配置 `Visual Assist`。
+
+推荐默认配置：
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+```
+
+适用场景：
+
+- app、dashboard、桌面工具等产品型界面
+- 本地没有 adapter 时工作流也应该继续
+- 想提升构图和层级，但不希望 adapter 缺失变成阻塞
+
+设计质量优先配置：
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - frontend-skill
+  - ui-ux-pro-max
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - motion guidance
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - true
+```
+
+适用场景：
+
+- 页面视觉质量要求高，不能接受普通 fallback 质量
+- 之前的重设计已经出现“堆卡片、弱锚点、只是旧 UI 换皮”这类问题
+- 你希望没有强设计辅助 skill 时直接停下，而不是继续生成普通结果
+
+选择建议：
+
+- 高密度 app、dashboard、工具型界面，且视觉要求中等时，优先把 `ui-ux-pro-max` 放第一位
+- 如果更重视 art direction、构图和高级感，就把 `frontend-skill` 放第一位
+- 默认保留 `Fallback: native-da-vinci`
+- `Require Adapter` 默认保持 `false`，只有设计要求很高时再改成 `true`
+- `Scope` 只管 presentation 质量，不要拿它去定义 behavior、route 或 state truth
+
 ## 核心工作流顺序
 
 Da Vinci 的默认顺序是：
@@ -185,6 +250,12 @@ project/
 - `.da-vinci/designs/` 是项目内持久化 `.pen` 文件的默认位置
 - `page-map.md` 是实现页面和状态的真相源
 - `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 规则：
 
@@ -194,21 +265,29 @@ project/
 - 它不能覆盖 behavior truth、路由真相、页面状态真相或验收规则
 - 如果本地没有请求的 adapter，Da Vinci 应继续使用原生设计规则，并在 `design-registry.md` 里记录回退结果
 
+建议做法：
+
+- 在开始大规模 Pencil 设计前，就在 `DA-VINCI.md` 里写好 `Visual Assist`
+- 面对复杂 Android 重设计时，先要求 Da Vinci 把 activities、fragments、tabs、sheets、dialogs 和明显不同的 states 拆开
+- 如果结果很丑，就把 `frontend-skill` 提到第一位，收紧 design checkpoint，并明确要求 fresh composition，而不是旧 UI 改色
+
 当已有页面映射存在时：
 
 - 优先复用已绑定的 Pencil 设计源
 - 如果 `design-registry.md` 里已经登记了 `.da-vinci/designs/` 下的本地 `.pen` 路径，优先使用它
+- 不要在没有同步 `design-registry.md` 的情况下，悄悄切到另一个当前活动编辑器路径继续设计
 
 当已有代码存在但还没有映射时：
 
 - 先从当前项目重建设计基线
 - 重建 inventory、page-map、design-registry
-- 在可行时把新的 Pencil 基线保存或导出到 `.da-vinci/designs/`
+- 先把复杂容器拆成真实的设计 surface，再进入大规模 Pencil 设计
+- 先解析出明确的项目内 `.pen` 目标路径，再把新的 Pencil 基线真正落到 `.da-vinci/designs/`
 
 当既没有映射也没有可用设计源时：
 
 - 基于当前本地真相源创建新的 Pencil 基线
-- 在可行时把基线保存到 `.da-vinci/designs/`
+- 把基线落到 `.da-vinci/designs/`
 - 并在 `design-registry.md` 里记录准确路径
 
 如果项目声明了 visual adapter：
@@ -348,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`
@@ -357,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

@@ -15,6 +15,7 @@ Keep these rules fixed:
 - Pencil decides presentation.
 - Tasks decide implementation order.
 - Code must follow both requirements and Pencil data.
+- Existing code is behavior truth, not layout truth, during `redesign-from-code`.
 - When requirements and Pencil drift apart, stop and update the source artifacts before continuing implementation.
 
 ## Execution Policy
@@ -356,6 +357,8 @@ If the active mode is `redesign-from-code`:
 
 - inventory current routes, pages, and modules before redefining page structure
 - distinguish preserved behavior from replaced presentation
+- treat existing code as behavior truth and implementation-surface discovery, not as a visual-layout baseline
+- default to fresh visual composition unless the user explicitly asks to preserve the current layout skeleton
 - partition specs by redesign slice when one oversized `ui-refresh` spec would hide important implementation boundaries
 
 ## Spec Partitioning Rules
@@ -397,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
@@ -417,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:
 
@@ -428,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:
 
@@ -435,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:
 
@@ -460,6 +478,33 @@ When visual adapters are requested:
 
 If the request is too vague to design or implement safely, ask a short clarification question before generating artifacts.
 
+## Surface Decomposition Rules
+
+Do not treat one implementation container as one design surface by default.
+
+For complex products, decompose by:
+
+- canonical page
+- subpage
+- state
+- overlay
+- shared shell region
+- implementation surface such as activity, fragment, tab, bottom sheet, dialog, or full-screen mode
+
+When an Android screen contains multiple fragments, tabs, nested flows, or materially different states:
+
+- split them into distinct design surfaces in `page-map.md`
+- give each meaningful state or subpage its own Pencil target when the layout materially changes
+- avoid collapsing them into one overloaded redesign screen
+
+One implementation page may legitimately map to:
+
+- multiple Pencil screens
+- multiple states of one Pencil page
+- one shared shell plus several detail surfaces
+
+Treat surface decomposition as required when visual structure changes materially across states or subflows.
+
 ## Pencil Design Rules
 
 Use Pencil as a structured UI source, not as a static image source.
@@ -469,10 +514,15 @@ 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
 - Make important states explicit when they change implementation: empty, loading, success, error, restricted, unavailable
 - Prefer layout clarity and information hierarchy over decorative complexity
+- Reject generic UI patterns such as dashboard-card mosaics, weak visual anchors, decorative clutter, or motion with no hierarchy value
+- For `redesign-from-code`, redesign from page responsibilities and state decomposition, not by recoloring or slightly rearranging the old UI
 - After changes, inspect the result visually before treating it as implementation-ready
 
 When multiple pages exist:
@@ -480,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:
 
@@ -531,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
@@ -341,9 +342,28 @@ Register the design sources, extract DA-VINCI.md from them, bind covered pages,
 For redesign work:
 
 - current code decides behavior
+- current code does not decide the new layout or visual composition
 - `DA-VINCI.md` decides the new visual contract
 - Pencil decides page-by-page presentation
 
+Fresh-layout rule:
+
+- default to fresh visual composition driven by page purpose and state coverage
+- 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
+- one implementation page may map to several Pencil screens or states
+- do not hide that complexity inside one oversized redesign page
+
 ### Spec partitioning rule
 
 For broad refreshes, do not keep everything inside one `ui-refresh/spec.md` unless the project surface is genuinely small or the change is mostly cosmetic.
@@ -409,13 +429,14 @@ Please inventory the current pages and shared layouts, register the HTML drafts
 Expected behavior:
 
 1. inventory current pages and shared regions
-2. register the HTML drafts as design references
-3. extract a stable `DA-VINCI.md`
-4. split broad redesign work into multiple spec slices when needed
-5. create or refine Pencil redesign screens
-6. bind implementation pages to redesign screens
-7. generate `tasks.md` aligned to the redesign slices
-8. continue into code changes without stopping at "next recommended step"
+2. decompose complex containers into real design surfaces, subpages, overlays, and states
+3. register the HTML drafts as design references
+4. extract a stable `DA-VINCI.md`
+5. split broad redesign work into multiple spec slices when needed
+6. create or refine Pencil redesign screens
+7. bind implementation pages to redesign screens
+8. generate `tasks.md` aligned to the redesign slices
+9. continue into code changes without stopping at "next recommended step"
 
 ### Best fit
 

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