@fprad0/skill-master-mcp 0.0.11 → 1.0.0

package/docs/skill-candidates/v0.0.10/winui-app/references/foundation-template-first-recovery.md

@@ -1,62 +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.
+---
+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/docs/skill-candidates/v0.0.10/winui-app/references/foundation-winui-app-structure.md

@@ -1,62 +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?
+---
+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?

package/docs/skill-candidates/v0.0.10/winui-app/references/motion-animations-and-polish.md

@@ -1,45 +1,45 @@
----
-title: Motion, Animations, and Polish
-priority: MEDIUM
-tags: motion, animations, transitions, connected-animation, polish
-sources:
-  - https://learn.microsoft.com/windows/apps/design/motion/
-  - https://github.com/microsoft/WinUI-Gallery
-  - https://github.com/CommunityToolkit/Windows
----
-
-## What This Reference Is For
-
-Use this file when adding polish to a WinUI app through motion, transitions, and subtle animated state changes.
-
-## Prefer
-
-- Motion that clarifies hierarchy, continuity, and state changes.
-- Theme transitions, connected animations, and built-in platform behaviors before custom animation systems.
-- Short, purposeful animations that support the task.
-
-## Avoid
-
-- Decorative animation that delays interaction.
-- Multiple overlapping animations for the same state change.
-- Animation that hides focus, selection, or accessibility state.
-
-## Guidance
-
-- Use transitions to explain where content came from and where it went.
-- Keep entrance and exit motion subtle.
-- Use connected animation when there is a real source-to-destination relationship.
-- Reach for CommunityToolkit animation helpers only when built-in transitions are not enough.
-
-## Sample and Source Anchors
-
-- WinUI Gallery animation, transition, and implicit animation pages
-- Learn motion guidance
-- CommunityToolkit animations package and samples
-
-## Review Checklist
-
-- Does the motion improve clarity?
-- Is the app still responsive while the animation runs?
-- Can the transition be simplified to a built-in WinUI behavior?
-- Does the motion preserve accessibility and input clarity?
+---
+title: Motion, Animations, and Polish
+priority: MEDIUM
+tags: motion, animations, transitions, connected-animation, polish
+sources:
+  - https://learn.microsoft.com/windows/apps/design/motion/
+  - https://github.com/microsoft/WinUI-Gallery
+  - https://github.com/CommunityToolkit/Windows
+---
+
+## What This Reference Is For
+
+Use this file when adding polish to a WinUI app through motion, transitions, and subtle animated state changes.
+
+## Prefer
+
+- Motion that clarifies hierarchy, continuity, and state changes.
+- Theme transitions, connected animations, and built-in platform behaviors before custom animation systems.
+- Short, purposeful animations that support the task.
+
+## Avoid
+
+- Decorative animation that delays interaction.
+- Multiple overlapping animations for the same state change.
+- Animation that hides focus, selection, or accessibility state.
+
+## Guidance
+
+- Use transitions to explain where content came from and where it went.
+- Keep entrance and exit motion subtle.
+- Use connected animation when there is a real source-to-destination relationship.
+- Reach for CommunityToolkit animation helpers only when built-in transitions are not enough.
+
+## Sample and Source Anchors
+
+- WinUI Gallery animation, transition, and implicit animation pages
+- Learn motion guidance
+- CommunityToolkit animations package and samples
+
+## Review Checklist
+
+- Does the motion improve clarity?
+- Is the app still responsive while the animation runs?
+- Can the transition be simplified to a built-in WinUI behavior?
+- Does the motion preserve accessibility and input clarity?

package/docs/skill-candidates/v0.0.10/winui-app/references/performance-diagnostics-and-responsiveness.md

