docs(dx): close cookbook and migration path

README.md

@@ -22,8 +22,9 @@ AsterGraph is a modular node-graph editor toolkit for .NET. It gives hosts a reu
 
 | I want to... | Start here | Why |
 | --- | --- | --- |
-| get the fastest first run | [`tools/AsterGraph.HelloWorld`](./tools/AsterGraph.HelloWorld/) | smallest runtime-only sample; one canonical route for custom UI or native shells |
-| embed the shipped Avalonia UI | [`tools/AsterGraph.HelloWorld.Avalonia`](./tools/AsterGraph.HelloWorld.Avalonia/) | smallest hosted-UI sample on the factory-based Avalonia route |
+| get the first hosted entry | [`tools/AsterGraph.Starter.Avalonia`](./tools/AsterGraph.Starter.Avalonia/) | smallest end-to-end Avalonia scaffold; the first hosted hop in the cookbook |
+| get the fastest runtime-only first run | [`tools/AsterGraph.HelloWorld`](./tools/AsterGraph.HelloWorld/) | smallest runtime-only sample; one canonical route for custom UI or native shells |
+| embed the shipped Avalonia UI | [`tools/AsterGraph.HelloWorld.Avalonia`](./tools/AsterGraph.HelloWorld.Avalonia/) | smallest stock hosted-UI sample after the starter scaffold |
 | try a realistic hosted integration | [Consumer Sample](./tools/AsterGraph.ConsumerSample.Avalonia/README.md) | medium sample on the same canonical route, with host-owned actions, parameter editing, and one trusted plugin |
 | integrate into an existing host | [Host Integration](./docs/en/host-integration.md) | route matrix, package boundary, migration guidance |
 | inspect the full surface visually | [Demo Guide](./docs/en/demo-guide.md) | showcase host for plugins, automation, localization, and standalone surfaces |
@@ -50,18 +51,20 @@ Add `AsterGraph.Core` only when the host also needs direct `GraphDocument`, seri
 
 | Route | Use when | First API | First sample |
 | --- | --- | --- | --- |
+| Hosted starter scaffold | the host wants the smallest end-to-end Avalonia entry before a fuller app | `AsterGraphEditorFactory.Create(...)` + `AsterGraphAvaloniaViewFactory.Create(...)` | [`AsterGraph.Starter.Avalonia`](./tools/AsterGraph.Starter.Avalonia/) |
 | Runtime-only or custom UI | the host owns its own UI and wants the canonical runtime boundary | `AsterGraphEditorFactory.CreateSession(...)` + `IGraphEditorSession` | [`AsterGraph.HelloWorld`](./tools/AsterGraph.HelloWorld/) |
-| Shipped Avalonia UI | the host wants the stock editor shell or stock standalone Avalonia surfaces | `AsterGraphEditorFactory.Create(...)` + `AsterGraphAvaloniaViewFactory.Create(...)` | [Quick Start](./docs/en/quick-start.md) |
+| Shipped Avalonia UI | the host wants the stock editor shell or stock standalone Avalonia surfaces | `AsterGraphEditorFactory.Create(...)` + `AsterGraphAvaloniaViewFactory.Create(...)` | [`AsterGraph.HelloWorld.Avalonia`](./tools/AsterGraph.HelloWorld.Avalonia/) |
 | Retained migration | the host is moving off older MVVM-shaped entry points in planned batches | `new GraphEditorViewModel(...)` + `new GraphEditorView { Editor = editor }` | [Host Integration](./docs/en/host-integration.md) |
 
 For new runtime-facing work, anchor on the first route. The Avalonia route is the supported hosted adapter path today, while the retained route stays migration-only.
 
 ## Public Entry Map
 
+- [`tools/AsterGraph.Starter.Avalonia`](./tools/AsterGraph.Starter.Avalonia/) = first hosted scaffold; the smallest end-to-end Avalonia entry
 - [`tools/AsterGraph.HelloWorld`](./tools/AsterGraph.HelloWorld/) = first-run sample for the runtime-only path
