@xenonbyte/da-vinci-workflow 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 - No unreleased changes yet.
 
+## 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,13 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.7`
+- `@xenonbyte/da-vinci-workflow@0.1.8`
 
 Release highlights:
 
+- 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 +90,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 +108,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 +125,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 +151,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 +173,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 +226,25 @@ 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
 
 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
 
@@ -299,9 +312,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 +395,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 +416,7 @@ $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/workflow-examples.md`
 - `docs/mode-use-cases.md`
 

package/README.zh-CN.md

@@ -29,10 +29,13 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.7`
+- `@xenonbyte/da-vinci-workflow@0.1.8`
 
 已发布版本重点：
 
+- 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 +95,7 @@ Da Vinci 的默认顺序是：
 1. 选择 mode
 2. 生成正确的源工件
 3. 检测或生成 `DA-VINCI.md`
-4. 收集设计输入并登记设计源
+4. 收集设计输入，优先使用 `.da-vinci/designs/` 下的项目内 `.pen` 文件，并登记设计源
 5. 定义或发现页面地图
 6. 创建或更新 Pencil 设计
 7. 绑定实现页面到 Pencil 页面
@@ -110,6 +113,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 +130,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 +140,66 @@ 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 页面绑定的真相源
+
+当已有页面映射存在时：
+
+- 优先复用已绑定的 Pencil 设计源
+- 如果 `design-registry.md` 里已经登记了 `.da-vinci/designs/` 下的本地 `.pen` 路径，优先使用它
+
+当已有代码存在但还没有映射时：
+
+- 先从当前项目重建设计基线
+- 重建 inventory、page-map、design-registry
+- 在可行时把新的 Pencil 基线保存或导出到 `.da-vinci/designs/`
+
+当既没有映射也没有可用设计源时：
+
+- 基于当前本地真相源创建新的 Pencil 基线
+- 在可行时把基线保存到 `.da-vinci/designs/`
+- 并在 `design-registry.md` 里记录准确路径
+
 ## 安装
 
 安装 npm 包：
