fpasoterm 1.6.0

package/completions/_fpasoterm

@@ -0,0 +1,81 @@
+#compdef fpasoterm
+
+_fpasoterm_profile_names() {
+  local -a profiles
+  profiles=("${(@f)$(command fpasoterm --profile-list 2>/dev/null | sed -n 's/^  //p')}")
+  _describe -t profiles profile profiles
+}
+
+_fpasoterm_plugin_names() {
+  local -a plugins
+  plugins=("${(@f)$(command fpasoterm --plugin-list 2>/dev/null | sed -n 's/^  plugins\/\([^ ]*\).*/\1/p')}")
+  _describe -t plugins plugin plugins
+}
+
+_fpasoterm() {
+  _arguments -s -S \
+    '(-h --help)'{-h,--help}'[show help]' \
+    '(-v --version)'{-v,--version}'[show version and build commit]' \
+    '--update-check[compare the installed version with npm latest]' \
+    '--doctor[check updates, npm audit, and config health]' \
+    '--completion=[print a completion script]:shell:(bash zsh fish powershell)' \
+    '--completion-install=[install persistent completion]:shell:(bash zsh fish powershell)' \
+    '--completion-uninstall=[remove persistent completion]:shell:(bash zsh fish powershell)' \
+    '(-l --list)'{-l,--list}'[list running windows]' \
+    '(-q --close)'{-q,--close}'[close a PID, exact title, or all]:target:(all)' \
+    '--broadcast=[send text plus Enter to local windows]:text:' \
+    '--broadcast-target=[limit Broadcast targets]:PID or title:' \
+    '--broadcast-sync[also send Broadcast through the sync channel]' \
+    '(-d --dev)'{-d,--dev}'[rebuild the local debug binary]' \
+    '(-F --foreground)'{-F,--foreground}'[keep the launcher attached]' \
+    '(-C --console-diagnostics)'{-C,--console-diagnostics}'[print diagnostics to stderr]' \
+    '(-c --config)'{-c,--config}'[use a config.toml file]:config file:_files -g "*.toml"' \
+    '(-p --profile)'{-p,--profile}'[apply a named profile]:profile:_fpasoterm_profile_names' \
+    '--profile-list[list available profiles]' \
+    '--show-config[print resolved config]' \
+    '--config-check[validate config]' \
+    '--config-path[print config path]' \
+    '--config-example[print config example]' \
+    '--diagnostics[print diagnostics report]' \
+    '--open-log-dir[open terminal log directory]' \
+    '--copy-diagnostics[copy diagnostics report]' \
+    '--plugin-list[list local User/plugins files]' \
+    '--plugin-path[print plugin directory]' \
+    '--plugin-info=[show plugin information]:plugin:_fpasoterm_plugin_names' \
+    '--plugin-uninstall=[remove local plugin files]:plugin:_fpasoterm_plugin_names' \
+    '--plugin-search=[search official public plugin ports]:query:' \
+    '--plugin-install=[download an official public port]:port:(terminal/hello terminal/welcome-banner terminal/status-banner terminal/theme appearance/amber appearance/teal appearance/high-contrast productivity/git-status productivity/session-marker)' \
+    '--plugin-ports-dir=[install --plugin-install from this local fpasoterm-plugins checkout]:directory:_files -/' \
+    '--plugin-install-file=[copy a trusted local JavaScript or TypeScript plugin]:plugin:_files -g "*.(js|ts)"' \
+    '--force[replace an existing file during plugin install]' \
+    '--enable[enable a plugin installed by one install command]' \
+    '--enable-plugin=[enable plugins]:plugin:_fpasoterm_plugin_names' \
+    '--disable-plugin=[disable plugins]:plugin:_fpasoterm_plugin_names' \
+    '--plugin-enable=[alias for enable-plugin]:plugin:_fpasoterm_plugin_names' \
+    '--plugin-disable=[alias for disable-plugin]:plugin:_fpasoterm_plugin_names' \
+    '--plugin-enable-all[enable all discovered plugins]' \
+    '--plugin-disable-all[disable all plugins]' \
+    '--update-config[add missing config defaults]' \
+    '--prune-config[remove unsupported config settings]' \
+    '--setup-sync[configure a sync folder]' \
+    '--sync-status[show sync health]' \
+    '--sync-clean[remove expired sync commands]' \
+    '--sync-diagnostics[print sync diagnostics]' \
+    '--self-update[update an npm installation]' \
+    '--self-update-checkout[update a git checkout]' \
+    '--update-desktop[refresh desktop integration]' \
+    '(-s --shell)'{-s,--shell}'[override shell]:command:_command_names' \
+    '(-o --cwd)'{-o,--cwd}'[start terminal in this directory]:directory:_files -/' \
+    '(-e --command)'{-e,--command}'[run command after launch]:command:' \
+    '(-t --title)'{-t,--title}'[override titlebar title]:title:' \
+    '(-b --titlebar-color)'{-b,--titlebar-color}'[override titlebar color]:color:' \
+    '(-r --reset-window-state)'{-r,--reset-window-state}'[delete saved window size]' \
+    '(-R --reset-config)'{-R,--reset-config}'[back up config and restore defaults]' \
+    '(-W --width)'{-W,--width}'[override window width]:pixels:' \
+    '(-H --height)'{-H,--height}'[override window height]:pixels:' \
+    '(-z --size)'{-z,--size}'[override window size]:width x height:' \
+    '(-k --debug-keys)'{-k,--debug-keys}'[enable key diagnostics]' \
+    '--disable-dmabuf[disable the Linux DMA-BUF renderer]'
+}
+
+_fpasoterm "$@"

