@@ -19,6 +19,11 @@ jobs:
     runs-on: ${{ matrix.os }}
     permissions:
       contents: write
+      # id-token: write is required for sigstore keyless signing. Cosign
+      # exchanges the OIDC token issued by GitHub Actions for a short-lived
+      # certificate from Fulcio bound to this workflow + commit + tag. No
+      # long-lived secrets to manage.
+      id-token: write
     strategy:
       fail-fast: false
       matrix:
@@ -154,12 +159,33 @@ jobs:
           $hash = (Get-FileHash -Algorithm SHA256 -Path $asset).Hash.ToLowerInvariant()
           "$hash  ${{ matrix.asset_name }}" | Out-File -FilePath "${asset}.sha256" -Encoding ascii
 
+      # Sigstore keyless signing via the GitHub Actions OIDC token. Produces
+      # a .sig and .pem alongside each binary; verifiable by anyone with:
+      #   cosign verify-blob --signature <asset>.sig --certificate <asset>.pem \
+      #     --certificate-identity-regexp 'https://github.com/fstubner/netscli/.*' \
+      #     --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+      #     <asset>
+      - name: Install cosign
+        uses: sigstore/cosign-installer@v3
+      - name: Sign release asset (sigstore keyless)
+        shell: bash
+        env:
+          COSIGN_EXPERIMENTAL: "1"
+        run: |
+          cd target/${{ matrix.target }}/release
+          cosign sign-blob --yes \
+            --output-signature "${{ matrix.asset_name }}.sig" \
+            --output-certificate "${{ matrix.asset_name }}.pem" \
+            "${{ matrix.asset_name }}"
+
       - name: Upload Release Asset
         uses: softprops/action-gh-release@v3
         with:
           files: |
             target/${{ matrix.target }}/release/${{ matrix.asset_name }}
             target/${{ matrix.target }}/release/${{ matrix.asset_name }}.sha256