@@ -177,9 +242,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,19 +308,27 @@ $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/workflow-examples.md`
 - `docs/mode-use-cases.md`

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
@@ -184,7 +187,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 +224,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 +258,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 +282,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 +387,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
@@ -386,6 +400,7 @@ Use `DA-VINCI.md` as the project-level visual source of truth for:
 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:
@@ -396,6 +411,7 @@ When `DA-VINCI.md` already exists:
 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 +420,20 @@ 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
 
 If the request is too vague to design or implement safely, ask a short clarification question before generating artifacts.
 
@@ -432,11 +456,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

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

@@ -0,0 +1,167 @@
+# Codex Natural-Language Usage
+
+Use this document when running Da Vinci from Codex through the natural-language skill entrypoint.
+
+## Core Rule
+
+In Codex, use:
+
+```text
+$da-vinci ...
+```
+
+as the primary workflow entry.
+
+The `$` prefix is a Codex skill invocation pattern inside the chat interface.
+It is not a shell command.
+
+## Base Patterns
+
+Use these patterns in Codex:
+
+### Start from a rough project situation
+
+```text
+$da-vinci use intake for <project situation>
+```
+
+Use this when:
+
+- the project is complex
+- the user does not know how to phrase the first workflow request
+- there are multiple truth sources
+
+### Ask for prompt text only
+
+```text
+$da-vinci use prompt for <known scenario>
+```
+
+Use this when:
+
+- the mode is already obvious
+- the user only wants copy-ready prompt text
+
+### Resume an existing workflow
+
+```text
+$da-vinci use continue for <existing workflow state>
+```
+
+Use this when:
+
+- `DA-VINCI.md` already exists
+- `.da-vinci/` artifacts already exist
+- the workflow paused and needs to resume
+
+### Run a mode directly
+
+```text
+$da-vinci use <mode> to <goal>
+```
+
+Supported modes:
+
+- `greenfield-spec`
+- `greenfield-brainstorm`
+- `redesign-from-code`
+- `feature-change`
+
+## Scenario Recipes
+
+### 1. New project with clear requirements
+
+```text
+$da-vinci use greenfield-spec to break down a new product into specs, page map, Pencil-backed design work, implementation tasks, and final code.
+```
+
+### 2. New project with rough ideas
+
+```text
+$da-vinci use greenfield-brainstorm to turn several rounds of rough product ideas into a stable proposal, specs, page map, Pencil-backed design work, and implementation tasks.
+```
+
+### 3. Existing product with broad UI redesign
+
+```text
+$da-vinci use redesign-from-code to inventory the current product, preserve existing behavior, split the redesign into implementation-safe slices, and deliver the redesigned UI.
+```
+
+### 4. Existing product with one scoped change
+
+```text
+$da-vinci use feature-change to add or update one scoped feature, generate any required Pencil design delta, and implement the change safely.
+```
+
+### 5. Existing Android project with global UI replacement
+
+```text
+$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.
+Preserve business logic, navigation, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
+Inspect the real codebase first and determine whether the UI stack is Jetpack Compose, XML, or mixed.
+Inventory all activities, fragments, composable destinations, nav graphs, dialogs, bottom sheets, tabs, nested flows, shared shells, subpages, and important states.
+Split the redesign into implementation-safe slices.
+Do not start code changes yet.
+Generate the best executable Da Vinci workflow prompt for the next step.
+```
+
+### 6. Existing Android project with HTML references
+
+```text
+$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.
+UI reference directory: /abs/path/to/mockups
+Treat the HTML files there as presentation references only, not behavior truth.
+Preserve business logic, navigation, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
+Inspect the real codebase first and determine whether the UI stack is Jetpack Compose, XML, or mixed.
+Inventory all activities, fragments, composable destinations, nav graphs, dialogs, bottom sheets, tabs, nested flows, shared shells, subpages, and important states.
+Split the redesign into implementation-safe slices.
+Treat this as full-delivery.
+```
+
+### 7. Continue after inventory and spec work
+
+```text
+$da-vinci use continue for this existing redesign-from-code workflow.
+
+Use the existing Da Vinci artifacts in this project.
+Existing code remains the behavior source of truth.
+Do not restart discovery unless an artifact is missing or clearly wrong.
+Do not stop at tasks.md.
+Continue into implementation and verification.
+```
+
+### 8. Ask for a scenario-specific prompt only
+
+```text
+$da-vinci use prompt for an existing Android project that needs a global UI replacement while keeping existing code behavior as the source of truth and using HTML files as presentation references.
+```
+
+## Practical Rule
+
+Use this default sequence in Codex:
+
+1. start with `intake` when the project is complex
+2. execute the generated main workflow prompt
+3. use `continue` when artifacts already exist and the workflow needs to resume
+
+If the mode is already obvious, skip `intake` and run the mode directly.
+
+## What To Avoid
+
+Do not treat `$da-vinci` as a shell command.
+
+Do not assume visual references can override behavior truth in existing projects.
+
+Do not default complex existing-project work straight into `build`.
+
+Prefer:
+
+- `use intake` for unclear starts
+- `use redesign-from-code` for broad UI replacement
+- `use feature-change` for narrow existing-product work

package/docs/mode-use-cases.md

@@ -19,6 +19,9 @@ project/
 └── .da-vinci/
     ├── project-inventory.md
     ├── design-registry.md
+    ├── designs/
+    │   ├── project-baseline.pen
+    │   └── <change-id>.pen
     ├── page-map.md
     └── changes/
         └── <change-id>/
@@ -38,6 +41,7 @@ Rule:
 
 - only `DA-VINCI.md` belongs at the project root
 - all other workflow outputs should stay under `.da-vinci/`
+- persisted project-local Pencil files should stay under `.da-vinci/designs/`
 
 ## Quick mode selection
 
@@ -126,12 +130,14 @@ Generate DA-VINCI.md, proposal, specs, page map, Pencil-backed launch pages, bin
 
 6. create `design-registry.md`
    - register the active `.pen` source once Pencil work starts
+   - prefer a project-local `.pen` path under `.da-vinci/designs/`
 
 7. create `design.md`
    - define page structure and layout strategy
 
 8. create `pencil-design.md`
    - record the generated Pencil screens
+   - save or export the active `.pen` file into `.da-vinci/designs/` when possible
 
 9. create `pencil-bindings.md`
    - map implementation pages to Pencil pages
@@ -220,6 +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
 
 ### Where this mode differs from `greenfield-spec`
 
@@ -306,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
+   - mark the preferred project-local `.pen` file under `.da-vinci/designs/` when available
 
 4. create or update `page-map.md`
    - identify canonical implementation pages
@@ -315,6 +323,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
 
 7. create or update `pencil-bindings.md`
    - bind pages to redesign screens
@@ -460,9 +469,11 @@ Keep the current behavior and project style baseline, update the affected page m
 
 5. update `design-registry.md`
    - if a new `.pen` source or screen is added
+   - record the preferred project-local `.pen` path under `.da-vinci/designs/` when available
 
 6. create `pencil-design.md` delta
    - only for the affected pages
+   - save or export the updated `.pen` file into `.da-vinci/designs/` when possible
 
 7. update `pencil-bindings.md`
    - bind the new or changed page

package/docs/prompt-entrypoints.md

@@ -81,9 +81,9 @@ Do not default this sequence to `build`.
 Use:
 
 ```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
