feat: unify automatic shell setup

AGENTS.md

@@ -37,6 +37,44 @@ cp target/release/recall ~/.local/bin/recall
 rm -f ~/.local/bin/recall.old
 ```
 
+### Testing installation changes locally
+
+Use the developer-only harness to build the current checkout, package it like a
+release, and run the production installer against that local fixture:
+
+```sh
+./scripts/dev-install.sh
+```
+
+The default mode creates an isolated home, binary directory, configuration, and
+data directory under `target/dev-install.*`. It prints the command for starting
+an interactive shell in that sandbox. The sandbox must not read or modify the
+real user profile, Recall configuration, or history database.
+
+Use `--user` only when a real local installation is intentional:
+
+```sh
+./scripts/dev-install.sh --user
+./scripts/dev-install.sh --user --mode hooks
+```
+
+`--user` gives the production installer the real user environment, including
+its normal destination selection, configuration handling, search-key choice,
+and history-import prompts. `RECALL_INSTALL_DIR` and the other documented
+installer environment variables continue to work. The harness supports the
+Unix installer; select a shell explicitly with `--shell` when `$SHELL` is not
+suitable.
+
+Keep the production `install.sh` independent from development concerns: do not
+add local-build switches to it or make it source the developer harness. The
+harness intentionally invokes the unchanged production installer with a local
+GitHub API, archive, and checksum substitute. This exercises the same logo,
+archive extraction, checksum verification, setup, configuration, prompts, and
+summary that users see without making GitHub requests. Shared post-install
+behavior belongs in the `recall setup` and `recall config` Rust commands rather
+than duplicated shell fragments. Live GitHub networking and published release
+assets remain responsibilities of release CI.
+
 ## Architecture
 
 ```

Cargo.toml

@@ -39,4 +39,4 @@ crossterm = { version = "0.29.0", features = ["use-dev-tty"] }
 
 [target."cfg(windows)".dependencies]
 sysinfo = { version = "=0.38.0", default-features = false, features = ["system"] }
-windows-sys = { version = "0.60", features = ["Win32_Foundation", "Win32_System_Console"] }
+windows-sys = { version = "0.60", features = ["Win32_Foundation", "Win32_Storage_FileSystem", "Win32_System_Console"] }

README.md

@@ -34,18 +34,19 @@ the matching binary from the latest GitHub Release, and verifies its SHA-256
 checksum. It then:
 
 - installs recall into `/usr/local/bin` or `~/.local/bin`;
-- adds the shell integration to zsh, bash, or fish automatically;
+- configures zsh, bash, or fish for automatic output capture and search;
 - creates the default `config.toml` without overwriting an existing one;
 - detects existing bash, zsh, fish, and atuin history and asks whether to import
   each source;
-- asks how new terminals should start recall's PTY proxy for automatic output
-  capture. Terminal emulator configuration is recommended; shell startup is
-  available as a fallback.
+- starts recall's PTY proxy automatically in new interactive shells without
+  changing terminal-emulator settings.
 
-For a non-interactive installation, set `RECALL_PROXY_SETUP` to `terminal`,
-`shell`, or `none` on the `sh` command. Set `RECALL_IMPORT_HISTORY` to `yes`,
-`no`, or `ask` to control history migration (`ask` skips prompts when input is
-not interactive).
+Automatic output capture is the default. Set `RECALL_PROXY_SETUP=hooks` for the
+lighter alternative that installs search and metadata hooks but only captures
+output after you run `recall shell`. The legacy values `shell` and `none` remain
+aliases for `auto` and `hooks`; explicit `terminal` mode is retained for
+existing terminal-managed setups. Set `RECALL_IMPORT_HISTORY` to `yes`, `no`,
+or `ask` to control history migration.
 
 ### One-line installer (Windows)
 
