@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/winui-app/references/_sections.md

@@ -0,0 +1,96 @@
+# Reference Sections
+
+Use this index to choose the narrowest reference file that fits the current task.
+
+## 1. Foundations
+
+- `foundation-setup-and-project-selection.md`
+  - Priority: CRITICAL
+  - Use for first-project setup, packaged vs unpackaged decisions, and core WinUI prerequisites.
+  - Authority: Microsoft Learn WinUI and Windows App SDK setup docs.
+
+- `foundation-environment-audit-and-remediation.md`
+  - Priority: CRITICAL
+  - Use for machine readiness checks, missing prerequisites, and guided remediation.
+  - Authority: Microsoft Learn setup and system requirements docs, plus the bundled bootstrap workflow.
+
+- `foundation-winui-app-structure.md`
+  - Priority: HIGH
+  - Use for solution layout, shell composition, resources, bindings, and C#-first project structure.
+  - Authority: WinUI Gallery source plus Learn XAML guidance.
+
+- `foundation-template-first-recovery.md`
+  - Priority: CRITICAL
+  - Use for opaque `MSB3073`, `XamlCompiler.exe`, and startup failures that should be recovered by comparing against a fresh `dotnet new winui` scaffold instead of applying alternate baseline files.
+  - Authority: Learn packaged and unpackaged deployment guidance plus recurring template-first recovery patterns.
+
+- `build-run-and-launch-verification.md`
+  - Priority: CRITICAL
+  - Use for build/run workflows, actual launch verification, startup crashes, and packaged-vs-unpackaged local execution choices.
+  - Authority: Learn setup and deployment guidance plus recurring WinUI troubleshooting patterns.
+
+## 2. Shell, Navigation, and Windowing
+
+- `shell-navigation-and-windowing.md`
+  - Priority: HIGH
+  - Use for `NavigationView`, page shells, title bars, `AppWindow`, and multi-window design.
+  - Authority: Learn design guidance, WinUI Gallery samples, Windows App SDK Windowing samples.
+
+## 3. Controls, Layout, and Adaptive UI
+
+- `controls-layout-and-adaptive-ui.md`
+  - Priority: HIGH
+  - Use for control selection, command surfaces, responsive layout, and page composition.
+  - Authority: Learn design guidance and WinUI Gallery control pages.
+
+## 4. Styling, Theming, Materials, and Icons
+
+- `styling-theming-materials-and-icons.md`
+  - Priority: HIGH
+  - Use for Fluent styling, theme resources, Mica, Acrylic, typography, and iconography.
+  - Authority: Learn design/material docs, WinUI Gallery backdrop samples, Windows App SDK Mica samples.
+
+- `motion-animations-and-polish.md`
+  - Priority: MEDIUM
+  - Use for transitions, connected animation, subtle polish, and animation discipline.
+  - Authority: Learn motion guidance, WinUI Gallery transition samples, CommunityToolkit animations.
+
+## 5. Accessibility, Input, and Localization
+
+- `accessibility-input-and-localization.md`
+  - Priority: HIGH
+  - Use for keyboarding, Narrator, high contrast, automation properties, and localization concerns.
+  - Authority: Learn accessibility and globalization guidance, WinUI Gallery automation patterns.
+
+## 6. Performance and Diagnostics
+
+- `performance-diagnostics-and-responsiveness.md`
+  - Priority: HIGH
+  - Use for UI-thread responsiveness, large item collections, rendering cost, and diagnostic tooling.
+  - Authority: Learn WinUI performance docs and XAML frame analysis guidance.
+
+## 7. Windows App SDK Scenarios
+
+- `windows-app-sdk-lifecycle-notifications-and-deployment.md`
+  - Priority: HIGH
+  - Use for lifecycle, activation, notifications, packaged vs unpackaged deployment, and runtime initialization.
+  - Authority: Microsoft Learn Windows App SDK docs and WindowsAppSDK-Samples.
+
+## 8. CommunityToolkit Extensions
+
+- `community-toolkit-controls-and-helpers.md`
+  - Priority: MEDIUM
+  - Use when built-in WinUI controls are not enough and Toolkit packages might close the gap cleanly.
+  - Authority: CommunityToolkit/Windows packages and samples.
+
+## 9. Testing, Debugging, and Review
+
+- `testing-debugging-and-review-checklists.md`
+  - Priority: HIGH
+  - Use for final review passes, debugging workflows, and validation checklists.
+  - Authority: Learn tooling docs plus recurring WinUI review patterns.
+
+- `sample-source-map.md`
+  - Priority: MEDIUM
+  - Use when you need to know which canonical repo or doc to inspect first for a given task.
+  - Authority: Curated map across Learn, WinUI Gallery, WindowsAppSDK-Samples, and CommunityToolkit.

