Widthdom · Widthdom · May 25, 2026 · May 25, 2026 · May 25, 2026 · May 25, 2026
diff --git a/COMMERCIAL_LICENSE.md b/COMMERCIAL_LICENSE.md
@@ -41,6 +41,10 @@ Allowed uses include:
 
 ## Requires a Separate Written Agreement
 
+The redistribution allowance above covers unmodified official releases only. A
+package, image, service, extension, or fork that is renamed or positioned as a
+substitute for CodeIndex falls under the competing-product boundary below.
+
 A separate written agreement with Widthdom is required if you make CodeIndex,
 a modified version of CodeIndex, or a derivative work of CodeIndex available
 to third parties as a commercial product or service whose primary or substantial

diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md
@@ -17,6 +17,18 @@ target frameworks when validating the full CI-equivalent test matrix.
 
 For test suite structure, shared helpers, and test-writing conventions, see [TESTING_GUIDE.md](TESTING_GUIDE.md).
 
+## Release Distribution Checklist
+
+When preparing a release, verify every supported distribution channel documented
+in [DISTRIBUTION.md](DISTRIBUTION.md):
+
+- `install.sh` latest install, explicit-version install, `--doctor`, and local
+  mirror self-test.
+- NuGet global tool install/update on a clean .NET 8 tool environment.
+- Published release assets for every advertised RID.
+- Package metadata for license, repository URL, tags, and runtime prerequisites.
+- Documentation links from README, USER_GUIDE, and package metadata.
+
 ### NuGet lock files
 
 `Directory.Build.props` sets `RestorePackagesWithLockFile=true`, so every project under this solution writes a `packages.lock.json` next to its `.csproj`. The lock file pins exact resolved versions and `contentHash` for every direct **and transitive** package, including the native-bearing `SQLitePCLRaw.bundle_e_sqlite3` that ships under `Microsoft.Data.Sqlite`. This keeps builds reproducible across machines, CI lanes, and release artifacts, and turns a silent transitive bump (or downgrade attack) into a loud, build-breaking diff.

