fpasoterm 1.6.0

package/docs/plugins.en.md

@@ -0,0 +1,266 @@
+# Plugins
+
+fpasoterm plugins are local JavaScript or TypeScript files that run in the
+terminal renderer after the terminal is ready. Use them for small, personal
+behavior changes such as a startup message, terminal option adjustment, or
+diagnostic integration.
+
+Prefer a plugin for a new convenience workflow instead of adding it to the
+fpasoterm core. Core changes remain appropriate for terminal correctness,
+platform integration, security, and compatibility with shells, multiplexers,
+and TUI editors.
+
+Plugins are an advanced local customization feature. They are not a sandboxed
+extension format. fpasoterm downloads a public port only when the user
+explicitly invokes `--plugin-install`; it never downloads plugins at startup
+or automatically from a renderer plugin.
+
+For reviewed public plugins, use the
+[fpasoterm-plugins ports repository](https://github.com/oyoguhito/fpasoterm-plugins).
+It owns the public catalog, `INDEX`, development checks, and contribution
+process. End users install a reviewed local checkout or an explicit local
+plugin file through the fpasoterm CLI; this document defines that runtime
+contract and manual local plugin layout.
+
+## Security
+
+Plugins run in the renderer context alongside the terminal UI. Enable only
+local files that you trust and have reviewed. Do not enable plugins copied from
+unknown sources, and do not put passwords, access tokens, private paths, or
+other secrets in a plugin file.
+
+## Plugin directory
+
+Place `.js` or `.ts` files below the `plugins` directory beside the active
+`config.toml`:
+
+```text
+~/.config/fpasoterm/User/
+├── config.toml
+└── plugins/
+    ├── welcome-banner.ts
+    └── status-banner.ts
+```
+
+Subdirectories are supported. Plugin paths in the configuration are always
+relative to the `User` directory, for example `plugins/team/banner.ts`.
+
+TypeScript plugins are transpiled at launch and cached below:
+
+```text
+~/.config/fpasoterm/User/cache/plugins/
+```
+
+Do not edit generated files in that cache; edit the original `.ts` file in
+`User/plugins` instead.
+
+## Plugin version metadata
+
+Plugins may declare their own version and description in source comments. No
+manifest or extra directory is required:
+
+```ts
+// @fpasoterm-plugin version: 1.0.0
+// @fpasoterm-plugin description: Displays a concise startup message.
+```
+
+`version` is an arbitrary local release identifier; use semantic versions such
+as `1.0.0` for consistency. It is distinct from `api.version`, which is the
+running fpasoterm application version. Omit the header for older plugins; the
+CLI reports their version as `(not declared)`.
+
+## Enable plugins
+
+fpasoterm creates `User/plugins` on its first normal launch. For a manually
+maintained local plugin, place its trusted source there and enable it in
+configuration.
+
+Enable the files in `~/.config/fpasoterm/User/config.toml`:
+
+```toml
+[plugins]
+enabled = [
+  "plugins/welcome-banner.ts",
+  "plugins/status-banner.ts",
+]
+```
+
+Restart fpasoterm after changing the plugin list or plugin source. Plugins are
+loaded in the order written in `enabled`.
+
+The CLI, including packaged Windows/macOS/Linux binaries, can update the list
+by plugin filename:
+
+```sh
+fpasoterm --enable-plugin welcome-banner,status-banner
+fpasoterm --disable-plugin status-banner
+fpasoterm --show-config
+```
+
+The explicit plugin-management spellings are also available from every CLI:
+
+```sh
+fpasoterm --plugin-path
+fpasoterm --plugin-list
+fpasoterm --plugin-info welcome-banner
+fpasoterm --plugin-uninstall welcome-banner
+fpasoterm --plugin-enable welcome-banner
+fpasoterm --plugin-disable welcome-banner
+fpasoterm --plugin-enable-all
+fpasoterm --plugin-disable-all
+```
+
+`--plugin-list` is a local-only view of the active `User/plugins` directory. It does not query
+GitHub or the public port catalog; use `--plugin-search [query]` for that remote catalog. It
+prints discovered files with their declared versions and the `enabled` entries. The
+`--plugin-enable` and `--plugin-disable` options are aliases for the existing
+`--enable-plugin` and `--disable-plugin` options.
+`--plugin-info <file>` prints the resolved source path, enabled state, declared
+version, description, load status, and renderer URL without opening a window. Pass a
+`.js` or `.ts` filename such as `welcome-banner.ts`. For all local
+`--plugin-*` selectors, the leading `plugins/` and the `.js`/`.ts` suffix are
+optional: use `welcome-banner` or `appearance/teal`. If both `.js` and `.ts`
+would match, provide an extension or a more specific path.
+`--plugin-uninstall <file>` removes one or comma-separated local plugin source
+files from `User/plugins`, removes their generated cache files, and removes the
+same entries from `plugins.enabled`. It never contacts the public catalog and
+refuses ambiguous names, traversal, and symlinked plugin files. Restart open
+fpasoterm windows after removal. It cannot be combined with other plugin
+mutation options.
+`--plugin-enable-all` enables every discovered `.js`/`.ts` file. It reports an
+error when `User/plugins` contains no plugin source; it never silently creates
+or enables an empty list.
+`--plugin-disable-all` clears only `plugins.enabled`; it does not delete any
+plugin source or cache file.
+
+## Public Port Install
+
+Search the public metadata index before selecting a port. This requests only
+the official `INDEX`; it does not download or execute plugin source:
+
+```sh
+fpasoterm --plugin-search
+fpasoterm --plugin-search teal
+```
+
+`--plugin-search` is a **remote** search and prints its source as the official
+GitHub `INDEX`. The `fpasoterm-plugins` `ports` command remains useful for
+local `INDEX` search, port development, and validation. It is not required for
+an end-user install.
+
+Download one selected port from the official
+[`oyoguhito/fpasoterm-plugins`](https://github.com/oyoguhito/fpasoterm-plugins)
+repository without cloning its full checkout or installing Node.js:
+
+```sh
+fpasoterm --plugin-install appearance/teal
+fpasoterm --plugin-install appearance/teal --enable
+fpasoterm --plugin-uninstall appearance/teal
+```
+
+The first command copies only the requested source into `User/plugins` and
+leaves it disabled for review. `--enable` explicitly adds it to
+`plugins.enabled`. Existing files are preserved unless
+`--force` is supplied. The installer connects over HTTPS only to
+the fixed official repository, validates port/source paths, manifest metadata,
+source size, and the expected fpasoterm plugin header. Downloaded plugins still
+run in the renderer, so review and trust them before enabling them.
+
+### Local checkout or file install
+
+To install a port you have cloned, reviewed, or are developing locally, use
+the fpasoterm CLI directly. No `npm run ports install` step is needed:
+
+```sh
+git clone https://github.com/oyoguhito/fpasoterm-plugins.git
+fpasoterm --plugin-install appearance/teal \
+  --plugin-ports-dir ./fpasoterm-plugins --enable
+```
+
+`--plugin-ports-dir` explicitly selects the checkout containing `ports/`.
+Without it, `--plugin-install` obtains the selected port from the official
+GitHub repository. With it, the installer reads `port.toml`, checks metadata
+and the minimum fpasoterm version, then copies only that local plugin source.
+The local path never contacts the network.
+
+For a standalone trusted plugin outside a ports checkout, explicitly name the
+source file:
+
+```sh
+fpasoterm --plugin-install-file ~/work/my-plugins/team-banner.ts --enable
+```
+
+Both local commands require a regular `.js` or `.ts` file with the fpasoterm
+plugin header and renderer API marker. They preserve an existing destination
+unless `--force` is supplied.
+
+When duplicate filenames exist in different subdirectories, use a path
+relative to `plugins`, such as `team/status-banner.ts`.
+
+### Windows packaged binary
+
+MSI/EXE supports `fpasoterm.exe --plugin-install <category/name>` with or
+without `--plugin-ports-dir`, and `--plugin-install-file` directly; Node.js is
+not required. Use `fpasoterm.cmd` only when running from a Windows source checkout.
+
+At startup, plugin scripts are loaded from the trusted `User/plugins` source or
+the generated TypeScript cache using Tauri's local asset protocol. The default
+`User` directory is supported. After enabling or editing a plugin, close and
+restart the affected fpasoterm window. For a load failure, start with
+`fpasoterm --foreground --console-diagnostics` and look for `plugin loaded` or
+`failed to load plugin`.
+
+Every plugin is evaluated in its own function scope. Plugins can therefore use
+their own top-level `const` and `let` declarations without colliding with other
+enabled plugins. Use `window.fpasotermPluginApi` for the supported shared API.
+
+## Plugin API
+
+The supported API is declared in
+[`docs/fpasoterm-plugin.d.ts`](fpasoterm-plugin.d.ts). Add this line at the top
+of a TypeScript plugin when working from this repository:
+
+```ts
+/// <reference path="../../docs/fpasoterm-plugin.d.ts" />
+```
+
+Installed plugins can instead copy the declaration file locally and update the
+reference path. The API is available as `window.fpasotermPluginApi` and
+provides:
+
+- `terminal`: write text, focus the terminal, and adjust supported terminal options.
+- `fitAddon`: call `fit()` after a plugin changes terminal layout-related options.
+- `config`: read the resolved runtime configuration, including `plugins.enabled`.
+- `log(message)`: write a plugin-prefixed diagnostic entry.
+- `version`: read the running fpasoterm version and build identifier.
+- `getOfficialPluginIndex()`: read metadata from the same fixed official `INDEX`
+  used by `fpasoterm --plugin-search`. It does not download, install, enable,
+  or execute plugin source.
+- `onReady(callback)`: run code once after the terminal backend has started.
+- `registerCommand(id, title, handler)`: add an action button under the
+  hamburger menu's `Plugins` submenu. The submenu is shown only when at least
+  one loaded plugin registers a command. Enabling a plugin alone does not add a
+  button because fpasoterm has no action handler to invoke.
+
+All current in-tree samples register one command, so enabling current copies of
+`hello.ts`, `status-banner.ts`, `theme.ts`, and `welcome-banner.ts` shows four
+buttons. If an older local sample does not register a command, it remains
+enabled and can still run its startup code, but it is intentionally absent from
+the menu. Use `--plugin-info <file>` to inspect its source/version and restart
+after replacing a local plugin file.
+
+Keep plugins small and defensive. A plugin load error is reported in diagnostics
+and does not stop later enabled plugins from loading, but an invalid plugin can
+still affect the renderer while it runs.
+
+Registered commands use the existing menu's Tab and arrow-key navigation.
+`Ctrl+Shift+P` remains assigned to `Log Show`; a command palette can reuse the
+same command registry in a future release without changing plugin source.
+
+## Samples And Ports
+
+The in-tree `examples/plugins/` files are minimal API references. Installable
+samples, appearance themes, metadata, compatibility validation, and updates are
+maintained in [fpasoterm-plugins](https://github.com/oyoguhito/fpasoterm-plugins).
+
+See [Configuration](config.en.md) for the full `config.toml` reference.

package/docs/plugins.ja.md

@@ -0,0 +1,176 @@
+# プラグイン
+
+fpasoterm のプラグインは、terminal の準備後に renderer で動作するローカルの JavaScript または TypeScript file です。起動時メッセージ、terminal option の調整、diagnostics 連携など、個人用の小さな挙動変更に使えます。追加すると便利な workflow は、原則として本体ではなく plugin として実装します。本体の変更は terminal の正確性、platform integration、security、shell / multiplexer / TUI editorとの互換性に必要なものへ限定します。
+
+plugin は高度なローカルカスタマイズ機能で、sandbox 化された extension 形式ではありません。fpasoterm は利用者が `--plugin-install` を明示した場合に限り公開portを取得できます。起動時やrenderer pluginから自動取得することはありません。
+
+review済みの公開pluginは [fpasoterm-plugins ports repository](https://github.com/oyoguhito/fpasoterm-plugins) を使用してください。このrepositoryは公開catalog、`INDEX`、開発時のcheck、contribution processを管理します。利用者向けのlocal checkoutまたは指定fileからのinstallはfpasoterm本体CLIで行います。本書はfpasoterm本体のruntime contractと手動local plugin配置を説明します。
+
+## セキュリティ
+
+plugin は terminal UI と同じ renderer context で実行されます。内容を確認して信頼できるローカル file だけを有効にしてください。出所不明の plugin は有効にせず、password、access token、private path、その他の秘密情報を plugin file に書かないでください。
+
+## plugin directory
+
+active な `config.toml` と同じ場所にある `plugins` directory 配下へ、`.js` または `.ts` file を配置します。
+
+```text
+~/.config/fpasoterm/User/
+├── config.toml
+└── plugins/
+    ├── welcome-banner.ts
+    └── status-banner.ts
+```
+
+subdirectory も使えます。設定に書く plugin path は常に `User` directory からの相対 path です。たとえば `plugins/team/banner.ts` のように指定します。
+
+TypeScript plugin は起動時に変換され、次の directory に cache されます。
+
+```text
+~/.config/fpasoterm/User/cache/plugins/
+```
+
+この cache の生成 file は編集せず、`User/plugins` 配下にある元の `.ts` file を編集してください。
+
+## plugin version metadata
+
+plugin source の comment に version と description を宣言できます。manifestや追加 directory は不要です。
+
+```ts
+// @fpasoterm-plugin version: 1.0.0
+// @fpasoterm-plugin description: 簡潔な起動 message を表示する。
+```
+
+`version` は plugin 固有のローカル release 識別子です。一貫性のため `1.0.0` のような semantic version を推奨します。実行中 fpasoterm 本体の version を返す `api.version` とは別です。headerの無い既存 plugin は従来どおり動作し、CLIでは `(not declared)` と表示します。
+
+## plugin の有効化
+
+fpasoterm は最初の通常起動時に `User/plugins` を作成します。手動管理するlocal pluginの場合は、そこへ信頼できるsourceを配置して設定で有効化します。
+
+`~/.config/fpasoterm/User/config.toml` で有効にします。
+
+```toml
+[plugins]
+enabled = [
+  "plugins/welcome-banner.ts",
+  "plugins/status-banner.ts",
+]
+```
+
+plugin list または plugin source を変更した後は fpasoterm を再起動してください。`enabled` に書かれた順番で読み込まれます。
+
+CLIでは、packaged Windows/macOS/Linux binaryを含めて、file nameを指定してlistを更新できます。
+
+```sh
+fpasoterm --enable-plugin welcome-banner,status-banner
+fpasoterm --disable-plugin status-banner
+fpasoterm --show-config
+```
+
+すべてのCLIでplugin管理用の明示的な表記も使えます。
+
+```sh
+fpasoterm --plugin-path
+fpasoterm --plugin-list
+fpasoterm --plugin-info welcome-banner
+fpasoterm --plugin-uninstall welcome-banner
+fpasoterm --plugin-enable welcome-banner
+fpasoterm --plugin-disable welcome-banner
+fpasoterm --plugin-enable-all
+fpasoterm --plugin-disable-all
+```
+
+`--plugin-list` はactiveな `User/plugins` directoryだけを対象にする **local list** です。GitHubや公開port catalogへの問い合わせは行いません。remote catalogは `--plugin-search [query]` を使用してください。検出した fileと宣言されたversion、および `enabled` を表示します。`--plugin-enable` と `--plugin-disable` は、既存の `--enable-plugin` と `--disable-plugin` の alias です。
+`--plugin-info <file>` は window を起動せずに、source path、有効状態、宣言version、description、load status、renderer URL を表示します。localの`--plugin-*` selectorでは、`plugins/` prefixと`.js`/`.ts` suffixを省略できます。たとえば`welcome-banner`や`appearance/teal`を指定できます。`.js`と`.ts`の両方が一致する場合はextensionまたはより具体的なpathを指定してください。
+`--plugin-uninstall <file>` は `User/plugins` のlocal plugin sourceを1件またはcomma区切りで削除し、生成済みcacheと同じ`plugins.enabled` entryも削除します。公開catalogには接続せず、曖昧なname、traversal、symlink化されたplugin fileはerrorにします。削除後は開いているfpasoterm windowを再起動してください。他のplugin変更optionとの同時指定はできません。
+`--plugin-enable-all` は検出済みの全 `.js` / `.ts` fileを有効化します。`User/plugins`にplugin sourceが無い場合は、空のlistを成功扱いにせずerrorを表示します。`--plugin-disable-all` は `plugins.enabled` だけを空にし、plugin sourceやcache fileは削除しません。
+
+## 公開portの直接install
+
+portを選ぶ前に公開metadata indexを検索できます。これは公式`INDEX`だけを取得し、plugin sourceのdownloadや実行は行いません。
+
+```sh
+fpasoterm --plugin-search
+fpasoterm --plugin-search teal
+```
+
+`--plugin-search` は公式GitHub `INDEX`を表示する **remote search** で、出力にもsourceを表示します。`fpasoterm-plugins` 内の `ports` command はlocal `INDEX`検索、port開発、検証に使えますが、利用者がpluginをinstallするためには不要です。
+
+公式の [oyoguhito/fpasoterm-plugins](https://github.com/oyoguhito/fpasoterm-plugins)
+repositoryから、必要なportだけを本体CLIで直接取得できます。ports checkout全体やNode.jsは不要です。
+
+```sh
+fpasoterm --plugin-install appearance/teal
+fpasoterm --plugin-install appearance/teal --enable
+fpasoterm --plugin-uninstall appearance/teal
+```
+
+最初のcommandは指定portのsourceだけを`User/plugins`へcopyし、reviewできるよう無効のままにします。`--enable`を明示した場合だけ`plugins.enabled`へ追加します。既存fileは`--force`を指定しない限り置き換えません。installerは固定の公式repositoryにHTTPSで接続し、port/source path、manifest metadata、source size、期待するfpasoterm plugin headerを検証します。download後もpluginはrendererで動作するため、有効化前に内容を確認して信頼できるものだけを使用してください。
+
+### local checkout / fileからのinstall
+
+clone、review、開発中のlocal portは、`npm run ports install` を使わずfpasoterm本体CLIからinstallできます。
+
+```sh
+git clone https://github.com/oyoguhito/fpasoterm-plugins.git
+fpasoterm --plugin-install appearance/teal \
+  --plugin-ports-dir ./fpasoterm-plugins --enable
+```
+
+`--plugin-ports-dir` には `ports/` を含むcheckoutを明示します。指定しない`--plugin-install`は公式GitHub repositoryから対象portを取得します。指定した場合はlocal installerとして`port.toml`、metadata、必要なfpasoterm versionを検証し、該当plugin sourceだけをcopyします。local経路はnetworkへ接続しません。
+
+ports checkout外にある信頼済みの単独pluginをcopyする場合は、source fileを明示します。
+
+```sh
+fpasoterm --plugin-install-file ~/work/my-plugins/team-banner.ts --enable
+```
+
+どちらのlocal commandもfpasoterm plugin headerとrenderer API markerを持つ通常の`.js`または`.ts` fileだけを受け付けます。既存fileは`--force`を指定しない限り置き換えません。
+
+subdirectory に同名 file がある場合は、`team/status-banner.ts` のように `plugins` からの相対 path を指定してください。
+
+### Windows packaged binary
+
+MSI/EXEでは`fpasoterm.exe --plugin-install <category/name>`を`--plugin-ports-dir`の有無にかかわらず使用でき、`--plugin-install-file`も直接使用できます。Node.jsは不要です。Windows source checkoutで実行する場合だけ`fpasoterm.cmd`を使用します。
+
+起動時は、trusted な `User/plugins` source または生成されたTypeScript cacheをTauriのlocal asset protocol経由で読み込みます。標準の`User` directoryが対象です。pluginを有効化または編集した後は、対象のfpasoterm windowを閉じて再起動してください。読み込みerrorを調べる場合は、`fpasoterm --foreground --console-diagnostics`で起動し、`plugin loaded` または `failed to load plugin` を確認します。
+
+各pluginは個別のfunction scopeで評価します。そのため、複数のpluginがそれぞれtop-levelで`const`や`let`を使用しても衝突しません。共有APIには`window.fpasotermPluginApi`を使用してください。
+
+## plugin API
+
+対応 API は [`docs/fpasoterm-plugin.d.ts`](fpasoterm-plugin.d.ts) に定義されています。この repository 内で TypeScript plugin を作成する場合は、先頭に次を追加します。
+
+```ts
+/// <reference path="../../docs/fpasoterm-plugin.d.ts" />
+```
+
+install 後の plugin では declaration file をローカルへコピーし、reference path を調整できます。API は `window.fpasotermPluginApi` として利用でき、次を提供します。
+
+- `terminal`: text の出力、terminal の focus、対応する terminal option の変更。
+- `fitAddon`: layout 関連 option を変更した後の `fit()` 実行。
+- `config`: `plugins.enabled` を含む解決済み runtime config の参照。
+- `log(message)`: plugin prefix 付き diagnostics の出力。
+- `version`: 実行中の fpasoterm version と build identifier の参照。
+- `getOfficialPluginIndex()`: `fpasoterm --plugin-search` と同じ固定公式
+  `INDEX`からmetadataを取得します。plugin sourceのdownload、install、enable、実行は
+  行いません。
+- `onReady(callback)`: terminal backend の起動成功後に一度だけ code を実行。
+- `registerCommand(id, title, handler)`: 既存 hamburger menu の `Plugins` submenu配下へ
+  action buttonを追加する。loaded pluginが一つ以上commandを登録した場合だけsubmenuを表示する。pluginを
+  有効化しただけでは実行するhandlerがないため、buttonは追加しない。
+
+現在のrepository内sampleはすべて一つのcommandを登録します。最新版の`hello.ts`、`status-banner.ts`、
+`theme.ts`、`welcome-banner.ts`を有効化すると、4つのbuttonが表示されるのが正しい動作です。古いlocal sampleが
+commandを登録しない場合もplugin自体は有効で起動時処理を実行できますが、意図してmenuには表示しません。sourceと
+versionは`--plugin-info <file>`で確認し、local plugin fileを差し替えた後はwindowを再起動してください。
+
+plugin は小さく防御的に実装してください。読み込み error は diagnostics に記録され、後続の有効 plugin の読み込みは継続します。ただし、実行中の不正な plugin は renderer に影響する可能性があります。
+
+登録した command は既存 menu の Tab / 矢印キー操作で選択できます。`Ctrl+Shift+P` は `Log Show` に割り当て済みのため維持します。将来 command palette を追加する場合も、同じ command registry を plugin source の変更なしに利用できます。
+
+## Sample と Ports
+
+repository内の`examples/plugins/`は最小のAPI参照用です。install可能なsample、appearance theme、metadata、compatibility validation、updateは [fpasoterm-plugins](https://github.com/oyoguhito/fpasoterm-plugins) で管理します。
+
+`config.toml` の全設定は [設定](config.ja.md) を参照してください。

package/docs/pr-review.en.md

@@ -0,0 +1,177 @@
+# Pull Request Review
+
+Ordinary pull requests do not include release artifacts by default. Release
+artifacts are generated from version tags by the `Release` workflow and uploaded
+to GitHub Releases.
+
+Use this document when a reviewer asks what to test when no downloadable PR
+artifact is available.
+
+## Source Checkout Review
+
+Use this path when the reviewer can build on the target OS.
+
+```sh
+gh pr checkout <number> --repo oyoguhito/fpasoterm
+npm install
+npm run check
+```
+
+Without GitHub CLI:
+
+```sh
+git fetch origin pull/<number>/head:review-pr-<number>
+git switch review-pr-<number>
+npm install
+npm run check
+```
+
+`git fetch` only downloads remote references; it does not change the current
+working tree. Always run `git switch` or `git checkout` before building.
+
+Prerequisites are Node.js 22+, Rust stable, and the native target tools: Xcode
+Command Line Tools on macOS, or Visual Studio Build Tools with **Desktop
+development with C++** plus the Edge WebView2 Runtime on Windows. If no local
+checkout exists yet, clone first with
+`git clone https://github.com/oyoguhito/fpasoterm.git` and `cd fpasoterm`.
+
+## Windows MSI Review
+
+Run these commands from PowerShell in the repository root. The PR-number ref
+avoids guessing the head branch name:
+
+```powershell
+git fetch origin pull/<number>/head:review-pr-<number>
+git switch review-pr-<number>
+git status --short
+git log -1 --oneline
+npm ci
+npm run check
+npm run build:bundles
+```
+
+The empty `git status --short` and the final `git log` line confirm the exact
+revision that is being packaged. `git fetch` alone leaves the current branch
+unchanged and must not be used as the build step.
+
+First test the built executable directly, which cannot accidentally launch an
+older Start menu, pinned, or Path entry. Use the generated `.cmd` wrapper for
+CLI output so PowerShell waits for the GUI-subsystem executable:
+
+```powershell
+.\src-tauri\target\release\fpasoterm.cmd --version
+.\src-tauri\target\release\fpasoterm.exe
+```
+
+Then test the actual Node launcher behavior required by PRs that change CLI
+startup. It must print a status line and return the PowerShell prompt without
+waiting for the window:
+
+```powershell
+node .\bin\fpasoterm
+Get-Content "$env:LOCALAPPDATA\fpasoterm\launcher.log" -Tail 40
+```
+
+The log should contain `cargo-build-start` / `cargo-build-complete` only when a
+local build was required, followed by `desktop-spawned` and elapsed times.
+
+Then open `Help` in the application and verify that `Config:` names the file
+being edited, and that the expected PR UI is present.
+
+An unreleased PR commonly has the same package version as an installed build.
+Close every fpasoterm process before installing its MSI, then force Windows
+Installer to reinstall the package rather than retaining its same-version
+installation:
+
+```powershell
+Get-Process fpasoterm -ErrorAction SilentlyContinue | Stop-Process -Force
+$msi = Get-ChildItem .\artifacts\*.msi | Sort-Object LastWriteTime -Descending | Select-Object -First 1
+& msiexec.exe /i $msi.FullName REINSTALL=ALL REINSTALLMODE=vomus
+if ($LASTEXITCODE -notin 0, 3010) { throw "MSI install failed: $LASTEXITCODE" }
+```
+
+Exit code `3010` means Windows requires a restart. Launch the installed app
+from its updated Start menu shortcut after this step. When only functional
+review is needed, prefer the direct release executable above; it is the most
+reliable way to prove the PR branch is running.
+
+## Windows Direct Binary Review
+
+For changes that affect direct `fpasoterm.exe` behavior, build and run the
+Windows binary from the PR branch.
+
+Debug build:
+
+```powershell
+cargo build --manifest-path src-tauri/Cargo.toml
+.\src-tauri\target\debug\fpasoterm.exe --help
+.\src-tauri\target\debug\fpasoterm.exe --size 1200x800 --title "PR test" --titlebar-color "#2e7d32"
+```
+
+Release-style local build:
+
+```powershell
+npm run build
+.\src-tauri\target\release\fpasoterm.exe --help
+```
+
+Expected behavior:
+
+- `--help` exits before opening the GUI window and prints usage text.
+- `--size` changes the initial window size.
+- `--title` changes the custom titlebar text.
+- `--titlebar-color` changes the custom titlebar color.
+
+## macOS App Bundle Review
+
+Run these commands in Terminal from the repository root. Build natively on the
+architecture being reviewed: Apple Silicon builds arm64, while an Intel Mac
+builds x64.
+
+```sh
+git fetch origin pull/<number>/head:review-pr-<number>
+git switch review-pr-<number>
+git status --short
+git log -1 --oneline
+npm ci
+npm run check
+npm run build:bundles
+./src-tauri/target/release/fpasoterm --version
+node ./bin/fpasoterm
+tail -40 ~/.cache/fpasoterm/launcher.log
+```
+
+`node ./bin/fpasoterm` is the command to use when reviewing launcher behavior:
+it must print a cached-runtime or Cargo-build status and return the Terminal
+prompt before the window appears. Use `--foreground --console-diagnostics` only
+to intentionally wait for compiler and application output.
+
+Open the locally built app bundle separately to review the icon and Finder/App
+bundle behavior:
+
+```sh
+open -n ./src-tauri/target/release/bundle/macos/fpasoterm.app
+```
+
+If macOS blocks an unsigned local build, use Finder's **Open** action and
+approve it in Privacy & Security. Do not substitute an older tagged DMG for the
+PR branch build.
+
+## If There Is No Artifact
+
+If there is no downloadable artifact on the PR, the review target is the PR
+branch itself. The reviewer should check out the PR branch, install dependencies,
+run the local checks, and build a local debug or release binary for the target
+OS.
+
+Do not use tag release assets as substitutes for PR artifacts, because those
+assets were built from a version tag, not from the pull request branch.
+
+## When PR Artifacts Are Required
+
+If reviewers need downloadable `.exe`, `.msi`, `.deb`, `.rpm`, `.dmg`, or app
+archives for every pull request, add a separate `pull_request` artifact workflow.
+That workflow should build from the PR branch and upload GitHub Actions
+artifacts, but it should not publish a GitHub Release.
+
+Keep the tag-based `Release` workflow for official versioned releases.