@ictechgy/lterm 1.0.1 → 1.0.3

package/README.ko.md

@@ -5,8 +5,8 @@
 ## TL;DR
 
 - **무엇** — tmux 같은 영속 터미널 세션 데몬을 더 작게 만든 도구. AI 에이전트 도구를 위한 tmux 호환 명령 계층을 제공하며, 세션을 이름이나 pane id로 detach·reattach할 수 있습니다.
-- **대상** — Claude Code, Codex CLI, Gemini CLI, `oh-my-codex` / `oh-my-claude` 같은 terminal-first coding agent를 쓰는 사용자와, 이를 `cmux` 안에서 실행하는 사용자.
-- **사용법** — `lterm start`로 만들고 `lterm resume`으로 (재)접속, shim이 적용된 agent 실행에는 `lterm agent <profile>` / `lterm claude` / `lterm codex` / `lterm gemini`. tmux가 켜진 세션 안에서는 `tmux` 명령이 `lterm tmux-compat`으로 해석됩니다.
+- **대상** — Claude Code, Codex CLI, OpenCode, GitHub Copilot CLI, Cursor Agent, Antigravity/`agy`, Kiro, Jules, Aider, Goose, Amp, Crush, Kimi, Qwen, Gemini CLI, `oh-my-codex` / `oh-my-claude` 같은 terminal-first coding agent를 쓰는 사용자와, 이를 `cmux` 안에서 실행하는 사용자.
+- **사용법** — `lterm start`로 만들고 `lterm resume`으로 (재)접속, shim이 적용된 agent 실행에는 `lterm agent <profile>` / `lterm claude` / `lterm codex` / `lterm opencode` / `lterm agy` / `lterm kiro` / `lterm gemini` 등 built-in shortcut입니다. tmux가 켜진 세션 안에서는 `tmux` 명령이 `lterm tmux-compat`으로 해석됩니다.
 - **상태** — alpha MVP. 같은 OS 사용자 안에서 쓰는 편의용 데몬이며, **샌드박스, escape-sequence sanitizer, 완전한 tmux 대체품 모두 아닙니다.**
 
 ---
@@ -15,6 +15,7 @@
 
 > **보안 모델:** `lterm`은 같은 OS 사용자 안에서 쓰는 편의용 데몬이며 샌드박스가 아닙니다. 다른 사용자의 Unix socket 접근은 거부하고 런타임 디렉터리는 소유자 전용 권한으로 만들지만, 같은 OS 사용자 권한으로 실행되는 프로세스는 세션을 제어할 수 있다고 보아야 합니다.
 > 전체 trust boundary와 audit policy는 [SECURITY.md](SECURITY.md)를 참고하세요.
+> Non-goals(의도적으로 지원하지 않는 항목)는 [docs/non-goals.md](docs/non-goals.md)를 참고하세요.
 
 ## 왜 tmux 대신 lterm인가요?
 
@@ -25,7 +26,7 @@ agent가 보통 필요로 하는 더 작은 표면에 집중합니다.
   계속 실행되므로, 모든 workflow가 full tmux server를 직접 관리할 필요가
   적습니다.
 - **Agent가 기대하는 tmux 호환성** — `lterm tmux-compat`는 Claude Code, Codex
-  CLI, Gemini CLI, OMX/OMC 같은 terminal-first tooling이 쓰는 tmux command
+  CLI, OpenCode, GitHub Copilot CLI, Cursor Agent, Antigravity/`agy`, Kiro, Jules, Aider, Goose, Amp, Crush, Kimi, Qwen, Gemini CLI, OMX/OMC 같은 terminal-first tooling이 쓰는 tmux command
   subset을 구현합니다.
 - **Raw attach, safe reports** — attach된 PTY stream은 TUI/interactive shell을
   위해 raw로 유지하고, `logs`, `capture`, `list`, `doctor` 같은 report surface는
