Stop tracking generated command wrappers and schema snapshots

.github/skills/pr-review/dimensions/ship-surfaces.md

@@ -19,7 +19,9 @@ internal and user-invisible, none of it applies — say so and return clean.
 
 ## Generated and hand-authored surfaces
 
-- `docs/cli-schema.json` is regenerated by `scripts/build-cli.ps1`.
+- The CLI schema is generated into ignored `artifacts/docs/cli-schema.json` by
+  `scripts/build-cli.ps1`. There is no tracked snapshot to update.
+- `docs/npm-usage.md` is a hand-authored task guide; npm tests type-check its examples.
 - `plugins/winapp/skills/winapp-*/SKILL.md` are hand-authored shipped files.
   Update them directly when a workflow or command changes.
 - `src/winapp-npm/src/winapp-commands.ts` regenerates via
@@ -30,14 +32,14 @@ internal and user-invisible, none of it applies — say so and return clean.
   that adds a top-level field outside `$schema`, `name`, `version`, `description`,
   `author`, `homepage`, `repository`, `license`, `keywords`, `extensions`.
 
-If `Commands/` changed and the generated schema or npm command types did not,
-flag the mismatch. Review hand-authored skills only when the command changes a
+If `Commands/` changed, verify that live schema extraction and npm generation
+cover the change; do not require generated files in the diff. Review hand-authored skills only when the command changes a
 documented workflow, example, or troubleshooting path. Do not run the scripts
 yourself.
 
 ## Match the change to affected surfaces
 
-- CLI syntax or help changes regenerate `docs/cli-schema.json` through the build;
+- CLI syntax or help changes appear in the live schema and generated npm wrappers;
   update `docs/usage.md` when it is the canonical hand-authored reference.
 - The relevant shipped skill in `plugins/winapp/skills/winapp-<area>/SKILL.md`
   when its workflow, examples, or troubleshooting changed.

.github/skills/spec-review/SKILL.md

@@ -79,13 +79,13 @@ report header — one line, not an analysis).
 ### 2. Map the impacted codebase areas
 
 The sub-agents need to know **where in the real repo to research.** Skim the
-spec, then use `grep` / `glob` / `view` (and `docs/cli-schema.json`) to locate
+spec, then use `grep` / `glob` / `view` (and `winapp --cli-schema` when built) to locate
 the actual files, commands, services, tools, and docs the proposal would touch.
 Build a short **area map** to include in every sub-agent prompt. Common buckets:
 
 | Area | Where to look |
 |------|---------------|
-| CLI commands / options | `src/winapp-CLI/WinApp.Cli/Commands/`, `docs/cli-schema.json` |
+| CLI commands / options | `src/winapp-CLI/WinApp.Cli/Commands/`, `winapp --cli-schema` when built |
 | Services & helpers | `src/winapp-CLI/WinApp.Cli/Services/`, `*Helper.cs`, `AppxManifestDocument` |
 | Packaging / MSIX / signing | `MsixService`, cert/signing services, `makeappx`/`signtool` usage |
 | Manifest handling | `AppxManifestDocument`, `ManifestHelper` |
@@ -194,7 +194,7 @@ experiments stay in temp directories. State each conclusion once.
 # Spec Review — <spec title or path>
 
 ## Decision
-<proceed | proceed-with-changes | reconsider> — <plain rationale grounded in evidence>
+<proceed | proceed-with-changes | reconsider> — <plain rationale grounded in evidence>
 
 <Only when it changes confidence or the decision: one sentence about independent
 model agreement or disagreement and the experiment/source that resolved it.>

.github/skills/spec-review/dimensions/dx-and-user-impact.md

@@ -7,7 +7,7 @@ understandable to users?** Apply the shared output contract in
 `_shared-contract.md`. Set `Domain: dx-and-user-impact` on every finding.
 
 Verify conventions against the real CLI, not your assumptions — skim
-`docs/cli-schema.json` and `src/winapp-CLI/WinApp.Cli/Commands/` to see how
+`winapp --cli-schema` when built and `src/winapp-CLI/WinApp.Cli/Commands/` to see how
 existing commands and options actually look before judging the proposal.
 
 ## Conventions to check the proposal against

.github/skills/spec-review/dimensions/feasibility-vs-reality.md

@@ -39,7 +39,7 @@ confidently, and do not stop at "the code looks like it does X"; where you can
    - API existence/shape/requirements → prefer authoritative vendor docs; where
      feasible, a tiny throwaway call.
    Keep experiments cheap and confined to temp dirs; never touch the repo tree.
-   Reading the repo's own code (`Commands/`, `Services/`, `docs/cli-schema.json`,
+   Reading the repo's own code (`Commands/`, `Services/`,
    `AppxManifestDocument`, `scripts/build-cli.ps1`) is still valuable for
    *repo-internal* behavior — but it is not a substitute for an experiment on an
    external tool/API/build mechanic.

