@xenonbyte/da-vinci-workflow 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -4,6 +4,26 @@
 
 - No unreleased changes yet.
 
+## v0.1.9 - 2026-03-27
+
+### Added
+- `docs/visual-adapters.md` and `docs/zh-CN/visual-adapters.md` to explain visual-adapter configuration, resolution, and fallback behavior
+- `docs/visual-assist-presets/` and `docs/zh-CN/visual-assist-presets/` with ready-to-copy `Visual Assist` presets for mobile, desktop, web, and tablet product surfaces
+
+### Changed
+- forward-test example artifacts now show `Visual Assist`, `Visual Adapter Resolution`, and project-local `.pen` persistence patterns
+- workflow examples and README navigation now point to the new visual-adapter and preset documentation
+
+## v0.1.8 - 2026-03-27
+
+### Added
+- Codex natural-language usage guides in `docs/codex-natural-language-usage.md` and `docs/zh-CN/codex-natural-language-usage.md`
+
+### Changed
+- Codex workflow docs now standardize on `$da-vinci ...` natural-language entry patterns for `intake`, `prompt`, `continue`, and direct mode usage
+- Da Vinci now documents `.da-vinci/designs/` as the default project-local location for persisted Pencil `.pen` files
+- artifact templates, mode guides, and design references now record preferred project-local `.pen` paths in `design-registry.md`
+
 ## v0.1.7 - 2026-03-27
 
 ### Changed

package/README.md

@@ -27,10 +27,16 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.7`
+- `@xenonbyte/da-vinci-workflow@0.1.9`
 
 Release highlights:
 
+- 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
+- Codex natural-language usage is now documented explicitly, including `intake`, `prompt`, `continue`, and direct mode entry patterns
+- project-local Pencil `.pen` files are now documented to persist under `.da-vinci/designs/`
+- design registry and artifact templates now record preferred persisted `.pen` paths for project-local reuse
 - prompt-entry helper routes for `intake`, `prompt`, and `continue` are now published across Codex, Claude, and Gemini
 - Chinese companion docs are now intentionally limited to `README.zh-CN.md` and `docs/zh-CN/`
 - asset validation now covers the full shipped documentation set
@@ -87,7 +93,7 @@ Da Vinci runs in this order:
 1. select the active mode
 2. build the correct source artifacts
 3. detect or generate `DA-VINCI.md` as the project visual contract
-4. collect design inputs and register design sources
+4. collect design inputs, prefer project-local `.pen` files under `.da-vinci/designs/`, and register design sources
 5. define or discover the project page map
 6. create or update Pencil designs
 7. bind implementation pages to Pencil pages
@@ -105,6 +111,7 @@ Depending on the mode, the workflow may use these artifacts:
 - `DA-VINCI.md`
 - `.da-vinci/changes/<change-id>/design-brief.md`
 - `.da-vinci/design-registry.md`
+- `.da-vinci/designs/`
 - `.da-vinci/page-map.md`
 - `.da-vinci/changes/<change-id>/proposal.md`
 - `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
@@ -121,6 +128,7 @@ Depending on the mode, the workflow may use these artifacts:
 - `DA-VINCI.md`: project-level visual contract for theme, palette, typography direction, component tone, and page-consistency rules
 - `design-brief.md`: form factor, style, density, brand constraints, and layout preferences
 - `design-registry.md`: project-level `.pen` source inventory
+- `.da-vinci/designs/`: project-local persisted Pencil sources such as `project-baseline.pen` or change-specific `.pen` files
 - `page-map.md`: canonical page list and page responsibilities
 - `proposal.md`: change scope and outcomes
 - `spec.md`: behavior, states, edge cases, and acceptance rules
@@ -146,6 +154,9 @@ project/
 └── .da-vinci/
     ├── project-inventory.md
     ├── design-registry.md
+    ├── designs/
+    │   ├── project-baseline.pen
+    │   └── <change-id>.pen
     ├── page-map.md
     └── changes/
         └── <change-id>/
