Document winget PATH behavior and require PortableCommandAlias

.claude/skills/publishing/ref/channel-contracts.md

@@ -88,6 +88,11 @@ Use the contract-declared GitHub token liveness check before dispatching the
 manifest-declared workflow. The manifest owns the package identifier and
 installer target.
 
+Portable zip submissions must include `PortableCommandAlias: wyvern` under
+`NestedInstallerFiles` so installs expose `wyvern` on PATH (komac does not add
+this automatically — verify or amend before merge). See
+[docs/WINGET_SETUP.md](../../../../docs/WINGET_SETUP.md).
+
 ## Scoop — `scoop-publisher`
 
 Use the contract-declared GitHub token liveness check before dispatching the

docs/WINGET_SETUP.md

@@ -15,6 +15,35 @@ fork token + wrong asset name).
 Declared in `release/install.json` → rendered `release/publish-artifacts.toml`
 `[channels.winget]`.
 
+## PATH after install
+
+| Channel | Command on PATH | Notes |
+|---------|-----------------|-------|
+| **winget** | `wyvern` | Requires `PortableCommandAlias: wyvern` in the installer manifest (see below) |
+| Homebrew | `wyvern`, `wyvern-viewer` | Automatic via `bin.install` |
+| Scoop | `wyvern` | Automatic via `"bin": "bin/wyvern.exe"` shim |
+| `cargo install wyvern-cli` | `wyvern` | Only when `~/.cargo/bin` is on PATH (typical rustup setup) |
+
+After `winget install randlee.wyvern`, open a **new terminal** if `wyvern` is not
+found — winget may not refresh PATH in the current session.
+
+## PortableCommandAlias (required)
+
+Portable zip manifests must alias the nested binary to `wyvern`:
+
+```yaml
+NestedInstallerFiles:
+  - RelativeFilePath: bin/wyvern.exe
+    PortableCommandAlias: wyvern
+```
+
+Without `PortableCommandAlias`, winget defaults the shim name to the filename
+(`wyvern.exe`). Reference: `release/winget-bootstrap/0.5.0/randlee.wyvern.installer.yaml`.
+
+`winget-releaser` / komac does **not** emit this field today. After each
+automated submission (or before merging a manual PR), verify the installer
+manifest includes `PortableCommandAlias: wyvern`.
+
 ## Release model (kit)
 
 1. **Root release** (`release.yml` on `main`) builds and uploads GitHub Release

release/winget-bootstrap/0.5.0/randlee.wyvern.installer.yaml

@@ -6,6 +6,7 @@ InstallerType: zip
 NestedInstallerType: portable
 NestedInstallerFiles:
   - RelativeFilePath: wyvern.exe
+    PortableCommandAlias: wyvern
 Installers:
   - Architecture: x64
     InstallerUrl: https://github.com/randlee/wyvern/releases/download/v0.5.0/wyvern-windows.zip

release/winget-bootstrap/README.md

@@ -7,6 +7,10 @@ Uses the **legacy** v0.5.0 asset `wyvern-windows.zip` (root-level `wyvern.exe`).
 Kit releases from j.3 onward use `wyvern_<version>_x86_64-pc-windows-msvc.zip`
 with `bin/wyvern.exe`; subsequent versions are handled by the kit workflow.
 
+Every portable installer manifest must set `PortableCommandAlias: wyvern` under
+`NestedInstallerFiles`. Without it, winget exposes `wyvern.exe` on PATH instead
+of `wyvern` (Homebrew and Scoop use the bare command name).
+
 ## Submit
 
 1. Fork `microsoft/winget-pkgs` using `WINGET_GITHUB_TOKEN` (see