feat(cli): add opt-in shell-local sp shorthand

docs/cli-reference.md

@@ -104,6 +104,32 @@ are ordinary command errors (JSON when requested, exit 1). No messages are
 submitted in either case. JSON results still describe submission rather than
 receipt; these flags introduce no structured JSON message-input protocol.
 
+## Optional interactive shorthand
+
+For releases containing these assets, Bash/zsh and PowerShell users can opt in to a shell-local alias named `sp`. It invokes the currently selected `session-peer` command with the same arguments, stdin, output, exit codes and permissions. It is not a separate parser or a Python/TypeScript selector. Keep the canonical command in scripts, SSH requests and generated reply instructions. Do not install both implementations simultaneously; switch with the original installation manager and verify which command your shell resolves first.
+
+The wheel and source distribution include passive activation files in `session_peer_shorthand`; installation does not activate them or edit profiles or PATH. Use the Python interpreter belonging to the selected installation to locate a file: an activated pip virtual environment's interpreter, or the interpreter inside the tool environment reported by `pipx environment --value PIPX_LOCAL_VENVS` or `uv tool dir`. On Unix those tool environments normally contain `session-peer/bin/python`; Windows uses `session-peer/Scripts/python.exe`. Inspect the actual environment instead of assuming its location. The module only prints the asset's path; read the file before sourcing it.
+
+```bash
+asset=$("/path/to/tool/python" -I -m session_peer_shorthand bash)
+source "$asset"
+sp --version
+source "${asset%/*}/sp-remove.sh"
+```
+
+```powershell
+$asset = & 'C:\path\to\tool\Scripts\python.exe' -I -m session_peer_shorthand powershell
+. $asset
+sp --version
+. $asset -Remove
+```
+
+Activation refuses an existing `sp` executable, alias or function without replacing it. PowerShell normally already defines `sp` as `Set-ItemProperty`, so activation refuses by default; continue using the canonical command unless you deliberately manage that collision yourself. Bash/zsh must source the file, and PowerShell must dot-source it. These assets do not support cmd.exe. Shell aliases require the shell's normal alias expansion; Bash disables it in non-interactive scripts, which should use the canonical command instead.
+
+Repeated activation of this unchanged owned alias succeeds without further changes. Removal affects only the alias created in the same shell; it refuses if you replaced it with another alias or command. Closing the shell removes the alias. An upgrade through the original manager keeps the alias pointing at the canonical command, not a copied runtime. Remove the alias before uninstalling or switching implementations; uninstall does not modify a running shell. Do not add these files to profiles unless you intentionally take responsibility for persistent setup and removal.
+
+Standalone installation remains unchanged and does not install these files automatically. To use the shorthand with standalone, obtain the files from a reviewed checkout or extract `session_peer_shorthand` from the corresponding verified release source distribution. Follow [release verification](../RELEASING.md) rather than sourcing an unverified download. Source the reviewed local file directly, keeping the canonical command on PATH. Updating or removing this manually selected file is your responsibility; it does not change standalone, pipx, uv or pip ownership. Alias collision detection covers only commands visible to the current shell and PATH, not other shells or future PATH changes.
+
 ## Install
 
 Python 3.9+, standard library only — no external dependencies.

docs/i18n-manifest.json

@@ -15,7 +15,7 @@
     "docs/ai-assistant-guide.md": "9624ec96b92fb688fae3be3c94cb3564c77985091be451fbf1f056a1af9b9d9c",
     "docs/antigravity.md": "f2b5122a0ce6e6fb5bd4d8ed50ce2c8bd2dc9c98ec8ce328405cf7c2cd24229d",
     "docs/architecture/agent-transports.md": "01a4e3942e87acb476595859f2e37f9653ea1e3bc19ebc68dced1adf20a6966f",