package/skills/winui-app/references/accessibility-input-and-localization.md

@@ -0,0 +1,51 @@
+---
+title: Accessibility, Input, and Localization
+priority: HIGH
+tags: accessibility, keyboard, narrator, automation, localization, high-contrast
+sources:
+  - https://learn.microsoft.com/windows/apps/design/accessibility/accessibility
+  - https://learn.microsoft.com/windows/apps/design/accessibility/keyboard-accessibility
+  - https://learn.microsoft.com/windows/apps/design/accessibility/high-contrast-themes
+  - https://learn.microsoft.com/windows/apps/design/globalizing/globalizing-portal
+  - https://github.com/microsoft/WinUI-Gallery
+---
+
+## What This Reference Is For
+
+Use this file for keyboard accessibility, Narrator support, automation properties, input parity, high contrast, and localization-ready UI.
+
+## Prefer
+
+- Accessible names, help text, and landmarks for meaningful UI elements.
+- Full keyboard reachability for the main workflow.
+- High-contrast-safe visuals.
+- Localizable strings and layouts that tolerate growth.
+- Equal support for mouse, touch, pen, and keyboard where the platform expects it.
+
+## Avoid
+
+- Icon-only interactions without accessible naming.
+- Focus traps, hidden tab stops, or keyboard-only dead ends.
+- Hard-coded strings in XAML or code-behind that block localization.
+- Text layouts that collapse when strings expand.
+
+## Guidance
+
+- Use automation properties intentionally.
+- Preserve visible focus and logical tab order.
+- Verify context menus, flyouts, and dialogs by keyboard as well as mouse.
+- Respect text scaling, contrast changes, and RTL where relevant.
+- Keep touch targets and spacing usable on both mouse and touch hardware.
+
+## WinUI Gallery Anchors
+
+- Accessibility-related control samples
+- Automation helper patterns in shell code
+- Standard WinUI controls that already expose useful accessibility behavior
+
+## Review Checklist
+
+- Can a keyboard-only user complete the task?
+- Does Narrator have enough information to describe the important UI?
+- Does the experience stay legible in high contrast?
+- Are strings and layout ready for localization and RTL growth?

package/skills/winui-app/references/build-run-and-launch-verification.md

