ticket: plan insomnia cli ownership

work-items/open/20260531-111956-insomnia-crate-cli-owner/item.md

@@ -0,0 +1,62 @@
+---
+id: 20260531-111956-insomnia-crate-cli-owner
+slug: insomnia-crate-cli-owner
+title: CLI: make insomnia crate own binary entrypoint and CLI dispatch
+status: open
+kind: task
+priority: P2
+labels: [cli, tui, pod, architecture]
+created_at: 2026-05-31T11:19:56Z
+updated_at: 2026-05-31T11:19:56Z
+assignee: null
+legacy_ticket: null
+---
+
+## Background
+
+The single-binary migration currently exposes the installed command as `insomnia`, but the binary target and CLI dispatch are still owned by the `tui` package (`cargo run -p tui -- ...`, `crates/tui/src/main.rs`). The helper crate now named `insomnia` was originally introduced for Pod runtime command resolution, which creates a responsibility mismatch.
+
+The desired architecture is that the `insomnia` crate owns the product CLI and binary entrypoint. The `tui` and `pod` crates should be libraries with no `main.rs`, and CLI/tool subcommand routing should happen at the `insomnia` boundary.
+
+## Requirements
+
+- Move product CLI ownership to the `insomnia` crate:
+  - binary target `insomnia` belongs to package/crate `insomnia`;
+  - CLI argument parsing and top-level mode/subcommand dispatch live in `insomnia`;
+  - development entrypoint becomes `cargo run -p insomnia -- ...`.
+- Make `tui` a library implementation crate rather than binary/CLI owner.
+  - `tui` should expose an API for launching the terminal UI with already-parsed options/configuration.
+  - `tui` should not own `insomnia pod ...` dispatch or headless CLI tool routing.
+- Keep `pod` as a library runtime crate with no dependency on `insomnia`.
+  - `pod` may expose its runtime entrypoint/parser API for `insomnia pod ...`, but it must not know the product CLI crate.
+- Move or relocate `PodRuntimeCommand` responsibility out of the current `insomnia` helper role if needed to avoid inverted dependencies.
+  - `pod -> insomnia` is not acceptable.
+  - Prefer passing the runtime command from the top-level CLI/orchestrating layer into TUI/client spawn paths.
+  - If a shared type is still needed, place it in a lower-level crate whose responsibility is process/client mechanics, not in the product CLI crate by accident.
+- CLI tools/headless commands should be routed by `insomnia`, not by `tui`.
+  - Examples: `memory lint`, `pod ...`, future non-TUI commands.
+- Preserve observable behavior:
+  - installed command remains `insomnia`;
+  - `insomnia -r`, `insomnia --multi`, `insomnia <podname>`, and `insomnia pod ...` keep their behavior;
+  - no `insomnia-pod` alias is reintroduced;
+  - Pod runtime remains a separate process.
+- Do not add compatibility layers for `cargo run -p tui -- ...`; updating docs/dev commands is sufficient.
+
+## Non-goals
+
+- Renaming the user-facing command away from `insomnia`.
+- Merging Pod runtime into the TUI process.
+- Reintroducing `INSOMNIA_POD_COMMAND` or test-only env command overrides.
+- Redesigning Pod protocol, profile semantics, or manifest semantics.
+- Broad TUI module-layout refactors beyond what is necessary to make `tui` library-callable.
+
+## Acceptance criteria
+
+- `cargo run -p insomnia -- --help` and `cargo run -p insomnia -- pod --help` work as the main development entrypoints.
+- Package `tui` no longer owns a binary `main.rs` entrypoint, or any remaining binary target is explicitly temporary and not the product CLI owner.
+- No active code path requires `pod -> insomnia` or `tui -> insomnia` dependency.
+- `insomnia` crate owns top-level CLI parsing/dispatch for TUI launch, Pod runtime launch, and headless CLI tools.
+- Pod spawn/restore still launches runtime subprocesses as `insomnia pod ...` through typed command injection from the top-level owner.
+- Nix/package outputs still expose only `bin/insomnia`.
+- Current docs/dev instructions no longer tell developers to use `cargo run -p tui -- ...` as the primary product CLI path.
+- Focused CLI/parser/spawn tests, `cargo fmt --check`, relevant `cargo check`/`cargo test`, `nix build .#insomnia` if packaging changed, `./tickets.sh doctor`, and `git diff --check` pass.

work-items/open/20260531-111956-insomnia-crate-cli-owner/thread.md

@@ -0,0 +1,7 @@
+<!-- event: create author: tickets.sh at: 2026-05-31T11:19:56Z -->
+
+## Created
+
+Created by tickets.sh create.
+
+---