Implement live_ui phase 18 focused example alignment

.spec/decisions/live_ui/live_ui.tooling.focused_example_alignment.md

@@ -0,0 +1,85 @@
+---
+id: live_ui.tooling.focused_example_alignment
+status: accepted
+date: 2026-04-26
+affects:
+  - live_ui.package
+  - live_ui.tooling
+---
+
+# Focused Example Alignment for LiveUi
+
+## Context
+
+The repository now treats the root `examples/` directory as the authoritative
+widget-focused example suite. Each example is a standalone application with one
+clear widget or construct focus, one repeatable review workflow, and one shared
+runtime-target story across `live_ui`, `desktop_ui`, `elm_ui`, and
+`terminal_ui`.
+
+`live_ui` still carries a different maintainer surface:
+
+- a package-local demo workbench
+- a small package-owned maintained example catalog organized as native,
+  canonical, and mixed lanes
+- a widget preview inventory whose ids and coverage do not match the
+  repository example inventory one-for-one
+
+That creates three kinds of drift:
+
+1. **Inventory Drift** - maintainers have to reason about a repository example
+   inventory and a separate `live_ui` package inventory with different ids and
+   coverage rules.
+2. **Workflow Drift** - the root suite has moved toward focused standalone app
+   review, while `live_ui` still centers a package-local demo/workbench and
+   comparison-oriented package examples.
+3. **Meaning Drift** - package examples can become abstractions about
+   categories, continuity lanes, or demo states instead of concrete widget
+   examples that match what the ecosystem already exposes publicly.
+
+The package still needs strong maintainer review for native rendering,
+canonical rendering, transport behavior, and runtime authority. The question is
+what example surface should carry that burden.
+
+## Decision
+
+`live_ui` shall retire its current package-local demo/workbench and divergent
+package-owned example catalog in favor of the same focused example inventory
+used by the repository example suite, specialized for direct native `live_ui`
+widgets and runtime entrypoints.
+
+1. **One Focused Inventory** - The package shall align its maintained example
+   identities one-for-one with the repository widget-focused example inventory
+   instead of keeping a second package-specific catalog with unrelated names.
+2. **Native Package Specialization** - Each aligned `live_ui` example shall use
+   the package's own native widgets and runtime entrypoints directly rather than
+   re-authoring the package example surface through `unified_ui`.
+3. **No Aggregate Demo Workbench** - The package shall not keep a package-local
+   demo/workbench as the primary review entry point once the aligned focused
+   examples exist.
+4. **Canonical Review on the Same Ids** - When package validation still needs
+   canonical `UnifiedIUR` rendering, transport inspection, or continuity
+   comparison, those workflows shall attach to the same focused example ids
+   rather than introducing separate example families or demo-only artifacts.
+5. **Package Tooling Follows the Inventory** - `mix live_ui.preview`,
+   `mix live_ui.inspect`, `mix live_ui.export`, and `mix live_ui.validate`
+   shall operate on the aligned focused example inventory and its package
+   specializations.
+6. **Repository Examples Stay Authoritative** - The repository `examples/`
+   inventory remains the authoritative cross-runtime example catalog; `live_ui`
+   specializes that inventory for native runtime review rather than replacing
+   or forking it.
+
+## Consequences
+
+- Maintainers review the same widget-focused example identities across the root
+  suite and the `live_ui` package.
+- The package loses a separate demo/workbench concept and the extra cognitive
+  layer that goes with it.
+- Example coverage gaps become easier to spot because missing package examples
+  map directly to missing repository example ids.
+- Native `live_ui` review becomes more concrete because examples are anchored to
+  real widget-focused application stories instead of category-level demo lanes.
+- Canonical rendering and transport diagnostics still remain available, but
+  they become inspection modes on the same example ids rather than a separate
+  maintained example taxonomy.

.spec/planning/live_ui/README.md