@@ -1,46 +1,46 @@
----
-title: Performance, Diagnostics, and Responsiveness
-priority: HIGH
-tags: performance, responsiveness, ui-thread, wpr, wpa, diagnostics
-sources:
-  - https://learn.microsoft.com/windows/apps/performance/winui-perf
-  - https://github.com/microsoft/WinUI-Gallery
----
-
-## What This Reference Is For
-
-Use this file when the user reports sluggish WinUI behavior, dropped frames, long startup, or laggy scrolling and layout.
-
-## Prefer
-
-- Keeping the UI thread free for layout, rendering, and input.
-- Simpler visual trees and lighter templates.
-- Virtualization-friendly controls and item layouts.
-- Measurement before optimization when the issue is not obvious.
-
-## Avoid
-
-- Doing expensive I/O or CPU work directly on the UI thread.
-- Deeply nested XAML trees without a concrete benefit.
-- Re-templating controls in ways that dramatically increase layout work.
-- Guessing at performance causes without profiling.
-
-## Guidance
-
-- Favor platform controls and layouts that virtualize well for long lists.
-- Defer or background heavy work when it does not need to block interaction.
-- Reduce unnecessary layout invalidation and repeated measure/arrange churn.
-- Use WPR and WPA with the XAML Frame Analysis plugin for frame-level investigations.
-- Treat slow-frame findings as a clue to UI-thread overload, not as a reason to micro-optimize blindly.
-
-## Sample and Source Anchors
-
-- Learn `winui-perf.md`
-- WinUI Gallery pages that demonstrate adaptive UI and complex controls without excessive custom infrastructure
-
-## Review Checklist
-
-- Is heavy work running off the UI thread where possible?
-- Are large collections using an appropriate items control?
-- Is the visual tree no more complex than it needs to be?
-- Has profiling been used before claiming a fix?
+---
+title: Performance, Diagnostics, and Responsiveness
+priority: HIGH
+tags: performance, responsiveness, ui-thread, wpr, wpa, diagnostics
+sources:
+  - https://learn.microsoft.com/windows/apps/performance/winui-perf
+  - https://github.com/microsoft/WinUI-Gallery
+---
+
+## What This Reference Is For
+
+Use this file when the user reports sluggish WinUI behavior, dropped frames, long startup, or laggy scrolling and layout.
+
+## Prefer
+
+- Keeping the UI thread free for layout, rendering, and input.
+- Simpler visual trees and lighter templates.
+- Virtualization-friendly controls and item layouts.
+- Measurement before optimization when the issue is not obvious.
+
+## Avoid
+
+- Doing expensive I/O or CPU work directly on the UI thread.
+- Deeply nested XAML trees without a concrete benefit.
+- Re-templating controls in ways that dramatically increase layout work.
+- Guessing at performance causes without profiling.
+
+## Guidance
+
+- Favor platform controls and layouts that virtualize well for long lists.
+- Defer or background heavy work when it does not need to block interaction.
+- Reduce unnecessary layout invalidation and repeated measure/arrange churn.
+- Use WPR and WPA with the XAML Frame Analysis plugin for frame-level investigations.
+- Treat slow-frame findings as a clue to UI-thread overload, not as a reason to micro-optimize blindly.
+
+## Sample and Source Anchors
+
+- Learn `winui-perf.md`
+- WinUI Gallery pages that demonstrate adaptive UI and complex controls without excessive custom infrastructure
+
+## Review Checklist
+
+- Is heavy work running off the UI thread where possible?
+- Are large collections using an appropriate items control?
+- Is the visual tree no more complex than it needs to be?
+- Has profiling been used before claiming a fix?

package/docs/skill-candidates/v0.0.10/winui-app/references/sample-source-map.md