package/completions/fpasoterm.bash

@@ -0,0 +1,55 @@
+# Bash completion for fpasoterm. Install with: source <(fpasoterm --completion bash)
+
+_fpasoterm_profile_names() {
+  command fpasoterm --profile-list 2>/dev/null | sed -n 's/^  //p'
+}
+
+_fpasoterm_plugin_names() {
+  command fpasoterm --plugin-list 2>/dev/null | sed -n 's/^  plugins\/\([^ ]*\).*/\1/p'
+}
+
+_fpasoterm() {
+  local cur prev options
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD - 1]}"
+  options='-h --help -v --version --update-check --doctor -l --list -q --close --broadcast --broadcast-target --broadcast-sync -d --dev -F --foreground -C --console-diagnostics -c --config -p --profile --profile-list --show-config --config-check --config-path --config-example --diagnostics --open-log-dir --copy-diagnostics --plugin-list --plugin-path --plugin-info --plugin-uninstall --plugin-search --plugin-install --plugin-ports-dir --plugin-install-file --force --enable --update-config --prune-config --setup-sync --sync-status --sync-clean --sync-diagnostics --self-update --self-update-checkout --update-desktop -s --shell -o --cwd -e --command -t --title -b --titlebar-color -r --reset-window-state -R --reset-config --enable-plugin --disable-plugin --plugin-enable-all --plugin-disable-all --plugin-enable --plugin-disable -W --width -H --height -z --size -k --debug-keys --disable-dmabuf --completion --completion-install --completion-uninstall'
+
+  case "$prev" in
+    --completion|--completion-install|--completion-uninstall)
+      COMPREPLY=( $(compgen -W 'bash zsh fish powershell' -- "$cur") )
+      return
+      ;;
+    --profile|-p)
+      COMPREPLY=( $(compgen -W "$(_fpasoterm_profile_names)" -- "$cur") )
+      return
+      ;;
+    --enable-plugin|--disable-plugin|--plugin-enable|--plugin-disable|--plugin-info|--plugin-uninstall)
+      COMPREPLY=( $(compgen -W "$(_fpasoterm_plugin_names)" -- "$cur") )
+      return
+      ;;
+    --plugin-install)
+      COMPREPLY=( $(compgen -W 'terminal/hello terminal/welcome-banner terminal/status-banner terminal/theme appearance/amber appearance/teal appearance/high-contrast productivity/git-status productivity/session-marker' -- "$cur") )
+      return
+      ;;
+    --plugin-ports-dir|--plugin-install-file)
+      COMPREPLY=( $(compgen -f -- "$cur") )
+      return
+      ;;
+    --config|-c|--cwd|-o)
+      COMPREPLY=( $(compgen -f -- "$cur") )
+      return
+      ;;
+    --shell|-s)
+      COMPREPLY=( $(compgen -c -- "$cur") )
+      return
+      ;;
+    --close|-q|--broadcast-target)
+      COMPREPLY=( $(compgen -W "all $(command fpasoterm --list 2>/dev/null | awk '{print $1}')" -- "$cur") )
+      return
+      ;;
+  esac
+
+  COMPREPLY=( $(compgen -W "$options" -- "$cur") )
+}
+
+complete -F _fpasoterm fpasoterm

package/completions/fpasoterm.fish