.github/skills/spec-review/dimensions/multi-model.md

@@ -26,7 +26,7 @@ This is not a rubber stamp. Do your **own** research against reality before you
 look at anyone's conclusions.
 
 1. **Independently research the spec** the way the specialists were asked to:
-   read the real code (`Commands/`, `Services/`, `docs/cli-schema.json`) **and,
+   read the real code (`Commands/`, `Services/`) and inspect `winapp --cli-schema` when built **and,
    for anything mechanical, run your own cheap experiment** — invoke the real
    tool, build a throwaway project in a temp dir, test the real command behavior
    — rather than only re-reasoning over the specialists' text. Form your own view

.github/skills/spec-review/dimensions/necessity-and-scope.md

@@ -32,7 +32,7 @@ it is individually well-designed.
   recurring manual workaround, a documented user pain, linked issues — or is it
   "someone might want this someday" generality? Prefer concrete need.
 - **Duplication.** Does the CLI (or the npm/NuGet/VSC surfaces) already do this,
-  fully or partially? Independently check: read `docs/cli-schema.json` and skim
+  fully or partially? Independently check: run `winapp --cli-schema` when built and skim
   `src/winapp-CLI/WinApp.Cli/Commands/` for an existing command that overlaps.
 - **Smaller / staged.** Is there a minimal version that delivers most of the
   value now, with the rest deferred until the need is proven? Name the leanest
@@ -45,7 +45,7 @@ it is individually well-designed.
 
 Do not take the spec's framing of "why we need this" at face value. Verify:
 
-- Grep `Commands/` and `docs/cli-schema.json` for existing overlapping
+- Grep `Commands/` and inspect `winapp --cli-schema` when built for existing overlapping
   functionality.
 - Check whether an existing Windows SDK tool, Windows App SDK API, or standard
   OS mechanism already covers the need (so winapp would just be a thin,

.github/workflows/docs-check.yml

@@ -56,9 +56,9 @@ jobs:
               return;
             }
 
-            // Check if any docs were updated (excluding cli-schema.json which is auto-generated)
+            // Check if any user-facing docs were updated.
             const docsChanges = changedPaths.filter(p =>
-              (p.startsWith('docs/') && p !== 'docs/cli-schema.json') ||
+              p.startsWith('docs/') ||
               p === 'README.md'
             );
 

.github/workflows/plugin-check.yml

@@ -1,6 +1,7 @@
 name: Plugin Check
 
-# Fast, build-free check of plugin manifests and skills. It always runs on PRs, so it is
+# Fast, build-free structural check of plugin manifests and skills. Command examples
+# are checked against the built CLI in the post-build validate-docs job. This always runs on PRs, so it is
 # safe to mark as a required check, and skips quickly when no relevant file changed.
 # The post-build validate-docs job in build-package.yml still runs the same script.
 on:
@@ -30,7 +31,7 @@ jobs:
       - name: Validate plugin packages and skills
         shell: pwsh
         run: |
-          $relevant = '^(plugins/|scripts/validate-plugin-package\.ps1$|docs/cli-schema\.json$|src/winapp-npm/src/cli\.ts$|\.github/workflows/plugin-check\.yml$)'
+          $relevant = '^(plugins/|scripts/validate-plugin-package\.ps1$|\.github/workflows/plugin-check\.yml$)'
           $changed = @(git diff --name-only HEAD^1 HEAD)
           if ($LASTEXITCODE -ne 0) { throw "Could not list the files this PR changes." }
           $matched = @($changed | Where-Object { $_ -match $relevant })

.gitignore

@@ -207,6 +207,9 @@ CMakeCache.txt
 
 /artifacts
 
+# Retired generated documentation snapshot; schemas now live under artifacts.
+/docs/cli-schema.json
+
 # Development certificate
 devcert.pfx
 *.msix

AGENTS.md

@@ -90,7 +90,7 @@ cd src/winapp-npm && npm run build-copy-only    # copies already-built Release b
 cd src/winapp-npm && npm install
 node cli.js help
 
-# Always call the build script at the end to ensure everything builds and all autogenerated docs are generated
+# Always call the build script at the end to ensure everything builds
 .\scripts\build-cli.ps1
 
 # Produce packages first, then validate them without republishing or deleting artifacts.
