docs: prefer managed/Scoop on Windows; avoid winget and Chocolatey

Recommend GitHub-tracking install and upgrade paths only. Status and
ready-check upgrade actions prefer Update/Install Patchloom managed
over Open Releases so users do not stick on lagging community packages.

Signed-off-by: Sebastien Tardif <sebtardif@ncf.ca>

Author: SebTardif

AGENTS.md

@@ -51,7 +51,7 @@ test/
     batchApply.test.ts   Batch template and operation count parsing (16 tests)
     binary.test.ts       Binary discovery, managed install, compatibility, workspace env (59 tests)
     binaryDiscovery.test.ts  Real executable discovery on PATH (13 tests)
-    initializeProject.test.ts  Status display, agents file classification, formatError (37 tests)
+    initializeProject.test.ts  Status display, agents file classification, formatError (39 tests)
     managedLifecycle.test.ts   Managed install with real file I/O (22 tests)
     mcpConfig.test.ts    MCP config with real temp directories (12 tests)
     outputChannel.test.ts Output channel logging wrapper (10 tests)

README.md

@@ -25,17 +25,16 @@ Or search for **Patchloom** in the Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+
 
 ## Get started in 30 seconds
 
-1. Install the [Patchloom CLI](https://github.com/patchloom/patchloom) (or run **Patchloom: Install Patchloom** from the command palette)
+1. Install the [Patchloom CLI](https://github.com/patchloom/patchloom) (or run **Patchloom: Install Patchloom** from the command palette; recommended: tracks GitHub Releases with checksum verification)
    ```sh
    brew install patchloom/tap/patchloom          # macOS / Linux (Homebrew)
    npm install -g patchloom                      # npm (Node.js)
    curl -LsSf https://github.com/patchloom/patchloom/releases/latest/download/patchloom-installer.sh | sh  # shell script
    cargo install patchloom                        # from source
    scoop bucket add patchloom https://github.com/patchloom/scoop-bucket
-   scoop install patchloom                        # Windows (Scoop; preferred Windows channel)
-   winget install Patchloom.Patchloom             # Windows (WinGet; run winget source update if the package is missing)
-   choco install patchloom                        # Windows (Chocolatey; often lags moderation)
+   scoop install patchloom                        # Windows (Scoop; preferred PATH channel)
    ```
+   On Windows, prefer the extension managed installer or Scoop. Avoid winget and Chocolatey for install or upgrade: both lag GitHub Releases and often leave you on an old CLI.
 2. Open a project and run **Patchloom: Setup Workspace**
 
 <p align="center">
@@ -175,8 +174,14 @@ The extension detects outdated CLI builds and warns with upgrade guidance. It re
 **Patchloom not found**
 Set `patchloom.path` in settings, or add the CLI to your `PATH`.
 
-**CLI compatibility warning**
-Run `Patchloom: Open Releases` to download the latest release. The extension requires 0.3.0 or newer; **0.28.0** is recommended.
+**CLI compatibility warning / upgrade path**
+The extension requires Patchloom **0.3.0** or newer; **0.28.0** is recommended. Prefer channels that track GitHub Releases the same day:
+
+1. **Patchloom: Update Patchloom** (or **Install Patchloom**) for the extension managed install (checksum-verified download from GitHub Releases)
+2. **Scoop** on Windows: `scoop update patchloom` after `scoop install patchloom`
+3. Homebrew / npm / cargo / the official installer script on macOS and Linux
+
+Do **not** rely on winget or Chocolatey to stay current. Those community packages lag moderation and Microsoft publish, so upgrades often stay stuck on older CLI versions.
 
 **Path rejected by workspace guard**
 Quick Actions and Batch Apply pass `--contain` so paths stay inside the open workspace folder. On CLI 0.18+, sandbox escapes report `error_kind: guard_rejected` (not a generic `invalid_input`). Keep targets under the workspace root, or open the folder that owns the files.

package.json

@@ -162,7 +162,7 @@
           {
             "id": "installCli",
             "title": "Install the Patchloom CLI",
-            "description": "Install the Patchloom CLI via the managed installer, Homebrew, or cargo.\n\n[Install Patchloom](command:patchloom.installBinary)",
+            "description": "Install the Patchloom CLI via the managed installer (recommended), Scoop on Windows, Homebrew, or cargo. Avoid winget and Chocolatey; they lag releases.\n\n[Install Patchloom](command:patchloom.installBinary)",
             "media": {
               "markdown": "walkthrough/install.md"
             },

src/binary/patchloom.ts

@@ -182,11 +182,23 @@ export async function ensurePatchloomReadyOrNotify(
 
   if (patchloomNeedsUpgrade(status)) {
     const vscode = await import("vscode");
+    // Prefer managed install/update (GitHub Releases) over lagging community packages.
+    const canUpdateManaged = status.source === "managed" || status.managedInstall?.exists === true;
+    const canInstallManaged = status.managedInstall !== undefined;
+    const primaryAction = canUpdateManaged
+      ? "Update Patchloom"
+      : canInstallManaged
+        ? "Install Patchloom"
+        : "Open Releases";
     const choice = await vscode.window.showWarningMessage(
       `${status.compatibilityMessage}${contextSuffix ? `\n\n${contextSuffix}` : ""}`,
-      "Open Releases"
+      primaryAction
     );
-    if (choice === "Open Releases") {
+    if (choice === "Update Patchloom") {
+      await vscode.commands.executeCommand("patchloom.updateBinary");
+    } else if (choice === "Install Patchloom") {
+      await vscode.commands.executeCommand("patchloom.installBinary");
+    } else if (choice === "Open Releases") {
       await vscode.commands.executeCommand("patchloom.openPatchloomReleases");
     }
     return null;

src/status/details.ts

@@ -57,6 +57,20 @@ export function preferredStatusAction(status: PatchloomStatus, workspaceReadines
   }
 
   if (patchloomNeedsUpgrade(status)) {
+    // Prefer managed install/update so users stay on GitHub Releases (not lagging
+    // community packages such as winget/Chocolatey).
+    if (status.source === "managed" || status.managedInstall?.exists) {
+      return {
+        title: "Update Patchloom",
+        command: "patchloom.updateBinary"
+      };
+    }
+    if (status.managedInstall) {
+      return {
+        title: "Install Patchloom",
+        command: "patchloom.installBinary"
+      };
+    }
     return {
       title: "Open Releases",
       command: "patchloom.openPatchloomReleases"

test/unit/initializeProject.test.ts

@@ -344,7 +344,65 @@ test("buildStatusDetails surfaces managed install failure diagnostics", () => {
   assert.match(details, /Managed install diagnostic: Checksum mismatch/);
 });
 
-test("preferredStatusAction points outdated CLI users to releases", () => {
+test("preferredStatusAction points outdated PATH CLI users to managed install", () => {
+  const action = preferredStatusAction({
+    ready: true,
+    source: "path",
+    message: "Using Patchloom from PATH.",
+    binaryPath: "/usr/local/bin/patchloom",
+    version: "patchloom 0.0.9",
+    detectedVersion: "0.0.9",
+    compatibility: "unsupported",
+    minimumSupportedVersion: MINIMUM_SUPPORTED_PATCHLOOM_VERSION,
+    compatibilityMessage: `Patchloom 0.0.9 is older than the minimum supported version ${MINIMUM_SUPPORTED_PATCHLOOM_VERSION}.`,
+    managedInstall: {
+      exists: false,
+      binaryPath: "/managed/managed-bin/patchloom",
+      target: {
+        platform: "darwin",
+        arch: "arm64",
+        targetTriple: "aarch64-apple-darwin",
+        archiveFormat: ".tar.xz"
+      }
+    }
+  });
+
+  assert.deepEqual(action, {
+    title: "Install Patchloom",
+    command: "patchloom.installBinary"
+  });
+});
+
+test("preferredStatusAction points outdated managed CLI users to update", () => {
+  const action = preferredStatusAction({
+    ready: true,
+    source: "managed",
+    message: "Using managed Patchloom install.",
+    binaryPath: "/managed/managed-bin/patchloom",
+    version: "patchloom 0.0.9",
+    detectedVersion: "0.0.9",
+    compatibility: "unsupported",
+    minimumSupportedVersion: MINIMUM_SUPPORTED_PATCHLOOM_VERSION,
+    compatibilityMessage: `Patchloom 0.0.9 is older than the minimum supported version ${MINIMUM_SUPPORTED_PATCHLOOM_VERSION}.`,
+    managedInstall: {
+      exists: true,
+      binaryPath: "/managed/managed-bin/patchloom",
+      target: {
+        platform: "darwin",
+        arch: "arm64",
+        targetTriple: "aarch64-apple-darwin",
+        archiveFormat: ".tar.xz"
+      }
+    }
+  });
+
+  assert.deepEqual(action, {
+    title: "Update Patchloom",
+    command: "patchloom.updateBinary"
+  });
+});
+
+test("preferredStatusAction falls back to releases when managed install unavailable", () => {
   const action = preferredStatusAction({
     ready: true,
     source: "path",

walkthrough/install.md

@@ -1,51 +1,43 @@
 # Install the Patchloom CLI
 
-Patchloom needs the CLI binary to work. Choose one of these methods:
+Patchloom needs the CLI binary to work. Prefer channels that track
+GitHub Releases promptly (same day as the tag).
 
-## Managed Install (Recommended)
+## Managed Install (Recommended on all platforms)
 
 Click **Install Patchloom** above to download and install the CLI
 automatically. The extension handles download, checksum verification,
-and installation.
+and installation from GitHub Releases.
 
-## Homebrew
+To upgrade later, run **Patchloom: Update Patchloom** (managed install
+only). That path always pulls the latest GitHub release.
 
-```bash
-brew install patchloom/tap/patchloom
-```
-
-## npm
-
-```bash
-npm install -g patchloom
-# or one-shot: npx patchloom --version
-```
-
-## Scoop (Windows, preferred)
+## Scoop (preferred Windows PATH install)
 
 ```bash
 scoop bucket add patchloom https://github.com/patchloom/scoop-bucket
 scoop install patchloom
+scoop update patchloom
 ```
 
-Scoop tracks GitHub Releases promptly. Prefer it when you manage Windows installs yourself.
+Scoop tracks the project release bucket. Use it when you want the CLI on
+`PATH` yourself. Avoid winget and Chocolatey for install or upgrade:
+both lag GitHub Releases and often leave you on an old version.
 
-## WinGet (Windows)
+## Homebrew (macOS / Linux)
 
 ```bash
-winget install Patchloom.Patchloom
+brew install patchloom/tap/patchloom
+brew upgrade patchloom
 ```
 
-After a new release, you may need `winget source update` before the package appears. Microsoft publish can lag the GitHub tag by a short window.
-
-## Chocolatey (Windows)
+## npm
 
 ```bash
-choco install patchloom
+npm install -g patchloom
+# or one-shot: npx patchloom --version
 ```
 
-Community moderation often lags Scoop and GitHub portable assets.
-
 ## Cargo
 
 ```bash