@@ -111,7 +111,11 @@ Use:
 Use:
 
 ```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 code is the behavior source of truth.
+HTML references are in /abs/path/to/mockups.
 ```
 
 Expected outcome:
@@ -126,7 +130,10 @@ Expected outcome:
 Use:
 
 ```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.
 ```
 
 Expected outcome:

package/docs/workflow-examples.md

@@ -121,11 +121,18 @@ And in every mode:
 When the user starts from a complex existing project and does not know how to phrase the first request:
 
 ```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 code is the behavior source of truth.
+HTML references are in /abs/path/to/mockups.
 ```
 
 When the project already has artifacts and needs to resume:
 
 ```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.
 ```

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

@@ -0,0 +1,168 @@
+# Codex 自然语言用法
+
+> 中文配套文档。若与英文原文存在差异，请以 `docs/codex-natural-language-usage.md` 为准。
+
+这份文档专门说明在 Codex 里如何通过自然语言入口使用 Da Vinci。
+
+## 核心规则
+
+在 Codex 里，把：
+
+```text
+$da-vinci ...
+```
+
+当成主工作流入口。
+
+这里的 `$` 是 Codex 对话里的 skill 调用前缀，不是终端 shell 命令。
+
+## 基本模式
+
+在 Codex 里优先用下面这些写法。
+
+### 从模糊项目起点进入
+
+```text
+$da-vinci use intake for <project situation>
+```
+
+适用：
+
+- 项目复杂
+- 用户不知道第一条工作流请求该怎么写
+- 存在多个真相源
+
+### 只需要提示词文本
+
+```text
+$da-vinci use prompt for <known scenario>
+```
+
+适用：
+
+- mode 已经明确
+- 用户只需要可复制的提示词
+
+### 恢复已有工作流
+
+```text
+$da-vinci use continue for <existing workflow state>
+```
+
+适用：
+
+- 已经存在 `DA-VINCI.md`
+- 已经存在 `.da-vinci/` 工件
+- 工作流中途暂停，需要恢复
+
+### 直接运行某个 mode
+
+```text
+$da-vinci use <mode> to <goal>
+```
+
+支持的 mode：
+
+- `greenfield-spec`
+- `greenfield-brainstorm`
+- `redesign-from-code`
+- `feature-change`
+
+## 场景模板
+
+### 1. 新项目，需求清晰
+
+```text
+$da-vinci use greenfield-spec to break down a new product into specs, page map, Pencil-backed design work, implementation tasks, and final code.
+```
+
+### 2. 新项目，想法还比较发散
+
+```text
+$da-vinci use greenfield-brainstorm to turn several rounds of rough product ideas into a stable proposal, specs, page map, Pencil-backed design work, and implementation tasks.
+```
+
+### 3. 已有产品，要做大范围 UI 重设计
+
+```text
+$da-vinci use redesign-from-code to inventory the current product, preserve existing behavior, split the redesign into implementation-safe slices, and deliver the redesigned UI.
+```
+
+### 4. 已有产品，只做一个范围明确的改动
+
+```text
+$da-vinci use feature-change to add or update one scoped feature, generate any required Pencil design delta, and implement the change safely.
+```
+
+### 5. 现有 Android 项目整体替换 UI
+
+```text
+$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.
+Preserve business logic, navigation, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
+Inspect the real codebase first and determine whether the UI stack is Jetpack Compose, XML, or mixed.
+Inventory all activities, fragments, composable destinations, nav graphs, dialogs, bottom sheets, tabs, nested flows, shared shells, subpages, and important states.
+Split the redesign into implementation-safe slices.
+Do not start code changes yet.
+Generate the best executable Da Vinci workflow prompt for the next step.
+```
+
+### 6. 现有 Android 项目，同时带 HTML 参考稿
+
+```text
+$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.
+UI reference directory: /abs/path/to/mockups
+Treat the HTML files there as presentation references only, not behavior truth.
+Preserve business logic, navigation, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
+Inspect the real codebase first and determine whether the UI stack is Jetpack Compose, XML, or mixed.
+Inventory all activities, fragments, composable destinations, nav graphs, dialogs, bottom sheets, tabs, nested flows, shared shells, subpages, and important states.
+Split the redesign into implementation-safe slices.
+Treat this as full-delivery.
+```
+
+### 7. 盘点和 spec 完成后继续
+
+```text
+$da-vinci use continue for this existing redesign-from-code workflow.
+
+Use the existing Da Vinci artifacts in this project.
+Existing code remains the behavior source of truth.
+Do not restart discovery unless an artifact is missing or clearly wrong.
+Do not stop at tasks.md.
+Continue into implementation and verification.
+```
+
+### 8. 只让它生成某个场景的提示词
+
+```text
+$da-vinci use prompt for an existing Android project that needs a global UI replacement while keeping existing code behavior as the source of truth and using HTML files as presentation references.
+```
+
+## 实用规则
+
+在 Codex 里，推荐默认顺序是：
+
+1. 起点复杂时先用 `intake`
+2. 执行它生成的主工作流提示词
+3. 工件已经存在、流程要恢复时再用 `continue`
+
+如果 mode 已经非常明确，可以跳过 `intake`，直接运行对应 mode。
+
+## 不要这样用
+
+不要把 `$da-vinci` 当成 shell 命令。
+
+不要在已有项目里让视觉参考覆盖行为真相。
+
+不要把复杂的存量项目一上来就直接导向 `build`。
+
+更稳的选择是：
+
+- 起点不清晰时用 `use intake`
+- 大范围 UI 替换时用 `use redesign-from-code`
+- 范围明确的存量改动时用 `use feature-change`

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