-    "docs/cli-reference.md": "a4abf8ca375d058a23b3ae1d91698f95c77e59f0ebd98f623da26461e6b3e08b",
+    "docs/cli-reference.md": "165c11eaa44db400f426c3a5dbec64b1392b548274dccafaac093ebc27ec70f6",
     "docs/compatibility-v1.md": "7e551aad37a369faff7e370728376763efb54c2c9e9cfd8556a0c19aabc3d103",
     "docs/contracts/handoff-v1.md": "46a953010c49214bd8f969412f26713384fbe09a0ba78ebf0fef75da40d0d889",
     "docs/diagnostics.md": "0949e53612eeab2cd7c7bbda498e14d71e9cb1b1189aa7722030cb8702cd8481",

docs/ja/cli-reference.md

@@ -103,6 +103,32 @@ session-peer list --output-format json
 これらのフラグによって構造化された JSON メッセージ入力プロトコルが導入されるわけではありません。
 
 <a id="install"></a>
+## 任意の対話型短縮コマンド
+
+これらのファイルを含むリリースでは、Bash/zsh と PowerShell で現在のシェルだけに有効な `sp` エイリアスを任意で利用できます。現在選択されている `session-peer` コマンドに同じ引数と標準入力を渡し、出力、終了コード、権限も変えません。別の引数解析器や Python/TypeScript の選択器ではありません。スクリプト、SSH リクエスト、自動生成される返信手順では正式なコマンドを使ってください。両実装を同時にインストールせず、元のインストール管理ツールで切り替え、シェルがどのコマンドを先に選ぶか確認してください。
+
+wheel とソース配布物には `session_peer_shorthand` 内に有効化ファイルが含まれます。インストールだけでは有効化されず、プロファイルや PATH も変更しません。選択したインストールの Python インタープリターでファイルを探してください。pip の有効な仮想環境、または `pipx environment --value PIPX_LOCAL_VENVS` や `uv tool dir` で確認したツール環境のインタープリターを使います。通常、Unix のツール環境には `session-peer/bin/python`、Windows には `session-peer/Scripts/python.exe` があります。場所を決めつけず実際の環境を確認してください。モジュールはファイルのパスだけを出力します。シェルで読み込む前に内容を確認してください。
+
+```bash
+asset=$("/path/to/tool/python" -I -m session_peer_shorthand bash)
+source "$asset"
+sp --version
+source "${asset%/*}/sp-remove.sh"
+```
+
+```powershell
+$asset = & 'C:\path\to\tool\Scripts\python.exe' -I -m session_peer_shorthand powershell
+. $asset
+sp --version
+. $asset -Remove
+```
+
+既に `sp` という実行ファイル、エイリアス、関数がある場合は上書きせず有効化を拒否します。PowerShell は通常 `sp` を `Set-ItemProperty` のエイリアスとして定義するため、既定では有効化できません。競合を自分で管理すると決めない限り、正式なコマンドを使い続けてください。Bash/zsh では source、PowerShell では dot-source で読み込む必要があります。cmd.exe は対応していません。エイリアスはシェルの通常の展開規則に従います。Bash の非対話型スクリプトでは既定で展開が無効なため、正式なコマンドを使ってください。
+
+この方式で作成したエイリアスを変更していなければ、繰り返し有効化しても追加変更なく成功します。削除は同じシェルで作成したエイリアスにだけ作用し、別のエイリアスやコマンドに変更されていれば拒否します。シェルを閉じるとエイリアスも消えます。元の管理ツールで更新した後も、コピーしたランタイムではなく正式なコマンドを参照します。アンインストールや実装の切り替え前にエイリアスを削除してください。パッケージの削除は実行中のシェルを変更しません。永続設定と削除を自分で管理する場合以外は、プロファイルに追加しないでください。
+
+standalone のインストールは変更されず、これらのファイルも自動で配置しません。standalone と併用する場合は、確認済みのチェックアウトからファイルを取得するか、対応するリリースの検証済みソース配布物から `session_peer_shorthand` を展開してください。未検証のダウンロードを直接読み込まず、[リリースの検証](../../RELEASING.ja.md)に従ってください。正式なコマンドを PATH で見つけられる状態にして、確認したローカルファイルを直接読み込みます。手動で選択したファイルの更新と削除は利用者の責任であり、standalone、pipx、uv、pip の管理主体は変わりません。競合検査は現在のシェルと PATH から見えるコマンドだけを対象とし、別のシェルや今後の PATH 変更は確認しません。
+
 ## インストール
 
 Python 3.9 以上、標準ライブラリのみ — 外部依存関係はありません。

