docs: make npm setup the primary install path

Author: morluto

README.md

@@ -14,16 +14,37 @@ persistence invariants, and side-effect rules. See
 
 ## Install
 
-GitContribute requires Go 1.26 or newer. A C toolchain is not required because
-the SQLite driver is pure Go.
+The recommended installation and onboarding command requires Node.js 18 or
+newer. It runs the native GitContribute binary bundled in the npm package; Go
+and a C toolchain are not required.
 
 ```sh
-go install github.com/morluto/gitcontribute/cmd/gitcontribute@latest
+npx gitcontribute@latest setup
+```
+
+Install a persistent shell command instead:
+
+```sh
+npm install --global gitcontribute@latest
+gitcontribute setup
 ```
 
-Or build a checkout:
+Projects that want to pin the CLI version can install it as a development
+dependency and invoke it through `npx` or package scripts:
 
 ```sh
+npm install --save-dev gitcontribute
+npx gitcontribute setup --codex --yes
+```
+
+The npm package has no install lifecycle and does not download an executable at
+install time. It contains native binaries for macOS ARM64/x64, Linux
+ARM64/x64, and Windows x64.
+
+Developers with Go 1.26 or newer can install from source or build a checkout:
+
+```sh
+go install github.com/morluto/gitcontribute/cmd/gitcontribute@latest
 go build -o gitcontribute ./cmd/gitcontribute
 ```
 
@@ -35,18 +56,40 @@ You also need a `git` executable. Optional helpers that the CLI can use:
 ## Quick start
 
 ```sh
-gitcontribute init
-gitcontribute configure --token-source=env --token-source-key=GITHUB_TOKEN
-gitcontribute sync owner/repo
-gitcontribute search threads "connection timeout" --repo owner/repo --json
-gitcontribute dossier build owner/repo --json
+npx gitcontribute@latest setup
+npx gitcontribute@latest sync owner/repo
+npx gitcontribute@latest search threads "connection timeout" --repo owner/repo --json
+npx gitcontribute@latest dossier build owner/repo --json
 ```
 
 Run `gitcontribute --help` and `gitcontribute <command> --help` for full flag
 reference.
 
 ## Initialization, configuration, and authentication
 
+`gitcontribute setup` is the normal entry point. It initializes the local
+corpus, selects a GitHub authentication source, and registers the MCP server
+with Codex and/or Claude Code. It remains local-only: adding `--repo owner/repo`
+creates a discovery source but does not contact GitHub or start a sync.
+
+```sh
+gitcontribute setup                              # interactive
+gitcontribute setup --codex --yes               # configure Codex
+gitcontribute setup --all-clients --yes          # configure every supported client
+gitcontribute setup --codex --mcp-version latest --yes
+gitcontribute setup --token-source env \
+  --token-source-key GITHUB_TOKEN --yes
+gitcontribute setup --codex --dry-run --json     # inspect without writing
+gitcontribute remove --all-clients --yes         # remove only MCP registrations
+gitcontribute upgrade --check                    # compare with the latest npm release
+gitcontribute upgrade --yes                      # update a global npm installation
+```
+
+When setup runs through `npx`, client configuration launches a released npm
+version rather than recording an ephemeral npm-cache path. `remove` never
+deletes the corpus or GitContribute application configuration. See
+[the onboarding design](docs/onboarding.md) for the complete contract.
+
 `gitcontribute init` creates the default corpus database and directories if they
 do not exist. It does not fetch anything from GitHub.
 

docs/onboarding.md

@@ -0,0 +1,59 @@
+# Onboarding and npm distribution
+
+The primary installation and onboarding entry point is:
+
+```sh
+npx gitcontribute@latest setup
+```
+
+GitContribute remains a native Go application. The `gitcontribute` npm package
+contains a small Node.js launcher and precompiled binaries for macOS ARM64/x64,
+Linux ARM64/x64, and Windows x64. Installation has no lifecycle script
+and performs no binary download. The launcher chooses the host binary at run
+time and forwards standard streams, arguments, signals, and its exit status.
+
+## Setup contract
+
+Setup is a local capability. It may create the GitContribute configuration and
+corpus, register the MCP server with selected coding clients, and add an
+explicit repository source. It does not synchronize a repository, access
+GitHub, execute repository-controlled code, or mutate GitHub.
+
+The setup engine plans and applies only GitContribute-owned entries:
+
+- `[mcp_servers.gitcontribute]` in Codex TOML configuration;
+- `mcpServers.gitcontribute` in Claude JSON configuration.
+
+Unrelated configuration is preserved. Repeated setup is idempotent. `remove`
+deletes only those entries; it never removes the GitContribute corpus or its
+application configuration. `--dry-run` performs validation without writes,
+and `--json` exposes per-step results for automation.
+
+When invoked through npm, setup records an npm launcher such as:
+
+```text
+npx --yes --package=gitcontribute@0.1.0 -- gitcontribute mcp
+```
+
+It never records a temporary executable from the npm cache. Development builds
+use `gitcontribute@latest`; released builds use their exact version so a client
+configuration is reproducible. Re-running setup with a newer release updates
+the registration. `--mcp-version latest` opts into following the latest npm
+release instead.
+
+## Release contract
+
+One tag version controls the Go binaries and npm package. Release automation:
+
+1. cross-compiles all supported native binaries with `CGO_ENABLED=0`;
+2. injects the tag version into the Go executable;
+3. assembles one npm package containing every binary;
+4. verifies the package has no install lifecycle;
+5. installs the tarball with `--ignore-scripts` and runs a smoke test;
+6. enforces a 100 MB compressed-package ceiling;
+7. publishes the npm package with provenance;
+8. creates a matching GitHub release.
+
+The npm environment must be configured for trusted publishing before the first
+release. Package publication is an external mutation and is performed only by
+the tag-triggered release workflow.