diff --git a/DISTRIBUTION.md b/DISTRIBUTION.md
@@ -0,0 +1,56 @@
+# Distribution Channels
+
+This document compares supported and planned ways to install `cdidx`.
+
+## Supported Channels
+
+| Channel | Platform support | Prerequisites | Update path | Offline or mirrored use | Lifecycle policy |
+|---|---|---|---|---|---|
+| `install.sh` release assets | Linux/macOS self-contained tarballs for `linux-x64`, `linux-arm64`, and `osx-arm64` where a matching release asset exists | POSIX shell, `curl`, `tar`, and network access to the configured release host | Re-run the installer without a version for latest, or pass `vX.Y.Z` for an exact release | Supports `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `CDIDX_GITHUB_BASE_URL`, `CDIDX_GITHUB_API_BASE_URL`, and local mirror self-tests | Primary self-contained installer for terminals, CI, containers, and ARM64 Unix hosts without .NET |
+| Windows release ZIP assets | Windows self-contained ZIPs for `win-x64` and `win-arm64` where published | PowerShell or another ZIP extraction workflow | Download and replace with the desired release ZIP | Mirror the GitHub release ZIP and checksum assets through the same artifact controls | Supported release-asset path for Windows users who do not use NuGet |
+| NuGet global tool | Any platform supported by .NET 8 global tools | .NET 8 SDK for `dotnet tool install/update`; .NET 8 runtime to run the installed tool | `dotnet tool update -g cdidx` | Use standard NuGet feeds, caches, and enterprise mirrors | Portable framework-dependent tool package; not RID-specific or self-contained |
+| Container or manual image build | Any base image that can run the selected install path | Either `install.sh` prerequisites or a .NET SDK for source builds | Rebuild the image with a pinned release or source revision | Mirror release assets or NuGet feeds inside the image build network | Supported as a deployment pattern, not as an official published container image |
+| Build from source | Windows, macOS, and Linux with a supported .NET SDK | .NET 8 SDK for production target; .NET 9 SDK if running the full test matrix | Pull source and rebuild | Works with restored package caches and internal NuGet mirrors | Contributor and advanced-user path |
+
+## Planned or Community Channels
+
+| Channel | Status | Notes |
+|---|---|---|
+| Homebrew | Available via `widthdom/tap/codeindex` when published for a release | Prefer this on macOS/Linux when you already use Homebrew. |
+| winget | Planned | Should point at unmodified official binaries and preserve notices. |
+| apt / rpm | Planned | Package metadata should make the license and update cadence clear. |
+| Snap / Flatpak | Planned | Must document filesystem and sandbox implications for `.cdidx` databases. |
+
+## Choosing a Channel
+
+Use `install.sh` when you want a self-contained binary, especially in ARM64
+cloud sessions, CI containers, or machines where .NET is not already managed.
+Use the NuGet global tool when your workstation already has a managed .NET 8
+toolchain and you want standard `dotnet tool` update behavior.
+
+If both are installed, whichever `cdidx` appears first on `PATH` wins. Check
+with:
+
+```bash
+command -v cdidx
+cdidx --version
+```
+
+## Package Maintainers and Mirrors
+
+Third-party package recipes, manifests, and mirrors may redistribute unmodified
+official CodeIndex releases when required notices are preserved. Do not market a
+renamed binary, fork, or service as a substitute for CodeIndex without a
+separate written agreement. See [INTEGRATION_POLICY.md](INTEGRATION_POLICY.md)
+and [COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md).
+
+## Release Verification Checklist
+
+Before publishing or updating a channel, verify:
+
+- `install.sh` can install the latest release and an explicit `vX.Y.Z` release.
+- `install.sh --doctor vX.Y.Z` reports the configured release and API hosts.
+- `dotnet tool install -g cdidx --version <version>` succeeds on a clean .NET 8 tool environment.
+- `cdidx --version` runs from each installed channel.
+- `cdidx status --help` or another lightweight command runs without requiring a repository.
+- Package metadata preserves license, homepage, and repository links.
diff --git a/INTEGRATION_POLICY.md b/INTEGRATION_POLICY.md
@@ -107,6 +107,12 @@ Version markers for these fields:
 The integration is allowed when it helps users operate official CodeIndex
 releases or permissively licensed integration materials.
 
+Third-party package maintainers may publish formulas, manifests, recipes, or
+internal mirrors for unmodified official CodeIndex release artifacts when the
+license, copyright, repository, and trademark notices are preserved and the
+package does not imply official endorsement. See [DISTRIBUTION.md](DISTRIBUTION.md)
+for channel expectations.
+
 The integration may require a separate written agreement when it makes CodeIndex,
 a modified CodeIndex engine, or a derivative work of CodeIndex available to
 third parties as a commercial product or service that substitutes for CodeIndex

diff --git a/README.md b/README.md
@@ -78,6 +78,18 @@ Output controls:
 Use `cdidx` when a repository will be searched repeatedly from terminals,
 scripts, CI, or AI tools. Use `rg` when you only need a one-off text scan.
 
+Install choice and network notes:
+
+| Need | Use |
+|---|---|
+| Self-contained binary with no .NET runtime | `install.sh` |
+| .NET global tool workflow | `dotnet tool install -g cdidx` with .NET 8 installed |
+| ARM64 host without a preinstalled .NET 8 runtime | `install.sh` |
+| Proxy or mirrored GitHub access | `install.sh --doctor` and `CDIDX_GITHUB_BASE_URL` / `CDIDX_GITHUB_API_BASE_URL` |
+
+See [DISTRIBUTION.md](DISTRIBUTION.md) for the full channel matrix and
+[isolated network install notes](USER_GUIDE.md#isolated-networks-and-proxies).
+
 ### Shell Completion
 
 Generate completion scripts with `cdidx --completions <bash|zsh|fish|powershell>`.
@@ -138,6 +150,7 @@ version 2.
 | Document | Contents |
 |---|---|
 | [User Guide](USER_GUIDE.md) | Detailed installation, command examples, options, supported languages, MCP setup, and troubleshooting. |
+| [Distribution Channels](DISTRIBUTION.md) | Install channel comparison, update paths, platform support, and package maintainer policy. |
 | [Cloud Bootstrap](CLOUD_BOOTSTRAP_PROMPT.md) | Install guidance for restricted cloud agent sessions. |
 | [Platform Support](docs/platform-support.md) | Official release asset RIDs, unsupported platforms, and source-build alternatives. |
 | [Developer Guide](DEVELOPER_GUIDE.md) | Architecture, implementation notes, release workflow, and the [`reference_kind` filtering matrix](DEVELOPER_GUIDE.md#reference-kind-filtering-matrix) for `callers` / `impact` / `deps` count reconciliation. |

diff --git a/USER_GUIDE.md b/USER_GUIDE.md
@@ -425,6 +425,17 @@ or `cdidx . --json` refresh so stale paths are purged.
 
 ## Installation
 
+Choose the install channel based on runtime ownership and network shape:
+
+| Channel | Best fit | Prerequisites | Update path |
+|---|---|---|---|
+| `install.sh` | Self-contained installs, CI, containers, ARM64 hosts without managed .NET | Shell tools and release-asset network access | Re-run the installer, optionally with `vX.Y.Z` |
+| NuGet global tool | Workstations already using .NET global tools | .NET 8 SDK for install/update; .NET 8 runtime to run | `dotnet tool update -g cdidx` |
+| Build from source | Contributors and custom local builds | .NET 8 SDK | Pull source and rebuild |
+
+For a full comparison, package maintainer guidance, and planned channels such
+as winget, apt, rpm, Snap, and Flatpak, see [DISTRIBUTION.md](DISTRIBUTION.md).
+
 ### Option A: One-liner install (no .NET required)
 
 Works in containers, CI, and any Linux/macOS environment — no .NET SDK needed.
@@ -467,12 +478,45 @@ RUN export CDIDX_INSTALL_DIR=/usr/local/bin \
     && curl -fsSL https://raw.githubusercontent.com/Widthdom/CodeIndex/main/install.sh | bash
 ```
 