@@ -55,10 +56,11 @@ irm https://raw.githubusercontent.com/wendaining/recall/master/install.ps1 | iex
 
 The installer downloads the latest release, verifies its SHA-256 checksum, and
 installs `recall.exe` into `%USERPROFILE%\.local\bin` (override with
-`RECALL_INSTALL_DIR`). It adds that directory to your user `PATH`, appends the
-PowerShell integration to `$PROFILE`, and creates the default `config.toml`.
+`RECALL_INSTALL_DIR`). It adds that directory to your user `PATH`, configures
+`$PROFILE` for automatic output capture, and creates the default `config.toml`.
 It also offers to import detected shell and atuin histories. Set
-`RECALL_NO_MODIFY_PROFILE` to skip the profile change, or
+`RECALL_NO_MODIFY_PROFILE` to skip the profile change,
+`RECALL_PROXY_SETUP=hooks` to install hooks without automatic capture, or
 `RECALL_IMPORT_HISTORY=yes|no|ask` to control migration prompts.
 
 ### Build from source
@@ -132,9 +134,30 @@ a custom `RECALL_INSTALL_DIR`, pass the same variable to the uninstall command.
 > configuration automatically. The manual steps below are mainly for source
 > builds or custom setups.
 
-### 1. Shell integration
+### 1. Unified shell setup
 
-If you built from source, add the matching line to your shell's startup file:
+If you built from source, run the setup command for your shell:
+
+```sh
+recall setup zsh       # or: bash, fish, pwsh, powershell
+```
+
+This configures automatic output capture by default. recall places a small,
+managed bootstrap at the top of the startup file and the integration at the
+end. The outer shell hands off to the PTY proxy before loading the rest of the
+file; the child shell then loads your configuration once and installs the
+hooks after themes, prompts, and PSReadLine are ready.
+
+For search and metadata hooks without automatic capture, use:
+
+```sh
+recall setup zsh --mode hooks
+```
+
+Run `recall setup zsh --remove` to remove only the blocks managed by recall.
+User-written setup remains untouched.
+
+`recall init` remains the low-level option for fully manual setups:
 
 ```zsh
 # ~/.zshrc
@@ -156,9 +179,9 @@ recall init fish | source
 recall init pwsh | Out-String | Invoke-Expression
 ```
 
-This installs the capture hooks and an **Alt+R** widget that opens the TUI and
-inserts the selected command into your prompt. The key is set by
-`[ui].search_key` in the config; see below for details.
+The integration installs command-boundary hooks and an **Alt+R** widget that
+opens the TUI and inserts the selected command into your prompt. The key is set
+by `[ui].search_key` in the config; see below for details.
 
 Without the proxy, recall still records command metadata in the background. To
 capture output, run your shell under the proxy.
@@ -196,24 +219,22 @@ You can also pick another key, for example `"ctrl-x ctrl-r"` (the installer
 offers this on macOS). Run `recall doctor` to confirm the shell integration and
 `PATH`.
 
-### 2. Enable output capture with the PTY proxy
+### 2. Output capture and the PTY proxy
 
-The one-line installer offers two setup methods. Configuring your terminal
-emulator's startup command is recommended. If your terminal does not provide
-that setting, the installer can configure your shell startup file instead.
-Either method starts your usual shell inside recall's PTY proxy so recall can
-save the output associated with each command.
+The installer and `recall setup` start your usual shell inside recall's PTY
+proxy automatically. No terminal-emulator configuration is needed. Set
+`RECALL_PROXY=0` before starting a new shell to bypass automatic capture while
+keeping the search and metadata hooks.
 
-If you skipped the setup or installed from source, start a wrapped shell
-manually:
+In hooks-only or fully manual setups, start a wrapped shell when output capture
+is needed:
 
 ```sh
 recall shell
 ```
 
