Update docs for bundled binary builds, dry runs, and recovery

Author: j-256

CLAUDE.md

@@ -28,7 +28,8 @@ test/
 ## Key Design Decisions
 
 - **Eager registration:** Decoration provider is registered before repo scanning completes. The git extension may not have discovered repositories when we activate (`onStartupFinished`), so gating on repo state causes missed decorations.
-- **PATH augmentation:** The VSCode extension host has a minimal PATH. `src/extension.ts` appends `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin` to `process.env.PATH` on the shared extension host so `git-crypt` is discoverable by all extensions (including the built-in git extension's clean/smudge filter invocations). This is the extension's primary function.
+- **PATH augmentation:** The VSCode extension host has a minimal PATH. `src/extension.ts` appends `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, and the bundled `bin/` directory to `process.env.PATH` on the shared extension host so `git-crypt` is discoverable by all extensions (including the built-in git extension's clean/smudge filter invocations). User-installed git-crypt takes precedence; the bundled binary is appended last. This is the extension's primary function.
+- **Bundled binary:** Platform-specific VSIX files ship a statically linked git-crypt binary (macOS arm64, Linux x64/arm64). A universal VSIX (no binary) is also published for unsupported platforms. The binary version is pinned in `git-crypt-version.txt` with a sha256 checksum.
 - **Unlock detection via key directory:** `isRepoUnlocked()` checks for `.git/git-crypt/keys/` existence rather than parsing `git-crypt status` output (which is slow on large repos and ambiguous -- it labels managed files as "encrypted:" even when unlocked).
 - **No shell execution:** All git commands use `execFile` with array arguments to prevent command injection.
 
@@ -45,11 +46,13 @@ Tests create a temporary git-crypt repo via `test/fixture.ts` (requires `git-cry
 1. **preversion** -- branch guard (must be on `main`), build, test
 2. Version bump, commit, `v*` tag
 3. **postversion** -- pushes commit + tag to origin
-4. CI: tests -> tag/version mismatch check -> package -> GitHub release -> marketplace publish
+4. CI: tests -> build static binaries -> package platform-specific + universal VSIX -> GitHub release -> marketplace publish
 
-Recovery from CI failure: `npm run retag` (force-moves tag to HEAD, re-triggers CI).
+Recovery from CI failure: `npm run retag` (force-moves tag to HEAD, re-triggers CI). If marketplace publish fails after GH release succeeds, bump version and release again (marketplace rejects same-version re-publishes).
 
-Branches: `main` (releases), `dev` (test-only CI, no publish).
+Dry runs: `gh workflow run ci.yml --ref dev` runs the full build/package pipeline with `dry_run=true` (default). Marketplace publish is also guarded against non-main branches.
+
+Branches: `main` (releases), `dev` (CI runs tests + dry-run builds, no publish).
 
 ## Installation (Development)
 

CONTRIBUTING.md

@@ -54,29 +54,48 @@ This single command:
 
 CI then takes over:
 
-5. Runs tests on the pushed tag
-6. Validates the tag matches package.json version
-7. Packages the VSIX and creates a GitHub release with it attached
-8. Publishes to the VS Code Marketplace
+5. Runs tests
+6. Validates the tag is on `main` and matches package.json version
+7. Builds static git-crypt binaries for macOS (arm64) and Linux (x64, arm64)
+8. Packages platform-specific VSIX files (with bundled binary) and a universal VSIX (without)
+9. Creates a GitHub release with all VSIX files attached
+10. Publishes all VSIX files to the VS Code Marketplace
+
+### Dry Runs
+
+Trigger the full build/package pipeline without publishing:
+
+```bash
+gh workflow run ci.yml --ref dev
+```
+
+This runs with `dry_run=true` (the default), which builds binaries, packages VSIX files, and verifies their contents -- but skips the GitHub release and marketplace publish steps. Uncheck `dry_run` in the GitHub UI to publish from a manual dispatch (only allowed from `main`).
 
 ### Recovery
 
-If CI fails after the tag is pushed (e.g. marketplace timeout), fix the issue and retag:
+**CI fails before publish** (tests, build, packaging): fix the issue and retag:
 
 ```bash
 npm run retag
 ```
 
 This force-moves the tag to the current commit and pushes it, re-triggering CI.
 
+**Marketplace publish fails after GitHub release succeeds**: the marketplace rejects same-version re-publishes, so `retag` alone won't work. Bump the version and release again:
+
+```bash
+npm version patch
+```
+
 ### Branches
 
 - **main** -- releases happen here; `npm version` enforces this via a branch guard
-- **dev** -- CI runs tests only; publish job verifies the tag is on main before proceeding
+- **dev** -- CI runs tests and dry-run builds; publish steps are gated behind `dry_run` input and a main-branch guard
 
 ## CI
 
 GitHub Actions (`.github/workflows/ci.yml`):
 
-- **test** job runs on every push to `main`/`dev` and on PRs to `main`
-- **publish** job runs only on `v*` tags on `main`, after tests pass
+- **test** -- runs on every push to `main`/`dev` and on PRs to `main`
+- **build-git-crypt** -- compiles static git-crypt binaries on macOS (arm64 via macos-15) and Linux (x64 and arm64 via Alpine Docker, arm64 uses QEMU). Runs on tags and `workflow_dispatch`
+- **publish** -- packages platform-specific and universal VSIX files, verifies contents, optionally creates GitHub release and publishes to marketplace. Release/publish steps are controlled by the `dry_run` input (defaults to true on manual dispatch; always false on tag pushes)