@@ -42,7 +43,7 @@ agent가 보통 필요로 하는 더 작은 표면에 집중합니다.
 
 1. **tmux와 비슷한 세션 지속성과 원격 접속** — 세션은 백그라운드 데몬에서 실행되며, 이름이나 pane id로 attach/detach할 수 있습니다. 원격 호스트에 `lterm`이 설치되어 있다면 `lterm ssh`로 접속할 수 있습니다.
 2. **cmux 호환성** — cmux 안에서 실행할 때는 OSC 알림을 그대로 통과시키고 `lterm notify`를 제공하며, tmux shim은 가능한 경우 worker pane을 cmux native split으로 엽니다.
-3. **AI 도구 지원** — `lterm agent <profile>`, `lterm claude`, `lterm codex`, `lterm gemini`, `lterm omx`, `lterm omc`, `lterm install-shim`은 tmux를 전제하는 agent 도구를 위해 가짜 `tmux` 명령과 `TMUX` / `TMUX_PANE` 환경 변수를 제공합니다.
+3. **AI 도구 지원** — `lterm agent <profile>`, `lterm claude`, `lterm codex`, `lterm opencode`, `lterm copilot`, `lterm cursor-agent`, `lterm agy`, `lterm jules`, `lterm kiro`, `lterm aider`, `lterm goose`, `lterm amp`, `lterm crush`, `lterm kimi`, `lterm qwen`, `lterm gemini`, `lterm omx`, `lterm omc`, `lterm install-shim`은 tmux를 전제하는 agent 도구를 위해 가짜 `tmux` 명령과 `TMUX` / `TMUX_PANE` 환경 변수를 제공합니다.
 
 cmux 호환 동작은 cmux가 문서화한 기능을 따릅니다. cmux는 `cmux notify`와 OSC 777 / OSC 99 알림, workspace/split을 위한 Unix socket·CLI API, 그리고 tmux 명령을 cmux native pane으로 매핑하는 tmux shim 모델을 문서화하고 있습니다.
 
@@ -63,14 +64,14 @@ npm install -g @ictechgy/lterm
 Homebrew와 npm 모두 `PATH`에 `lterm` 명령을 설치합니다. `lterm --version`으로 확인하세요.
 
 수동 설치도 귀찮다면 [`docs/agent-install.ko.md`](docs/agent-install.ko.md)의
-프롬프트를 Claude Code, Codex CLI, Gemini CLI 같은 terminal coding agent에
+프롬프트를 Claude Code, Codex CLI, OpenCode, GitHub Copilot CLI, Cursor Agent, Antigravity/`agy`, Kiro, Jules, Aider, Goose, Amp, Crush, Kimi, Qwen, Gemini CLI 같은 terminal coding agent에
 붙여 넣으세요. Agent가 platform을 감지하고, `lterm`을 설치하고, smoke test로
 검증하며, shell startup file을 바꿔야 할 때는 먼저 diff를 보여주도록 안내합니다.
 
 GitHub에서 Cargo로 설치 (Releases 페이지의 최신 태그를 사용하세요):
 
 ```bash
-cargo install --git https://github.com/ictechgy/light_terminal --tag v1.0.1
+cargo install --git https://github.com/ictechgy/light_terminal --tag v1.0.3
 ```
 
 저장소를 클론한 뒤 직접 빌드하려면 Rust 1.85 이상이 필요합니다.
@@ -141,7 +142,7 @@ lterm -a api
 
 | 작업 | 제품 명령 | 호환 경계 |
 | --- | --- | --- |
-| profile 기반 agent 세션 실행 | `lterm agent claude -- --help` | sibling shortcuts: `lterm claude`, `lterm codex`, `lterm gemini`, `lterm omx`, `lterm omc` |
+| profile 기반 agent 세션 실행 | `lterm agent claude -- --help` | sibling shortcuts: `lterm claude`, `lterm codex`, `lterm opencode`, `lterm copilot`, `lterm cursor-agent`, `lterm agy`, `lterm jules`, `lterm kiro`, `lterm aider`, `lterm goose`, `lterm amp`, `lterm crush`, `lterm kimi`, `lterm qwen`, `lterm gemini`, `lterm omx`, `lterm omc` |
 | 사용 가능한 agent profile 확인 | `lterm agents --json` | 실행 시점의 `PATH` 사용 가능 여부 확인 |
 | `tmux` 호환 shim 설치 | `lterm install-shim` | `lterm tmux-compat`으로 전달하는 shim 생성 |
 | tmux 호환 shell export 출력 | `eval "$(lterm env)"` | shim dir을 `$PATH` 앞에 추가하는 신뢰된 `export` 행 출력 |