docs/ko/cli-reference.md

@@ -103,6 +103,32 @@ session-peer list --output-format json
 않습니다.
 
 <a id="install"></a>
+## 선택적 대화형 단축 명령
+
+이 파일이 포함된 릴리스에서는 Bash/zsh와 PowerShell에서 현재 셸에만 적용되는 `sp` 별칭을 선택적으로 사용할 수 있습니다. 현재 선택된 `session-peer` 명령에 인자와 표준 입력을 그대로 전달하며 출력, 종료 코드, 권한도 동일합니다. 별도의 인자 해석기나 Python/TypeScript 선택기가 아닙니다. 스크립트, SSH 요청, 자동 생성 회신 안내에는 정식 명령을 사용하세요. 두 구현을 동시에 설치하지 마세요. 기존 설치 관리자로 구현을 교체하고 셸에서 어떤 명령이 먼저 선택되는지 확인하세요.
+
+wheel과 소스 배포 파일의 `session_peer_shorthand`에 활성화 파일이 포함됩니다. 설치만으로 활성화되거나 프로필과 PATH가 바뀌지는 않습니다. 선택한 설치본의 Python 인터프리터로 파일 경로를 확인하세요. 활성화한 pip 가상 환경의 인터프리터 또는 `pipx environment --value PIPX_LOCAL_VENVS`나 `uv tool dir`에서 확인한 도구 환경의 인터프리터를 사용합니다. 일반적으로 Unix 도구 환경에는 `session-peer/bin/python`, Windows에는 `session-peer/Scripts/python.exe`가 있습니다. 경로를 추측하지 말고 실제 환경을 확인하세요. 모듈은 파일 경로만 출력합니다. 셸에서 읽어 실행하기 전에 파일을 검토하세요.
+
+```bash
+asset=$("/path/to/tool/python" -I -m session_peer_shorthand bash)
+source "$asset"
+sp --version
+source "${asset%/*}/sp-remove.sh"
+```
+
+```powershell
+$asset = & 'C:\path\to\tool\Scripts\python.exe' -I -m session_peer_shorthand powershell
+. $asset
+sp --version
+. $asset -Remove
+```
+
+이미 `sp` 실행 파일, 별칭 또는 함수가 있으면 덮어쓰지 않고 활성화를 거부합니다. PowerShell은 보통 `sp`를 `Set-ItemProperty`의 별칭으로 정의하므로 기본적으로 활성화가 거부됩니다. 충돌을 직접 관리하기로 결정하지 않았다면 정식 명령을 계속 사용하세요. Bash/zsh에서는 source로, PowerShell에서는 dot-source로 파일을 읽어야 합니다. cmd.exe는 지원하지 않습니다. 별칭은 셸의 일반적인 별칭 확장 규칙을 따릅니다. Bash의 비대화형 스크립트는 기본적으로 별칭 확장을 끄므로 정식 명령을 사용해야 합니다.
+
+이 방식으로 만든 별칭이 변경되지 않았다면 반복 활성화해도 추가 변경 없이 성공합니다. 제거는 같은 셸에서 생성한 별칭에만 적용되며, 다른 별칭이나 명령으로 바꾸었다면 거부합니다. 셸을 닫으면 별칭도 사라집니다. 기존 설치 관리자로 업데이트하면 별칭은 복사된 실행본이 아니라 정식 명령을 계속 가리킵니다. 제거하거나 구현을 교체하기 전에 별칭을 먼저 제거하세요. 패키지 제거는 실행 중인 셸을 바꾸지 않습니다. 영구 설정과 제거를 직접 관리할 의사가 없다면 프로필에 이 파일을 추가하지 마세요.
+
+standalone 설치 방식은 바뀌지 않으며 이 파일들을 자동 설치하지 않습니다. standalone과 함께 쓰려면 검토한 체크아웃에서 파일을 가져오거나 해당 릴리스의 검증된 소스 배포 파일에서 `session_peer_shorthand`를 추출하세요. 검증되지 않은 다운로드를 바로 실행하지 말고 [릴리스 검증](../../RELEASING.ko.md) 절차를 따르세요. PATH에서 정식 명령을 찾을 수 있게 한 뒤 검토한 로컬 파일을 직접 읽으세요. 직접 선택한 파일의 업데이트와 제거는 사용자의 책임이며 standalone, pipx, uv, pip의 관리 주체는 바뀌지 않습니다. 충돌 검사는 현재 셸과 PATH에 보이는 명령만 확인하며 다른 셸이나 향후 PATH 변경까지 확인하지 않습니다.
+
 ## 설치
 
 Python 3.9+, 표준 라이브러리 전용 — 외부 의존성 없음.

