gauravtiwari · Jul 27, 2026 · Jul 27, 2026
diff --git a/INSTALLATION.md b/INSTALLATION.md
@@ -1,92 +1,152 @@
-# BoringCache CLI Installation
+# BoringCache CLI Installation Setup
 
-This repository publishes the installer and GitHub Release assets used by the
-BoringCache CLI. The normal install command is:
+This document describes how to set up the
+`curl -sSL -H "Cache-Control: no-cache" -H "Pragma: no-cache" https://install.boringcache.com/install.sh | sh`
+installation method for the BoringCache CLI. The explicit no-cache headers ensure
+Cloudflare (or any intermediary CDN) revalidates the script on each install.
 
-```bash
-curl -sSL https://install.boringcache.com/install.sh | sh
-```
-
-The installer always verifies `SHA256SUMS`. When `cosign` is available it also
-verifies `SHA256SUMS.bundle` automatically. To make Sigstore verification
-mandatory, install `cosign` first and run:
+The installer always verifies every downloaded artifact against `SHA256SUMS`.
+On macOS it installs both the universal CLI and the universal Xcode CAS adapter
+beside it. When `cosign` is available it also verifies the signed checksum
+bundle automatically.
+For fail-closed Sigstore verification, install `cosign` first and run:
 
 ```bash
 curl -sSL https://install.boringcache.com/install.sh | BORINGCACHE_VERIFY_SIGNATURE=1 sh
 ```
 
-When testing the installer itself, use:
+## Files Overview
 
-```bash
-curl -sSL -H "Cache-Control: no-cache" -H "Pragma: no-cache" https://install.boringcache.com/install.sh | sh
+- `install.sh` - The installation script that users will curl and execute
+- `install-web/` - Static website files for the installation page
+- `install-web/index.html` - Landing page with installation instructions and manual download links
+
+## Setup Instructions
+
+### 1. Domain Setup
+
+You'll need to configure `install.boringcache.com/install.sh` to serve the installation script. Here are a few options:
+
+#### Option A: GitHub Pages (Recommended)
+1. Create a new repository `boringcache/install`
+2. Upload `install.sh` and `install-web/` contents to the repository
+3. Enable GitHub Pages to serve from the main branch
+4. Configure custom domain `install.boringcache.com/install.sh` in repository settings
+5. Add CNAME record in DNS: `install.boringcache.com/install.sh` → `boringcache.github.io`
+
+#### Option B: Cloudflare Pages
+1. Connect the CLI repository to Cloudflare Pages
+2. Set build command to copy installation files to output directory
+3. Configure custom domain `install.boringcache.com/install.sh`
+
+#### Option C: Simple Static Hosting
+Use any static file hosting service (Netlify, Vercel, etc.) to serve:
+- Root path `/` serves `install.sh` with `Content-Type: text/plain`
+- Path `/web` serves `install-web/index.html`
+
+### 2. Web Server Configuration
+
+The installation script should be served with proper headers:
+
+```nginx
+# Nginx example
+location = / {
+    add_header Content-Type text/plain;
+    try_files /install.sh =404;
+}
+
+location /web/ {
+    try_files $uri $uri/ /install-web/index.html;
+}
 ```
 
-The explicit no-cache headers ensure Cloudflare or another intermediary CDN
-revalidates the script on each test install.
+### 3. DNS Configuration
 
-## Files
+Add these DNS records:
+```
+install.boringcache.com/install.sh  CNAME  your-hosting-provider.com
+```
 
-- `install.sh` - installer script served by `install.boringcache.com`
-- `install-web/` - static install page
-- `README.md` and `docs/` - public CLI usage docs
-- GitHub Releases - platform binaries and `SHA256SUMS`
+### 4. SSL Certificate
 
-## Testing
+Ensure HTTPS is enabled since users will be downloading and executing scripts.
 
-Test the script URL:
+## Testing the Installation
 
+### Test the script URL:
 ```bash
 curl -sSL -H "Cache-Control: no-cache" -H "Pragma: no-cache" \
   https://install.boringcache.com/install.sh
 ```
 
-Test the latest release asset URL:
+Should return the installation script content.
+
+### Test the installation:
+```bash
+curl -sSL -H "Cache-Control: no-cache" -H "Pragma: no-cache" \
+  https://install.boringcache.com/install.sh | sh
+```
+
+Should detect platform, download appropriate binary, and install it.
 
+### Test manual download links:
 ```bash