@@ -40,6 +40,7 @@ The plan aligns to:
 15. [Phase 15 - Canonical Renderer Convergence](./phase-15-canonical-renderer-convergence.md): finish the convergence work so canonical `UnifiedIUR` rendering targets the same widget component boundaries used by direct native screens.
 16. [Phase 16 - Advanced Widget Integration Tests](./phase-16-advanced-widget-integration-tests.md): validate the complete widget-component architecture end to end across all widget families.
 17. [Phase 17 - Tooling, Demo, Validation, and Release Readiness for Widget Components](./phase-17-tooling-demo-validation-and-release-readiness-for-widget-components.md): finish the widget-component transition with demo/example upgrades, tooling visibility, validation gates, documentation, and cleanup of legacy helper-only paths.
+18. [Phase 18 - Focused Example Alignment and Demo Retirement](./phase-18-focused-example-alignment-and-demo-retirement.md): replace the package-local demo and divergent example catalog with `live_ui`-native specializations of the repository widget-focused example inventory, and move tooling, docs, and validation onto those aligned example ids.
 
 ## Shared Conventions
 - Numbering:

.spec/planning/live_ui/phase-18-focused-example-alignment-and-demo-retirement.md

@@ -0,0 +1,95 @@
+# Phase 18 - Focused Example Alignment and Demo Retirement
+
+Back to index: [README](./README.md)
+
+## Relevant Shared APIs / Interfaces
+- `LiveUi.Tooling`
+- `LiveUi.Examples`
+- `LiveUi.Demo`
+- `LiveUi.Info`
+- `LiveUi.Reference`
+- `LiveUi.Renderer`
+- `LiveUi.Runtime`
+- `LiveUi.Component`
+- `UnifiedExamples.*`
+- `mix live_ui.preview`
+- `mix live_ui.inspect`
+- `mix live_ui.export`
+- `mix live_ui.validate`
+
+## Relevant Assumptions / Defaults
+- The repository `examples/` inventory is now the authoritative widget-focused example catalog for the ecosystem.
+- `live_ui` should specialize that same inventory for direct native runtime review instead of maintaining a second demo/workbench or divergent example taxonomy.
+- Native `live_ui` widget usage remains the primary package-specialized example path, while canonical `UnifiedIUR` review, transport inspection, and continuity checks remain available as maintainer tooling on the same example ids.
+- This phase is expected to retire the current package-local demo/workbench and the small native/canonical/mixed package-owned example catalog once aligned focused examples replace them.
+
+[ ] 18 Phase 18 - Focused Example Alignment and Demo Retirement
+  Replace the current package-local demo and divergent example catalog with the same focused widget example inventory used by the repository suite, specialized for direct native `live_ui` widgets and runtime entrypoints while keeping canonical review and transport tooling attached to those same example ids.
+
+  [ ] 18.1 Section - Focused Example Inventory Alignment
+    Align the package example inventory one-for-one with the authoritative repository widget example catalog.
+
+    [ ] 18.1.1 Task - Define the aligned `live_ui` example identity and coverage model
+      Establish the package-owned example ids, naming, metadata, and coverage rules so every repository example has one matching `live_ui` specialization.
+
+      [ ] 18.1.1.1 Subtask - Create a one-for-one mapping between the root `examples/` inventory and the package-specialized `live_ui` example ids, preserving widget identity and reviewer intent.
+      [ ] 18.1.1.2 Subtask - Define package metadata for each aligned example, including native runtime entrypoint, canonical review obligations, transport coverage, and continuity expectations.
+      [ ] 18.1.1.3 Subtask - Add tests that fail when a repository example id is missing from the `live_ui` package-specialized inventory or when a retired package-only id remains exposed.
+
+    [ ] 18.1.2 Task - Implement the package-local structure for aligned focused examples
+      Replace the current divergent example surface with a structure that is clearly organized around the same widget-focused examples as the root suite.
+
+      [ ] 18.1.2.1 Subtask - Create or reorganize the package example modules so maintainers can locate each `live_ui` specialization by the same widget-focused identity used in the repository suite.
+      [ ] 18.1.2.2 Subtask - Ensure each aligned example uses direct native `live_ui` widgets and runtime entrypoints rather than re-authoring the example through `unified_ui`.
+      [ ] 18.1.2.3 Subtask - Add tests that prove the aligned examples remain package-local `live_ui` specializations rather than thin wrappers around the root example applications.
+
+  [ ] 18.2 Section - Tooling and Review Workflow Realignment
+    Move maintainer tooling from the old demo/catalog model onto the aligned focused example inventory.
+
+    [ ] 18.2.1 Task - Retarget preview, inspection, export, and validation workflows to aligned example ids
+      Make the package tooling operate on the same focused example identities that the repository suite exposes publicly.
+
+      [ ] 18.2.1.1 Subtask - Update `mix live_ui.preview`, `mix live_ui.inspect`, and `mix live_ui.export` so they resolve aligned focused example ids instead of the current native/canonical/mixed package catalog.
+      [ ] 18.2.1.2 Subtask - Keep canonical rendering, transport diagnostics, and continuity review available as inspection modes on the aligned example ids rather than as separate example families.
+      [ ] 18.2.1.3 Subtask - Add tests that prove tooling output stays deterministic when maintainers review native runtime behavior and canonical behavior for the same aligned example id.
+
+    [ ] 18.2.2 Task - Remove the package-local demo/workbench and divergent example taxonomy
+      Retire the surfaces that no longer match the package and tooling specs.
+
+      [ ] 18.2.2.1 Subtask - Remove `LiveUi.Demo` and its package-local workbench routing, catalog, and widget preview entrypoints once aligned focused examples replace them.
+      [ ] 18.2.2.2 Subtask - Remove or migrate the current native/canonical/mixed package-owned example catalog so no divergent package-only example names remain public.
+      [ ] 18.2.2.3 Subtask - Add tests that fail if demo-only commands, divergent review artifacts, or package-only example ids are accidentally reintroduced.
+
+  [ ] 18.3 Section - Documentation, Validation, and Release Policy Alignment
+    Make the aligned focused example model the official package story in docs, validation, and release-readiness workflows.
+
+    [ ] 18.3.1 Task - Update package documentation and maintainer guidance
+      Replace the old demo-and-catalog narrative with the new aligned focused example story.
+
+      [ ] 18.3.1.1 Subtask - Update `packages/live_ui/README.md` and the package guides to describe the aligned focused example inventory as the maintainer entry point.
+      [ ] 18.3.1.2 Subtask - Document how native runtime review, canonical review, transport inspection, and continuity checks attach to the same aligned example ids.
+      [ ] 18.3.1.3 Subtask - Add documentation tests that fail if package docs mention the retired demo/workbench or divergent example taxonomy.
+
+    [ ] 18.3.2 Task - Tighten validation and traceability around aligned examples
+      Make the new example contract enforceable and visible in release-readiness workflows.
+
+      [ ] 18.3.2.1 Subtask - Extend `mix live_ui.validate` so it verifies one-for-one coverage against the repository example inventory and fails when package examples drift or disappear.
+      [ ] 18.3.2.2 Subtask - Update the live_ui planning traceability manifest so the new package and tooling requirements point at this phase explicitly.
+      [ ] 18.3.2.3 Subtask - Add release-readiness checks that fail when tooling, docs, and validation disagree about the aligned example inventory or the removal of the package-local demo.
+
+  [ ] 18.4 Section - Phase 18 Integration Tests
+    Validate the aligned example inventory, tooling migration, and demo retirement end to end.
+
+    [ ] 18.4.1 Task - Focused example alignment integration scenarios
+      Verify the package now exposes the same focused example identities as the repository suite for `live_ui`-native review.
+
+      [ ] 18.4.1.1 Subtask - Verify every repository widget-focused example id has one matching `live_ui` package specialization.
+      [ ] 18.4.1.2 Subtask - Verify native runtime review and canonical inspection operate on the same aligned example ids without introducing package-only aliases.
+      [ ] 18.4.1.3 Subtask - Verify package examples remain direct native `live_ui` widget/runtime specializations instead of reusing the authored `unified_ui` example implementations.
+
+    [ ] 18.4.2 Task - Demo retirement and release-readiness integration scenarios
+      Verify the old demo/workbench surface is fully retired and the new example model is the only supported maintainer path.
+
+      [ ] 18.4.2.1 Subtask - Verify `LiveUi.Demo`, demo-only routes, and divergent example commands are gone or fail with explicit migration guidance.
+      [ ] 18.4.2.2 Subtask - Verify package validation and release-readiness gates fail when aligned example coverage drifts from the repository example inventory.
+      [ ] 18.4.2.3 Subtask - Verify package docs, tooling output, and traceability all describe the same focused example alignment story.

