Output references, paste batches, queue conditions, pins and recipes

docs/architecture/context-modules.md

@@ -8,8 +8,8 @@ without taking over shell execution or running anything the workspace chose.
 > **Release status.** v0.17.0 shipped the foundation: typed fact metadata,
 > native module routing and the Context Rail. Everything else described here —
 > capability scheduling, the first-party module catalog, declarative Context
-> Packs, Status Strip routing and Status Strip 2.0, `/modules` and Claude Code agent context — shipped in
-> v0.18.0.
+> Packs, Status Strip routing and Status Strip 2.0, `/modules` and Claude Code agent context — is in
+> the v0.18 development stack, pending acceptance and release.
 
 ## From capability to presentation
 
@@ -169,9 +169,28 @@ fullscreen programs hide it, and it is never written to the transcript.
 - **Packs** — bundled and installed Context Packs with their verified state;
   installed packs can be enabled, disabled or removed (with confirmation).
 
+Short detail panels keep the module title visible and scroll through existing rows
+with Up/Down or PageUp/PageDown. Resize clamps that temporary view; scrolling
+does not edit settings or demand data.
+
 A module's details show what it reads, whether its value may be kept with
 commands in history, and each fact's current state ("fresh · 3s ago", "last
-known, refreshing", "unavailable (timed out after 1500 ms)", "not checked").
+known, refresh waits for demand", "unavailable (timeout)", "not checked"). Trusted source IDs,
+scope, freshness TTL, event invalidation and demand-driven refresh policy come
+from the capability definition. Failure text excludes raw exception paths and
+values. A failed refresh can retain a previous value; the view distinguishes
+that from a failure with no cached value, without claiming that new data arrived.
+
+"Took" measures the last collection's wall time, starting when the scheduler
+dispatches it; it excludes time waiting in the queue. An unmeasured collection
+has no invented zero. Opening details reads existing snapshots and declarations,
+and does not demand collectors. `/doctor` summarizes bounded engine counters.
+Routing, provider availability, conditions and priority explain presentation
+policy. Enabled means the saved setting, not proof that the module is on screen.
+The live condition check is shared with Native rendering; it does not infer
+visibility from collection success. Width fitting can compact or omit lower
+priority modules; the detail view does not claim to record the last frame's
+exact compaction decisions.
 `/shell` edits the current-shell module's visibility and side.
 
 ## Context Packs

docs/design/claude-remote-control-compatibility.md