@@ -270,7 +271,19 @@ lterm shutdown
 ```bash
 lterm claude
 lterm codex
-lterm gemini -- -p "이 저장소를 요약해줘"
+lterm opencode
+lterm copilot
+lterm cursor-agent
+lterm agy -- -p "이 저장소를 요약해줘"
+lterm kiro
+lterm jules
+lterm aider
+lterm goose
+lterm amp
+lterm crush
+lterm kimi
+lterm qwen
+lterm gemini -- -p "이 저장소를 요약해줘"  # legacy 호환
 lterm agents
 ```
 
@@ -279,6 +292,10 @@ lterm agents
 ```bash
 lterm agent claude
 lterm agent codex
+lterm agent opencode
+lterm agent cursor-agent
+lterm agent agy -- -p "이 저장소를 요약해줘"
+lterm agent qwen
 lterm agent gemini -- -p "이 저장소를 요약해줘"
 ```
 
@@ -287,16 +304,16 @@ agent launcher는 built-in profile과 custom `lterm agent <profile>` 실행에
 ```bash
 lterm claude --name repo-review --cwd /path/to/repo
 lterm codex --detach --name repo-codex -- exec "이 저장소를 요약해줘"
-lterm gemini --status -- -p "lterm status를 유지해줘"
+lterm agy --status -- -p "lterm status를 유지해줘"
 ```
 
-Claude/Codex/Gemini profile은 각 도구의 자체 TUI/status/alternate-screen 렌더링과 충돌하지 않도록 기본적으로 lterm status bar를 끈 raw full-terminal attach를 사용합니다. `--status`로 lterm status bar를 강제로 켜거나, 기본값이 켜진 profile에서는 `--no-status`로 끌 수 있습니다. agent에 넘길 인자가 lterm launch option처럼 보일 수 있으면 앞에 `--`를 두세요. 직접 generic tmux-compatible primitive를 쓰거나 아직 profile이 없는 미래 agent를 실행하려면 `lterm run -- <command>`를 사용하세요. `run`은 shim을 기본으로 켜며 `--no-tmux`로 끌 수 있습니다.
+Claude/Codex/OpenCode/Copilot/Cursor Agent/Antigravity/Kiro/Jules/Aider/Goose/Amp/Crush/Kimi/Qwen/Gemini/OMX/OMC profile은 각 도구의 자체 TUI/status/alternate-screen 렌더링과 충돌하지 않도록 기본적으로 lterm status bar를 끈 raw full-terminal attach를 사용합니다. `--status`로 lterm status bar를 강제로 켜거나, status bar가 표시되는 launch/profile에서는 `--no-status`로 숨길 수 있습니다. agent에 넘길 인자가 lterm launch option처럼 보일 수 있으면 앞에 `--`를 두세요. `lterm agent <name>`은 `PATH`에서 찾을 수 있는 안전한 bare command name이면 바로 동작하므로, 예를 들어 `lterm agent qwen-code`처럼 미래/서드파티 agent도 쓸 수 있습니다. `lterm run -- <command>`는 더 낮은 수준의 tmux-compatible primitive를 직접 쓰고 싶을 때만 사용하세요.
 