-- [`tools/AsterGraph.HelloWorld.Avalonia`](./tools/AsterGraph.HelloWorld.Avalonia/) = first-run sample for the hosted Avalonia UI path
-- [`tools/AsterGraph.ConsumerSample.Avalonia`](./tools/AsterGraph.ConsumerSample.Avalonia/README.md) = medium hosted-UI consumer sample with one custom node family, one host action rail, and one trusted plugin
-- [`tools/AsterGraph.HostSample`](./tools/AsterGraph.HostSample/) = minimal canonical proof harness for runtime-only and hosted-UI validation
+- [`tools/AsterGraph.HelloWorld.Avalonia`](./tools/AsterGraph.HelloWorld.Avalonia/) = smallest stock hosted-UI sample after the starter scaffold
+- [`tools/AsterGraph.ConsumerSample.Avalonia`](./tools/AsterGraph.ConsumerSample.Avalonia/README.md) = realistic hosted-UI consumer sample between `HelloWorld.Avalonia` and `Demo`
+- [`tools/AsterGraph.HostSample`](./tools/AsterGraph.HostSample/) = proof harness for runtime-only and hosted-UI validation, not the onboarding step
 - [`tools/AsterGraph.PackageSmoke`](./tools/AsterGraph.PackageSmoke/) = packed-package proof
 - [`tools/AsterGraph.ScaleSmoke`](./tools/AsterGraph.ScaleSmoke/) = public larger-graph baseline plus history/state proof
 - [`src/AsterGraph.Demo`](./src/AsterGraph.Demo/) = showcase host; menu labels follow the current UI language

README.zh-CN.md

@@ -22,8 +22,9 @@ AsterGraph 是一个面向 .NET 的模块化节点图编辑器工具包，提供
 
 | 我现在要做什么 | 先看哪里 | 为什么 |
 | --- | --- | --- |
-| 想最快跑起来 | [`tools/AsterGraph.HelloWorld`](./tools/AsterGraph.HelloWorld/) | 最小仅运行时样例；面向自定义 UI 或原生壳层的 canonical 路线 |
-| 想嵌入默认 Avalonia UI | [`tools/AsterGraph.HelloWorld.Avalonia`](./tools/AsterGraph.HelloWorld.Avalonia/) | 基于 factory 路线的最小默认 UI 样例 |
+| 想先看第一个 hosted 入口 | [`tools/AsterGraph.Starter.Avalonia`](./tools/AsterGraph.Starter.Avalonia/) | 最小端到端 Avalonia 脚手架；cookbook 里的第一个 hosted 跳板 |
+| 想最快跑起仅运行时路径 | [`tools/AsterGraph.HelloWorld`](./tools/AsterGraph.HelloWorld/) | 最小仅运行时样例；面向自定义 UI 或原生壳层的 canonical 路线 |
+| 想嵌入默认 Avalonia UI | [`tools/AsterGraph.HelloWorld.Avalonia`](./tools/AsterGraph.HelloWorld.Avalonia/) | 在 starter 之后的最小默认 UI 样例 |
 | 想先看一个更真实的宿主集成 | [Consumer Sample](./tools/AsterGraph.ConsumerSample.Avalonia/README.md) | 同一条 canonical 路线上的中等复杂度样例，包含宿主动作、参数编辑和一个可信插件 |
 | 想接到现有宿主里 | [Host Integration](./docs/zh-CN/host-integration.md) | 路线矩阵、包边界和迁移说明 |
 | 想先把完整能力看一遍 | [Demo Guide](./docs/zh-CN/demo-guide.md) | 展示插件、自动化、本地化和独立表面 |
@@ -50,18 +51,20 @@ dotnet add package AsterGraph.Abstractions --prerelease
 
 | 路线 | 适合什么场景 | 第一个 API | 第一个样例 |
 | --- | --- | --- | --- |
+| Hosted starter scaffold | 宿主先要一个最小端到端的 Avalonia 入口，再往完整应用扩展 | `AsterGraphEditorFactory.Create(...)` + `AsterGraphAvaloniaViewFactory.Create(...)` | [`AsterGraph.Starter.Avalonia`](./tools/AsterGraph.Starter.Avalonia/) |
 | 仅运行时 / 自定义 UI | 宿主自己管 UI，只想拿推荐的运行时边界 | `AsterGraphEditorFactory.CreateSession(...)` + `IGraphEditorSession` | [`AsterGraph.HelloWorld`](./tools/AsterGraph.HelloWorld/) |
-| 默认 Avalonia UI | 宿主想直接复用默认编辑器壳层或独立 Avalonia 表面 | `AsterGraphEditorFactory.Create(...)` + `AsterGraphAvaloniaViewFactory.Create(...)` | [Quick Start](./docs/zh-CN/quick-start.md) |
+| 默认 Avalonia UI | 宿主想直接复用默认编辑器壳层或独立 Avalonia 表面 | `AsterGraphEditorFactory.Create(...)` + `AsterGraphAvaloniaViewFactory.Create(...)` | [`AsterGraph.HelloWorld.Avalonia`](./tools/AsterGraph.HelloWorld.Avalonia/) |
 | retained 迁移 | 现有宿主要分批迁移，暂时还离不开旧的 MVVM 入口 | `new GraphEditorViewModel(...)` + `new GraphEditorView { Editor = editor }` | [Host Integration](./docs/zh-CN/host-integration.md) |
 
 新的运行时能力接入优先锚定第一条。Avalonia 路线是当前受支持的 hosted adapter 路线，retained 路线只作为迁移桥接。
 
 ## 公开入口分工
 