docs/zh-CN/cli-reference.md

@@ -62,6 +62,32 @@ session-peer list --output-format json
 `--json --output-format json` 是合法的；无论先后顺序，将 `--json` 与 `--output-format text` 组合都会报错。无效或矛盾的输出选项属于 argparse 用法错误（stderr，退出码 2）；消息来源冲突属于普通命令错误（请求时为 JSON，退出码 1）。无论哪种情况均不会提交任何消息。JSON 结果仍然描述提交情况而非接收情况；这些标志并未引入结构化的 JSON 消息输入协议。
 
 <a id="install"></a>
+## 可选的交互式短命令
+
+在包含这些文件的版本中，Bash/zsh 和 PowerShell 用户可以自行启用仅在当前 shell 生效的 `sp` 别名。它调用当前选中的 `session-peer` 命令，保持参数、标准输入、输出、退出码和权限不变。它不是独立的参数解析器，也不是 Python/TypeScript 选择器。脚本、SSH 请求和自动生成的回复指令仍应使用正式命令。不要同时安装两个实现；切换时使用原安装管理工具，并确认 shell 优先找到哪个命令。
+
+wheel 和源码发行包在 `session_peer_shorthand` 中包含启用脚本。安装不会自动启用，也不会修改配置文件或 PATH。请使用所选安装对应的 Python 解释器定位文件：已激活的 pip 虚拟环境解释器，或通过 `pipx environment --value PIPX_LOCAL_VENVS`、`uv tool dir` 查到的工具环境解释器。Unix 工具环境通常包含 `session-peer/bin/python`，Windows 使用 `session-peer/Scripts/python.exe`。请查看实际环境，不要猜测位置。模块只输出文件路径；在 shell 中加载前请先审阅文件。
+
+```bash
+asset=$("/path/to/tool/python" -I -m session_peer_shorthand bash)
+source "$asset"
+sp --version
+source "${asset%/*}/sp-remove.sh"
+```
+
+```powershell
+$asset = & 'C:\path\to\tool\Scripts\python.exe' -I -m session_peer_shorthand powershell
+. $asset
+sp --version
+. $asset -Remove
+```
+
+如果已有 `sp` 可执行文件、别名或函数，脚本会拒绝启用而不会覆盖。PowerShell 通常已将 `sp` 定义为 `Set-ItemProperty` 的别名，因此默认会拒绝启用；除非您明确决定自行处理冲突，否则请继续使用正式命令。Bash/zsh 必须通过 source 加载，PowerShell 必须通过 dot-source 加载。不支持 cmd.exe。别名遵循 shell 的正常展开规则；Bash 在非交互脚本中默认关闭别名展开，因此脚本应使用正式命令。
+
+如果此方式创建的别名没有被修改，重复启用会成功且不产生额外变更。移除操作只针对同一 shell 中创建的别名；若已被替换成其他别名或命令，则拒绝移除。关闭 shell 也会清除别名。通过原管理工具升级后，别名仍指向正式命令，而非复制的运行时。在卸载或切换实现前请先移除别名；包卸载不会修改正在运行的 shell。除非您愿意自行负责持久配置及其移除，否则不要把这些文件加入 shell 配置文件。
+
+standalone 安装方式不变，不会自动安装这些文件。如果要搭配 standalone 使用，请从已审阅的检出目录取得文件，或从对应版本经过验证的源码发行包提取 `session_peer_shorthand`。遵循[发行验证](../../RELEASING.zh-CN.md)流程，不要直接加载未经验证的下载。确保 PATH 能找到正式命令，再直接加载审阅后的本地文件。手动选择文件的更新和移除由您负责，不会改变 standalone、pipx、uv 或 pip 的管理归属。冲突检查仅覆盖当前 shell 和 PATH 中可见的命令，不覆盖其他 shell 或将来的 PATH 变更。
+
 ## 安装
 
 Python 3.9+，仅限标准库 —— 无外部依赖。