+            target/${{ matrix.target }}/release/${{ matrix.asset_name }}.sig
+            target/${{ matrix.target }}/release/${{ matrix.asset_name }}.pem
           tag_name: ${{ github.event.inputs.tag || github.ref_name }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -20,6 +20,8 @@ thiserror.workspace = true
 chrono.workspace = true
 ipnet.workspace = true
 clap = { version = "4.4", features = ["derive"] }
+clap_complete = "4.4"
+clap_mangen = "0.2"
 ratatui = "0.29.0"
 crossterm = "0.27"
 tui-textarea = "0.4"
 
@@ -1,4 +1,5 @@
 use clap::{Parser, Subcommand};
+use clap_complete::Shell;
 
 #[derive(Parser)]
 #[command(name = "netscli", version, about = "Modern network scanner", long_about = None)]
@@ -293,6 +294,22 @@ pub enum Commands {
     #[command(name = "serve")]
     McpServe,
 
+    /// Print shell-completion script for the requested shell.
+    ///
+    /// Typical usage:
+    ///   bash:       netscli completions bash       > ~/.local/share/bash-completion/completions/netscli
+    ///   zsh:        netscli completions zsh        > ~/.zsh/completions/_netscli
+    ///   fish:       netscli completions fish       > ~/.config/fish/completions/netscli.fish
+    ///   powershell: netscli completions powershell > $PROFILE/netscli.ps1
+    #[command(name = "completions")]
+    Completions { shell: Shell },
+
+    /// Print the roff-format man page to stdout.
+    ///
+    /// Typical usage: netscli man | gzip > /usr/share/man/man1/netscli.1.gz
+    #[command(name = "man")]
+    Man,
+
     /// Manage MCP server auto-start (systemd service)
     McpService {
         /// Generate systemd user service file
 
@@ -499,6 +499,21 @@ async fn main() -> Result<()> {
                     }
                 }
             }
+            Commands::Completions { shell } => {
+                use clap::CommandFactory;
+                let mut cmd = Cli::command();
+                let name = cmd.get_name().to_string();
+                clap_complete::generate(*shell, &mut cmd, name, &mut io::stdout());
+                return Ok(());
+            }
+            Commands::Man => {
+                use clap::CommandFactory;
+                let cmd = Cli::command();
+                let man = clap_mangen::Man::new(cmd);
+                man.render(&mut io::stdout())
+                    .context("rendering man page")?;
+                return Ok(());
+            }
             Commands::McpServe => {
                 netscli_mcp::run_server().await?;
             }
 
@@ -0,0 +1,60 @@
+# Packaging
+
+Manifest templates and submission notes for getting netscli into the
+major OS package managers.
+
+Each subdirectory is a template that points at a specific release tag.
+After cutting a new release, update the version + SHA256 values and
+submit a PR to the respective registry.
+
+## How the release pipeline feeds these
+
+Every push of a `v*` tag triggers `.github/workflows/release.yml`,
+which for each platform:
+
+1. Builds the binary with `cargo build --release --locked`.
+2. Writes a `.sha256` alongside it.
+3. Signs it via [sigstore keyless](https://docs.sigstore.dev/cosign/signing/overview/)
+   using the GitHub Actions OIDC token, producing `.sig` + `.pem`.
+4. Uploads all four files as release assets.
+
+Package manifests reference the `.tar.gz`/`.zip`/`.exe` URL plus the
+SHA256. The `.sig` + `.pem` let security-conscious users verify
+provenance without trusting GitHub's binary storage:
+
+```bash
+cosign verify-blob \
+  --certificate netscli-linux-x86_64.pem \
+  --signature   netscli-linux-x86_64.sig \
+  --certificate-identity-regexp 'https://github.com/fstubner/netscli/.github/workflows/release\.yml@.*' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  netscli-linux-x86_64
+```
+
+## Submission targets
+
+| Registry | Dir | Status |
+|---|---|---|
+| Homebrew (tap) | [`homebrew/`](./homebrew/) | not submitted |
+| Scoop bucket | [`scoop/`](./scoop/) | not submitted |
+| Winget (microsoft/winget-pkgs) | [`winget/`](./winget/) | not submitted |
+| Arch AUR | [`aur/`](./aur/) | not submitted |
+
+Each directory has its own README with the exact submission steps. The
+submission PRs should be filed **after** the corresponding release is
+published and the assets (including `.sha256`) are live on the release
+page — the registries refuse PRs whose URLs 404 or whose checksums
+don't match the served bytes.
+
+## Release-day checklist
+
+1. Cut a crates.io release (see [`../docs/PUBLISHING.md`](../docs/PUBLISHING.md)).
+2. Tag `vX.Y.Z` and push. Release workflow builds + signs + uploads all
+   assets.
+3. Verify release page has the full asset matrix (22 files: 11 binaries
+   × `.sha256`/`.sig`/`.pem`).
+4. Run `./update-manifests.sh vX.Y.Z` (planned) to pull the real SHA256s
+   and stamp them into each template.
+5. Open the four PRs, one per registry.
+6. Monitor for lint/review feedback; most registries have maintainer
+   review latency in the hours-to-days range.
@@ -0,0 +1,48 @@
+# Maintainer: Felix Stubner <felix.stubner@gmail.com>
+
+pkgname=netscli-bin
+_binname=netscli
+pkgver=0.1.1
+pkgrel=1
+pkgdesc="Network scanner with CLI, TUI, desktop app, and MCP server"
+arch=('x86_64' 'aarch64')
+url="https://netscli.com"
+license=('MIT')
+provides=("${_binname}")
+conflicts=("${_binname}")
+source_x86_64=("${_binname}-${pkgver}-x86_64::https://github.com/fstubner/netscli/releases/download/v${pkgver}/netscli-linux-x86_64")
+source_aarch64=("${_binname}-${pkgver}-aarch64::https://github.com/fstubner/netscli/releases/download/v${pkgver}/netscli-linux-aarch64")
+sha256sums_x86_64=('VERSION_SHA256_LINUX_X86_64')
+sha256sums_aarch64=('VERSION_SHA256_LINUX_AARCH64')
+
+package() {
+  local src
+  if [[ $CARCH == "x86_64" ]]; then
+    src="${_binname}-${pkgver}-x86_64"
+  else
+    src="${_binname}-${pkgver}-aarch64"
+  fi
+
+  install -Dm755 "${srcdir}/${src}" "${pkgdir}/usr/bin/${_binname}"
+
+  # Shell completions — generate from the binary we just installed.
+  "${pkgdir}/usr/bin/${_binname}" completions bash \
+    > "${srcdir}/${_binname}.bash"
+  install -Dm644 "${srcdir}/${_binname}.bash" \
+    "${pkgdir}/usr/share/bash-completion/completions/${_binname}"
+
+  "${pkgdir}/usr/bin/${_binname}" completions zsh \
+    > "${srcdir}/_${_binname}"
+  install -Dm644 "${srcdir}/_${_binname}" \
+    "${pkgdir}/usr/share/zsh/site-functions/_${_binname}"
+
+  "${pkgdir}/usr/bin/${_binname}" completions fish \
+    > "${srcdir}/${_binname}.fish"
+  install -Dm644 "${srcdir}/${_binname}.fish" \
+    "${pkgdir}/usr/share/fish/vendor_completions.d/${_binname}.fish"
+
+  # Man page.
+  "${pkgdir}/usr/bin/${_binname}" man > "${srcdir}/${_binname}.1"
+  install -Dm644 "${srcdir}/${_binname}.1" \
+    "${pkgdir}/usr/share/man/man1/${_binname}.1"
+}
@@ -0,0 +1,48 @@
+# Arch User Repository (AUR)
+
+## First submission
+
+The AUR wants a git repo per package. The package namespace `netscli`
+is unclaimed; we submit as `netscli-bin` (Arch convention for a
+prebuilt-binary package; a `netscli` source package that compiles from
+crates.io would be a separate submission).
+
+```bash
+# One-time: clone your AUR profile
+git clone ssh://aur@aur.archlinux.org/netscli-bin.git
+cd netscli-bin
+
+# Copy the template PKGBUILD in, fill in real SHA256s from the release
+cp /path/to/packaging/aur/PKGBUILD .
+
+# Required: .SRCINFO derived from PKGBUILD
+makepkg --printsrcinfo > .SRCINFO
+
+# Sanity check the build
+makepkg -si
+
+# Submit
+git add PKGBUILD .SRCINFO
+git commit -m "Initial release: netscli-bin 0.1.1"
+git push origin master
+```
+
+## After each release
+
+```bash
+cd netscli-bin
+# Edit PKGBUILD: bump pkgver, replace the two sha256sums_* values
+makepkg --printsrcinfo > .SRCINFO
+git commit -am "Update to 0.1.2"
+git push
+```
+
+AUR is entirely self-service — there's no review, and the moment you
+push, the new version is live.
+
+## Source-based package (future)
+
+Once netscli is stable enough that its dep tree doesn't churn every
+release, a `netscli` source PKGBUILD that builds from crates.io is
+worth creating. It would avoid the `-bin` suffix and give Arch users
+a properly compiled binary for their specific CPU.
@@ -0,0 +1,34 @@
+# Homebrew
+
+## One-time setup: create the tap repo
+
+1. Create a new public GitHub repo named
+   [`fstubner/homebrew-tap`](https://github.com/fstubner/homebrew-tap).
+   Homebrew finds taps by the `homebrew-` prefix.
+2. Copy `netscli.rb` from this directory into `Formula/netscli.rb` in
+   that repo. Commit and push.
+
+Users install with:
+
+```bash
+brew tap fstubner/tap
+brew install netscli
+```
+
+## After each release
+
+1. Update `Formula/netscli.rb` in the tap repo:
+   - bump `version`
+   - replace the four `VERSION_SHA256_*` values with the SHA256s from
+     the new release's `.sha256` files
+2. `brew install --build-from-source ./Formula/netscli.rb` to verify
+   locally.
+3. Commit + push to the tap.
+
+## Moving to homebrew-core later
+
+Once the project has ~1k stars and a stable release track record, the
+formula can be submitted to
+[Homebrew/homebrew-core](https://github.com/Homebrew/homebrew-core) so
+users don't need to tap — `brew install netscli` just works. Formula
+structure stays similar; the review is stricter.
Original file line number	Diff line number	Diff line change
`@@ -499,6 +499,21 @@ async fn main() -> Result<()> {`
`499`	`499`	`}`
`500`	`500`	`}`
`501`	`501`	`}`
	`502`	`+ Commands::Completions { shell } => {`
	`503`	`+ use clap::CommandFactory;`
	`504`	`+ let mut cmd = Cli::command();`
	`505`	`+ let name = cmd.get_name().to_string();`
	`506`	`+ clap_complete::generate(*shell, &mut cmd, name, &mut io::stdout());`
	`507`	`+ return Ok(());`
	`508`	`+ }`
	`509`	`+ Commands::Man => {`
	`510`	`+ use clap::CommandFactory;`
	`511`	`+ let cmd = Cli::command();`
	`512`	`+ let man = clap_mangen::Man::new(cmd);`
	`513`	`+ man.render(&mut io::stdout())`
	`514`	`+ .context("rendering man page")?;`
	`515`	`+ return Ok(());`
	`516`	`+ }`
`502`	`517`	`Commands::McpServe => {`
`503`	`518`	`netscli_mcp::run_server().await?;`
`504`	`519`	`}`