@@ -165,6 +176,7 @@ Placement rules:
 
 - keep `DA-VINCI.md` at the project root
 - keep project-wide workflow files in `.da-vinci/`
+- keep project-local Pencil files in `.da-vinci/designs/`
 - keep change-specific workflow files in `.da-vinci/changes/<change-id>/`
 - do not scatter `proposal.md`, `tasks.md`, and `verification.md` across the project root
 
@@ -217,21 +229,33 @@ Rules:
 
 - `DA-VINCI.md` is the project-level visual contract for cross-page consistency
 - `design-registry.md` is the project-level inventory of `.pen` sources
+- `.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
 
+Optional visual-adapter policy:
+
+- `DA-VINCI.md` may declare preferred visual adapters for design assistance
+- visual adapters are optional helpers for composition, hierarchy, spacing, and motion guidance
+- they may refine `DA-VINCI.md`, `design.md`, and `pencil-design.md`
+- 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`
+
 When a relevant mapping already exists:
 
 - iterate on the mapped Pencil source
+- prefer the project-local `.pen` path already registered in `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
 
 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`
 
 ## Design input collection
 
@@ -243,6 +267,7 @@ Before generating Pencil designs for a greenfield project, Da Vinci should colle
 - density
 - brand direction
 - responsive priority
+- optional visual-adapter preferences
 
 Preferred inference order:
 
@@ -257,6 +282,12 @@ If `DA-VINCI.md` does not exist:
 - generate it from stable user preferences, existing project signals, or inferred defaults
 - save it before generating many project pages, so later pages do not drift stylistically
 
+If the project requests visual adapters:
+
+- resolve them from the user request first, then `DA-VINCI.md`, then locally available skills
+- choose one primary adapter when multiple helpers are available
+- treat them as non-blocking unless the user explicitly requires a specific adapter
+
 ## Installation
 
 Install the package:
@@ -299,9 +330,9 @@ $da-vinci <request>
 Entry helpers:
 
 ```text
-/prompts:dv-intake
-/prompts:dv-prompt
-/prompts:dv-continue
+$da-vinci use intake for <project situation>
+$da-vinci use prompt for <known scenario>
+$da-vinci use continue for <existing workflow state>
 ```
 
 ### Claude
@@ -382,13 +413,20 @@ $da-vinci use feature-change to add a billing page, generate the relevant Pencil
 ### Prompt intake for a complex redesign
 
 ```text
-/dv:intake I need to globally replace the UI of an existing Android project. Existing code is the behavior source of truth. HTML references are in /abs/path/to/mockups.
+$da-vinci use intake for this existing Android project.
+
+I need to globally replace the UI.
+Existing Android code is the behavior source of truth.
+HTML references are in /abs/path/to/mockups.
 ```
 
 ### Continue after inventory and spec work
 
 ```text
-/dv:continue Continue this redesign-from-code workflow into full-delivery using the existing Da Vinci artifacts.
+$da-vinci use continue for this existing redesign-from-code workflow.
+
+Use the existing Da Vinci artifacts.
+Continue into full-delivery.
 ```
 
 ## Workflow examples
@@ -396,6 +434,9 @@ $da-vinci use feature-change to add a billing page, generate the relevant Pencil
 See:
 
 - `docs/prompt-entrypoints.md`
+- `docs/codex-natural-language-usage.md`
+- `docs/visual-adapters.md`
+- `docs/visual-assist-presets/`
 - `docs/workflow-examples.md`
 - `docs/mode-use-cases.md`
 
@@ -404,6 +445,8 @@ See:
 Chinese companion documents are included in this repository:
 
 - `README.zh-CN.md`
+- `docs/zh-CN/visual-adapters.md`
+- `docs/zh-CN/visual-assist-presets/`
 - `docs/zh-CN/`
 
 ## Repository layout

package/README.zh-CN.md