@@ -99,6 +99,16 @@ node cli.js help
 .\scripts\build-cli.ps1 -OnlyTests -UseExistingArtifacts
 ```
 
+`src\winapp-npm\src\winapp-commands.ts` is ignored generated output. Change the
+CLI commands or `src\winapp-npm\scripts\generate-commands.mjs`, not that file.
+Standalone npm compile, watch, and test commands regenerate it from an available
+CLI binary. With no binary, they build and run the Debug CLI using the .NET SDK,
+so fresh-checkout npm development requires Windows and .NET as well as Node.
+The repository build extracts its current CLI schema explicitly and skips these
+npm pre-hooks to preserve that schema. Schemas under `artifacts\` are also ignored;
+never commit generated wrappers or schemas. `docs\npm-usage.md` is a hand-written
+guide, and its TypeScript examples are checked against the public API by npm tests.
+
 To measure which plugin skills Copilot CLI loads (and the tokens it uses) for realistic prompts, run the local agent benchmark: `pwsh benchmarks\agents\run.ps1 -Plan`. See [`benchmarks/agents/README.md`](benchmarks/agents/README.md).
 
 ### Running tests on a Microsoft corporate machine
@@ -290,7 +300,7 @@ token; the privileged comment workflow reads metrics as data, never executes it.
 | Services | `src/winapp-CLI/WinApp.Cli/Services/*.cs` |
 | Node CLI | `src/winapp-npm/cli.js`, `winapp-cli-utils.js` |
 | Config example | `winapp.example.yaml` |
-| CLI schema | `docs/cli-schema.json` |
+| CLI schema | `winapp --cli-schema`; command definitions in `src/winapp-CLI/WinApp.Cli/Commands/` |
 | Shipped agent skills | `plugins/winapp/skills/` |
 | Plugin (Copilot + Claude) | `plugins/winapp/` |
 | Copilot-specific plugin components | `plugins/winapp/com.github.copilot/` |
@@ -318,7 +328,8 @@ same way, and write the condition as a positive test for `rel/v*` so it fails cl
 
 ## CLI command semantics
 
-Look at the `docs\cli-schema.json` for the full schema to know what the cli can do
+Run `winapp --cli-schema` for the complete command tree. If the CLI is not built,
+read the command definitions under `src\winapp-CLI\WinApp.Cli\Commands\`.
 
 ## Quick change checklist
 
@@ -336,8 +347,10 @@ Look at the `docs\cli-schema.json` for the full schema to know what the cli can
 
 ## Documentation and skill maintenance
 
-`docs/cli-schema.json` is generated from the CLI by `scripts/generate-llm-docs.ps1`.
-Do not edit it directly; run `scripts/build-cli.ps1` to regenerate it.
+`scripts/generate-llm-docs.ps1` writes the built CLI's schema to
+`artifacts\docs\cli-schema.json` and synchronizes plugin versions by default.
+There is no tracked schema snapshot. `docs\npm-usage.md` is maintained by hand;
+use the installed npm package's declarations for the exhaustive API surface.
 
 The files under `plugins/winapp/skills/` are the hand-authored, shipped plugin
 skills shared by GitHub Copilot and Claude Code. Edit these files directly.
@@ -383,20 +396,23 @@ root under `plugins/` (any folder holding `plugin.json` and a `skills/` folder,
   files inside the same plugin — use a full `https://` URL for repo docs, and name the
   owning skill for cross-skill paths (`` `winui-packaging`'s `references/x.md` ``);
   `winapp …` lines in fenced code blocks of skills and agents (including host wrappers in
-  outer `agents/` folders) use command paths from `docs/cli-schema.json` or the npm
-  wrapper's `node` subcommands.
+  outer `agents/` folders) use command paths from a current CLI schema when
+  `-CliSchemaPath` is supplied, plus the npm wrapper's `node` subcommands.
 - **Warnings:** descriptions over 300 characters (`$DescriptionWarnChars`).
 - **Report:** approximate token sizes per skill and agent, also written to the GitHub
   Actions job summary.
 
-It needs no build output, so run it directly while editing plugin files:
+Structural checks need no build output, so run them directly while editing plugin files:
 
 ```powershell
 .\scripts\validate-plugin-package.ps1
 ```
 
-`validate-llm-docs.ps1` also invokes it, so CI fails on any conformance regression. The
-`Plugin Check` workflow (`.github/workflows/plugin-check.yml`) also runs it on every PR
+`validate-llm-docs.ps1` extracts a fresh schema from the built CLI and passes it to
+the plugin validator, so the post-build CI job also checks command examples. Run
+`.\scripts\validate-llm-docs.ps1` locally after building, or pass
+`-CliSchemaPath .\artifacts\docs\cli-schema.json` to the plugin validator.
+`Plugin Check` (`.github/workflows/plugin-check.yml`) runs structural checks on PRs
 without waiting for a CLI build, skipping quickly when no plugin-related file changed.
 
 ## C# service architecture guidelines

README.md

@@ -266,7 +266,7 @@ See also: [Security guidance](./docs/security.md) — what development certifica
 - [`node clear-electron-debug-identity`](./docs/usage.md#node-clear-electron-debug-identity) - Remove identity from Electron processes
 
 The full CLI usage can be found here: [Documentation](/docs/usage.md)
-The full NPM usage can be found here: [NPM Programmatic API Reference](/docs/npm-usage.md)
+Use winapp from JavaScript or TypeScript: [NPM programmatic guide](/docs/npm-usage.md)
 
 ## 🧾 Samples