.spec/planning/live_ui/spec-traceability.json

@@ -375,6 +375,20 @@
       ],
       "ownership_note": "Phase 11: Native surface is a mountable LiveComponent-oriented widget library."
     },
+    {
+      "requirement_id": "live_ui.package.focused_example_specialization",
+      "scope": "direct",
+      "source_file": ".spec/specs/live_ui/package.spec.md",
+      "primary_plan_refs": [
+        "18.1.1"
+      ],
+      "supporting_plan_refs": [
+        "18.1.2",
+        "18.2.1",
+        "18.3.2"
+      ],
+      "ownership_note": "Phase 18: Package examples align one-for-one with the repository focused example inventory and specialize it for native live_ui review."
+    },
     {
       "requirement_id": "live_ui.structure.mix_library_layout",
       "scope": "direct",
@@ -851,28 +865,29 @@
       "scope": "direct",
       "source_file": ".spec/specs/live_ui/tooling.spec.md",
       "primary_plan_refs": [
-        "6.1.1"
+        "18.1.1"
       ],
       "supporting_plan_refs": [
-        "2.4.1",
-        "4.4.1",
-        "5.4.1"
+        "18.1.2",
+        "18.2.1",
+        "18.4.1"
       ],
-      "ownership_note": "Direct tooling obligation."
+      "ownership_note": "Phase 18: Maintained reference examples align one-for-one with the repository focused example inventory."
     },
     {
       "requirement_id": "live_ui.tooling.preview_and_inspection",
       "scope": "direct",
       "source_file": ".spec/specs/live_ui/tooling.spec.md",
       "primary_plan_refs": [
-        "6.2.1"
+        "18.2.1"
       ],
       "supporting_plan_refs": [
         "5.3.1",
         "5.3.2",
-        "6.3.2"
+        "6.3.2",
+        "18.2.2"
       ],
-      "ownership_note": "Direct tooling obligation."
+      "ownership_note": "Phase 18: Preview and inspection workflows attach native, canonical, and transport review to the aligned focused example ids."
     },
     {
       "requirement_id": "live_ui.tooling.validation_workflow",
@@ -884,7 +899,9 @@
       "supporting_plan_refs": [
         "4.3.1",
         "5.5.1",
-        "6.5.2"
+        "6.5.2",
+        "18.3.2",
+        "18.4.2"
       ],
       "ownership_note": "Direct tooling obligation."
     },