@@ -0,0 +1,64 @@
+# Fish completion for fpasoterm. Install with: fpasoterm --completion fish | source
+
+complete -c fpasoterm -s h -l help -d 'Show help'
+complete -c fpasoterm -s v -l version -d 'Show version and build commit'
+complete -c fpasoterm -l update-check -d 'Compare installed version with npm latest'
+complete -c fpasoterm -l doctor -d 'Check updates, npm audit, and config health'
+complete -c fpasoterm -s l -l list -d 'List running windows'
+complete -c fpasoterm -s q -l close -r -d 'Close a PID, exact title, or all'
+complete -c fpasoterm -l broadcast -r -d 'Send text to local windows'
+complete -c fpasoterm -l broadcast-target -r -d 'Limit Broadcast targets'
+complete -c fpasoterm -l broadcast-sync -d 'Include the sync channel'
+complete -c fpasoterm -s d -l dev -d 'Rebuild local debug binary'
+complete -c fpasoterm -s F -l foreground -d 'Keep launcher attached'
+complete -c fpasoterm -s C -l console-diagnostics -d 'Print diagnostics to stderr'
+complete -c fpasoterm -s c -l config -r -F -d 'Use a config.toml file'
+complete -c fpasoterm -s p -l profile -r -d 'Apply a named profile'
+complete -c fpasoterm -l profile-list -d 'List named profiles'
+complete -c fpasoterm -l show-config -d 'Print resolved config'
+complete -c fpasoterm -l config-check -d 'Validate config'
+complete -c fpasoterm -l config-path -d 'Print config path'
+complete -c fpasoterm -l config-example -d 'Print config example'
+complete -c fpasoterm -l diagnostics -d 'Print diagnostics report'
+complete -c fpasoterm -l open-log-dir -d 'Open terminal log directory'
+complete -c fpasoterm -l copy-diagnostics -d 'Copy diagnostics report'
+complete -c fpasoterm -l plugin-list -d 'List local User/plugins files'
+complete -c fpasoterm -l plugin-path -d 'Print plugin directory'
+complete -c fpasoterm -l plugin-info -r -d 'Show plugin information'
+complete -c fpasoterm -l plugin-uninstall -r -d 'Remove local plugin files'
+complete -c fpasoterm -l plugin-search -d 'Search official public plugin ports'
+complete -c fpasoterm -l plugin-install -r -a 'terminal/hello terminal/welcome-banner terminal/status-banner terminal/theme appearance/amber appearance/teal appearance/high-contrast productivity/git-status productivity/session-marker' -d 'Download an official public port'
+complete -c fpasoterm -l plugin-ports-dir -r -F -d 'Install --plugin-install from this local checkout'
+complete -c fpasoterm -l plugin-install-file -r -F -d 'Copy a trusted local .js/.ts plugin'
+complete -c fpasoterm -l force -d 'Replace an existing plugin during install'
+complete -c fpasoterm -l enable -d 'Enable a plugin installed by an install command'
+complete -c fpasoterm -l enable-plugin -r -d 'Enable plugins'
+complete -c fpasoterm -l disable-plugin -r -d 'Disable plugins'
+complete -c fpasoterm -l plugin-enable -r -d 'Alias for enable-plugin'
+complete -c fpasoterm -l plugin-disable -r -d 'Alias for disable-plugin'
+complete -c fpasoterm -l plugin-enable-all -d 'Enable all discovered plugins'
+complete -c fpasoterm -l plugin-disable-all -d 'Disable all plugins'
+complete -c fpasoterm -l update-config -d 'Add missing config defaults'
+complete -c fpasoterm -l prune-config -d 'Remove unsupported config settings'
+complete -c fpasoterm -l setup-sync -d 'Configure a sync folder'
+complete -c fpasoterm -l sync-status -d 'Show sync health'
+complete -c fpasoterm -l sync-clean -d 'Remove expired sync commands'
+complete -c fpasoterm -l sync-diagnostics -d 'Print sync diagnostics'
+complete -c fpasoterm -l self-update -d 'Update an npm installation'
+complete -c fpasoterm -l self-update-checkout -d 'Update a git checkout'
+complete -c fpasoterm -l update-desktop -d 'Refresh desktop integration'
+complete -c fpasoterm -s s -l shell -r -d 'Override shell'
+complete -c fpasoterm -s o -l cwd -r -F -d 'Start terminal in this directory'
+complete -c fpasoterm -s e -l command -r -d 'Run command after launch'
+complete -c fpasoterm -s t -l title -r -d 'Override titlebar title'
+complete -c fpasoterm -s b -l titlebar-color -r -d 'Override titlebar color'
+complete -c fpasoterm -s r -l reset-window-state -d 'Delete saved window size'
+complete -c fpasoterm -s R -l reset-config -d 'Restore default config'
+complete -c fpasoterm -s W -l width -r -d 'Override window width'
+complete -c fpasoterm -s H -l height -r -d 'Override window height'
+complete -c fpasoterm -s z -l size -r -d 'Override window size'
+complete -c fpasoterm -s k -l debug-keys -d 'Enable key diagnostics'
+complete -c fpasoterm -l disable-dmabuf -d 'Disable Linux DMA-BUF renderer'
+complete -c fpasoterm -l completion -r -a 'bash zsh fish powershell' -d 'Print completion script'
+complete -c fpasoterm -l completion-install -r -a 'bash zsh fish powershell' -d 'Install persistent completion'
+complete -c fpasoterm -l completion-uninstall -r -a 'bash zsh fish powershell' -d 'Remove persistent completion'