+- [`tools/AsterGraph.Starter.Avalonia`](./tools/AsterGraph.Starter.Avalonia/) = 第一个 hosted 脚手架；最小端到端 Avalonia 入口
 - [`tools/AsterGraph.HelloWorld`](./tools/AsterGraph.HelloWorld/) = 仅运行时第一跑样例
-- [`tools/AsterGraph.HelloWorld.Avalonia`](./tools/AsterGraph.HelloWorld.Avalonia/) = 默认 Avalonia UI 第一跑样例
-- [`tools/AsterGraph.ConsumerSample.Avalonia`](./tools/AsterGraph.ConsumerSample.Avalonia/README.md) = 中等复杂度 hosted-UI consumer 样例，展示宿主动作、参数编辑和一个可信插件
-- [`tools/AsterGraph.HostSample`](./tools/AsterGraph.HostSample/) = 仅运行时 / 默认 UI 两条推荐路线的最小验证样例
+- [`tools/AsterGraph.HelloWorld.Avalonia`](./tools/AsterGraph.HelloWorld.Avalonia/) = 在 starter 之后的最小默认 UI 样例
+- [`tools/AsterGraph.ConsumerSample.Avalonia`](./tools/AsterGraph.ConsumerSample.Avalonia/README.md) = 介于 `HelloWorld.Avalonia` 和 `Demo` 之间的真实 hosted-UI consumer 样例
+- [`tools/AsterGraph.HostSample`](./tools/AsterGraph.HostSample/) = 仅运行时 / 默认 UI 两条推荐路线的 proof harness，不是最先上手的入口
 - [`tools/AsterGraph.PackageSmoke`](./tools/AsterGraph.PackageSmoke/) = 打包消费验证
 - [`tools/AsterGraph.ScaleSmoke`](./tools/AsterGraph.ScaleSmoke/) = 公开的大图基线加 history/state 验证
 - [`src/AsterGraph.Demo`](./src/AsterGraph.Demo/) = 展示宿主；菜单标签会跟着当前 UI 语言切换

docs/en/alpha-status.md

@@ -14,6 +14,9 @@
 - the four publishable packages
 - canonical factory/session composition
 - default Avalonia hosted UI and standalone surfaces
+- runtime inspection surface for trusted, loaded, and blocked outcomes
+- command/trust timeline and perf overlay in the showcase host
+- `tools/AsterGraph.Starter.Avalonia` as the shipped Avalonia starter scaffold
 - plugin discovery, trust policy, load inspection, and runtime loading
 - automation execution through `IGraphEditorSession.Automation`
 - official proof lanes and smoke tools
@@ -43,7 +46,7 @@
 - the latest public prerelease tag is `v0.2.0-alpha.3`, while `v1.9` remains only as a historical pre-launch milestone marker
 - public prerelease publishing and release artifacts still depend on the maintainer release flow
 - the deepest package-validation lane and the `.NET 10` packed-consumer proof still run on the Windows release-validation path
-- retained compatibility APIs are still present during the migration window
+- retained compatibility APIs are still present during the migration window, but they are only a migration bridge
 - the public alpha still has only one official UI adapter today: Avalonia
 - advanced editing is now published as host-facing capability modules, but broader ecosystem and adapter validation work remains ahead
 

docs/en/consumer-sample.md

@@ -1,6 +1,6 @@
 # Consumer Sample
 
-`tools/AsterGraph.ConsumerSample.Avalonia` is the medium hosted-UI sample on the canonical session/runtime route, between the smallest `HelloWorld.Avalonia` route and the full `AsterGraph.Demo` showcase host.
+`tools/AsterGraph.ConsumerSample.Avalonia` is the medium hosted-UI sample on the canonical session/runtime route, after the starter scaffold and the smallest `HelloWorld.Avalonia` route, and before the full `AsterGraph.Demo` showcase host.
 
 ## What It Proves
 
@@ -42,10 +42,11 @@ Expected proof markers:
 
 ## When To Use This Sample
 