+#### Isolated networks and proxies
+
+Use `--doctor` before installing when a corporate proxy, egress allowlist, or
+GitHub mirror is involved:
+
+```bash
+bash ./install.sh --doctor
+HTTPS_PROXY=http://proxy.example:8080 bash ./install.sh --doctor v1.5.0
+```
+
+To point the installer at a mirror, set both release and API base URLs:
+
+```bash
+export CDIDX_GITHUB_BASE_URL=https://github.example.internal
+export CDIDX_GITHUB_API_BASE_URL=https://github.example.internal/api/v3
+curl -fsSL "$CDIDX_GITHUB_BASE_URL/Widthdom/CodeIndex/raw/main/install.sh" | bash
+```
+
+The local mirror self-test verifies the mirror code path without touching real
+release assets. It installs a mock `cdidx` into the selected install directory,
+so use an isolated directory unless you explicitly pass the overwrite guard:
+
+```bash
+export CDIDX_INSTALL_DIR="$(mktemp -d)"
+bash ./install.sh --self-test-local-mirror
+```
+
+If the default local self-test port is busy, set
+`CDIDX_LOCAL_MIRROR_PORT=18766`.
+
 ### Option B: NuGet Global Tool
 
-Requires the [.NET 8.x SDK](https://dotnet.microsoft.com/download/dotnet/8.0).
-CodeIndex targets `net8.0`; .NET 8.x is the supported SDK/runtime line for the
-published tool, while the CI test suite also covers the test project on
-`net9.0`.
+Requires the [.NET 8.x SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
+for `dotnet tool install` / `dotnet tool update`. CodeIndex targets `net8.0`;
+.NET 8.x is the supported runtime line for the published tool, while the CI
+test suite also covers the test project on `net9.0`. The NuGet package is
+framework-dependent rather than RID-specific or self-contained. On Apple
+Silicon, Linux ARM64, and Windows ARM64, prefer `install.sh` when the host does
+not already manage a .NET 8 runtime.
 
 ```bash
 dotnet tool install -g cdidx
@@ -2281,6 +2325,17 @@ freshness が曖昧になった場合は、stale paths を purge できるよう
 
 ## インストール
 
+runtime の管理方法とネットワーク条件に合わせて install channel を選んでください。
+
+| Channel | 向いている用途 | 前提条件 | 更新方法 |
+|---|---|---|---|
+| `install.sh` | self-contained install、CI、container、managed .NET が無い ARM64 host | shell tools と release asset へ到達できるネットワーク | installer を再実行。必要なら `vX.Y.Z` を指定 |
+| NuGet global tool | 既に .NET global tool を使う workstation | install/update には .NET 8 SDK、実行には .NET 8 runtime | `dotnet tool update -g cdidx` |
+| source build | contributor と custom local build | .NET 8 SDK | source を pull して rebuild |
+
+完全な比較、package maintainer guidance、winget / apt / rpm / Snap /
+Flatpak などの予定チャネルは [DISTRIBUTION.md](DISTRIBUTION.md) を参照してください。
+
 ### 方法A: ワンライナーインストール（.NET 不要）
 
 コンテナ、CI、Linux/macOS 環境で .NET SDK なしで使えます。
@@ -2323,12 +2378,46 @@ RUN export CDIDX_INSTALL_DIR=/usr/local/bin \
     && curl -fsSL https://raw.githubusercontent.com/Widthdom/CodeIndex/main/install.sh | bash
 ```
 
+#### 隔離ネットワークと proxy
+
+企業 proxy、egress allowlist、GitHub mirror が関係する環境では、install 前に
+`--doctor` で経路を確認してください。
+
+```bash
+bash ./install.sh --doctor
+HTTPS_PROXY=http://proxy.example:8080 bash ./install.sh --doctor v1.5.0
+```
+
+installer を mirror に向ける場合は、release host と API host の両方を設定します。
+
+```bash
+export CDIDX_GITHUB_BASE_URL=https://github.example.internal
+export CDIDX_GITHUB_API_BASE_URL=https://github.example.internal/api/v3
+curl -fsSL "$CDIDX_GITHUB_BASE_URL/Widthdom/CodeIndex/raw/main/install.sh" | bash
+```
+
+local mirror self-test は、実リリース資産に触れずに mirror 経路を検証します。
+選択した install directory に mock `cdidx` を配置するため、明示的に
+overwrite guard を渡す場合を除き、隔離ディレクトリを使ってください。
+
+```bash
+export CDIDX_INSTALL_DIR="$(mktemp -d)"
+bash ./install.sh --self-test-local-mirror
+```
+
+既定の local self-test port が埋まっている場合は
+`CDIDX_LOCAL_MIRROR_PORT=18766` を設定してください。
+
 ### 方法B: NuGet グローバルツール
 
+`dotnet tool install` / `dotnet tool update` には
 [.NET 8.x SDK](https://dotnet.microsoft.com/download/dotnet/8.0) が必要です。
-CodeIndex は `net8.0` を対象にしており、公開ツールのサポート対象
-SDK/runtime 系列は .NET 8.x です。一方で、CI のテストスイートは
-テストプロジェクトを `net9.0` でも検証します。
+CodeIndex は `net8.0` を対象にしており、公開ツールのサポート対象 runtime
+系列は .NET 8.x です。一方で、CI のテストスイートはテストプロジェクトを
+`net9.0` でも検証します。NuGet package は framework-dependent であり、
+RID-specific / self-contained ではありません。Apple Silicon、Linux ARM64、
+Windows ARM64 で host 側が .NET 8 runtime を管理していない場合は、
+`install.sh` を優先してください。
 
 ```bash
 dotnet tool install -g cdidx

diff --git a/changelog.d/unreleased/1951.docs.md b/changelog.d/unreleased/1951.docs.md
@@ -0,0 +1,17 @@
+---
+category: docs
+issues:
+  - 1951
+affected:
+  - README.md
+  - USER_GUIDE.md
+  - DISTRIBUTION.md
+---
+
+## English
+
+- **NuGet global tool docs now call out the .NET 8 runtime requirement on ARM64 (#1951)** - The install guidance distinguishes the framework-dependent NuGet path from the self-contained `install.sh` path.
+
+## 日本語
+
+- **NuGet global tool の ARM64 向け .NET 8 ランタイム要件を明記しました (#1951)** - framework-dependent な NuGet 経路と self-contained な `install.sh` 経路の違いをインストール案内で区別しました。
diff --git a/changelog.d/unreleased/1952.docs.md b/changelog.d/unreleased/1952.docs.md
@@ -0,0 +1,20 @@
+---
+category: docs
+issues:
+  - 1952
+affected:
+  - README.md
+  - USER_GUIDE.md
+  - DISTRIBUTION.md
+  - INTEGRATION_POLICY.md
+  - COMMERCIAL_LICENSE.md
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **Distribution channel documentation now has a comparison matrix (#1952)** - `DISTRIBUTION.md` documents supported and planned install channels, update paths, prerequisites, package maintainer boundaries, and release verification checks.
+
+## 日本語
+
+- **配布チャネルの比較表を追加しました (#1952)** - `DISTRIBUTION.md` に、対応済み/予定中のインストール経路、更新方法、前提条件、パッケージメンテナー向け境界、リリース検証項目をまとめました。
diff --git a/changelog.d/unreleased/1957.docs.md b/changelog.d/unreleased/1957.docs.md
@@ -0,0 +1,17 @@
+---
+category: docs
+issues:
+  - 1957
+affected:
+  - README.md
+  - USER_GUIDE.md
+  - install.sh
+---
+
+## English
+
+- **Installer mirror and proxy recovery paths are now documented (#1957)** - README and USER_GUIDE link to `--doctor`, GitHub base URL overrides, and the local mirror self-test for restricted networks.
+
+## 日本語
+
+- **installer の mirror/proxy 復旧経路を文書化しました (#1957)** - README と USER_GUIDE から、制限ネットワーク向けの `--doctor`、GitHub base URL override、local mirror self-test を参照できるようにしました。
@@ -9,11 +9,17 @@
 #   bash ./install.sh --self-test-local-mirror [--self-test-allow-overwrite] [vX.Y.Z]
 #   bash ./install.sh --reinstall-real vX.Y.Z
 #   bash ./install.sh --doctor [vX.Y.Z]
+#   HTTPS_PROXY=http://proxy.example:8080 bash ./install.sh --doctor
+#   CDIDX_GITHUB_BASE_URL=https://github.example.internal \
+#     CDIDX_GITHUB_API_BASE_URL=https://github.example.internal/api/v3 \
+#     bash ./install.sh --doctor vX.Y.Z
 #
 # Optional env vars / 任意環境変数:
 #   CDIDX_GITHUB_BASE_URL       Release download base URL override
 #   CDIDX_GITHUB_API_BASE_URL   API base URL override for latest-release lookup
 #   CDIDX_LOCAL_MIRROR_PORT     Local self-test HTTP server port (default: 18765)
+#   HTTPS_PROXY / HTTP_PROXY    Proxy used by curl for release and API probes
+#   NO_PROXY                    Hosts that should bypass the proxy
 #
 # Self-test mock payload safety / セルフテスト mock 上書き防止:
 #   The --self-test-local-mirror path installs a **mock** cdidx that only