package/completions/fpasoterm.ps1

@@ -0,0 +1,47 @@
+# PowerShell completion for fpasoterm. Install with:
+# fpasoterm --completion powershell | Out-String | Invoke-Expression
+
+$fpasotermCompletion = {
+  param($wordToComplete, $commandAst, $cursorPosition)
+
+  $shells = @('bash', 'zsh', 'fish', 'powershell')
+  $options = @(
+    @('--help', 'Show help'), @('-h', 'Show help'), @('--version', 'Show version and build commit'), @('-v', 'Show version and build commit'), @('--update-check', 'Compare installed version with npm latest'), @('--doctor', 'Check updates, npm audit, and config health'),
+    @('--list', 'List running windows'), @('-l', 'List running windows'), @('--close', 'Close a PID, exact title, or all'), @('-q', 'Close a PID, exact title, or all'),
+    @('--broadcast', 'Send text to local windows'), @('--broadcast-target', 'Limit Broadcast targets'), @('--broadcast-sync', 'Include the sync channel'),
+    @('--dev', 'Rebuild local debug binary'), @('-d', 'Rebuild local debug binary'), @('--foreground', 'Keep launcher attached'), @('-F', 'Keep launcher attached'),
+    @('--console-diagnostics', 'Print diagnostics to stderr'), @('-C', 'Print diagnostics to stderr'), @('--config', 'Use a config.toml file'), @('-c', 'Use a config.toml file'),
+    @('--profile', 'Apply a named profile'), @('-p', 'Apply a named profile'), @('--profile-list', 'List named profiles'), @('--show-config', 'Print resolved config'),
+    @('--config-check', 'Validate config'), @('--config-path', 'Print config path'), @('--config-example', 'Print config example'), @('--diagnostics', 'Print diagnostics report'),
+    @('--open-log-dir', 'Open terminal log directory'), @('--copy-diagnostics', 'Copy diagnostics report'), @('--plugin-list', 'List local User/plugins files'), @('--plugin-path', 'Print plugin directory'),
+    @('--plugin-info', 'Show plugin information'), @('--plugin-uninstall', 'Remove local plugin files'), @('--plugin-search', 'Search official public plugin ports'), @('--plugin-install', 'Install a port from GitHub or --plugin-ports-dir'), @('--plugin-ports-dir', 'Install --plugin-install from a local checkout'), @('--plugin-install-file', 'Copy a trusted local .js/.ts plugin'), @('--force', 'Replace an existing plugin during install'), @('--enable', 'Enable a plugin installed by an install command'), @('--enable-plugin', 'Enable plugins'), @('--disable-plugin', 'Disable plugins'), @('--plugin-enable', 'Alias for enable-plugin'),
+    @('--plugin-disable', 'Alias for disable-plugin'), @('--plugin-enable-all', 'Enable all discovered plugins'), @('--plugin-disable-all', 'Disable all plugins'),
+    @('--update-config', 'Add missing config defaults'), @('--prune-config', 'Remove unsupported config settings'), @('--setup-sync', 'Configure a sync folder'),
+    @('--sync-status', 'Show sync health'), @('--sync-clean', 'Remove expired sync commands'), @('--sync-diagnostics', 'Print sync diagnostics'),
+    @('--self-update', 'Update an npm installation'), @('--self-update-checkout', 'Update a git checkout'), @('--update-desktop', 'Refresh desktop integration'),
+    @('--shell', 'Override shell'), @('-s', 'Override shell'), @('--cwd', 'Start terminal in this directory'), @('-o', 'Start terminal in this directory'), @('--command', 'Run command after launch'), @('-e', 'Run command after launch'),
+    @('--title', 'Override titlebar title'), @('-t', 'Override titlebar title'), @('--titlebar-color', 'Override titlebar color'), @('-b', 'Override titlebar color'),
+    @('--reset-window-state', 'Delete saved window size'), @('-r', 'Delete saved window size'), @('--reset-config', 'Restore default config'), @('-R', 'Restore default config'),
+    @('--width', 'Override window width'), @('-W', 'Override window width'), @('--height', 'Override window height'), @('-H', 'Override window height'),
+    @('--size', 'Override window size'), @('-z', 'Override window size'), @('--debug-keys', 'Enable key diagnostics'), @('-k', 'Enable key diagnostics'),
+    @('--disable-dmabuf', 'Disable Linux DMA-BUF renderer'),
+    @('--completion', 'Print completion script'), @('--completion-install', 'Install persistent completion'), @('--completion-uninstall', 'Remove persistent completion')
+  )
+
+  $previous = ''
+  if ($commandAst.CommandElements.Count -gt 1) {
+    $previous = $commandAst.CommandElements[$commandAst.CommandElements.Count - 2].Extent.Text
+  }
+  if ($previous -in '--completion', '--completion-install', '--completion-uninstall') {
+    foreach ($shell in $shells | Where-Object { $_ -like "$wordToComplete*" }) {
+      [System.Management.Automation.CompletionResult]::new($shell, $shell, 'ParameterValue', "fpasoterm completion for $shell")
+    }
+    return
+  }
+
+  foreach ($option in $options | Where-Object { $_[0] -like "$wordToComplete*" }) {
+    [System.Management.Automation.CompletionResult]::new($option[0], $option[0], 'ParameterName', $option[1])
+  }
+}
+
+Register-ArgumentCompleter -Native -CommandName fpasoterm, fpasoterm.cmd, fpasoterm.exe -ScriptBlock $fpasotermCompletion