-Use `ConsumerSample.Avalonia` when you need one realistic host before jumping to the full `Demo`.
+Use `ConsumerSample.Avalonia` when you need one realistic host after `HelloWorld.Avalonia` and before the full `Demo`.
 
 Use a different artifact when you need something narrower:
 
+- `Starter.Avalonia` = first hosted scaffold and smallest end-to-end Avalonia entry
 - `HelloWorld` = smallest runtime-only first run
 - `HelloWorld.Avalonia` = smallest hosted-UI first run
 - `HostSample` = proof harness for canonical route validation

docs/en/demo-guide.md

@@ -77,10 +77,11 @@ Expected proof markers:
 
 ## Demo vs Other Entry Samples
 
+- `Starter.Avalonia` = first hosted scaffold; the smallest end-to-end Avalonia entry
 - `HelloWorld` = smallest runtime-only first-run sample
 - `HelloWorld.Avalonia` = smallest hosted-UI first-run sample
 - `ConsumerSample.Avalonia` = realistic hosted-UI consumer sample on the canonical route with one host action rail, parameter editing, and one trusted plugin
-- `HostSample` = narrow proof harness for the canonical consumer routes
+- `HostSample` = narrow proof harness for the canonical consumer routes, not the onboarding step
 - `Demo` = full showcase host for product surface and host boundary
 
-Use the demo when you need to inspect behavior visually. Use `HelloWorld` or `HelloWorld.Avalonia` for the quickest first run on a single route, `ConsumerSample.Avalonia` for one realistic hosted integration, and `HostSample` for proof-oriented route validation.
+Use the demo when you need to inspect behavior visually. Use `Starter.Avalonia` for the first hosted entry, `HelloWorld` or `HelloWorld.Avalonia` for the quickest first run on a single route, `ConsumerSample.Avalonia` for one realistic hosted integration, and `HostSample` for proof-oriented route validation.

docs/en/extension-contracts.md

@@ -27,6 +27,8 @@ This document publishes the contract around surface stability, compatibility ret
 - `CompatiblePortTarget`
 - older MVVM-shaped overloads where newer runtime-first alternatives already exist
 
+Use the retained surfaces only as migration bridges. New work should start on the stable canonical surfaces above, with [Host Integration](./host-integration.md) as the route map.
+
 ## Extension Precedence
 
 - plugin trust is host-owned and runs before activation

docs/en/host-integration.md

@@ -1,17 +1,17 @@
 # Host Integration Guide
 
-This guide expands the supported host routes without turning the public onboarding flow into maintainer proof documentation.
+This guide expands the supported host routes without turning the public onboarding flow into maintainer proof documentation. The canonical route stays session-first/runtime-first; retained MVVM is only a compatibility bridge during migration.
 
 ## Canonical Routes
 
 1. Runtime-only or custom UI  
    `AsterGraphEditorFactory.CreateSession(...)` + `IGraphEditorSession`
 2. Shipped Avalonia UI  
    `AsterGraphEditorFactory.Create(...)` + `AsterGraphAvaloniaViewFactory.Create(...)`
-3. Retained migration  
+3. Retained migration bridge
    `new GraphEditorViewModel(...)` + `new GraphEditorView { Editor = editor }`
 
-Routes 1 and 2 are the canonical surfaces for new work. Route 3 remains supported only as a retained compatibility facade during migration.
+Routes 1 and 2 are the canonical surfaces for new work. Route 3 remains supported only as a retained compatibility bridge for legacy hosts during migration.
 
 If the host owns its UI, route 1 is the canonical native/custom-UI path; you compose your own surface around the same session/runtime owner instead of introducing a second model.
 
