@codyswann/lisa 2.327.0 → 2.328.0

package/plugins/lisa/skills/lisa-setup-local-env/scripts/local-env.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * Bring a developer's machine in line with the toolchain the project declares.
+ *
+ * The manifest, the planner, the pins and the installers are the remote flow's,
+ * unchanged and imported — this is the surface that was missing, not a second
+ * implementation. `remoteEnv.tools` was always surface-aware and the executor
+ * always understood `local`; the only way to reach either was to run a file
+ * called `setup-remote-env.mjs` out of a directory called `lisa-remote-env`,
+ * which nobody looking for local setup ever found.
+ *
+ * Two things differ from the remote flow, and both are because a person is here:
+ *
+ *   consent  — a container provisions itself silently because it is disposable
+ *              and nobody is watching. A laptop belongs to someone, so nothing
+ *              is installed until they ask with --install-tools.
+ *
+ *   tolerance — a container that cannot be fully provisioned should fail before
+ *              it half-runs, because there is no one to read the report. A
+ *              developer can act on a list, so an unprovisionable tool is
+ *              reported, everything else is still installed, and the exit code
+ *              carries the failure.
+ * @module local-env
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve a script belonging to a sibling skill.
+ *
+ * Skills are always siblings under one `skills/` directory, in every install
+ * layout, so this holds for a plugin install, a checkout, and node_modules
+ * alike. Failing loudly here beats reimplementing what the sibling owns.
+ * @param {string} skill Sibling skill slug.
+ * @param {string} script Script filename.
+ * @returns {string} Absolute path.
+ */
+function siblingScript(skill, script) {
+  const path = resolve(HERE, "..", "..", skill, "scripts", script);
+  if (!existsSync(path)) {
+    throw new Error(
+      `cannot find ${skill}/scripts/${script} beside this skill.\n` +
+        `Local setup composes with that skill rather than reimplementing it: ` +
+        `the pins, checksums and installers must be the same ones the remote ` +
+        `surface uses, or the two drift and only one gets fixed.`
+    );
+  }
+  return path;
+}
+
+/**
+ * Load the pieces the remote flow owns.
+ * @returns {Promise<object>} The imported helpers.
+ */
+async function loadRemoteEnv() {
+  const setup = await import(
+    pathToFileURL(
+      siblingScript("lisa-setup-remote-env", "setup-remote-env.mjs")
+    ).href
+  );
+  const toolchain = await import(
+    pathToFileURL(siblingScript("lisa-setup-remote-env", "toolchain.mjs")).href
+  );
+  return { ...toolchain, ...setup };
+}
+
+/**
+ * Describe one blocked decision in terms a person can act on.
+ *
+ * A blocked step on a laptop is usually one of two things, and they are fixed
+ * differently: a tool the project requires and the machine lacks (install it),
+ * or a tool with no artifact pinned for this platform (add the pin, or install
+ * it however this platform normally would). Printing the planner's reason alone
+ * left the reader to work out which.
+ * @param {object} step A plan step.
+ * @param {string} platform The platform key that was resolved against.
+ * @returns {string} A rendered block.
+ */
+function explainBlocked(step, platform) {
+  if (step.action === "invalid" && step.reason.includes("no pin for")) {
+    return (
+      `  ${step.name} — declared, but no artifact is pinned for ${platform}.\n` +
+      `      Lisa will not guess a download URL, because a guessed artifact is ` +
+      `one the checksum cannot vouch for.\n` +
+      `      Add a "${platform}" block under this tool's "platforms" map, or ` +
+      `install it yourself.`
+    );
+  }
+  return `  ${step.name} — ${step.reason.split("\n")[0]}`;
+}
+
+/**
+ * Report and optionally apply the local toolchain.
+ * @param {object} argv Parsed arguments.
+ * @returns {Promise<number>} Process exit code.
+ */
+export async function run(argv) {
+  const env = await loadRemoteEnv();
+  // Both seams exist for tests, and both default to this machine. A platform
+  // that can only be exercised by running on it is one CI will never cover,
+  // which is how a resolution bug ships to the platform nobody tested.
+  const platform = argv.platform ?? env.currentPlatform();
+  const { tools } = env.readRemoteEnvConfig(argv.cwd);
+
+  const declared = (tools.require ?? []).length + (tools.install ?? []).length;
+  if (declared === 0) {
+    console.log(
+      "No tools are declared in remoteEnv.tools, so there is nothing to check.\n" +
+        "Run /lisa:detect-tooling — it reads npm scripts, MCP servers, " +
+        "credential\nnotes and quality config, and proposes pinned entries for " +
+        "what it finds."
+    );
+    return 0;
+  }
+
+  const plan = env.planToolchain(tools, env.probe, "local", platform);
+  const blocked = plan.filter(
+    step => step.action === "missing" || step.action === "invalid"
+  );
+  const installable = plan.filter(step => step.action === "install");
+
+  if (argv.json) {
+    console.log(JSON.stringify({ platform, plan }, null, 2));
+    return blocked.length ? 1 : 0;
+  }
+
+  console.log(`Local toolchain for ${platform}\n`);
+  for (const step of plan) {
+    console.log(`  ${step.action.padEnd(8)} ${step.reason.split("\n")[0]}`);
+  }
+
+  if (installable.length && !argv.installTools) {
+    console.log(
+      `\n${installable.length} declared tool(s) can be installed here.\n` +
+        `Nothing has been installed: this machine is yours, not a container.\n` +
+        `Re-run with --install-tools to provision them into ~/.local/bin.`
+    );
+  }
+
+  if (installable.length && argv.installTools) {
+    const binDir = env.ensureBinDir();
+    console.log(`\nInstalling into ${binDir}`);
+    for (const step of installable) {
+      console.log(`  ${step.name}`);
+      if (!argv.dryRun) env.installTool(step.tool, binDir);
+    }
+  }
+
+  if (blocked.length) {
+    console.log(`\n${blocked.length} tool(s) this command cannot resolve:\n`);
+    for (const step of blocked) console.log(explainBlocked(step, platform));
+    return 1;
+  }
+
+  return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const argv = {
+    installTools: process.argv.includes("--install-tools"),
+    dryRun: process.argv.includes("--dry-run"),
+    json: process.argv.includes("--json"),
+  };
+  run(argv)
+    .then(code => process.exit(code))
+    .catch(err => {
+      console.error(err.message);
+      process.exit(1);
+    });
+}