package/docs/capability-diagnostics.en.md

@@ -0,0 +1,77 @@
+# Terminal Capability Diagnostics
+
+Open the window menu, then select **Diagnostics > Capability Test**. This
+opens the existing diagnostics panel and does not change the terminal session,
+shell configuration, or saved settings.
+
+The panel reports the environment fpasoterm provides to its PTY:
+
+- `TERM`: `xterm-256color`
+- `COLORTERM`: `truecolor`
+- `locale`: the effective `LC_ALL`, `LC_CTYPE`, or `LANG` value
+- `output encoding`: the configured PTY decoder
+- `shell`: the configured or platform-selected shell command
+
+## Output Encoding
+
+The panel can save `terminal.encoding` as `utf-8`, `shift-jis`, or `euc-jp`.
+The choice applies when the window is restarted because both the PTY decoder and
+shell locale are selected before the shell starts. UTF-8 is the default. On
+Unix, fpasoterm supplies a UTF-8 locale to an inherited non-UTF-8 environment,
+so normal tools keep UTF-8 filenames intact. It does not auto-detect byte
+encodings because detection is ambiguous and can corrupt otherwise valid text.
+
+## Truecolor
+
+The renderer supports 24-bit ANSI colors and advertises that through
+`COLORTERM=truecolor`. Run the command shown in the panel in the terminal. It
+should render distinct red, green, and blue words:
+
+```sh
+printf '\033[38;2;255;80;80mred \033[38;2;80;220;140mgreen \033[38;2;90;150;255mblue\033[0m\n'
+```
+
+## Control Sequences
+
+- **OSC 52 clipboard:** fpasoterm accepts received text clipboard payloads and
+  writes them to the operating-system clipboard when `security.osc52` is
+  `trusted`. `security.osc52MaxBytes` limits the decoded payload. Set
+  `security.osc52 = "disabled"` when terminal output is not trusted.
+- **OSC 7 current directory:** received `file://` reports are retained only as
+  diagnostics metadata. Use `Ctrl+Shift+o` or **Window > New CWD** to open a
+  separate terminal in an existing local absolute directory reported by OSC 7.
+  Remote-host reports and unavailable paths are rejected. fpasoterm does not
+  open, inspect, or synchronize the reported path. fpasoterm configures Bash
+  to report OSC 7 at each prompt; other shells need their own OSC 7 integration.
+- **OSC 133 shell integration:** prompt and command lifecycle markers are
+  retained only as diagnostics metadata. They do not execute a command or
+  replace the shell, multiplexer, or TUI workflow.
+- **OSC 8 hyperlinks:** clicking a rendered OSC 8 link or plain `http(s)` URL
+  opens an explicit confirmation dialog. Copy remains available. External
+  browser opening is disabled by default and additionally requires
+  `security.osc8Open = true`; links are never opened automatically. Absolute
+  and `~/` paths remain copy-only links.
+- **OSC 9 / OSC 99 notifications:** desktop notifications are disabled by
+  default. Set `security.oscNotifications = true` to allow them. The first use
+  can request operating-system notification permission, and
+  `security.oscNotificationMinIntervalMs` limits notifications to one per
+  1,000--60,000 ms (default 5,000 ms).
+- **Bracketed paste:** xterm.js handles terminal input. A shell or TUI enables
+  bracketed paste with DECSET 2004, then receives pasted text as a bracketed
+  sequence.
+- **Bell:** BEL is passed to xterm.js. Audible or visual feedback is controlled
+  by the operating system and webview, so it may be silent.
+
+The panel documents the supported paths rather than sending a clipboard write,
+opening a URL, or ringing a bell automatically. This keeps diagnostics safe for
+the current terminal session.
+
+## Verification
+
+1. Start fpasoterm and open **Diagnostics > Capability Test**.
+2. Confirm `TERM` is `xterm-256color` and `COLORTERM` is `truecolor`.
+3. Run the displayed truecolor command and confirm all three colors differ.
+4. Run `printf 'https://example.com /tmp/fpasoterm-link-test\n'`, click each
+   item, and paste into a trusted text field to confirm URL/path copying.
+5. If a TUI behaves differently, record this panel together with
+   `fpasoterm --diagnostics` when filing an issue.

