[Jaylyn Barbee (Jaylyn-Barbee)]

What and why

winapp ask "how do I add a jump list?" searches WinUI samples and Microsoft Learn together. It shows sample IDs first, then up to three documentation links, each with a short plain-text excerpt (up to 400 characters). It returns search results, not a generated answer.

find-ui stays a separate, sample-only command. It is not an alias for ask, and does not send questions to Learn. Every ask question is sent to the public Learn service; do not include secrets or private project text. If Learn fails, is offline, or exceeds its five-second timeout, sample results remain available and the source error is reported, including in --json. Learn takes longer to search long questions, so the timeout message tells you to ask about one feature in a few words.

Agents learn when to use it: a new winapp-ask skill, a routing row in the winapp agent, and a pointer from the winui-design skill and winui-dev agent for features samples don't explain. The skill shows how to write short, one-feature queries, with examples.

Related to #1070. This PR is for testing the combined search workflow.

Before / after

Command on both builds: winapp ask "how do I add a jump list?".

Before — main at 444d93ce does not recognize ask. The help text that follows the error is cut with Select-Object -First 2.

After — this branch at 17c00ac5 shows WinUI samples, then Learn docs as plain-text excerpts.

Not tested / risks

MSIX and NuGet package creation, the full managed suite, and sample/UI end-to-end suites have not been run locally. Runtime checks were on ARM64; x64 was built but not exercised. Learn's search time grows with question length (about 1.3s at 36 characters, 2.3s at 432, and over 5s at 1,700), so a pasted task description still returns samples without docs. Offline, ask keeps samples and reports that Learn could not be reached.

Local validation

• pwsh -NoProfile -File .\scripts\build-cli.ps1 -SkipTests -SkipMsix -SkipNuGet — passed on the final head, including native x64 and ARM64 publishes with the normal trim/NativeAOT warning gates, DevTools engine checks, npm packaging, formatting, lint and compilation. The process-local PATH included the Visual Studio Installer directory. No audit or AOT warning suppression was needed.
• dotnet test --project src\winapp-CLI\WinApp.Cli.Tests\WinApp.Cli.Tests.csproj -c Release -- --filter 'FullyQualifiedName~AskCommandTests|FullyQualifiedName~LearnSearchClientTests|FullyQualifiedName~FindUiCommandTests|FullyQualifiedName~ProgramJsonBridgeTests|FullyQualifiedName~ScenarioSanitizerTests' — passed, 240 tests.
• npm run build-copy-only then npm test in src\winapp-npm — passed, 347 tests, including the generated ask wrapper and guide examples.
• pwsh -NoProfile -File .\scripts\validate-plugin-package.ps1 — passed, including after the WinUI skill update.
• pwsh -NoProfile -File .\scripts\validate-llm-docs.ps1 — passed against the current CLI schema.
• npm install --global --prefix .\artifacts\ask-installed .\artifacts\microsoft-winappcli-0.7.2-jaylyn-barbee-winapp-ask-starter.107.tgz then .\artifacts\ask-installed\winapp.cmd ask "how do I add a jump list?" --json — passed; the isolated installation returned one sample group and three docs, exit 0.
• Published ARM64 checks: ask "azure storage blob upload" --json returned three docs after fixing mixed-source results; ask --json returned a flat parser error and exit 1; find-ui "jump list" --json returned sample matches without docs.

Checklist

• Tests added or updated
• Tested locally on Windows
• Docs, samples, and plugins/winapp/skills/ updated if user-facing behavior changed

Notes for reviewers

Uses the public Learn MCP endpoint over HTTPS with ModelContextProtocol.Core protocol types. The transport uses source-generated JSON so the CLI keeps its NativeAOT build gates. There is no CLI batch syntax.

No corpus re-bake is needed: the only sanitizer change makes its existing terminal-control filter accessible to the Learn client; the filter and baked sample output are unchanged.

[Copilot]

🔵 Needs a closer look

The new network transport and NativeAOT dependency need final human review, with current-head packaging and required CI results still unverified here.

No open issues 🎉

What changed in this PR

Adds winapp ask "<question>" to search WinUI samples and Microsoft Learn documentation together, addressing the broader Windows development questions in #1070. Results remain separate from generated answers, and find-ui stays sample-only.

Changes:

• Adds text and JSON output with separate sample matches, documentation links, and source errors.
• Adds a Learn client with a three-second deadline, bounded responses, and sample preservation when documentation search fails.
• Adds command, transport, and npm tests, plus usage documentation and agent guidance covering privacy and partial results.

