[Epic] Replace the public curl-pipe installer with an official npm/npx distribution

## Outcome

NemoClaw has an NVIDIA-controlled npm package and a supported npm/npx installation path. The canonical first-run command does not execute downloaded shell text through a pipe.

The npm package installs a persistent `nemoclaw` CLI and preserves the existing onboarding, update, recovery, and uninstall contracts. The package and each installed CLI identify the same immutable NemoClaw release and source revision.

A candidate public command is:

```bash
npx --yes @nvidia/nemoclaw@lkg install
```

The package name and command are not accepted product contracts until maintainers approve the decisions below.

## Current state

The supported public installer is a two-stage Bash flow:

1. [`install.sh`](https://github.com/NVIDIA/NemoClaw/blob/main/install.sh) resolves `lkg` or an explicit Git ref.
2. The bootstrap clones that ref and runs [`scripts/install.sh`](https://github.com/NVIDIA/NemoClaw/blob/main/scripts/install.sh) from the checkout.
3. The payload can install Node.js and OpenShell, build the CLI and plugin, run `npm link`, create user-local shims, recover existing sandboxes, and start onboarding.

The managed installation remains a Git checkout under `~/.nemoclaw/source`. An update reruns the hosted installer and can upgrade registered sandboxes after backup and recovery checks.

The repository already contains npm package metadata and package contracts in [`package.json`](https://github.com/NVIDIA/NemoClaw/blob/main/package.json) and `test/package-contract/`. However, the release process in [`scripts/release-plan.mts`](https://github.com/NVIDIA/NemoClaw/blob/main/scripts/release-plan.mts) is tag-only. It does not publish a repository-built npm artifact.

The bare public package name cannot be the new entry point today. On 2026-08-05, registry metadata for `nemoclaw@0.1.0` reported one 222-byte unpacked file, no `bin`, and metadata that does not match this repository. The repository already treats that package as a broken placeholder. See #506 and #737.

Do not document or execute `npx nemoclaw` unless NVIDIA control of that package and its release history is verified. Prefer an NVIDIA-controlled scoped package unless maintainers accept another name.

No existing issue defines this complete migration. Related epics #6056 and #5047 retain the hosted installer as their installation boundary. Closed issues #506, #737, #2399, and #642 address earlier npm failures or retain the installer-driven update flow.

## Product decisions

Maintainers must accept these decisions before implementation creates a supported surface:

- **Package identity:** Acquire and verify the bare `nemoclaw` name, or publish an NVIDIA-controlled scoped package. The proposed default is `@nvidia/nemoclaw` with a `nemoclaw` binary.
- **Node.js prerequisite:** `npx` requires Node.js and npm before NemoClaw can run. Decide whether Node.js 22.19 or later becomes a documented prerequisite or whether a separate non-npx bootstrap remains for hosts without Node.js.
- **Command contract:** Select the explicit install command, its flags, exit codes, prompts, and non-interactive behavior. Package installation must not start onboarding through an npm lifecycle script.
- **Release channels:** Define how immutable npm versions and npm dist-tags map to Git release tags. The maintained `lkg` channel must not silently become npm `latest`.
- **Installation ownership:** Define the persistent package location, shim ownership, update authority, rollback boundary, and uninstall behavior.
- **Rollout:** Define the evidence window in which the hosted installer remains available. Define when docs stop presenting `curl | bash` as canonical.
- **Security ownership:** Name the maintainers for npm organization access, trusted publishing, provenance, incident response, package deprecation, and emergency dist-tag rollback.

## Required invariants

- Fetching the package can modify the npm cache. It must not modify NemoClaw state until the user runs the explicit install command.
- The published package must not use `postinstall` or another lifecycle script for host setup, onboarding, privileged work, service changes, or sandbox mutation.
- Each artifact must bind its npm version, Git release tag, source commit SHA, and package integrity in verifiable metadata.
- The installed CLI must remain available after the npx process exits and after a new shell starts.
- A normal npm installation must not require a Git checkout, TypeScript compiler, contributor dependency, `npm link`, or repository hook.
- Install and update must use a lock. Concurrent operations must fail before they modify managed state.
- An interrupted update must leave either the previous verified CLI or the new verified CLI executable. It must not leave a partial active version.
- Migration must preserve `~/.nemoclaw` state, registered sandboxes, snapshots, credentials, and accepted onboarding progress.
- Migration must remove a legacy source link or placeholder package only after identity checks prove that NemoClaw owns the target.
- Install, update, onboarding, and uninstall output must not expose credentials in arguments, logs, npm metadata, receipts, or package contents.
- Existing prompts for third-party software, privileged work, destructive recovery, and sandbox replacement must remain before the related mutation.
- An unsupported OS, architecture, Node.js version, npm version, or OpenShell contract must fail before host mutation.
- `nemoclaw`, `nemohermes`, and `nemo-deepagents` must resolve to the same installed release.
- `nemoclaw uninstall` must use the uninstaller from the installed package. It must not fetch an unversioned remote script.

## Workstreams

### 1. Accept package and installation contracts

- [ ] Record the accepted package name, command syntax, prerequisite policy, supported platform matrix, release channels, and ownership.
- [ ] Reserve the NVIDIA-controlled npm package before any public documentation change.
- [ ] Define the managed installation layout and atomic activation model.
- [ ] Define compatibility and rollback for installations created by the hosted installer.

### 2. Produce a consumer package

- [ ] Separate consumer runtime files from contributor tooling and source-install behavior.
- [ ] Package compiled CLI and plugin artifacts, blueprints, policies, schemas, agent runtime assets, and the local uninstaller.
- [ ] Keep package installation inert until an explicit NemoClaw command runs.
- [ ] Add a package contract that inspects `npm pack --json`, archive paths, file modes, symlinks, size limits, executables, required assets, dependency closure, and prohibited files.
- [ ] Verify that the packed CLI runs with production dependencies only.
- [ ] Verify that package contents contain no credential-shaped values, local paths, release tokens, or contributor state.

### 3. Add the explicit installer command

- [ ] Implement the accepted install command in the packaged CLI.
- [ ] Reuse one installer plan for package and compatibility entry points. Do not maintain separate behavior in JavaScript and Bash.
- [ ] Install an exact package version into a NemoClaw-owned version directory and activate it atomically.
- [ ] Create owned user-local shims without changing an unrelated npm global package.
- [ ] Preserve OpenShell installation, gateway service, host preflight, backup, sandbox recovery, and onboarding behavior.
- [ ] Map the current agent, provider, policy, port, consent, `--fresh`, and non-interactive inputs to documented CLI flags.
- [ ] Record a secret-free install receipt with package version, source commit SHA, integrity, channel, active path, and previous active version.

### 4. Publish through the release process

- [ ] Make the npm package version equal the immutable NemoClaw release version. Remove the static `0.1.0` release ambiguity.
- [ ] Build the package from the exact release commit in GitHub Actions.
- [ ] Use npm trusted publishing and provenance. Do not use a long-lived publish token when trusted publishing is available.
- [ ] Restrict workflow permissions and protect the publish environment.
- [ ] Verify the packed artifact before publication. Verify registry metadata and integrity after publication.
- [ ] Promote npm `lkg` only when the Git `lkg` tag points to the same source commit SHA.
- [ ] Define canary, maintained, rollback, deprecation, and emergency-revocation operations.

### 5. Migrate legacy installations

- [ ] Detect the managed Git checkout, npm link, user-local shims, and the known placeholder package without trusting names alone.
- [ ] Adopt existing state without recreating sandboxes or repeating completed onboarding choices.
- [ ] Run existing pre-update backup and sandbox recovery checks before CLI activation changes affect registered sandboxes.
- [ ] Preserve a verified previous CLI until update and post-install verification complete.
- [ ] Remove only identity-verified legacy CLI files after successful activation.
- [ ] Make rerunning the same package version idempotent.
- [ ] Keep uninstall ownership correct before, during, and after migration.

### 6. Test the published journey

- [ ] Add hermetic unit and integration tests for package resolution, install planning, locking, activation, rollback, and migration.
- [ ] Add registry-backed package tests that use the exact candidate tarball and integrity.
- [ ] Prove that the bare placeholder package is never invoked by the supported path.
- [ ] Test fresh install, rerun, update, interrupted update, rollback, onboarding resume, and uninstall.
- [ ] Test `nemoclaw`, `nemohermes`, and `nemo-deepagents` from the persistent installation.
- [ ] Test interactive and non-interactive flows, including consent and no-TTY failures.
- [ ] Test Linux amd64, Linux arm64, WSL, DGX Spark, DGX Station, and Apple silicon macOS where the existing installer supports them.
- [ ] Test supported npm versions, npm cache reuse, corporate proxy and CA behavior, and registry outage diagnostics.
- [ ] Add protected live E2E that installs the release candidate, creates a sandbox, runs a validation request, updates, and uninstalls.

### 7. Roll out and retire the curl-pipe path

- [ ] Update the quickstarts, reference docs, troubleshooting, Windows WSL bootstrap, starter prompt, generated variants, and install recovery output.
- [ ] Document immutable version and `lkg` examples without using implicit npm `latest`.
- [ ] Keep the hosted installer as a compatibility path until the accepted platform matrix passes against a published candidate.
- [ ] During the compatibility window, make both entry points resolve the same release and installer plan.
- [ ] After the window, change the hosted script to print migration guidance or retire it according to the accepted decision.
- [ ] Remove curl-pipe-specific staging and recovery code only after supported installations no longer depend on it.

## Activation criteria

- [ ] Maintainers accept the package identity, prerequisites, installation layout, release-channel mapping, support matrix, and security ownership.
- [ ] The npm package is under verified NVIDIA control and uses trusted publishing with provenance.
- [ ] A package contract confirms the exact candidate archive contents and production dependency closure.
- [ ] An immutable npm version and npm `lkg` resolve to the accepted Git release commit SHA.
- [ ] The supported npx command leaves a persistent CLI that reports the expected version and source revision.
- [ ] Fresh install and migration from the hosted installer pass on every accepted platform and architecture.
- [ ] Update failure returns to the previous verified CLI without losing sandbox or onboarding state.
- [ ] Install, update, and uninstall preserve the existing credential and user-approval boundaries.
- [ ] The protected live E2E journey passes against the published candidate artifact.
- [ ] Documentation uses the new command only after the corresponding platform evidence passes.
- [ ] A documentation writer reviews all user-visible commands, prerequisites, migration steps, and deprecation text.
- [ ] The hosted installer remains supported until the accepted compatibility window closes.

## Non-goals

- Native Windows support. That product surface is tracked in #8178.
- Portable air-gapped production bundles. That work is tracked in #4872.
- A redesign of the onboarding finite-state machine.
- Publishing under the bare `nemoclaw` name before NVIDIA control is verified.
- Making npx install Node.js on a host that has no Node.js runtime.
- Maintaining two independent installer implementations after migration.

## Related work

- #506 — broken public `nemoclaw@0.1.0` package
- #737 — placeholder npm package clobbered the source installation
- #2399 — repository `prepare` script mixed consumer and contributor setup
- #642 — self-update proposal closed in favor of the hosted installer
- #9 and #2868 — persistent CLI and PATH behavior
- #6056 — common user entry points follow the maintained `lkg` release
- #5047 — agent-supported installation path
- #4872 — portable air-gapped bundles
- #8178 — native Windows through OpenShell MXC