package/docs/capability-diagnostics.ja.md

@@ -0,0 +1,63 @@
+# Terminal Capability Diagnostics
+
+window menu から **Diagnostics > Capability Test** を選択します。既存の
+diagnostics panelを表示するだけで、terminal session、shell設定、保存済み設定は変更しません。
+
+panelにはfpasotermがPTYへ設定する次のenvironmentを表示します。
+
+- `TERM`: `xterm-256color`
+- `COLORTERM`: `truecolor`
+- `locale`: 有効な`LC_ALL`、`LC_CTYPE`、または`LANG`
+- `output encoding`: 設定済みPTY decoder
+- `shell`: configまたはOS既定から選択したshell command
+
+## Output Encoding
+
+panelから`terminal.encoding`を`utf-8`、`shift-jis`、`euc-jp`として保存できます。
+PTY decoderとshell localeはshell起動前に決まるため、選択後はwindowを再起動してください。
+既定値はUTF-8です。Unixでは親環境がUTF-8以外のlocaleでも、UTF-8 PTYにはUTF-8 localeを
+設定するため、通常のtoolが日本語filenameを`?`へ置換することを防ぎます。文字コードの自動判定は
+曖昧で正しいtextも壊し得るため実装しません。
+
+## Truecolor
+
+rendererは24-bit ANSI colorを扱い、`COLORTERM=truecolor`でterminal applicationへ通知します。
+panel内の次のcommandをterminalで実行し、赤・緑・青のwordがそれぞれ異なる色で表示されることを
+確認してください。
+
+```sh
+printf '\033[38;2;255;80;80mred \033[38;2;80;220;140mgreen \033[38;2;90;150;255mblue\033[0m\n'
+```
+
+## Control Sequence
+
+- **OSC 52 clipboard:** `security.osc52`が`trusted`の場合だけ受信したtext clipboard
+  payloadをOS clipboardへ書き込みます。`security.osc52MaxBytes`でdecode後のsizeを制限します。
+  terminal outputをtrustedできない場合は`security.osc52 = "disabled"`を設定してください。
+- **OSC 7 current directory:** 受信した`file://` reportはdiagnostics metadataとして保持します。
+  `Ctrl+Shift+o`または**Window > New CWD**で、OSC 7が通知したexisting local absolute directoryから別windowを開けます。
+  remote hostのreportまたは存在しないpathは拒否します。報告されたpathをopen、参照、syncしません。
+  fpasotermはBash promptごとにOSC 7を通知するよう設定します。ほかのshellでは、そのshell側のOSC 7 integrationが必要です。
+- **OSC 133 shell integration:** promptとcommand lifecycle markerはdiagnostics metadataとしてだけ
+  保持します。commandを実行したりshell、multiplexer、TUIのworkflowを置き換えたりしません。
+- **OSC 8 hyperlink:** 表示されたOSC 8 linkまたは通常の`http(s)` URLをclickすると明示的な確認dialogを表示します。
+  URLのcopyは常に可能です。外部browserでopenするには`security.osc8Open = true`も必要です。自動openはしません。
+  absolute pathと`~/` pathはcopy-onlyです。
+- **OSC 9 / OSC 99通知:** desktop notificationは既定で無効です。`security.oscNotifications = true`で有効化できます。
+  最初の使用時にはOS notification permissionを確認することがあります。`security.oscNotificationMinIntervalMs`は通知間隔を
+  1,000--60,000 msに制限します（既定5,000 ms）。
+- **Bracketed paste:** xterm.jsがterminal inputを処理します。shellまたはTUIがDECSET 2004を有効にすると、
+  paste textはbracketed sequenceとして届きます。
+- **Bell:** BELはxterm.jsへ渡します。音またはvisual feedbackはOSとwebviewの設定に依存するため、
+  無音の場合があります。
+
+panelはclipboard書込み、URL open、bellを自動実行せず、対応経路を説明します。現在のterminal sessionへ
+影響を与えないためです。
+
+## 動作確認
+
+1. fpasotermを起動し、**Diagnostics > Capability Test** を開きます。
+2. `TERM`が`xterm-256color`、`COLORTERM`が`truecolor`であることを確認します。
+3. 表示されたtruecolor commandを実行し、3色が異なることを確認します。
+4. `printf 'https://example.com /tmp/fpasoterm-link-test\n'`を実行し、各項目をclickしてtrustedなtext fieldへpasteし、URL/pathがcopyされることを確認します。
+5. TUIの挙動に問題がある場合は、このpanelの内容と`fpasoterm --diagnostics`を合わせてIssueへ記載します。

package/docs/completion.en.md

