nix (#7)

npm
cargo

docs/releasing.md

@@ -0,0 +1,110 @@
+# Releasing deskctl
+
+This document covers the operator flow for shipping `deskctl` across:
+
+- GitHub Releases
+- crates.io
+- npm
+- the repo flake
+
+GitHub Releases are the canonical binary source. The npm package consumes those release assets instead of building a separate binary.
+
+## Package Names
+
+- crate: `deskctl`
+- npm package: `deskctl-cli`
+- installed command: `deskctl`
+
+## Prerequisites
+
+Before the first live publish on each registry:
+
+- npm ownership for `deskctl-cli`
+- crates.io ownership for `deskctl`
+- repository secrets:
+  - `NPM_TOKEN`
+  - `CARGO_REGISTRY_TOKEN`
+
+These are user-owned prerequisites. The repo can validate and automate the rest, but it cannot create registry ownership for you.
+
+## Normal Release Flow
+
+1. Merge release-ready changes to `main`.
+2. Let CI run:
+   - validation
+   - integration
+   - distribution validation
+   - release asset build
+3. Confirm the GitHub Release exists for the version tag and includes:
+   - `deskctl-linux-x86_64`
+   - `checksums.txt`
+4. Trigger the `Publish Registries` workflow with:
+   - `tag`
+   - `publish_npm`
+   - `publish_crates`
+5. Confirm the publish summary for each channel.
+
+## What CI Validates
+
+The repository validates:
+
+- `cargo publish --dry-run --locked`
+- npm package metadata and packability
+- npm install smoke path on Linux using the packaged `deskctl` command
+- repo flake evaluation/build
+
+The repository release workflow:
+
+- builds the Linux release binary
+- publishes the canonical GitHub Release asset
+- uploads `checksums.txt`
+
+The registry publish workflow:
+
+- targets an existing release tag
+- checks that Cargo, npm, and the requested tag all agree on version
+- checks whether that version is already published on npm and crates.io
+- only publishes the channels explicitly requested
+
+## Rerun Safety
+
+Registry publishing is intentionally separate from release asset creation.
+
+If a partial failure happens:
+
+- GitHub Release assets remain the source of truth
+- rerun the `Publish Registries` workflow for the same tag
+- already-published channels are reported and skipped
+- remaining channels can still be published
+
+## Local Validation
+
+Run the distribution checks locally with:
+
+```bash
+make cargo-publish-dry-run
+make npm-package-check
+make nix-flake-check
+make dist-validate
+```
+
+Notes:
+
+- `make npm-package-check` does a runtime smoke test only on Linux
+- `make nix-flake-check` requires a local Nix installation
+- Docker remains a local Linux build convenience, not the canonical release path
+
+## Nix Boundary
+
+The repo-owned `flake.nix` is the supported Nix surface in this phase.
+
+In scope:
+
+- `nix run github:harivansh-afk/deskctl`
+- `nix profile install github:harivansh-afk/deskctl`
+- CI validation for the repo flake
+
+Out of scope for this phase:
+
+- `nixpkgs` upstreaming
+- extra distro packaging outside the repo