@@ -12,6 +12,9 @@ project/
 └── .da-vinci/
     ├── project-inventory.md
     ├── design-registry.md
+    ├── designs/
+    │   ├── project-baseline.pen
+    │   └── <change-id>.pen
     ├── page-map.md
     └── changes/
         └── <change-id>/
@@ -31,6 +34,7 @@ project/
 
 - `DA-VINCI.md` 放根目录
 - 其他工作流工件放 `.da-vinci/`
+- 项目内持久化的 Pencil `.pen` 文件默认放 `.da-vinci/designs/`
 
 ## 快速选 mode
 
@@ -82,8 +86,10 @@ Da Vinci 应该：
 4. 生成 `specs/<capability>/spec.md`
 5. 生成 `page-map.md`
 6. 生成 `design-registry.md`
+   - 优先登记 `.da-vinci/designs/` 下的本地 `.pen` 路径
 7. 生成 `design.md`
 8. 生成 `pencil-design.md`
+   - 在可行时把当前 `.pen` 文件保存或导出到 `.da-vinci/designs/`
 9. 生成 `pencil-bindings.md`
 10. 生成 `tasks.md`
 11. 进入实现
@@ -104,6 +110,7 @@ Da Vinci 应该：
 5. 生成 `specs/<capability>/spec.md`
 6. 生成 `page-map.md`
 7. 继续到设计、绑定、任务和实现
+   - 在可行时把当前 `.pen` 文件保存或导出到 `.da-vinci/designs/`
 
 ## 3. `redesign-from-code`
 
@@ -118,11 +125,13 @@ Da Vinci 应该：
 1. 先做 `project-inventory.md`
 2. 生成或对齐 `DA-VINCI.md`
 3. 生成 `design-registry.md`
+   - 如已有本地 `.pen` 文件，优先登记 `.da-vinci/designs/` 下的路径
 4. 生成 `proposal.md`
 5. 按 redesign slice 拆分 `specs/`
 6. 重建或更新 `page-map.md`
 7. 生成 `design.md`
 8. 生成 `pencil-design.md`
+   - 在可行时把新的 Pencil 基线持久化到 `.da-vinci/designs/`
 9. 生成 `pencil-bindings.md`
 10. 生成 `tasks.md`
 11. 进入实现
@@ -139,7 +148,9 @@ Da Vinci 应该：
 2. 写受影响行为到 `specs/<capability>/spec.md`
 3. 更新受影响的 `page-map.md`
 4. 复用或更新 `design-registry.md`
+   - 如果已有项目内 `.pen` 文件，优先登记 `.da-vinci/designs/` 下的路径
 5. 生成 `pencil-design.md` 增量
+   - 在可行时把更新后的 `.pen` 文件保存或导出到 `.da-vinci/designs/`
 6. 更新 `pencil-bindings.md`
 7. 生成 `tasks.md`
 8. 进入实现

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

@@ -80,9 +80,9 @@
 ### Codex
 
 ```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
@@ -104,7 +104,11 @@
 ## 示例：已有 Android 项目全局换 UI
 
 ```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 code is the behavior source of truth.