@@ -0,0 +1,141 @@
+# Command Completion
+
+fpasoterm can print completion scripts for Bash, Zsh, Fish, and PowerShell.
+The scripts complete CLI options and the values for `--completion`; Bash and
+Zsh also query local profile and plugin lists for those options.
+
+```sh
+fpasoterm --completion bash
+fpasoterm --completion zsh
+fpasoterm --completion fish
+fpasoterm --completion powershell
+```
+
+The command only writes a script to standard output. It does not start a
+terminal window or modify configuration. To install or remove fpasoterm's
+user-only persistent completion file, use:
+
+```sh
+fpasoterm --completion-install bash
+fpasoterm --completion-uninstall bash
+```
+
+Replace `bash` with `zsh`, `fish`, or `powershell`. Install and uninstall only
+touch fpasoterm-owned user files; they do not modify system completion files.
+
+## Updating Completion
+
+An application update does not require reinstallation for the existing
+completion script to keep working. Persistent completion is a copied user file,
+so rerun the install command only when you want newly added CLI options or
+value candidates to appear in Tab completion:
+
+```sh
+fpasoterm --completion-install bash
+fpasoterm --completion-install zsh
+fpasoterm --completion-install fish
+fpasoterm --completion-install powershell
+```
+
+Restart the shell after updating. In PowerShell, `. $PROFILE` reloads the
+profile without opening a new console. Use `--completion-uninstall <shell>`
+only to remove completion; it is not needed for a normal update.
+
+## Bash
+
+Current shell:
+
+```bash
+source <(fpasoterm --completion bash)
+```
+
+Persistent user installation: `fpasoterm --completion-install bash`.
+It installs `~/.local/share/bash-completion/completions/fpasoterm` (or the
+equivalent location under `XDG_DATA_HOME`). Remove it with
+`fpasoterm --completion-uninstall bash`.
+
+## Zsh
+
+Current shell:
+
+```zsh
+source <(fpasoterm --completion zsh)
+```
+
+Persistent user installation: `fpasoterm --completion-install zsh`.
+It installs `~/.zfunc/_fpasoterm`; remove it with
+`fpasoterm --completion-uninstall zsh`.
+
+Add `fpath=(~/.zfunc $fpath)` before `autoload -Uz compinit && compinit` in
+`.zshrc` when `~/.zfunc` is not already in `fpath`.
+
+## Fish
+
+Current shell:
+
+```fish
+fpasoterm --completion fish | source
+```
+
+Persistent user installation: `fpasoterm --completion-install fish`.
+It installs `~/.config/fish/completions/fpasoterm.fish` (or the equivalent
+location under `XDG_CONFIG_HOME`); remove it with
+`fpasoterm --completion-uninstall fish`.
+
+Fish automatically loads that file in later shells.
+
+## PowerShell
+
+Current PowerShell session:
+
+```powershell
+fpasoterm --completion powershell | Out-String | Invoke-Expression
+```
+
+For a persistent user installation, use:
+
+```powershell
+fpasoterm --completion-install powershell
+```
+
+This writes a fpasoterm-owned script below `User/completions` and adds one
+marked fpasoterm block to every available user PowerShell profile (`pwsh` and
+Windows PowerShell). It handles redirected Documents folders. Remove both the
+script and only those marked blocks with `fpasoterm --completion-uninstall powershell`.
+If a profile contains only that managed block, uninstall removes the otherwise
+empty profile file too; unrelated profile settings are preserved.
+
+The fpasoterm window does not reload a PowerShell profile. Close and reopen the
+PowerShell console after installing, or enable it immediately in the current
+console with:
+
+```powershell
+. $PROFILE
+```
+
+Profiles are skipped when PowerShell is launched with `-NoProfile`; in that
+case source the installed completion script manually or start PowerShell
+without `-NoProfile`.
+
+If PowerShell reports that scripts cannot run, inspect the effective policy and
+allow locally-created scripts for the current user only. This does not require
+an administrator console:
+
+```powershell
+Get-ExecutionPolicy -List
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+. $PROFILE
+```
+
+An organization policy can override `CurrentUser`; in that case contact the
+device administrator rather than using a machine-wide bypass.
+
+When using an installer artifact directly, use the console wrapper so output
+returns to PowerShell:
+
+```powershell
+.\fpasoterm.cmd --completion powershell | Out-String | Invoke-Expression
+```
+
+`cmd.exe` does not provide a comparable programmable argument-completion API.
+Use PowerShell for Windows interactive completion.

package/docs/completion.ja.md