-launcher 제어 옵션은 agent의 흔한 short flag(`-c` 등)를 빼앗지 않도록 long-only(`--name`, `--cwd`, `--detach`, `--status`, `--no-status`, `--status-theme`)입니다. 이 옵션들은 `claude`, `codex`, `gemini`, `omx`, `omc`, `agent <profile>`에 동일하게 적용됩니다. 해당 agent 세션이 이후 attach에서도 특정 lterm status 색을 유지하게 하려면 `--status-theme` / `--status-color`를 사용하세요.
+launcher 제어 옵션은 agent의 흔한 short flag(`-c` 등)를 빼앗지 않도록 long-only(`--name`, `--cwd`, `--detach`, `--status`, `--no-status`, `--status-theme`)입니다. 이 옵션들은 `claude`, `codex`, `opencode`, `copilot`, `cursor-agent`, `agy`, `kiro`, `jules`, `aider`, `goose`, `amp`, `crush`, `kimi`, `qwen`, `gemini`, `omx`, `omc`, `agent <profile>`에 동일하게 적용됩니다. 해당 agent 세션이 이후 attach에서도 특정 lterm status 색을 유지하게 하려면 `--status-theme` / `--status-color`를 사용하세요.
 `--detach`는 각 field의 control character와 Unicode line/paragraph separator를 공백으로 바꾼 `name<TAB>pane<TAB>command`를 출력하며, 나중에 `lterm resume <name>` 또는 호환 이름 `lterm attach <name>`으로 다시 붙으면 됩니다. detach record에는 `--cwd`가 포함되지 않으므로 나중에 필요하면 session을 조회하세요.
 명시한 `--name`은 lterm의 일반 session-name 문법을 따르고 사용 중이지 않아야 합니다. 충돌 시 자동 suffix를 붙이지 않고 conflict error로 실패합니다.
 이름에는 ASCII 문자/숫자와 `.`, `_`, `-`만 사용할 수 있고, `-` 또는 `%`로 시작할 수 없으며, 숫자만으로 이뤄질 수 없고, UUID처럼 보이면 안 되고, 128바이트를 넘을 수 없습니다.