@@ -25,12 +25,15 @@ Standalone Avalonia surfaces such as `AsterGraphCanvasViewFactory`, `AsterGraphI
 | Default Avalonia UI | `AsterGraph.Avalonia` | `Create(...)` + `AsterGraphAvaloniaViewFactory.Create(...)` | `tools/AsterGraph.HelloWorld.Avalonia` |
 | Plugin trust/discovery | `AsterGraph.Editor` | `DiscoverPluginCandidates(...)` + `PluginTrustPolicy` | `tools/AsterGraph.ConsumerSample.Avalonia` |
 | Automation | `AsterGraph.Editor` | `IGraphEditorSession.Automation.Execute(...)` | `src/AsterGraph.Demo` |
-| Retained migration | `AsterGraph.Editor` (+ `AsterGraph.Avalonia` when embedding `GraphEditorView`) | retained constructor path | migration-only |
+| Retained migration bridge | `AsterGraph.Editor` (+ `AsterGraph.Avalonia` when embedding `GraphEditorView`) | retained constructor path | migration-only legacy host |
+
+If you are starting new work, begin with [Quick Start](./quick-start.md) and keep the retained bridge for legacy migration only.
 
 ## Sample Roles
 
 - `AsterGraph.HelloWorld` = first-run sample for the runtime-only path
 - `AsterGraph.HelloWorld.Avalonia` = first-run sample for the shipped Avalonia UI path
+- `AsterGraph.Starter.Avalonia` = starter scaffold for the shipped Avalonia path
 - `AsterGraph.ConsumerSample.Avalonia` = medium hosted-UI sample on the canonical route with host actions, parameter editing, and one trusted plugin
 - `AsterGraph.HostSample` = narrow proof harness for the canonical runtime-only and hosted-UI routes
 - `AsterGraph.PackageSmoke` = packed-package proof
@@ -69,7 +72,7 @@ Short version:
 - leaving the saved snapshot through undo makes the editor dirty
 - returning to the saved snapshot through redo clears dirty again
 - no-op interactions must not latch fake dirty or undo state
-- retained and runtime mutations still share one kernel-owned history/save authority
+- retained and runtime mutations still share one kernel-owned history/save authority, but new integrations should still start on the canonical session route
 
 ## Export Versus Persistence
 
@@ -89,10 +92,10 @@ Important defaults:
 
 - canonical runtime surfaces are `CreateSession(...)`, `IGraphEditorSession`, and DTO/snapshot queries
 - `Create(...)` remains the supported hosted-Avalonia composition helper; `Editor.Session` is still the shared runtime owner behind that route
-- retained `GraphEditorViewModel` / `GraphEditorView` remain supported migration facades and are explicitly labeled as advanced compatibility surfaces
+- retained `GraphEditorViewModel` / `GraphEditorView` remain supported migration facades and are explicitly labeled as advanced compatibility bridge surfaces
 - host localization runs after plugin localization, so host override wins
 - plugin-contributed commands now surface through the canonical session command descriptors and execute through `IGraphEditorSession.Commands.TryExecuteCommand(...)`
-- retained host augmentor composition still differs from the runtime path; use the runtime path for new work
+- retained host augmentor composition still differs from the runtime path; use the runtime path for new work and treat the retained route as a bridge only
 
 ## Plugin Trust Boundary
 

docs/en/project-status.md

@@ -15,6 +15,7 @@
 - sample and proof tools:
   - `tools/AsterGraph.HelloWorld` for the quickest runtime-only first run
   - `tools/AsterGraph.HelloWorld.Avalonia` for the quickest hosted-UI first run
+  - `tools/AsterGraph.Starter.Avalonia` for the shipped Avalonia starter scaffold
   - `tools/AsterGraph.ConsumerSample.Avalonia` for one realistic hosted integration before the full Demo shell
   - `tools/AsterGraph.HostSample` for the minimal consumer proof harness
   - `tools/AsterGraph.PackageSmoke` for packed-package proof
@@ -28,6 +29,8 @@
 - the four-package SDK boundary
 - kernel/session-first runtime ownership
 - default Avalonia shell plus standalone surfaces
+- runtime inspection surface for trusted, loaded, and blocked outcomes
+- command/trust timeline and perf overlay in the showcase surface
 - v1.23 graph-surface usability proof markers:
   - `COMMAND_SURFACE_OK:True`
   - `TIERED_NODE_SURFACE_OK:True`
@@ -60,6 +63,7 @@ The current public-repo priority is turning the public alpha into a coherent SDK
 - keep public alpha documentation and proof guidance easy to follow as advanced editing closes
 - maintain hosted CI parity across the supported proof lanes
 - continue the retained compatibility migration window without abrupt public breaks
+- keep the shipped starter scaffold, runtime inspection surface, command/trust timeline, and perf overlay aligned with the canonical session-first route
 
 ## Public Entry Matrix
 
@@ -69,6 +73,7 @@ The current public-repo priority is turning the public alpha into a coherent SDK
 - `tools/AsterGraph.HostSample` = minimal canonical adoption proof
 - `tools/AsterGraph.PackageSmoke` = packed-package consumption proof
 - `tools/AsterGraph.ScaleSmoke` = larger-graph baseline plus history/state-continuity proof
+- `tools/AsterGraph.Starter.Avalonia` = shipped Avalonia starter scaffold
 - `src/AsterGraph.Demo` = showcase host for visual/manual inspection
 
 ## Public Entry Points