@@ -0,0 +1,113 @@
+# コマンド補完
+
+fpasoterm は Bash、Zsh、Fish、PowerShell 向けのcompletion scriptを出力できます。
+CLI optionと`--completion`の値を補完し、Bash/Zshでは`--profile`とplugin指定時に
+ローカルのprofile/plugin一覧も候補にします。
+
+```sh
+fpasoterm --completion bash
+fpasoterm --completion zsh
+fpasoterm --completion fish
+fpasoterm --completion powershell
+```
+
+このcommandはscriptを標準出力へ書き出すだけです。terminal windowの起動や設定変更は行いません。fpasoterm専用の永続completion fileを導入・削除する場合は次を使います。
+
+```sh
+fpasoterm --completion-install bash
+fpasoterm --completion-uninstall bash
+```
+
+`bash`は`zsh`、`fish`、`powershell`へ置き換えられます。install/uninstallはfpasotermが管理するuser fileだけを操作し、system completion fileは変更しません。
+
+## 更新時のcompletion
+
+アプリを更新しても、既に導入したcompletion scriptが動かなくなるための再導入は不要です。永続completionはuser directoryへcopyしたfileであるため、新しいCLI optionや値をTab補完の候補へ追加したい場合だけ、使用するshellに対して再度installを実行してください。
+
+```sh
+fpasoterm --completion-install bash
+fpasoterm --completion-install zsh
+fpasoterm --completion-install fish
+fpasoterm --completion-install powershell
+```
+
+更新後はshellを再起動します。PowerShellでは新しいconsoleを開かずに`. $PROFILE`でprofileを再読込できます。`--completion-uninstall <shell>`はcompletionを削除するためだけのcommandであり、通常の更新時には必要ありません。
+
+## Bash
+
+現在のshellだけで有効にする場合:
+
+```bash
+source <(fpasoterm --completion bash)
+```
+
+永続的に導入する場合は`fpasoterm --completion-install bash`を実行します。`~/.local/share/bash-completion/completions/fpasoterm`（または`XDG_DATA_HOME`配下）へ導入され、`fpasoterm --completion-uninstall bash`で削除できます。
+
+## Zsh
+
+現在のshellだけで有効にする場合:
+
+```zsh
+source <(fpasoterm --completion zsh)
+```
+
+永続的に導入する場合は`fpasoterm --completion-install zsh`を実行します。`~/.zfunc/_fpasoterm`へ導入され、`fpasoterm --completion-uninstall zsh`で削除できます。
+
+`~/.zfunc`が`fpath`に含まれていない場合は、`.zshrc`の
+`autoload -Uz compinit && compinit`より前へ`fpath=(~/.zfunc $fpath)`を追加してください。
+
+## Fish
+
+現在のshellだけで有効にする場合:
+
+```fish
+fpasoterm --completion fish | source
+```
+
+永続的に導入する場合は`fpasoterm --completion-install fish`を実行します。`~/.config/fish/completions/fpasoterm.fish`（または`XDG_CONFIG_HOME`配下）へ導入され、`fpasoterm --completion-uninstall fish`で削除できます。
+
+Fishは次回以降のshellでこのfileを自動的に読み込みます。
+
+## PowerShell
+
+現在のPowerShell sessionだけで有効にする場合:
+
+```powershell
+fpasoterm --completion powershell | Out-String | Invoke-Expression
+```
+
+ユーザー環境へ永続的に導入する場合は次を実行します。
+
+```powershell
+fpasoterm --completion-install powershell
+```
+
+`User/completions`配下へscriptを配置し、利用可能なPowerShellのuser profile（`pwsh`とWindows PowerShell）すべてへfpasoterm専用の識別可能なblockを追加します。Documentsのredirectにも対応します。`fpasoterm --completion-uninstall powershell`はscriptとこのblockだけを削除します。
+profileの内容がこの管理blockだけの場合は空fileを残さずprofile自体を削除します。他のprofile設定がある場合は保持します。
+
+fpasoterm windowの再起動ではPowerShell profileは読み直されません。install後にPowerShell consoleを一度閉じて開き直すか、現在のconsoleで直ちに有効にするには次を実行します。
+
+```powershell
+. $PROFILE
+```
+
+`-NoProfile`を付けてPowerShellを起動している場合はprofileを読み込まないため、上記のようにcompletion scriptをsourceするか、`-NoProfile`なしでPowerShellを起動してください。
+
+PowerShellが「このシステムではスクリプトを実行できません」と表示する場合は、effective policyを確認し、現在のuserだけでlocal scriptを許可します。administrator consoleは不要です。
+
+```powershell
+Get-ExecutionPolicy -List
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+. $PROFILE
+```
+
+organization policyが`CurrentUser`より優先される場合は、machine-wide bypassを設定せずdevice administratorへ確認してください。
+
+installer artifactを直接使用する場合は、PowerShellへstdoutを返すconsole wrapperを使います。
+
+```powershell
+.\fpasoterm.cmd --completion powershell | Out-String | Invoke-Expression
+```
+
+`cmd.exe`にはBashやPowerShellと同等のprogrammaticな引数completion APIがありません。
+Windowsでinteractive completionを使用する場合はPowerShellを使ってください。