cli: create single binary architecture ticket

work-items/open/20260531-005557-single-binary-insomnia-cli/item.md

@@ -0,0 +1,50 @@
+---
+id: 20260531-005557-single-binary-insomnia-cli
+slug: single-binary-insomnia-cli
+title: CLI: clarify single-binary insomnia architecture
+status: open
+kind: task
+priority: P2
+labels: [cli, architecture, nix]
+created_at: 2026-05-31T00:55:57Z
+updated_at: 2026-05-31T00:56:38Z
+assignee: null
+legacy_ticket: null
+---
+
+## Background
+
+The installed user-facing command is already `insomnia`, while the Cargo package/crate that owns it is still named `tui`. Headless CLI commands such as `insomnia memory lint` are starting to live in that same binary. This is acceptable short-term, but the architecture should be made explicit before more commands accumulate.
+
+The preferred product direction is a single user-facing `insomnia` binary that can run TUI screens and headless commands. The main downside is that headless commands inherit ratatui/crossterm and related dependencies, but binary size is not expected to dominate runtime memory compared with LLM clients, HTTP/TLS, JSON/session/memory processing, and spawned process orchestration. A single binary also improves distribution and “minimal standalone install” ergonomics.
+
+## Requirements
+
+- Decide and document the intended command architecture:
+  - one installed `insomnia` binary as the primary user-facing entry point;
+  - headless subcommands under that binary;
+  - TUI/interactive paths as subcommands or default modes;
+  - relationship to `insomnia-pod`.
+- Refactor only if necessary to keep headless commands cleanly separated from terminal/TUI initialization.
+- Ensure headless commands do not initialize ratatui, enter raw mode, connect Pod sockets, or spawn Pod processes unless explicitly requested by that command.
+- Evaluate whether to rename the Cargo package/crate from `tui` to `insomnia`.
+  - If the rename is straightforward, implement it with scoped Nix/docs updates.
+  - If it is broad/risky, leave the rename as a follow-up and document the boundary.
+- Keep installed command names stable unless a separate explicit decision says otherwise.
+- Preserve Nix/Home Manager packaging expectations: installing the flake package should put the intended commands on `PATH`.
+- Avoid introducing separate binaries for every headless command unless there is a measured startup/binary-size/runtime-memory reason.
+
+## Non-goals
+
+- Reworking the Pod daemon binary protocol.
+- Removing `insomnia-pod` unless a separate architecture decision covers Pod process lifecycle.
+- Feature-gating ratatui/crossterm for a headless-only build before there is a measured need.
+- Large CLI UX redesign beyond clarifying the single-binary structure.
+
+## Acceptance criteria
+
+- The repository has a clear documented decision or implementation path for the single-binary `insomnia` CLI architecture.
+- Existing TUI flows and headless command flows remain tested.
+- If crate/package rename is implemented, Cargo/Nix/docs references are updated consistently.
+- If crate/package rename is deferred, a precise follow-up or documented rationale explains why.
+- `cargo fmt --check`, relevant `cargo test`/`cargo check`, `./tickets.sh doctor`, and `git diff --check` pass.

work-items/open/20260531-005557-single-binary-insomnia-cli/thread.md

@@ -0,0 +1,22 @@
+<!-- event: create author: tickets.sh at: 2026-05-31T00:55:57Z -->
+
+## Created
+
+Created by tickets.sh create.
+
+---
+
+<!-- event: decision author: hare at: 2026-05-31T00:56:38Z -->
+
+## Decision
+
+Decision note from discussion:
+
+- Short-term direction: keep adding headless commands to the existing user-facing `insomnia` binary owned by the current `tui` crate.
+- Product preference: a single standalone `insomnia` binary is easier to distribute and explain than many small binaries.
+- Known tradeoff: headless commands inherit TUI dependencies such as ratatui/crossterm. This is acceptable until binary size/startup/runtime memory is measured as a real problem.
+- Internal structure should still separate headless command dispatch from terminal/TUI initialization.
+- Future cleanup: consider renaming the Cargo package/crate from `tui` to `insomnia`; treat it as part of this ticket only if the scope remains contained.
+
+
+---