File	Description
src/​winapp-npm/​test/​winapp-commands-run.test.ts	Tests question forwarding and preservation of JSON results.
src/​winapp-CLI/​WinApp.Cli/​WinApp.Cli.csproj	References the MCP protocol package.
src/​winapp-CLI/​WinApp.Cli/​Services/​Learn/​LearnSearchClient.cs	Implements Learn requests, timeout handling, filtering, and result limits.
src/​winapp-CLI/​WinApp.Cli/​Services/​Controls/​ScenarioSanitizer.cs	Makes text sanitization available to Learn results.
src/​winapp-CLI/​WinApp.Cli/​Program.cs	Routes ask parser errors through the flat JSON contract.
src/​winapp-CLI/​WinApp.Cli/​Models/​JsonOutputModels.cs	Adds source-generated JSON models for combined results.
src/​winapp-CLI/​WinApp.Cli/​Helpers/​HostBuilderExtensions.cs	Registers the Learn client and command handler.
src/​winapp-CLI/​WinApp.Cli/​Commands/​WinAppRootCommand.cs	Registers ask and includes it in grouped help.
src/​winapp-CLI/​WinApp.Cli/​Commands/​FindUiCommand.cs	Shares existing sample formatting and JSON conversion.
src/​winapp-CLI/​WinApp.Cli/​Commands/​AskCommand.cs	Coordinates both searches and presents results or source errors.
src/​winapp-CLI/​WinApp.Cli.Tests/​ProgramJsonBridgeTests.cs	Tests JSON parser errors for ask.
src/​winapp-CLI/​WinApp.Cli.Tests/​LearnSearchClientTests.cs	Tests protocol handling, limits, cancellation, and malformed responses.
src/​winapp-CLI/​WinApp.Cli.Tests/​AskCommandTests.cs	Tests combined output, partial failures, privacy help, and command separation.
src/​winapp-CLI/​Directory.Packages.props	Pins the MCP protocol dependency version.
README.md	Adds ask to discovery commands with a privacy note.
plugins/​winapp/​skills/​winapp-find-ui/​SKILL.md	Links to the broader documentation-search skill.
plugins/​winapp/​skills/​winapp-ask/​SKILL.md	Guides research, privacy, evidence checking, and partial-result handling.
plugins/​winapp/​com.github.copilot/​agents/​winapp.agent.md	Routes documentation questions to the new skill.
docs/​usage.md	Documents usage, privacy, result limits, JSON fields, and exit codes.
docs/​npm-usage.md	Adds the npm wrapper example and links to privacy guidance.

_{Review effort: Balanced}

[github-actions]

Build Metrics Report

Validation passed. All required build and validation jobs succeeded.

Binary Sizes

Artifact	Baseline	Current	Delta
CLI (ARM64)	65.45 MB	65.75 MB	📈 +300.5 KB (+0.45%)
CLI (x64)	65.35 MB	65.64 MB	📈 +294.5 KB (+0.44%)
MSIX (ARM64)	27.09 MB	27.20 MB	📈 +111.5 KB (+0.40%)
MSIX (x64)	28.70 MB	28.82 MB	📈 +121.5 KB (+0.41%)
NPM Package	56.42 MB	56.66 MB	📈 +254.7 KB (+0.44%)
NuGet Package	56.57 MB	56.82 MB	📈 +248.8 KB (+0.43%)

.NET Test Results (TRX reports)

Other suites are reflected in the overall validation status above.

✅ 11135 passed, 44 skipped out of 11179 tests in 1636.7s (+116 tests, -482.0s vs. baseline)

Test Coverage

✅ 87.6% line coverage, 81.8% branch coverage · ✅ no change vs. baseline

CLI Startup Time

65ms median (x64, winapp --version) · ✅ -8ms vs. baseline

Try This Build

Installs the MSIX for your architecture, replacing any previously installed build. Needs the GitHub CLI — the command offers to install it and sign you in if it is missing.

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) 1187

Switching between builds often?

Put the tool on your PATH once:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) -AddToPath

Then this build is just:

winapp-pr 1187

Run winapp-pr with no arguments to pick from a list of open PRs.

---

Updated 2026-11-05 14:53:47 UTC · commit 70f10e5 · workflow run

[Zach Teutsch (zateutsch)]

🤖 AI-generated review (winappcli pr-review skill) — verify before acting.

No blocking defects found in the review of commit 2390b06. The optional quiet-mode note is inline. The PR has since advanced to ad68955; I verified that the commented code is unchanged, but have not reviewed the other changes in that newer head.

At the reviewed commit, x64 and ARM64 native publishes passed, all 222 targeted tests passed, and published CLI checks covered live Learn results, unavailable Learn with preserved samples, JSON parser errors, and empty-result exit codes. Plugin validation against the published schema also passed. Full test and packaging suites were not rerun locally; the GitHub checks inspected during the review passed.