cli: create insomnia-pod removal ticket

work-items/open/20260531-054728-remove-insomnia-pod-binary/item.md

@@ -0,0 +1,68 @@
+---
+id: 20260531-054728-remove-insomnia-pod-binary
+slug: remove-insomnia-pod-binary
+title: CLI: remove insomnia-pod installed/runtime alias
+status: open
+kind: task
+priority: P2
+labels: [cli, pod, nix, docs]
+created_at: 2026-05-31T05:47:28Z
+updated_at: 2026-05-31T05:48:20Z
+assignee: null
+legacy_ticket: null
+---
+
+## Background
+
+Parent/umbrella ticket: `single-binary-insomnia-cli`.
+
+Previous phases have already:
+
+- added `insomnia pod ...` as the Pod runtime entrypoint;
+- moved internal spawn/restore defaults to typed `current_exe() + ["pod"]` command resolution;
+- left `insomnia-pod` as a temporary old binary/package output.
+
+The user decision is that `insomnia-pod` does not need to remain as a compatibility alias. It was never designed as a human-facing command. The next phase is to remove/demote it so the installed package exposes one primary runtime executable: `insomnia`.
+
+## Requirements
+
+- Remove the long-term `insomnia-pod` installed/runtime alias.
+- Prefer removing the `insomnia-pod` binary target from the `pod` crate if no active tests/build paths require it.
+  - The `pod` crate should remain as a library crate providing the Pod runtime entrypoint used by `insomnia pod ...`.
+  - If a temporary binary target must remain for a narrow reason, document exactly why and do not install/expose it.
+- Update Nix packaging:
+  - build/install only the user-facing `insomnia` binary as the package command;
+  - remove `apps.insomnia-pod` from `flake.nix`;
+  - update install checks to use `insomnia pod --help` instead of `insomnia-pod --help`.
+- Update devshell behavior:
+  - remove the `insomnia-pod` wrapper if internal callers no longer need it;
+  - preserve the “do not pollute `INSOMNIA-READY` stderr handshake with cargo output” property for dev workflows if a wrapper remains necessary;
+  - document any remaining dev override path (`INSOMNIA_POD_COMMAND`) if still relevant.
+- Update docs that describe installed commands / Nix usage / profile manifest CLI examples:
+  - replace user-facing `insomnia-pod ...` examples with `insomnia pod ...` where current behavior is intended;
+  - avoid rewriting historical work-item artifacts;
+  - leave clearly historical docs alone unless they are current user docs.
+- Preserve runtime behavior:
+  - `insomnia pod --help` works;
+  - Pod spawning/restoration still uses `insomnia pod ...` by default;
+  - `INSOMNIA_POD_COMMAND` override behavior remains executable-only if still supported, or is intentionally removed with tests/docs updated.
+- Do not rename the `tui` package/crate in this ticket.
+- Do not merge Pod controller into the TUI process.
+
+## Non-goals
+
+- Crate/package rename from `tui` to `insomnia`.
+- Removing the `pod` library crate.
+- Changing Pod runtime flags/profile/manifest semantics.
+- Changing Pod protocol.
+- Large CLI UX redesign.
+
+## Acceptance criteria
+
+- Installed/Nix package exposes `bin/insomnia` as the primary command and no longer exposes `bin/insomnia-pod`.
+- `nix build .#insomnia` and install checks pass using `insomnia pod --help`.
+- `flake.nix` no longer advertises `apps.insomnia-pod`.
+- `insomnia pod --help` and relevant Pod runtime parser tests pass.
+- Internal spawn/restore tests still pass after removing the old binary output.
+- Current docs no longer instruct users to run `insomnia-pod` as the normal runtime command; use `insomnia pod` instead.
+- `cargo fmt --check`, focused pod/tui/client/nix tests or checks, `cargo check -p tui -p pod -p client`, `./tickets.sh doctor`, and `git diff --check` pass.

work-items/open/20260531-054728-remove-insomnia-pod-binary/thread.md

@@ -0,0 +1,22 @@
+<!-- event: create author: tickets.sh at: 2026-05-31T05:47:28Z -->
+
+## Created
+
+Created by tickets.sh create.
+
+---
+
+<!-- event: plan author: hare at: 2026-05-31T05:48:20Z -->
+
+## Plan
+
+Implementation plan:
+
+1. Remove or demote the `insomnia-pod` Cargo binary target if active code/tests no longer require it; keep `pod` as a library crate.
+2. Update Nix packaging/install checks and flake app outputs so the package exposes only `insomnia`; install checks should call `insomnia pod --help`.
+3. Update devshell wrapper behavior. Since internal default spawning now uses `current_exe() + ["pod"]`, the old `insomnia-pod` wrapper should be removed unless a focused dev reason remains.
+4. Update current user docs (`docs/nix.md`, `docs/pod-factory.md`, manifest/profile docs, architecture docs) from `insomnia-pod` to `insomnia pod`. Do not rewrite historical work-item artifacts.
+5. Validate runtime parser/help, internal spawn/restore tests, Nix build, doctor, and diff check.
+
+
+---