@@ -0,0 +1,62 @@
+# Claude Remote Control: compatibility findings
+
+Issue [#340](https://github.com/raiseCatError/notMyShell/issues/340) (research). Primary source: Anthropic's Claude Code
+documentation page *Continue local sessions from any device with Remote Control*
+(`https://code.claude.com/docs/en/remote-control`), read on 2026-10-10. Findings are what the page states or does not
+state; **nothing here was probed against a live account**, which needs an eligible claude.ai login and a human to
+approve it. Re-verify before any implementation: the feature is new and its flags change.
+
+## What the documentation says
+
+| Topic | Documented fact |
+| --- | --- |
+| Where it runs | The session keeps running on the person's machine; the remote surface (claude.ai/code, mobile apps) drives it |
+| Invocation modes | `claude remote-control` (server mode, creates sessions on demand), `claude --remote-control` / `--rc` (a normal interactive session that is also reachable remotely), `/remote-control` or `/rc` inside an existing session; the Desktop app and VS Code extension use `/remote-control` |
+| Eligibility | Pro, Max, Team and Enterprise; **API keys are not supported**; Team and Enterprise need an Owner to enable the toggle in admin settings; a claude.ai login is required |
+| One session per process | Each interactive process registers one remote session; several instances give several sessions. Server mode runs several sessions in one process (`--capacity`, default 32; `--spawn same-dir` or `worktree`) |
+| Flags | Global `claude` flags placed before `remote-control` (or added by a wrapper) are **not** carried into the sessions the server creates; `--permission-mode` and sandboxing are set explicitly |
+| Trust | In an untrusted directory `claude remote-control` asks `Trust <directory>? [y/N]` before starting |
+| Terminal indicator | An interactive session shows an `/rc active` indicator (hidden in terminals that are too narrow) and a failure reason when the connection drops |
+| Security model | Outbound HTTPS only, no inbound ports; traffic through the Anthropic API over TLS; optional Trusted Devices enrolment, enforced per organization |
+| Resume | `claude remote-control --continue` / `--session-id` for about four hours after the server stops; interactive sessions resume with `claude --continue` / `--resume` |
+| Not documented | Any support for `--print` / stream-json (headless or SDK-style) sessions, for a third-party UI driving the session, or for exposing the remote channel to such a UI |
+
+## What this means for NMSh
+
+NMSh has two relationships with Claude Code:
+
+1. **Raw (native TUI)**: Claude runs in NMSh's shell as any program. `claude --remote-control` and `/remote-control` are
+   Claude's own features, work exactly as documented, and need nothing from NMSh. NMSh only has to keep passthrough
+   correct (it does).
+2. **Managed**: NMSh drives Claude through `--print --input-format stream-json --output-format stream-json` (see
+   `src/agents/sessions/claudeAdapter.ts`). **The documentation does not describe Remote Control for that mode.** The
+   modes it does describe are interactive sessions and its own server.
+
+| Question | Finding |
+| --- | --- |
+| Remote Control for a Raw session | **Supported by Claude itself**; NMSh must not interfere or claim it |
+| Remote Control for a Managed (stream-json) session | **Unknown / undocumented.** Do not advertise it |
+| NMSh starting `claude remote-control` as a managed target | **Unsupported**: server mode creates its own sessions with its own permission handling; NMSh could not own the approval path or the transcript |
+| Flag inheritance for per-profile launch policy | **Documented limitation**: flags are not inherited by server-created sessions, so a per-profile `--permission-mode` would have to be passed to the server itself |
+| Account/device boundaries | Remote Control needs the person's claude.ai login (no API keys) and may be gated by an organization toggle and Trusted Devices; NMSh must never read, store or forward those credentials, and must show the organization's refusal as Claude reports it |
+| Privacy | A remote session sends the conversation through Anthropic's API to the person's other devices; that is a data-sharing choice the person makes inside Claude, not an NMSh feature |
+
+## Go / no-go
+
+**No-go for a Never / Ask / Always Remote Control setting in NMSh at this time.** The only supported combination (Raw +
+Claude's own commands) needs no NMSh feature, and the Managed combination is undocumented. A setting would imply support
+NMSh cannot demonstrate and would blur who owns approvals.
+
+Revisit when: (a) Anthropic documents Remote Control for headless or SDK-driven sessions, or (b) a human-run probe
+shows a supported way to attach the remote channel to a stream-json session.
+
+## Probe plan (not run; needs a person with an eligible login)
+
+1. With an eligible account on a test machine, run Claude in Raw mode under NMSh, enable `/remote-control`, and confirm
+   the `/rc active` indicator survives NMSh's passthrough, resize and detach/reattach. Record the Claude Code version.
+2. Start a Managed target and check whether any documented flag attaches Remote Control to a stream-json session. Record
+   the exact help text and error output; treat silence as "unsupported".
+3. Confirm that environment variables and arguments NMSh sets for a managed target do not change the login Claude uses.
+4. Record each result with the Claude Code version and date in this file.
+
+Any implementation is a separate reviewed scope with physical validation, as the issue requires.

docs/design/external-tool-decisions.md

@@ -0,0 +1,58 @@
+# External tool integrations: decisions
+
+Issue [#366](https://github.com/raiseCatError/notMyShell/issues/366), under [#359](https://github.com/raiseCatError/notMyShell/issues/359).
+Every candidate was checked against what NMSh already does (the curated `/tools` catalog in `src/tools/catalog.ts`, the
+provider registry behind `/providers`, `/dirs`, `/open`, Theme Bridge, the clipboard writer and reader, the same-shell
+command queue, native Compare). A decision is one of **adopt** (already supported or built), **defer** (a plausible
+slice, not now) or **reject**.
+
+## Principles that decide every row
+
+- Optional and absent-safe: NMSh works fully without any of these. Nothing is installed, configured or enabled without
+  a deliberate action and a preview.
+- The native same-shell **queue** stays the way to prepare commands for the person's own shell. It keeps the shell's
+  state (directory, variables, functions) and its input ownership. A detached job runner is a different tool for a
+  different job, never a replacement.
+- Native **Compare** stays the comparison of two stored command outputs. An external diff renderer adds colour, not
+  meaning.
+- No tool receives clipboard or output contents unless the person invoked that tool on that content.
+- No second picker, file manager or form framework inside NMSh.
+
+## Decisions
+
+| Tool | Already in NMSh | Decision | Why |
+| --- | --- | --- | --- |
+| **[Atuin](https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/config.md)** | Curated in `/tools`; usable as the explicit history provider (`/providers`); NMSh reads local commands and metadata for suggestions | **Adopt as is** | NMSh keeps shell history authority and uses Atuin as an optional source. Project/session-aware ranking is already NMSh's own (directory affinity, frecency); do not add a second history store |
+| **[fzf](https://github.com/junegunn/fzf#usage)** | Curated in `/tools`; selection provider; shell keybindings remain external configuration | **Adopt as is** | The existing picker provider covers selection. No new picker subsystem |
+| **[Television](https://github.com/alexpasmantier/television#readme)** | Curated in `/tools`; picker provider choice | **Adopt as is** | Same provider slot as fzf. Preview/select actions for output references (#353) already use NMSh's own palette, which is enough |
+| **[zoxide](https://github.com/ajeetdsouza/zoxide#readme)** | Curated in `/tools`; directory provider behind `/dirs`, queried through a private database copy | **Adopt as is** | zoxide can write while querying. NMSh protects the original database and falls back to Native when it cannot obtain a bounded snapshot |
+| **[bat](https://github.com/sharkdp/bat#adding-new-themes)** | Curated in `/tools`; Ask knows it; Theme Bridge offers an owned theme and explicitly reviewed cache build | **Adopt as is** | No dedicated source-preview launcher is implemented. Users can invoke bat in their shell; Compare and reports use native plain text |
+| **[delta](https://github.com/dandavison/delta#readme)** | Curated in `/tools`; Theme Bridge offers optional Git diff colours and bat-backed syntax theme support | **Adopt as is; do not use for Compare** | Native Compare uses a bounded edit distance, reviewed reports and a sanitized plain diff copy. Sending output to an external renderer creates another presentation/copy boundary without addressing the accepted workflow needs |
+| **[Pueue](https://github.com/Nukesor/pueue#readme)** | No Pueue adapter | **Defer** | Its separate daemon provides durable jobs, but it owns independent execution and persisted output. A reviewed handoff would need output capture and transcript provenance. The same-shell queue stays native. Workspace background-task work (#383/#384) belongs to the other track; adding a second adapter before that handoff is premature |
+| **[Yazi](https://yazi-rs.github.io/docs/tips/)** | No chooser adapter | **Defer** | Returning paths through `--chooser-file` is plausible, but needs a bounded private result file, validated shell quoting, passthrough handoff and explicit insertion. No accepted implementation slice supersedes the existing deferral |
+| **[Gum](https://github.com/charmbracelet/gum#readme)** | No Gum-specific adapter | **Reject** | Gum provides script prompts. NMSh retains ordinary passthrough and input ownership rather than adding a forms framework. Gum-specific physical interoperability has not been validated |
+
+## What stays native, and why
+
+- **Command queue** (same shell, once-only, pauses on failure or interrupt, optional approval): needed because the next
+  command depends on the state the previous one left in the person's shell.
+- **Compare** and **Copy as Report**: exact, reviewed, redactable text; the properties that make them safe to share would
+  be lost behind an external renderer.
+- **Output references and failure navigation**: use the existing editor/browser bridges instead of a picker tool.
+
+## Follow-ups worth a ticket each
+
+1. Yazi chooser handoff (isolated, high value).
+2. Pueue *send to background* with status (needs the output-capture design first).
+
+## Implementation evidence and limits
+
+Re-audited 2026-10-11. Existing optional-provider behavior is implemented in
+[`historyProviders.ts`](../../src/shell/historyProviders.ts),
+[`HistoryService.ts`](../../src/shell/HistoryService.ts),
+[`Picker.ts`](../../src/pickers/Picker.ts),
+[`DirectoryService.ts`](../../src/shell/DirectoryService.ts) and
+[`Theme Bridge runtime`](../../src/themeBridge/runtime.ts).
+Provider and bridge tests cover bounded reads, absent dependencies, native fallbacks and owned configuration;
+live queue, alternate-screen and report/diff acceptance covers the retained native paths. No new CLI adapter is
+claimed by this audit. Host-specific picker visuals and physical interoperability remain human QA.