-or configure your terminal emulator to launch it as the shell, so every new
-window is captured automatically. The setting name varies between emulators
-(`shell`, `command`, …), for example:
+Existing terminal-managed setups may continue launching recall directly, but
+this is an advanced compatibility path rather than the recommended setup:
 
 ```
 # in your terminal emulator's config file
@@ -238,8 +259,7 @@ On Windows the proxy runs the shell under ConPTY. When neither `proxy.shell` nor
 the parent process chain), then falls back to `pwsh`, `powershell`, and
 `%COMSPEC%`. Override with `--shell` or `proxy.shell`, for example
 `recall shell --shell cmd`. The macOS-only `-l` login flag is not used on
-Windows. To capture every Windows Terminal tab automatically, set the profile's
-**Command line** to `recall shell` (Settings → your profile → Command line).
+Windows.
 
 ### 3. Import existing history (optional)
 
@@ -274,6 +294,7 @@ Other commands:
 
 ```sh
 recall search --cmd-only   # print the selection (used by the zsh widget)
+recall setup [shell]       # configure automatic capture and shell hooks
 recall doctor              # diagnose config, databases and clipboard
 recall prune               # drop output older than the retention window
 recall config path|show|default

README.zh-CN.md

@@ -31,15 +31,15 @@ curl -fsSL https://raw.githubusercontent.com/wendaining/recall/master/install.sh
 下载对应二进制文件并校验 SHA-256。随后它会：
 
 - 将 recall 安装到 `/usr/local/bin` 或 `~/.local/bin`；
-- 自动把 shell 集成写入 zsh、bash 或 fish 的启动文件；
+- 为 zsh、bash 或 fish 配置自动输出捕获与搜索快捷键；
 - 在正确位置创建默认 `config.toml`，已有配置不会被覆盖；
 - 检测已有 bash、zsh、fish 与 atuin 历史，并逐项询问是否导入；
-- 询问新终端该如何启动 recall 的 PTY 代理以自动捕获输出。推荐配置终端模拟器；
-  如果终端不支持，再使用 shell 启动文件方式。
+- 在新的交互式 shell 中自动启动 PTY 代理，无需修改终端模拟器设置。
 
-非交互安装时，可在 `sh` 命令上将 `RECALL_PROXY_SETUP` 设置为 `terminal`、
-`shell` 或 `none`。`RECALL_IMPORT_HISTORY` 可设为 `yes`、`no` 或 `ask` 来控制
-历史迁移；输入不是交互终端时，`ask` 不会阻塞安装。
+默认会自动捕获输出。若只需要搜索快捷键和元数据，可设置
+`RECALL_PROXY_SETUP=hooks`，需要捕获输出时再运行 `recall shell`。旧值 `shell`
+和 `none` 分别兼容映射为 `auto` 与 `hooks`；显式 `terminal` 模式仅为已有的
+终端托管配置保留。`RECALL_IMPORT_HISTORY` 可设为 `yes`、`no` 或 `ask`。
 
 ### Windows 一行安装
 
@@ -49,9 +49,10 @@ irm https://raw.githubusercontent.com/wendaining/recall/master/install.ps1 | iex
 
 脚本会下载最新 Release、校验 SHA-256，并把 `recall.exe` 安装到
 `%USERPROFILE%\.local\bin`（可用 `RECALL_INSTALL_DIR` 覆盖），把该目录加入用户
-`PATH`，将 PowerShell 集成追加到 `$PROFILE`，并创建默认 `config.toml`。设置
-`RECALL_NO_MODIFY_PROFILE` 可跳过修改 profile。安装器也会询问是否导入检测到的
-shell 与 atuin 历史；可用 `RECALL_IMPORT_HISTORY=yes|no|ask` 控制。
+`PATH`，为 `$PROFILE` 配置自动输出捕获，并创建默认 `config.toml`。设置
+`RECALL_NO_MODIFY_PROFILE` 可跳过修改 profile，设置 `RECALL_PROXY_SETUP=hooks`
+可只安装 hooks。安装器也会询问是否导入检测到的 shell 与 atuin 历史；可用
+`RECALL_IMPORT_HISTORY=yes|no|ask` 控制。
 
 ### 从源码构建
 
@@ -114,9 +115,28 @@ irm https://raw.githubusercontent.com/wendaining/recall/master/uninstall.ps1 | i
 > 一行安装脚本会自动完成 shell 集成并创建默认配置。下面的手动步骤主要用于源码
 > 构建或自定义安装。
 
