@fprad0/skill-master-mcp 0.0.12 → 1.0.1

package/docs/skill-candidates/v0.0.10/winui-app/references/community-toolkit-controls-and-helpers.md

@@ -1,57 +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?
+---
+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/docs/skill-candidates/v0.0.10/winui-app/references/controls-layout-and-adaptive-ui.md

@@ -1,84 +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?
+---
+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/docs/skill-candidates/v0.0.10/winui-app/references/foundation-environment-audit-and-remediation.md

@@ -1,82 +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?
+---
+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/docs/skill-candidates/v0.0.10/winui-app/references/foundation-setup-and-project-selection.md

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