@@ -897,10 +914,26 @@
       ],
       "supporting_plan_refs": [
         "6.4.2",
-        "6.5.2"
+        "6.5.2",
+        "18.3.1",
+        "18.4.2"
       ],
       "ownership_note": "Direct tooling obligation."
     },
+    {
+      "requirement_id": "live_ui.tooling.no_package_local_demo_workbench",
+      "scope": "direct",
+      "source_file": ".spec/specs/live_ui/tooling.spec.md",
+      "primary_plan_refs": [
+        "18.2.2"
+      ],
+      "supporting_plan_refs": [
+        "18.3.1",
+        "18.3.2",
+        "18.4.2"
+      ],
+      "ownership_note": "Phase 18: Retire the package-local demo/workbench and divergent widget catalog in favor of aligned focused examples."
+    },
     {
       "requirement_id": "unified_iur.widgets.input_and_navigation",
       "scope": "upstream_constraint",

.spec/planning/live_ui/spec-traceability.md

@@ -58,6 +58,7 @@ tasks because they govern other runtime packages:
 | `live_ui.package.not_dsl_or_iur_owner` | `1.1.2` | `6.4.2` | Direct live_ui boundary obligation. |
 | `live_ui.package.traceable_to_root_specs` | `6.4.1` | `6.4.2`, `6.3.2` | Direct live_ui documentation and governance obligation. |
 | `live_ui.package.widget_component_library_surface` | `11.1` | `11.1.1` | Phase 11: Native surface is a mountable LiveComponent-oriented widget library. |
+| `live_ui.package.focused_example_specialization` | `18.1.1` | `18.1.2`, `18.2.1`, `18.3.2` | Phase 18: Package examples align one-for-one with the repository focused example inventory and specialize it for native live_ui review. |
 ### `structure.spec.md`
 | Requirement ID | Primary plan coverage | Supporting coverage | Ownership note |
 | --- | --- | --- | --- |
@@ -110,10 +111,11 @@ tasks because they govern other runtime packages:
 ### `tooling.spec.md`
 | Requirement ID | Primary plan coverage | Supporting coverage | Ownership note |
 | --- | --- | --- | --- |
-| `live_ui.tooling.reference_examples` | `6.1.1` | `2.4.1`, `4.4.1`, `5.4.1` | Direct tooling obligation. |
-| `live_ui.tooling.preview_and_inspection` | `6.2.1` | `5.3.1`, `5.3.2`, `6.3.2` | Direct tooling obligation. |
-| `live_ui.tooling.validation_workflow` | `6.3.1` | `4.3.1`, `5.5.1`, `6.5.2` | Direct tooling obligation. |
-| `live_ui.tooling.documentation_surface` | `6.4.1` | `6.4.2`, `6.5.2` | Direct tooling obligation. |
+| `live_ui.tooling.reference_examples` | `18.1.1` | `18.1.2`, `18.2.1`, `18.4.1` | Phase 18: Maintained reference examples align one-for-one with the repository focused example inventory. |
+| `live_ui.tooling.preview_and_inspection` | `18.2.1` | `5.3.1`, `5.3.2`, `6.3.2`, `18.2.2` | Phase 18: Preview and inspection workflows attach native, canonical, and transport review to the aligned focused example ids. |
+| `live_ui.tooling.validation_workflow` | `6.3.1` | `4.3.1`, `5.5.1`, `6.5.2`, `18.3.2`, `18.4.2` | Direct tooling obligation. |
+| `live_ui.tooling.documentation_surface` | `6.4.1` | `6.4.2`, `6.5.2`, `18.3.1`, `18.4.2` | Direct tooling obligation. |
+| `live_ui.tooling.no_package_local_demo_workbench` | `18.2.2` | `18.3.1`, `18.3.2`, `18.4.2` | Phase 18: Retire the package-local demo/workbench and divergent widget catalog in favor of aligned focused examples. |
 ## Upstream Canonical Input And Authoring Constraints
 These specs are referenced by the planning index because they define the
 canonical input surface and authored boundary that `live_ui` must consume or

.spec/specs/live_ui/package.spec.md

@@ -28,6 +28,7 @@ surface:
 decisions:
   - repo.ecosystem.contract_model
   - live_ui.runtime.widget_livecomponents
+  - live_ui.tooling.focused_example_alignment
 ```
 
 ## Requirements
@@ -62,6 +63,11 @@ decisions:
   statement: The `live_ui` package subjects shall link back to the repository-level architecture, runtime-library, and signal transport subjects so package design remains subordinate to the root ecosystem contract.
   priority: must
   stability: stable
+
+- id: live_ui.package.focused_example_specialization
+  statement: The package review and maintainer example surface shall specialize the repository widget-focused example suite for direct native `live_ui` usage, aligning package example identities with the repository example inventory rather than maintaining a divergent package-local demo or unrelated example catalog.
+  priority: must
+  stability: stable
 ```
 
 ## Scenarios
@@ -85,5 +91,6 @@ decisions:
     - live_ui.package.iur_renderer_entrypoint
     - live_ui.package.not_dsl_or_iur_owner
     - live_ui.package.traceable_to_root_specs
+    - live_ui.package.focused_example_specialization
     - live_ui.package.direct_use_and_iur_use
 ```