+# Should redirect to latest release
 curl -I https://github.com/boringcache/cli/releases/latest/download/boringcache-linux-amd64
 ```
 
 ## Platform Support
 
-Release assets currently target:
+The installation script supports:
 
-- Linux glibc: AMD64, ARM64
-- Linux musl: AMD64, ARM64
-- macOS universal
-- Windows: AMD64, ARM64
+- **Linux**: AMD64, ARM64
+- **macOS**: Apple Silicon and Intel through universal binaries
+- **Windows**: AMD64 (experimental, manual download recommended)
 
 ## Binary Names
 
-The release workflow publishes:
-
+The GitHub release workflow creates these binaries:
 - `boringcache-linux-amd64`
 - `boringcache-linux-arm64`
 - `boringcache-linux-musl-amd64`
 - `boringcache-linux-musl-arm64`
 - `boringcache-macos-universal`
+- `libboringcache_xcode_cas-macos-universal.dylib`
 - `boringcache-windows-amd64.exe`
 - `boringcache-windows-arm64.exe`
 - `SHA256SUMS`
 - `SHA256SUMS.bundle`
 
 ## Installation Locations
 
-The script installs to the first writable location:
-
-1. `/usr/local/bin` with `sudo` when needed
+The script installs the CLI to the first writable location. On macOS it also
+installs `libboringcache_xcode_cas.dylib` in that same directory so
+`boringcache xcode` works without a separate plugin setup:
+1. `/usr/local/bin` (with sudo if needed)
 2. `$HOME/.local/bin`
 3. `$HOME/bin`
 
-## Security Notes
-
-- Downloads use HTTPS.
-- The installer always verifies the binary against `SHA256SUMS`.
-- When `cosign` is available, the installer verifies `SHA256SUMS.bundle`
-  automatically; `BORINGCACHE_VERIFY_SIGNATURE=1` makes this fail closed.
-- Sigstore verification accepts only the monorepo CLI release workflow on a
-  semantic-version tag or the checksum-repair workflow on `main`.
-- The installer verifies the downloaded binary can run before finishing.
-- Product source is maintained in the BoringCache monorepo; this public repo is
-  the distribution channel.
-- Potential vulnerabilities should be reported through the private process in
-  [the security policy](.github/SECURITY.md), not a public issue.
+## Security Considerations
+
+- Downloads over HTTPS only
+- Provides warning about piping curl to shell
+- Verifies the downloaded binary against `SHA256SUMS`
+- Automatically verifies `SHA256SUMS.bundle` with Sigstore when `cosign` is
+  available; `BORINGCACHE_VERIFY_SIGNATURE=1` makes the signature mandatory
+- Accepts checksum signatures only from the monorepo CLI release workflow on a
+  semantic-version tag or the checksum-repair workflow on `main`
+- Shows installation path and PATH information
+- Includes verification step after installation
+
+## Maintenance
+
+- Update `REPO` variable in `install.sh` if repository moves
+- Update download links in `index.html` if repository moves
+- Monitor GitHub API rate limits for release fetching
+
+## Future Enhancements
+
+- Support for installing specific versions
+- Package manager installations (brew, apt, etc.)
+- Windows MSI installer
+- Auto-update mechanism in the CLI itself
diff --git a/README.md b/README.md
@@ -10,21 +10,15 @@ cd your-project
 boringcache onboard
 ```
 
-The installer always verifies the release checksum. If `cosign` is installed,
-it also verifies the signed checksum bundle automatically. To require the
-signature and fail closed, run:
-
-```bash
-curl -sSL https://install.boringcache.com/install.sh | BORINGCACHE_VERIFY_SIGNATURE=1 sh
-```
-
 `boringcache onboard` authenticates the CLI, chooses a workspace, writes `.boringcache.toml` when it can, and lines up the same cache names across local runs, Docker builds, and GitHub Actions.
 
+For restore-first laptop use, set `boringcache config set read_only true` once
+and add `--write` only when a local command should publish.
+
 If you want to start sign-in from the terminal by email, use `boringcache onboard --email you@example.com`. For a brand-new account, pass `--name` and `--username` too.
 
 Repo config can also keep the repeated command itself under `[adapters.<tool>]`.
 `command` accepts either an argv array or a shell-style string.
-This is not general TOML templating: proxy-backed commands only substitute `{PORT}`, `{ENDPOINT}`, and `{CACHE_REF}`.
 After that, start with the shortest command that fits the tool:
 
 ```bash
@@ -33,35 +27,40 @@ boringcache run -- bundle install
 
 # Docker adapter from repo config
 boringcache docker
-
-# Same adapter without repo config
-boringcache docker --tag docker-cache -- docker buildx build .
-
-# Long-lived local proxy
-boringcache cache-registry my-org/app registry-cache --port 5000
+# Native Xcode compilation cache (macOS)
+boringcache xcode -- xcodebuild -workspace App.xcworkspace -scheme App build
 ```
 
 Use archive mode commands (`run`, `save`, and `restore`) when you are caching explicit directories.
 Use adapter commands when the build tool already speaks a remote-cache protocol and BoringCache has a dedicated wrapper for it.