-`lterm agents` 또는 `lterm agents --json`으로 profile 기본값과 현재 `PATH`에서 binary를 찾을 수 있는지 확인할 수 있습니다. JSON row의 `kind` 값은 `built-in`, `custom`, `configured` 중 하나입니다. `lterm agents codex my-agent --json`처럼 profile 이름을 넘기면 선택한 built-in/custom/configured profile만 확인합니다. availability는 실행 시점의 PATH probe입니다.
+`lterm agents` 또는 `lterm agents --json`으로 profile 기본값과 현재 `PATH`에서 binary를 찾을 수 있는지 확인할 수 있습니다. JSON row의 `kind` 값은 `built-in`, `custom`, `configured` 중 하나입니다. `lterm agents codex my-agent --json`처럼 profile 이름을 넘기면 선택한 built-in/custom/configured profile만 확인합니다. availability는 실행 시점의 PATH probe입니다. Built-in은 `lterm agents`에 표시되는 binary 이름을 그대로 `PATH`에서 찾습니다. 대부분 profile 이름과 같지만 `kiro`는 `kiro-cli`를 사용합니다. provider가 다른 command 이름으로 설치된다면 추측 alias에 의존하지 말고 `lterm agent <command>`나 configured profile을 사용하세요.
 반복해서 쓰는 custom alias는 명시적인 JSON config 파일로 넘길 수 있습니다.
 
 ```bash

package/README.md

@@ -5,8 +5,8 @@
 ## TL;DR
 
 - **What** — A persistent terminal session daemon (like tmux, but smaller) with a tmux-compatible command layer for AI agent tooling. Detach and reattach by name or pane id.
-- **Who it's for** — Terminal-first coding agents such as Claude Code, Codex CLI, Gemini CLI, `oh-my-codex` / `oh-my-claude`, and users running them inside `cmux`.
-- **How** — `lterm start` to create, `lterm resume` to (re)connect, `lterm agent <profile>` / `lterm claude` / `lterm codex` / `lterm gemini` for shimmed agent runs. Inside a tmux-enabled session, the `tmux` command resolves to `lterm tmux-compat`.
+- **Who it's for** — Terminal-first coding agents such as Claude Code, Codex CLI, OpenCode, GitHub Copilot CLI, Cursor Agent, Antigravity/`agy`, Kiro, Jules, Aider, Goose, Amp, Crush, Kimi, Qwen, Gemini CLI, `oh-my-codex` / `oh-my-claude`, and users running them inside `cmux`.
+- **How** — `lterm start` to create, `lterm resume` to (re)connect, `lterm agent <profile>` / `lterm claude` / `lterm codex` / `lterm opencode` / `lterm agy` / `lterm kiro` / `lterm gemini` and other built-in shortcuts for shimmed agent runs. Inside a tmux-enabled session, the `tmux` command resolves to `lterm tmux-compat`.
 - **Status** — alpha MVP. A same-user convenience daemon — **not** a sandbox, an escape-sequence sanitizer, or a full tmux replacement.
 
 ---
@@ -15,6 +15,7 @@
 
 > **Security model:** `lterm` is a same-user convenience daemon, not a sandbox. It rejects cross-user Unix-socket peers and uses owner-only runtime directories, but any process running as your OS user should be considered capable of controlling your sessions.
 > See [SECURITY.md](SECURITY.md) for the full trust-boundary and audit policy details.
+> Non-goals: see [docs/non-goals.md](docs/non-goals.md).
 
 ## Why lterm instead of plain tmux?
 
@@ -25,8 +26,9 @@ need:
 - **Agent-first persistence** — named PTY sessions keep running across detached
   clients without requiring every workflow to manage a full tmux server.
 - **tmux-compatible where agents expect it** — `lterm tmux-compat` implements
-  the command subset used by Claude Code, Codex CLI, Gemini CLI, OMX/OMC, and
-  similar terminal-first tooling.
+  the command subset used by Claude Code, Codex CLI, OpenCode, GitHub Copilot
+  CLI, Cursor Agent, Antigravity/`agy`, Kiro, Jules, Aider, Goose, Amp,
+  Crush, Kimi, Qwen, Gemini CLI, OMX/OMC, and similar terminal-first tooling.
 - **Raw attach, safe reports** — attached PTY streams remain raw for TUIs and
   interactive shells, while `logs`, `capture`, `list`, `doctor`, and other
   report surfaces sanitize terminal control sequences before printing.
@@ -42,7 +44,7 @@ The project addresses three constraints:
 
 1. **tmux-like persistence and remote access** — sessions run inside a background daemon and can be attached or detached by name or pane id. Remote access is available through `lterm ssh`, provided `lterm` is installed on the remote host.
 2. **cmux compatibility** — when running inside cmux, `lterm` preserves OSC notifications, exposes `lterm notify`, and the tmux shim opens worker panes as native cmux splits when possible.
-3. **AI tooling support** — `lterm agent <profile>`, `lterm claude`, `lterm codex`, `lterm gemini`, `lterm omx`, `lterm omc`, and `lterm install-shim` provide a fake `tmux` command and the `TMUX` / `TMUX_PANE` environment variables that agent tools expect.
+3. **AI tooling support** — `lterm agent <profile>`, `lterm claude`, `lterm codex`, `lterm opencode`, `lterm copilot`, `lterm cursor-agent`, `lterm agy`, `lterm jules`, `lterm kiro`, `lterm aider`, `lterm goose`, `lterm amp`, `lterm crush`, `lterm kimi`, `lterm qwen`, `lterm gemini`, `lterm omx`, `lterm omc`, and `lterm install-shim` provide a fake `tmux` command and the `TMUX` / `TMUX_PANE` environment variables that agent tools expect.
 
 cmux compatibility is grounded in cmux's documented behavior: notifications via `cmux notify` and OSC 777 / OSC 99, a Unix-socket/CLI API for workspaces and splits, and a tmux shim that maps tmux commands into native cmux panes.
 
@@ -64,7 +66,7 @@ Homebrew and npm both install the `lterm` command on your `PATH`; verify with `l
 
 Too lazy to install it manually? Copy the prompt in
 [`docs/agent-install.md`](docs/agent-install.md) into Claude Code, Codex CLI,
-Gemini CLI, or another terminal coding agent. It asks the agent to detect your
+OpenCode, GitHub Copilot CLI, Cursor Agent, Antigravity/`agy`, Kiro, Jules, Aider, Goose, Amp, Crush, Kimi, Qwen, Gemini CLI, or another terminal coding agent. It asks the agent to detect your
 platform, install `lterm`, verify it with a smoke test, and avoid modifying
 shell startup files without showing you the change.
 