pyproject.toml

@@ -54,6 +54,7 @@ include = [
     "/.gitattributes",
     "/session_peer_core",
     "/session_peer_relay",
+    "/session_peer_shorthand",
     "/session_peer.py",
     "/session_peer_mcp.py",
     "/tools/generate_session_peer.py",
@@ -71,4 +72,4 @@ include = [
 ]
 
 [tool.hatch.build.targets.wheel]
-only-include = ["session_peer_relay", "session_peer.py", "session_peer_mcp.py"]
+only-include = ["session_peer_relay", "session_peer_shorthand", "session_peer.py", "session_peer_mcp.py"]

session_peer_shorthand/__init__.py

@@ -0,0 +1 @@
+"""Passive, opt-in interactive shell assets; no installation side effects."""

session_peer_shorthand/__main__.py

@@ -0,0 +1,16 @@
+"""Locate an activation asset using this installation's Python interpreter."""
+
+import argparse
+from pathlib import Path
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("shell", choices=("bash", "powershell"))
+    args = parser.parse_args()
+    filename = "sp.sh" if args.shell == "bash" else "sp.ps1"
+    print(Path(__file__).resolve().with_name(filename))
+
+
+if __name__ == "__main__":
+    main()

session_peer_shorthand/sp-remove.sh

@@ -0,0 +1,32 @@
+# Source in the same Bash/zsh scope to remove only our unchanged owned alias.
+# A separate file avoids interpreting inherited caller positional arguments.
+if [ -n "${BASH_VERSION-}" ]; then
+    if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+        printf '%s\n' 'Source sp-remove.sh in Bash or zsh.' >&2
+        exit 1
+    fi
+elif [ -n "${ZSH_VERSION-}" ]; then
+    case "$ZSH_EVAL_CONTEXT" in
+        *:file) ;;
+        *) printf '%s\n' 'Source sp-remove.sh in Bash or zsh.' >&2; exit 1 ;;
+    esac
+else
+    printf '%s\n' 'sp-remove.sh supports Bash and zsh only.' >&2
+    # The exit fallback is needed when an unsupported shell executes the file.
+    # shellcheck disable=SC2317
+    return 1 2>/dev/null || exit 1
+fi
+if [ "${_SESSION_PEER_SP_OWNED-}" = 1 ]; then
+    case "$(alias sp 2>/dev/null)" in
+        "alias sp='session-peer'"|"sp=session-peer")
+            unalias sp
+            unset _SESSION_PEER_SP_OWNED
+            return 0
+            ;;
+    esac
+fi
+if command -v sp >/dev/null 2>&1; then
+    printf '%s\n' 'sp was not created by this activation or has changed. Nothing was removed.' >&2
+    return 1
+fi
+unset _SESSION_PEER_SP_OWNED