# winsmux npm package

This directory is the public npm install surface for `winsmux`. It covers the
CLI package path. The recommended graphical desktop app path is the GitHub
Release installer, not this npm package.

For the recommended desktop app, open the latest GitHub Release and download
the `winsmux_..._x64-setup.exe` installer:

- https://github.com/Sora-bluesky/winsmux/releases/latest

The npm package name is `winsmux`.
Repository publishing is tag-driven and uses the staged package from
`scripts/stage-npm-release.mjs`.

The source directory is not the publish artifact. Do not publish
`packages/winsmux` directly from a checkout. The published npm tarball is
produced by `scripts/stage-npm-release.mjs`; `install.ps1` is added during
staging and pinned to the exact GitHub tag recorded in package metadata.

Install the CLI package on Windows with:

```powershell
npm install -g winsmux
```

The `winsmux` npm command proxies to the bundled Windows installer flow for the
CLI package path. It does not install or open the desktop app.

User-facing setup docs:

- https://github.com/Sora-bluesky/winsmux/blob/main/docs/quickstart.md
- https://github.com/Sora-bluesky/winsmux/blob/main/docs/installation.md
- https://github.com/Sora-bluesky/winsmux/blob/main/docs/customization.md

## Public contract

- Windows only
- public install command: `npm install -g winsmux`
- `winsmux install`
- `winsmux update`
- `winsmux uninstall`
- `winsmux version`
- `winsmux help`
- the staged package records the exact GitHub release tag in
  `winsmuxReleaseTag`; packaging-hotfix tags use a distinct valid npm prerelease
  version in the reserved `pkgfix` namespace (for example, `v0.36.28.1`
  becomes npm `0.36.28-pkgfix.1`)
- the package source directory is not the publish artifact; the staged package
  contains the generated release-pinned `install.ps1`

## Installer profiles

The public package will keep one package name and expose profile selection through
the installer command instead of publishing separate package names.

| Profile | Shape | Primary use |
| ------- | ------- | ------- |
| `core` | runtime binary, wrapper scripts, `PATH` setup, and base config | users who only need the Windows-native tmux-compatible runtime |
| `orchestra` | `core` plus orchestration scripts and the Windows Terminal profile | users who need managed pane agents under one operator |
| `security` | `core` plus vault, redaction, and audit-oriented scripts | users who need credential handling and evidence checks without the full orchestration surface |
| `full` | `core`, `orchestra`, and `security` contents | default public install profile |

The npm form is:

```powershell
winsmux install --profile full
winsmux update --profile orchestra
```

`install.ps1` accepts the same profile names through `-Profile`. The package
entrypoint forwards `--profile` to that script as `-Profile`.

After installation, start the CLI-managed workspace from the project directory
that agents should work in:

```powershell
cd <project>
winsmux init
winsmux launch
```

`winsmux launch` is the public CLI startup path for the npm package. It starts
the managed Windows Terminal workspace. It does not open the desktop app. For
the graphical desktop app, install the desktop app from GitHub Releases and
choose the project folder in that app.

Updates keep the previously recorded profile when no new profile is supplied.
Each install or update records the selected shape in:

- `~\.winsmux\install-profile`
- `~\.winsmux\install-profile.json`

Profile scope is enforced by the installer:

- `core` does not install orchestration scripts, vault support, or the Windows Terminal profile.
- `orchestra` installs orchestration scripts and the Windows Terminal profile.
- `security` installs vault-oriented support without the Windows Terminal profile.
- `full` installs both orchestration and security support.

When a later install or update switches profiles, support scripts that are no
longer part of the selected profile are removed from `~\.winsmux\winsmux-core\scripts`.

## Release gate

- the staged package must pass the Windows verify job
- the publish workflow stays tag-driven
- the publish job uses the staged package from `scripts/stage-npm-release.mjs`
- the publish job requires the repository `NPM_TOKEN` secret

## License

The public npm package is Apache-2.0.
Some runtime compatibility code in the repository keeps an upstream MIT notice.
See the repository notices for provenance details:

- https://github.com/Sora-bluesky/winsmux/blob/main/core/LICENSE
- https://github.com/Sora-bluesky/winsmux/blob/main/THIRD_PARTY_NOTICES.md