Depends on #652 — the lexical/fuzzy port of the winmd tool into winapp (full v1). This issue adds the semantic layer on top of that ported foundation.

Is your feature request related to a problem? Please describe.

To call a Windows API, a developer (or agent) has to already know the namespace/type/method and then find a usage example. Discovery today means grepping metadata, browsing docs, or guessing — and agents in particular waste turns hallucinating API shapes instead of grounding on the real surface. There's no way to ask, in natural language, "which API does X, and how do I call it?" from the CLI.

Current state

• API discovery lives in the separate winmd tool (in the microsoft/win-dev-skills repo). It's a native-AOT, fully-local/offline tool that scans a project's referenced .winmd/.dll metadata (NuGet + Windows SDK + WinAppSDK), parses it plus XML docs (48K+ IntelliSense-grade API descriptions), and caches structured JSON to %LOCALAPPDATA%\winmd-cache — refreshing when the project's packages change.
• Its query commands (search, members, check-property, types, enums) read that local cache, but search is fuzzy/lexical — natural-language intent ("read a file the user picked") doesn't resolve.
• The repo's own WinmdService is unrelated: it only finds activatable classes / WinRT components for packaging, not the full API surface — so the search-oriented winmd work needs to be brought over.

Describe the solution you'd like

Add a winapp find-api "<query>" command: natural-language, semantic search over Windows/WinRT APIs that returns the relevant API plus how to call it. Same shape as winapp find-ui (#625), over a different primary corpus (Windows/WinRT API metadata rather than UI controls).

• Natural-language query — "read a file the user picked", "show a toast", not just exact type names.
• Semantic matching — ranks by intent, computed locally; the existing fuzzy/lexical search stays as the fast exact-name path.
• Framework-agnostic — covers any framework that references WinRT metadata (WASDK/WinUI, Windows SDK/UWP, C++/WinRT, C#/WinRT, Rust/WinRT).
• Agent-friendly output — --json with a structured result (API, signature, snippet, source, link) so an agent grounds on the real surface in one shot.

Replaces the winmd tool (from microsoft/win-dev-skills), upgrading it from fuzzy to semantic.

Proposed architecture

find-api searches three sources, split by locality, unified in one shared vector space (shared with find-ui):

• Local — your project's API surface (referenced winmds, including private/preview): reuse the ported winmd scan/cache, embed those records on-device with the bundled model. Never uploaded; the only place this data can be indexed.
• Global — docs + samples (same for every user): gathered and embedded centrally at release, delivered as a download-only, fetch-and-cached vector index (small bundled baseline for offline). No user data is uploaded.
• Query — on-device: embedded locally and compared against both; the existing fuzzy/lexical winmd search stays as the fast exact-name path.

winapp find-api "<query>"
  ├─ (local)  ported winmd scan/cache → embed your referenced APIs on-device   [lazy, incremental]
  ├─ (global) ensure docs+samples index (bundled baseline + fetch/refresh online)
  ├─ embed the query locally with the bundled model
  ├─ search all sources in one vector space; merge/rank hits
  │     (semantic hits can also generate candidate API/type names → feed the local lexical winmd search)
  └─ return ranked results (API, signature, snippet, source, link)   [+ --json]

• Reuse, don't rebuild: port the winmd tool's parser/cache/query engine; the new work is the on-device semantic layer + the global index integration.
• Payload minimized: the only heavy bundled artifact is the shared embedding model. Local API vectors are computed on-device (winmd already caches to %LOCALAPPDATA%); the global docs/samples index is fetched-and-cached, not shipped whole.
• Lazy/incremental local indexing: embed on first probe; refresh when the project's packages change (reuse the project.assets.json staleness check); explicit refresh for CI/force.
• Cross-source, one call: semantically search docs + samples, ground against your local API surface, and use semantic hits to generate concrete API names for the local lexical search — one call, all sources (fewer agent turns, fewer tokens).
• Download-only cloud: the service serves public prebuilt vectors to the client; it never receives the query or your project's metadata.
• Shared model / one vector space with find-ui, toward a future unified index across UI, docs, and APIs.
• The main thing to approve: find-api = on-device local winmd index + fetch-and-cached global docs/samples index + local query embedding, on the shared model.

Stretch goal

Grow the corpus to include popular/common API records beyond your project, so a broad question ("what's the best API for X?") can recommend packages/APIs you haven't referenced yet — discovery on top of v1's grounding.

Open questions

• Cost of embedding the local cache at scan time — embed only the referenced surface (subset) vs. the full 48K; incremental vs. full.
• Global docs/samples index: how it's gathered/embedded centrally (sources, chunking, release pipeline) and how much ships offline vs. fetch-and-cache.
• Payload budget for the bundled model (~30–40 MB quantized), shared with find-ui.
• Result schema shape? needs to be aligned with find-ui.
• Command placement

Additional context

Part of the single-winapp-CLI direction (new top-level command). Migrates the winmd tool from microsoft/win-dev-skills into winapp. Sibling of winapp find-ui (semantic control/sample search) — the two share an embedding model/vector space toward a future unified semantic index across UI, docs, and APIs. Future function winapp ask <query> once each has been established?