-### 1. Shell 集成
+### 1. 统一 Shell 设置
 
-如果是从源码构建，请在对应 shell 的启动文件中加入相应的一行：
+如果是从源码构建，请运行对应 shell 的设置命令：
+
+```sh
+recall setup zsh       # 也可以是 bash、fish、pwsh、powershell
+```
+
+默认会启用自动输出捕获。recall 在启动文件顶部写入一小段托管的代理启动逻辑，
+并在末尾加载集成。外层 shell 会在读取其余配置前交给 PTY 代理；代理中的子 shell
+只加载一次用户配置，并在主题、prompt 和 PSReadLine 就绪后安装 hooks。
+
+如果只需要搜索快捷键和元数据，不希望自动启动代理：
+
+```sh
+recall setup zsh --mode hooks
+```
+
+运行 `recall setup zsh --remove` 只会移除 recall 托管的配置块，用户手写的配置
+保持不变。
+
+`recall init` 仍作为完全手动配置的底层接口：
 
 ```zsh
 # ~/.zshrc
@@ -138,7 +158,7 @@ recall init fish | source
 recall init pwsh | Out-String | Invoke-Expression
 ```
 
-这会安装捕获钩子，以及一个 **Alt+R** 组件：打开 TUI 并把选中的命令插入到提示符。
+集成会安装命令边界钩子，以及一个 **Alt+R** 组件：打开 TUI 并把选中的命令插入到提示符。
 按键由配置里的 `[ui].search_key` 决定，详见下文。
 
 #### 设置快捷键
@@ -176,18 +196,17 @@ Mac 键盘没有 `Alt`，对应的是 `Option`（`⌥`）。recall 同时支持
 
 ### 2. 使用 PTY 代理捕获输出
 
-一行安装脚本会提供两种设置方式。推荐把 recall 配置为终端模拟器的启动命令；如果
-终端没有这项设置，再让安装脚本写入 shell 启动文件。两种方式都会在 recall 的 PTY
-代理中启动你原本使用的 shell，以便保存每条命令对应的终端输出。
+安装脚本和 `recall setup` 会自动在 recall 的 PTY 代理中启动原本使用的 shell，
+无需配置终端模拟器。在启动新 shell 前设置 `RECALL_PROXY=0`，可以跳过自动捕获，
+同时保留搜索和元数据 hooks。
 
-如果安装时选择暂不设置，或使用源码安装，可以手动启动被包裹的 shell：
+在 hooks-only 或完全手动配置中，需要捕获输出时可启动被包裹的 shell：
 
 ```sh
 recall shell
 ```
 
-或配置终端模拟器，把它作为 shell 启动，这样每个新窗口都会自动捕获输出。不同
-模拟器的设置项名称不同（`shell`、`command` 等），例如：
+已有的终端托管配置可以继续直接启动 recall，但这只是兼容用的高级方式：
 
 ```
 # 在你的终端模拟器配置文件中
@@ -207,8 +226,6 @@ Windows 上代理通过 ConPTY 运行 shell。未设置 `proxy.shell` 和 `--she
 它会沿父进程链检测你启动 `recall shell` 时所用的 shell，再依次回退到 `pwsh`、
 `powershell`、`%COMSPEC%`。可用 `--shell` 或 `proxy.shell` 覆盖，例如
 `recall shell --shell cmd`。macOS 专用的 `-l` 登录参数不会在 Windows 上传入。
-要让 Windows Terminal 的每个标签页都自动捕获，可在"设置 → 你的配置文件 →
-命令行"中填入 `recall shell`。
 
 ### 3. 导入已有历史（可选）
 
@@ -242,6 +259,7 @@ recall import atuin --path /path/to/history.db
 
 ```sh
 recall search --cmd-only   # 打印选择结果（供 shell 组件使用）
+recall setup [shell]       # 配置自动捕获和 shell hooks
 recall doctor              # 诊断配置、数据库和剪贴板
 recall prune               # 清理超过保留期的输出
 recall config path|show|default