@@ -29,10 +29,16 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.7`
+- `@xenonbyte/da-vinci-workflow@0.1.9`
 
 已发布版本重点：
 
+- visual adapter 的配置字段、解析顺序和回退行为现在有单独文档说明
+- 现在提供按移动端、桌面端、Web、平板拆分的 `Visual Assist` 可复制模板
+- 仓库内的 forward test 示例现在展示了 `Visual Assist`、adapter 解析结果和 `.pen` 持久化记录方式
+- Codex 的自然语言用法现在有单独文档，明确说明 `intake`、`prompt`、`continue` 和直接 mode 调用方式
+- 项目内 Pencil `.pen` 文件现在明确约定默认持久化到 `.da-vinci/designs/`
+- 设计源登记和工件模板现在会记录项目内优先使用的 `.pen` 路径
 - `intake`、`prompt`、`continue` 三个提示词入口辅助路由已随 Codex、Claude、Gemini 一起发布
 - 中文配套文档现在刻意只保留 `README.zh-CN.md` 和 `docs/zh-CN/`
 - 资产校验现在覆盖完整的随包文档集合
@@ -92,7 +98,7 @@ Da Vinci 的默认顺序是：
 1. 选择 mode
 2. 生成正确的源工件
 3. 检测或生成 `DA-VINCI.md`
-4. 收集设计输入并登记设计源
+4. 收集设计输入，优先使用 `.da-vinci/designs/` 下的项目内 `.pen` 文件，并登记设计源
 5. 定义或发现页面地图
 6. 创建或更新 Pencil 设计
 7. 绑定实现页面到 Pencil 页面
@@ -110,6 +116,7 @@ Da Vinci 的默认顺序是：
 - `DA-VINCI.md`
 - `.da-vinci/changes/<change-id>/design-brief.md`
 - `.da-vinci/design-registry.md`
+- `.da-vinci/designs/`
 - `.da-vinci/page-map.md`
 - `.da-vinci/changes/<change-id>/proposal.md`
 - `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
@@ -126,6 +133,7 @@ Da Vinci 的默认顺序是：
 - `DA-VINCI.md`：项目级视觉契约
 - `design-brief.md`：设计方向、形态、密度、品牌和限制条件
 - `design-registry.md`：项目级 `.pen` 设计源登记
+- `.da-vinci/designs/`：项目内持久化的 Pencil 设计源，例如 `project-baseline.pen` 或按 change 保存的 `.pen` 文件
 - `page-map.md`：页面、职责、状态和共享区域
 - `proposal.md`：范围、目标、非目标和成功标准
 - `spec.md`：行为、状态、边界和验收规则
@@ -135,6 +143,81 @@ Da Vinci 的默认顺序是：
 - `tasks.md`：任务分组和实施顺序
 - `verification.md`：覆盖度和漂移检查
 