@@ -1,37 +1,37 @@
----
-title: Sample and Source Map
-priority: MEDIUM
-tags: sources, mapping, lookup, gallery, docs, toolkit
-sources:
-  - https://learn.microsoft.com/windows/apps/get-started/samples
-  - https://github.com/microsoft/WinUI-Gallery
-  - https://github.com/microsoft/WindowsAppSDK-Samples
-  - https://github.com/CommunityToolkit/Windows
----
-
-## What This Reference Is For
-
-Use this file when you know the task but need to identify the best canonical source to inspect first.
-
-| Task | First source | Backup source |
-| --- | --- | --- |
-| Check whether a PC can build WinUI apps | `../SKILL.md` | `foundation-environment-audit-and-remediation.md` |
-| Install missing prerequisites | `../SKILL.md` | `foundation-environment-audit-and-remediation.md` |
-| Start a new packaged or unpackaged app | `../SKILL.md` | `foundation-setup-and-project-selection.md` |
-| Choose packaged vs unpackaged | Learn Windows App SDK deployment docs | WindowsAppSDK-Samples `Samples/Unpackaged` |
-| Build a shell with navigation | WinUI Gallery navigation pages | Learn navigation basics |
-| Design a custom title bar | Learn title bar guidance | WinUI Gallery title bar samples |
-| Add Mica or system backdrops | Learn Mica guidance | WindowsAppSDK-Samples `Samples/Mica` |
-| Design a settings page | WinUI Gallery control pages | CommunityToolkit `SettingsControls` |
-| Pick a control for a list or collection | WinUI Gallery control pages | Learn responsive/layout guidance |
-| Improve accessibility | Learn accessibility docs | WinUI Gallery standard control behavior |
-| Diagnose responsiveness | Learn `winui-perf.md` | WPR/WPA guidance in `testing-debugging-and-review-checklists.md` |
-| Add notifications or activation flows | WindowsAppSDK-Samples | Learn Windows App SDK lifecycle docs |
-| Decide whether to add CommunityToolkit | `community-toolkit-controls-and-helpers.md` | Toolkit component directories |
-
-## Source Preferences
-
-- Learn first for requirements and behavioral guidance.
-- WinUI Gallery first for concrete control usage and shell composition.
-- WindowsAppSDK-Samples first for scenario APIs and platform integration.
-- CommunityToolkit only when the task clearly requires Toolkit-specific functionality.
+---
+title: Sample and Source Map
+priority: MEDIUM
+tags: sources, mapping, lookup, gallery, docs, toolkit
+sources:
+  - https://learn.microsoft.com/windows/apps/get-started/samples
+  - https://github.com/microsoft/WinUI-Gallery
+  - https://github.com/microsoft/WindowsAppSDK-Samples
+  - https://github.com/CommunityToolkit/Windows
+---
+
+## What This Reference Is For
+
+Use this file when you know the task but need to identify the best canonical source to inspect first.
+
+| Task | First source | Backup source |
+| --- | --- | --- |
+| Check whether a PC can build WinUI apps | `../SKILL.md` | `foundation-environment-audit-and-remediation.md` |
+| Install missing prerequisites | `../SKILL.md` | `foundation-environment-audit-and-remediation.md` |
+| Start a new packaged or unpackaged app | `../SKILL.md` | `foundation-setup-and-project-selection.md` |
+| Choose packaged vs unpackaged | Learn Windows App SDK deployment docs | WindowsAppSDK-Samples `Samples/Unpackaged` |
+| Build a shell with navigation | WinUI Gallery navigation pages | Learn navigation basics |
+| Design a custom title bar | Learn title bar guidance | WinUI Gallery title bar samples |
+| Add Mica or system backdrops | Learn Mica guidance | WindowsAppSDK-Samples `Samples/Mica` |
+| Design a settings page | WinUI Gallery control pages | CommunityToolkit `SettingsControls` |
+| Pick a control for a list or collection | WinUI Gallery control pages | Learn responsive/layout guidance |
+| Improve accessibility | Learn accessibility docs | WinUI Gallery standard control behavior |
+| Diagnose responsiveness | Learn `winui-perf.md` | WPR/WPA guidance in `testing-debugging-and-review-checklists.md` |
+| Add notifications or activation flows | WindowsAppSDK-Samples | Learn Windows App SDK lifecycle docs |
+| Decide whether to add CommunityToolkit | `community-toolkit-controls-and-helpers.md` | Toolkit component directories |
+
+## Source Preferences
+
+- Learn first for requirements and behavioral guidance.
+- WinUI Gallery first for concrete control usage and shell composition.
+- WindowsAppSDK-Samples first for scenario APIs and platform integration.
+- CommunityToolkit only when the task clearly requires Toolkit-specific functionality.

package/docs/skill-candidates/v0.0.10/winui-app/references/shell-navigation-and-windowing.md