package/plugins/lisa/skills/lisa-setup-remote-env/SKILL.md

@@ -95,6 +95,19 @@ This repository has paid for that twice: `gh` was declared nowhere and a cloud s
 
 The detector proposes and a human decides. It writes nothing, so provisioning still only ever happens from a reviewed, pinned, checksummed entry.
 
+## The same manifest provisions a laptop
+
+`remoteEnv.tools` is not a remote-only manifest, and `/lisa:setup:local-env` is how a developer
+applies it to their own machine — same pins, same checksums, same installers, differing only in
+that nothing installs without `--install-tools` and that a newer tool already on `PATH` is left
+alone rather than downgraded.
+
+A downloaded tool declares a `platforms` map keyed `<platform>-<arch>`, each block carrying its
+own `install` method, `url`, and `sha256`, because the artifact and the archive kind both vary
+by platform. Before that existed, the only way to keep a Linux binary off a laptop was
+`surfaces: ["remote"]`, which achieved it by making the tool uninstallable there — so `bws` and
+`gh` were required on developer machines and provisionable only in containers.
+
 ## Toolchain manifest — two entry kinds
 
 ```json
@@ -108,20 +121,23 @@ The detector proposes and a human decides. It writes nothing, so provisioning st
         { "name": "unzip" }
       ],
       "install": [
-        {
-          "name": "bws",
-          "version": "2.1.0",
-          "install": "release-zip",
-          "url": "https://<vendor>/releases/download/bws-v2.1.0/bws-<platform>-2.1.0.zip",
-          "sha256": "<sha256 published with that exact release>"
-        },
         {
           "name": "gh",
           "version": "2.83.0",
-          "install": "release-tar",
-          "url": "https://<vendor>/releases/download/v2.83.0/gh_2.83.0_linux_amd64.tar.gz",
-          "sha256": "<sha256 published with that exact release>",
-          "binary": "gh_2.83.0_linux_amd64/bin/gh"
+          "platforms": {
+            "linux-x64": {
+              "install": "release-tar",
+              "url": "https://<vendor>/releases/download/v2.83.0/gh_2.83.0_linux_amd64.tar.gz",
+              "sha256": "<sha256 published with that exact release>",
+              "binary": "gh_2.83.0_linux_amd64/bin/gh"
+            },
+            "darwin-arm64": {
+              "install": "release-zip",
+              "url": "https://<vendor>/releases/download/v2.83.0/gh_2.83.0_macOS_arm64.zip",
+              "sha256": "<sha256 published with that exact release>",
+              "binary": "gh_2.83.0_macOS_arm64/bin/gh"
+            }
+          }
         },
         {
           "name": "codex",

package/plugins/lisa/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs

@@ -29,6 +29,7 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import {
   chmodSync,
   existsSync,
@@ -37,7 +38,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { basename, delimiter, dirname, join, resolve } from "node:path";
+import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { assertPinned, extractVersion, planToolchain } from "./toolchain.mjs";
@@ -122,6 +123,34 @@ export function probe(name, exec = execFileSync) {
   }
 }
 
+/**
+ * Refuse an archive whose contents are not exactly what was pinned.
+ *
+ * Hashed in-process rather than by shelling out. `sha256sum` is a GNU coreutils
+ * program: it is not present on a stock macOS, where the equivalent is
+ * `shasum -a 256`, and it was never in the manifest's `require` list either — so
+ * the verification step depended on a tool nothing asserted, on every surface.
+ * Doing it here removes the dependency instead of adding a second name to probe
+ * for, and the check can then be tested without a real archive or a real binary.
+ * @param {string} archive Path to the downloaded file.
+ * @param {string} expected Pinned lowercase hex digest.
+ * @param {string} name Tool name, for the message.
+ */
+export function verifyChecksum(archive, expected, name) {
+  const actual = createHash("sha256")
+    .update(readFileSync(archive))
+    .digest("hex");
+  if (actual !== String(expected).trim().toLowerCase()) {
+    throw new Error(
+      `${name}: checksum mismatch — refusing to install.\n` +
+        `  expected ${expected}\n` +
+        `  actual   ${actual}\n` +
+        `The URL served something other than the reviewed artifact. Do not ` +
+        `update the pin to match without establishing why it changed.`
+    );
+  }
+}
+
 /**
  * Install a pinned archive, refusing anything whose checksum does not match.
  * @param {object} tool Manifest entry.
@@ -137,10 +166,7 @@ function installReleaseZip(tool, binDir) {
     });
     // Verify before unpacking, not after. An unexpected archive must fail
     // before any of its contents reach a directory that is on PATH.
-    execFileSync("sha256sum", ["-c", "-"], {
-      input: `${tool.sha256}  ${archive}\n`,
-      stdio: ["pipe", "ignore", "inherit"],
-    });
+    verifyChecksum(archive, tool.sha256, tool.name);
     execFileSync("unzip", ["-q", "-o", archive, "-d", temporary], {
       stdio: "inherit",
     });
@@ -171,10 +197,7 @@ function installReleaseTar(tool, binDir) {
     execFileSync("curl", ["-fsSL", tool.url, "-o", archive], {
       stdio: "inherit",
     });
-    execFileSync("sha256sum", ["-c", "-"], {
-      input: `${tool.sha256}  ${archive}\n`,
-      stdio: ["pipe", "ignore", "inherit"],
-    });
+    verifyChecksum(archive, tool.sha256, tool.name);
     execFileSync("tar", ["-xzf", archive, "-C", temporary], {
       stdio: "inherit",
     });
@@ -205,16 +228,46 @@ function installNpmGlobal(tool) {
 
 /**
  * Execute one install decision.
- * @param {object} tool Manifest entry.
+ *
+ * Exported because the local-environment flow installs from the same manifest
+ * with the same pins and the same checksum refusal. A second installer would be
+ * a second thing to keep honest, and the one people run least would rot.
+ * @param {object} tool Manifest entry, already resolved to this platform.
  * @param {string} binDir Directory for downloaded binaries.
  */
-function installTool(tool, binDir) {
+export function installTool(tool, binDir) {
   assertPinned(tool);
   if (tool.install === "release-zip") installReleaseZip(tool, binDir);
   else if (tool.install === "release-tar") installReleaseTar(tool, binDir);
   else installNpmGlobal(tool);
 }
 
+/**
+ * Create the directory installs land in, and make sure PATH will find it.
+ *
+ * Installing a binary somewhere nothing looks is the same as not installing it.
+ * `~/.local/bin` is on PATH by default on a developer workstation and is NOT on
+ * a minimal container, so the toolchain step reported `install bws`, the file
+ * landed at ~/.local/bin/bws mode 755, and the very next step died with
+ * `spawnSync bws ENOENT`.
+ *
+ * This was invisible in every local test because a workstation shell already
+ * exports the directory — the environment doing the hiding was the one used to
+ * verify the fix.
+ *
+ * Prepended, not appended: a pinned-and-checksummed binary must win over
+ * whatever an image happens to ship under the same name.
+ * @returns {string} The directory installs are written to.
+ */
+export function ensureBinDir() {
+  const binDir = join(process.env.HOME ?? "", ".local", "bin");
+  mkdirSync(binDir, { recursive: true, mode: 0o755 });
+  if (!pathContains(binDir)) {
+    process.env.PATH = `${binDir}${delimiter}${process.env.PATH ?? ""}`;
+  }
+  return binDir;
+}
+
 /**
  * Apply the toolchain plan, reporting every decision.
  * @param {object} tools Manifest.
@@ -231,8 +284,7 @@ function applyToolchain(tools, dryRun, options = {}) {
     throw new Error(blocked.map(p => p.reason).join("\n\n"));
   }
 
-  const binDir = join(process.env.HOME ?? "", ".local", "bin");
-  mkdirSync(binDir, { recursive: true, mode: 0o755 });
+  const binDir = ensureBinDir();
   const byName = new Map((tools.install ?? []).map(t => [t.name, t]));
 
   // Installing is a different act on a laptop than in a container. A container
@@ -263,26 +315,14 @@ function applyToolchain(tools, dryRun, options = {}) {
     return plan;
   }
 
-  // Installing a binary somewhere nothing looks is the same as not installing
-  // it. `~/.local/bin` is on PATH by default on a developer workstation and is
-  // NOT on a minimal container, so the toolchain step reported `install bws`,
-  // the file landed at ~/.local/bin/bws mode 755, and the very next step died
-  // with `spawnSync bws ENOENT`.
-  //
-  // This was invisible in every local test because a workstation shell already
-  // exports the directory — the environment doing the hiding was the one used
-  // to verify the fix.
-  //
-  // Prepended, not appended: a pinned-and-checksummed binary must win over
-  // whatever an image happens to ship under the same name.
-  if (!pathContains(binDir)) {
-    process.env.PATH = `${binDir}${delimiter}${process.env.PATH ?? ""}`;
-  }
-
   for (const step of plan) {
     console.log(`  ${step.action.padEnd(8)} ${step.reason}`);
+    // The planner already resolved this entry to the running platform, so use
+    // what it decided rather than looking the raw entry up again. `byName` is
+    // the pre-platform shape and would hand the installer a url that belongs to
+    // whichever platform happened to be written first.
     if (step.action === "install" && !dryRun)
-      installTool(byName.get(step.name), binDir);
+      installTool(step.tool ?? byName.get(step.name), binDir);
   }
   return plan;
 }

package/plugins/lisa/skills/lisa-setup-remote-env/scripts/toolchain.mjs

@@ -100,7 +100,7 @@ function planRequired(tool, found) {
  * @param {{version: string|null, present: boolean}} found Probe result.
  * @returns {{name: string, action: string, reason: string}} The decision.
  */
-function planInstallable(tool, found) {
+function planInstallable(tool, found, pinIsFloor = false) {
   if (!tool.version) {
     return {
       name: tool.name,
@@ -115,6 +115,25 @@ function planInstallable(tool, found) {
       reason: `${tool.name} ${tool.version} already installed`,
     };
   }
+  // On a laptop the pin is a floor, not an equality. A container is disposable
+  // and reproducible by construction, so an exact match is right there. A
+  // developer's machine is shared with every other project they work on, and
+  // installing a pinned binary into ~/.local/bin ahead of a NEWER one already on
+  // PATH is a downgrade this project imposed on all of them — for gh, pinned at
+  // 2.83.0 against a workstation running 2.96.0, that is the likely case rather
+  // than the exotic one.
+  if (
+    pinIsFloor &&
+    found.present &&
+    found.version &&
+    compareVersions(found.version, tool.version) > 0
+  ) {
+    return {
+      name: tool.name,
+      action: "newer",
+      reason: `${tool.name} ${found.version} is newer than the pinned ${tool.version} — leaving it alone`,
+    };
+  }
   return {
     name: tool.name,
     action: "install",
@@ -127,6 +146,72 @@ function planInstallable(tool, found) {
 /** Surfaces a manifest entry may name. */
 const KNOWN_SURFACES = new Set(["local", "remote"]);
 
+/**
+ * The platform key a manifest entry is resolved against.
+ *
+ * `<platform>-<arch>` rather than either alone, because both halves change the
+ * artifact: an Apple Silicon laptop and an Intel one run different builds of the
+ * same release, and so do an arm64 container and an amd64 one.
+ * @param {{platform: string, arch: string}} [runtime] Injectable, for tests.
+ * @returns {string} A key such as "darwin-arm64" or "linux-x64".
+ */
+export function currentPlatform(runtime = process) {
+  return `${runtime.platform}-${runtime.arch}`;
+}
+
+/**
+ * Collapse a manifest entry to the artifact for one platform.
+ *
+ * A download URL is platform-specific and a checksum doubly so, which the
+ * single-URL shape could not express: the only way to stop a laptop being handed
+ * a Linux binary was `surfaces: ["remote"]`, which bought that safety by making
+ * the tool uninstallable on the laptop entirely. So `bws` and `gh` — the two
+ * tools Lisa's own guardrails shell out to — were declared, required, and
+ * unprovisionable on the machine most likely to be missing them.
+ *
+ * A `platforms` map fixes the cause instead of the symptom. `install` lives
+ * inside each block rather than beside it, because the method varies too: gh
+ * publishes a .tar.gz for Linux and a .zip for macOS, so a single install method
+ * would have forced one platform onto an archive kind its vendor does not ship.
+ *
+ * A flat entry is still valid and means "identical everywhere" — true of every
+ * `npm-global` install, which is genuinely platform-independent.
+ * @param {object} tool Manifest entry.
+ * @param {string} [platform] Platform key to resolve for.
+ * @returns {object} The entry with its platform block merged in.
+ */
+export function resolvePlatform(tool, platform = currentPlatform()) {
+  const { platforms } = tool;
+  if (platforms === undefined) return tool;
+  if (
+    typeof platforms !== "object" ||
+    platforms === null ||
+    Array.isArray(platforms)
+  ) {
+    throw new Error(
+      `${tool.name}: platforms must be an object keyed by <platform>-<arch>, ` +
+        `got ${Array.isArray(platforms) ? "an array" : typeof platforms}.\n` +
+        `Omit it when one artifact serves every platform.`
+    );
+  }
+  const block = platforms[platform];
+  if (!block) {
+    const known = Object.keys(platforms).sort().join(", ");
+    throw new Error(
+      `${tool.name}: no pin for ${platform}.\n` +
+        `Declared platforms: ${known || "(none)"}.\n` +
+        `Add a block for ${platform} with its own url and sha256, or drop the ` +
+        `tool from this surface. Guessing an artifact would defeat the ` +
+        `checksum.`
+    );
+  }
+  // The platform block wins over the shared fields, and `platforms` itself is
+  // dropped so a resolved entry is indistinguishable from a flat one — that is
+  // what lets assertPinned and the installers stay unaware of any of this.
+  const { platforms: _discarded, ...shared } = tool;
+  return { ...shared, ...block };
+}
+
 /**
  * Whether a manifest entry applies to the surface being provisioned.
  *
@@ -171,18 +256,48 @@ export function appliesToSurface(tool, surface) {
 
 /**
  * Produce the complete plan for a toolchain manifest.
+ *
+ * Install entries are resolved to the running platform here rather than at
+ * install time, so a tool with no artifact for this machine is reported
+ * alongside every other problem instead of aborting the run at the first one.
+ * An operator fixing a manifest wants the whole list.
+ *
+ * `require` entries are deliberately not resolved: they carry a name and a
+ * minimum version, nothing platform-specific, and inventing a per-platform shape
+ * for them would be ceremony with no artifact behind it.
  * @param {{require?: object[], install?: object[]}} tools Manifest.
  * @param {(name: string) => {version: string|null, present: boolean}} probe Version probe.
- * @returns {Array<{name: string, action: string, reason: string}>} Ordered decisions.
+ * @param {string} [surface] Surface being provisioned.
+ * @param {string} [platform] Platform key to resolve install entries against.
+ * @returns {Array<{name: string, action: string, reason: string, tool?: object}>} Ordered decisions.
  */
-export function planToolchain(tools, probe, surface = "remote") {
+export function planToolchain(
+  tools,
+  probe,
+  surface = "remote",
+  platform = currentPlatform()
+) {
   const plan = [];
   for (const tool of tools.require ?? [])
     if (appliesToSurface(tool, surface))
       plan.push(planRequired(tool, probe(tool.name)));
-  for (const tool of tools.install ?? [])
-    if (appliesToSurface(tool, surface))
-      plan.push(planInstallable(tool, probe(tool.name)));
+  for (const tool of tools.install ?? []) {
+    if (!appliesToSurface(tool, surface)) continue;
+    let resolved;
+    try {
+      resolved = resolvePlatform(tool, platform);
+    } catch (err) {
+      plan.push({ name: tool.name, action: "invalid", reason: err.message });
+      continue;
+    }
+    // The resolved entry travels with the decision so the installer never has to
+    // resolve a second time — two resolutions are two chances to disagree, and
+    // the one that installs would be the one nothing tested.
+    plan.push({
+      ...planInstallable(resolved, probe(tool.name), surface === "local"),
+      tool: resolved,
+    });
+  }
   return plan;
 }
 
@@ -195,6 +310,17 @@ export function planToolchain(tools, probe, surface = "remote") {
  * @param {object} tool Manifest entry.
  */
 export function assertPinned(tool) {
+  // An unresolved entry reaching here means a caller skipped resolvePlatform and
+  // is about to read a url and sha256 that belong to no platform in particular.
+  // Refusing is the point: the failure this whole change exists to prevent is
+  // exactly "downloaded the wrong platform's artifact", and a silent pass here
+  // would reintroduce it one call site at a time.
+  if (tool.platforms !== undefined) {
+    throw new Error(
+      `${tool.name}: platform-specific entry was not resolved before install.\n` +
+        `Call resolvePlatform() first — the shared fields alone do not name an artifact.`
+    );
+  }
   // Both archive kinds carry the same obligation, and differ only in how they
   // are unpacked. gh, for one, publishes no zip for Linux at all — only .deb,
   // .rpm and .tar.gz — so a zip-only installer could not pin the CLI that

package/plugins/lisa-agy/commands/lisa/setup/local-env.md

@@ -0,0 +1,7 @@
+---
+description: "Bring this machine in line with the toolchain the project declares. Reports every tool in remoteEnv.tools that is missing, outdated, or unpinned for this platform, and installs the missing ones into ~/.local/bin from the same pinned, checksummed entries the remote surfaces use — but only when asked with --install-tools. A newer tool already on PATH is left alone."
+allowed-tools: ["Skill"]
+argument-hint: "[--install-tools] [--json]"
+---
+
+Use the /lisa-setup-local-env skill to report and optionally install the project's declared toolchain on this machine. $ARGUMENTS

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.327.0",
+  "version": "2.328.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-agy/skills/lisa-detect-tooling/SKILL.md

@@ -46,7 +46,27 @@ What genuinely differs is **consent**, not the list:
 
 Omitting `surfaces` means every surface, because that is true of most tools and the cost of forgetting should be a redundant check rather than a silent absence.
 
-A platform-specific pin is the exception worth knowing: a Linux release archive must be `surfaces: ["remote"]`, with a matching `require` entry for `local`, so a laptop asserts the tool without being offered a binary it cannot run.
+Platform differences are **not** expressed with `surfaces`. A downloaded tool declares a
+`platforms` map keyed `<platform>-<arch>`, each block carrying its own `install` method, `url`,
+and `sha256`:
+
+```json
+"platforms": {
+  "linux-x64":    { "install": "release-tar", "url": "...", "sha256": "..." },
+  "darwin-arm64": { "install": "release-zip", "url": "...", "sha256": "..." }
+}
+```
+
+The method lives inside the block because it varies — gh ships a `.tar.gz` for Linux and a
+`.zip` for macOS. A flat entry means one artifact serves everything, which is true of
+`npm-global` and nothing else.
+
+This replaces an earlier convention worth naming, because its residue may still be in a
+manifest you read: a Linux archive used to be marked `surfaces: ["remote"]` with a bare
+`require` entry for `local`, so a laptop asserted the tool without being offered a binary it
+could not run. That kept the wrong binary off the laptop by making the tool uninstallable
+there — which is how `bws` and `gh`, the two CLIs Lisa's own guardrails shell out to, came to
+be required on developer machines and provisionable only in containers.
 
 ## Usage