-Use `cache-registry` when the repo already has a checked-in local endpoint setup or another process should keep the proxy alive. `cache-registry` is the proxy. `run --proxy` and adapter commands temporarily start that same proxy for one command.
-When `.boringcache.toml` stores the Docker command, `boringcache docker` is the short form. Use the longer version when you want to pass the Docker command inline.
+`.boringcache.toml` keeps repeated adapter commands and cache identity out of
+shell scripts.
 
-If you are wiring GitHub Actions, pin the verified `boringcache/one` v1.13.99
-distribution commit after onboard so CI can reuse the same repo config and
-trust model:
+Image publication is opt-in and uses the same workspace CAS as the BuildKit
+cache. Configure a stable default with `publish-image = "web:latest"` under
+`[adapters.docker]`, or pass a dynamic tag with `--publish-image`. To pull from
+another machine, use a workspace restore token as the password. The hosted
+registry is pull-only in this release; publish through the BoringCache wrapper,
+not a direct `docker push`:
 
-```yaml
-- uses: boringcache/one@b55458ec8a4165e3fd70b1a1645f518a2095ed02 # v1.13.99
+```bash
+boringcache docker --publish-image web:$GITHUB_SHA
+
+echo "$BORINGCACHE_RESTORE_TOKEN" | docker login registry.boringcache.com \
+  --username boringcache --password-stdin
+docker pull registry.boringcache.com/my-org/my-workspace/web:latest
 ```
 
+If you are wiring GitHub Actions, use [`boringcache/one@9721d419d2c78c0780963d297eb3f81f24641a27`](https://github.com/boringcache/one) after onboard so CI can reuse the same repo config and trust model.
+
 ## Docs
 
 - [Quick start](docs/quick-start.md)
 - [Onboard](docs/onboard.md)
 - [Archive mode](docs/archive-mode.md)
 - [Adapter commands](docs/adapter-commands.md)
 - [Tool guides](docs/tool-guides.md)
-- [Proxy mode](docs/proxy-mode.md)
 - [GitHub Actions](docs/github-actions.md)
+- [Development](docs/development.md)
 - [Installation setup](INSTALLATION.md)
 - [Website docs](https://boringcache.com/docs)
diff --git a/docs/README.md b/docs/README.md
@@ -1,7 +1,6 @@
 # CLI docs
 
-The CLI README is the entrypoint. This repository is the public distribution
-home for releases, installation, and customer docs.
+The CLI README is the entrypoint.
 
 If you are new to BoringCache, start here:
 
@@ -10,8 +9,26 @@ If you are new to BoringCache, start here:
 - [Archive mode](archive-mode.md)
 - [Adapter commands](adapter-commands.md)
 - [Tool guides](tool-guides.md)
-- [Proxy mode](proxy-mode.md)
 - [GitHub Actions](github-actions.md)
+
+If you are working on the CLI repo itself:
+
+- [Development](development.md)
+- [Adapter cache profiles](adapter-cache-profiles.md)
+- [Adapter contract matrix](adapter-contract-matrix.md)
+- [Adapter spec guardrails](adapter-spec-guardrails.md)
+- [Historical performance learning log](performance-learning-log.md)
+- [Engine boundary ADR](adr/0001-engine-boundary.md)
+- [Proxy engine Plan B ADR](adr/0002-proxy-engine-plan-b.md)
+- [Runner proxy optimization roadmap ADR](adr/0003-runner-proxy-optimization-roadmap.md)
+- [OCI large blob stream-through ADR](adr/0004-oci-large-blob-stream-through.md)
+- [Borrowed upload sessions and blob cache policy ADR](adr/0005-borrowed-upload-sessions-and-blob-cache-policy.md)
+- [Cache session trace and OCI negative cache ADR](adr/0006-cache-session-trace-and-oci-negative-cache.md)
+- [Docker registry-cache identity ADR](adr/0007-docker-human-tag-registry-identity.md)
+- [OCI mistake ledger](oci-mistake-ledger.md)
+- [sccache mistake ledger](sccache-mistake-ledger.md)
+- [Bazel mistake ledger](bazel-mistake-ledger.md)
+- [Gradle/Maven mistake ledger](gradle-maven-mistake-ledger.md)
 - [Installation setup](../INSTALLATION.md)
 
 The website docs live at [boringcache.com/docs](https://boringcache.com/docs).