@@ -1,67 +1,67 @@
----
-title: Shell, Navigation, and Windowing
-priority: HIGH
-tags: navigationview, titlebar, appwindow, multi-window, shell
-sources:
-  - https://learn.microsoft.com/windows/apps/design/basics/navigation-basics
-  - https://learn.microsoft.com/windows/apps/design/basics/titlebar-design
-  - https://github.com/microsoft/WinUI-Gallery
-  - https://github.com/microsoft/WindowsAppSDK-Samples/tree/main/Samples/Windowing
----
-
-## What This Reference Is For
-
-Use this file for top-level app shells, page navigation models, custom title bars, and multi-window decisions.
-
-## Prefer
-
-- `NavigationView` for standard desktop shells with clear top-level destinations.
-- A small, stable set of primary destinations.
-- Built-in back navigation behavior that matches user expectations.
-- `AppWindow` and Windows App SDK windowing APIs for modern window management.
-
-## Avoid
-
-- Overloading the nav surface with every command and secondary action.
-- Turning the `NavigationView` pane into a branded hero area when the user did not ask for custom shell treatment.
-- Custom title bar layouts that break drag regions or caption button clarity.
-- Multi-window designs unless the workflow clearly benefits from them.
-
-## Navigation Guidance
-
-- Use left navigation when the app has several stable, high-level destinations.
-- Use top navigation when there are few peer destinations and width is available.
-- Use a single-page or document-first layout when navigation is shallow and the user mostly stays in one workflow.
-- Keep naming and iconography stable across pages.
-- Treat `NavigationView` as functional shell chrome first. Keep pane headers, footer content, and decorative branding minimal unless the product requirements clearly call for them.
-- Prefer the platform's normal pane structure before adding custom logo blocks, taglines, or non-navigation content that changes the shell's native feel.
-- For narrow or phone-like widths, stop reserving permanent pane width for desktop navigation. Prefer a minimal or overlay navigation mode, show the pane toggle when needed, close the pane by default after navigation, and give content the width back.
-- When a shell enters a phone-width mode, reduce content padding and decorative chrome so the page reads as one primary column instead of a desktop shell with a squeezed content strip.
-
-## Title Bar Guidance
-
-- Treat the title bar as functional chrome first, branding surface second.
-- Keep empty non-interactive areas draggable.
-- Blend title bar visuals with the rest of the app when possible.
-- Respect light, dark, and high-contrast states.
-
-## Windowing Guidance
-
-- Start with one main window.
-- Add secondary windows only for workflows such as document detachment, inspection panes, or tool windows.
-- Use Windows App SDK samples for resizing, placement, and window-specific behaviors instead of inventing custom platform abstractions.
-
-## Sample and Source Anchors
-
-- WinUI Gallery `NavigationView`, `TitleBar`, `AppWindow`, and windowing sample pages
-- WindowsAppSDK-Samples `Samples/Windowing`
-- Learn navigation and title bar guidance
-
-## Review Checklist
-
-- Is the navigation model simple and intentional?
-- Does the shell still look and behave like a normal WinUI `NavigationView` unless there is an explicit reason to diverge?
-- Does the title bar still behave like a Windows title bar?
-- Are back, search, and pane behaviors consistent?
-- Is multi-window use justified by the workflow?
-- Does the shell intentionally switch behavior at narrow or phone widths instead of leaving a full desktop pane open?
+---
+title: Shell, Navigation, and Windowing
+priority: HIGH
+tags: navigationview, titlebar, appwindow, multi-window, shell
+sources:
+  - https://learn.microsoft.com/windows/apps/design/basics/navigation-basics
+  - https://learn.microsoft.com/windows/apps/design/basics/titlebar-design
+  - https://github.com/microsoft/WinUI-Gallery
+  - https://github.com/microsoft/WindowsAppSDK-Samples/tree/main/Samples/Windowing
+---
+
+## What This Reference Is For
+
+Use this file for top-level app shells, page navigation models, custom title bars, and multi-window decisions.
+
+## Prefer
+
+- `NavigationView` for standard desktop shells with clear top-level destinations.
+- A small, stable set of primary destinations.
+- Built-in back navigation behavior that matches user expectations.
+- `AppWindow` and Windows App SDK windowing APIs for modern window management.
+
+## Avoid
+
+- Overloading the nav surface with every command and secondary action.
+- Turning the `NavigationView` pane into a branded hero area when the user did not ask for custom shell treatment.
+- Custom title bar layouts that break drag regions or caption button clarity.
+- Multi-window designs unless the workflow clearly benefits from them.
+
+## Navigation Guidance
+
+- Use left navigation when the app has several stable, high-level destinations.
+- Use top navigation when there are few peer destinations and width is available.
+- Use a single-page or document-first layout when navigation is shallow and the user mostly stays in one workflow.
+- Keep naming and iconography stable across pages.
+- Treat `NavigationView` as functional shell chrome first. Keep pane headers, footer content, and decorative branding minimal unless the product requirements clearly call for them.
+- Prefer the platform's normal pane structure before adding custom logo blocks, taglines, or non-navigation content that changes the shell's native feel.
+- For narrow or phone-like widths, stop reserving permanent pane width for desktop navigation. Prefer a minimal or overlay navigation mode, show the pane toggle when needed, close the pane by default after navigation, and give content the width back.
+- When a shell enters a phone-width mode, reduce content padding and decorative chrome so the page reads as one primary column instead of a desktop shell with a squeezed content strip.
+
+## Title Bar Guidance
+
+- Treat the title bar as functional chrome first, branding surface second.
+- Keep empty non-interactive areas draggable.
+- Blend title bar visuals with the rest of the app when possible.
+- Respect light, dark, and high-contrast states.
+
+## Windowing Guidance
+
+- Start with one main window.
+- Add secondary windows only for workflows such as document detachment, inspection panes, or tool windows.
+- Use Windows App SDK samples for resizing, placement, and window-specific behaviors instead of inventing custom platform abstractions.
+
+## Sample and Source Anchors
+
+- WinUI Gallery `NavigationView`, `TitleBar`, `AppWindow`, and windowing sample pages
+- WindowsAppSDK-Samples `Samples/Windowing`
+- Learn navigation and title bar guidance
+
+## Review Checklist
+
+- Is the navigation model simple and intentional?
+- Does the shell still look and behave like a normal WinUI `NavigationView` unless there is an explicit reason to diverge?
+- Does the title bar still behave like a Windows title bar?
+- Are back, search, and pane behaviors consistent?
+- Is multi-window use justified by the workflow?
+- Does the shell intentionally switch behavior at narrow or phone widths instead of leaving a full desktop pane open?