@@ -75,7 +77,7 @@ For the 1.0 command/output stability boundary, see the
 With Cargo from GitHub (use the latest tag from the Releases page):
 
 ```bash
-cargo install --git https://github.com/ictechgy/light_terminal --tag v1.0.1
+cargo install --git https://github.com/ictechgy/light_terminal --tag v1.0.3
 ```
 
 From this checkout, use Rust 1.85 or newer:
@@ -97,10 +99,14 @@ To expose the tmux shim:
 lterm install-shim
 # Add the printed directory to PATH ahead of the real tmux, or eval the helper:
 eval "$(lterm env)"
+# fish:
+lterm env --shell fish | source
 ```
 
 ## Quick start
 
+![lterm quick demo](docs/assets/lterm-demo.svg)
+
 **Create a persistent session and attach immediately:**
 
 ```bash
@@ -139,6 +145,7 @@ lterm -a api
 | Write input to a PTY | `lterm input api 'echo hello' --enter` | `send` |
 | Stop a session | `lterm close api` | `kill` |
 | Diagnose daemon and shim state | `lterm doctor --json` | `status` |
+| Preview local setup steps | `lterm init --shell zsh` | None |
 | Run the background daemon explicitly | `lterm daemon` | None |
 | Stop the daemon and all sessions | `lterm shutdown` | None |
 
@@ -146,16 +153,17 @@ Agent and shim utilities are also product CLI commands, not tmux aliases:
 
 | Task | Product command | Compatibility boundary |
 | --- | --- | --- |
-| Launch a profiled agent session | `lterm agent claude -- --help` | Sibling shortcuts: `lterm claude`, `lterm codex`, `lterm gemini`, `lterm omx`, `lterm omc` |
+| Launch a profiled agent session | `lterm agent claude -- --help` | Sibling shortcuts: `lterm claude`, `lterm codex`, `lterm opencode`, `lterm copilot`, `lterm cursor-agent`, `lterm agy`, `lterm jules`, `lterm kiro`, `lterm aider`, `lterm goose`, `lterm amp`, `lterm crush`, `lterm kimi`, `lterm qwen`, `lterm gemini`, `lterm omx`, `lterm omc` |
 | Inspect available agent profiles | `lterm agents --json` | PATH availability probe at command runtime |
 | Install the `tmux` compatibility shim | `lterm install-shim` | Creates a shim that forwards to `lterm tmux-compat` |
-| Print shell exports for tmux compatibility | `eval "$(lterm env)"` | Emits trusted `export` lines that prepend the shim dir to `$PATH` |
+| Print shell exports for tmux compatibility | `eval "$(lterm env)"` (`lterm env --shell fish \| source` for fish) | Emits trusted shell setup that prepends the shim dir to `$PATH` |
 | Send a cmux-friendly notification | `lterm notify --title 'Done' --body 'Tests passed'` | OSC 777 fallback strips terminal controls while preserving Unicode text |
 | Attach to a remote host | `lterm ssh user@host main` | Use trusted hosts; SSH handles host-key checks, and remote PTY bytes pass through without sanitization |
 | Call the tmux shim namespace directly | `lterm tmux-compat list-commands` | Compatibility namespace, not a product alias table |
 
 Use `eval "$(lterm env)"` only when you trust the `lterm` binary on your `PATH`.
 It emits fixed `export` lines that prepend the shim directory to `$PATH`.
+For fish, use `lterm env --shell fish | source` after the same trust check.
 
 `lterm ssh` forwards remote PTY bytes to the local terminal without sanitizing
 terminal control sequences, so a compromised remote can drive terminal features
@@ -274,7 +282,19 @@ lterm shutdown
 ```bash
 lterm claude
 lterm codex
-lterm gemini -- -p "summarize this repo"
+lterm opencode
+lterm copilot
+lterm cursor-agent
+lterm agy -- -p "summarize this repo"
+lterm kiro
+lterm jules
+lterm aider
+lterm goose
+lterm amp
+lterm crush
+lterm kimi
+lterm qwen
+lterm gemini -- -p "summarize this repo"  # legacy-compatible
 lterm agents
 ```
 
@@ -283,6 +303,10 @@ These are thin profile aliases for:
 ```bash
 lterm agent claude
 lterm agent codex
+lterm agent opencode
+lterm agent cursor-agent
+lterm agent agy -- -p "summarize this repo"
+lterm agent qwen
 lterm agent gemini -- -p "summarize this repo"
 ```
 