+## 工件放置建议
+
+推荐结构：
+
+```text
+project/
+├── DA-VINCI.md
+└── .da-vinci/
+    ├── project-inventory.md
+    ├── design-registry.md
+    ├── designs/
+    │   ├── project-baseline.pen
+    │   └── <change-id>.pen
+    ├── page-map.md
+    └── changes/
+        └── <change-id>/
+            ├── brainstorm.md
+            ├── design-brief.md
+            ├── proposal.md
+            ├── design.md
+            ├── pencil-design.md
+            ├── pencil-bindings.md
+            ├── tasks.md
+            ├── verification.md
+            └── specs/
+                └── <capability>/spec.md
+```
+
+规则：
+
+- `DA-VINCI.md` 放在项目根目录
+- 项目级工作流工件放在 `.da-vinci/`
+- 项目内持久化的 Pencil `.pen` 文件默认放在 `.da-vinci/designs/`
+- change 级工件放在 `.da-vinci/changes/<change-id>/`
+
+## 设计源规则
+
+- `DA-VINCI.md` 是跨页面视觉一致性的项目级视觉契约
+- `design-registry.md` 用来登记项目中的 `.pen` 设计源
+- `.da-vinci/designs/` 是项目内持久化 `.pen` 文件的默认位置
+- `page-map.md` 是实现页面和状态的真相源
+- `pencil-bindings.md` 是实现页面到 Pencil 页面绑定的真相源
+
+可选 visual adapter 规则：
+
+- `DA-VINCI.md` 可以声明期望使用的 visual adapter 来辅助设计
+- visual adapter 只用于增强构图、层级、留白、节奏和 motion 判断
+- 它可以影响 `DA-VINCI.md`、`design.md`、`pencil-design.md`
+- 它不能覆盖 behavior truth、路由真相、页面状态真相或验收规则
+- 如果本地没有请求的 adapter，Da Vinci 应继续使用原生设计规则，并在 `design-registry.md` 里记录回退结果
+
+当已有页面映射存在时：
+
+- 优先复用已绑定的 Pencil 设计源
+- 如果 `design-registry.md` 里已经登记了 `.da-vinci/designs/` 下的本地 `.pen` 路径，优先使用它
+
+当已有代码存在但还没有映射时：
+
+- 先从当前项目重建设计基线
+- 重建 inventory、page-map、design-registry
+- 在可行时把新的 Pencil 基线保存或导出到 `.da-vinci/designs/`
+
+当既没有映射也没有可用设计源时：
+
+- 基于当前本地真相源创建新的 Pencil 基线
+- 在可行时把基线保存到 `.da-vinci/designs/`
+- 并在 `design-registry.md` 里记录准确路径
+
+如果项目声明了 visual adapter：
+
+- 先看用户请求，其次看 `DA-VINCI.md`，再看本地可用 skill
+- 如果存在多个可用辅助 skill，收敛出一个 primary adapter，必要时再保留 secondary helpers
+- 默认把它当成非阻塞增强层
+- 只有用户明确要求必须使用某个 adapter 时，缺失才应阻塞工作流
+
 ## 安装
 
 安装 npm 包：
@@ -177,9 +260,9 @@ $da-vinci <request>
 辅助入口：
 
 ```text
-/prompts:dv-intake
-/prompts:dv-prompt
-/prompts:dv-continue
+$da-vinci use intake for <project situation>
+$da-vinci use prompt for <known scenario>
+$da-vinci use continue for <existing workflow state>
 ```
 
 ### Claude
@@ -243,20 +326,30 @@ $da-vinci use feature-change to add a billing page, generate the relevant Pencil
 ### 复杂重设计先做 intake
 
 ```text
-/dv:intake I need to globally replace the UI of an existing Android project. Existing code is the behavior source of truth. HTML references are in /abs/path/to/mockups.
+$da-vinci use intake for this existing Android project.
+
+I need to globally replace the UI.
+Existing Android code is the behavior source of truth.
+HTML references are in /abs/path/to/mockups.
 ```
 
 ### 已有工件后继续推进
 
 ```text
-/dv:continue Continue this redesign-from-code workflow into full-delivery using the existing Da Vinci artifacts.
+$da-vinci use continue for this existing redesign-from-code workflow.
+
+Use the existing Da Vinci artifacts.
+Continue into full-delivery.
 ```
 
 ## 文档导航
 
 英文文档：
 
+- `docs/codex-natural-language-usage.md`
 - `docs/prompt-entrypoints.md`
+- `docs/visual-adapters.md`
+- `docs/visual-assist-presets/`
 - `docs/workflow-examples.md`
 - `docs/mode-use-cases.md`
 - `references/`
@@ -264,6 +357,8 @@ $da-vinci use feature-change to add a billing page, generate the relevant Pencil
 中文文档：
 
 - `README.zh-CN.md`
+- `docs/zh-CN/visual-adapters.md`
+- `docs/zh-CN/visual-assist-presets/`
 - `docs/zh-CN/`
 
 ## 仓库布局