+HTML references are in /abs/path/to/mockups.
 ```
 
 预期输出：
@@ -117,7 +121,10 @@
 ## 示例：盘点完成后继续
 
 ```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.
 ```
 
 预期输出：

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

@@ -121,13 +121,20 @@ $da-vinci use feature-change to add a billing page, generate the Pencil design d
 如果用户起点是复杂的存量项目重设计，可以先这样：
 
 ```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 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.
 ```
 
 ## 跨模式共同规则

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "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

@@ -10,6 +10,7 @@ Write artifacts into the target project using this rule:
 
 - keep `DA-VINCI.md` at the project root
 - keep project-level workflow files in `.da-vinci/`
+- keep project-local Pencil `.pen` files in `.da-vinci/designs/`
 - keep change-level workflow files in `.da-vinci/changes/<change-id>/`
 
 Recommended placement:
@@ -20,6 +21,9 @@ project/
 └── .da-vinci/
     ├── project-inventory.md
     ├── design-registry.md
+    ├── designs/
+    │   ├── project-baseline.pen
+    │   └── <change-id>.pen
     ├── page-map.md
     └── changes/
         └── <change-id>/
@@ -212,11 +216,13 @@ Use this structure:
 
 ## Active Design Sources
 - `.pen` file path
+- whether it lives under `.da-vinci/designs/`
 - status
 - purpose
 
 ## Preferred Design Source
 - Which `.pen` file is authoritative
+- Why that file should be preferred over live-only or external sources
 
 ## Historical Or Secondary Sources
 - Legacy files
@@ -225,6 +231,7 @@ Use this structure:
 ## Notes
 - Why a source is active
 - Whether a source is safe to iterate
+- Whether local export is still pending
 ```
 
 Use this artifact whenever a project can have one or more Pencil sources.
@@ -394,6 +401,7 @@ Use this structure:
 
 ## Source
 - `.pen` file path
+- project-local persisted path under `.da-vinci/designs/` when available
 - Active pages
 
 ## Page Mapping
@@ -413,6 +421,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
 ```
 
 Recommended path:
@@ -458,6 +467,7 @@ Use this structure:
 
 ## Source
 - `.pen` file path
+- project-local persisted path under `.da-vinci/designs/` when available
 
 ## Bindings
 - implementation page or route -> Pencil page or screen
@@ -468,6 +478,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
 ```
 
 Use this artifact whenever implementation must trace back to Pencil pages.

package/references/design-inputs.md

@@ -4,9 +4,10 @@ Use this reference when collecting product form factor, UI direction, and design
 
 ## Visual Contract Detection
 
-Check for `DA-VINCI.md` first.
+Check for `DA-VINCI.md` first, then check whether the project already has persisted Pencil files under `.da-vinci/designs/`.
 
 - if it exists, treat it as the project visual contract
+- if `.da-vinci/designs/*.pen` exists, treat those files as project-local design inputs and record the exact preferred path in `design-registry.md`
 - 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
 
@@ -44,10 +45,11 @@ Collect or infer:
 Infer in this order:
 
 1. `DA-VINCI.md`
-2. existing artifacts
-3. existing codebase
-4. user statements
-5. direct clarification
+2. project-local `.pen` files under `.da-vinci/designs/`
+3. existing artifacts
+4. existing codebase
+5. user statements
+6. direct clarification
 
 ## When To Ask
 
@@ -64,3 +66,5 @@ Examples:
 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`.

package/references/page-mapping.md

@@ -8,6 +8,8 @@ Treat `page-map.md` as the source of truth for implementation pages.
 
 Treat `design-registry.md` as the source of truth for available `.pen` sources.
 
+Treat `.da-vinci/designs/` as the default project-local storage for persisted `.pen` files.
+
 Treat `pencil-bindings.md` as the source of truth for:
 
 - implementation page -> Pencil page
@@ -29,6 +31,12 @@ Use a simple mapping line:
 - `/settings/billing` -> `Billing Settings Screen`
 ```
 
+If the binding depends on a specific project-local source, record that exact file in `design-registry.md`, for example:
+
+```md
+- Preferred `.pen`: `.da-vinci/designs/project-baseline.pen`
+```
+
 For shared regions:
 
 ```md
@@ -40,6 +48,7 @@ For shared regions:
 Treat bindings as insufficient when:
 
 - no active `.pen` source is registered
+- the only known Pencil source is a live or external session and no project-local persistence path is recorded
 - the implementation page has no Pencil source
 - the Pencil page exists but cannot be traced to a route or page responsibility
 - shared layout regions are undefined and implementation would guess too much

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

@@ -16,6 +16,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
 - target page frame
 - child section hierarchy

package/references/platform-adapters.md

@@ -25,12 +25,12 @@ Use this for:
 - Pencil page generation planning
 - design-to-code implementation
 
-Explicit helper routes:
+Natural-language helper patterns:
 
 ```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>
 ```
 
 Use them when: