From 58cdd561dafabcef239563b3716190f0739cdf8c Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Wed, 21 Oct 2026 08:22:21 -0500
Subject: [PATCH 01/27] feat(cli): ship standalone binaries for installs
 without Node.js

Build per-platform `openspec` executables with `bun build --compile`,
smoke-test them on Linux/macOS/Windows in CI, and attach every target to
each published GitHub release with SHA256SUMS.

The binary has no package directory, so the build bundles package.json
(createRequire calls become static requires) and embeds schemas/, which
the entry writes to a content-hashed data-dir folder on first run.

Refs #2055

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/binaries.yml            | 102 ++++++++++++++++++++++
 .gitignore                                |   4 +
 scripts/README.md                         |  18 ++++
 scripts/binary/build.mjs                  |  60 +++++++++++++
 scripts/binary/entry.mjs                  |  38 ++++++++
 scripts/binary/smoke.sh                   |  33 +++++++
 src/core/artifact-graph/resolver.ts       |  12 +++
 test/core/artifact-graph/resolver.test.ts |  19 +++-
 8 files changed, 285 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/binaries.yml
 create mode 100644 scripts/binary/build.mjs
 create mode 100644 scripts/binary/entry.mjs
 create mode 100755 scripts/binary/smoke.sh

diff --git a/.github/workflows/binaries.yml b/.github/workflows/binaries.yml
new file mode 100644
index 0000000000..da29853d53
--- /dev/null
+++ b/.github/workflows/binaries.yml
@@ -0,0 +1,102 @@
+name: Binaries
+
+# Standalone `openspec` executables for people without Node.js (#2055).
+# Pull requests smoke-test the host binary on each OS; a published release gets
+# every platform's binary attached, cross-compiled from one Linux runner.
+on:
+  pull_request:
+    branches: [main]
+  merge_group:
+    branches: [main]
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing release tag to build and attach binaries to
+        required: true
+
+permissions:
+  contents: read
+
+concurrency:
+  group: binaries-${{ github.ref }}-${{ inputs.tag }}
+  cancel-in-progress: true
+
+env:
+  BUN_VERSION: '1.4.3'
+
+jobs:
+  smoke:
+    name: Smoke (${{ matrix.os }})
+    if: github.event_name == 'pull_request' || github.event_name == 'merge_group'
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '20.19.0'
+          cache: 'pnpm'
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - run: bun scripts/binary/build.mjs
+      - name: Smoke-test the binary
+        run: bash scripts/binary/smoke.sh dist-bin/openspec-*
+
+  release:
+    name: Attach to release
+    if: github.repository == 'Fission-AI/OpenSpec' && (github.event_name == 'release' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: write # upload release assets
+    env:
+      TAG: ${{ github.event.release.tag_name || inputs.tag }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.TAG }}
+          persist-credentials: false
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '20.19.0'
+          cache: 'pnpm'
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - run: >-
+          bun scripts/binary/build.mjs
+          bun-linux-x64 bun-linux-arm64 bun-darwin-x64 bun-darwin-arm64 bun-windows-x64
+      # Also checks the binary reports the version the tag names, so assets
+      # never land on the wrong release.
+      - name: Smoke-test the Linux binary
+        run: |
+          bash scripts/binary/smoke.sh dist-bin/openspec-linux-x64
+          [[ "$TAG" == *"$(dist-bin/openspec-linux-x64 --version)" ]] || {
+            echo "::error::Binary version does not match release tag $TAG"
+            exit 1
+          }
+      - name: Upload
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          cd dist-bin
+          sha256sum openspec-* > SHA256SUMS
+          gh release upload "$TAG" openspec-* SHA256SUMS --clobber --repo "$GITHUB_REPOSITORY"
diff --git a/.gitignore b/.gitignore
index 1fb5c4a26a..7ff3e1ecd3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -166,3 +166,7 @@ opencode.json
 
 # Cursor
 .cursor/
+
+# Standalone binaries (scripts/binary/build.mjs); Bun can leave .bun-build temp files
+dist-bin/
+*.bun-build
diff --git a/scripts/README.md b/scripts/README.md
index 0fb25f7747..a56796f36e 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -70,3 +70,21 @@ test file mid-suite.
 ## pack-version-check.mjs
 
 Validates package version consistency before publishing.
+
+## binary/
+
+Builds standalone `openspec` executables with Bun, for people without Node.js.
+CI smoke-tests them on every PR and attaches them to each published release
+(`.github/workflows/binaries.yml`).
+
+**Usage**:
+```bash
+pnpm build
+bun scripts/binary/build.mjs                  # this machine → dist-bin/
+bun scripts/binary/build.mjs bun-linux-x64    # cross-compile any Bun target
+bash scripts/binary/smoke.sh dist-bin/openspec-<os>-<arch>
+```
+
+The binary has no package directory, so `build.mjs` bundles `package.json`
+and embeds `schemas/`, which `entry.mjs` writes to
+`<data dir>/binary-schemas/<content hash>/` on first run.
diff --git a/scripts/binary/build.mjs b/scripts/binary/build.mjs
new file mode 100644
index 0000000000..f1fef0aa76
--- /dev/null
+++ b/scripts/binary/build.mjs
@@ -0,0 +1,60 @@
+#!/usr/bin/env bun
+// Builds standalone `openspec` executables with `bun build --compile`, so the
+// CLI can be installed without Node.js. Run `pnpm build` first.
+//
+//   bun scripts/binary/build.mjs                    # host platform
+//   bun scripts/binary/build.mjs bun-linux-x64 ...  # cross-compile
+//
+// Output: dist-bin/openspec-<os>-<arch>[.exe]
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = path.resolve(import.meta.dir, '../..');
+const targets = process.argv.slice(2);
+if (targets.length === 0) targets.push(`bun-${process.platform}-${process.arch}`);
+
+// Node resolves `createRequire(import.meta.url)(...)` at runtime against the
+// package directory, which a binary does not have. Turning those calls into
+// plain `require` lets Bun bundle package.json and cross-spawn instead.
+const staticRequire = {
+  name: 'static-require',
+  setup(build) {
+    build.onLoad({ filter: /[\\/]dist[\\/].*\.js$/ }, async (args) => {
+      const contents = (await Bun.file(args.path).text())
+        .replace(/const require = createRequire\(import\.meta\.url\);/g, '')
+        .replaceAll('createRequire(import.meta.url)(', 'require(');
+      // A new call shape would otherwise ship a binary that fails at runtime.
+      if (contents.includes('createRequire(import.meta.url)')) {
+        throw new Error(`Unhandled createRequire(import.meta.url) in ${args.path}`);
+      }
+      return { contents, loader: 'js' };
+    });
+  },
+};
+
+const files = {};
+const schemasDir = path.join(root, 'schemas');
+for (const entry of fs.readdirSync(schemasDir, { recursive: true, withFileTypes: true })) {
+  if (!entry.isFile()) continue;
+  const file = path.join(entry.parentPath, entry.name);
+  files[path.relative(schemasDir, file).split(path.sep).join('/')] = fs.readFileSync(file, 'utf8');
+}
+const hash = createHash('sha256').update(JSON.stringify(files)).digest('hex').slice(0, 16);
+
+for (const target of targets) {
+  const name = target.replace(/^bun-/, 'openspec-');
+  const outfile = path.join(root, 'dist-bin', target.includes('windows') ? `${name}.exe` : name);
+  const result = await Bun.build({
+    entrypoints: [path.join(import.meta.dir, 'entry.mjs')],
+    compile: { target, outfile },
+    minify: true,
+    define: { OPENSPEC_EMBEDDED_SCHEMAS: JSON.stringify({ hash, files }) },
+    plugins: [staticRequire],
+  });
+  if (!result.success) {
+    for (const log of result.logs) console.error(log);
+    process.exit(1);
+  }
+  console.log(`Built ${path.relative(root, outfile)}`);
+}
diff --git a/scripts/binary/entry.mjs b/scripts/binary/entry.mjs
new file mode 100644
index 0000000000..ed5462bae0
--- /dev/null
+++ b/scripts/binary/entry.mjs
@@ -0,0 +1,38 @@
+// Entry point of the standalone `openspec` binary built by build.mjs. The
+// binary has no package directory on disk, so the built-in schemas are
+// embedded at build time and written to a real directory before the CLI runs.
+import fs from 'node:fs';
+import path from 'node:path';
+import { getGlobalDataDir } from '../../dist/core/global-config.js';
+import { setPackageSchemasDir } from '../../dist/core/artifact-graph/resolver.js';
+
+// Replaced by build.mjs: { hash, files: { 'spec-driven/schema.yaml': '...' } }
+const { hash, files } = OPENSPEC_EMBEDDED_SCHEMAS;
+
+// Keyed by content, so a directory that exists is complete and current: it is
+// only ever created by an atomic rename of a fully written one.
+function extractSchemas() {
+  const dir = path.join(getGlobalDataDir(), 'binary-schemas', hash);
+  if (fs.existsSync(dir)) return dir;
+
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  const tmp = fs.mkdtempSync(`${dir}.tmp-`);
+  for (const [relativePath, content] of Object.entries(files)) {
+    const file = path.join(tmp, relativePath);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content);
+  }
+  try {
+    fs.renameSync(tmp, dir);
+  } catch (error) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    // Another process finished first; its copy is identical.
+    if (!fs.existsSync(dir)) throw error;
+  }
+  return dir;
+}
+
+setPackageSchemasDir(extractSchemas());
+// No runCli() call: in a compiled binary process.argv[1] is the executable's
+// own module path, so the CLI's "run when executed directly" check fires.
+await import('../../dist/cli/index.js');
diff --git a/scripts/binary/smoke.sh b/scripts/binary/smoke.sh
new file mode 100755
index 0000000000..88126ed947
--- /dev/null
+++ b/scripts/binary/smoke.sh
@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Smoke-tests a standalone binary from build.mjs: version, built-in schemas,
+# and a real init → change → status → instructions run in a scratch project.
+#
+#   bash scripts/binary/smoke.sh dist-bin/openspec-<os>-<arch>
+set -euo pipefail
+
+bin=$(cd "$(dirname "$1")" && pwd)/$(basename "$1")
+expected=$(sed -nE 's/^  "version": "([^"]+)".*/\1/p' "$(dirname "$0")/../../package.json")
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+
+# Keep the run off the user's real config and data, and offline.
+export XDG_CONFIG_HOME="$work/config" XDG_DATA_HOME="$work/data"
+export OPENSPEC_TELEMETRY=0 OPENSPEC_NO_UPDATE_CHECK=1 NO_COLOR=1
+mkdir "$work/project" && cd "$work/project"
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+version=$("$bin" --version)
+[ "$version" = "$expected" ] || fail "--version printed '$version', expected '$expected'"
+
+"$bin" schemas --json | grep -q '"source": "package"' || fail "built-in schema not found"
+"$bin" init --tools claude > /dev/null
+[ -f openspec/config.yaml ] || fail "init did not write openspec/config.yaml"
+"$bin" new change demo > /dev/null
+"$bin" status --change demo --json | grep -q '"schemaName": "spec-driven"' || fail "status did not resolve the schema"
+"$bin" instructions proposal --change demo | grep -q '<template>' || fail "instructions missing the proposal template"
+
+# The CLI must run once per invocation, not once per entry point.
+[ "$("$bin" schemas | grep -c 'Available schemas')" = 1 ] || fail "CLI ran more than once"
+
+echo "OK: $bin ($version)"
diff --git a/src/core/artifact-graph/resolver.ts b/src/core/artifact-graph/resolver.ts
index 48295086d7..7534cfde30 100644
--- a/src/core/artifact-graph/resolver.ts
+++ b/src/core/artifact-graph/resolver.ts
@@ -20,11 +20,23 @@ export class SchemaLoadError extends Error {
   }
 }
 
+let packageSchemasDirOverride: string | undefined;
+
+/**
+ * Points the built-in schemas at another directory. The standalone binary has
+ * no package directory on disk, so it extracts its embedded schemas and calls
+ * this before the CLI runs.
+ */
+export function setPackageSchemasDir(dir: string): void {
+  packageSchemasDirOverride = dir;
+}
+
 /**
  * Gets the package's built-in schemas directory path.
  * Uses import.meta.url to resolve relative to the current module.
  */
 export function getPackageSchemasDir(): string {
+  if (packageSchemasDirOverride) return packageSchemasDirOverride;
   const currentFile = fileURLToPath(import.meta.url);
   // Navigate from dist/core/artifact-graph/ to package root's schemas/
   return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');
diff --git a/test/core/artifact-graph/resolver.test.ts b/test/core/artifact-graph/resolver.test.ts
index 053529c355..a90881e756 100644
--- a/test/core/artifact-graph/resolver.test.ts
+++ b/test/core/artifact-graph/resolver.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
@@ -34,6 +34,23 @@ describe('artifact-graph/resolver', () => {
       expect(typeof schemasDir).toBe('string');
       expect(schemasDir.length).toBeGreaterThan(0);
     });
+
+    it('serves built-in schemas from the directory the standalone binary sets', async () => {
+      // A fresh module copy, so the override cannot leak into other tests.
+      vi.resetModules();
+      process.env.XDG_DATA_HOME = tempDir; // no user overrides in the way
+      const resolver = await import('../../../src/core/artifact-graph/resolver.js');
+      const packageDir = path.join(tempDir, 'extracted');
+      fs.cpSync(path.join(getPackageSchemasDir(), 'spec-driven'), path.join(packageDir, 'spec-driven'), {
+        recursive: true,
+      });
+
+      resolver.setPackageSchemasDir(packageDir);
+
+      expect(resolver.getPackageSchemasDir()).toBe(packageDir);
+      expect(resolver.getSchemaDir('spec-driven')).toBe(path.join(packageDir, 'spec-driven'));
+      expect(resolver.listSchemas()).toContain('spec-driven');
+    });
   });
 
   describe('getUserSchemasDir', () => {

From fb522f5ae0c6f389b740a972ecf8a49da68424a8 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Wed, 21 Oct 2026 08:57:35 -0500
Subject: [PATCH 02/27] fix(cli): make the standalone binary survive damaged or
 unwritable data dirs

- Extract the built-in schemas lazily, only when a command needs them, so
  --version and list work even when nothing is writable.
- Verify the extracted copy on every start and replace it if it was edited,
  partly deleted, or replaced by a file, instead of failing forever.
- Fall back to a private temp copy when the data dir is read-only, and fail
  with a plain CLI error when no location is writable.
- smoke.sh now runs the binary renamed, from a path with a space and
  non-ASCII characters, and checks the repair path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/binary/entry.mjs                  | 69 +++++++++++++++++++----
 scripts/binary/smoke.sh                   | 17 +++++-
 src/core/artifact-graph/resolver.ts       | 12 ++--
 test/core/artifact-graph/resolver.test.ts |  7 ++-
 4 files changed, 83 insertions(+), 22 deletions(-)

diff --git a/scripts/binary/entry.mjs b/scripts/binary/entry.mjs
index ed5462bae0..328b266ba4 100644
--- a/scripts/binary/entry.mjs
+++ b/scripts/binary/entry.mjs
@@ -2,6 +2,7 @@
 // binary has no package directory on disk, so the built-in schemas are
 // embedded at build time and written to a real directory before the CLI runs.
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { getGlobalDataDir } from '../../dist/core/global-config.js';
 import { setPackageSchemasDir } from '../../dist/core/artifact-graph/resolver.js';
@@ -9,30 +10,74 @@ import { setPackageSchemasDir } from '../../dist/core/artifact-graph/resolver.js
 // Replaced by build.mjs: { hash, files: { 'spec-driven/schema.yaml': '...' } }
 const { hash, files } = OPENSPEC_EMBEDDED_SCHEMAS;
 
-// Keyed by content, so a directory that exists is complete and current: it is
-// only ever created by an atomic rename of a fully written one.
-function extractSchemas() {
-  const dir = path.join(getGlobalDataDir(), 'binary-schemas', hash);
-  if (fs.existsSync(dir)) return dir;
+// Checked on every start, so a copy someone edited or partly deleted is
+// replaced instead of breaking the CLI until they find and remove it.
+function isIntact(dir) {
+  try {
+    return Object.entries(files).every(
+      ([relativePath, content]) => fs.readFileSync(path.join(dir, relativePath), 'utf8') === content
+    );
+  } catch {
+    return false;
+  }
+}
 
-  fs.mkdirSync(path.dirname(dir), { recursive: true });
-  const tmp = fs.mkdtempSync(`${dir}.tmp-`);
+function writeFiles(dir) {
   for (const [relativePath, content] of Object.entries(files)) {
-    const file = path.join(tmp, relativePath);
+    const file = path.join(dir, relativePath);
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, content);
   }
+  return dir;
+}
+
+// Keyed by content and created only by an atomic rename of a fully written
+// copy, so concurrent first runs never see a half-written directory.
+function extractToDataDir() {
+  const dir = path.join(getGlobalDataDir(), 'binary-schemas', hash);
+  if (isIntact(dir)) return dir;
+
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  const tmp = writeFiles(fs.mkdtempSync(`${dir}.tmp-`));
+  if (fs.existsSync(dir)) {
+    // A rename cannot replace a non-empty directory, so move the damaged
+    // copy aside first. Another process may already have done it.
+    try {
+      fs.renameSync(dir, `${tmp}-stale`);
+    } catch {}
+    fs.rmSync(`${tmp}-stale`, { recursive: true, force: true });
+  }
   try {
     fs.renameSync(tmp, dir);
   } catch (error) {
     fs.rmSync(tmp, { recursive: true, force: true });
     // Another process finished first; its copy is identical.
-    if (!fs.existsSync(dir)) throw error;
+    if (!isIntact(dir)) throw error;
   }
   return dir;
 }
 
-setPackageSchemasDir(extractSchemas());
-// No runCli() call: in a compiled binary process.argv[1] is the executable's
-// own module path, so the CLI's "run when executed directly" check fires.
+function extractSchemas() {
+  try {
+    return extractToDataDir();
+  } catch {
+    // Read-only home, locked-down CI: use a private copy for this run only.
+    const dir = writeFiles(fs.mkdtempSync(path.join(os.tmpdir(), 'openspec-schemas-')));
+    process.on('exit', () => fs.rmSync(dir, { recursive: true, force: true }));
+    return dir;
+  }
+}
+
+let schemasDir;
+setPackageSchemasDir(() => {
+  try {
+    schemasDir ??= extractSchemas();
+  } catch (error) {
+    throw new Error(`Could not write the built-in schemas to disk: ${error.message}`);
+  }
+  return schemasDir;
+});
+// No runCli() call: process.argv[1] and import.meta.url are both fixed at
+// build time to the same virtual path, so the CLI's "run when executed
+// directly" check always fires, whatever the user renames the binary to.
 await import('../../dist/cli/index.js');
diff --git a/scripts/binary/smoke.sh b/scripts/binary/smoke.sh
index 88126ed947..2d117bacdb 100755
--- a/scripts/binary/smoke.sh
+++ b/scripts/binary/smoke.sh
@@ -5,13 +5,20 @@
 #   bash scripts/binary/smoke.sh dist-bin/openspec-<os>-<arch>
 set -euo pipefail
 
-bin=$(cd "$(dirname "$1")" && pwd)/$(basename "$1")
 expected=$(sed -nE 's/^  "version": "([^"]+)".*/\1/p' "$(dirname "$0")/../../package.json")
 work=$(mktemp -d)
 trap 'rm -rf "$work"' EXIT
 
+# Run it from, and keep its data under, paths with a space and non-ASCII
+# characters, as on a machine whose user name has them. Renamed too, as a
+# user would after downloading.
+mkdir -p "$work/bin dir ü"
+bin="$work/bin dir ü/openspec"
+case "$1" in *.exe) bin="$bin.exe" ;; esac
+cp "$1" "$bin"
+
 # Keep the run off the user's real config and data, and offline.
-export XDG_CONFIG_HOME="$work/config" XDG_DATA_HOME="$work/data"
+export XDG_CONFIG_HOME="$work/config ü" XDG_DATA_HOME="$work/data ü"
 export OPENSPEC_TELEMETRY=0 OPENSPEC_NO_UPDATE_CHECK=1 NO_COLOR=1
 mkdir "$work/project" && cd "$work/project"
 
@@ -27,7 +34,11 @@ version=$("$bin" --version)
 "$bin" status --change demo --json | grep -q '"schemaName": "spec-driven"' || fail "status did not resolve the schema"
 "$bin" instructions proposal --change demo | grep -q '<template>' || fail "instructions missing the proposal template"
 
+# A damaged copy of the extracted schemas is repaired, not trusted.
+find "$XDG_DATA_HOME" -path '*binary-schemas*' -name proposal.md -delete
+"$bin" instructions proposal --change demo | grep -q '<template>' || fail "damaged schema copy was not repaired"
+
 # The CLI must run once per invocation, not once per entry point.
 [ "$("$bin" schemas | grep -c 'Available schemas')" = 1 ] || fail "CLI ran more than once"
 
-echo "OK: $bin ($version)"
+echo "OK: $(basename "$1") ($version)"
diff --git a/src/core/artifact-graph/resolver.ts b/src/core/artifact-graph/resolver.ts
index 7534cfde30..cef92f5750 100644
--- a/src/core/artifact-graph/resolver.ts
+++ b/src/core/artifact-graph/resolver.ts
@@ -20,15 +20,15 @@ export class SchemaLoadError extends Error {
   }
 }
 
-let packageSchemasDirOverride: string | undefined;
+let packageSchemasDirOverride: (() => string) | undefined;
 
 /**
  * Points the built-in schemas at another directory. The standalone binary has
- * no package directory on disk, so it extracts its embedded schemas and calls
- * this before the CLI runs.
+ * no package directory on disk, so it passes a function that extracts its
+ * embedded schemas; it runs only when a command first needs them.
  */
-export function setPackageSchemasDir(dir: string): void {
-  packageSchemasDirOverride = dir;
+export function setPackageSchemasDir(resolveDir: () => string): void {
+  packageSchemasDirOverride = resolveDir;
 }
 
 /**
@@ -36,7 +36,7 @@ export function setPackageSchemasDir(dir: string): void {
  * Uses import.meta.url to resolve relative to the current module.
  */
 export function getPackageSchemasDir(): string {
-  if (packageSchemasDirOverride) return packageSchemasDirOverride;
+  if (packageSchemasDirOverride) return packageSchemasDirOverride();
   const currentFile = fileURLToPath(import.meta.url);
   // Navigate from dist/core/artifact-graph/ to package root's schemas/
   return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');
diff --git a/test/core/artifact-graph/resolver.test.ts b/test/core/artifact-graph/resolver.test.ts
index a90881e756..ba3c009121 100644
--- a/test/core/artifact-graph/resolver.test.ts
+++ b/test/core/artifact-graph/resolver.test.ts
@@ -45,7 +45,12 @@ describe('artifact-graph/resolver', () => {
         recursive: true,
       });
 
-      resolver.setPackageSchemasDir(packageDir);
+      let calls = 0;
+      resolver.setPackageSchemasDir(() => {
+        calls++;
+        return packageDir;
+      });
+      expect(calls).toBe(0); // nothing is extracted until a command needs it
 
       expect(resolver.getPackageSchemasDir()).toBe(packageDir);
       expect(resolver.getSchemaDir('spec-driven')).toBe(path.join(packageDir, 'spec-driven'));

From a1bb7d47c2131c92b894528a74769ff04af01d70 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Wed, 21 Oct 2026 08:57:35 -0500
Subject: [PATCH 03/27] feat(cli): verify every binary on its own platform and
 add an installer

- Ship 8 assets: glibc and musl Linux, macOS, and Windows on x64 and arm64.
  x64 uses Bun's baseline builds, which do not require AVX2.
- CI builds once, then smoke-tests each asset on a native runner (Alpine
  3.17 for musl, plus PowerShell and cmd on Windows), and attaches assets to
  a release only when all pass. Release builds skip dependency caches.
- install.sh picks the asset for the machine (arch, musl, Rosetta), checks
  it against SHA256SUMS, and avoids the macOS quarantine that kills
  unnotarized browser downloads.
- Build unminified so crash traces from binary users name real functions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/binaries.yml | 164 +++++++++++++++++++++++----------
 scripts/binary/build.mjs       |  46 +++++++--
 scripts/binary/install.sh      |  82 +++++++++++++++++
 3 files changed, 234 insertions(+), 58 deletions(-)
 create mode 100644 scripts/binary/install.sh

diff --git a/.github/workflows/binaries.yml b/.github/workflows/binaries.yml
index da29853d53..c9186587d2 100644
--- a/.github/workflows/binaries.yml
+++ b/.github/workflows/binaries.yml
@@ -1,8 +1,8 @@
 name: Binaries
 
 # Standalone `openspec` executables for people without Node.js (#2055).
-# Pull requests smoke-test the host binary on each OS; a published release gets
-# every platform's binary attached, cross-compiled from one Linux runner.
+# One Linux job cross-compiles every asset; each is then tested on its own OS
+# and CPU, and only then attached to a published release.
 on:
   pull_request:
     branches: [main]
@@ -21,82 +21,150 @@ permissions:
 
 concurrency:
   group: binaries-${{ github.ref }}-${{ inputs.tag }}
-  cancel-in-progress: true
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 env:
   BUN_VERSION: '1.4.3'
+  # The release's tag, or the commit under test.
+  REF: ${{ github.event.release.tag_name || inputs.tag || github.sha }}
 
 jobs:
-  smoke:
-    name: Smoke (${{ matrix.os }})
-    if: github.event_name == 'pull_request' || github.event_name == 'merge_group'
-    runs-on: ${{ matrix.os }}
+  build:
+    name: Build
+    runs-on: ubuntu-latest
     timeout-minutes: 15
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-    defaults:
-      run:
-        shell: bash
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
+          ref: ${{ env.REF }}
           persist-credentials: false
       - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      # No dependency caches: this job builds release binaries, and a cache
+      # written by a pull request run could poison them.
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: '20.19.0'
-          cache: 'pnpm'
+          package-manager-cache: false
       - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version: ${{ env.BUN_VERSION }}
+          no-cache: true
       - run: pnpm install --frozen-lockfile
       - run: pnpm run build
-      - run: bun scripts/binary/build.mjs
-      - name: Smoke-test the binary
-        run: bash scripts/binary/smoke.sh dist-bin/openspec-*
+      - run: bun scripts/binary/build.mjs --all
+      # The binaries report package.json's version (smoke.sh checks), so this
+      # keeps assets off a release they do not belong to.
+      - name: Check the version matches the release tag
+        if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+        run: |
+          version=$(node -p "require('./package.json').version")
+          [[ "$REF" == *"$version" ]] || {
+            echo "::error::package.json version $version does not match tag $REF"
+            exit 1
+          }
+      - name: Checksums and installer
+        run: |
+          cd dist-bin
+          sha256sum openspec-* > SHA256SUMS
+          cp ../scripts/binary/install.sh .
+          cat SHA256SUMS
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: binaries
+          path: dist-bin/
+          if-no-files-found: error
+          retention-days: 7
+
+  verify:
+    name: Verify ${{ matrix.asset }}
+    needs: build
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { asset: linux-x64, os: ubuntu-latest }
+          - { asset: linux-arm64, os: ubuntu-24.04-arm }
+          # Oldest Alpine whose libstdc++ the musl build links against.
+          - { asset: linux-x64-musl, os: ubuntu-latest, alpine: '3.17' }
+          - { asset: linux-arm64-musl, os: ubuntu-24.04-arm, alpine: '3.17' }
+          - { asset: darwin-x64, os: macos-15-intel }
+          - { asset: darwin-arm64, os: macos-latest }
+          - { asset: windows-x64, os: windows-latest }
+          - { asset: windows-arm64, os: windows-11-arm }
+    defaults:
+      run:
+        shell: bash
+    env:
+      ASSET: ${{ matrix.asset }}
+      ALPINE: ${{ matrix.alpine }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.REF }}
+          persist-credentials: false
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: binaries
+          path: dist-bin
+      - run: chmod +x dist-bin/openspec-*
+
+      - name: Smoke test
+        run: |
+          if [ -n "$ALPINE" ]; then
+            docker run --rm -v "$PWD:/src" -w /src "alpine:$ALPINE" sh -c \
+              "apk add --no-cache bash libstdc++ libgcc >/dev/null && bash scripts/binary/smoke.sh dist-bin/openspec-$ASSET"
+          elif [ "$RUNNER_OS" = Windows ]; then
+            bash scripts/binary/smoke.sh "dist-bin/openspec-$ASSET.exe"
+          else
+            bash scripts/binary/smoke.sh "dist-bin/openspec-$ASSET"
+          fi
+
+      - name: Run from PowerShell and cmd
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $exe = "dist-bin\openspec-$env:ASSET.exe"
+          & $exe --version
+          if ($LASTEXITCODE -ne 0) { exit 1 }
+          cmd /c "$exe --version"
+          if ($LASTEXITCODE -ne 0) { exit 1 }
+
+      # Serves this build as a release and checks the installer picks exactly
+      # this asset on this machine, verifies it, and installs a working copy.
+      - name: Install script
+        if: runner.os != 'Windows'
+        run: |
+          python3 -m http.server 8765 --directory dist-bin >/dev/null 2>&1 &
+          for _ in $(seq 20); do curl -sf -o /dev/null http://127.0.0.1:8765/SHA256SUMS && break; sleep 0.5; done
+          if [ -n "$ALPINE" ]; then
+            docker run --rm --network host -v "$PWD/dist-bin:/dist:ro" "alpine:$ALPINE" sh -c \
+              "apk add --no-cache libstdc++ libgcc >/dev/null &&
+               OPENSPEC_DOWNLOAD_URL=http://127.0.0.1:8765 OPENSPEC_INSTALL_DIR=/opt/bin sh /dist/install.sh &&
+               cmp /opt/bin/openspec /dist/openspec-$ASSET"
+          else
+            OPENSPEC_DOWNLOAD_URL=http://127.0.0.1:8765 OPENSPEC_INSTALL_DIR="$RUNNER_TEMP/bin" sh dist-bin/install.sh
+            cmp "$RUNNER_TEMP/bin/openspec" "dist-bin/openspec-$ASSET"
+          fi
 
   release:
     name: Attach to release
+    needs: verify
     if: github.repository == 'Fission-AI/OpenSpec' && (github.event_name == 'release' || github.event_name == 'workflow_dispatch')
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 10
     permissions:
       contents: write # upload release assets
-    env:
-      TAG: ${{ github.event.release.tag_name || inputs.tag }}
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          ref: ${{ env.TAG }}
-          persist-credentials: false
-      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
         with:
-          node-version: '20.19.0'
-          cache: 'pnpm'
-      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
-        with:
-          bun-version: ${{ env.BUN_VERSION }}
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm run build
-      - run: >-
-          bun scripts/binary/build.mjs
-          bun-linux-x64 bun-linux-arm64 bun-darwin-x64 bun-darwin-arm64 bun-windows-x64
-      # Also checks the binary reports the version the tag names, so assets
-      # never land on the wrong release.
-      - name: Smoke-test the Linux binary
-        run: |
-          bash scripts/binary/smoke.sh dist-bin/openspec-linux-x64
-          [[ "$TAG" == *"$(dist-bin/openspec-linux-x64 --version)" ]] || {
-            echo "::error::Binary version does not match release tag $TAG"
-            exit 1
-          }
+          name: binaries
+          path: dist-bin
       - name: Upload
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
           cd dist-bin
-          sha256sum openspec-* > SHA256SUMS
-          gh release upload "$TAG" openspec-* SHA256SUMS --clobber --repo "$GITHUB_REPOSITORY"
+          sha256sum --check SHA256SUMS
+          gh release upload "$REF" openspec-* SHA256SUMS install.sh --clobber --repo "$GITHUB_REPOSITORY"
diff --git a/scripts/binary/build.mjs b/scripts/binary/build.mjs
index f1fef0aa76..9fdb38ac24 100644
--- a/scripts/binary/build.mjs
+++ b/scripts/binary/build.mjs
@@ -2,17 +2,42 @@
 // Builds standalone `openspec` executables with `bun build --compile`, so the
 // CLI can be installed without Node.js. Run `pnpm build` first.
 //
-//   bun scripts/binary/build.mjs                    # host platform
-//   bun scripts/binary/build.mjs bun-linux-x64 ...  # cross-compile
+//   bun scripts/binary/build.mjs                  # this machine
+//   bun scripts/binary/build.mjs --all            # every release asset
+//   bun scripts/binary/build.mjs linux-x64-musl   # named assets
 //
-// Output: dist-bin/openspec-<os>-<arch>[.exe]
+// Output: dist-bin/openspec-<asset>[.exe]
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
+// Release asset → Bun target. x64 uses Bun's "baseline" builds, which drop
+// the AVX2 requirement of the default ones so pre-2013 CPUs and some VMs work.
+// The -musl assets are for Alpine and other non-glibc Linux.
+export const ASSETS = {
+  'linux-x64': 'bun-linux-x64-baseline',
+  'linux-arm64': 'bun-linux-arm64',
+  'linux-x64-musl': 'bun-linux-x64-musl-baseline',
+  'linux-arm64-musl': 'bun-linux-arm64-musl',
+  'darwin-x64': 'bun-darwin-x64-baseline',
+  'darwin-arm64': 'bun-darwin-arm64',
+  'windows-x64': 'bun-windows-x64-baseline',
+  'windows-arm64': 'bun-windows-arm64',
+};
+
 const root = path.resolve(import.meta.dir, '../..');
-const targets = process.argv.slice(2);
-if (targets.length === 0) targets.push(`bun-${process.platform}-${process.arch}`);
+const args = process.argv.slice(2);
+const assets = args.includes('--all')
+  ? Object.keys(ASSETS)
+  : args.length > 0
+    ? args
+    : [`${process.platform === 'win32' ? 'windows' : process.platform}-${process.arch}`];
+for (const asset of assets) {
+  if (!ASSETS[asset]) {
+    console.error(`Unknown asset "${asset}". Known: ${Object.keys(ASSETS).join(', ')}`);
+    process.exit(1);
+  }
+}
 
 // Node resolves `createRequire(import.meta.url)(...)` at runtime against the
 // package directory, which a binary does not have. Turning those calls into
@@ -42,13 +67,14 @@ for (const entry of fs.readdirSync(schemasDir, { recursive: true, withFileTypes:
 }
 const hash = createHash('sha256').update(JSON.stringify(files)).digest('hex').slice(0, 16);
 
-for (const target of targets) {
-  const name = target.replace(/^bun-/, 'openspec-');
-  const outfile = path.join(root, 'dist-bin', target.includes('windows') ? `${name}.exe` : name);
+for (const asset of assets) {
+  const outfile = path.join(root, 'dist-bin', `openspec-${asset}${asset.startsWith('windows') ? '.exe' : ''}`);
   const result = await Bun.build({
     entrypoints: [path.join(import.meta.dir, 'entry.mjs')],
-    compile: { target, outfile },
-    minify: true,
+    compile: { target: ASSETS[asset], outfile },
+    // Unminified, a crash names the real function and shows readable code
+    // (about 1 MB more), so bug reports from binary users are actionable.
+    minify: false,
     define: { OPENSPEC_EMBEDDED_SCHEMAS: JSON.stringify({ hash, files }) },
     plugins: [staticRequire],
   });
diff --git a/scripts/binary/install.sh b/scripts/binary/install.sh
new file mode 100644
index 0000000000..e814050d5a
--- /dev/null
+++ b/scripts/binary/install.sh
@@ -0,0 +1,82 @@
+#!/bin/sh
+# Installs the standalone `openspec` binary (no Node.js needed) on Linux or macOS.
+#
+#   curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+#
+# OPENSPEC_VERSION      release tag to install (default: latest), e.g. v1.15.0
+# OPENSPEC_INSTALL_DIR  where to put it (default: ~/.local/bin)
+# OPENSPEC_DOWNLOAD_URL base URL of the release assets (mirrors, testing)
+set -eu
+
+fail() { echo "openspec install: $*" >&2; exit 1; }
+
+case "$(uname -s)" in
+  Linux) os=linux ;;
+  Darwin) os=darwin ;;
+  *) fail "unsupported OS $(uname -s). On Windows, download openspec-windows-x64.exe from the release page." ;;
+esac
+case "$(uname -m)" in
+  x86_64 | amd64) arch=x64 ;;
+  arm64 | aarch64) arch=arm64 ;;
+  *) fail "unsupported CPU $(uname -m). Install with npm instead: npm install -g @fission-ai/openspec" ;;
+esac
+# An x64 shell under Rosetta still runs on an Apple Silicon Mac.
+if [ "$os" = darwin ] && [ "$(sysctl -n sysctl.proc_translated 2>/dev/null || echo 0)" = 1 ]; then
+  arch=arm64
+fi
+asset="openspec-$os-$arch"
+# Alpine and other musl distros cannot run the glibc build.
+if [ "$os" = linux ] && { ls /lib/ld-musl-* >/dev/null 2>&1 || ldd --version 2>&1 | grep -qi musl; }; then
+  asset="$asset-musl"
+fi
+
+version="${OPENSPEC_VERSION:-latest}"
+if [ -n "${OPENSPEC_DOWNLOAD_URL:-}" ]; then
+  base="$OPENSPEC_DOWNLOAD_URL"
+elif [ "$version" = latest ]; then
+  base="https://github.com/Fission-AI/OpenSpec/releases/latest/download"
+else
+  base="https://github.com/Fission-AI/OpenSpec/releases/download/$version"
+fi
+dir="${OPENSPEC_INSTALL_DIR:-$HOME/.local/bin}"
+
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+download() {
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL --retry 3 -o "$2" "$1"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -q -O "$2" "$1"
+  else
+    fail "curl or wget is required"
+  fi
+}
+
+echo "Downloading $asset ($version)..."
+download "$base/$asset" "$tmp/$asset" || fail "could not download $base/$asset"
+download "$base/SHA256SUMS" "$tmp/SHA256SUMS" || fail "could not download $base/SHA256SUMS"
+
+expected=$(awk -v f="$asset" '$2 == f { print $1 }' "$tmp/SHA256SUMS")
+[ -n "$expected" ] || fail "$asset is not listed in SHA256SUMS"
+if command -v sha256sum >/dev/null 2>&1; then
+  actual=$(sha256sum "$tmp/$asset" | awk '{ print $1 }')
+else
+  actual=$(shasum -a 256 "$tmp/$asset" | awk '{ print $1 }')
+fi
+[ "$actual" = "$expected" ] || fail "checksum mismatch for $asset; refusing to install"
+
+chmod 755 "$tmp/$asset"
+if ! installed=$("$tmp/$asset" --version); then
+  case "$asset" in
+    *-musl) fail "$asset needs the C++ runtime (Alpine 3.17+): apk add libstdc++ libgcc" ;;
+    *) fail "the downloaded $asset does not run on this machine" ;;
+  esac
+fi
+mkdir -p "$dir"
+mv -f "$tmp/$asset" "$dir/openspec"
+echo "Installed openspec $installed to $dir/openspec"
+
+case ":$PATH:" in
+  *":$dir:"*) ;;
+  *) echo "Add $dir to your PATH to run it, e.g.: export PATH=\"$dir:\$PATH\"" ;;
+esac

From 77507ce06f7e346c2a396df920364f8487336d3a Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Wed, 21 Oct 2026 08:57:35 -0500
Subject: [PATCH 04/27] docs(installation): document the standalone binary

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/installation.md | 27 ++++++++++++++++++++++++++-
 scripts/README.md    | 17 ++++++++++-------
 2 files changed, 36 insertions(+), 8 deletions(-)

diff --git a/docs/installation.md b/docs/installation.md
index a42f026dc9..0c3444eafc 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-- **Node.js 20.19.0 or higher** — Check your version: `node --version`
+- **Node.js 20.19.0 or higher** — Check your version: `node --version`. Not needed for the [standalone binary](#standalone-binary-no-nodejs).
 
 ## Install with your AI assistant
 
@@ -124,6 +124,27 @@ You still need Node.js 20.19.0 or higher available on `PATH`.
 bun add -g @fission-ai/openspec@latest
 ```
 
+## Standalone binary (no Node.js)
+
+Each [GitHub release](https://github.com/Fission-AI/OpenSpec/releases) includes a single-file `openspec` executable for every platform, with Node built in. On macOS or Linux:
+
+```bash
+curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+```
+
+The script picks the right file for your machine, checks it against the release's `SHA256SUMS`, and installs it to `~/.local/bin` (set `OPENSPEC_INSTALL_DIR` to change that, or `OPENSPEC_VERSION=v1.15.0` to pin a release).
+
+To install by hand, download your platform's file, rename it to `openspec` (`openspec.exe` on Windows), and put it on your `PATH`:
+
+| Platform | File |
+|---|---|
+| macOS (Apple Silicon / Intel) | `openspec-darwin-arm64` / `openspec-darwin-x64` |
+| Linux (glibc 2.17+) | `openspec-linux-x64` / `openspec-linux-arm64` |
+| Alpine 3.17+ (needs `apk add libstdc++ libgcc`) | `openspec-linux-x64-musl` / `openspec-linux-arm64-musl` |
+| Windows | `openspec-windows-x64.exe` / `openspec-windows-arm64.exe` |
+
+On macOS, a file downloaded with a browser is blocked until you run `xattr -d com.apple.quarantine openspec`; the install script avoids this. On Windows, SmartScreen may warn the first time you run it from Explorer.
+
 ## Nix
 
 Run OpenSpec directly without installation:
@@ -170,6 +191,8 @@ npm install -g @fission-ai/openspec@latest   # or pnpm/yarn/bun equivalent
 openspec update                              # run inside each project
 ```
 
+With the standalone binary, run the install script again (or download the new file) instead of the package manager command.
+
 `openspec update` regenerates the skill and command files for the tools you've configured, so your slash commands stay current with the installed version. It also checks whether a newer CLI has been published and offers to upgrade, since upgrading is what makes new workflows available in the first place — see [CLI Reference](cli.md#openspec-update).
 
 ## Uninstalling
@@ -182,6 +205,8 @@ There's no `openspec uninstall` command, because OpenSpec is just a global packa
 npm uninstall -g @fission-ai/openspec   # or: pnpm rm -g / yarn global remove / bun rm -g
 ```
 
+With the standalone binary, delete the file instead (`rm ~/.local/bin/openspec` if you used the install script). It also keeps a copy of its built-in schemas under your OpenSpec data directory (`~/.local/share/openspec/binary-schemas` on macOS and Linux, `%LOCALAPPDATA%\openspec\binary-schemas` on Windows), which you can delete too.
+
 **2. Remove OpenSpec from a project (optional).** Delete the `openspec/` directory if you no longer want its specs and changes:
 
 ```bash
diff --git a/scripts/README.md b/scripts/README.md
index a56796f36e..03c5292156 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -74,17 +74,20 @@ Validates package version consistency before publishing.
 ## binary/
 
 Builds standalone `openspec` executables with Bun, for people without Node.js.
-CI smoke-tests them on every PR and attaches them to each published release
-(`.github/workflows/binaries.yml`).
+`.github/workflows/binaries.yml` cross-compiles every asset on Linux, tests
+each on its own OS and CPU (Alpine for the musl ones), and attaches them,
+`SHA256SUMS`, and `install.sh` to each published release.
 
 **Usage**:
 ```bash
 pnpm build
-bun scripts/binary/build.mjs                  # this machine → dist-bin/
-bun scripts/binary/build.mjs bun-linux-x64    # cross-compile any Bun target
-bash scripts/binary/smoke.sh dist-bin/openspec-<os>-<arch>
+bun scripts/binary/build.mjs                    # this machine → dist-bin/
+bun scripts/binary/build.mjs --all              # every release asset
+bun scripts/binary/build.mjs linux-x64-musl     # named assets (see ASSETS in build.mjs)
+bash scripts/binary/smoke.sh dist-bin/openspec-<asset>
 ```
 
 The binary has no package directory, so `build.mjs` bundles `package.json`
-and embeds `schemas/`, which `entry.mjs` writes to
-`<data dir>/binary-schemas/<content hash>/` on first run.
+and embeds `schemas/`; `entry.mjs` writes them to
+`<data dir>/binary-schemas/<content hash>/` the first time a command needs
+them, and rewrites that copy if it was edited or partly deleted.

From b1163c047d9d8376d5168dea6f56c7a00498c6e7 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Wed, 21 Oct 2026 12:27:49 -0500
Subject: [PATCH 05/27] fix(cli): give standalone binary users upgrade advice
 that works

`openspec update` told binary users to run `npm install -g`, which needs
the Node.js they don't have. The binary now marks itself at startup and:

- prints the installer pointed at the binary's own directory (a
  PowerShell download on Windows), so the new copy replaces the old one;
- reports `(standalone)` and its location in `openspec version`;
- never feeds a directory to the npm self-upgrade logic.

getInstallDir() now resolves package.json from import.meta.url at runtime.
require.resolve was resolved by the bundler at build time, baking the build
machine's repo path into the binary; on the build machine that path is a
git checkout, which also silently skipped the update check. npm and pnpm
installs resolve to the same (symlink-resolved) directory as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/binary/entry.mjs        |  3 ++
 src/core/version-check.ts       | 51 +++++++++++++++++++++++++++++----
 test/core/version-check.test.ts | 47 ++++++++++++++++++++++++++++++
 3 files changed, 95 insertions(+), 6 deletions(-)

diff --git a/scripts/binary/entry.mjs b/scripts/binary/entry.mjs
index 328b266ba4..dee947b6db 100644
--- a/scripts/binary/entry.mjs
+++ b/scripts/binary/entry.mjs
@@ -6,6 +6,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { getGlobalDataDir } from '../../dist/core/global-config.js';
 import { setPackageSchemasDir } from '../../dist/core/artifact-graph/resolver.js';
+import { markStandaloneBinary } from '../../dist/core/version-check.js';
 
 // Replaced by build.mjs: { hash, files: { 'spec-driven/schema.yaml': '...' } }
 const { hash, files } = OPENSPEC_EMBEDDED_SCHEMAS;
@@ -68,6 +69,8 @@ function extractSchemas() {
   }
 }
 
+markStandaloneBinary(process.execPath);
+
 let schemasDir;
 setPackageSchemasDir(() => {
   try {
diff --git a/src/core/version-check.ts b/src/core/version-check.ts
index 6d935d7894..993db32299 100644
--- a/src/core/version-check.ts
+++ b/src/core/version-check.ts
@@ -3,6 +3,7 @@ import http from 'http';
 import https from 'https';
 import path from 'path';
 import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 import { isCiEnvironment } from '../utils/ci.js';
 import { isTelemetryOptedOutByEnv } from '../telemetry/opt-out.js';
@@ -26,6 +27,31 @@ const MAX_REDIRECTS = 3;
  */
 const SAFE_VERSION = /^\d{1,10}\.\d{1,10}\.\d{1,10}(?:-[0-9A-Za-z.-]{1,64})?(?:\+[0-9A-Za-z.-]{1,64})?$/;
 
+const RELEASE_DOWNLOAD_URL = 'https://github.com/Fission-AI/OpenSpec/releases/latest/download';
+let standaloneBinaryPath: string | null = null;
+
+/**
+ * Called by the standalone binary's entry point. That copy has no package
+ * manager behind it, so a package-manager command is the wrong upgrade advice.
+ */
+export function markStandaloneBinary(executablePath: string): void {
+  standaloneBinaryPath = executablePath;
+}
+
+/**
+ * Replaces the standalone binary where it already is, so the new copy cannot
+ * end up shadowed by the old one on PATH. Null when this is not the binary.
+ */
+function standaloneUpgradeCommand(): string | null {
+  if (!standaloneBinaryPath) return null;
+  if (process.platform === 'win32') {
+    const target = standaloneBinaryPath.replace(/'/g, "''");
+    return `Invoke-WebRequest ${RELEASE_DOWNLOAD_URL}/openspec-windows-${process.arch}.exe -OutFile '${target}'`;
+  }
+  const dir = path.dirname(standaloneBinaryPath).replace(/'/g, `'\\''`);
+  return `curl -fsSL ${RELEASE_DOWNLOAD_URL}/install.sh | OPENSPEC_INSTALL_DIR='${dir}' sh`;
+}
+
 /**
  * The check is opt-out and must never get in the way: no network in CI or
  * tests, an explicit escape hatch for anyone offline or air-gapped, and the
@@ -322,11 +348,13 @@ export async function getAvailableCliUpdate(): Promise<string | null> {
  * which copy is actually answering.
  */
 export function getInstallDir(): string | null {
-  try {
-    return path.dirname(require.resolve('../../package.json'));
-  } catch {
-    return null;
-  }
+  // The binary is not a package install, so no package-manager logic applies.
+  if (standaloneBinaryPath) return null;
+  // Resolved at runtime from this module's own (symlink-resolved) location.
+  // require.resolve would be resolved by the binary's bundler at build time,
+  // baking the build machine's path into it.
+  const packageJson = fileURLToPath(new URL('../../package.json', import.meta.url));
+  return fs.existsSync(packageJson) ? path.dirname(packageJson) : null;
 }
 
 /**
@@ -490,7 +518,7 @@ export function isSourceCheckout(installDir: string | null): boolean {
 }
 
 export type PackageManager = 'npm' | 'pnpm' | 'bun' | 'yarn' | 'volta';
-export type InstallScope = 'global' | 'project' | 'temporary' | 'source';
+export type InstallScope = 'global' | 'project' | 'temporary' | 'source' | 'standalone';
 
 export interface CliInstallInfo {
   location: string | null;
@@ -550,6 +578,9 @@ export function getCliInstallInfo(
   installDir: string | null = getInstallDir(),
   projectPath: string = '.'
 ): CliInstallInfo {
+  if (standaloneBinaryPath) {
+    return { location: path.dirname(standaloneBinaryPath), packageManager: null, scope: 'standalone' };
+  }
   if (!installDir) {
     return { location: null, packageManager: null, scope: null };
   }
@@ -581,6 +612,7 @@ export function getCliInstallInfo(
 
 /** Returns a safe update command only for an install with known global ownership. */
 export function getCliUpdateCommand(install: CliInstallInfo): string | null {
+  if (install.scope === 'standalone') return standaloneUpgradeCommand();
   if (install.scope !== 'global' || install.packageManager === null) return null;
   return GLOBAL_UPGRADE_COMMANDS[install.packageManager];
 }
@@ -643,6 +675,13 @@ export function buildUpgradeCommandLines(
 ): string[] {
   const lines: string[] = [];
 
+  const standalone = standaloneUpgradeCommand();
+  if (standalone) {
+    lines.push(`  ${standalone}`);
+    lines.push('  Then run "openspec update" again to pick up new workflows.');
+    return lines;
+  }
+
   if (isEphemeralRunnerInstall(installDir)) {
     // That command *is* the update, so there is nothing to run afterwards.
     lines.push(`  npx ${PACKAGE_NAME}@latest update`);
diff --git a/test/core/version-check.test.ts b/test/core/version-check.test.ts
index e68b3f5aba..ae211bb7e6 100644
--- a/test/core/version-check.test.ts
+++ b/test/core/version-check.test.ts
@@ -1242,3 +1242,50 @@ describe('displayCliUpdateNote', () => {
     expect(isEphemeralRunnerInstall(null)).toBe(false);
   });
 });
+
+describe('standalone binary', () => {
+  // A path with a space and a quote, to prove the printed command survives a shell.
+  const executable = path.join(os.tmpdir(), "it's bin", process.platform === 'win32' ? 'openspec.exe' : 'openspec');
+
+  async function loadMarked() {
+    // A fresh module copy, so the mark cannot leak into other tests.
+    vi.resetModules();
+    const versionCheck = await import('../../src/core/version-check.js');
+    versionCheck.markStandaloneBinary(executable);
+    return versionCheck;
+  }
+
+  it('reports itself as standalone, located where the binary is', async () => {
+    const { getCliInstallInfo, getInstallDir, buildVersionReportLines } = await loadMarked();
+    // Not a package install: no package-manager logic may act on a directory.
+    expect(getInstallDir()).toBeNull();
+    const install = getCliInstallInfo(null);
+
+    expect(install).toEqual({ location: path.dirname(executable), packageManager: null, scope: 'standalone' });
+    expect(buildVersionReportLines('1.0.0', install)[0]).toBe('OpenSpec 1.0.0 (standalone)');
+  });
+
+  it('upgrades by replacing the binary in place, never through a package manager', async () => {
+    const { getCliInstallInfo, getCliUpdateCommand, buildCliUpdateLines, canSelfUpgrade } = await loadMarked();
+    const command = getCliUpdateCommand(getCliInstallInfo(null));
+    const lines = buildCliUpdateLines('9.9.9', null, PROJECT_ROOT).join('\n');
+
+    if (process.platform === 'win32') {
+      expect(command).toBe(
+        `Invoke-WebRequest https://github.com/Fission-AI/OpenSpec/releases/latest/download/openspec-windows-${process.arch}.exe -OutFile '${executable.replace(/'/g, "''")}'`
+      );
+    } else {
+      expect(command).toMatch(
+        /^curl -fsSL https:\/\/github\.com\/Fission-AI\/OpenSpec\/releases\/latest\/download\/install\.sh \| OPENSPEC_INSTALL_DIR='.*' sh$/
+      );
+      // The quoted directory is exactly the binary's directory once a shell reads it.
+      const quoted = command!.match(/OPENSPEC_INSTALL_DIR=(.*) sh$/)![1];
+      const { execFileSync } = await import('child_process');
+      expect(execFileSync('sh', ['-c', `printf %s ${quoted}`], { encoding: 'utf8' })).toBe(path.dirname(executable));
+    }
+    expect(lines).toContain(command!);
+    expect(lines).toContain('Then run "openspec update" again');
+    expect(lines).not.toMatch(/npm|pnpm|yarn|volta|bun add/);
+    expect(canSelfUpgrade(null, PROJECT_ROOT)).toBe(false);
+  });
+});

From 758078cf7e668f29440a0bc311ecc2e1942f67b9 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Wed, 21 Oct 2026 12:27:49 -0500
Subject: [PATCH 06/27] fix(ci): tighten binary builds and the release tag
 check

- Fail the build if a binary embeds the build machine's path.
- Hash schemas in sorted order so builds are reproducible, and refuse
  schema files that are not UTF-8 text instead of corrupting them.
- Match the release tag to package.json exactly (v1.2.3 or the scoped
  @fission-ai/openspec@1.2.3 tag); a suffix match let v11.0.0 pass 1.0.0.
- Skip the merge queue: the PR run covers the change and a release
  re-verifies before upload.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/binaries.yml | 11 +++++++----
 scripts/binary/build.mjs       | 25 +++++++++++++++++++++----
 2 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/binaries.yml b/.github/workflows/binaries.yml
index c9186587d2..7892cc0e67 100644
--- a/.github/workflows/binaries.yml
+++ b/.github/workflows/binaries.yml
@@ -2,12 +2,11 @@ name: Binaries
 
 # Standalone `openspec` executables for people without Node.js (#2055).
 # One Linux job cross-compiles every asset; each is then tested on its own OS
-# and CPU, and only then attached to a published release.
+# and CPU, and only then attached to a published release. Not run in the merge
+# queue: the PR run covers the change, and a release re-verifies before upload.
 on:
   pull_request:
     branches: [main]
-  merge_group:
-    branches: [main]
   release:
     types: [published]
   workflow_dispatch:
@@ -58,7 +57,11 @@ jobs:
         if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
         run: |
           version=$(node -p "require('./package.json').version")
-          [[ "$REF" == *"$version" ]] || {
+          # Tags are v1.2.3, or @fission-ai/openspec@1.2.3 as changesets first
+          # creates them. Exact match: a suffix match would let v11.0.0 pass for 1.0.0.
+          tag_version=${REF##*@}
+          tag_version=${tag_version#v}
+          [[ "$tag_version" == "$version" ]] || {
             echo "::error::package.json version $version does not match tag $REF"
             exit 1
           }
diff --git a/scripts/binary/build.mjs b/scripts/binary/build.mjs
index 9fdb38ac24..937a79ab3a 100644
--- a/scripts/binary/build.mjs
+++ b/scripts/binary/build.mjs
@@ -58,12 +58,23 @@ const staticRequire = {
   },
 };
 
+// Sorted, so the same schemas give the same hash on every filesystem.
 const files = {};
 const schemasDir = path.join(root, 'schemas');
-for (const entry of fs.readdirSync(schemasDir, { recursive: true, withFileTypes: true })) {
-  if (!entry.isFile()) continue;
-  const file = path.join(entry.parentPath, entry.name);
-  files[path.relative(schemasDir, file).split(path.sep).join('/')] = fs.readFileSync(file, 'utf8');
+const schemaFiles = fs
+  .readdirSync(schemasDir, { recursive: true, withFileTypes: true })
+  .filter((entry) => entry.isFile())
+  .map((entry) => path.relative(schemasDir, path.join(entry.parentPath, entry.name)).split(path.sep).join('/'))
+  .sort();
+for (const relativePath of schemaFiles) {
+  const bytes = fs.readFileSync(path.join(schemasDir, relativePath));
+  const content = bytes.toString('utf8');
+  // Embedded as text; anything else would be silently corrupted.
+  if (!Buffer.from(content, 'utf8').equals(bytes)) {
+    console.error(`schemas/${relativePath} is not UTF-8 text and cannot be embedded`);
+    process.exit(1);
+  }
+  files[relativePath] = content;
 }
 const hash = createHash('sha256').update(JSON.stringify(files)).digest('hex').slice(0, 16);
 
@@ -82,5 +93,11 @@ for (const asset of assets) {
     for (const log of result.logs) console.error(log);
     process.exit(1);
   }
+  // Bun resolves some paths at build time; one baked into the binary points
+  // at this machine and would mislead the CLI everywhere else.
+  if (fs.readFileSync(outfile).includes(root)) {
+    console.error(`${path.relative(root, outfile)} embeds the build path ${root}`);
+    process.exit(1);
+  }
   console.log(`Built ${path.relative(root, outfile)}`);
 }

From eaf3cab28d7bc6be55da0185506aaa4961c4b78c Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Wed, 21 Oct 2026 12:27:50 -0500
Subject: [PATCH 07/27] fix(cli): harden the binary installer for more machines

- Detect glibc first, so a glibc distro with musl installed alongside no
  longer gets the Alpine build.
- Stage the download in the install dir: works when /tmp is noexec and
  replaces an existing copy atomically.
- Run everything from main(), so a truncated `curl | sh` does nothing.
- Clear errors for unset HOME, an unwritable dir, and macOS older than 13;
  accept OPENSPEC_VERSION with or without the leading v.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/binary/install.sh | 144 +++++++++++++++++++++-----------------
 1 file changed, 81 insertions(+), 63 deletions(-)

diff --git a/scripts/binary/install.sh b/scripts/binary/install.sh
index e814050d5a..e0b6dd1199 100644
--- a/scripts/binary/install.sh
+++ b/scripts/binary/install.sh
@@ -3,80 +3,98 @@
 #
 #   curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
 #
-# OPENSPEC_VERSION      release tag to install (default: latest), e.g. v1.15.0
+# OPENSPEC_VERSION      release to install (default: latest), e.g. v1.15.0
 # OPENSPEC_INSTALL_DIR  where to put it (default: ~/.local/bin)
 # OPENSPEC_DOWNLOAD_URL base URL of the release assets (mirrors, testing)
 set -eu
 
 fail() { echo "openspec install: $*" >&2; exit 1; }
 
-case "$(uname -s)" in
-  Linux) os=linux ;;
-  Darwin) os=darwin ;;
-  *) fail "unsupported OS $(uname -s). On Windows, download openspec-windows-x64.exe from the release page." ;;
-esac
-case "$(uname -m)" in
-  x86_64 | amd64) arch=x64 ;;
-  arm64 | aarch64) arch=arm64 ;;
-  *) fail "unsupported CPU $(uname -m). Install with npm instead: npm install -g @fission-ai/openspec" ;;
-esac
-# An x64 shell under Rosetta still runs on an Apple Silicon Mac.
-if [ "$os" = darwin ] && [ "$(sysctl -n sysctl.proc_translated 2>/dev/null || echo 0)" = 1 ]; then
-  arch=arm64
-fi
-asset="openspec-$os-$arch"
-# Alpine and other musl distros cannot run the glibc build.
-if [ "$os" = linux ] && { ls /lib/ld-musl-* >/dev/null 2>&1 || ldd --version 2>&1 | grep -qi musl; }; then
-  asset="$asset-musl"
-fi
-
-version="${OPENSPEC_VERSION:-latest}"
-if [ -n "${OPENSPEC_DOWNLOAD_URL:-}" ]; then
-  base="$OPENSPEC_DOWNLOAD_URL"
-elif [ "$version" = latest ]; then
-  base="https://github.com/Fission-AI/OpenSpec/releases/latest/download"
-else
-  base="https://github.com/Fission-AI/OpenSpec/releases/download/$version"
-fi
-dir="${OPENSPEC_INSTALL_DIR:-$HOME/.local/bin}"
+# Everything runs from main, so a download cut short while piped into sh
+# runs nothing instead of half a script.
+main() {
+  case "$(uname -s)" in
+    Linux) os=linux ;;
+    Darwin) os=darwin ;;
+    *) fail "unsupported OS $(uname -s). On Windows, download openspec-windows-x64.exe from the release page." ;;
+  esac
+  case "$(uname -m)" in
+    x86_64 | amd64) arch=x64 ;;
+    arm64 | aarch64) arch=arm64 ;;
+    *) fail "unsupported CPU $(uname -m). Install with npm instead: npm install -g @fission-ai/openspec" ;;
+  esac
+  # An x64 shell under Rosetta still runs on an Apple Silicon Mac.
+  if [ "$os" = darwin ] && [ "$(sysctl -n sysctl.proc_translated 2>/dev/null || echo 0)" = 1 ]; then
+    arch=arm64
+  fi
+  asset="openspec-$os-$arch"
+  # Alpine and other musl distros cannot run the glibc build. Ask glibc first:
+  # a glibc system can have musl installed alongside, loader and all.
+  if [ "$os" = linux ] && ! getconf GNU_LIBC_VERSION >/dev/null 2>&1 &&
+    { ldd --version 2>&1 | grep -qi musl || ls /lib/ld-musl-* >/dev/null 2>&1; }; then
+    asset="$asset-musl"
+  fi
 
-tmp=$(mktemp -d)
-trap 'rm -rf "$tmp"' EXIT
-download() {
-  if command -v curl >/dev/null 2>&1; then
-    curl -fsSL --retry 3 -o "$2" "$1"
-  elif command -v wget >/dev/null 2>&1; then
-    wget -q -O "$2" "$1"
+  version="${OPENSPEC_VERSION:-latest}"
+  case "$version" in latest | v*) ;; *) version="v$version" ;; esac
+  if [ -n "${OPENSPEC_DOWNLOAD_URL:-}" ]; then
+    base="$OPENSPEC_DOWNLOAD_URL"
+  elif [ "$version" = latest ]; then
+    base="https://github.com/Fission-AI/OpenSpec/releases/latest/download"
   else
-    fail "curl or wget is required"
+    base="https://github.com/Fission-AI/OpenSpec/releases/download/$version"
   fi
-}
+  if [ -n "${OPENSPEC_INSTALL_DIR:-}" ]; then
+    dir="$OPENSPEC_INSTALL_DIR"
+  elif [ -n "${HOME:-}" ]; then
+    dir="$HOME/.local/bin"
+  else
+    fail "HOME is not set; set OPENSPEC_INSTALL_DIR to choose where to install"
+  fi
+
+  # Staged inside the install dir, not /tmp: /tmp is often mounted noexec, and
+  # a same-filesystem mv replaces an existing copy atomically.
+  mkdir -p "$dir" || fail "cannot create $dir"
+  tmp=$(mktemp -d "$dir/.openspec-install.XXXXXX") || fail "cannot write to $dir"
+  trap 'rm -rf "$tmp"' EXIT
+  download() {
+    if command -v curl >/dev/null 2>&1; then
+      curl -fsSL --retry 3 -o "$2" "$1"
+    elif command -v wget >/dev/null 2>&1; then
+      wget -q -O "$2" "$1"
+    else
+      fail "curl or wget is required"
+    fi
+  }
 
-echo "Downloading $asset ($version)..."
-download "$base/$asset" "$tmp/$asset" || fail "could not download $base/$asset"
-download "$base/SHA256SUMS" "$tmp/SHA256SUMS" || fail "could not download $base/SHA256SUMS"
+  echo "Downloading $asset ($version)..."
+  download "$base/$asset" "$tmp/$asset" || fail "could not download $base/$asset"
+  download "$base/SHA256SUMS" "$tmp/SHA256SUMS" || fail "could not download $base/SHA256SUMS"
 
-expected=$(awk -v f="$asset" '$2 == f { print $1 }' "$tmp/SHA256SUMS")
-[ -n "$expected" ] || fail "$asset is not listed in SHA256SUMS"
-if command -v sha256sum >/dev/null 2>&1; then
-  actual=$(sha256sum "$tmp/$asset" | awk '{ print $1 }')
-else
-  actual=$(shasum -a 256 "$tmp/$asset" | awk '{ print $1 }')
-fi
-[ "$actual" = "$expected" ] || fail "checksum mismatch for $asset; refusing to install"
+  expected=$(awk -v f="$asset" '$2 == f { print $1 }' "$tmp/SHA256SUMS")
+  [ -n "$expected" ] || fail "$asset is not listed in SHA256SUMS"
+  if command -v sha256sum >/dev/null 2>&1; then
+    actual=$(sha256sum "$tmp/$asset" | awk '{ print $1 }')
+  else
+    actual=$(shasum -a 256 "$tmp/$asset" | awk '{ print $1 }')
+  fi
+  [ "$actual" = "$expected" ] || fail "checksum mismatch for $asset; refusing to install"
 
-chmod 755 "$tmp/$asset"
-if ! installed=$("$tmp/$asset" --version); then
-  case "$asset" in
-    *-musl) fail "$asset needs the C++ runtime (Alpine 3.17+): apk add libstdc++ libgcc" ;;
-    *) fail "the downloaded $asset does not run on this machine" ;;
+  chmod 755 "$tmp/$asset"
+  if ! installed=$("$tmp/$asset" --version); then
+    case "$asset" in
+      *-musl) fail "$asset needs the C++ runtime (Alpine 3.17+): apk add libstdc++ libgcc" ;;
+      openspec-darwin-*) fail "$asset needs macOS 13 or later" ;;
+      *) fail "the downloaded $asset does not run on this machine" ;;
+    esac
+  fi
+  mv -f "$tmp/$asset" "$dir/openspec"
+  echo "Installed openspec $installed to $dir/openspec"
+
+  case ":$PATH:" in
+    *":$dir:"*) ;;
+    *) echo "Add $dir to your PATH to run it, e.g.: export PATH=\"$dir:\$PATH\"" ;;
   esac
-fi
-mkdir -p "$dir"
-mv -f "$tmp/$asset" "$dir/openspec"
-echo "Installed openspec $installed to $dir/openspec"
+}
 
-case ":$PATH:" in
-  *":$dir:"*) ;;
-  *) echo "Add $dir to your PATH to run it, e.g.: export PATH=\"$dir:\$PATH\"" ;;
-esac
+main "$@"

From 79ecec3ac0c85dccef9d813b3c87538f00bb3d63 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Wed, 21 Oct 2026 12:27:50 -0500
Subject: [PATCH 08/27] docs(installation): offer the binary when Node is
 missing

The assistant install prompt and install.md now offer the standalone
binary, with the user's confirmation, instead of stopping when Node is
missing or too old. Also states macOS 13+ / Windows 10+ and when the
schema copy is kept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/installation.md | 15 ++++++++++-----
 install.md           |  2 +-
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/docs/installation.md b/docs/installation.md
index 0c3444eafc..9d32e0b636 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -15,8 +15,13 @@ Install OpenSpec in this project and set it up for me. Follow these steps in
 order, and stop where a step tells you to stop.
 
 1. RUNTIME. Run `node --version`. OpenSpec needs Node.js 20.19.0 or higher. If
-   Node is missing or older, say so and stop — don't install Node, switch
-   versions, or reconfigure my version manager for me.
+   Node is missing or older, don't install Node, switch versions, or
+   reconfigure my version manager for me. Offer the standalone binary instead,
+   which needs no Node. On macOS or Linux, show me this command and run it only
+   once I confirm, then skip to step 3:
+     curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+   On Windows, or if I decline or it fails, point me at the "Standalone binary"
+   section of the OpenSpec installation docs and stop.
 
 2. INSTALL. Use whichever package manager is already on my PATH, preferring npm:
      npm install -g @fission-ai/openspec@latest
@@ -138,10 +143,10 @@ To install by hand, download your platform's file, rename it to `openspec` (`ope
 
 | Platform | File |
 |---|---|
-| macOS (Apple Silicon / Intel) | `openspec-darwin-arm64` / `openspec-darwin-x64` |
+| macOS 13+ (Apple Silicon / Intel) | `openspec-darwin-arm64` / `openspec-darwin-x64` |
 | Linux (glibc 2.17+) | `openspec-linux-x64` / `openspec-linux-arm64` |
 | Alpine 3.17+ (needs `apk add libstdc++ libgcc`) | `openspec-linux-x64-musl` / `openspec-linux-arm64-musl` |
-| Windows | `openspec-windows-x64.exe` / `openspec-windows-arm64.exe` |
+| Windows 10+ | `openspec-windows-x64.exe` / `openspec-windows-arm64.exe` |
 
 On macOS, a file downloaded with a browser is blocked until you run `xattr -d com.apple.quarantine openspec`; the install script avoids this. On Windows, SmartScreen may warn the first time you run it from Explorer.
 
@@ -205,7 +210,7 @@ There's no `openspec uninstall` command, because OpenSpec is just a global packa
 npm uninstall -g @fission-ai/openspec   # or: pnpm rm -g / yarn global remove / bun rm -g
 ```
 
-With the standalone binary, delete the file instead (`rm ~/.local/bin/openspec` if you used the install script). It also keeps a copy of its built-in schemas under your OpenSpec data directory (`~/.local/share/openspec/binary-schemas` on macOS and Linux, `%LOCALAPPDATA%\openspec\binary-schemas` on Windows), which you can delete too.
+With the standalone binary, delete the file instead (`rm ~/.local/bin/openspec` if you used the install script). When that directory is writable, it also keeps a copy of its built-in schemas under your OpenSpec data directory (`~/.local/share/openspec/binary-schemas` on macOS and Linux, `%LOCALAPPDATA%\openspec\binary-schemas` on Windows), which you can delete too.
 
 **2. Remove OpenSpec from a project (optional).** Delete the `openspec/` directory if you no longer want its specs and changes:
 
diff --git a/install.md b/install.md
index a37c0fe402..fd1401f99b 100644
--- a/install.md
+++ b/install.md
@@ -22,7 +22,7 @@ TODO:
 
 ## 1. Runtime
 
-Run `node --version`. OpenSpec needs Node.js 20.19.0 or higher. If Node is missing or older, say so and stop, but leave the user with their next move: point them at https://nodejs.org, or if they use a version manager like nvm, name the command that would switch to a newer version. Don't install Node, switch versions, or reconfigure the user's version manager yourself.
+Run `node --version`. OpenSpec needs Node.js 20.19.0 or higher. If Node is missing or older, don't install Node, switch versions, or reconfigure the user's version manager yourself. Offer the standalone binary instead, which needs no Node: on macOS or Linux, show `curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh`, run it only once the user confirms, then skip to step 3. On Windows, or if the user declines or it fails, stop and leave them with their next move: the standalone binary section of https://openspec.dev/docs/installation, https://nodejs.org, or, if they use a version manager like nvm, the command that would switch to a newer version.
 
 ## 2. Install
 

From 17103c11960349e64166a0bc08f3475364a12b11 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Thu, 22 Oct 2026 09:31:55 -0500
Subject: [PATCH 09/27] feat(cli): add a Windows installer for the standalone
 binary

install.ps1 is the Windows counterpart of install.sh: `irm .../install.ps1 |
iex` in Windows PowerShell 5.1 or PowerShell 7. It picks the x64 or ARM build
from the OS architecture, checks SHA256SUMS, installs to
%LOCALAPPDATA%\Programs\openspec and appends that folder to the user PATH
once. The PATH is read and written raw so %VAR% entries keep expanding. It
throws rather than exits, so a failure never closes the user's window.

A binary on Windows now gets this installer as its upgrade advice instead
of an unverified download. Both installers suggest npm when a download
fails.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/binary/install.ps1      | 95 +++++++++++++++++++++++++++++++++
 scripts/binary/install.sh       |  5 +-
 src/core/version-check.ts       |  4 +-
 test/core/version-check.test.ts |  2 +-
 4 files changed, 101 insertions(+), 5 deletions(-)
 create mode 100644 scripts/binary/install.ps1

diff --git a/scripts/binary/install.ps1 b/scripts/binary/install.ps1
new file mode 100644
index 0000000000..b86d37bde3
--- /dev/null
+++ b/scripts/binary/install.ps1
@@ -0,0 +1,95 @@
+# Installs the standalone `openspec.exe` (no Node.js needed) on Windows.
+#
+#   irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex
+#
+# $env:OPENSPEC_VERSION      release to install (default: latest), e.g. v1.15.0
+# $env:OPENSPEC_INSTALL_DIR  where to put it (default: %LOCALAPPDATA%\Programs\openspec)
+# $env:OPENSPEC_DOWNLOAD_URL base URL of the release assets (mirrors, testing)
+#
+# Runs in Windows PowerShell 5.1 and PowerShell 7. It throws instead of
+# calling exit, which would close the window of anyone who piped it into iex.
+& {
+  $ErrorActionPreference = 'Stop'
+  # Windows PowerShell 5.1 may default to TLS 1.0, which GitHub refuses, and
+  # draws a progress bar that slows downloads many times over.
+  [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+  $ProgressPreference = 'SilentlyContinue'
+
+  # The OS architecture, not this PowerShell's: an x64 shell on an ARM PC
+  # should still get the native ARM build.
+  $arch = switch ([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture) {
+    'X64' { 'x64' }
+    'Arm64' { 'arm64' }
+    default { throw "openspec install: unsupported CPU $_. Install with npm instead: npm install -g @fission-ai/openspec" }
+  }
+  $asset = "openspec-windows-$arch.exe"
+
+  $version = if ($env:OPENSPEC_VERSION) { $env:OPENSPEC_VERSION } else { 'latest' }
+  if ($version -ne 'latest' -and -not $version.StartsWith('v')) { $version = "v$version" }
+  $base = if ($env:OPENSPEC_DOWNLOAD_URL) {
+    $env:OPENSPEC_DOWNLOAD_URL
+  } elseif ($version -eq 'latest') {
+    'https://github.com/Fission-AI/OpenSpec/releases/latest/download'
+  } else {
+    "https://github.com/Fission-AI/OpenSpec/releases/download/$version"
+  }
+  $dir = if ($env:OPENSPEC_INSTALL_DIR) { $env:OPENSPEC_INSTALL_DIR } else { Join-Path $env:LOCALAPPDATA 'Programs\openspec' }
+
+  # Staged inside the install dir so the final move is a same-volume rename.
+  New-Item -ItemType Directory -Force -Path $dir | Out-Null
+  $tmp = Join-Path $dir ('.openspec-install-' + [Guid]::NewGuid().ToString('N'))
+  New-Item -ItemType Directory -Path $tmp | Out-Null
+  try {
+    Write-Host "Downloading $asset ($version)..."
+    $exe = Join-Path $tmp $asset
+    $sums = Join-Path $tmp 'SHA256SUMS'
+    try {
+      Invoke-WebRequest -UseBasicParsing -Uri "$base/$asset" -OutFile $exe
+      Invoke-WebRequest -UseBasicParsing -Uri "$base/SHA256SUMS" -OutFile $sums
+    } catch {
+      throw "openspec install: could not download from ${base}: $($_.Exception.Message). Or install with npm (Node.js 20.19+): npm install -g @fission-ai/openspec"
+    }
+
+    $line = Get-Content $sums | Where-Object { ($_ -split '\s+')[1] -eq $asset } | Select-Object -First 1
+    if (-not $line) { throw "openspec install: $asset is not listed in SHA256SUMS" }
+    $expected = ($line -split '\s+')[0]
+    $actual = (Get-FileHash -Algorithm SHA256 -Path $exe).Hash
+    if ($actual -ne $expected) { throw "openspec install: checksum mismatch for $asset; refusing to install" }
+
+    $installed = $null
+    try { $installed = & $exe --version } catch {}
+    if ($LASTEXITCODE -ne 0 -or -not $installed) {
+      throw "openspec install: the downloaded $asset does not run on this machine (needs Windows 10 or later)"
+    }
+
+    $target = Join-Path $dir 'openspec.exe'
+    try {
+      Move-Item -Force -Path $exe -Destination $target
+    } catch {
+      throw "openspec install: could not replace $target. Close any running openspec and try again."
+    }
+    Write-Host "Installed openspec $installed to $target"
+  } finally {
+    Remove-Item -Recurse -Force -Path $tmp -ErrorAction SilentlyContinue
+  }
+
+  # Unlike a shell profile, the user PATH is the standard place for this on
+  # Windows. Only appended to, and only when missing. Read and written raw:
+  # [Environment]::SetEnvironmentVariable would save it expanded, turning
+  # entries like %USERPROFILE%\bin into fixed paths for good.
+  $key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
+  try {
+    $raw = [string]$key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
+    $entries = @($raw -split ';' | Where-Object { $_ })
+    if ($entries -notcontains $dir) {
+      $key.SetValue('Path', (($entries + $dir) -join ';'), [Microsoft.Win32.RegistryValueKind]::ExpandString)
+      # Setting any user variable broadcasts the change, so new terminals see it.
+      [Environment]::SetEnvironmentVariable('OPENSPEC_INSTALL_PATH_CHANGED', '1', 'User')
+      [Environment]::SetEnvironmentVariable('OPENSPEC_INSTALL_PATH_CHANGED', $null, 'User')
+      $env:Path = "$env:Path;$dir"
+      Write-Host "Added $dir to your user PATH. Open a new terminal to use openspec everywhere."
+    }
+  } finally {
+    $key.Close()
+  }
+}
diff --git a/scripts/binary/install.sh b/scripts/binary/install.sh
index e0b6dd1199..d2824b0a7a 100644
--- a/scripts/binary/install.sh
+++ b/scripts/binary/install.sh
@@ -68,8 +68,9 @@ main() {
   }
 
   echo "Downloading $asset ($version)..."
-  download "$base/$asset" "$tmp/$asset" || fail "could not download $base/$asset"
-  download "$base/SHA256SUMS" "$tmp/SHA256SUMS" || fail "could not download $base/SHA256SUMS"
+  npm_hint="or install with npm (Node.js 20.19+): npm install -g @fission-ai/openspec"
+  download "$base/$asset" "$tmp/$asset" || fail "could not download $base/$asset; $npm_hint"
+  download "$base/SHA256SUMS" "$tmp/SHA256SUMS" || fail "could not download $base/SHA256SUMS; $npm_hint"
 
   expected=$(awk -v f="$asset" '$2 == f { print $1 }' "$tmp/SHA256SUMS")
   [ -n "$expected" ] || fail "$asset is not listed in SHA256SUMS"
diff --git a/src/core/version-check.ts b/src/core/version-check.ts
index 993db32299..0de587fe0b 100644
--- a/src/core/version-check.ts
+++ b/src/core/version-check.ts
@@ -45,8 +45,8 @@ export function markStandaloneBinary(executablePath: string): void {
 function standaloneUpgradeCommand(): string | null {
   if (!standaloneBinaryPath) return null;
   if (process.platform === 'win32') {
-    const target = standaloneBinaryPath.replace(/'/g, "''");
-    return `Invoke-WebRequest ${RELEASE_DOWNLOAD_URL}/openspec-windows-${process.arch}.exe -OutFile '${target}'`;
+    const dir = path.dirname(standaloneBinaryPath).replace(/'/g, "''");
+    return `$env:OPENSPEC_INSTALL_DIR='${dir}'; irm ${RELEASE_DOWNLOAD_URL}/install.ps1 | iex`;
   }
   const dir = path.dirname(standaloneBinaryPath).replace(/'/g, `'\\''`);
   return `curl -fsSL ${RELEASE_DOWNLOAD_URL}/install.sh | OPENSPEC_INSTALL_DIR='${dir}' sh`;