package/SKILL.md

@@ -70,7 +70,7 @@ Do not stop merely because:
 
 - some pages are still out of scope
 - a future follow-up spec may be needed for untouched behavior
-- a design source should also be saved or exported for better traceability
+- a project-local `.pen` export is still pending for traceability, unless that missing file would make the active design source ambiguous
 
 Those are warnings unless they prevent safe implementation of the current in-scope work.
 
@@ -80,9 +80,12 @@ Canonical workflow name is `da-vinci`.
 
 - Codex preferred: `$da-vinci <request>`
 - Claude and Gemini preferred: `/da-vinci <request>` when platform adapters exist
-- Explicit action routes also exist for workflow entry help:
-  - Codex: `/prompts:dv-intake`, `/prompts:dv-prompt`, `/prompts:dv-continue`
-  - Claude and Gemini: `/dv:intake`, `/dv:prompt`, `/dv:continue`
+- For Codex helper intents, prefer natural-language patterns:
+  - `$da-vinci use intake for <project situation>`
+  - `$da-vinci use prompt for <known scenario>`
+  - `$da-vinci use continue for <existing workflow state>`
+- Claude and Gemini helper routes remain:
+  - `/dv:intake`, `/dv:prompt`, `/dv:continue`
 - Natural-language invocation remains the default path
 
 ## Prompt Entry Routes
@@ -148,6 +151,7 @@ Before generating new Pencil designs for a greenfield project, collect or infer:
    - detect whether `DA-VINCI.md` already exists
    - if it exists, treat it as the visual baseline for future pages
    - if it does not exist, generate it from stable user preferences, existing project signals, or inferred defaults before broad Pencil page generation
+   - if it declares preferred visual adapters, treat them as optional design-assist preferences, not as behavior truth
 
 1. product form factor
    - desktop software
@@ -177,6 +181,13 @@ Use this priority order:
 
 Do not repeatedly ask for inputs that are already stable in the artifacts.
 
+Treat visual adapters as optional design-assist layers.
+
+- resolve them from the user request first, then `DA-VINCI.md`, then locally available skills
+- use them to improve visual contract quality, composition, hierarchy, spacing, and motion guidance
+- do not let them redefine behavior, page truth, route truth, or acceptance rules
+- if a requested adapter is unavailable locally, continue with native Da Vinci design rules and record the fallback
+
 ## Default Workflow
 
 Run the workflow in this order:
@@ -184,7 +195,7 @@ Run the workflow in this order:
 1. Select the active mode
 2. Build the correct source artifacts for that mode
 3. Detect or generate `DA-VINCI.md` as the project visual contract
-4. Collect design inputs and register available design sources
+4. Collect design inputs, prefer project-local `.pen` files under `.da-vinci/designs/`, and register available design sources
 5. Define or discover the project page map
 6. Create or update Pencil designs for the required pages
 7. Bind implementation pages to Pencil pages
@@ -221,14 +232,15 @@ Use these artifacts unless the project defines a different schema:
 3. `DA-VINCI.md`
 4. `.da-vinci/changes/<change-id>/design-brief.md`
 5. `.da-vinci/design-registry.md`
-6. `.da-vinci/page-map.md`
-7. `.da-vinci/changes/<change-id>/proposal.md`
-8. `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
-9. `.da-vinci/changes/<change-id>/design.md`
-10. `.da-vinci/changes/<change-id>/pencil-design.md`
-11. `.da-vinci/changes/<change-id>/pencil-bindings.md`
-12. `.da-vinci/changes/<change-id>/tasks.md`
-13. `.da-vinci/changes/<change-id>/verification.md`
+6. `.da-vinci/designs/`
+7. `.da-vinci/page-map.md`
+8. `.da-vinci/changes/<change-id>/proposal.md`
+9. `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
+10. `.da-vinci/changes/<change-id>/design.md`
+11. `.da-vinci/changes/<change-id>/pencil-design.md`
+12. `.da-vinci/changes/<change-id>/pencil-bindings.md`
+13. `.da-vinci/changes/<change-id>/tasks.md`
+14. `.da-vinci/changes/<change-id>/verification.md`
 
 Not every mode requires every artifact.
 