@@ -291,16 +315,16 @@ Agent launchers accept the same session controls across built-in profiles and cu
 ```bash
 lterm claude --name repo-review --cwd /path/to/repo
 lterm codex --detach --name repo-codex -- exec "summarize this repo"
-lterm gemini --status -- -p "keep lterm status visible"
+lterm agy --status -- -p "keep lterm status visible"
 ```
 
-Known Claude/Codex/Gemini profiles default to a raw full-terminal attach without the lterm status bar, so their own TUI/status/alternate-screen rendering stays in control. Use `--status` to force the lterm status bar on, or `--no-status` to force it off for profiles that default on. Put `--` before agent arguments that could be parsed as lterm launch options. Use `lterm run -- <command>` when you want the generic tmux-compatible primitive directly or need to launch an unprofiled future agent; `run` enables the shim by default and `--no-tmux` opts out.
+Known Claude/Codex/OpenCode/Copilot/Cursor Agent/Antigravity/Kiro/Jules/Aider/Goose/Amp/Crush/Kimi/Qwen/Gemini/OMX/OMC profiles default to a raw full-terminal attach without the lterm status bar, so their own TUI/status/alternate-screen rendering stays in control. Use `--status` to force the lterm status bar on, or `--no-status` to suppress it for any launch/profile that would otherwise show it. Put `--` before agent arguments that could be parsed as lterm launch options. `lterm agent <name>` also works for any safe bare command name available in `PATH` (for example `lterm agent qwen-code`); use `lterm run -- <command>` only when you want the lower-level tmux-compatible primitive directly.
 
-Launcher controls are long-only (`--name`, `--cwd`, `--detach`, `--status`, `--no-status`, `--status-theme`) so common agent short flags such as `-c` pass through naturally. They apply uniformly to `claude`, `codex`, `gemini`, `omx`, `omc`, and `agent <profile>`. Use `--status-theme` / `--status-color` on agent launches when you want that session to keep a specific lterm status color across future attaches.
+Launcher controls are long-only (`--name`, `--cwd`, `--detach`, `--status`, `--no-status`, `--status-theme`) so common agent short flags such as `-c` pass through naturally. They apply uniformly to built-in agent shortcuts such as `claude`, `codex`, `opencode`, `copilot`, `cursor-agent`, `agy`, `kiro`, `jules`, `aider`, `goose`, `amp`, `crush`, `kimi`, `qwen`, `gemini`, `omx`, `omc`, and `agent <profile>`. Use `--status-theme` / `--status-color` on agent launches when you want that session to keep a specific lterm status color across future attaches.
 `--detach` prints `name<TAB>pane<TAB>command` with control characters and Unicode line/paragraph separators in each field replaced by spaces; resume later with `lterm resume <name>` or compatibility name `lterm attach <name>`. The detach record does not echo `--cwd`; query the session if you need to inspect it later.
 Explicit `--name` values use lterm's normal session-name syntax and must be free; they do not auto-suffix on conflict, so an in-use name fails with a conflict error.
 Names may contain ASCII letters, digits, `.`, `_`, and `-`, must not start with `-` or `%`, must not consist only of digits, must not look like a UUID, and are limited to 128 bytes.
-Use `lterm agents` (or `lterm agents --json`) to inspect profile defaults and whether their binaries are currently available in `PATH`. JSON rows use `kind` values of `built-in`, `custom`, or `configured`. Pass profile names, such as `lterm agents codex my-agent --json`, to inspect a selected built-in/custom/configured set; availability is a point-in-time PATH probe.
+Use `lterm agents` (or `lterm agents --json`) to inspect profile defaults and whether their binaries are currently available in `PATH`. JSON rows use `kind` values of `built-in`, `custom`, or `configured`. Pass profile names, such as `lterm agents codex my-agent --json`, to inspect a selected built-in/custom/configured set; availability is a point-in-time PATH probe. Built-ins resolve the binary names shown by `lterm agents`; most match the profile name, while `kiro` resolves `kiro-cli`. If a provider installs a different command name, use `lterm agent <command>` or a configured profile rather than relying on a guessed alias.
 For reusable custom aliases, pass an explicit JSON config file:
 
 ```bash
@@ -439,6 +463,20 @@ LTERM_RUNTIME_DIR="$TMP/run" LTERM_DATA_DIR="$TMP/data" cargo run -- logs test -
 LTERM_RUNTIME_DIR="$TMP/run" LTERM_DATA_DIR="$TMP/data" cargo run -- shutdown
 ```
 