diff --git a/test/core/version-check.test.ts b/test/core/version-check.test.ts
index ae211bb7e6..0f7bc361ec 100644
--- a/test/core/version-check.test.ts
+++ b/test/core/version-check.test.ts
@@ -1272,7 +1272,7 @@ describe('standalone binary', () => {
 
     if (process.platform === 'win32') {
       expect(command).toBe(
-        `Invoke-WebRequest https://github.com/Fission-AI/OpenSpec/releases/latest/download/openspec-windows-${process.arch}.exe -OutFile '${executable.replace(/'/g, "''")}'`
+        `$env:OPENSPEC_INSTALL_DIR='${path.dirname(executable).replace(/'/g, "''")}'; irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex`
       );
     } else {
       expect(command).toMatch(

From a6eb5f2e380864bd4855f38f28a3fc1a6dcd3e3d Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Thu, 22 Oct 2026 09:31:55 -0500
Subject: [PATCH 10/27] test(cli): run the whole CLI test suite against each
 binary

OPENSPEC_TEST_BINARY points runCLI at a standalone binary instead of
`node dist/cli/index.js`, and scripts/binary/e2e.sh runs every CLI test
file that way (refusing to run if it finds none). CI now runs it on all
eight native runners, with Alpine in a node:22-alpine container as a
non-root user, and tests install.ps1 in PowerShell 7 and Windows
PowerShell 5.1, including that it keeps %VAR% user PATH entries intact.

Four tests encoded the source-checkout answer; they now expect what each
runtime should report (`standalone`, and the binary's schema copy in the
data dir).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/binaries.yml       | 67 ++++++++++++++++++++++++++--
 scripts/binary/e2e.sh                | 13 ++++++
 test/cli-e2e/basic.test.ts           | 14 +++---
 test/cli-e2e/store-lifecycle.test.ts |  8 +++-
 test/helpers/run-cli.ts              | 10 ++++-
 5 files changed, 100 insertions(+), 12 deletions(-)
 create mode 100755 scripts/binary/e2e.sh

diff --git a/.github/workflows/binaries.yml b/.github/workflows/binaries.yml
index 7892cc0e67..ff78227d1d 100644
--- a/.github/workflows/binaries.yml
+++ b/.github/workflows/binaries.yml
@@ -69,7 +69,7 @@ jobs:
         run: |
           cd dist-bin
           sha256sum openspec-* > SHA256SUMS
-          cp ../scripts/binary/install.sh .
+          cp ../scripts/binary/install.sh ../scripts/binary/install.ps1 .
           cat SHA256SUMS
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
@@ -82,7 +82,7 @@ jobs:
     name: Verify ${{ matrix.asset }}
     needs: build
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 15
+    timeout-minutes: 40
     strategy:
       fail-fast: false
       matrix:
@@ -151,6 +151,67 @@ jobs:
             cmp "$RUNNER_TEMP/bin/openspec" "dist-bin/openspec-$ASSET"
           fi
 
+      # Same as above for Windows, in both PowerShell 7 and the Windows
+      # PowerShell 5.1 every Windows 10/11 machine has, through `irm | iex`.
+      - name: Install script (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          Invoke-ScriptAnalyzer -Path scripts/binary/install.ps1 -Severity Warning,Error -ExcludeRule PSAvoidUsingWriteHost -EnableExit
+          $server = Start-Process python -ArgumentList '-m', 'http.server', '8765', '--directory', 'dist-bin' -PassThru -WindowStyle Hidden
+          foreach ($i in 1..40) { try { Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8765/SHA256SUMS | Out-Null; break } catch { Start-Sleep -Milliseconds 500 } }
+          # A user PATH entry that relies on expansion must survive untouched.
+          $key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
+          $before = [string]$key.GetValue('Path', '', 'DoNotExpandEnvironmentNames')
+          $key.SetValue('Path', "$before;%USERPROFILE%\openspec-path-probe", 'ExpandString')
+          try {
+            foreach ($shell in 'pwsh', 'powershell') {
+              $dir = Join-Path $env:RUNNER_TEMP "install $shell"
+              foreach ($run in 1, 2) {
+                & $shell -NoProfile -Command "`$env:OPENSPEC_DOWNLOAD_URL='http://127.0.0.1:8765'; `$env:OPENSPEC_INSTALL_DIR='$dir'; irm http://127.0.0.1:8765/install.ps1 | iex"
+                if ($LASTEXITCODE -ne 0) { throw "$shell install run $run failed" }
+              }
+              $exe = Join-Path $dir 'openspec.exe'
+              if ((Get-FileHash $exe).Hash -ne (Get-FileHash "dist-bin/openspec-$env:ASSET.exe").Hash) { throw "$shell installed the wrong file" }
+              & $exe --version
+              if ($LASTEXITCODE -ne 0) { throw "$shell's installed copy does not run" }
+              $raw = [string]$key.GetValue('Path', '', 'DoNotExpandEnvironmentNames')
+              if (@($raw -split ';' | Where-Object { $_ -eq $dir }).Count -ne 1) { throw "$shell did not add $dir to the user PATH exactly once: $raw" }
+              if ($raw -notlike '*%USERPROFILE%\openspec-path-probe*') { throw "$shell expanded the user PATH: $raw" }
+              if ($key.GetValueKind('Path') -ne 'ExpandString') { throw "$shell changed the user PATH type" }
+            }
+          } finally {
+            $key.SetValue('Path', $before, 'ExpandString')
+            $key.Close()
+            Stop-Process $server
+          }
+
+      # The repo's own CLI tests, run against this binary instead of Node.
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+        if: matrix.alpine == ''
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        if: matrix.alpine == ''
+        with:
+          node-version: '20.19.0'
+          package-manager-cache: false
+      - name: CLI test suite against the binary
+        run: |
+          if [ -n "$ALPINE" ]; then
+            # Copied in: the container installs its own (musl) dependencies.
+            # Run as a normal user; root can read files the tests make unreadable.
+            docker run --rm -v "$PWD:/src:ro" node:22-alpine sh -c \
+              "apk add -q --no-cache bash git libstdc++ libgcc && corepack enable &&
+               mkdir /w && cd /src && tar --exclude=./node_modules -cf - . | tar -xf - -C /w && chown -R node /w &&
+               su node -c 'cd /w && pnpm install --frozen-lockfile && pnpm run build &&
+                 bash scripts/binary/e2e.sh dist-bin/openspec-$ASSET'"
+          else
+            pnpm install --frozen-lockfile
+            pnpm run build
+            bin="dist-bin/openspec-$ASSET"
+            [ "$RUNNER_OS" = Windows ] && bin="$bin.exe"
+            bash scripts/binary/e2e.sh "$bin"
+          fi
+
   release:
     name: Attach to release
     needs: verify
@@ -170,4 +231,4 @@ jobs:
         run: |
           cd dist-bin
           sha256sum --check SHA256SUMS
-          gh release upload "$REF" openspec-* SHA256SUMS install.sh --clobber --repo "$GITHUB_REPOSITORY"
+          gh release upload "$REF" openspec-* SHA256SUMS install.sh install.ps1 --clobber --repo "$GITHUB_REPOSITORY"
diff --git a/scripts/binary/e2e.sh b/scripts/binary/e2e.sh
new file mode 100755
index 0000000000..0d3bf022df
--- /dev/null
+++ b/scripts/binary/e2e.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Runs every CLI test (each test file that uses runCLI) against a standalone
+# binary instead of `node dist/cli/index.js`. Needs `pnpm install`.
+#
+#   bash scripts/binary/e2e.sh dist-bin/openspec-<asset>
+set -euo pipefail
+
+files=()
+while IFS= read -r file; do files+=("$file"); done < <(grep -rl 'runCLI' test | grep '\.test\.ts$' | sort)
+# Without files vitest would run the whole suite and prove nothing about $1.
+[ "${#files[@]}" -gt 0 ] || { echo "No CLI test files found" >&2; exit 1; }
+echo "Running ${#files[@]} CLI test files against $1"
+OPENSPEC_TEST_BINARY="$1" pnpm exec vitest run "${files[@]}"
diff --git a/test/cli-e2e/basic.test.ts b/test/cli-e2e/basic.test.ts
index 285b66e8ba..a89c7a75c3 100644
--- a/test/cli-e2e/basic.test.ts
+++ b/test/cli-e2e/basic.test.ts
@@ -3,7 +3,7 @@ import { promises as fs, realpathSync } from 'fs';
 import path from 'path';
 import { tmpdir } from 'os';
 import { execFileSync } from 'node:child_process';
-import { runCLI, cliProjectRoot } from '../helpers/run-cli.js';
+import { runCLI, cliProjectRoot, testBinary } from '../helpers/run-cli.js';
 import { isolatedGitEnv } from '../helpers/store-git.js';
 import { AI_TOOLS } from '../../src/core/config.js';
 import { getGlobalDataDir, registerStore } from '../../src/core/index.js';
@@ -104,6 +104,10 @@ describe('openspec CLI e2e basics', () => {
   });
 
   describe('version command', () => {
+    // From this checkout the CLI is a source install; the binary knows it is one.
+    const scope = testBinary ? 'standalone' : 'source';
+    const installRoot = testBinary ? path.dirname(testBinary) : cliProjectRoot;
+
     it('reports local version and source install details outside an OpenSpec project', async () => {
       const cwd = await fs.mkdtemp(path.join(tmpdir(), 'openspec-version-empty-'));
       tempRoots.push(cwd);
@@ -113,7 +117,7 @@ describe('openspec CLI e2e basics', () => {
       const result = await runCLI(['version'], { cwd });
 
       expect(result.exitCode).toBe(0);
-      expect(result.stdout).toBe(`OpenSpec ${pkg.version} (source)\n`);
+      expect(result.stdout).toBe(`OpenSpec ${pkg.version} (${scope})\n`);
       expect(result.stderr).toBe('');
     });
 
@@ -129,10 +133,10 @@ describe('openspec CLI e2e basics', () => {
         install: {
           location: expect.any(String),
           packageManager: null,
-          scope: 'source',
+          scope,
         },
       });
-      expect(await fs.realpath(output.install.location)).toBe(await fs.realpath(cliProjectRoot));
+      expect(await fs.realpath(output.install.location)).toBe(await fs.realpath(installRoot));
     });
 
     it('reports a disabled update check as data and exits successfully', async () => {
@@ -158,7 +162,7 @@ describe('openspec CLI e2e basics', () => {
       });
 
       expect(result.exitCode).toBe(0);
-      expect(result.stdout).toMatch(/^OpenSpec \S+ \(source\)\nUpdate check disabled\.\n$/);
+      expect(result.stdout).toMatch(new RegExp(`^OpenSpec \\S+ \\(${scope}\\)\\nUpdate check disabled\\.\\n$`));
       expect(result.stderr).toBe('');
     });
 
diff --git a/test/cli-e2e/store-lifecycle.test.ts b/test/cli-e2e/store-lifecycle.test.ts
index 39c79da9d8..4caf2a0b04 100644
--- a/test/cli-e2e/store-lifecycle.test.ts
+++ b/test/cli-e2e/store-lifecycle.test.ts
@@ -4,7 +4,7 @@ import { promises as fs, realpathSync } from 'fs';
 import path from 'path';
 import { tmpdir } from 'os';
 import { promisify } from 'util';
-import { runCLI } from '../helpers/run-cli.js';
+import { runCLI, testBinary } from '../helpers/run-cli.js';
 import { cleanupTempPath } from '../helpers/temp-cleanup.js';
 
 const execFileAsync = promisify(execFile);
@@ -480,7 +480,11 @@ describe('standalone store lifecycle journey', () => {
         path.join(env.XDG_DATA_HOME as string, 'openspec'),
         new Set()
       );
-      expect(dataEntries).toEqual(['stores/', 'stores/registry.yaml']);
+      // The standalone binary also keeps its built-in schemas here.
+      const planningState = testBinary
+        ? dataEntries.filter((entry) => !entry.startsWith('binary-schemas/'))
+        : dataEntries;
+      expect(planningState).toEqual(['stores/', 'stores/registry.yaml']);
     }
   });
 
diff --git a/test/helpers/run-cli.ts b/test/helpers/run-cli.ts
index 3c0cf43f77..3a8b70698b 100644
--- a/test/helpers/run-cli.ts
+++ b/test/helpers/run-cli.ts
@@ -10,6 +10,9 @@ const __dirname = path.dirname(__filename);
 const projectRoot = path.resolve(__dirname, '..', '..');
 const cliEntry = path.join(projectRoot, 'dist', 'cli', 'index.js');
 const DEFAULT_CLI_TIMEOUT_MS = 30_000;
+// Set to a standalone binary (scripts/binary/build.mjs) to run every CLI test
+// against it instead of `node dist/cli/index.js`.
+export const testBinary = process.env.OPENSPEC_TEST_BINARY ? path.resolve(process.env.OPENSPEC_TEST_BINARY) : undefined;
 
 let buildPromise: Promise<void> | undefined;
 const activeCliChildren = new Set<ChildProcess>();
@@ -135,9 +138,12 @@ export async function ensureCliBuilt() {
 }
 
 export async function runCLI(args: string[] = [], options: RunCLIOptions = {}): Promise<RunCLIResult> {
-  await ensureCliBuilt();
+  if (!testBinary) await ensureCliBuilt();
 
   const finalArgs = Array.isArray(args) ? args : [args];
+  const [command, commandArgs] = testBinary
+    ? [testBinary, finalArgs]
+    : [process.execPath, [cliEntry, ...finalArgs]];
   const invocation = [cliEntry, ...finalArgs].join(' ');
   const explicitConfigHome = options.env?.XDG_CONFIG_HOME;
   const isolatedConfigHome =
@@ -147,7 +153,7 @@ export async function runCLI(args: string[] = [], options: RunCLIOptions = {}):
 
   return new Promise<RunCLIResult>((resolve, reject) => {
     const timeoutMs = options.timeoutMs ?? DEFAULT_CLI_TIMEOUT_MS;
-    const child = spawn(process.execPath, [cliEntry, ...finalArgs], {
+    const child = spawn(command, commandArgs, {
       cwd: options.cwd ?? projectRoot,
       env: mergeEnv(
         process.env,

From beb8ab94c3e0f52af82048e9846cb871a0810890 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Thu, 22 Oct 2026 09:31:55 -0500
Subject: [PATCH 11/27] docs(installation): make the standalone binary the
 default install

README, the installation guide, getting started, the AI setup prompt and
install.md now lead with the one-line installers; npm, Homebrew and the
other package managers stay as the alternative, with the Node.js 20.19+
requirement moved to them. Adds a minor changeset so the release that
ships the binaries announces them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/standalone-binary.md |  5 ++
 README.md                       | 20 +++++---
 docs/README.md                  |  4 +-
 docs/getting-started.md         |  4 +-
 docs/installation.md            | 91 ++++++++++++++++++---------------
 install.md                      | 25 ++++++---
 scripts/README.md               | 26 +++++-----
 7 files changed, 103 insertions(+), 72 deletions(-)
 create mode 100644 .changeset/standalone-binary.md

diff --git a/.changeset/standalone-binary.md b/.changeset/standalone-binary.md
new file mode 100644
index 0000000000..94c1e3ba4e
--- /dev/null
+++ b/.changeset/standalone-binary.md
@@ -0,0 +1,5 @@
+---
+'@fission-ai/openspec': minor
+---
+
+OpenSpec now installs as a single file with no Node.js needed: `curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh` on macOS and Linux, or `irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex` on Windows. Every release now includes binaries for macOS, Linux (glibc and musl) and Windows on x64 and arm64, with `SHA256SUMS`. npm and the other package managers keep working as before.
diff --git a/README.md b/README.md
index 5839c5d783..e85777f478 100644
--- a/README.md
+++ b/README.md
@@ -117,20 +117,22 @@ Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the har
 
 ## Quick Start
 
-**Requires Node.js 20.19.0 or higher.** Homebrew installs it as a dependency.
+Install OpenSpec. It is a single file with nothing else to install, not even Node.js.
 
-Install OpenSpec globally:
+macOS and Linux:
 
 ```bash
-npm install -g @fission-ai/openspec@latest
+curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
 ```
 
-Or install the official [Homebrew formula](https://formulae.brew.sh/formula/openspec) on macOS or Linux:
+Windows (PowerShell):
 
-```bash
-brew install openspec
+```powershell
+irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex
 ```
 
+Prefer a package manager? `npm install -g @fission-ai/openspec@latest` (needs Node.js 20.19.0 or higher) or the official [Homebrew formula](https://formulae.brew.sh/formula/openspec), `brew install openspec`.
+
 Then navigate to your project directory and initialize:
 
 ```bash
@@ -152,7 +154,7 @@ Both are in the default profile. If you want the expanded workflow (`/opsx:new`,
 > [!NOTE]
 > Not sure if your tool is supported? [View the full list](https://openspec.dev/docs/supported-tools) – we support 30+ tools and growing.
 >
-> Also works with Homebrew, pnpm, yarn, bun, and Nix. [See installation options](https://openspec.dev/docs/installation).
+> Also works with npm, Homebrew, pnpm, yarn, bun, and Nix. [See installation options](https://openspec.dev/docs/installation).
 
 ## Docs
 
@@ -192,7 +194,9 @@ AI coding assistants are powerful but unpredictable when requirements live only
 
 ## Updating OpenSpec
 
-**Upgrade the package**
+**Upgrade the CLI**
+
+Run the install command from [Quick Start](#quick-start) again. If you installed with npm:
 
 ```bash
 npm install -g @fission-ai/openspec@latest
diff --git a/docs/README.md b/docs/README.md
index 0b3f1f2135..43259431b0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -99,7 +99,7 @@ That second one matters more than it looks. OpenSpec has two halves: a command l
 ## The thirty-second version
 
 ```text
-1. Install        npm install -g @fission-ai/openspec@latest
+1. Install        curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
 2. Initialize     cd your-project && openspec init
 3. Explore        (in your AI chat)  /opsx:explore           ← optional, but a great habit
 4. Propose        (in your AI chat)  /opsx:propose add-dark-mode
@@ -107,7 +107,7 @@ That second one matters more than it looks. OpenSpec has two halves: a command l
 6. Archive        (in your AI chat)  /opsx:archive
 ```
 
-Steps 1 and 2 happen in your terminal. The rest happen in your AI assistant's chat. That split is the one thing worth memorizing, and [How Commands Work](how-commands-work.md) explains exactly why. Step 3 is optional, but starting with `/opsx:explore` when you're unsure is the habit most worth forming.
+Steps 1 and 2 happen in your terminal (for Windows or npm, see [Installation](installation.md)). The rest happen in your AI assistant's chat. That split is the one thing worth memorizing, and [How Commands Work](how-commands-work.md) explains exactly why. Step 3 is optional, but starting with `/opsx:explore` when you're unsure is the habit most worth forming.
 
 ## Where else to get help
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 373efa186d..852ca84b61 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -14,7 +14,7 @@ This guide explains how OpenSpec works after you've installed and initialized it
 The whole loop, with each step labeled by where it happens:
 
 ```text
-TERMINAL   $ npm install -g @fission-ai/openspec@latest
+TERMINAL   $ curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
 TERMINAL   $ cd your-project && openspec init
 AI CHAT      /opsx:explore                    (optional: think it through first)
 AI CHAT      /opsx:propose add-dark-mode      (AI drafts the plan; you review it)
@@ -22,7 +22,7 @@ AI CHAT      /opsx:apply                      (AI builds it)
 AI CHAT      /opsx:archive                    (specs updated, change filed away)
 ```
 
-Two terminal steps to set up, then you live in chat. The rest of this guide unpacks what each step does and what you'll see.
+Two terminal steps to set up, then you live in chat. (Windows, npm, and other ways to install are in [Installation](installation.md).) The rest of this guide unpacks what each step does and what you'll see.
 
 **Don't want to do the terminal part yourself?** Paste the [setup prompt](installation.md#install-with-your-ai-assistant) into your assistant and it handles both lines, then reports what it created.
 
diff --git a/docs/installation.md b/docs/installation.md
index 9d32e0b636..38201718d5 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,29 +1,58 @@
 # Installation
 
-## Prerequisites
+## Install
 
-- **Node.js 20.19.0 or higher** — Check your version: `node --version`. Not needed for the [standalone binary](#standalone-binary-no-nodejs).
+OpenSpec is a single file. It has nothing else to install, not even Node.js.
+
+macOS and Linux:
+
+```bash
+curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```powershell
+irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex
+```
+
+The installer picks the right file for your machine, checks it against the release's `SHA256SUMS`, and installs it to `~/.local/bin` (Windows: `%LOCALAPPDATA%\Programs\openspec`, added to your user `PATH`). Set `OPENSPEC_INSTALL_DIR` to choose another folder, or `OPENSPEC_VERSION=v1.15.0` to pin a release. Prefer npm or another package manager? See [Package Managers](#package-managers).
+
+To install by hand, download your platform's file from the [latest release](https://github.com/Fission-AI/OpenSpec/releases/latest), rename it to `openspec` (`openspec.exe` on Windows), and put it on your `PATH`:
+
+| Platform | File |
+|---|---|
+| macOS 13+ (Apple Silicon / Intel) | `openspec-darwin-arm64` / `openspec-darwin-x64` |
+| Linux (glibc 2.17+) | `openspec-linux-x64` / `openspec-linux-arm64` |
+| Alpine 3.17+ (needs `apk add libstdc++ libgcc`) | `openspec-linux-x64-musl` / `openspec-linux-arm64-musl` |
+| Windows 10+ | `openspec-windows-x64.exe` / `openspec-windows-arm64.exe` |
+
+On macOS, a file downloaded with a browser is blocked until you run `xattr -d com.apple.quarantine openspec`; the install script avoids this. On Windows, SmartScreen may warn the first time you run it from Explorer.
 
 ## Install with your AI assistant
 
 Rather not do this by hand? Paste the prompt below into any coding assistant that can run shell commands — Claude Code, Codex, Cursor, Gemini CLI, Copilot, and the rest of the [supported tools](supported-tools.md). It installs the CLI, initializes this project, and reports back what actually happened.
 
-The manual steps below are the source of truth — the prompt just runs them for you. If your assistant stops and hands something back, that's by design: it asks before anything privileged and never edits your shell startup files. Finish those bits yourself with [Package Managers](#package-managers) and [Troubleshooting](troubleshooting.md).
+The manual steps below are the source of truth — the prompt just runs them for you. If your assistant stops and hands something back, that's by design: it asks before anything privileged and never edits your shell startup files. Finish those bits yourself with [Install](#install) and [Troubleshooting](troubleshooting.md).
 
 ```text
 Install OpenSpec in this project and set it up for me. Follow these steps in
 order, and stop where a step tells you to stop.
 
-1. RUNTIME. Run `node --version`. OpenSpec needs Node.js 20.19.0 or higher. If
-   Node is missing or older, don't install Node, switch versions, or
-   reconfigure my version manager for me. Offer the standalone binary instead,
-   which needs no Node. On macOS or Linux, show me this command and run it only
-   once I confirm, then skip to step 3:
-     curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
-   On Windows, or if I decline or it fails, point me at the "Standalone binary"
-   section of the OpenSpec installation docs and stop.
-
-2. INSTALL. Use whichever package manager is already on my PATH, preferring npm:
+1. INSTALL. Run `openspec --version` first; if it prints a version, OpenSpec is
+   already installed, so offer to update it with the command below and skip to
+   step 3 if I decline. Otherwise install the standalone OpenSpec binary, which
+   needs nothing else, not even Node.js. Show me the command for my OS and run
+   it only once I confirm, then skip to step 3:
+     macOS / Linux:        curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+     Windows (PowerShell): irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex
+   If I'd rather use a package manager, or the installer fails, go to step 2.
+
+2. PACKAGE MANAGER (only if step 1 did not install it). Run `node --version`:
+   this needs Node.js 20.19.0 or higher. If Node is missing or older, say so and
+   stop — don't install Node, switch versions, or reconfigure my version
+   manager for me. Otherwise use whichever package manager is already on my
+   PATH, preferring npm:
      npm install -g @fission-ai/openspec@latest
      pnpm add -g @fission-ai/openspec@latest
      bun add -g @fission-ai/openspec@latest
@@ -83,6 +112,8 @@ Nothing in the prompt is vendor-specific: it's plain instructions plus the same
 
 ## Package Managers
 
+Installing with a package manager needs **Node.js 20.19.0 or higher** (check with `node --version`).
+
 ### npm
 
 ```bash
@@ -129,27 +160,6 @@ You still need Node.js 20.19.0 or higher available on `PATH`.
 bun add -g @fission-ai/openspec@latest
 ```
 
-## Standalone binary (no Node.js)
-
-Each [GitHub release](https://github.com/Fission-AI/OpenSpec/releases) includes a single-file `openspec` executable for every platform, with Node built in. On macOS or Linux:
-
-```bash
-curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
-```
-
-The script picks the right file for your machine, checks it against the release's `SHA256SUMS`, and installs it to `~/.local/bin` (set `OPENSPEC_INSTALL_DIR` to change that, or `OPENSPEC_VERSION=v1.15.0` to pin a release).
-
-To install by hand, download your platform's file, rename it to `openspec` (`openspec.exe` on Windows), and put it on your `PATH`:
-
-| Platform | File |
-|---|---|
-| macOS 13+ (Apple Silicon / Intel) | `openspec-darwin-arm64` / `openspec-darwin-x64` |
-| Linux (glibc 2.17+) | `openspec-linux-x64` / `openspec-linux-arm64` |
-| Alpine 3.17+ (needs `apk add libstdc++ libgcc`) | `openspec-linux-x64-musl` / `openspec-linux-arm64-musl` |
-| Windows 10+ | `openspec-windows-x64.exe` / `openspec-windows-arm64.exe` |
-
-On macOS, a file downloaded with a browser is blocked until you run `xattr -d com.apple.quarantine openspec`; the install script avoids this. On Windows, SmartScreen may warn the first time you run it from Explorer.
-
 ## Nix
 
 Run OpenSpec directly without installation:
@@ -189,28 +199,25 @@ openspec --version
 
 ## Updating
 
-Upgrade the package, then refresh each project's generated files:
+Upgrade the CLI by running the [install command](#install) again (with a package manager: `npm install -g @fission-ai/openspec@latest` or its pnpm/yarn/bun equivalent). Then refresh each project's generated files:
 
 ```bash
-npm install -g @fission-ai/openspec@latest   # or pnpm/yarn/bun equivalent
-openspec update                              # run inside each project
+openspec update   # run inside each project
 ```
 
-With the standalone binary, run the install script again (or download the new file) instead of the package manager command.
-
 `openspec update` regenerates the skill and command files for the tools you've configured, so your slash commands stay current with the installed version. It also checks whether a newer CLI has been published and offers to upgrade, since upgrading is what makes new workflows available in the first place — see [CLI Reference](cli.md#openspec-update).
 
 ## Uninstalling
 
-There's no `openspec uninstall` command, because OpenSpec is just a global package plus some files in your project. Removing it is a few manual steps, and nothing here touches your source code.
+There's no `openspec uninstall` command, because OpenSpec is just one program plus some files in your project. Removing it is a few manual steps, and nothing here touches your source code.
 
-**1. Remove the global package:**
+**1. Remove the CLI.** Delete the file the installer put in place: `~/.local/bin/openspec`, or on Windows `%LOCALAPPDATA%\Programs\openspec\openspec.exe` (and that folder from your user `PATH`). If you installed with a package manager:
 
 ```bash
 npm uninstall -g @fission-ai/openspec   # or: pnpm rm -g / yarn global remove / bun rm -g
 ```
 
-With the standalone binary, delete the file instead (`rm ~/.local/bin/openspec` if you used the install script). When that directory is writable, it also keeps a copy of its built-in schemas under your OpenSpec data directory (`~/.local/share/openspec/binary-schemas` on macOS and Linux, `%LOCALAPPDATA%\openspec\binary-schemas` on Windows), which you can delete too.
+The standalone binary also keeps, when that directory is writable, a copy of its built-in schemas under your OpenSpec data directory (`~/.local/share/openspec/binary-schemas` on macOS and Linux, `%LOCALAPPDATA%\openspec\binary-schemas` on Windows), which you can delete too.
 
 **2. Remove OpenSpec from a project (optional).** Delete the `openspec/` directory if you no longer want its specs and changes:
 
diff --git a/install.md b/install.md
index fd1401f99b..878f41b014 100644
--- a/install.md
+++ b/install.md
@@ -14,19 +14,32 @@ DONE WHEN:
 
 TODO:
 
-- [ ] Check the Node.js runtime
-- [ ] Install the CLI globally, with the user's confirmation
+- [ ] Install the standalone CLI, with the user's confirmation (npm only as a fallback)
 - [ ] Verify `openspec` is on PATH
 - [ ] Confirm which folder to set up, then run `openspec init --tools <ids>` there
 - [ ] Report what init actually created and how to invoke it
 
-## 1. Runtime
+## 1. Install
 
-Run `node --version`. OpenSpec needs Node.js 20.19.0 or higher. If Node is missing or older, don't install Node, switch versions, or reconfigure the user's version manager yourself. Offer the standalone binary instead, which needs no Node: on macOS or Linux, show `curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh`, run it only once the user confirms, then skip to step 3. On Windows, or if the user declines or it fails, stop and leave them with their next move: the standalone binary section of https://openspec.dev/docs/installation, https://nodejs.org, or, if they use a version manager like nvm, the command that would switch to a newer version.
+Run `openspec --version` first. If it already prints a version, the CLI is installed: say so, offer to update it with the install command below, and if the user declines skip ahead to step 4.
 
-## 2. Install
+Install the standalone OpenSpec binary. It is a single file and needs nothing else, not even Node.js. Show the command for the user's OS and run it only once they confirm, then skip to step 3:
 
-Run `openspec --version` first. If it already prints a version, the CLI is installed: say so, offer to update it with the install command below, and if the user declines skip ahead to step 4.
+```bash
+# macOS / Linux
+curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+```
+
+```powershell
+# Windows (PowerShell)
+irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex
+```
+
+If the user would rather use a package manager, or the installer fails, continue with step 2.
+
+## 2. Package manager (only if step 1 did not install it)
+
+Run `node --version`. Installing with a package manager needs Node.js 20.19.0 or higher. If Node is missing or older, don't install Node, switch versions, or reconfigure the user's version manager yourself; stop and leave them with their next move: https://nodejs.org, or, if they use a version manager like nvm, the command that would switch to a newer version.
 
 Use whichever package manager is already on PATH, preferring npm:
 
diff --git a/scripts/README.md b/scripts/README.md
index 03c5292156..2d1d82842f 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -73,21 +73,23 @@ Validates package version consistency before publishing.
 
 ## binary/
 
-Builds standalone `openspec` executables with Bun, for people without Node.js.
-`.github/workflows/binaries.yml` cross-compiles every asset on Linux, tests
-each on its own OS and CPU (Alpine for the musl ones), and attaches them,
-`SHA256SUMS`, and `install.sh` to each published release.
+Builds the standalone `openspec` executables (no Node.js needed), the default
+way users install OpenSpec. `.github/workflows/binaries.yml` cross-compiles
+every asset on Linux, tests each on its own OS and CPU, and attaches them,
+`SHA256SUMS`, `install.sh` and `install.ps1` to each published release.
+
+| File | What it is |
+|---|---|
+| `build.mjs` | Builds assets into `dist-bin/` (run `pnpm build` first) |
+| `entry.mjs` | The binary's entry point: embedded schemas, upgrade advice |
+| `install.sh` / `install.ps1` | The installers users run (macOS/Linux, Windows) |
+| `smoke.sh` | Quick check of one binary |
+| `e2e.sh` | Runs every CLI test against one binary instead of Node |
 
-**Usage**:
 ```bash
 pnpm build
-bun scripts/binary/build.mjs                    # this machine → dist-bin/
+bun scripts/binary/build.mjs                    # this machine
 bun scripts/binary/build.mjs --all              # every release asset
-bun scripts/binary/build.mjs linux-x64-musl     # named assets (see ASSETS in build.mjs)
 bash scripts/binary/smoke.sh dist-bin/openspec-<asset>
+bash scripts/binary/e2e.sh dist-bin/openspec-<asset>
 ```
-
-The binary has no package directory, so `build.mjs` bundles `package.json`
-and embeds `schemas/`; `entry.mjs` writes them to
-`<data dir>/binary-schemas/<content hash>/` the first time a command needs
-them, and rewrites that copy if it was edited or partly deleted.

From f568ef03772e2863c0cb5bd59bc9ea4293eb7ede Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Thu, 22 Oct 2026 09:47:06 -0500
Subject: [PATCH 12/27] fix(cli): log why the installer's launch check failed

PSScriptAnalyzer flags an empty catch block, which failed the Windows
verify jobs before the CLI test suite ran.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/binary/install.ps1 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scripts/binary/install.ps1 b/scripts/binary/install.ps1
index b86d37bde3..270d33ce41 100644
--- a/scripts/binary/install.ps1
+++ b/scripts/binary/install.ps1
@@ -57,7 +57,8 @@
     if ($actual -ne $expected) { throw "openspec install: checksum mismatch for $asset; refusing to install" }
 
     $installed = $null
-    try { $installed = & $exe --version } catch {}
+    # A binary that cannot start at all throws instead of setting an exit code.
+    try { $installed = & $exe --version } catch { Write-Verbose "openspec --version failed: $_" }
     if ($LASTEXITCODE -ne 0 -or -not $installed) {
       throw "openspec install: the downloaded $asset does not run on this machine (needs Windows 10 or later)"
     }

From 9334a8c1853df74db6197d320fee85a1bef606b8 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Thu, 22 Oct 2026 11:16:05 -0500
Subject: [PATCH 13/27] fix(cli): upgrade the binary the user actually runs

- Upgrade advice passes the binary's own file name when it isn't the
  default (`openspec-darwin-arm64` kept as downloaded), so the installer
  replaces that file instead of writing a second one beside it. Both
  installers take OPENSPEC_INSTALL_NAME for this.
- Both installers resolve a relative OPENSPEC_INSTALL_DIR first, so the
  PATH advice (and the Windows user PATH entry) work from any directory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/binaries.yml  |  9 +++++++++
 scripts/binary/install.ps1      |  6 +++++-
 scripts/binary/install.sh       |  8 ++++++--
 src/core/version-check.ts       | 15 ++++++++++-----
 test/core/version-check.test.ts | 23 +++++++++++++++++++++++
 5 files changed, 53 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/binaries.yml b/.github/workflows/binaries.yml
index ff78227d1d..ee8135d7e7 100644
--- a/.github/workflows/binaries.yml
+++ b/.github/workflows/binaries.yml
@@ -180,6 +180,15 @@ jobs:
               if ($raw -notlike '*%USERPROFILE%\openspec-path-probe*') { throw "$shell expanded the user PATH: $raw" }
               if ($key.GetValueKind('Path') -ne 'ExpandString') { throw "$shell changed the user PATH type" }
             }
+            # A relative folder is saved to PATH as an absolute one; a custom name is kept.
+            Push-Location $env:RUNNER_TEMP
+            pwsh -NoProfile -Command "`$env:OPENSPEC_DOWNLOAD_URL='http://127.0.0.1:8765'; `$env:OPENSPEC_INSTALL_DIR='relative install'; `$env:OPENSPEC_INSTALL_NAME='openspec-renamed.exe'; irm http://127.0.0.1:8765/install.ps1 | iex"
+            Pop-Location
+            if ($LASTEXITCODE -ne 0) { throw 'relative install failed' }
+            $abs = Join-Path $env:RUNNER_TEMP 'relative install'
+            if (-not (Test-Path (Join-Path $abs 'openspec-renamed.exe'))) { throw 'custom name not used' }
+            $raw = [string]$key.GetValue('Path', '', 'DoNotExpandEnvironmentNames')
+            if (($raw -split ';') -notcontains $abs) { throw "relative folder not saved as $abs : $raw" }
           } finally {
             $key.SetValue('Path', $before, 'ExpandString')
             $key.Close()
diff --git a/scripts/binary/install.ps1 b/scripts/binary/install.ps1
index 270d33ce41..99798fa472 100644
--- a/scripts/binary/install.ps1
+++ b/scripts/binary/install.ps1
@@ -4,6 +4,7 @@
 #
 # $env:OPENSPEC_VERSION      release to install (default: latest), e.g. v1.15.0
 # $env:OPENSPEC_INSTALL_DIR  where to put it (default: %LOCALAPPDATA%\Programs\openspec)
+# $env:OPENSPEC_INSTALL_NAME file name to install as (default: openspec.exe)
 # $env:OPENSPEC_DOWNLOAD_URL base URL of the release assets (mirrors, testing)
 #
 # Runs in Windows PowerShell 5.1 and PowerShell 7. It throws instead of
@@ -34,6 +35,9 @@
     "https://github.com/Fission-AI/OpenSpec/releases/download/$version"
   }
   $dir = if ($env:OPENSPEC_INSTALL_DIR) { $env:OPENSPEC_INSTALL_DIR } else { Join-Path $env:LOCALAPPDATA 'Programs\openspec' }
+  # Absolute, so the user PATH entry works from any directory.
+  $dir = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($dir)
+  $name = if ($env:OPENSPEC_INSTALL_NAME) { $env:OPENSPEC_INSTALL_NAME } else { 'openspec.exe' }
 
   # Staged inside the install dir so the final move is a same-volume rename.
   New-Item -ItemType Directory -Force -Path $dir | Out-Null
@@ -63,7 +67,7 @@
       throw "openspec install: the downloaded $asset does not run on this machine (needs Windows 10 or later)"
     }
 
-    $target = Join-Path $dir 'openspec.exe'
+    $target = Join-Path $dir $name
     try {
       Move-Item -Force -Path $exe -Destination $target
     } catch {
diff --git a/scripts/binary/install.sh b/scripts/binary/install.sh
index d2824b0a7a..d2e4c4f6cc 100644
--- a/scripts/binary/install.sh
+++ b/scripts/binary/install.sh
@@ -5,6 +5,7 @@
 #
 # OPENSPEC_VERSION      release to install (default: latest), e.g. v1.15.0
 # OPENSPEC_INSTALL_DIR  where to put it (default: ~/.local/bin)
+# OPENSPEC_INSTALL_NAME file name to install as (default: openspec)
 # OPENSPEC_DOWNLOAD_URL base URL of the release assets (mirrors, testing)
 set -eu
 
@@ -55,6 +56,9 @@ main() {
   # Staged inside the install dir, not /tmp: /tmp is often mounted noexec, and
   # a same-filesystem mv replaces an existing copy atomically.
   mkdir -p "$dir" || fail "cannot create $dir"
+  # Absolute, so the PATH advice below works from any directory.
+  dir=$(cd "$dir" && pwd) || fail "cannot use $dir"
+  name="${OPENSPEC_INSTALL_NAME:-openspec}"
   tmp=$(mktemp -d "$dir/.openspec-install.XXXXXX") || fail "cannot write to $dir"
   trap 'rm -rf "$tmp"' EXIT
   download() {
@@ -89,8 +93,8 @@ main() {
       *) fail "the downloaded $asset does not run on this machine" ;;
     esac
   fi
-  mv -f "$tmp/$asset" "$dir/openspec"
-  echo "Installed openspec $installed to $dir/openspec"
+  mv -f "$tmp/$asset" "$dir/$name"
+  echo "Installed openspec $installed to $dir/$name"
 
   case ":$PATH:" in
     *":$dir:"*) ;;
diff --git a/src/core/version-check.ts b/src/core/version-check.ts
index 0de587fe0b..cf21f22e4a 100644
--- a/src/core/version-check.ts
+++ b/src/core/version-check.ts
@@ -44,12 +44,17 @@ export function markStandaloneBinary(executablePath: string): void {
  */
 function standaloneUpgradeCommand(): string | null {
   if (!standaloneBinaryPath) return null;
+  const dir = path.dirname(standaloneBinaryPath);
+  const name = path.basename(standaloneBinaryPath);
   if (process.platform === 'win32') {
-    const dir = path.dirname(standaloneBinaryPath).replace(/'/g, "''");
-    return `$env:OPENSPEC_INSTALL_DIR='${dir}'; irm ${RELEASE_DOWNLOAD_URL}/install.ps1 | iex`;
-  }
-  const dir = path.dirname(standaloneBinaryPath).replace(/'/g, `'\\''`);
-  return `curl -fsSL ${RELEASE_DOWNLOAD_URL}/install.sh | OPENSPEC_INSTALL_DIR='${dir}' sh`;
+    const quote = (value: string) => `'${value.replace(/'/g, "''")}'`;
+    // A binary kept under its download name is replaced under that name.
+    const setName = name.toLowerCase() === 'openspec.exe' ? '' : ` $env:OPENSPEC_INSTALL_NAME=${quote(name)};`;
+    return `$env:OPENSPEC_INSTALL_DIR=${quote(dir)};${setName} irm ${RELEASE_DOWNLOAD_URL}/install.ps1 | iex`;
+  }
+  const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`;
+  const setName = name === 'openspec' ? '' : ` OPENSPEC_INSTALL_NAME=${quote(name)}`;
+  return `curl -fsSL ${RELEASE_DOWNLOAD_URL}/install.sh | OPENSPEC_INSTALL_DIR=${quote(dir)}${setName} sh`;
 }
 
 /**
diff --git a/test/core/version-check.test.ts b/test/core/version-check.test.ts
index 0f7bc361ec..fe5e2a6d66 100644
--- a/test/core/version-check.test.ts
+++ b/test/core/version-check.test.ts
@@ -1289,3 +1289,26 @@ describe('standalone binary', () => {
     expect(canSelfUpgrade(null, PROJECT_ROOT)).toBe(false);
   });
 });
+
+describe('standalone binary kept under its download name', () => {
+  it('upgrades the file the user actually runs', async () => {
+    const name = process.platform === 'win32' ? `openspec-windows-${process.arch}.exe` : `openspec-${process.platform}-${process.arch}`;
+    const executable = path.join(os.tmpdir(), "it's bin", name);
+    vi.resetModules();
+    const { markStandaloneBinary, getCliInstallInfo, getCliUpdateCommand } = await import('../../src/core/version-check.js');
+    markStandaloneBinary(executable);
+    const command = getCliUpdateCommand(getCliInstallInfo(null))!;
+
+    if (process.platform === 'win32') {
+      expect(command).toContain(`$env:OPENSPEC_INSTALL_NAME='${name}';`);
+    } else {
+      // Both variables read back exactly once a shell parses the command.
+      const vars = command.match(/\| (OPENSPEC_INSTALL_DIR=.*) sh$/)![1];
+      const { execFileSync } = await import('child_process');
+      const read = execFileSync('sh', ['-c', `${vars} sh -c 'printf "%s|%s" "$OPENSPEC_INSTALL_DIR" "$OPENSPEC_INSTALL_NAME"'`], {
+        encoding: 'utf8',
+      });
+      expect(read).toBe(`${path.dirname(executable)}|${name}`);
+    }
+  });
+});

From 38847b7a668ea49027b4e55b9e252ed5b068290d Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Thu, 22 Oct 2026 11:16:05 -0500
Subject: [PATCH 14/27] test(cli): report the executable runCLI actually ran

With OPENSPEC_TEST_BINARY set, failures named `node dist/cli/index.js`
instead of the binary under test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 test/helpers/run-cli.ts | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/test/helpers/run-cli.ts b/test/helpers/run-cli.ts
index 3a8b70698b..fff568bf97 100644
--- a/test/helpers/run-cli.ts
+++ b/test/helpers/run-cli.ts
@@ -144,7 +144,8 @@ export async function runCLI(args: string[] = [], options: RunCLIOptions = {}):
   const [command, commandArgs] = testBinary
     ? [testBinary, finalArgs]
     : [process.execPath, [cliEntry, ...finalArgs]];
-  const invocation = [cliEntry, ...finalArgs].join(' ');
+  // What actually runs, so a failure names the binary when testing one.
+  const invocation = [command, ...commandArgs].join(' ');
   const explicitConfigHome = options.env?.XDG_CONFIG_HOME;
   const isolatedConfigHome =
     explicitConfigHome !== undefined
@@ -213,7 +214,7 @@ export async function runCLI(args: string[] = [], options: RunCLIOptions = {}):
         reject(
           new Error(
             [
-              `CLI command timed out after ${timeoutMs}ms: node ${invocation}`,
+              `CLI command timed out after ${timeoutMs}ms: ${invocation}`,
               stderr ? `stderr tail:\n${formatOutputTail(stderr)}` : '',
               stdout ? `stdout tail:\n${formatOutputTail(stdout)}` : '',
             ]
@@ -229,7 +230,7 @@ export async function runCLI(args: string[] = [], options: RunCLIOptions = {}):
         stdout,
         stderr,
         timedOut,
-        command: `node ${invocation}`,
+        command: invocation,
       });
     });
 

From e2a917444521737119cbe226247e3625efd54cf9 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Thu, 22 Oct 2026 11:16:05 -0500
Subject: [PATCH 15/27] docs(installation): update installs the way they were
 made

- The setup prompt and install.md update an existing install with the
  command `openspec version --check` prints for it, instead of offering
  the binary installer and leaving two copies on PATH.
- The PATH step covers where the standalone installer puts the binary.
- Alpine's libstdc++ prerequisite is stated where "no Node.js" is
  claimed, and manual Unix installs include `chmod +x`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md            |  2 +-
 docs/installation.md | 24 ++++++++++++++----------
 install.md           |  6 +++---
 3 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index e85777f478..b68088ef6b 100644
--- a/README.md
+++ b/README.md
@@ -117,7 +117,7 @@ Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the har
 
 ## Quick Start
 
-Install OpenSpec. It is a single file with nothing else to install, not even Node.js.
+Install OpenSpec. It is a single file and needs no Node.js (on Alpine Linux, first run `apk add libstdc++ libgcc`).
 
 macOS and Linux:
 
diff --git a/docs/installation.md b/docs/installation.md
index 38201718d5..39135b249c 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -2,7 +2,7 @@
 
 ## Install
 
-OpenSpec is a single file. It has nothing else to install, not even Node.js.
+OpenSpec is a single file. It needs no Node.js or anything else (on Alpine Linux, first run `apk add libstdc++ libgcc`).
 
 macOS and Linux:
 
@@ -18,7 +18,7 @@ irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1
 
 The installer picks the right file for your machine, checks it against the release's `SHA256SUMS`, and installs it to `~/.local/bin` (Windows: `%LOCALAPPDATA%\Programs\openspec`, added to your user `PATH`). Set `OPENSPEC_INSTALL_DIR` to choose another folder, or `OPENSPEC_VERSION=v1.15.0` to pin a release. Prefer npm or another package manager? See [Package Managers](#package-managers).
 
-To install by hand, download your platform's file from the [latest release](https://github.com/Fission-AI/OpenSpec/releases/latest), rename it to `openspec` (`openspec.exe` on Windows), and put it on your `PATH`:
+To install by hand, download your platform's file from the [latest release](https://github.com/Fission-AI/OpenSpec/releases/latest), rename it to `openspec` (`openspec.exe` on Windows), make it executable on macOS and Linux (`chmod +x openspec`), and put it on your `PATH`:
 
 | Platform | File |
 |---|---|
@@ -39,11 +39,13 @@ The manual steps below are the source of truth — the prompt just runs them for
 Install OpenSpec in this project and set it up for me. Follow these steps in
 order, and stop where a step tells you to stop.
 
-1. INSTALL. Run `openspec --version` first; if it prints a version, OpenSpec is
-   already installed, so offer to update it with the command below and skip to
-   step 3 if I decline. Otherwise install the standalone OpenSpec binary, which
-   needs nothing else, not even Node.js. Show me the command for my OS and run
-   it only once I confirm, then skip to step 3:
+1. INSTALL. Run `openspec --version` first. If it prints a version, OpenSpec is
+   already installed: run `openspec version --check`, which prints the update
+   command for how it was installed when it can tell (otherwise update it the
+   way it was installed, e.g. `brew upgrade openspec`), offer to run that, and
+   skip to step 3. Never switch it to a different install method. Otherwise install
+   the standalone OpenSpec binary, which needs no Node.js. Show me the command
+   for my OS and run it only once I confirm, then skip to step 3:
      macOS / Linux:        curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
      Windows (PowerShell): irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex
    If I'd rather use a package manager, or the installer fails, go to step 2.
@@ -71,9 +73,11 @@ order, and stop where a step tells you to stop.
    me — show me the change and let me make it.
 
 3. PATH. Run `openspec --version`. If the command isn't found, it may just be
-   missing from this shell: tell me where the package manager installed it and
-   how to add that directory to PATH for my shell and OS, then stop until I
-   confirm. If it prints an older version than the one the install just
+   missing from this shell: tell me where it was installed (the standalone
+   installer prints the folder, ~/.local/bin by default; a package manager has
+   its own global bin folder) and how to add that folder to PATH for my shell
+   and OS, then stop until I confirm. On Windows the standalone installer adds
+   it for me; a new terminal picks it up. If it prints an older version than the one the install just
    reported, an earlier copy is shadowing it on PATH — tell me both versions
    instead of continuing. If I use a version manager, say so rather than editing
    PATH around it: with nvm or fnm the CLI is tied to the Node version that was
diff --git a/install.md b/install.md
index 878f41b014..49873a2bdb 100644
--- a/install.md
+++ b/install.md
@@ -21,9 +21,9 @@ TODO:
 
 ## 1. Install
 
-Run `openspec --version` first. If it already prints a version, the CLI is installed: say so, offer to update it with the install command below, and if the user declines skip ahead to step 4.
+Run `openspec --version` first. If it already prints a version, the CLI is installed: say so, run `openspec version --check` (it prints the update command for how OpenSpec was installed when it can tell; otherwise update it the way it was installed, e.g. `brew upgrade openspec`), offer to run that command, and skip ahead to step 3. Never switch an existing install to a different method; that leaves two copies competing on PATH.
 
-Install the standalone OpenSpec binary. It is a single file and needs nothing else, not even Node.js. Show the command for the user's OS and run it only once they confirm, then skip to step 3:
+Install the standalone OpenSpec binary. It is a single file and needs no Node.js (on Alpine Linux, `apk add libstdc++ libgcc` first). Show the command for the user's OS and run it only once they confirm, then skip to step 3:
 
 ```bash
 # macOS / Linux
@@ -58,7 +58,7 @@ Stop and ask again if the install needs sudo or admin rights, fails with a permi
 
 ## 3. PATH
 
-Run `openspec --version`. If the command isn't found, it may only be missing from this shell: say where the package manager installed it and how to add that directory to PATH for the user's shell and OS, then stop until they confirm. If it prints an older version than the one the install just reported, an earlier copy is shadowing it on PATH; report both versions instead of continuing. If the user uses a version manager, say so rather than editing PATH around it: with nvm or fnm the CLI is tied to the Node version that was active at install time, and with asdf or volta a shim may need regenerating.
+Run `openspec --version`. If the command isn't found, it may only be missing from this shell: say where it was installed (the standalone installer prints the folder, `~/.local/bin` by default; a package manager has its own global bin folder) and how to add that folder to PATH for the user's shell and OS, then stop until they confirm. On Windows the standalone installer adds its folder to the user PATH itself; a new terminal picks it up. If it prints an older version than the one the install just reported, an earlier copy is shadowing it on PATH; report both versions instead of continuing. If the user uses a version manager, say so rather than editing PATH around it: with nvm or fnm the CLI is tied to the Node version that was active at install time, and with asdf or volta a shim may need regenerating.
 
 ## 4. Initialize
 

From 985e33288e4cab0972b44656e65e07759600ebdc Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Thu, 22 Oct 2026 15:34:44 -0500
Subject: [PATCH 16/27] docs(installation): lead the published page with the
 binary, add npm switch

The live site builds from docs-lab, so its installation page now leads with
the one-line installers, keeps npm and the other package managers (with the
Node.js prerequisite) as the alternative, and covers the binary in updating
and uninstalling.

New "Switch from npm to the standalone install" section: install the binary,
remove the npm copy (it otherwise keeps running first on PATH), then check
`openspec version` prints `(standalone)`. Settings and projects carry over.
Rehearsed end to end on macOS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs-lab/start/installation.md | 93 ++++++++++++++++++++++++++--------
 docs/installation.md           |  8 +++
 2 files changed, 81 insertions(+), 20 deletions(-)

diff --git a/docs-lab/start/installation.md b/docs-lab/start/installation.md
index 2ffdd53aa1..6896321eff 100644
--- a/docs-lab/start/installation.md
+++ b/docs-lab/start/installation.md
@@ -3,24 +3,47 @@
 > Install the `openspec` CLI on your machine, update it, and uninstall it.
 
 
-## Prerequisites
+## Install
 
-OpenSpec runs on Node.js 20.19.0 or newer. Homebrew installs Node.js as a
-dependency, and the Nix package includes the runtime. Check your installed version
-before using another install method.
+OpenSpec installs as a single `openspec` file. It needs no Node.js.
 
-In your terminal:
+On macOS or Linux, in your terminal:
 
 ```bash
-node --version
+curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+```
+
+On Windows, in PowerShell:
+
+```powershell
+irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex
 ```
 
-If that prints `v20.19.0` or higher, you're set. If not, install a newer Node from
-[nodejs.org](https://nodejs.org) or through your version manager (nvm, fnm, asdf,
-volta). You can skip this check when you install with Homebrew or Nix.
+- **Where it goes**: `~/.local/bin`; on Windows, `%LOCALAPPDATA%\Programs\openspec`, which it adds to your user PATH.
+- **What it checks**: it picks the file for your machine and verifies it against the release's `SHA256SUMS` before installing.
+- **Alpine Linux**: run `apk add libstdc++ libgcc` first.
+- **Options**: set `OPENSPEC_INSTALL_DIR` to install elsewhere, or `OPENSPEC_VERSION=v1.15.0` to pin a release.
+
+If the installer says the folder isn't on your PATH, add it as it shows. Then [check it worked](#check-it-worked).
 
 The workflow itself runs inside an AI coding tool: Claude Code, Cursor, or any other tool on the [supported list](../reference/supported-tools.md).
 
+### Download it yourself
+
+Each [release](https://github.com/Fission-AI/OpenSpec/releases/latest) has one file per platform:
+
+| Platform | File |
+|---|---|
+| macOS 13+ (Apple silicon / Intel) | `openspec-darwin-arm64` / `openspec-darwin-x64` |
+| Linux, glibc 2.17+ (arm64 / x64) | `openspec-linux-arm64` / `openspec-linux-x64` |
+| Alpine 3.17+ (arm64 / x64) | `openspec-linux-arm64-musl` / `openspec-linux-x64-musl` |
+| Windows 10+ (arm64 / x64) | `openspec-windows-arm64.exe` / `openspec-windows-x64.exe` |
+
+Rename it to `openspec` (`openspec.exe` on Windows), run `chmod +x openspec` on macOS or Linux, and put it in a folder on your PATH.
+
+> [!NOTE]
+> macOS blocks a file downloaded in a browser until you run `xattr -d com.apple.quarantine openspec`. The install command above doesn't need this.
+
 ## Install with your AI assistant
 
 Paste this into your AI chat:
@@ -37,26 +60,32 @@ curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md
 
 That fetches [install.md at the repo root](https://github.com/Fission-AI/OpenSpec/blob/main/install.md), a prompt written for any agent that can run shell commands (a few IDE integrations can't). Expect your assistant to:
 
-1. Check your Node version, and stop if it's older than 20.19.0.
-2. Skip the install if the CLI is already on your machine. Otherwise, show you the install command and wait for your confirmation before running it.
+1. Skip the install if the CLI is already on your machine, and offer to update it the way it was installed. Otherwise, show you the install command above and wait for your confirmation before running it.
+2. Use npm instead only if you ask for it or the installer fails, and stop if your Node is older than 20.19.0.
 3. Verify `openspec` is on your PATH.
 4. Name the folder it thinks you mean, suggest the AI tool you're already talking to, and ask which others you use, then run `openspec init` there (the [project setup](setup.md) step).
 5. Report what init created and the exact spelling to invoke OpenSpec in your tool.
 
-It stops before anything privileged and never edits your shell startup files. The [manual methods below](#install-methods) are the source of truth, and the prompt runs them for you.
+It stops before anything privileged and never edits your shell startup files. The [install command above](#install) and the [package managers below](#package-managers) are the source of truth, and the prompt runs them for you.
 
 This install method is new and can have varying results depending on model used. Only use if you're comfortable correcting AI mistakes. Otherwise we recommend following the standard method below.
 
-## Install methods
+## Package managers
+
+These install OpenSpec as a Node.js package, so they need Node.js 20.19.0 or newer (Homebrew and Nix bring their own). In your terminal:
 
-Install the CLI globally; [setting up your project](setup.md) comes after.
+```bash
+node --version
+```
 
-In your terminal:
+If that prints `v20.19.0` or higher, install with npm:
 
 ```npm
 npm install -g @fission-ai/openspec@latest
 ```
 
+If not, install a newer Node from [nodejs.org](https://nodejs.org) or through your version manager (nvm, fnm, asdf, volta), or use the [standalone install](#install) instead.
+
 ### Homebrew
 
 Homebrew installs OpenSpec and its Node.js dependency on macOS or Linux. In your terminal:
@@ -73,7 +102,7 @@ The formula is published in [homebrew-core](https://formulae.brew.sh/formula/ope
 
 ### Bun
 
-Bun installs OpenSpec but doesn't run it, so you still need Node on your machine (the [prerequisite](#prerequisites) above). Without it, every command fails with `env: node: No such file or directory`. Bun treats [every Node CLI](https://bun.com/docs/pm/bunx#shebangs) this way.
+Bun installs OpenSpec but doesn't run it, so you still need Node on your machine (see [Package managers](#package-managers)). Without it, every command fails with `env: node: No such file or directory`. Bun treats [every Node CLI](https://bun.com/docs/pm/bunx#shebangs) this way.
 
 ### Deno
 
@@ -113,7 +142,7 @@ locations (`share/bash-completion/completions`, `share/fish/vendor_completions.d
 `share/zsh/site-functions`), so they load with the package and there is no need to run
 `openspec completion install`.
 
-### Check it worked
+## Check it worked
 
 Whichever method you used, in your terminal:
 
@@ -125,6 +154,30 @@ If that prints a version number, the CLI is on your PATH. It installs once per m
 
 Next, [set up your project](setup.md). If your assistant already ran init, that page shows what it wrote and how to adjust it.
 
+## Switch from npm to the standalone install
+
+Your settings and your projects carry over; only the program changes.
+
+**1. Install the standalone file.** Run the [install command](#install) for your system.
+
+**2. Remove the npm copy.** It usually comes first on your PATH, so until it's gone it keeps running instead. In your terminal:
+
+```npm
+npm uninstall -g @fission-ai/openspec
+```
+
+On Homebrew, run `brew uninstall openspec` instead.
+
+**3. Check which copy runs.** Open a new terminal:
+
+```bash
+openspec version
+```
+
+It should print `OpenSpec <version> (standalone)`. If it names a package manager instead, another copy is still on your PATH: `which -a openspec` (Windows: `where.exe openspec`) lists every copy, so remove the others.
+
+No project needs re-initializing. To switch back, delete the file and run the npm install again.
+
 ## Updating
 
 In your terminal, in each project where you ran init:
@@ -137,7 +190,7 @@ When a newer CLI is out, [`openspec update`](../reference/cli.md#openspec-update
 
 
 > [!WARNING]
-> On Homebrew, run `brew upgrade openspec`. On Deno, re-run the [Deno install](#deno) with `-f`; it won't overwrite the installed command without it. On Nix, use `nix profile upgrade openspec`.
+> With the standalone install, `openspec update` prints the command that replaces your copy in place; run it, or the [install command](#install) again. On Homebrew, run `brew upgrade openspec`. On Deno, re-run the [Deno install](#deno) with `-f`; it won't overwrite the installed command without it. On Nix, use `nix profile upgrade openspec`.
 
 > [!NOTE]
 > A global npm install belongs to one Node installation. Switch Node versions with nvm and the `openspec` command doesn't come along, so install it again under the new version.
@@ -152,7 +205,7 @@ To uninstall OpenSpec, run through the steps below; none of them touch your sour
 openspec completion uninstall
 ```
 
-**2. Remove the package.** In your terminal:
+**2. Remove the CLI.** For the standalone install, delete `~/.local/bin/openspec` (Windows: `%LOCALAPPDATA%\Programs\openspec`, and that folder from your user PATH). For npm, in your terminal:
 
 ```npm
 npm uninstall -g @fission-ai/openspec
@@ -165,4 +218,4 @@ On Homebrew: `brew uninstall openspec`. On Deno: `deno uninstall --global opensp
 - Generated agent files: `openspec-*` skills and `opsx` commands under directories like `.claude/` or `.agents/`, per project. [Supported tools](../reference/supported-tools.md) lists each tool's paths; MiniMax Code keeps skills in `~/.minimax/skills`.
 - Leftovers from older versions: marker blocks in `CLAUDE.md` or `AGENTS.md` (delete the block, keep the file) and `opsx-*.md` prompts in `~/.codex/prompts`.
 - The `openspec/` folder: pause first. `specs/` and `changes/archive/` are your record of the system, plain Markdown that reads fine without OpenSpec.
-- Per-machine state: settings and the telemetry id in `~/.config/openspec/`; schema overrides and store registrations in `~/.local/share/openspec/` (Windows: `%APPDATA%\openspec`, `%LOCALAPPDATA%\openspec`). Registrations are pointers; the store repos they point to are untouched.
+- Per-machine state: settings and the telemetry id in `~/.config/openspec/`; schema overrides, store registrations, and the standalone install's built-in schemas (`binary-schemas/`) in `~/.local/share/openspec/` (Windows: `%APPDATA%\openspec`, `%LOCALAPPDATA%\openspec`). Registrations are pointers; the store repos they point to are untouched.
diff --git a/docs/installation.md b/docs/installation.md
index 39135b249c..557d5fa7cf 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -201,6 +201,14 @@ Or add to your development environment in `flake.nix`:
 openspec --version
 ```
 
+## Switch from npm to the standalone install
+
+Your settings and projects carry over; only the program changes.
+
+1. Run the [install command](#install) for your system.
+2. Remove the npm copy, which otherwise keeps running first on your PATH: `npm uninstall -g @fission-ai/openspec` (Homebrew: `brew uninstall openspec`).
+3. In a new terminal, run `openspec version`. It should print `OpenSpec <version> (standalone)`. If it names a package manager, another copy is still on your PATH: `which -a openspec` (Windows: `where.exe openspec`) lists them.
+
 ## Updating
 
 Upgrade the CLI by running the [install command](#install) again (with a package manager: `npm install -g @fission-ai/openspec@latest` or its pnpm/yarn/bun equivalent). Then refresh each project's generated files:

From 9c7755532e092439ceca8abc5ae5c91c89b4010d Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Fri, 23 Oct 2026 11:52:11 -0500
Subject: [PATCH 17/27] feat(cli): add `openspec install` to switch to the
 standalone binary

Following the npm-to-native pattern of tools like Claude Code: one command
installs the standalone binary, and nothing is forced.

- From a package manager: runs the release installer (same SHA256SUMS
  check as the documented one-liners), then prints the command that
  removes the old copy (npm, pnpm, yarn, bun, volta, or Homebrew's
  formula) and which copy `openspec` now runs. It never removes the old
  copy itself.
- From the binary: reinstalls it in place under its own name, so the
  binary's upgrade advice is now simply `openspec install` (or its full
  path when `openspec` on PATH is a different copy).

The installer is fetched with curl/wget or PowerShell, like the
one-liners, so proxies behave the same, and saved to a file first so a
failed download cannot look like success.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/cli/index.ts                         |  18 +++
 src/commands/install-standalone.ts       | 151 +++++++++++++++++++++++
 src/core/completions/command-registry.ts |   7 ++
 src/core/version-check.ts                |  29 ++---
 src/utils/executable-path.ts             |  43 +++++++
 test/commands/install-standalone.test.ts | 102 +++++++++++++++
 test/core/version-check.test.ts          |  55 ++++-----
 7 files changed, 362 insertions(+), 43 deletions(-)
 create mode 100644 src/commands/install-standalone.ts
 create mode 100644 src/utils/executable-path.ts
 create mode 100644 test/commands/install-standalone.test.ts

diff --git a/src/cli/index.ts b/src/cli/index.ts
index 4504e44432..69be8d3847 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -403,6 +403,24 @@ program
       } else if (latestVersion) {
         displayCliUpdateNote(latestVersion, targetPath);
       }
+
+      // Once per machine, a package-manager user hears the standalone install
+      // exists. Offered, never pushed; deferred when stderr is not a terminal.
+      const { maybeShowStandaloneTip } = await import('../core/standalone-tip.js');
+      await maybeShowStandaloneTip({ silent: !process.stderr.isTTY });
+    } catch (error) {
+      await failWithError(error);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('install [version]')
+  .description('Install the standalone openspec, which runs without Node.js (latest release unless [version] is given)')
+  .action(async (version?: string) => {
+    try {
+      const { installStandalone } = await import('../commands/install-standalone.js');
+      await installStandalone({ version });
     } catch (error) {
       await failWithError(error);
       process.exit(1);
diff --git a/src/commands/install-standalone.ts b/src/commands/install-standalone.ts
new file mode 100644
index 0000000000..f72637ac85
--- /dev/null
+++ b/src/commands/install-standalone.ts
@@ -0,0 +1,151 @@
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import chalk from 'chalk';
+import { findCopiesOnPath, samePath } from '../utils/executable-path.js';
+import {
+  getCliInstallInfo,
+  getStandaloneBinaryPath,
+  type CliInstallInfo,
+} from '../core/version-check.js';
+
+/**
+ * `openspec install`: installs the standalone binary (no Node.js needed) by
+ * running the same release installer the docs give users, then says how to
+ * retire the package-manager copy. It never removes that copy itself: switching
+ * is the user's choice, and so is when.
+ */
+
+const RELEASES_URL = 'https://github.com/Fission-AI/OpenSpec/releases';
+const RELEASE_VERSION = /^v?\d{1,10}\.\d{1,10}\.\d{1,10}(?:-[0-9A-Za-z.-]{1,64})?$/;
+
+export interface InstallTarget {
+  dir: string;
+  name: string;
+}
+
+/**
+ * Where the installer will put the binary. Mirrors install.sh and install.ps1,
+ * and is passed to them explicitly so both sides agree. The standalone binary
+ * reinstalls itself where it is, under its own name.
+ */
+export function resolveInstallTarget(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+  standalonePath: string | null = getStandaloneBinaryPath()
+): InstallTarget {
+  const defaultName = platform === 'win32' ? 'openspec.exe' : 'openspec';
+  if (env.OPENSPEC_INSTALL_DIR) {
+    return { dir: path.resolve(env.OPENSPEC_INSTALL_DIR), name: env.OPENSPEC_INSTALL_NAME || defaultName };
+  }
+  if (standalonePath) {
+    return { dir: path.dirname(standalonePath), name: path.basename(standalonePath) };
+  }
+  if (platform === 'win32') {
+    const localAppData = env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return { dir: path.join(localAppData, 'Programs', 'openspec'), name: defaultName };
+  }
+  return { dir: path.join(os.homedir(), '.local', 'bin'), name: defaultName };
+}
+
+/** The command that removes a package-manager install, or null when there is nothing to remove. */
+export function removeCommandFor(install: CliInstallInfo): string | null {
+  if (install.scope !== 'global') return null;
+  // The Homebrew formula keeps its own npm tree under Cellar; brew owns it.
+  if (install.location && /[\\/]Cellar[\\/]openspec[\\/]/i.test(install.location)) {
+    return 'brew uninstall openspec';
+  }
+  switch (install.packageManager) {
+    case 'npm':
+      return 'npm uninstall -g @fission-ai/openspec';
+    case 'pnpm':
+      return 'pnpm remove -g @fission-ai/openspec';
+    case 'yarn':
+      return 'yarn global remove @fission-ai/openspec';
+    case 'bun':
+      return 'bun remove -g @fission-ai/openspec';
+    case 'volta':
+      return 'volta uninstall @fission-ai/openspec';
+    default:
+      return null;
+  }
+}
+
+function releaseBase(version: string | undefined): string {
+  if (process.env.OPENSPEC_DOWNLOAD_URL) return process.env.OPENSPEC_DOWNLOAD_URL.replace(/\/+$/, '');
+  if (!version || version === 'latest') return `${RELEASES_URL}/latest/download`;
+  return `${RELEASES_URL}/download/${version.startsWith('v') ? version : `v${version}`}`;
+}
+
+/**
+ * Downloads and runs the installer with the same tools as the documented
+ * one-liners (curl or wget; PowerShell's irm), so proxies and certificates
+ * behave as they do for those. Saved to a file first: piped straight into sh,
+ * a failed download would look like a successful run.
+ */
+function runInstaller(scriptUrl: string, env: NodeJS.ProcessEnv): Promise<number> {
+  const [command, args] =
+    process.platform === 'win32'
+      ? [
+          'powershell.exe',
+          ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', `irm '${scriptUrl.replace(/'/g, "''")}' | iex`],
+        ]
+      : [
+          'sh',
+          [
+            '-c',
+            'f=$(mktemp) || exit 1; ' +
+              '{ curl -fsSL "$1" -o "$f" 2>/dev/null || wget -q -O "$f" "$1"; } && sh "$f"; ' +
+              's=$?; rm -f "$f"; exit $s',
+            'openspec-install',
+            scriptUrl,
+          ],
+        ];
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: 'inherit', env });
+    child.on('error', reject);
+    child.on('close', (code) => resolve(code ?? 1));
+  });
+}
+
+export async function installStandalone(options: { version?: string } = {}): Promise<void> {
+  const { version } = options;
+  if (version && version !== 'latest' && !RELEASE_VERSION.test(version)) {
+    throw new Error(`Not a release version: ${version}. Use one like 1.15.0, or leave it out for the latest.`);
+  }
+
+  const base = releaseBase(version);
+  const scriptUrl = `${base}/${process.platform === 'win32' ? 'install.ps1' : 'install.sh'}`;
+  const target = resolveInstallTarget();
+  const exitCode = await runInstaller(scriptUrl, {
+    ...process.env,
+    OPENSPEC_INSTALL_DIR: target.dir,
+    OPENSPEC_INSTALL_NAME: target.name,
+    ...(version && version !== 'latest' ? { OPENSPEC_VERSION: version } : {}),
+  });
+  if (exitCode !== 0) {
+    throw new Error(`The standalone install did not finish (installer: ${scriptUrl}).`);
+  }
+
+  const installedPath = path.join(target.dir, target.name);
+  const defaultName = process.platform === 'win32' ? 'openspec.exe' : 'openspec';
+  // A custom file name is never what `openspec` on PATH finds, so skip that check.
+  const first = target.name === defaultName ? findCopiesOnPath()[0] : undefined;
+  const runsStandalone = first !== undefined && samePath(first, installedPath);
+  // Run from a package manager, the old copy stays until the user removes it.
+  const remove = getStandaloneBinaryPath() ? null : removeCommandFor(getCliInstallInfo());
+
+  console.log();
+  if (runsStandalone) {
+    console.log('openspec now runs the standalone copy.');
+  } else if (first) {
+    console.log(`${first} comes first on your PATH, so it still runs.`);
+  } else if (target.name === defaultName) {
+    console.log('Open a new terminal so it picks up the new PATH.');
+  }
+  if (remove) {
+    console.log(runsStandalone ? 'To remove your package-manager copy:' : 'To switch, remove your package-manager copy:');
+    console.log(chalk.cyan(`  ${remove}`));
+  }
+  console.log(chalk.dim("Check with 'openspec version'; it shows (standalone)."));
+}
diff --git a/src/core/completions/command-registry.ts b/src/core/completions/command-registry.ts
index cf31dc452f..6ae64fcfef 100644
--- a/src/core/completions/command-registry.ts
+++ b/src/core/completions/command-registry.ts
@@ -55,6 +55,13 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
       },
     ],
   },
+  {
+    name: 'install',
+    description: 'Install the standalone openspec, which runs without Node.js (latest release unless [version] is given)',
+    acceptsPositional: true,
+    positionals: [{ name: 'version', optional: true }],
+    flags: [],
+  },
   {
     name: 'version',
     description: 'Report the installed OpenSpec version and update availability',
diff --git a/src/core/version-check.ts b/src/core/version-check.ts
index cf21f22e4a..c83908ee19 100644
--- a/src/core/version-check.ts
+++ b/src/core/version-check.ts
@@ -9,6 +9,7 @@ import { isCiEnvironment } from '../utils/ci.js';
 import { isTelemetryOptedOutByEnv } from '../telemetry/opt-out.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { getGlobalConfig, isGlobalConfigUnreadable } from './global-config.js';
+import { findCopiesOnPath, samePath } from '../utils/executable-path.js';
 
 const require = createRequire(import.meta.url);
 const { name: PACKAGE_NAME, version: OPENSPEC_VERSION } = require('../../package.json');
@@ -27,7 +28,6 @@ const MAX_REDIRECTS = 3;
  */
 const SAFE_VERSION = /^\d{1,10}\.\d{1,10}\.\d{1,10}(?:-[0-9A-Za-z.-]{1,64})?(?:\+[0-9A-Za-z.-]{1,64})?$/;
 
-const RELEASE_DOWNLOAD_URL = 'https://github.com/Fission-AI/OpenSpec/releases/latest/download';
 let standaloneBinaryPath: string | null = null;
 
 /**
@@ -38,23 +38,24 @@ export function markStandaloneBinary(executablePath: string): void {
   standaloneBinaryPath = executablePath;
 }
 
+/** The standalone binary's own path, or null when running from a package. */
+export function getStandaloneBinaryPath(): string | null {
+  return standaloneBinaryPath;
+}
+
 /**
- * Replaces the standalone binary where it already is, so the new copy cannot
- * end up shadowed by the old one on PATH. Null when this is not the binary.
+ * `openspec install` reinstalls the standalone binary where it already is,
+ * under its own name, so the new copy cannot end up shadowed by the old one.
+ * Spelled with the full path when `openspec` on PATH is some other copy.
+ * Null when this is not the binary.
  */
 function standaloneUpgradeCommand(): string | null {
   if (!standaloneBinaryPath) return null;
-  const dir = path.dirname(standaloneBinaryPath);
-  const name = path.basename(standaloneBinaryPath);
-  if (process.platform === 'win32') {
-    const quote = (value: string) => `'${value.replace(/'/g, "''")}'`;
-    // A binary kept under its download name is replaced under that name.
-    const setName = name.toLowerCase() === 'openspec.exe' ? '' : ` $env:OPENSPEC_INSTALL_NAME=${quote(name)};`;
-    return `$env:OPENSPEC_INSTALL_DIR=${quote(dir)};${setName} irm ${RELEASE_DOWNLOAD_URL}/install.ps1 | iex`;
-  }
-  const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`;
-  const setName = name === 'openspec' ? '' : ` OPENSPEC_INSTALL_NAME=${quote(name)}`;
-  return `curl -fsSL ${RELEASE_DOWNLOAD_URL}/install.sh | OPENSPEC_INSTALL_DIR=${quote(dir)}${setName} sh`;
+  const first = findCopiesOnPath()[0];
+  if (first && samePath(first, standaloneBinaryPath)) return 'openspec install';
+  return process.platform === 'win32'
+    ? `& '${standaloneBinaryPath.replace(/'/g, "''")}' install`
+    : `'${standaloneBinaryPath.replace(/'/g, `'\\''`)}' install`;
 }
 
 /**
diff --git a/src/utils/executable-path.ts b/src/utils/executable-path.ts
new file mode 100644
index 0000000000..3f5f451239
--- /dev/null
+++ b/src/utils/executable-path.ts
@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Every `openspec` on PATH, in the order a shell would find them. */
+export function findCopiesOnPath(
+  pathValue: string = process.env.PATH ?? '',
+  platform: NodeJS.Platform = process.platform
+): string[] {
+  const names = platform === 'win32' ? ['openspec.exe', 'openspec.cmd'] : ['openspec'];
+  const seen = new Set<string>();
+  const copies: string[] = [];
+  for (const dir of pathValue.split(path.delimiter)) {
+    if (!dir) continue;
+    for (const name of names) {
+      const candidate = path.join(dir, name);
+      try {
+        if (!fs.statSync(candidate).isFile()) continue;
+        if (platform !== 'win32') fs.accessSync(candidate, fs.constants.X_OK);
+        const key = platform === 'win32' ? candidate.toLowerCase() : candidate;
+        if (!seen.has(key)) {
+          seen.add(key);
+          copies.push(candidate);
+        }
+      } catch {
+        // Not there, or not runnable: not a copy a shell would run.
+      }
+    }
+  }
+  return copies;
+}
+
+/** Whether two paths name the same file once symlinks are resolved. */
+export function samePath(a: string, b: string): boolean {
+  const real = (value: string) => {
+    try {
+      return fs.realpathSync(value);
+    } catch {
+      return path.resolve(value);
+    }
+  };
+  const [x, y] = [real(a), real(b)];
+  return process.platform === 'win32' ? x.toLowerCase() === y.toLowerCase() : x === y;
+}
diff --git a/test/commands/install-standalone.test.ts b/test/commands/install-standalone.test.ts
new file mode 100644
index 0000000000..e8daa19bd8
--- /dev/null
+++ b/test/commands/install-standalone.test.ts
@@ -0,0 +1,102 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  installStandalone,
+  removeCommandFor,
+  resolveInstallTarget,
+} from '../../src/commands/install-standalone.js';
+import { findCopiesOnPath } from '../../src/utils/executable-path.js';
+
+describe('openspec install', () => {
+  describe('resolveInstallTarget', () => {
+    it('uses the installers\' default folder', () => {
+      expect(resolveInstallTarget({}, 'darwin', null)).toEqual({
+        dir: path.join(os.homedir(), '.local', 'bin'),
+        name: 'openspec',
+      });
+      expect(resolveInstallTarget({ LOCALAPPDATA: 'C:\\Users\\a\\AppData\\Local' }, 'win32', null)).toEqual({
+        dir: path.join('C:\\Users\\a\\AppData\\Local', 'Programs', 'openspec'),
+        name: 'openspec.exe',
+      });
+    });
+
+    it('reinstalls the standalone binary where it is, under its own name', () => {
+      const binary = path.join(os.tmpdir(), 'tools', 'openspec-linux-x64');
+      expect(resolveInstallTarget({}, 'linux', binary)).toEqual({
+        dir: path.dirname(binary),
+        name: 'openspec-linux-x64',
+      });
+    });
+
+    it('honors OPENSPEC_INSTALL_DIR and resolves it to an absolute folder', () => {
+      expect(resolveInstallTarget({ OPENSPEC_INSTALL_DIR: 'relative/bin' }, 'linux', '/x/openspec')).toEqual({
+        dir: path.resolve('relative/bin'),
+        name: 'openspec',
+      });
+    });
+  });
+
+  describe('removeCommandFor', () => {
+    const global = (packageManager: string | null, location = '/usr/lib/node_modules/@fission-ai/openspec') =>
+      ({ location, packageManager, scope: 'global' }) as Parameters<typeof removeCommandFor>[0];
+
+    it('names the uninstall command of the package manager that owns the copy', () => {
+      expect(removeCommandFor(global('npm'))).toBe('npm uninstall -g @fission-ai/openspec');
+      expect(removeCommandFor(global('pnpm'))).toBe('pnpm remove -g @fission-ai/openspec');
+      expect(removeCommandFor(global('yarn'))).toBe('yarn global remove @fission-ai/openspec');
+      expect(removeCommandFor(global('bun'))).toBe('bun remove -g @fission-ai/openspec');
+      expect(removeCommandFor(global('volta'))).toBe('volta uninstall @fission-ai/openspec');
+    });
+
+    it('sends the Homebrew formula to brew', () => {
+      const cellar = '/opt/homebrew/Cellar/openspec/1.14.3/libexec/lib/node_modules/@fission-ai/openspec';
+      expect(removeCommandFor(global('npm', cellar))).toBe('brew uninstall openspec');
+    });
+
+    it('suggests nothing for copies that are not a global install', () => {
+      expect(removeCommandFor({ location: '/p/node_modules/@fission-ai/openspec', packageManager: 'npm', scope: 'project' })).toBeNull();
+      expect(removeCommandFor({ location: '/repo', packageManager: null, scope: 'source' })).toBeNull();
+      expect(removeCommandFor({ location: null, packageManager: null, scope: 'standalone' })).toBeNull();
+    });
+  });
+
+  describe('findCopiesOnPath', () => {
+    let root: string;
+    beforeEach(() => {
+      root = fs.mkdtempSync(path.join(os.tmpdir(), 'openspec-path-'));
+    });
+    afterEach(() => {
+      fs.rmSync(root, { recursive: true, force: true });
+    });
+
+    const place = (dir: string, name: string, mode = 0o755) => {
+      fs.mkdirSync(path.join(root, dir), { recursive: true });
+      fs.writeFileSync(path.join(root, dir, name), '', { mode });
+      return path.join(root, dir, name);
+    };
+
+    it.skipIf(process.platform === 'win32')('lists runnable copies in PATH order, once each', () => {
+      const first = place('a', 'openspec');
+      place('b', 'openspec', 0o644); // not executable: a shell skips it
+      const second = place('c', 'openspec');
+      const pathValue = ['a', 'missing', 'b', 'c', 'a'].map((dir) => path.join(root, dir)).join(path.delimiter);
+
+      expect(findCopiesOnPath(pathValue, 'linux')).toEqual([first, second]);
+    });
+
+    it('finds the Windows executable and npm\'s .cmd shim', () => {
+      const exe = place('a', 'openspec.exe');
+      const shim = place('b', 'openspec.cmd');
+      const pathValue = [path.join(root, 'a'), path.join(root, 'b')].join(path.delimiter);
+
+      expect(findCopiesOnPath(pathValue, 'win32')).toEqual([exe, shim]);
+    });
+  });
+
+  it('refuses a version that is not a release version, before downloading anything', async () => {
+    await expect(installStandalone({ version: '1.2.3; rm -rf /' })).rejects.toThrow('Not a release version');
+    await expect(installStandalone({ version: 'main' })).rejects.toThrow('Not a release version');
+  });
+});
diff --git a/test/core/version-check.test.ts b/test/core/version-check.test.ts
index fe5e2a6d66..8c99240129 100644
--- a/test/core/version-check.test.ts
+++ b/test/core/version-check.test.ts
@@ -1265,33 +1265,32 @@ describe('standalone binary', () => {
     expect(buildVersionReportLines('1.0.0', install)[0]).toBe('OpenSpec 1.0.0 (standalone)');
   });
 
-  it('upgrades by replacing the binary in place, never through a package manager', async () => {
+  it('upgrades with `openspec install`, never through a package manager', async () => {
     const { getCliInstallInfo, getCliUpdateCommand, buildCliUpdateLines, canSelfUpgrade } = await loadMarked();
-    const command = getCliUpdateCommand(getCliInstallInfo(null));
-    const lines = buildCliUpdateLines('9.9.9', null, PROJECT_ROOT).join('\n');
-
-    if (process.platform === 'win32') {
-      expect(command).toBe(
-        `$env:OPENSPEC_INSTALL_DIR='${path.dirname(executable).replace(/'/g, "''")}'; irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex`
-      );
-    } else {
-      expect(command).toMatch(
-        /^curl -fsSL https:\/\/github\.com\/Fission-AI\/OpenSpec\/releases\/latest\/download\/install\.sh \| OPENSPEC_INSTALL_DIR='.*' sh$/
-      );
-      // The quoted directory is exactly the binary's directory once a shell reads it.
-      const quoted = command!.match(/OPENSPEC_INSTALL_DIR=(.*) sh$/)![1];
-      const { execFileSync } = await import('child_process');
-      expect(execFileSync('sh', ['-c', `printf %s ${quoted}`], { encoding: 'utf8' })).toBe(path.dirname(executable));
+    // `openspec` on PATH is this binary.
+    const binDir = path.dirname(executable);
+    fs.mkdirSync(binDir, { recursive: true });
+    fs.writeFileSync(executable, '', { mode: 0o755 });
+    const originalPath = process.env.PATH;
+    process.env.PATH = `${binDir}${path.delimiter}${originalPath ?? ''}`;
+    try {
+      const command = getCliUpdateCommand(getCliInstallInfo(null));
+      const lines = buildCliUpdateLines('9.9.9', null, PROJECT_ROOT).join('\n');
+
+      expect(command).toBe('openspec install');
+      expect(lines).toContain('  openspec install');
+      expect(lines).toContain('Then run "openspec update" again');
+      expect(lines).not.toMatch(/npm|pnpm|yarn|volta|bun add/);
+      expect(canSelfUpgrade(null, PROJECT_ROOT)).toBe(false);
+    } finally {
+      process.env.PATH = originalPath;
+      fs.rmSync(binDir, { recursive: true, force: true });
     }
-    expect(lines).toContain(command!);
-    expect(lines).toContain('Then run "openspec update" again');
-    expect(lines).not.toMatch(/npm|pnpm|yarn|volta|bun add/);
-    expect(canSelfUpgrade(null, PROJECT_ROOT)).toBe(false);
   });
 });
 
-describe('standalone binary kept under its download name', () => {
-  it('upgrades the file the user actually runs', async () => {
+describe('standalone binary that `openspec` on PATH does not find', () => {
+  it('names its own path, so the upgrade reaches the file the user runs', async () => {
     const name = process.platform === 'win32' ? `openspec-windows-${process.arch}.exe` : `openspec-${process.platform}-${process.arch}`;
     const executable = path.join(os.tmpdir(), "it's bin", name);
     vi.resetModules();
@@ -1300,15 +1299,13 @@ describe('standalone binary kept under its download name', () => {
     const command = getCliUpdateCommand(getCliInstallInfo(null))!;
 
     if (process.platform === 'win32') {
-      expect(command).toContain(`$env:OPENSPEC_INSTALL_NAME='${name}';`);
+      expect(command).toBe(`& '${executable.replace(/'/g, "''")}' install`);
     } else {
-      // Both variables read back exactly once a shell parses the command.
-      const vars = command.match(/\| (OPENSPEC_INSTALL_DIR=.*) sh$/)![1];
+      expect(command).toMatch(/^'.*' install$/);
+      // The quoted path reads back exactly once a shell parses it.
+      const quoted = command.replace(/ install$/, '');
       const { execFileSync } = await import('child_process');
-      const read = execFileSync('sh', ['-c', `${vars} sh -c 'printf "%s|%s" "$OPENSPEC_INSTALL_DIR" "$OPENSPEC_INSTALL_NAME"'`], {
-        encoding: 'utf8',
-      });
-      expect(read).toBe(`${path.dirname(executable)}|${name}`);
+      expect(execFileSync('sh', ['-c', `printf %s ${quoted}`], { encoding: 'utf8' })).toBe(executable);
     }
   });
 });

From c2d93b9c5ed399e06e509b13ce4a6f86c032d553 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Fri, 23 Oct 2026 11:52:11 -0500
Subject: [PATCH 18/27] feat(cli): tell package-manager users once that the
 standalone install exists

After `openspec update`, a global npm/pnpm/yarn/bun/volta/Homebrew install
prints one line pointing at `openspec install`, once per machine
(standaloneTipSeen in the global config). Never in CI, never for the binary,
project installs, npx or source checkouts, and deferred rather than used up
when stderr is not a terminal, so agents never consume it. Reuses the
completion tip's safe config write.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/core/completion-tip.ts       |  8 +--
 src/core/config-schema.ts        |  1 +
 src/core/global-config.ts        |  2 +
 src/core/standalone-tip.ts       | 39 +++++++++++++
 test/core/config-schema.test.ts  |  2 +
 test/core/standalone-tip.test.ts | 99 ++++++++++++++++++++++++++++++++
 6 files changed, 147 insertions(+), 4 deletions(-)
 create mode 100644 src/core/standalone-tip.ts
 create mode 100644 test/core/standalone-tip.test.ts

diff --git a/src/core/completion-tip.ts b/src/core/completion-tip.ts
index 4d23e5e26a..1d5275260d 100644
--- a/src/core/completion-tip.ts
+++ b/src/core/completion-tip.ts
@@ -89,7 +89,7 @@ async function decideTip(): Promise<'show' | 'retire'> {
  * Returns null when the file exists but cannot be read or parsed — a config we
  * cannot understand is left strictly alone rather than overwritten.
  */
-function readRawConfig(): Record<string, unknown> | null {
+export function readRawConfig(): Record<string, unknown> | null {
   const configPath = getGlobalConfigPath();
   if (!fs.existsSync(configPath)) {
     return {};
@@ -111,7 +111,7 @@ function readRawConfig(): Record<string, unknown> | null {
  * write down to this one key, and the rename keeps a reader from ever seeing a
  * half-written config.
  */
-async function markTipSeen(): Promise<void> {
+export async function markConfigFlag(key: string): Promise<void> {
   const configPath = getGlobalConfigPath();
   const current = readRawConfig() ?? {};
 
@@ -120,7 +120,7 @@ async function markTipSeen(): Promise<void> {
   // is both guessable and world-readable once renamed over the config.
   await writeFileAtomically(
     configPath,
-    JSON.stringify({ ...current, completionTipSeen: true }, null, 2) + '\n'
+    JSON.stringify({ ...current, [key]: true }, null, 2) + '\n'
   );
 }
 
@@ -149,7 +149,7 @@ export async function maybeShowCompletionTip(
 
     // Record before printing: if the flag cannot be persisted, staying quiet
     // beats reprinting the tip on every future run.
-    await markTipSeen();
+    await markConfigFlag('completionTipSeen');
     if (decision === 'show') {
       console.error(`\n${COMPLETION_TIP_MESSAGE}`);
     }
diff --git a/src/core/config-schema.ts b/src/core/config-schema.ts
index 1310e48fff..3bf5e4a398 100644
--- a/src/core/config-schema.ts
+++ b/src/core/config-schema.ts
@@ -37,6 +37,7 @@ export const GlobalConfigSchema = z
       .optional(),
     // Runtime-managed (like telemetry.noticeSeen); not user-settable via CLI set.
     completionTipSeen: z.boolean().optional(),
+    standaloneTipSeen: z.boolean().optional(),
   })
   .passthrough();
 
diff --git a/src/core/global-config.ts b/src/core/global-config.ts
index 5bbab86ae0..beac1808b1 100644
--- a/src/core/global-config.ts
+++ b/src/core/global-config.ts
@@ -38,6 +38,8 @@ export interface GlobalConfig {
   telemetry?: TelemetryConfig;
   /** Whether the first-run shell-completions tip has been shown. */
   completionTipSeen?: boolean;
+  /** Whether the one-time note about the standalone install has been shown. */
+  standaloneTipSeen?: boolean;
 }
 
 const DEFAULT_CONFIG: GlobalConfig = {
diff --git a/src/core/standalone-tip.ts b/src/core/standalone-tip.ts
new file mode 100644
index 0000000000..e3f5c9d33a
--- /dev/null
+++ b/src/core/standalone-tip.ts
@@ -0,0 +1,39 @@
+/**
+ * One-time note telling package-manager users that the standalone install
+ * exists. It only offers: people who chose npm may have a reason, so it is
+ * shown once, never repeated, and never changes anything.
+ *
+ * Shown on stderr after `openspec update` (the moment people think about
+ * versions), and only for a global package-manager install. Deferred, not
+ * consumed, when nobody would read it: stderr that is not a terminal (agents,
+ * pipes) and CI.
+ */
+import { isCiEnvironment } from '../utils/ci.js';
+import { markConfigFlag, readRawConfig } from './completion-tip.js';
+import { getCliInstallInfo, getStandaloneBinaryPath } from './version-check.js';
+
+export const STANDALONE_TIP_MESSAGE =
+  "Tip: OpenSpec also comes as a standalone app that runs without Node.js. To switch, run 'openspec install'.";
+
+/** Never throws: a hint must not break a command. */
+export async function maybeShowStandaloneTip(options: { silent?: boolean } = {}): Promise<void> {
+  if (isCiEnvironment() || getStandaloneBinaryPath()) {
+    return;
+  }
+  try {
+    const raw = readRawConfig();
+    if (raw === null || raw.standaloneTipSeen === true || options.silent) {
+      return;
+    }
+    // Project dependencies, npx runs and source checkouts have nothing to switch.
+    if (getCliInstallInfo().scope !== 'global') {
+      return;
+    }
+    // Record before printing: if the flag cannot be saved, staying quiet beats
+    // repeating the note on every run.
+    await markConfigFlag('standaloneTipSeen');
+    console.error(`\n${STANDALONE_TIP_MESSAGE}`);
+  } catch {
+    // Silent failure - a hint should never break the CLI.
+  }
+}
diff --git a/test/core/config-schema.test.ts b/test/core/config-schema.test.ts
index cae2548888..e60818f3df 100644
--- a/test/core/config-schema.test.ts
+++ b/test/core/config-schema.test.ts
@@ -397,6 +397,8 @@ describe('config-schema', () => {
       // but never settable — it is runtime state, like telemetry.noticeSeen.
       expect(GlobalConfigSchema.safeParse({ completionTipSeen: true }).success).toBe(true);
       expect(validateConfigKeyPath('completionTipSeen').valid).toBe(false);
+      expect(GlobalConfigSchema.safeParse({ standaloneTipSeen: true }).success).toBe(true);
+      expect(validateConfigKeyPath('standaloneTipSeen').valid).toBe(false);
     });
 
     it('rejects bare telemetry and unknown leaves', () => {
diff --git a/test/core/standalone-tip.test.ts b/test/core/standalone-tip.test.ts
new file mode 100644
index 0000000000..ecee940846
--- /dev/null
+++ b/test/core/standalone-tip.test.ts
@@ -0,0 +1,99 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const state = vi.hoisted(() => ({
+  ci: false,
+  standalone: null as string | null,
+  scope: 'global' as string | null,
+}));
+
+vi.mock('../../src/utils/ci.js', () => ({ isCiEnvironment: () => state.ci }));
+vi.mock('../../src/core/version-check.js', () => ({
+  getStandaloneBinaryPath: () => state.standalone,
+  getCliInstallInfo: () => ({ location: '/x', packageManager: 'npm', scope: state.scope }),
+}));
+
+const { maybeShowStandaloneTip, STANDALONE_TIP_MESSAGE } = await import('../../src/core/standalone-tip.js');
+
+describe('standalone tip', () => {
+  let configHome: string;
+  let originalConfigHome: string | undefined;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+  const configPath = () => path.join(configHome, 'openspec', 'config.json');
+  const shown = () => errorSpy.mock.calls.filter((call) => String(call[0]).includes(STANDALONE_TIP_MESSAGE)).length;
+
+  beforeEach(() => {
+    configHome = fs.mkdtempSync(path.join(os.tmpdir(), 'openspec-standalone-tip-'));
+    originalConfigHome = process.env.XDG_CONFIG_HOME;
+    process.env.XDG_CONFIG_HOME = configHome;
+    Object.assign(state, { ci: false, standalone: null, scope: 'global' });
+    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    errorSpy.mockRestore();
+    process.env.XDG_CONFIG_HOME = originalConfigHome;
+    fs.rmSync(configHome, { recursive: true, force: true });
+  });
+
+  it('offers the standalone install once to a global package-manager install', async () => {
+    await maybeShowStandaloneTip();
+    await maybeShowStandaloneTip();
+
+    expect(shown()).toBe(1);
+    expect(STANDALONE_TIP_MESSAGE).toContain("openspec install");
+    expect(JSON.parse(fs.readFileSync(configPath(), 'utf8')).standaloneTipSeen).toBe(true);
+  });
+
+  it('keeps the rest of the config untouched when it records the flag', async () => {
+    fs.mkdirSync(path.dirname(configPath()), { recursive: true });
+    fs.writeFileSync(configPath(), JSON.stringify({ profile: 'custom', workflows: ['propose'] }));
+
+    await maybeShowStandaloneTip();
+
+    expect(JSON.parse(fs.readFileSync(configPath(), 'utf8'))).toEqual({
+      profile: 'custom',
+      workflows: ['propose'],
+      standaloneTipSeen: true,
+    });
+  });
+
+  it('defers without using up the tip when nobody would read it', async () => {
+    await maybeShowStandaloneTip({ silent: true });
+    expect(shown()).toBe(0);
+    expect(fs.existsSync(configPath())).toBe(false);
+
+    await maybeShowStandaloneTip();
+    expect(shown()).toBe(1);
+  });
+
+  it('stays quiet for the binary itself, in CI, and for installs with nothing to switch', async () => {
+    state.standalone = '/home/a/.local/bin/openspec';
+    await maybeShowStandaloneTip();
+    state.standalone = null;
+
+    state.ci = true;
+    await maybeShowStandaloneTip();
+    state.ci = false;
+
+    for (const scope of ['project', 'temporary', 'source', null]) {
+      state.scope = scope;
+      await maybeShowStandaloneTip();
+    }
+
+    expect(shown()).toBe(0);
+    expect(fs.existsSync(configPath())).toBe(false);
+  });
+
+  it('leaves a config it cannot read alone', async () => {
+    fs.mkdirSync(path.dirname(configPath()), { recursive: true });
+    fs.writeFileSync(configPath(), '{ not json');
+
+    await maybeShowStandaloneTip();
+
+    expect(shown()).toBe(0);
+    expect(fs.readFileSync(configPath(), 'utf8')).toBe('{ not json');
+  });
+});

From 09a6269874ca944e5f93ebe9da0fd69747eaf84a Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Fri, 23 Oct 2026 11:52:11 -0500
Subject: [PATCH 19/27] fix(cli): let the Windows installer replace a running
 openspec.exe

`openspec install` runs the installer from the very exe it replaces, and
Windows cannot overwrite a running exe. The installer now renames the old
copy aside (allowed while it runs), moves the new one in, deletes the old one
now or on the next install, and restores it if the move fails. It also
clears any download mark on the new exe (Unblock-File).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/binary/install.ps1 | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/scripts/binary/install.ps1 b/scripts/binary/install.ps1
index 99798fa472..05b6990d47 100644
--- a/scripts/binary/install.ps1
+++ b/scripts/binary/install.ps1
@@ -41,6 +41,9 @@
 
   # Staged inside the install dir so the final move is a same-volume rename.
   New-Item -ItemType Directory -Force -Path $dir | Out-Null
+  # Copies set aside by an earlier upgrade, once nothing runs them any more.
+  Get-ChildItem -Path $dir -Filter "$name.old-*" -ErrorAction SilentlyContinue |
+    Remove-Item -Force -ErrorAction SilentlyContinue
   $tmp = Join-Path $dir ('.openspec-install-' + [Guid]::NewGuid().ToString('N'))
   New-Item -ItemType Directory -Path $tmp | Out-Null
   try {
@@ -68,11 +71,23 @@
     }
 
     $target = Join-Path $dir $name
+    # Windows cannot overwrite a running exe, and `openspec install` runs this
+    # from the very exe it replaces. Renaming a running exe is allowed, so the
+    # old copy moves aside: deleted now, or by the next install if still running.
+    $old = $null
+    if (Test-Path $target) {
+      $old = "$target.old-" + [Guid]::NewGuid().ToString('N')
+      Rename-Item -Path $target -NewName (Split-Path $old -Leaf)
+    }
     try {
-      Move-Item -Force -Path $exe -Destination $target
+      Move-Item -Path $exe -Destination $target
     } catch {
-      throw "openspec install: could not replace $target. Close any running openspec and try again."
+      if ($old) { Rename-Item -Path $old -NewName $name -ErrorAction SilentlyContinue }
+      throw "openspec install: could not install to ${target}: $($_.Exception.Message)"
     }
+    if ($old) { Remove-Item -Force -Path $old -ErrorAction SilentlyContinue }
+    # Clear any "downloaded from the internet" mark so Windows does not block it.
+    Unblock-File -Path $target -ErrorAction SilentlyContinue
     Write-Host "Installed openspec $installed to $target"
   } finally {
     Remove-Item -Recurse -Force -Path $tmp -ErrorAction SilentlyContinue

From 0049e8ca0479587fc0ff0f0105d3e2738bcb017a Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Fri, 23 Oct 2026 11:52:11 -0500
Subject: [PATCH 20/27] ci(binaries): test `openspec install` everywhere and
 attest release binaries

- Every verify runner (Alpine in its container) runs install-check.sh: the
  Node build switching to the binary, and the binary reinstalling itself
  twice in place, against this build served locally.
- Releases get signed build-provenance attestations (actions/attest,
  pinned), verifiable with `gh attestation verify`. They stand in for code
  signing until notarization lands, and run after the upload so a
  first-time problem cannot hold binaries back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/binaries.yml  | 24 +++++++++++++++++++---
 scripts/binary/install-check.sh | 36 +++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 3 deletions(-)
 create mode 100755 scripts/binary/install-check.sh

diff --git a/.github/workflows/binaries.yml b/.github/workflows/binaries.yml
index ee8135d7e7..366b2bef52 100644
--- a/.github/workflows/binaries.yml
+++ b/.github/workflows/binaries.yml
@@ -203,22 +203,29 @@ jobs:
         with:
           node-version: '20.19.0'
           package-manager-cache: false
-      - name: CLI test suite against the binary
+      - name: CLI test suite and `openspec install` against the binary
         run: |
+          # `openspec install` (install-check.sh) downloads from this build, served locally.
+          # On Windows, python3 can be the Microsoft Store stub; python is the real one.
+          py=python3; [ "$RUNNER_OS" = Windows ] && py=python
+          $py -m http.server 8766 --directory dist-bin >/dev/null 2>&1 &
+          for _ in $(seq 20); do curl -sf -o /dev/null http://127.0.0.1:8766/SHA256SUMS && break; sleep 0.5; done
           if [ -n "$ALPINE" ]; then
             # Copied in: the container installs its own (musl) dependencies.
             # Run as a normal user; root can read files the tests make unreadable.
-            docker run --rm -v "$PWD:/src:ro" node:22-alpine sh -c \
+            docker run --rm --network host -v "$PWD:/src:ro" node:22-alpine sh -c \
               "apk add -q --no-cache bash git libstdc++ libgcc && corepack enable &&
                mkdir /w && cd /src && tar --exclude=./node_modules -cf - . | tar -xf - -C /w && chown -R node /w &&
                su node -c 'cd /w && pnpm install --frozen-lockfile && pnpm run build &&
-                 bash scripts/binary/e2e.sh dist-bin/openspec-$ASSET'"
+                 bash scripts/binary/e2e.sh dist-bin/openspec-$ASSET &&
+                 OPENSPEC_DOWNLOAD_URL=http://127.0.0.1:8766 bash scripts/binary/install-check.sh dist-bin/openspec-$ASSET'"
           else
             pnpm install --frozen-lockfile
             pnpm run build
             bin="dist-bin/openspec-$ASSET"
             [ "$RUNNER_OS" = Windows ] && bin="$bin.exe"
             bash scripts/binary/e2e.sh "$bin"
+            OPENSPEC_DOWNLOAD_URL=http://127.0.0.1:8766 bash scripts/binary/install-check.sh "$bin"
           fi
 
   release:
@@ -229,6 +236,9 @@ jobs:
     timeout-minutes: 10
     permissions:
       contents: write # upload release assets
+      id-token: write # sign the provenance attestation
+      attestations: write # store it
+      artifact-metadata: write # record the attested files
     steps:
       - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
         with:
@@ -241,3 +251,11 @@ jobs:
           cd dist-bin
           sha256sum --check SHA256SUMS
           gh release upload "$REF" openspec-* SHA256SUMS install.sh install.ps1 --clobber --repo "$GITHUB_REPOSITORY"
+      # Signed proof each binary was built by this workflow from this tag, which
+      # anyone can check with `gh attestation verify`. The binaries are not
+      # notarized or code-signed yet, so this is the verifiable trail meanwhile.
+      # After the upload, so a first-time problem here never holds binaries back.
+      - uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
+        continue-on-error: true
+        with:
+          subject-path: 'dist-bin/openspec-*'
diff --git a/scripts/binary/install-check.sh b/scripts/binary/install-check.sh
new file mode 100755
index 0000000000..df29c581f4
--- /dev/null
+++ b/scripts/binary/install-check.sh
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Checks `openspec install` against a release served at OPENSPEC_DOWNLOAD_URL:
+# run from the Node build, as an npm user would, and by the binary on itself,
+# which reinstalls in place. Needs `pnpm build`.
+#
+#   OPENSPEC_DOWNLOAD_URL=http://127.0.0.1:8766 bash scripts/binary/install-check.sh dist-bin/openspec-<asset>
+set -euo pipefail
+
+asset=$1
+ext=""
+case "$asset" in *.exe) ext=".exe" ;; esac
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+export XDG_CONFIG_HOME="$work/config" XDG_DATA_HOME="$work/data" OPENSPEC_TELEMETRY=0 OPENSPEC_NO_UPDATE_CHECK=1
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+# 1. From the Node build, into a fresh folder.
+OPENSPEC_INSTALL_DIR="$work/from-node" node bin/openspec.js install
+cmp "$work/from-node/openspec$ext" "$asset" || fail "install from Node wrote the wrong file"
+"$work/from-node/openspec$ext" version | grep -q '(standalone)' || fail "installed copy is not standalone"
+
+# 2. The binary replacing itself where it is, under its own (custom) name.
+# Twice: on Windows the running exe is set aside, and the next run removes it.
+mkdir "$work/self"
+self="$work/self/my-openspec$ext"
+cp "$asset" "$self"
+for run in 1 2; do
+  out=$(env -u OPENSPEC_INSTALL_DIR -u OPENSPEC_INSTALL_NAME "$self" install 2>&1) || fail "self-install run $run failed: $out"
+  case "$out" in *"Installed openspec"*"my-openspec$ext"*) ;; *) fail "self-install run $run did not replace itself: $out" ;; esac
+  cmp "$self" "$asset" || fail "self-install run $run wrote the wrong file"
+done
+"$self" version | grep -q '(standalone)' || fail "reinstalled copy is not standalone"
+leftovers=$(find "$work/self" -mindepth 1 -maxdepth 1 ! -name "my-openspec$ext" | wc -l | tr -d ' ')
+[ "$leftovers" -le 1 ] || fail "files pile up next to the binary: $(ls -A "$work/self")"
+
+echo "OK: openspec install ($asset)"

From 9a761aeea6cae26ccb1120577634483b0f6140e6 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Fri, 23 Oct 2026 11:52:11 -0500
Subject: [PATCH 21/27] docs(installation): switch with `openspec install`, and
 verify downloads

- The switch steps start with `openspec install`, which prints the
  removal command for the old copy; switching is stated as optional.
- The CLI reference documents `openspec install` and the `standalone`
  scope.
- The setup prompt and install.md mention the standalone install once to
  package-manager users, without pushing it.
- New "Verify a download" note for `gh attestation verify`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                      |  2 +-
 docs-lab/reference/cli.md      | 34 +++++++++++++++++++++++++++++++++-
 docs-lab/start/installation.md | 28 +++++++++++++++++++++-------
 docs/installation.md           |  8 +++++---
 install.md                     |  2 +-
 5 files changed, 61 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index b68088ef6b..c720ea9254 100644
--- a/README.md
+++ b/README.md
@@ -196,7 +196,7 @@ AI coding assistants are powerful but unpredictable when requirements live only
 
 **Upgrade the CLI**
 
-Run the install command from [Quick Start](#quick-start) again. If you installed with npm:
+With the standalone install, run `openspec install`. If you installed with npm:
 
 ```bash
 npm install -g @fission-ai/openspec@latest
diff --git a/docs-lab/reference/cli.md b/docs-lab/reference/cli.md
index 889103bef4..0fa9ff5171 100644
--- a/docs-lab/reference/cli.md
+++ b/docs-lab/reference/cli.md
@@ -51,6 +51,7 @@ Your agent runs most of these during the workflow.
 | Command | What it does |
 |---|---|
 | [`openspec version`](#openspec-version) | Report the installed version and optionally check for an update. |
+| [`openspec install`](#openspec-install) | Install the standalone `openspec`, which runs without Node.js. |
 | [`openspec feedback`](#openspec-feedback) | Submit feedback about OpenSpec. |
 | [`openspec completion`](#openspec-completion) | Install or generate shell completions. |
 
@@ -2221,7 +2222,7 @@ For a global npm install:
 OpenSpec 1.13.2 (npm, global)
 ```
 
-The install scope is `global`, `project`, `temporary` for an ephemeral runner such as npx, or `source` for a checkout. OpenSpec omits details it cannot identify instead of guessing.
+The install scope is `global`, `project`, `temporary` for an ephemeral runner such as npx, `source` for a checkout, or `standalone` for the [standalone install](../start/installation.md#install). OpenSpec omits details it cannot identify instead of guessing.
 
 `--json` keeps unknown details as explicit `null` values:
 
@@ -2272,6 +2273,8 @@ Update status values:
 | `disabled` | An existing privacy or update-check setting blocked registry access. `latest` is `null`. |
 | `offline` | The registry was unavailable or returned an unusable response. `latest` is `null`. |
 
+For the standalone install, the update command is `openspec install`.
+
 `DO_NOT_TRACK`, telemetry opt-outs, `OPENSPEC_NO_UPDATE_CHECK`, CI detection, and rejected non-HTTPS registry overrides disable the check. Disabled and offline checks still exit 0 because update availability is advisory. This command never upgrades OpenSpec; `canSelfUpgrade` only reports whether the existing `openspec update` path could safely upgrade this copy.
 
 **Exit codes**
@@ -2279,6 +2282,35 @@ Update status values:
 - `0`: the local report printed, including disabled or offline update checks.
 - `1`: command syntax was invalid, such as the unsupported `--upgrade` option.
 
+## openspec install
+
+Installs the standalone `openspec`, a single file that runs without Node.js. Run it from an npm or Homebrew install to switch, or from the standalone install to upgrade it in place.
+
+```bash
+openspec install          # latest release
+openspec install 1.15.0   # a specific release
+```
+
+It runs the release's installer, which picks the file for your machine and checks it against the release's `SHA256SUMS`:
+
+- **From a package manager**: installs to `~/.local/bin` (Windows: `%LOCALAPPDATA%\Programs\openspec`) and prints the command that removes the old copy, such as `npm uninstall -g @fission-ai/openspec`. It never removes that copy itself.
+- **From the standalone install**: replaces the running file where it is, under its own name.
+
+Afterwards it says which copy `openspec` now runs, since a package-manager copy earlier on your PATH keeps running until you remove it.
+
+**Arguments**
+
+| Argument | What it is |
+|---|---|
+| `version` | Release to install, like `1.15.0`. Optional; defaults to the latest. |
+
+`OPENSPEC_INSTALL_DIR` and `OPENSPEC_INSTALL_NAME` choose another folder or file name.
+
+**Exit codes**
+
+- `0`: installed.
+- `1`: the version isn't a release version, or the download or install failed. Your current copy is left as it was.
+
 ## openspec feedback
 
 Submits feedback about OpenSpec.
diff --git a/docs-lab/start/installation.md b/docs-lab/start/installation.md
index 6896321eff..94e8d97071 100644
--- a/docs-lab/start/installation.md
+++ b/docs-lab/start/installation.md
@@ -44,6 +44,16 @@ Rename it to `openspec` (`openspec.exe` on Windows), run `chmod +x openspec` on
 > [!NOTE]
 > macOS blocks a file downloaded in a browser until you run `xattr -d com.apple.quarantine openspec`. The install command above doesn't need this.
 
+### Verify a download
+
+Each release binary comes with a signed record of the workflow run that built it. With the [GitHub CLI](https://cli.github.com), in your terminal:
+
+```bash
+gh attestation verify openspec-darwin-arm64 --repo Fission-AI/OpenSpec
+```
+
+It confirms the file is the one that release's workflow built, or fails. This is optional; the installer already checks every download against `SHA256SUMS`.
+
 ## Install with your AI assistant
 
 Paste this into your AI chat:
@@ -60,7 +70,7 @@ curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md
 
 That fetches [install.md at the repo root](https://github.com/Fission-AI/OpenSpec/blob/main/install.md), a prompt written for any agent that can run shell commands (a few IDE integrations can't). Expect your assistant to:
 
-1. Skip the install if the CLI is already on your machine, and offer to update it the way it was installed. Otherwise, show you the install command above and wait for your confirmation before running it.
+1. Skip the install if the CLI is already on your machine, and offer to update it the way it was installed. If that was npm or Homebrew, mention once that `openspec install` switches to the standalone install, without pushing it. Otherwise, show you the install command above and wait for your confirmation before running it.
 2. Use npm instead only if you ask for it or the installer fails, and stop if your Node is older than 20.19.0.
 3. Verify `openspec` is on your PATH.
 4. Name the folder it thinks you mean, suggest the AI tool you're already talking to, and ask which others you use, then run `openspec init` there (the [project setup](setup.md) step).
@@ -156,18 +166,22 @@ Next, [set up your project](setup.md). If your assistant already ran init, that
 
 ## Switch from npm to the standalone install
 
-Your settings and your projects carry over; only the program changes.
+Switching is optional; npm keeps working. Your settings and your projects carry over; only the program changes.
 
-**1. Install the standalone file.** Run the [install command](#install) for your system.
+**1. Install the standalone copy.** In your terminal:
 
-**2. Remove the npm copy.** It usually comes first on your PATH, so until it's gone it keeps running instead. In your terminal:
+```bash
+openspec install
+```
+
+It installs the standalone `openspec` and prints the command that removes your npm or Homebrew copy.
+
+**2. Remove the old copy.** It usually comes first on your PATH, so until it's gone it keeps running instead. Run the command step 1 printed, for example:
 
 ```npm
 npm uninstall -g @fission-ai/openspec
 ```
 
-On Homebrew, run `brew uninstall openspec` instead.
-
 **3. Check which copy runs.** Open a new terminal:
 
 ```bash
@@ -190,7 +204,7 @@ When a newer CLI is out, [`openspec update`](../reference/cli.md#openspec-update
 
 
 > [!WARNING]
-> With the standalone install, `openspec update` prints the command that replaces your copy in place; run it, or the [install command](#install) again. On Homebrew, run `brew upgrade openspec`. On Deno, re-run the [Deno install](#deno) with `-f`; it won't overwrite the installed command without it. On Nix, use `nix profile upgrade openspec`.
+> With the standalone install, run `openspec install` to replace your copy in place; `openspec update` tells you when a newer one is out. On Homebrew, run `brew upgrade openspec`. On Deno, re-run the [Deno install](#deno) with `-f`; it won't overwrite the installed command without it. On Nix, use `nix profile upgrade openspec`.
 
 > [!NOTE]
 > A global npm install belongs to one Node installation. Switch Node versions with nvm and the `openspec` command doesn't come along, so install it again under the new version.
diff --git a/docs/installation.md b/docs/installation.md
index 557d5fa7cf..6eb3d6afcd 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -43,7 +43,9 @@ order, and stop where a step tells you to stop.
    already installed: run `openspec version --check`, which prints the update
    command for how it was installed when it can tell (otherwise update it the
    way it was installed, e.g. `brew upgrade openspec`), offer to run that, and
-   skip to step 3. Never switch it to a different install method. Otherwise install
+   skip to step 3. If I installed it with a package manager, mention once that
+   `openspec install` switches to the standalone install, but only switch if I
+   ask; never switch it to a different install method on your own. Otherwise install
    the standalone OpenSpec binary, which needs no Node.js. Show me the command
    for my OS and run it only once I confirm, then skip to step 3:
      macOS / Linux:        curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
@@ -205,8 +207,8 @@ openspec --version
 
 Your settings and projects carry over; only the program changes.
 
-1. Run the [install command](#install) for your system.
-2. Remove the npm copy, which otherwise keeps running first on your PATH: `npm uninstall -g @fission-ai/openspec` (Homebrew: `brew uninstall openspec`).
+1. Run `openspec install`. It installs the standalone copy and prints the command that removes your old one.
+2. Run that command, for example `npm uninstall -g @fission-ai/openspec` (Homebrew: `brew uninstall openspec`). Until then the old copy keeps running first on your PATH.
 3. In a new terminal, run `openspec version`. It should print `OpenSpec <version> (standalone)`. If it names a package manager, another copy is still on your PATH: `which -a openspec` (Windows: `where.exe openspec`) lists them.
 
 ## Updating
diff --git a/install.md b/install.md
index 49873a2bdb..1c80aced20 100644
--- a/install.md
+++ b/install.md
@@ -21,7 +21,7 @@ TODO:
 
 ## 1. Install
 
-Run `openspec --version` first. If it already prints a version, the CLI is installed: say so, run `openspec version --check` (it prints the update command for how OpenSpec was installed when it can tell; otherwise update it the way it was installed, e.g. `brew upgrade openspec`), offer to run that command, and skip ahead to step 3. Never switch an existing install to a different method; that leaves two copies competing on PATH.
+Run `openspec --version` first. If it already prints a version, the CLI is installed: say so, run `openspec version --check` (it prints the update command for how OpenSpec was installed when it can tell; otherwise update it the way it was installed, e.g. `brew upgrade openspec`), offer to run that command, and skip ahead to step 3. If it was installed with npm or another package manager, mention once that `openspec install` switches to the standalone install, which runs without Node.js. Only offer it: the user may have chosen npm on purpose, so don't repeat it or switch unless they ask. Never switch an install to a different method on your own; that leaves two copies competing on PATH.
 
 Install the standalone OpenSpec binary. It is a single file and needs no Node.js (on Alpine Linux, `apk add libstdc++ libgcc` first). Show the command for the user's OS and run it only once they confirm, then skip to step 3:
 

From d8a66c392d0d3d2a2c1f0ea05515bbe4e6d155f9 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Fri, 23 Oct 2026 15:27:04 -0500
Subject: [PATCH 22/27] fix(cli): untangle `update` and `install` after merging
 main

Merging main's `update --dry-run` (#2109) interleaved the two commands'
catch blocks: update's JSON-aware failure handling landed in `install`,
which failed the build. Both are restored; against main, index.ts now
differs only by the standalone notice and the `install` command.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/cli/index.ts | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/src/cli/index.ts b/src/cli/index.ts
index 8a7b8dc35c..61e373fa12 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -435,19 +435,6 @@ program
       // exists. Offered, never pushed; deferred when stderr is not a terminal.
       const { maybeShowStandaloneTip } = await import('../core/standalone-tip.js');
       await maybeShowStandaloneTip({ silent: !process.stderr.isTTY });
-    } catch (error) {
-      await failWithError(error);
-      process.exit(1);
-    }
-  });
-
-program
-  .command('install [version]')
-  .description('Install the standalone openspec, which runs without Node.js (latest release unless [version] is given)')
-  .action(async (version?: string) => {
-    try {
-      const { installStandalone } = await import('../commands/install-standalone.js');
-      await installStandalone({ version });
     } catch (error) {
       // The --json dry run follows the agent contract: exactly one JSON
       // document on stdout, even on failure.
@@ -464,6 +451,19 @@ program
     }
   );
 
+program
+  .command('install [version]')
+  .description('Install the standalone openspec, which runs without Node.js (latest release unless [version] is given)')
+  .action(async (version?: string) => {
+    try {
+      const { installStandalone } = await import('../commands/install-standalone.js');
+      await installStandalone({ version });
+    } catch (error) {
+      await failWithError(error);
+      process.exit(1);
+    }
+  });
+
 program
   .command('list')
   .description('List items (changes by default). Use --specs to list specs.')

From e6d9abf8edb5d82a489335c4df36eeda888f5de6 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Fri, 23 Oct 2026 15:41:07 -0500
Subject: [PATCH 23/27] fix(cli): address CodeQL findings in `openspec install`

- The installer URL no longer becomes part of a command line: macOS and
  Linux get it as an argument to a fixed sh script, Windows as an
  environment variable read by a fixed PowerShell line.
- OPENSPEC_DOWNLOAD_URL must be https, or http to localhost only, in
  `openspec install` and both installers. The binary and SHA256SUMS come
  from the same place, so a remote plain-HTTP source could swap both.
- A test wrote to a predictable temp path; it now uses mkdtemp.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/binary/install.ps1               |  7 +++
 scripts/binary/install.sh                |  6 +++
 src/commands/install-standalone.ts       | 59 +++++++++++++++---------
 test/commands/install-standalone.test.ts | 19 ++++++++
 test/core/version-check.test.ts          | 13 ++++--
 5 files changed, 77 insertions(+), 27 deletions(-)

diff --git a/scripts/binary/install.ps1 b/scripts/binary/install.ps1
index 05b6990d47..9236eff8e2 100644
--- a/scripts/binary/install.ps1
+++ b/scripts/binary/install.ps1
@@ -28,6 +28,13 @@
   $version = if ($env:OPENSPEC_VERSION) { $env:OPENSPEC_VERSION } else { 'latest' }
   if ($version -ne 'latest' -and -not $version.StartsWith('v')) { $version = "v$version" }
   $base = if ($env:OPENSPEC_DOWNLOAD_URL) {
+    # The binary and SHA256SUMS come from the same place, so a remote plain
+    # HTTP source could swap both.
+    $uri = $null
+    if (-not [Uri]::TryCreate($env:OPENSPEC_DOWNLOAD_URL, 'Absolute', [ref]$uri) -or
+        -not ($uri.Scheme -eq 'https' -or ($uri.Scheme -eq 'http' -and $uri.IsLoopback))) {
+      throw "openspec install: OPENSPEC_DOWNLOAD_URL must use https (or http to localhost): $($env:OPENSPEC_DOWNLOAD_URL)"
+    }
     $env:OPENSPEC_DOWNLOAD_URL
   } elseif ($version -eq 'latest') {
     'https://github.com/Fission-AI/OpenSpec/releases/latest/download'
diff --git a/scripts/binary/install.sh b/scripts/binary/install.sh
index d2e4c4f6cc..db6827ce19 100644
--- a/scripts/binary/install.sh
+++ b/scripts/binary/install.sh
@@ -40,6 +40,12 @@ main() {
   case "$version" in latest | v*) ;; *) version="v$version" ;; esac
   if [ -n "${OPENSPEC_DOWNLOAD_URL:-}" ]; then
     base="$OPENSPEC_DOWNLOAD_URL"
+    # The binary and SHA256SUMS come from the same place, so a remote plain
+    # HTTP source could swap both.
+    case "$base" in
+      https://* | http://localhost[:/]* | http://localhost | http://127.0.0.1[:/]* | http://127.0.0.1 | "http://[::1]"*) ;;
+      *) fail "OPENSPEC_DOWNLOAD_URL must use https (or http to localhost): $base" ;;
+    esac
   elif [ "$version" = latest ]; then
     base="https://github.com/Fission-AI/OpenSpec/releases/latest/download"
   else
diff --git a/src/commands/install-standalone.ts b/src/commands/install-standalone.ts
index f72637ac85..1f7691dea7 100644
--- a/src/commands/install-standalone.ts
+++ b/src/commands/install-standalone.ts
@@ -71,38 +71,53 @@ export function removeCommandFor(install: CliInstallInfo): string | null {
   }
 }
 
-function releaseBase(version: string | undefined): string {
-  if (process.env.OPENSPEC_DOWNLOAD_URL) return process.env.OPENSPEC_DOWNLOAD_URL.replace(/\/+$/, '');
+/**
+ * Where the release files come from. OPENSPEC_DOWNLOAD_URL (a mirror, or a
+ * local server in tests) must be HTTPS, or plain HTTP to this machine only:
+ * the binary is checked against SHA256SUMS from the same place, so a remote
+ * HTTP source could swap both.
+ */
+export function releaseBase(version: string | undefined, override = process.env.OPENSPEC_DOWNLOAD_URL): string {
+  if (override) {
+    let url: URL;
+    try {
+      url = new URL(override);
+    } catch {
+      throw new Error(`OPENSPEC_DOWNLOAD_URL is not a URL: ${override}`);
+    }
+    const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) {
+      throw new Error(`OPENSPEC_DOWNLOAD_URL must use https (or http to localhost): ${override}`);
+    }
+    return url.href.replace(/\/+$/, '');
+  }
   if (!version || version === 'latest') return `${RELEASES_URL}/latest/download`;
   return `${RELEASES_URL}/download/${version.startsWith('v') ? version : `v${version}`}`;
 }
 
+// Fixed scripts: the installer URL reaches them as data (an argument, or an
+// environment variable), never as part of the command text.
+const POSIX_RUNNER =
+  'f=$(mktemp) || exit 1; { curl -fsSL "$1" -o "$f" 2>/dev/null || wget -q -O "$f" "$1"; } && sh "$f"; s=$?; rm -f "$f"; exit $s';
+const WINDOWS_RUNNER = 'irm $env:OPENSPEC_INSTALLER_URL | iex';
+
 /**
  * Downloads and runs the installer with the same tools as the documented
  * one-liners (curl or wget; PowerShell's irm), so proxies and certificates
- * behave as they do for those. Saved to a file first: piped straight into sh,
- * a failed download would look like a successful run.
+ * behave as they do for those. Saved to a file first on macOS and Linux:
+ * piped straight into sh, a failed download would look like a successful run.
  */
 function runInstaller(scriptUrl: string, env: NodeJS.ProcessEnv): Promise<number> {
-  const [command, args] =
-    process.platform === 'win32'
-      ? [
-          'powershell.exe',
-          ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', `irm '${scriptUrl.replace(/'/g, "''")}' | iex`],
-        ]
-      : [
-          'sh',
-          [
-            '-c',
-            'f=$(mktemp) || exit 1; ' +
-              '{ curl -fsSL "$1" -o "$f" 2>/dev/null || wget -q -O "$f" "$1"; } && sh "$f"; ' +
-              's=$?; rm -f "$f"; exit $s',
-            'openspec-install',
-            scriptUrl,
-          ],
-        ];
+  const windows = process.platform === 'win32';
+  const command = windows ? 'powershell.exe' : 'sh';
+  const args = windows
+    ? ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', WINDOWS_RUNNER]
+    : ['-c', POSIX_RUNNER, 'openspec-install', scriptUrl];
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, { stdio: 'inherit', env });
+    const child = spawn(command, args, {
+      stdio: 'inherit',
+      env: windows ? { ...env, OPENSPEC_INSTALLER_URL: scriptUrl } : env,
+    });
     child.on('error', reject);
     child.on('close', (code) => resolve(code ?? 1));
   });
diff --git a/test/commands/install-standalone.test.ts b/test/commands/install-standalone.test.ts
index e8daa19bd8..f76d2ed3f9 100644
--- a/test/commands/install-standalone.test.ts
+++ b/test/commands/install-standalone.test.ts
@@ -4,6 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import {
   installStandalone,
+  releaseBase,
   removeCommandFor,
   resolveInstallTarget,
 } from '../../src/commands/install-standalone.js';
@@ -95,6 +96,24 @@ describe('openspec install', () => {
     });
   });
 
+  describe('releaseBase', () => {
+    it('downloads from the latest release, or the release named', () => {
+      const releases = 'https://github.com/Fission-AI/OpenSpec/releases';
+      expect(releaseBase(undefined, '')).toBe(`${releases}/latest/download`);
+      expect(releaseBase('1.15.0', '')).toBe(`${releases}/download/v1.15.0`);
+      expect(releaseBase('v1.15.0', '')).toBe(`${releases}/download/v1.15.0`);
+    });
+
+    it('accepts a mirror over https, and plain http only to this machine', () => {
+      expect(releaseBase(undefined, 'https://mirror.example.com/openspec/')).toBe('https://mirror.example.com/openspec');
+      expect(releaseBase(undefined, 'http://127.0.0.1:8765')).toBe('http://127.0.0.1:8765');
+      expect(releaseBase(undefined, 'http://localhost:9/x')).toBe('http://localhost:9/x');
+      for (const unsafe of ['http://mirror.example.com', 'http://localhost.example.com', 'ftp://x', 'not a url']) {
+        expect(() => releaseBase(undefined, unsafe)).toThrow('OPENSPEC_DOWNLOAD_URL');
+      }
+    });
+  });
+
   it('refuses a version that is not a release version, before downloading anything', async () => {
     await expect(installStandalone({ version: '1.2.3; rm -rf /' })).rejects.toThrow('Not a release version');
     await expect(installStandalone({ version: 'main' })).rejects.toThrow('Not a release version');
diff --git a/test/core/version-check.test.ts b/test/core/version-check.test.ts
index 8c99240129..20437b235f 100644
--- a/test/core/version-check.test.ts
+++ b/test/core/version-check.test.ts
@@ -1266,11 +1266,14 @@ describe('standalone binary', () => {
   });
 
   it('upgrades with `openspec install`, never through a package manager', async () => {
-    const { getCliInstallInfo, getCliUpdateCommand, buildCliUpdateLines, canSelfUpgrade } = await loadMarked();
-    // `openspec` on PATH is this binary.
-    const binDir = path.dirname(executable);
-    fs.mkdirSync(binDir, { recursive: true });
-    fs.writeFileSync(executable, '', { mode: 0o755 });
+    // `openspec` on PATH is this binary, in a fresh private folder.
+    const binDir = fs.mkdtempSync(path.join(os.tmpdir(), "it's bin-"));
+    const onPath = path.join(binDir, path.basename(executable));
+    fs.writeFileSync(onPath, '', { mode: 0o755 });
+    vi.resetModules();
+    const { markStandaloneBinary, getCliInstallInfo, getCliUpdateCommand, buildCliUpdateLines, canSelfUpgrade } =
+      await import('../../src/core/version-check.js');
+    markStandaloneBinary(onPath);
     const originalPath = process.env.PATH;
     process.env.PATH = `${binDir}${path.delimiter}${originalPath ?? ''}`;
     try {

From 6f98098b11dd00c0750cb4bf2cc534006872e4ea Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Fri, 23 Oct 2026 18:27:52 -0500
Subject: [PATCH 24/27] fix(ci): attach binaries to a release even if its tag
 is renamed

A release can be retagged while the Binaries workflow runs (the scoped
@fission-ai/openspec@x.y.z tag corrected to vx.y.z), which made the upload
look up a tag the release no longer has. The upload now finds the release by
id and uses its current tag.

The release skill now also checks that the binaries, SHA256SUMS and both
installers are attached, and says to re-run binaries.yml (never npm) if
they are missing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .agents/skills/release-openspec/SKILL.md |  3 ++-
 .github/workflows/binaries.yml           | 10 +++++++++-
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/.agents/skills/release-openspec/SKILL.md b/.agents/skills/release-openspec/SKILL.md
index 99d4f5df59..0b077dfdf4 100644
--- a/.agents/skills/release-openspec/SKILL.md
+++ b/.agents/skills/release-openspec/SKILL.md
@@ -146,7 +146,8 @@ After the Version Packages PR merges:
    - `npm view @fission-ai/openspec@<version> version`
    - remote tag `v<version>` points at the expected commit;
    - `gh release view v<version>` exists and is not a prerelease.
-3. If only some artifacts exist, report partial state and resume verification before retrying any publish action. Never republish a version already on npm.
+   - The release's assets include the 8 `openspec-*` standalone binaries, `SHA256SUMS`, `install.sh` and `install.ps1`, attached by the Binaries workflow (`binaries.yml`) about 10 minutes after the release is published.
+3. If only some artifacts exist, report partial state and resume verification before retrying any publish action. Never republish a version already on npm. Missing binaries never need an npm action: re-run `binaries.yml` with `workflow_dispatch` and the release tag to attach them.
 4. Once all artifacts exist, read [references/release-notes.md](references/release-notes.md), polish the GitHub Release, and verify the saved title/body.
 
 ## Cut a beta
diff --git a/.github/workflows/binaries.yml b/.github/workflows/binaries.yml
index 366b2bef52..2d928dc67a 100644
--- a/.github/workflows/binaries.yml
+++ b/.github/workflows/binaries.yml
@@ -247,10 +247,18 @@ jobs:
       - name: Upload
         env:
           GH_TOKEN: ${{ github.token }}
+          RELEASE_ID: ${{ github.event.release.id }}
         run: |
           cd dist-bin
           sha256sum --check SHA256SUMS
-          gh release upload "$REF" openspec-* SHA256SUMS install.sh install.ps1 --clobber --repo "$GITHUB_REPOSITORY"
+          # A release can be retagged while this runs (the scoped
+          # @fission-ai/openspec@x.y.z tag corrected to vx.y.z), so find it by
+          # id, which never changes, and upload to whatever tag it has now.
+          tag="$REF"
+          if [ -n "$RELEASE_ID" ]; then
+            tag=$(gh api "repos/$GITHUB_REPOSITORY/releases/$RELEASE_ID" --jq .tag_name)
+          fi
+          gh release upload "$tag" openspec-* SHA256SUMS install.sh install.ps1 --clobber --repo "$GITHUB_REPOSITORY"
       # Signed proof each binary was built by this workflow from this tag, which
       # anyone can check with `gh attestation verify`. The binaries are not
       # notarized or code-signed yet, so this is the verifiable trail meanwhile.

From 73673768b8783f2d23c596c6352b1258e9461670 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Fri, 23 Oct 2026 19:00:10 -0500
Subject: [PATCH 25/27] fix(cli): never let a release in progress break the
 installers

Two problems, both from trusting a string instead of checking the thing:

- Every release briefly broke the default install, and a failed Binaries
  run broke it for good. The installers hung off `releases/latest`, which
  GitHub moves the moment a release is published, about ten minutes before
  its binaries are attached. Now the installers are served from main (always
  present), and "latest" means the newest stable release that has its
  SHA256SUMS, which is uploaded last. Until then they install the previous
  release and say so; with no complete release they fail clearly and point
  at npm. A pinned OPENSPEC_VERSION still installs exactly that release.
- install.sh matched OPENSPEC_DOWNLOAD_URL by prefix, so
  `http://localhost:80@evil.example/` passed as localhost while connecting
  to evil.example over plain HTTP. It now parses the host, refuses any user
  part, and requires a numeric port; install.ps1 and `openspec install`,
  which already parsed the host, also refuse a user part now, so all three
  apply the same rule, including to the new OPENSPEC_RELEASES_URL.

test/binary-installer.test.ts runs the real install.sh against a local
stand-in for the releases page; all 16 cases fail on the previous script.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/binary/install.ps1               |  60 +++++---
 scripts/binary/install.sh                |  94 +++++++++---
 src/commands/install-standalone.ts       |  48 ++++---
 test/binary-installer.test.ts            | 176 +++++++++++++++++++++++
 test/commands/install-standalone.test.ts |  46 ++++--
 5 files changed, 356 insertions(+), 68 deletions(-)
 create mode 100644 test/binary-installer.test.ts

diff --git a/scripts/binary/install.ps1 b/scripts/binary/install.ps1
index 9236eff8e2..685fb7e9b5 100644
--- a/scripts/binary/install.ps1
+++ b/scripts/binary/install.ps1
@@ -1,11 +1,12 @@
 # Installs the standalone `openspec.exe` (no Node.js needed) on Windows.
 #
-#   irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex
+#   irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex
 #
-# $env:OPENSPEC_VERSION      release to install (default: latest), e.g. v1.15.0
+# $env:OPENSPEC_VERSION      release to install (default: the newest complete one), e.g. v1.15.0
 # $env:OPENSPEC_INSTALL_DIR  where to put it (default: %LOCALAPPDATA%\Programs\openspec)
 # $env:OPENSPEC_INSTALL_NAME file name to install as (default: openspec.exe)
-# $env:OPENSPEC_DOWNLOAD_URL base URL of the release assets (mirrors, testing)
+# $env:OPENSPEC_RELEASES_URL releases page to install from (default: GitHub's; mirrors, testing)
+# $env:OPENSPEC_DOWNLOAD_URL one folder holding the release files (mirrors, testing)
 #
 # Runs in Windows PowerShell 5.1 and PowerShell 7. It throws instead of
 # calling exit, which would close the window of anyone who piped it into iex.
@@ -27,20 +28,20 @@
 
   $version = if ($env:OPENSPEC_VERSION) { $env:OPENSPEC_VERSION } else { 'latest' }
   if ($version -ne 'latest' -and -not $version.StartsWith('v')) { $version = "v$version" }
-  $base = if ($env:OPENSPEC_DOWNLOAD_URL) {
-    # The binary and SHA256SUMS come from the same place, so a remote plain
-    # HTTP source could swap both.
+  # The binary and SHA256SUMS come from the same place, so a remote plain HTTP
+  # source could swap both: only https, or http to this machine. [Uri] parses
+  # the host, so http://localhost:80@evil.example/ is evil.example, not loopback.
+  function Assert-Source($label, $value) {
     $uri = $null
-    if (-not [Uri]::TryCreate($env:OPENSPEC_DOWNLOAD_URL, 'Absolute', [ref]$uri) -or
+    if (-not [Uri]::TryCreate($value, 'Absolute', [ref]$uri) -or $uri.UserInfo -or
         -not ($uri.Scheme -eq 'https' -or ($uri.Scheme -eq 'http' -and $uri.IsLoopback))) {
-      throw "openspec install: OPENSPEC_DOWNLOAD_URL must use https (or http to localhost): $($env:OPENSPEC_DOWNLOAD_URL)"
+      throw "openspec install: $label must use https (or http to localhost): $value"
     }
-    $env:OPENSPEC_DOWNLOAD_URL
-  } elseif ($version -eq 'latest') {
-    'https://github.com/Fission-AI/OpenSpec/releases/latest/download'
-  } else {
-    "https://github.com/Fission-AI/OpenSpec/releases/download/$version"
   }
+  $releases = if ($env:OPENSPEC_RELEASES_URL) { $env:OPENSPEC_RELEASES_URL.TrimEnd('/') } else { 'https://github.com/Fission-AI/OpenSpec/releases' }
+  Assert-Source 'OPENSPEC_RELEASES_URL' $releases
+  if ($env:OPENSPEC_DOWNLOAD_URL) { Assert-Source 'OPENSPEC_DOWNLOAD_URL' $env:OPENSPEC_DOWNLOAD_URL }
+  $npmHint = 'Or install with npm (Node.js 20.19+): npm install -g @fission-ai/openspec'
   $dir = if ($env:OPENSPEC_INSTALL_DIR) { $env:OPENSPEC_INSTALL_DIR } else { Join-Path $env:LOCALAPPDATA 'Programs\openspec' }
   # Absolute, so the user PATH entry works from any directory.
   $dir = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($dir)
@@ -54,14 +55,41 @@
   $tmp = Join-Path $dir ('.openspec-install-' + [Guid]::NewGuid().ToString('N'))
   New-Item -ItemType Directory -Path $tmp | Out-Null
   try {
-    Write-Host "Downloading $asset ($version)..."
     $exe = Join-Path $tmp $asset
     $sums = Join-Path $tmp 'SHA256SUMS'
+    if ($env:OPENSPEC_DOWNLOAD_URL) {
+      $base = $env:OPENSPEC_DOWNLOAD_URL.TrimEnd('/')
+    } elseif ($version -ne 'latest') {
+      $base = "$releases/download/$version"
+    } else {
+      # The newest stable release whose files are all attached. GitHub calls a
+      # release "latest" the moment it is published, minutes before the
+      # Binaries workflow attaches the files (and for good, if that fails), so
+      # "latest" is not trusted. SHA256SUMS is uploaded last: a release that
+      # has it is complete.
+      $feed = ''
+      try { $feed = (Invoke-WebRequest -UseBasicParsing -Uri "$releases.atom").Content } catch { Write-Verbose "No release feed: $_" }
+      $tags = @([regex]::Matches($feed, '/releases/tag/(v\d+\.\d+\.\d+)"') | ForEach-Object { $_.Groups[1].Value } | Select-Object -Unique)
+      foreach ($tag in $tags) {
+        try {
+          Invoke-WebRequest -UseBasicParsing -Uri "$releases/download/$tag/SHA256SUMS" -OutFile $sums
+          $version = $tag
+          break
+        } catch {
+          Write-Verbose "$tag is not complete yet: $_"
+        }
+      }
+      if ($version -eq 'latest') { throw "openspec install: found no release with the standalone files at $releases. $npmHint" }
+      if ($tags.Count -gt 0 -and $version -ne $tags[0]) { Write-Host "$($tags[0]) is still being prepared; installing $version." }
+      $base = "$releases/download/$version"
+    }
+
+    Write-Host "Downloading $asset ($version)..."
     try {
       Invoke-WebRequest -UseBasicParsing -Uri "$base/$asset" -OutFile $exe
-      Invoke-WebRequest -UseBasicParsing -Uri "$base/SHA256SUMS" -OutFile $sums
+      if (-not (Test-Path $sums)) { Invoke-WebRequest -UseBasicParsing -Uri "$base/SHA256SUMS" -OutFile $sums }
     } catch {
-      throw "openspec install: could not download from ${base}: $($_.Exception.Message). Or install with npm (Node.js 20.19+): npm install -g @fission-ai/openspec"
+      throw "openspec install: could not download from ${base}: $($_.Exception.Message). $npmHint"
     }
 
     $line = Get-Content $sums | Where-Object { ($_ -split '\s+')[1] -eq $asset } | Select-Object -First 1
diff --git a/scripts/binary/install.sh b/scripts/binary/install.sh
index db6827ce19..956b5088cf 100644
--- a/scripts/binary/install.sh
+++ b/scripts/binary/install.sh
@@ -1,16 +1,45 @@
 #!/bin/sh
 # Installs the standalone `openspec` binary (no Node.js needed) on Linux or macOS.
 #
-#   curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+#   curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh
 #
-# OPENSPEC_VERSION      release to install (default: latest), e.g. v1.15.0
+# OPENSPEC_VERSION      release to install (default: the newest complete one), e.g. v1.15.0
 # OPENSPEC_INSTALL_DIR  where to put it (default: ~/.local/bin)
 # OPENSPEC_INSTALL_NAME file name to install as (default: openspec)
-# OPENSPEC_DOWNLOAD_URL base URL of the release assets (mirrors, testing)
+# OPENSPEC_RELEASES_URL releases page to install from (default: GitHub's; mirrors, testing)
+# OPENSPEC_DOWNLOAD_URL one folder holding the release files (mirrors, testing)
 set -eu
 
 fail() { echo "openspec install: $*" >&2; exit 1; }
 
+# The binary and SHA256SUMS come from the same place, so a remote plain HTTP
+# source could swap both: only https, or http to this machine. The host is
+# parsed, not prefix-matched: http://localhost:80@evil.example/ names
+# evil.example, so anything with a user part is refused.
+check_source() {
+  case "$2" in
+    https://*) scheme=https authority=${2#https://} ;;
+    http://*) scheme=http authority=${2#http://} ;;
+    *) fail "$1 must use https (or http to localhost): $2" ;;
+  esac
+  authority=${authority%%/*}
+  authority=${authority%%\?*}
+  authority=${authority%%#*}
+  case "$authority" in *@*) fail "$1 must use https (or http to localhost): $2" ;; esac
+  [ "$scheme" = https ] && return 0
+  host=$authority
+  case "$authority" in
+    "[::1]:"* | localhost:* | 127.0.0.1:*)
+      host=${authority%:*}
+      case "${authority##*:}" in "" | *[!0-9]*) fail "$1 has an invalid port: $2" ;; esac
+      ;;
+  esac
+  case "$host" in
+    localhost | 127.0.0.1 | "[::1]") return 0 ;;
+    *) fail "$1 must use https (or http to localhost): $2" ;;
+  esac
+}
+
 # Everything runs from main, so a download cut short while piped into sh
 # runs nothing instead of half a script.
 main() {
@@ -38,18 +67,11 @@ main() {
 
   version="${OPENSPEC_VERSION:-latest}"
   case "$version" in latest | v*) ;; *) version="v$version" ;; esac
+  releases="${OPENSPEC_RELEASES_URL:-https://github.com/Fission-AI/OpenSpec/releases}"
+  releases=${releases%/}
+  check_source OPENSPEC_RELEASES_URL "$releases"
   if [ -n "${OPENSPEC_DOWNLOAD_URL:-}" ]; then
-    base="$OPENSPEC_DOWNLOAD_URL"
-    # The binary and SHA256SUMS come from the same place, so a remote plain
-    # HTTP source could swap both.
-    case "$base" in
-      https://* | http://localhost[:/]* | http://localhost | http://127.0.0.1[:/]* | http://127.0.0.1 | "http://[::1]"*) ;;
-      *) fail "OPENSPEC_DOWNLOAD_URL must use https (or http to localhost): $base" ;;
-    esac
-  elif [ "$version" = latest ]; then
-    base="https://github.com/Fission-AI/OpenSpec/releases/latest/download"
-  else
-    base="https://github.com/Fission-AI/OpenSpec/releases/download/$version"
+    check_source OPENSPEC_DOWNLOAD_URL "$OPENSPEC_DOWNLOAD_URL"
   fi
   if [ -n "${OPENSPEC_INSTALL_DIR:-}" ]; then
     dir="$OPENSPEC_INSTALL_DIR"
@@ -76,11 +98,51 @@ main() {
       fail "curl or wget is required"
     fi
   }
+  fetch() {
+    if command -v curl >/dev/null 2>&1; then
+      curl -fsSL --retry 3 "$1"
+    elif command -v wget >/dev/null 2>&1; then
+      wget -q -O - "$1"
+    else
+      fail "curl or wget is required"
+    fi
+  }
 
-  echo "Downloading $asset ($version)..."
   npm_hint="or install with npm (Node.js 20.19+): npm install -g @fission-ai/openspec"
+  if [ -n "${OPENSPEC_DOWNLOAD_URL:-}" ]; then
+    base=${OPENSPEC_DOWNLOAD_URL%/}
+  elif [ "$version" != latest ]; then
+    base="$releases/download/$version"
+  else
+    # The newest stable release whose files are all attached. GitHub calls a
+    # release "latest" the moment it is published, minutes before the Binaries
+    # workflow attaches the files (and for good, if that fails), so "latest"
+    # is not trusted. SHA256SUMS is uploaded last: a release that has it is
+    # complete.
+    newest=""
+    tags=$(fetch "$releases.atom" 2>/dev/null |
+      grep -o '/releases/tag/v[0-9]*\.[0-9]*\.[0-9]*"' | sed 's#.*/tag/##; s/"$//' | awk '!seen[$0]++') || tags=""
+    for tag in $tags; do
+      [ -n "$newest" ] || newest=$tag
+      if download "$releases/download/$tag/SHA256SUMS" "$tmp/SHA256SUMS" 2>/dev/null; then
+        version=$tag
+        break
+      fi
+    done
+    if [ "$version" = latest ]; then
+      fail "found no release with the standalone files at $releases; $npm_hint"
+    fi
+    if [ "$version" != "$newest" ]; then
+      echo "$newest is still being prepared; installing $version."
+    fi
+    base="$releases/download/$version"
+  fi
+
+  echo "Downloading $asset ($version)..."
   download "$base/$asset" "$tmp/$asset" || fail "could not download $base/$asset; $npm_hint"
-  download "$base/SHA256SUMS" "$tmp/SHA256SUMS" || fail "could not download $base/SHA256SUMS; $npm_hint"
+  if [ ! -s "$tmp/SHA256SUMS" ]; then
+    download "$base/SHA256SUMS" "$tmp/SHA256SUMS" || fail "could not download $base/SHA256SUMS; $npm_hint"
+  fi
 
   expected=$(awk -v f="$asset" '$2 == f { print $1 }' "$tmp/SHA256SUMS")
   [ -n "$expected" ] || fail "$asset is not listed in SHA256SUMS"
diff --git a/src/commands/install-standalone.ts b/src/commands/install-standalone.ts
index 1f7691dea7..42b209bdb7 100644
--- a/src/commands/install-standalone.ts
+++ b/src/commands/install-standalone.ts
@@ -16,7 +16,9 @@ import {
  * is the user's choice, and so is when.
  */
 
-const RELEASES_URL = 'https://github.com/Fission-AI/OpenSpec/releases';
+// The installers come from main, which always has them; they then pick the
+// newest release whose files are all attached (see install.sh).
+const INSTALLER_BASE = 'https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary';
 const RELEASE_VERSION = /^v?\d{1,10}\.\d{1,10}\.\d{1,10}(?:-[0-9A-Za-z.-]{1,64})?$/;
 
 export interface InstallTarget {
@@ -72,27 +74,30 @@ export function removeCommandFor(install: CliInstallInfo): string | null {
 }
 
 /**
- * Where the release files come from. OPENSPEC_DOWNLOAD_URL (a mirror, or a
- * local server in tests) must be HTTPS, or plain HTTP to this machine only:
- * the binary is checked against SHA256SUMS from the same place, so a remote
- * HTTP source could swap both.
+ * Checks a download source given through the environment. Release files and
+ * SHA256SUMS come from the same place, so a remote plain-HTTP source could
+ * swap both: only https, or http to this machine. The host is parsed, not
+ * prefix-matched, and a user part (http://localhost:80@evil.example/) is
+ * refused.
  */
-export function releaseBase(version: string | undefined, override = process.env.OPENSPEC_DOWNLOAD_URL): string {
-  if (override) {
-    let url: URL;
-    try {
-      url = new URL(override);
-    } catch {
-      throw new Error(`OPENSPEC_DOWNLOAD_URL is not a URL: ${override}`);
-    }
-    const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
-    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) {
-      throw new Error(`OPENSPEC_DOWNLOAD_URL must use https (or http to localhost): ${override}`);
-    }
-    return url.href.replace(/\/+$/, '');
+export function checkSource(label: string, value: string): string {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${label} is not a URL: ${value}`);
   }
-  if (!version || version === 'latest') return `${RELEASES_URL}/latest/download`;
-  return `${RELEASES_URL}/download/${version.startsWith('v') ? version : `v${version}`}`;
+  const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if (url.username || url.password || (url.protocol !== 'https:' && !(url.protocol === 'http:' && local))) {
+    throw new Error(`${label} must use https (or http to localhost): ${value}`);
+  }
+  return url.href.replace(/\/+$/, '');
+}
+
+/** Where the installer script comes from: OPENSPEC_DOWNLOAD_URL when set (mirrors, tests), else main. */
+export function installerBase(env: NodeJS.ProcessEnv = process.env): string {
+  if (env.OPENSPEC_RELEASES_URL) checkSource('OPENSPEC_RELEASES_URL', env.OPENSPEC_RELEASES_URL);
+  return env.OPENSPEC_DOWNLOAD_URL ? checkSource('OPENSPEC_DOWNLOAD_URL', env.OPENSPEC_DOWNLOAD_URL) : INSTALLER_BASE;
 }
 
 // Fixed scripts: the installer URL reaches them as data (an argument, or an
@@ -129,8 +134,7 @@ export async function installStandalone(options: { version?: string } = {}): Pro
     throw new Error(`Not a release version: ${version}. Use one like 1.15.0, or leave it out for the latest.`);
   }
 
-  const base = releaseBase(version);
-  const scriptUrl = `${base}/${process.platform === 'win32' ? 'install.ps1' : 'install.sh'}`;
+  const scriptUrl = `${installerBase()}/${process.platform === 'win32' ? 'install.ps1' : 'install.sh'}`;
   const target = resolveInstallTarget();
   const exitCode = await runInstaller(scriptUrl, {
     ...process.env,
diff --git a/test/binary-installer.test.ts b/test/binary-installer.test.ts
new file mode 100644
index 0000000000..76763fa685
--- /dev/null
+++ b/test/binary-installer.test.ts
@@ -0,0 +1,176 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import type { AddressInfo } from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+// scripts/binary/install.sh against a local stand-in for GitHub's releases
+// page: its .atom feed plus /download/<tag>/<file>. The "binaries" are tiny
+// scripts that print their version, so no real build is needed.
+const installer = path.resolve('scripts/binary/install.sh');
+const ASSETS = [
+  'openspec-darwin-arm64',
+  'openspec-darwin-x64',
+  'openspec-linux-arm64',
+  'openspec-linux-x64',
+  'openspec-linux-arm64-musl',
+  'openspec-linux-x64-musl',
+];
+
+describe.skipIf(process.platform === 'win32')('standalone installer (install.sh)', () => {
+  let root: string;
+  let server: http.Server;
+  let base: string;
+
+  /** A release whose files are attached; `complete: false` leaves out SHA256SUMS, as mid-upload. */
+  function release(site: string, tag: string, options: { complete?: boolean; tamper?: boolean } = {}) {
+    const dir = path.join(root, site, 'releases', 'download', tag);
+    fs.mkdirSync(dir, { recursive: true });
+    const sums: string[] = [];
+    for (const asset of ASSETS) {
+      const body = `#!/bin/sh\necho ${tag.replace(/^v/, '')}\n`;
+      fs.writeFileSync(path.join(dir, asset), options.tamper ? `${body}# changed\n` : body);
+      sums.push(`${createHash('sha256').update(body).digest('hex')}  ${asset}`);
+    }
+    if (options.complete !== false) fs.writeFileSync(path.join(dir, 'SHA256SUMS'), sums.join('\n') + '\n');
+  }
+
+  /** The releases feed, newest first, as GitHub lists it. */
+  function feed(site: string, tags: string[]) {
+    fs.mkdirSync(path.join(root, site), { recursive: true });
+    const entries = tags.map(
+      (tag) => `<entry><link rel="alternate" type="text/html" href="https://github.com/Fission-AI/OpenSpec/releases/tag/${tag}"/></entry>`
+    );
+    fs.writeFileSync(path.join(root, site, 'releases.atom'), `<feed>${entries.join('')}</feed>`);
+  }
+
+  function install(site: string, env: Record<string, string> = {}) {
+    const home = fs.mkdtempSync(path.join(root, 'home-'));
+    return new Promise<{ code: number; out: string; installed: string | null }>((resolve) => {
+      execFile(
+        'sh',
+        [installer],
+        {
+          env: {
+            PATH: process.env.PATH,
+            HOME: home,
+            OPENSPEC_RELEASES_URL: `${base}/${site}/releases`,
+            OPENSPEC_INSTALL_DIR: path.join(home, 'bin'),
+            ...env,
+          },
+        },
+        (error, stdout, stderr) => {
+          const target = path.join(home, 'bin', 'openspec');
+          resolve({
+            code: error ? Number(error.code ?? 1) : 0,
+            out: stdout + stderr,
+            installed: fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null,
+          });
+        }
+      );
+    });
+  }
+
+  beforeAll(async () => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'openspec-installer-'));
+    server = http.createServer((req, res) => {
+      const file = path.join(root, decodeURIComponent(new URL(req.url ?? '/', 'http://x').pathname));
+      if (!file.startsWith(root) || !fs.existsSync(file) || !fs.statSync(file).isFile()) {
+        res.writeHead(404).end();
+        return;
+      }
+      res.writeHead(200).end(fs.readFileSync(file));
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+
+    feed('current', ['v1.2.0', 'v1.1.0']);
+    release('current', 'v1.2.0');
+    release('current', 'v1.1.0');
+
+    // v1.2.0 published, its files still uploading (or the upload failed).
+    feed('mid-release', ['v1.2.0', 'v1.1.0']);
+    release('mid-release', 'v1.2.0', { complete: false });
+    release('mid-release', 'v1.1.0');
+
+    feed('nothing-complete', ['v1.2.0']);
+    release('nothing-complete', 'v1.2.0', { complete: false });
+
+    // Betas and the scoped tag changesets creates first are not stable v-tags.
+    feed('noise', ['v1.3.0-beta.1', '%40fission-ai%2Fopenspec%401.3.0', 'v1.2.0']);
+    release('noise', 'v1.3.0-beta.1');
+    release('noise', 'v1.2.0');
+
+    feed('tampered', ['v1.2.0']);
+    release('tampered', 'v1.2.0', { tamper: true });
+  });
+
+  afterAll(async () => {
+    await new Promise((resolve) => server.close(resolve));
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('installs the newest release when its files are all attached', async () => {
+    const result = await install('current');
+    expect(result.code, result.out).toBe(0);
+    expect(result.installed).toContain('echo 1.2.0');
+    expect(result.out).not.toContain('still being prepared');
+  });
+
+  it('keeps installing the previous release while the newest is incomplete', async () => {
+    const result = await install('mid-release');
+    expect(result.code, result.out).toBe(0);
+    expect(result.installed).toContain('echo 1.1.0');
+    expect(result.out).toContain('v1.2.0 is still being prepared; installing v1.1.0.');
+  });
+
+  it('fails clearly, pointing at npm, when no release is complete', async () => {
+    const result = await install('nothing-complete');
+    expect(result.code).not.toBe(0);
+    expect(result.installed).toBeNull();
+    expect(result.out).toContain('found no release with the standalone files');
+    expect(result.out).toContain('npm install -g @fission-ai/openspec');
+  });
+
+  it('installs a pinned version even when it is not the newest', async () => {
+    const result = await install('current', { OPENSPEC_VERSION: '1.1.0' });
+    expect(result.code, result.out).toBe(0);
+    expect(result.installed).toContain('echo 1.1.0');
+  });
+
+  it('ignores betas and scoped tags when choosing the newest release', async () => {
+    const result = await install('noise');
+    expect(result.code, result.out).toBe(0);
+    expect(result.installed).toContain('echo 1.2.0');
+  });
+
+  it('refuses a file that does not match SHA256SUMS', async () => {
+    const result = await install('tampered');
+    expect(result.code).not.toBe(0);
+    expect(result.installed).toBeNull();
+    expect(result.out).toContain('checksum mismatch');
+  });
+
+  it.each([
+    'http://localhost:80@evil.example/releases',
+    'http://localhost@evil.example',
+    'https://user@mirror.example.com',
+    'http://user:pw@127.0.0.1@evil.example/',
+    'http://127.0.0.1.evil.example/',
+    'http://localhost.evil.example',
+    'http://localhost:80.evil.example/',
+    'http://[::1].evil.example/',
+    'http://evil.example/?h=localhost',
+    'ftp://localhost/',
+  ])('refuses %s as a download source, before downloading anything', async (url) => {
+    for (const variable of ['OPENSPEC_RELEASES_URL', 'OPENSPEC_DOWNLOAD_URL']) {
+      const result = await install('current', { [variable]: url });
+      expect(result.code).not.toBe(0);
+      expect(result.out).toMatch(/must use https|invalid port/);
+      expect(result.out).not.toContain('Downloading');
+    }
+  });
+});
diff --git a/test/commands/install-standalone.test.ts b/test/commands/install-standalone.test.ts
index f76d2ed3f9..de3a7f0382 100644
--- a/test/commands/install-standalone.test.ts
+++ b/test/commands/install-standalone.test.ts
@@ -4,7 +4,8 @@ import os from 'node:os';
 import path from 'node:path';
 import {
   installStandalone,
-  releaseBase,
+  checkSource,
+  installerBase,
   removeCommandFor,
   resolveInstallTarget,
 } from '../../src/commands/install-standalone.js';
@@ -96,21 +97,38 @@ describe('openspec install', () => {
     });
   });
 
-  describe('releaseBase', () => {
-    it('downloads from the latest release, or the release named', () => {
-      const releases = 'https://github.com/Fission-AI/OpenSpec/releases';
-      expect(releaseBase(undefined, '')).toBe(`${releases}/latest/download`);
-      expect(releaseBase('1.15.0', '')).toBe(`${releases}/download/v1.15.0`);
-      expect(releaseBase('v1.15.0', '')).toBe(`${releases}/download/v1.15.0`);
+  describe('installerBase', () => {
+    it('takes the installer from main, which always has it, unless a mirror is set', () => {
+      expect(installerBase({})).toBe('https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary');
+      expect(installerBase({ OPENSPEC_DOWNLOAD_URL: 'http://127.0.0.1:8765/' })).toBe('http://127.0.0.1:8765');
     });
 
-    it('accepts a mirror over https, and plain http only to this machine', () => {
-      expect(releaseBase(undefined, 'https://mirror.example.com/openspec/')).toBe('https://mirror.example.com/openspec');
-      expect(releaseBase(undefined, 'http://127.0.0.1:8765')).toBe('http://127.0.0.1:8765');
-      expect(releaseBase(undefined, 'http://localhost:9/x')).toBe('http://localhost:9/x');
-      for (const unsafe of ['http://mirror.example.com', 'http://localhost.example.com', 'ftp://x', 'not a url']) {
-        expect(() => releaseBase(undefined, unsafe)).toThrow('OPENSPEC_DOWNLOAD_URL');
-      }
+    it('checks OPENSPEC_RELEASES_URL too, though the installer is what reads it', () => {
+      expect(() => installerBase({ OPENSPEC_RELEASES_URL: 'http://localhost:80@evil.example/' })).toThrow(
+        'OPENSPEC_RELEASES_URL must use https'
+      );
+    });
+  });
+
+  describe('checkSource', () => {
+    it('accepts https anywhere, and plain http only to this machine', () => {
+      expect(checkSource('X', 'https://mirror.example.com/openspec/')).toBe('https://mirror.example.com/openspec');
+      expect(checkSource('X', 'http://127.0.0.1:8765')).toBe('http://127.0.0.1:8765');
+      expect(checkSource('X', 'http://localhost:9/x')).toBe('http://localhost:9/x');
+      expect(checkSource('X', 'http://[::1]:8/x')).toBe('http://[::1]:8/x');
+    });
+
+    it.each([
+      'http://localhost:80@evil.example/x',
+      'http://localhost@evil.example',
+      'https://user@mirror.example.com',
+      'http://127.0.0.1.evil.example/',
+      'http://localhost.evil.example',
+      'http://mirror.example.com',
+      'ftp://localhost/',
+      'not a url',
+    ])('refuses %s', (unsafe) => {
+      expect(() => checkSource('OPENSPEC_DOWNLOAD_URL', unsafe)).toThrow('OPENSPEC_DOWNLOAD_URL');
     });
   });
 

From 36842097703483a2b18805654a6888cf18ea2364 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Fri, 23 Oct 2026 19:00:10 -0500
Subject: [PATCH 26/27] ci(binaries): upload SHA256SUMS last and point installs
 at main

- The release upload attaches the binaries first and SHA256SUMS last, so
  a release with SHA256SUMS is complete. The installers are no longer
  release assets; they are served from main.
- The Windows verify jobs run install.ps1, in PowerShell 5.1 and 7, against
  a stand-in releases page whose newest release is incomplete, and check it
  installs the previous one with a note and refuses a localhost URL whose
  real host is remote.
- Docs, install.md, the changeset and the release skill use the new
  installer URLs and say what "newest release" means.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .agents/skills/release-openspec/SKILL.md |  2 +-
 .changeset/standalone-binary.md          |  2 +-
 .github/workflows/binaries.yml           | 28 +++++++++++++++++++++++-
 README.md                                |  4 ++--
 docs-lab/reference/cli.md                |  4 ++--
 docs-lab/start/installation.md           |  5 +++--
 docs/README.md                           |  2 +-
 docs/getting-started.md                  |  2 +-
 docs/installation.md                     | 10 ++++-----
 install.md                               |  4 ++--
 10 files changed, 45 insertions(+), 18 deletions(-)

diff --git a/.agents/skills/release-openspec/SKILL.md b/.agents/skills/release-openspec/SKILL.md
index 0b077dfdf4..19c03a6c03 100644
--- a/.agents/skills/release-openspec/SKILL.md
+++ b/.agents/skills/release-openspec/SKILL.md
@@ -146,7 +146,7 @@ After the Version Packages PR merges:
    - `npm view @fission-ai/openspec@<version> version`
    - remote tag `v<version>` points at the expected commit;
    - `gh release view v<version>` exists and is not a prerelease.
-   - The release's assets include the 8 `openspec-*` standalone binaries, `SHA256SUMS`, `install.sh` and `install.ps1`, attached by the Binaries workflow (`binaries.yml`) about 10 minutes after the release is published.
+   - The release's assets include the 8 `openspec-*` standalone binaries and `SHA256SUMS`, attached by the Binaries workflow (`binaries.yml`) about 10 minutes after the release is published. Until `SHA256SUMS` is there, the install scripts keep installing the previous release, so users are never left without one.
 3. If only some artifacts exist, report partial state and resume verification before retrying any publish action. Never republish a version already on npm. Missing binaries never need an npm action: re-run `binaries.yml` with `workflow_dispatch` and the release tag to attach them.
 4. Once all artifacts exist, read [references/release-notes.md](references/release-notes.md), polish the GitHub Release, and verify the saved title/body.
 
diff --git a/.changeset/standalone-binary.md b/.changeset/standalone-binary.md
index 94c1e3ba4e..b89f365938 100644
--- a/.changeset/standalone-binary.md
+++ b/.changeset/standalone-binary.md
@@ -2,4 +2,4 @@
 '@fission-ai/openspec': minor
 ---
 
-OpenSpec now installs as a single file with no Node.js needed: `curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh` on macOS and Linux, or `irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex` on Windows. Every release now includes binaries for macOS, Linux (glibc and musl) and Windows on x64 and arm64, with `SHA256SUMS`. npm and the other package managers keep working as before.
+OpenSpec now installs as a single file with no Node.js needed: `curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh` on macOS and Linux, or `irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex` on Windows. Every release now includes binaries for macOS, Linux (glibc and musl) and Windows on x64 and arm64, with `SHA256SUMS`. npm and the other package managers keep working as before.
diff --git a/.github/workflows/binaries.yml b/.github/workflows/binaries.yml
index 2d928dc67a..22cfec30fc 100644
--- a/.github/workflows/binaries.yml
+++ b/.github/workflows/binaries.yml
@@ -189,6 +189,28 @@ jobs:
             if (-not (Test-Path (Join-Path $abs 'openspec-renamed.exe'))) { throw 'custom name not used' }
             $raw = [string]$key.GetValue('Path', '', 'DoNotExpandEnvironmentNames')
             if (($raw -split ';') -notcontains $abs) { throw "relative folder not saved as $abs : $raw" }
+
+            # Mid-release: the newest release has no SHA256SUMS yet (still
+            # uploading, or the upload failed). Its previous release installs.
+            $site = Join-Path (Get-Location) 'dist-bin/site'
+            foreach ($tag in 'v1.1.0', 'v1.2.0') {
+              $d = Join-Path $site "releases/download/$tag"
+              New-Item -ItemType Directory -Force -Path $d | Out-Null
+              Copy-Item "dist-bin/openspec-$env:ASSET.exe" $d
+              if ($tag -eq 'v1.1.0') { Copy-Item dist-bin/SHA256SUMS $d }
+            }
+            Set-Content -Path (Join-Path $site 'releases.atom') -Value ('<feed>' + (('v1.2.0', 'v1.1.0' | ForEach-Object { "<link href=""https://github.com/Fission-AI/OpenSpec/releases/tag/$_""/>" }) -join '') + '</feed>')
+            foreach ($shell in 'pwsh', 'powershell') {
+              $dir = Join-Path $env:RUNNER_TEMP "fallback $shell"
+              $out = & $shell -NoProfile -Command "`$env:OPENSPEC_RELEASES_URL='http://127.0.0.1:8765/site/releases'; `$env:OPENSPEC_INSTALL_DIR='$dir'; irm http://127.0.0.1:8765/install.ps1 | iex" 2>&1 | Out-String
+              if ($LASTEXITCODE -ne 0) { throw "$shell fallback install failed: $out" }
+              if ($out -notmatch 'v1\.2\.0 is still being prepared; installing v1\.1\.0\.') { throw "$shell did not fall back with a note: $out" }
+              if ((Get-FileHash (Join-Path $dir 'openspec.exe')).Hash -ne (Get-FileHash "dist-bin/openspec-$env:ASSET.exe").Hash) { throw "$shell fallback installed the wrong file" }
+              # A localhost-looking URL whose real host is remote is refused before any download.
+              $out = & $shell -NoProfile -Command "`$env:OPENSPEC_DOWNLOAD_URL='http://localhost:80@evil.example/x'; `$env:OPENSPEC_INSTALL_DIR='$dir-evil'; irm http://127.0.0.1:8765/install.ps1 | iex" 2>&1 | Out-String
+              if ($LASTEXITCODE -eq 0 -or $out -notmatch 'must use https') { throw "$shell accepted a remote host behind localhost: $out" }
+              if (Test-Path "$dir-evil/openspec.exe") { throw "$shell installed from a refused source" }
+            }
           } finally {
             $key.SetValue('Path', $before, 'ExpandString')
             $key.Close()
@@ -258,7 +280,11 @@ jobs:
           if [ -n "$RELEASE_ID" ]; then
             tag=$(gh api "repos/$GITHUB_REPOSITORY/releases/$RELEASE_ID" --jq .tag_name)
           fi
-          gh release upload "$tag" openspec-* SHA256SUMS install.sh install.ps1 --clobber --repo "$GITHUB_REPOSITORY"
+          # SHA256SUMS goes last: installers treat a release that has it as
+          # complete and keep installing the previous one until then. The
+          # installers themselves are served from main, not from releases.
+          gh release upload "$tag" openspec-* --clobber --repo "$GITHUB_REPOSITORY"
+          gh release upload "$tag" SHA256SUMS --clobber --repo "$GITHUB_REPOSITORY"
       # Signed proof each binary was built by this workflow from this tag, which
       # anyone can check with `gh attestation verify`. The binaries are not
       # notarized or code-signed yet, so this is the verifiable trail meanwhile.
diff --git a/README.md b/README.md
index c720ea9254..ce794e0949 100644
--- a/README.md
+++ b/README.md
@@ -122,13 +122,13 @@ Install OpenSpec. It is a single file and needs no Node.js (on Alpine Linux, fir
 macOS and Linux:
 
 ```bash
-curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh
 ```
 
 Windows (PowerShell):
 
 ```powershell
-irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex
+irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex
 ```
 
 Prefer a package manager? `npm install -g @fission-ai/openspec@latest` (needs Node.js 20.19.0 or higher) or the official [Homebrew formula](https://formulae.brew.sh/formula/openspec), `brew install openspec`.
diff --git a/docs-lab/reference/cli.md b/docs-lab/reference/cli.md
index 00ca4d1e2e..982acf456d 100644
--- a/docs-lab/reference/cli.md
+++ b/docs-lab/reference/cli.md
@@ -2332,11 +2332,11 @@ For the standalone install, the update command is `openspec install`.
 Installs the standalone `openspec`, a single file that runs without Node.js. Run it from an npm or Homebrew install to switch, or from the standalone install to upgrade it in place.
 
 ```bash
-openspec install          # latest release
+openspec install          # newest release
 openspec install 1.15.0   # a specific release
 ```
 
-It runs the release's installer, which picks the file for your machine and checks it against the release's `SHA256SUMS`:
+It runs the [install script](../start/installation.md#install), which picks the newest release whose files are all attached and the file for your machine, and checks it against that release's `SHA256SUMS`:
 
 - **From a package manager**: installs to `~/.local/bin` (Windows: `%LOCALAPPDATA%\Programs\openspec`) and prints the command that removes the old copy, such as `npm uninstall -g @fission-ai/openspec`. It never removes that copy itself.
 - **From the standalone install**: replaces the running file where it is, under its own name.
diff --git a/docs-lab/start/installation.md b/docs-lab/start/installation.md
index 94e8d97071..1e228cf821 100644
--- a/docs-lab/start/installation.md
+++ b/docs-lab/start/installation.md
@@ -10,17 +10,18 @@ OpenSpec installs as a single `openspec` file. It needs no Node.js.
 On macOS or Linux, in your terminal:
 
 ```bash
-curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh
 ```
 
 On Windows, in PowerShell:
 
 ```powershell
-irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex
+irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex
 ```
 
 - **Where it goes**: `~/.local/bin`; on Windows, `%LOCALAPPDATA%\Programs\openspec`, which it adds to your user PATH.
 - **What it checks**: it picks the file for your machine and verifies it against the release's `SHA256SUMS` before installing.
+- **Which release**: the newest one whose files are all attached. For the few minutes after a release is published while its files upload, it installs the previous one and says so.
 - **Alpine Linux**: run `apk add libstdc++ libgcc` first.
 - **Options**: set `OPENSPEC_INSTALL_DIR` to install elsewhere, or `OPENSPEC_VERSION=v1.15.0` to pin a release.
 
diff --git a/docs/README.md b/docs/README.md
index 43259431b0..8c5df9d12e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -99,7 +99,7 @@ That second one matters more than it looks. OpenSpec has two halves: a command l
 ## The thirty-second version
 
 ```text
-1. Install        curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+1. Install        curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh
 2. Initialize     cd your-project && openspec init
 3. Explore        (in your AI chat)  /opsx:explore           ← optional, but a great habit
 4. Propose        (in your AI chat)  /opsx:propose add-dark-mode
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 852ca84b61..2112a65e4c 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -14,7 +14,7 @@ This guide explains how OpenSpec works after you've installed and initialized it
 The whole loop, with each step labeled by where it happens:
 
 ```text
-TERMINAL   $ curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+TERMINAL   $ curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh
 TERMINAL   $ cd your-project && openspec init
 AI CHAT      /opsx:explore                    (optional: think it through first)
 AI CHAT      /opsx:propose add-dark-mode      (AI drafts the plan; you review it)
diff --git a/docs/installation.md b/docs/installation.md
index 6eb3d6afcd..759d29414e 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -7,16 +7,16 @@ OpenSpec is a single file. It needs no Node.js or anything else (on Alpine Linux
 macOS and Linux:
 
 ```bash
-curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh
 ```
 
 Windows (PowerShell):
 
 ```powershell
-irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex
+irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex
 ```
 
-The installer picks the right file for your machine, checks it against the release's `SHA256SUMS`, and installs it to `~/.local/bin` (Windows: `%LOCALAPPDATA%\Programs\openspec`, added to your user `PATH`). Set `OPENSPEC_INSTALL_DIR` to choose another folder, or `OPENSPEC_VERSION=v1.15.0` to pin a release. Prefer npm or another package manager? See [Package Managers](#package-managers).
+The installer picks the newest release whose files are all attached and the right file for your machine, checks it against the release's `SHA256SUMS`, and installs it to `~/.local/bin` (Windows: `%LOCALAPPDATA%\Programs\openspec`, added to your user `PATH`). Set `OPENSPEC_INSTALL_DIR` to choose another folder, or `OPENSPEC_VERSION=v1.15.0` to pin a release. Prefer npm or another package manager? See [Package Managers](#package-managers).
 
 To install by hand, download your platform's file from the [latest release](https://github.com/Fission-AI/OpenSpec/releases/latest), rename it to `openspec` (`openspec.exe` on Windows), make it executable on macOS and Linux (`chmod +x openspec`), and put it on your `PATH`:
 
@@ -48,8 +48,8 @@ order, and stop where a step tells you to stop.
    ask; never switch it to a different install method on your own. Otherwise install
    the standalone OpenSpec binary, which needs no Node.js. Show me the command
    for my OS and run it only once I confirm, then skip to step 3:
-     macOS / Linux:        curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
-     Windows (PowerShell): irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex
+     macOS / Linux:        curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh
+     Windows (PowerShell): irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex
    If I'd rather use a package manager, or the installer fails, go to step 2.
 
 2. PACKAGE MANAGER (only if step 1 did not install it). Run `node --version`:
diff --git a/install.md b/install.md
index 1c80aced20..51e73bacc4 100644
--- a/install.md
+++ b/install.md
@@ -27,12 +27,12 @@ Install the standalone OpenSpec binary. It is a single file and needs no Node.js
 
 ```bash
 # macOS / Linux
-curl -fsSL https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh
 ```
 
 ```powershell
 # Windows (PowerShell)
-irm https://github.com/Fission-AI/OpenSpec/releases/latest/download/install.ps1 | iex
+irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex
 ```
 
 If the user would rather use a package manager, or the installer fails, continue with step 2.

From 154c836d90b986977f58b7ef851bd26ecdac0027 Mon Sep 17 00:00:00 2001
From: Clay Good <hi@claygood.com>
Date: Fri, 23 Oct 2026 19:07:52 -0500
Subject: [PATCH 27/27] test(cli): serve the stand-in releases page without a
 check-then-read race

CodeQL flagged the test server's exists/stat/read sequence. It now reads
directly and answers 404 on any failure.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 test/binary-installer.test.ts | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/test/binary-installer.test.ts b/test/binary-installer.test.ts
index 76763fa685..fc26f6f6e4 100644
--- a/test/binary-installer.test.ts
+++ b/test/binary-installer.test.ts
@@ -78,11 +78,16 @@ describe.skipIf(process.platform === 'win32')('standalone installer (install.sh)
     root = fs.mkdtempSync(path.join(os.tmpdir(), 'openspec-installer-'));
     server = http.createServer((req, res) => {
       const file = path.join(root, decodeURIComponent(new URL(req.url ?? '/', 'http://x').pathname));
-      if (!file.startsWith(root) || !fs.existsSync(file) || !fs.statSync(file).isFile()) {
+      // Read, rather than check and then read: missing files and folders are a 404.
+      let body: Buffer;
+      try {
+        if (!file.startsWith(root + path.sep)) throw new Error('outside the site');
+        body = fs.readFileSync(file);
+      } catch {
         res.writeHead(404).end();
         return;
       }
-      res.writeHead(200).end(fs.readFileSync(file));
+      res.writeHead(200).end(body);
     });
     await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
     base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;