@@ -0,0 +1,72 @@
+---
+title: Build, Run, and Launch Verification
+priority: CRITICAL
+tags: build, run, launch, verification, packaged, unpackaged, debugging
+sources:
+  - https://learn.microsoft.com/windows/apps/get-started/start-here
+  - https://learn.microsoft.com/windows/apps/windows-app-sdk/deploy-packaged-apps
+  - https://learn.microsoft.com/windows/apps/windows-app-sdk/deploy-unpackaged-apps
+---
+
+## What This Reference Is For
+
+Use this file when the task involves building, running, launch failures, startup crashes, or final verification that a WinUI app actually opens on the current machine.
+
+## Required Workflow
+
+1. Identify the real build target:
+   - solution or project file
+   - configuration
+   - platform
+   - packaged or unpackaged model
+2. Build after each meaningful code edit and again at task completion.
+3. Run the app after changes when feasible. Always do it when the user asked for it or when startup, navigation, resources, or packaging changed.
+4. Use the launch path that matches the deployment model:
+   - packaged local dev: normally Visual Studio deploy or another package-aware flow
+   - unpackaged local dev: normally the built executable the user will actually run
+5. Verify real launch with objective evidence such as:
+   - non-zero main window handle
+   - expected window title
+   - responsive process with visible shell
+   - no immediate startup exception or crash
+6. After completing app work, including a first scaffold or a later build-and-fix cycle, leave a successfully verified final app instance running so the user can see that it worked unless they explicitly asked you not to.
+7. If launch fails or verification is ambiguous, debug the failure before saying the app is ready.
+
+## Packaged vs Unpackaged Rules
+
+- Choose one model intentionally before wiring startup, persistence, and launch instructions.
+- Packaged apps can rely on package identity and package-backed storage.
+- Unpackaged apps must not assume package identity. Guard or replace APIs that require it.
+- APIs such as `Windows.Storage.ApplicationData.Current` can fail in unpackaged runs even when the build succeeds.
+- Do not mix packaged-only assumptions into an unpackaged startup path.
+
+## Build and Launch Guidance
+
+- Prefer explicit platform targets when WinUI output is sensitive to architecture defaults. If `AnyCPU` creates ambiguity, use `x64` for local verification.
+- For unpackaged verification, prefer launching the built `.exe` from `bin\Debug\...\win-x64\` or the project-specific output path.
+- After a successful final launch verification, do not immediately tear the app down just because verification succeeded; keep it open for the user unless it blocks the next required action.
+- If `dotnet run` throws bootstrapper, deployment, or COM activation errors, treat that as a signal that the chosen launch path or packaging setup is wrong for the current app.
+- Stop old app instances before rebuilding if they can lock output files.
+
+## Debugging Startup Failures
+
+- Separate environment problems from app-code startup crashes.
+- If the app exits before showing a window, inspect the startup path first:
+  - `App.xaml`
+  - merged resource dictionaries
+  - converters
+  - `MainWindow`
+  - services used during startup
+- For startup or manifest issues, compare the current app against a fresh `dotnet new winui` scaffold for the same packaging model before broader surgery.
+- For opaque `MSB3073` and `XamlCompiler.exe` failures, simplify back toward the template-generated startup and shared-resource shape before making further structural changes.
+- Restore complex startup pieces incrementally when the failure point is unclear. A minimal `App.xaml` plus minimal `MainWindow` is a valid isolation step.
+- If the diagnostics look stale or inconsistent with the current files, run a clean build once before deeper surgery.
+- Prefer restoring the last known-good template-based shared-resource state over moving styles inline as the long-term fix.
+- When using unpackaged startup, review persistence, notifications, storage, and activation code for hidden package-identity assumptions.
+
+## Exit Criteria
+
+- Build succeeds from the intended local workflow.
+- The app launches from the intended local workflow.
+- A real top-level window or equivalent expected UI is confirmed.
+- No unresolved startup exception remains.

package/skills/winui-app/references/community-toolkit-controls-and-helpers.md

@@ -0,0 +1,57 @@
+---
+title: CommunityToolkit Controls and Helpers
+priority: MEDIUM
+tags: communitytoolkit, controls, helpers, animations, settingscontrols
+sources:
+  - https://github.com/CommunityToolkit/Windows
+  - https://learn.microsoft.com/dotnet/communitytoolkit/windows/getting-started
+---
+
+## What This Reference Is For
+
+Use this file when deciding whether the Windows Community Toolkit should be added to a WinUI 3 app.
+
+## Prefer
+
+- Platform controls first.
+- Targeted Toolkit package additions for clear gaps such as richer settings surfaces, segmented controls, or focused animation helpers.
+- The smallest package set that solves the problem.
+
+## Avoid
+
+- Adding Toolkit packages because they look convenient without checking whether WinUI already covers the need.
+- Pulling in multiple Toolkit packages for a minor visual difference.
+- Hiding fundamental UX problems behind a new dependency.
+
+## Good Candidate Areas
+
+- `SettingsControls`
+  - useful for settings surfaces and cards
+- `Segmented`
+  - useful when segmented selection is clearer than a tab or radio cluster
+- `HeaderedControls`
+  - useful for labeled control groupings
+- `Animations`
+  - useful when built-in transitions are not enough
+- helpers and extensions
+  - useful when they reduce repetitive WinUI plumbing cleanly
+
+## Package Guidance
+
+- Prefer WinUI 3 compatible Toolkit packages.
+- Add only what the app will actually use.
+- Document why a Toolkit dependency was added and what built-in alternative was rejected.
+
+## Sample and Source Anchors
+
+- CommunityToolkit `components/SettingsControls`
+- CommunityToolkit `components/Segmented`
+- CommunityToolkit `components/HeaderedControls`
+- Toolkit animations and helper packages
+
+## Review Checklist
+
+- Does built-in WinUI already solve the problem?
+- Is the dependency narrowly scoped and justified?
+- Does the new control match the rest of the app’s design language?
+- Will the package meaningfully reduce custom code or improve UX?

package/skills/winui-app/references/controls-layout-and-adaptive-ui.md

@@ -0,0 +1,84 @@
+---
+title: Controls, Layout, and Adaptive UI
+priority: HIGH
+tags: controls, layout, adaptive-ui, responsive, forms, lists
+sources:
+  - https://learn.microsoft.com/windows/apps/design/layout/responsive-design
+  - https://learn.microsoft.com/windows/apps/design/basics/navigation-basics
+  - https://github.com/microsoft/WinUI-Gallery
+---
+
+## What This Reference Is For
+
+Use this file when choosing controls, composing pages, or making a WinUI layout adapt well to different window sizes and input modes.
+
+## Prefer
+
+- Built-in WinUI controls first.
+- Native command surfaces such as `CommandBar` when the UI is grouping actions, toggles, and lightweight tool controls.
+- Standard controls for common tasks: `TextBox`, `NumberBox`, `ComboBox`, `ListView`, `GridView`, `ContentDialog`, `InfoBar`, `TeachingTip`, `TabView`, `NavigationView`.
+- Explicit scroll ownership for collection layouts. If the page already scrolls vertically, prefer giving a media shelf its own horizontal `ScrollViewer` and a simple horizontal panel.
+- Responsive techniques such as reposition, resize, reflow, and show/hide.
+- Layouts that remain usable when the window becomes narrow.
+- A real phone-width plan when the app may be resized that far: fewer columns, reduced padding, simplified controls, and stacked content instead of compressed desktop rails.
+
+## Avoid
+
+- Replacing standard WinUI controls with custom controls just to change appearance.
+- Building custom toolbar rows out of generic layout panels when a stock `CommandBar` would cover the grouping cleanly.
+- Hard-coded sizes that only look correct at one window width.
+- Dense desktop-only layouts that break touch or keyboard workflows.
+- Adding extra controls for local filtering or sorting when live updates and a simpler layout would better match the workflow.
+- Nesting a scroll-owning `GridView` inside an outer page `ScrollViewer` without deciding which control owns scrolling; this often produces a single vertical column or awkward scroll conflicts instead of a horizontal media shelf.
+- Wrapping list sections or card groups in an extra `Border` when the section header, spacing, and child surfaces already establish grouping.
+
+## Control Selection Guidance
+
+- Forms and settings:
+  - Prefer native controls first; add Toolkit settings controls only if the experience clearly benefits.
+- Command surfaces:
+  - Prefer `CommandBar` for grouped document, formatting, view, and page-level actions before composing a custom bar from `Grid`, `StackPanel`, `Border`, and loose buttons.
+  - Prefer the `CommandBar` overflow model for secondary actions before splitting the command surface into multiple custom rows.
+  - Fall back to a custom command layout only when a verified `CommandBar` limitation, an explicit product design requirement, or unusual content composition makes the native surface a poor fit.
+- Large collections:
+  - Prefer controls with virtualization-friendly behavior.
+  - Use `GridView` when it owns the collection surface and its scrolling behavior is part of the intended experience.
+  - For poster rails or other horizontal shelves inside a vertically scrolling page, prefer a horizontal `ScrollViewer` containing an `ItemsControl` or `ItemsRepeater` with a horizontal panel instead of a nested `GridView`.
+  - Consider `ItemsRepeater` when the layout is custom and performance matters.
+- Search and filtering:
+  - Prefer a single search field with live updates for local or otherwise inexpensive filtering.
+  - Add explicit apply, refresh, or mode-selection controls only when the underlying operation is expensive, remote, asynchronous, or semantically different.
+- Dialogs and transient guidance:
+  - Use `ContentDialog` for modal decisions.
+  - Use `InfoBar` for persistent status.
+  - Use `TeachingTip` for contextual onboarding.
+
+## Adaptive Layout Guidance
+
+- Design with effective pixels, not fixed device assumptions.
+- Make the smallest supported layout fully usable.
+- Add density or multi-column views only when width allows.
+- Use visual states, adaptive triggers, or layout state changes intentionally.
+- Keep commands and primary content reachable after resize.
+- Verify collection orientation and scrolling behavior at runtime. A shelf that looks horizontal in XAML can still render as a vertical stack once nested scroll regions are involved.
+- When simplifying a dense section, remove redundant outer surfaces before adding more adaptive layout rules; fewer layers usually adapt more cleanly across breakpoints.
+- Define breakpoint intent explicitly. Typical questions: when does a shelf become a stacked list, when does a footer drop nonessential controls, and when does the page stop behaving like a desktop canvas and become a single-column phone layout?
+- Simplify as width shrinks. Prefer dropping secondary controls or moving them behind shell affordances over preserving every control at every breakpoint.
+- When a page contains desktop-oriented horizontal shelves, add a phone-width alternative that stacks items vertically instead of relying on clipped rails and horizontal scrolling everywhere.
+
+## WinUI Gallery Anchors
+
+- Control pages for built-in WinUI control usage
+- Gallery home and shell pages for adaptive layout ideas
+- Sample pages for title bar and system backdrop interactions with content layout
+
+## Review Checklist
+
+- Did you choose the simplest built-in control that fits?
+- Are search and filter controls no more complex than the data flow requires?
+- Does the page remain usable when narrow?
+- Can keyboard, mouse, and touch all reach the same core actions?
+- Are spacing and hierarchy consistent across breakpoints?
+- If the page mixes page scrolling with collection scrolling, is it obvious which control owns vertical scrolling and which one, if any, owns horizontal shelf scrolling?
+- Are section containers doing real layout or surface work, or are some outer borders now redundant?
+- At phone width, does the page read as a coherent single-column flow instead of a squeezed desktop layout?

package/skills/winui-app/references/foundation-environment-audit-and-remediation.md

@@ -0,0 +1,82 @@
+---
+title: Environment Audit and Remediation
+priority: CRITICAL
+tags: setup, audit, install, dotnet, visual-studio, windows-sdk, developer-mode
+sources:
+  - https://learn.microsoft.com/windows/apps/get-started/start-here
+  - https://learn.microsoft.com/windows/apps/windows-app-sdk/system-requirements
+  - https://learn.microsoft.com/windows/apps/get-started/developer-mode-features-and-debugging
+  - https://learn.microsoft.com/dotnet/core/install/windows
+---
+
+## What This Reference Is For
+
+Use this file for machine-readiness checks, build failures caused by missing tools, and any request to install WinUI prerequisites.
+
+## Required Workflow
+
+1. Use the setup-and-scaffold flow in [../SKILL.md](../SKILL.md) for environment readiness, remediation, and initial verification.
+2. If the user asked only for an audit and not for setup, explain that the bundled bootstrap may change the machine and get confirmation before running it.
+3. If the user declines machine changes, run a manual non-mutating audit instead and summarize the result under four headings:
+   - present
+   - missing
+   - uncertain
+   - recommended optional tools
+4. Manual non-mutating audit coverage should focus on:
+   - OS version and build floor
+   - Developer Mode state when relevant to the task
+   - `dotnet --list-sdks`
+   - `dotnet new list winui`
+   - Visual Studio presence and edition
+   - Windows SDK presence
+   - MSBuild availability for XAML compilation
+5. If prerequisites are still missing after the bundled setup flow, stop and report the blocker clearly instead of inventing alternate install recipes.
+
+## Required vs Optional
+
+Required for normal C# WinUI 3 development:
+
+- Supported Windows build
+- Visual Studio with WinUI C# support
+- Windows SDK 10.0.19041.0 or later
+- MSBuild available for XAML compilation
+- .NET SDK 6 or later
+
+Usually optional, but often recommended:
+
+- Developer Mode for local deploy and debug
+- WinGet for one-command remediation
+- Visual Studio debugging features such as Hot Reload and Live Visual Tree
+
+## Prefer
+
+- The setup-and-scaffold flow in `SKILL.md` over ad hoc manual checks or duplicated setup instructions in this reference.
+- A short manual audit only when the user wants a non-mutating readiness check.
+
+## Avoid
+
+- Rewriting or paraphrasing the bundled setup workflow here when `SKILL.md` already covers the user's goal.
+- Marking workload detection as present when the bootstrap or manual audit leaves uncertainty.
+- Branching into custom per-component install steps unless the user explicitly asks for them.
+- Treating Developer Mode as a hard requirement for every task.
+
+## Remediation Strategy
+
+- Missing any required WinUI prerequisite:
+  - Use the setup-and-scaffold flow in `SKILL.md` after confirmation when the request is audit-only.
+- The bundled setup flow reports a partial failure but the toolchain appears usable:
+  - Note the partial failure and continue when the user's task can proceed.
+- The bundled setup flow fails and prerequisites still appear to be missing:
+  - Use the manual audit checks above for detail if needed, then stop and report the blocker clearly.
+- Windows build unsupported:
+  - Upgrade Windows first. The WinUI bootstrap command does not replace the OS requirement.
+- Developer Mode disabled:
+  - Explain whether the current task needs it.
+  - If it does, prefer the bundled setup flow or let the user enable it manually.
+
+## Review Checklist
+
+- Was the setup-and-scaffold flow in `SKILL.md` used before advice was given?
+- Are missing items clearly separated from uncertain signals?
+- Is the remediation plan the minimum needed for the user's goal?
+- Was post-install verification handled by the bundled setup flow or by a clearly justified fallback?

package/skills/winui-app/references/foundation-setup-and-project-selection.md

@@ -0,0 +1,67 @@
+---
+title: Setup and Project Selection
+priority: CRITICAL
+tags: setup, prerequisites, packaged, unpackaged, visual-studio, dotnet
+sources:
+  - https://learn.microsoft.com/windows/apps/get-started/start-here
+  - https://learn.microsoft.com/windows/apps/winui/winui3/
+  - https://learn.microsoft.com/windows/apps/windows-app-sdk/
+  - https://learn.microsoft.com/windows/apps/windows-app-sdk/system-requirements
+---
+
+## What This Reference Is For
+
+Use this file when the user is starting from scratch, choosing a project template, or asking what a WinUI machine needs before code work begins.
+
+## Prefer
+
+- The setup-and-scaffold flow in [../SKILL.md](../SKILL.md) for prerequisite setup, template verification, and the first scaffold.
+- A C# WinUI 3 desktop app on the Windows App SDK unless the user has a clear reason to prefer C++ or an existing non-WinUI stack.
+- Official project templates and default packaging choices first.
+- The current supported LTS .NET SDK for new C# work instead of only meeting the bare minimum.
+- A packaged app by default for the smoothest first-project, deployment, and Store-compatible path.
+- An unpackaged app when the user explicitly needs repeatable CLI build-and-run verification or direct executable launches as the normal local workflow.
+
+## Avoid
+
+- Starting project setup before the setup-and-scaffold flow in this skill has finished.
+- Starting with unpackaged deployment unless the user needs repeatable CLI launch, an installer, existing desktop app integration, or a deliberate runtime strategy.
+- Giving machine-readiness advice without verification.
+- Treating old Windows builds, missing SDKs, or partial Visual Studio installs as "probably fine."
+- Deferring the packaging choice until after startup, storage, and launch code are already written.
+
+## Setup Baseline
+
+- Use the setup-and-scaffold flow in [../SKILL.md](../SKILL.md) for prerequisite setup, template verification, and the first scaffold.
+- Treat [../config.yaml](../config.yaml) as the bundled WinGet bootstrap source for setup and remediation.
+- Return to this reference only after that workflow completes or when the task moves beyond initial project creation.
+- Windows 10 version 1809 (build 17763) or later is the floor.
+- Windows SDK 10.0.19041.0 or later is the practical baseline.
+- Visual Studio with the WinUI application development workload is the supported primary IDE path.
+- For C# apps, a supported .NET SDK must be installed.
+- Developer Mode matters for common local deploy and debug flows.
+
+## Project Selection Guidance
+
+- Choose packaged when the user wants the default WinUI 3 path, easy local F5 workflows, or Store-friendly deployment. Keep the scaffold at its default unless the user explicitly asks for unpackaged behavior.
+- Choose packaged when the app needs package identity or package-backed APIs during normal operation.
+- Choose unpackaged when the user expects direct `.exe` launches, agent-driven local verification after each change, or integration with an existing installer or external location. Request that option through the setup flow instead of converting the initial project afterward.
+- For either packaging model, scaffold first through the setup flow in `SKILL.md` and continue from the generated project instead of copying in prebuilt baseline files.
+- If startup or shared resources later become suspect, create a fresh comparison app with the same packaging model and diff against that `dotnet new winui` output before broader restructuring.
+- Once the model is chosen, keep startup and service code consistent with that model.
+- Choose the standard blank app template first, then layer in navigation, title bar, or windowing patterns as the app matures.
+
+## Sample and Source Anchors
+
+- Learn `start-here.md` for the current official setup path.
+- Learn `winui/winui3/index.md` for the framework position and platform benefits.
+- Learn `windows-app-sdk/index.md` for the Windows App SDK feature surface.
+- Learn `system-requirements.md` for tool and OS baselines.
+
+## Review Checklist
+
+- Is the machine baseline actually verified through the setup-and-scaffold flow in `SKILL.md`?
+- Is the chosen packaging model intentional?
+- Does the launch workflow match the chosen packaging model?
+- Is the app still rooted in the standard WinUI template unless there is a real reason not to?
+- Is the recommendation aligned with a C#-first WinUI 3 workflow?

package/skills/winui-app/references/foundation-template-first-recovery.md

@@ -0,0 +1,62 @@
+---
+title: Template-First Recovery for Startup and XAML Failures
+priority: CRITICAL
+tags: template, recovery, xaml-compiler, msb3073, startup
+sources:
+  - https://learn.microsoft.com/windows/apps/get-started/start-here
+  - https://learn.microsoft.com/windows/apps/windows-app-sdk/deploy-packaged-apps
+  - https://learn.microsoft.com/windows/apps/windows-app-sdk/deploy-unpackaged-apps
+  - https://github.com/microsoft/WinUI-Gallery
+---
+
+## What This Reference Is For
+
+Use this file when a new app should stay close to the `dotnet new winui` scaffold, or when opaque `MSB3073`, `XamlCompiler.exe`, and startup failures make it unclear whether the problem is in app code, shared resources, or the surrounding project structure.
+
+## Prefer
+
+- Scaffold with the standard `dotnet new winui` template first and keep the generated project file, manifests, assets, and startup shape unless the task explicitly requires broader changes.
+- Match any comparison scaffold to the app's actual packaging model.
+- Keep `App.xaml` minimal while isolating startup problems.
+- Prefer explicit `new Window()` and avoid `Window.Current` when customizing WinUI 3 startup.
+- Reintroduce shell, resources, bindings, and services incrementally after a clean build and launch.
+
+## Avoid
+
+- Swapping in alternate baseline files or helper scripts as the first recovery move.
+- Replacing the template-generated `.csproj` or manifests during initial isolation.
+- Flattening all styles into page-local markup as the permanent fix for opaque compiler failures.
+- Treating `MSB3073` as proof that the most recently edited XAML line is the only fault.
+
+## Template-First Recovery Loop
+
+1. Confirm the intended packaging model and launch path.
+2. If the current startup shape is unclear, scaffold a temporary comparison app with the same packaging choice. Example:
+   - `dotnet new winui -n RecoveryReference -o RecoveryReference --use-slnx false --no-solution-file false`
+   - Add `--unpackaged true` when the target app is unpackaged.
+3. Diff only the startup and shared-resource areas against that comparison scaffold:
+   - `App.xaml`
+   - `App.xaml.cs`
+   - `MainWindow.xaml` / `MainWindow.xaml.cs` or the app's actual shell entry point
+   - merged resource dictionaries
+   - startup-related project properties
+4. Revert the suspect area toward the template-generated shape until the app builds cleanly again.
+5. Build explicitly for a concrete architecture. Example:
+   - `dotnet build MyApp.sln -c Debug -p:Platform=x64`
+6. Launch using the correct packaged or unpackaged path and confirm objective startup signals.
+7. Reapply custom changes in small slices, building and running after each meaningful edit.
+
+## Common Recovery Checks
+
+- Confirm `Window.Current` is not used in WinUI 3 startup code.
+- Confirm `x:Class`, namespaces, and code-behind names still match.
+- Confirm merged resource dictionaries load cleanly before adding more layers.
+- Confirm project content items still match any local data or asset files the app expects at runtime.
+- Run one clean build if diagnostics appear stale.
+
+## Exit Criteria
+
+- The current app is still rooted in the generated `dotnet new winui` scaffold rather than an alternate baseline shell.
+- Build succeeds from the intended local workflow.
+- The app launches from the intended local workflow.
+- A real top-level window or equivalent expected UI is confirmed.

package/skills/winui-app/references/foundation-winui-app-structure.md

@@ -0,0 +1,62 @@
+---
+title: WinUI App Structure
+priority: HIGH
+tags: app-structure, xaml, resources, pages, bindings, csharp
+sources:
+  - https://github.com/microsoft/WinUI-Gallery
+  - https://learn.microsoft.com/windows/apps/winui/
+---
+
+## What This Reference Is For
+
+Use this file when structuring a WinUI 3 app, reviewing project layout, or deciding where shell, pages, controls, resources, and view models should live.
+
+## Prefer
+
+- A clear C#-first folder split such as `Pages`, `Controls`, `ViewModels`, `Services`, `Styles`, and `Assets`.
+- `App.xaml` and shared resource dictionaries for app-wide theme resources and styles.
+- A single main shell window that owns navigation and common chrome.
+- Native command surfaces such as `CommandBar` for grouped window or page actions before inventing a custom toolbar composition.
+- Strongly typed `x:Bind` where it improves compile-time safety and performance.
+
+## Avoid
+
+- Putting shell logic, page logic, and resource definitions into one large window file.
+- Scattering theme brushes and styles across many page-local dictionaries.
+- Introducing MVVM ceremony that the project will not actually maintain.
+
+## Recommended Shape
+
+- `App.xaml` / `App.xaml.cs`
+  - global resources, startup, window creation, app-level exceptions
+- `MainWindow.xaml` / `MainWindow.xaml.cs`
+  - shell, title bar, top-level navigation host
+- `Pages/`
+  - page views and page-specific logic
+- `Controls/`
+  - reusable WinUI user controls
+- `ViewModels/`
+  - state and commands when the app benefits from separation
+- `Styles/`
+  - resource dictionaries, theme tokens, shared control styles
+- `Helpers/` or `Services/`
+  - windowing, navigation, persistence, OS integration helpers
+
+## Binding Guidance
+
+- Prefer `x:Bind` for page-local properties, event handlers, and strongly typed view model access.
+- Use `Binding` where the data context is dynamic or a template must stay flexible.
+- Avoid binding patterns that depend on unclear page lifetime or implicit data contexts.
+
+## WinUI Gallery Anchors
+
+- `App.xaml.cs` shows app-level startup and integration points.
+- `MainWindow.xaml` shows shell composition, title bar usage, and search integration.
+- `Pages/` and `Samples/` show how Microsoft organizes pages, helpers, and styles in a real WinUI companion app.
+
+## Review Checklist
+
+- Are app resources centralized?
+- Is shell logic separated from content pages?
+- Are bindings explicit and maintainable?
+- Is the structure consistent with the scale of the app?