+Release/contract preflight helpers:
+
+```bash
+scripts/release-preflight.sh --contract-only
+scripts/release-preflight.sh --allow-occupied-skip --skip-audit
+scripts/dependency-minor-dry-run.sh
+```
+
+Use `--run-soak` on `scripts/release-preflight.sh` only for the manual
+release-gate soak profile. Use
+[`docs/release-evidence-template.md`](docs/release-evidence-template.md) to
+capture release, audit, contract, dependency, and soak evidence before tagging or
+publishing.
+
 ## License
 
 Licensed under either of:

package/docs/assets/lterm-demo.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="920" height="420" role="img" aria-labelledby="title desc">
+  <title id="title">lterm quick demo</title>
+  <desc id="desc">Terminal-style demo showing a detached lterm session, sanitized logs, JSON wait, and resume.</desc>
+  <rect width="920" height="420" rx="18" fill="#0b1020"/>
+  <rect x="18" y="18" width="884" height="384" rx="14" fill="#111827" stroke="#334155"/>
+  <circle cx="46" cy="46" r="7" fill="#ef4444"/>
+  <circle cx="70" cy="46" r="7" fill="#f59e0b"/>
+  <circle cx="94" cy="46" r="7" fill="#22c55e"/>
+  <text x="124" y="52" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="15" fill="#94a3b8">lterm: persistent terminal sessions for agents</text>
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">
+    <text x="42" y="94" fill="#38bdf8">$</text>
+    <text x="66" y="94" fill="#e5e7eb">lterm start -d -n api -- sh -lc 'echo READY; sleep 60'</text>
+    <text x="66" y="124" fill="#a7f3d0">api    %0    sh -lc 'echo READY; sleep 60'</text>
+
+    <text x="42" y="172" fill="#38bdf8">$</text>
+    <text x="66" y="172" fill="#e5e7eb">lterm logs api -S=-20</text>
+    <text x="66" y="202" fill="#a7f3d0">READY</text>
+
+    <text x="42" y="250" fill="#38bdf8">$</text>
+    <text x="66" y="250" fill="#e5e7eb">lterm wait api --contains READY --json</text>
+    <text x="66" y="280" fill="#a7f3d0">{ &quot;target&quot;: &quot;api&quot;, &quot;matched&quot;: true, &quot;timed_out&quot;: false }</text>
+
+    <text x="42" y="328" fill="#38bdf8">$</text>
+    <text x="66" y="328" fill="#e5e7eb">lterm resume api</text>
+    <text x="66" y="358" fill="#fbbf24">raw PTY attach resumes the live session</text>
+  </g>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ictechgy/lterm",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Lightweight tmux-compatible terminal session daemon with cmux-friendly notifications.",
   "license": "MIT OR Apache-2.0",
   "homepage": "https://github.com/ictechgy/light_terminal#readme",
@@ -23,6 +23,7 @@
   },
   "files": [
     "bin/lterm.js",
+    "docs/assets/lterm-demo.svg",
     "README.md",
     "README.ko.md",
     "LICENSE",
@@ -30,10 +31,10 @@
     "LICENSE-MIT"
   ],
   "optionalDependencies": {
-    "lterm-darwin-arm64": "1.0.1",
-    "lterm-darwin-x64": "1.0.1",
-    "lterm-linux-arm64": "1.0.1",
-    "lterm-linux-x64": "1.0.1"
+    "lterm-darwin-arm64": "1.0.3",
+    "lterm-darwin-x64": "1.0.3",
+    "lterm-linux-arm64": "1.0.3",
+    "lterm-linux-x64": "1.0.3"
   },
   "engines": {
     "node": ">=16"