@@ -254,6 +266,7 @@ Optional artifacts:
 - `DA-VINCI.md`: project-level visual contract for theme, color system, surface treatment, typography direction, and cross-page style rules
 - `design-brief.md`: form factor, visual direction, density, brand constraints, and UI preferences
 - `design-registry.md`: project-level `.pen` file inventory and active design sources
+- `.da-vinci/designs/`: project-local persisted Pencil sources such as `project-baseline.pen` or change-specific `.pen` files
 - `page-map.md`: canonical page list, page responsibilities, route mapping, and page states
 - `proposal.md`: scope, goal, non-goals, and success criteria
 - `spec.md`: behavior, states, inputs, outputs, edge cases, and acceptance rules
@@ -277,10 +290,17 @@ Keep this file at the project root so the visual contract is easy to discover an
 
 - `.da-vinci/project-inventory.md`
 - `.da-vinci/design-registry.md`
+- `.da-vinci/designs/`
 - `.da-vinci/page-map.md`
 
 These files describe project-wide facts that can outlive any one change.
 
+Recommended `.pen` persistence patterns:
+
+- `.da-vinci/designs/project-baseline.pen`
+- `.da-vinci/designs/<change-id>.pen`
+- `.da-vinci/designs/<change-id>/main.pen`
+
 ### Change-level workflow directory
 
 - `.da-vinci/changes/<change-id>/brainstorm.md`
@@ -375,6 +395,8 @@ Do not split page-by-page unless the product is unusually fragmented. Prefer imp
 
 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.
+
 Use `DA-VINCI.md` as the project-level visual source of truth for:
 
 - theme and palette
@@ -382,20 +404,30 @@ Use `DA-VINCI.md` as the project-level visual source of truth for:
 - typography direction
 - component tone
 - rules for cross-page consistency
+- optional visual adapter preferences
+
+Treat visual adapters as optional helpers for presentation quality only.
+
+- they may refine `DA-VINCI.md`, `design.md`, and `pencil-design.md`
+- they must not override behavior truth from requirements or existing code
+- they must not replace `page-map.md`, `design-registry.md`, or `pencil-bindings.md`
 
 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
 
 When `DA-VINCI.md` already exists:
 
 - use it as the baseline visual contract
 - do not regenerate visual direction from scratch unless the change explicitly rebrands or resets the product style
+- if it declares preferred visual adapters, try to resolve them without blocking the workflow
 
 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`
 
 When project mappings do not exist but existing code exists:
 
@@ -404,12 +436,27 @@ When project mappings do not exist but existing code exists:
 - reconstruct `page-map.md`
 - create or rebuild `design-registry.md`
 - generate a new Pencil baseline only after the inventory is stable
+- save or export that baseline into `.da-vinci/designs/` when possible
 
 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`
+
+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
+
+When visual adapters are requested:
+
+- resolve them from local availability when possible
+- choose one primary adapter when multiple helpers are available
+- record the requested adapters, resolved primary adapter, any secondary helpers, and fallback status in `design-registry.md`
+- continue with native Da Vinci design rules when no adapter is available unless the user explicitly requires a specific adapter
 
 If the request is too vague to design or implement safely, ask a short clarification question before generating artifacts.
 
@@ -422,6 +469,7 @@ 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 resolved visual adapter, when available, for composition, hierarchy, restraint, and motion guidance
 - 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
@@ -432,11 +480,13 @@ 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
 
 ## Pencil MCP Rules
 
 When Pencil is available through MCP:
 
+- Prefer the project-local `.pen` file under `.da-vinci/designs/` when one is registered
 - 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