gemiterm 2.0.0

package/README.md

@@ -0,0 +1,245 @@
+# GemiTerm
+
+Access and manage your Gemini web chats from the command line. GemiTerm bridges Playwright-based Google authentication to let you list, fetch, export, continue, and delete conversations trapped in the Gemini web interface — without a standard API. Built with [Bun](https://bun.sh) and TypeScript.
+
+## Prerequisites
+
+- **[Bun](https://bun.sh)** runtime
+- **Chromium Browser** — GemiTerm uses your system Chrome/Edge if available, otherwise installs Playwright's Chromium automatically
+- **Google Account** with access to [Gemini](https://gemini.google.com)
+
+## Installation
+
+See [docs/INSTALL.md](docs/INSTALL.md) for the full guide, uninstall instructions, troubleshooting, and build-from-source steps.
+
+**Windows** (PowerShell 7+):
+
+```powershell
+irm https://github.com/expert-vision-software/GemiTerm/releases/latest/download/install.ps1 | iex
+```
+
+**Linux / WSL**:
+
+```bash
+curl -fsSL https://github.com/expert-vision-software/GemiTerm/releases/latest/download/install.sh | bash
+```
+
+> **Upgrading from v1.4.1?** Your profiles, cookies, and default profile marker are preserved. The installer replaces the binary in place; it does NOT touch your config dir. See the "Upgrade from v1.4.1" section in [docs/INSTALL.md](docs/INSTALL.md) for details.
+
+## Quick Start
+
+```bash
+gemiterm auth          # authenticate with Google
+gemiterm list          # list your chats
+```
+
+## Development
+
+```bash
+bun install
+bun run dev              # run the CLI
+bun test                 # run tests (Bun test runner)
+bun run typecheck        # TypeScript type checking
+bun run build            # compile to standalone Bun binary
+bun run build:linux      # cross-compile for Linux x64
+bun run build:windows    # cross-compile for Windows x64
+```
+
+For installing Chromium, use the platform-specific wrapper scripts:
+```bash
+bash scripts/install-browser.sh   # Linux/macOS
+pwsh scripts/install-browser.ps1 # Windows
+```
+
+## Building from source
+
+GemiTerm is built with [Bun](https://bun.sh) 1.3.13 or later.
+
+```bash
+bun run build            # native binary (dist/gemiterm or dist/gemiterm.exe)
+bun run build:linux      # Linux x64 binary (dist/gemiterm)
+bun run build:windows    # Windows x64 binary (dist/gemiterm.exe)
+bun run build:release    # minified release binary (dist/gemiterm)
+```
+
+Output paths:
+- **Linux/macOS**: `dist/gemiterm`
+- **Windows**: `dist/gemiterm.exe`
+
+## Release artifacts
+
+The v2.0.0 release ships the following GitHub Release assets:
+- `GemiTerm` — Linux x64 binary
+- `GemiTerm.exe` — Windows x64 binary
+- `install.sh` — POSIX installer script
+- `install.ps1` — Windows PowerShell installer script
+
+## Usage
+
+### Authentication
+
+```bash
+gemiterm auth
+```
+
+Opens a browser window to log in with your Google account. Cookies are saved for future use.
+
+### Check Status
+
+```bash
+gemiterm status
+```
+
+Shows the config directory and a table of all profiles with their authentication state.
+
+### List Chats
+
+```bash
+gemiterm list
+```
+
+Options:
+- `-n, --limit N`: Maximum number of chats (default: 10)
+- `--offset N`: Skip first N chats (default: 0)
+- `--sort <recent|oldest|alpha>`: Sort order
+- `-s, --search <query>`: Filter by title
+- `--after <date>`: Only chats after this date
+- `--before <date>`: Only chats before this date
+- `--all`: Show all chats (no limit)
+- `--all-profiles`: Merge chats from all profiles
+- `-f, --format <text|json>`: Output format
+- `-p, --path <path>`: Save output to file
+
+### Fetch Chat History
+
+```bash
+gemiterm fetch <conversation_id>
+```
+
+Options:
+- `-f, --format <text|json>`: Output format
+- `-p, --path <path>`: Save output to file
+
+### Continue a Chat
+
+```bash
+gemiterm continue <conversation_id> [message]
+```
+
+Without a message, enters an interactive REPL session. Without a conversation ID, falls back to `list`.
+
+### Start a New Chat
+
+```bash
+gemiterm new [message]
+```
+
+Options:
+- `-p, --profile <name>`: Use a specific profile
+
+Without a message, enters an interactive REPL session.
+
+### Export Chat
+
+```bash
+gemiterm export <conversation_id>
+```
+
+Options:
+- `-o, --output <path>`: Custom output file path
+- `-f, --format <markdown|json>`: Export format (default: markdown)
+- `--include-metadata`: Include full metadata in export
+
+### Export All Chats
+
+```bash
+gemiterm export-all
+```
+
+Options:
+- `-o, --output-dir <dir>`: Output directory (default: `./exports`)
+- `--since <date>`: Only chats newer than this date
+- `--include-metadata`: Include full metadata
+- `-a, --all-profiles`: Export from all profiles
+
+Creates an `index.md` with links to all exported files.
+
+### Delete a Chat
+
+```bash
+gemiterm delete <conversation_id>
+```
+
+Options:
+- `-f, --force`: Skip confirmation prompt
+
+### Manage Profiles
+
+```bash
+gemiterm profile list                    # list all profiles
+gemiterm profile add <name>               # add a new profile
+gemiterm profile delete <name>            # delete a profile
+gemiterm profile rename <name> <newName>  # rename a profile
+gemiterm profile default <name>          # set default profile
+```
+
+### Install Browser
+
+```bash
+gemiterm install-browser
+```
+
+Checks for system Chrome/Edge first, falls back to installing Playwright's Chromium.
+
+### Verbose Logging
+
+```bash
+gemiterm -v <command>
+```
+
+## Configuration
+
+### Configuration Directory
+
+Default locations:
+- **Binary**: `$env:LOCALAPPDATA\GemiTerm\` (Windows), `~/.local/bin/gemiterm` (Linux/macOS)
+- **Config**: `%APPDATA%\gemiterm\` (Windows), `~/gemiterm/` (Linux/macOS)
+
+Override with:
+```bash
+export GEMITERM_CONFIG_DIR=/custom/path
+```
+
+### Profile Storage
+
+```
+gemiterm/
+  profiles/
+    .default              # text file with default profile name
+    <profile-name>/
+      storage_state.json  # authentication cookies
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GEMITERM_CONFIG_DIR` | Configuration directory | Platform default |
+
+## Architecture
+
+```
+src/
+  cli/            # CLI commands, argument parsing, output formatting
+  core/           # Mediator pattern (CQRS), typed commands/queries, handlers, domain types
+  services/       # Business logic: auth flow, cookie management, Gemini API client
+  infrastructure/  # Config, file I/O, logging, validation, formatters
+tests/
+  cli/            # CLI command tests
+  core/           # Query handler tests
+  services/       # Service layer tests
+  infrastructure/  # Infrastructure tests
+  fixtures/       # Shared test fixtures
+```
+
+Core uses a **Mediator pattern** with typed Command/Query messages dispatching to registered handlers, decoupling CLI commands from business logic.

package/bun.lock

@@ -0,0 +1,105 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "gemiterm-bun-rewrite",
+      "dependencies": {
+        "chalk": "^5.6.2",
+        "cli-table3": "^0.6.5",
+        "gemini-reverse": "^1.0.12",
+      },
+      "devDependencies": {
+        "@types/bun": "^1.3.14",
+      },
+      "peerDependencies": {
+        "typescript": "^6.0.3",
+      },
+    },
+  },
+  "packages": {
+    "@colors/colors": ["@colors/colors@1.5.0", "", {}, "sha512-ooWCrlZP11i8GImSjTHYHLkvFDP48nS4+204nGb1RiX/WXYHmJA2III9/e2DWVabCESdW7hBAEzHRqUn9OUVvQ=="],
+
+    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
+
+    "@types/node": ["@types/node@25.9.2", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-G05zqtJhcDLb8uslf5EjCxXg9G1KQxiV8OS0R26IC//Eoyitzqe8z37I7cqvnZlrlSfgocQRfSn/AHBZJJFyGw=="],
+
+    "agent-base": ["agent-base@6.0.2", "", { "dependencies": { "debug": "4" } }, "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ=="],
+
+    "ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
+
+    "asynckit": ["asynckit@0.4.0", "", {}, "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q=="],
+
+    "axios": ["axios@1.17.0", "", { "dependencies": { "follow-redirects": "^1.16.0", "form-data": "^4.0.5", "https-proxy-agent": "^5.0.1", "proxy-from-env": "^2.1.0" } }, "sha512-J8SwNxprqqpbfenehxWYXE7CW+wM1BB4w3+N+g+/Wx40xM4rsLrfPmHHxSWIxJLYDgSY/HqlFPIYb2/S3rxafw=="],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
+    "call-bind-apply-helpers": ["call-bind-apply-helpers@1.0.2", "", { "dependencies": { "es-errors": "^1.3.0", "function-bind": "^1.1.2" } }, "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ=="],
+
+    "chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
+
+    "cli-table3": ["cli-table3@0.6.5", "", { "dependencies": { "string-width": "^4.2.0" }, "optionalDependencies": { "@colors/colors": "1.5.0" } }, "sha512-+W/5efTR7y5HRD7gACw9yQjqMVvEMLBHmboM/kPWam+H+Hmyrgjh6YncVKK122YZkXrLudzTuAukUw9FnMf7IQ=="],
+
+    "combined-stream": ["combined-stream@1.0.8", "", { "dependencies": { "delayed-stream": "~1.0.0" } }, "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg=="],
+
+    "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
+
+    "delayed-stream": ["delayed-stream@1.0.0", "", {}, "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ=="],
+
+    "dunder-proto": ["dunder-proto@1.0.1", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.1", "es-errors": "^1.3.0", "gopd": "^1.2.0" } }, "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A=="],
+
+    "emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="],
+
+    "es-define-property": ["es-define-property@1.0.1", "", {}, "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g=="],
+
+    "es-errors": ["es-errors@1.3.0", "", {}, "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw=="],
+
+    "es-object-atoms": ["es-object-atoms@1.1.2", "", { "dependencies": { "es-errors": "^1.3.0" } }, "sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw=="],
+
+    "es-set-tostringtag": ["es-set-tostringtag@2.1.0", "", { "dependencies": { "es-errors": "^1.3.0", "get-intrinsic": "^1.2.6", "has-tostringtag": "^1.0.2", "hasown": "^2.0.2" } }, "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA=="],
+
+    "follow-redirects": ["follow-redirects@1.16.0", "", {}, "sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw=="],
+
+    "form-data": ["form-data@4.0.5", "", { "dependencies": { "asynckit": "^0.4.0", "combined-stream": "^1.0.8", "es-set-tostringtag": "^2.1.0", "hasown": "^2.0.2", "mime-types": "^2.1.12" } }, "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w=="],
+
+    "function-bind": ["function-bind@1.1.2", "", {}, "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA=="],
+
+    "gemini-reverse": ["gemini-reverse@1.0.12", "", { "dependencies": { "axios": "^1.13.6", "form-data": "^4.0.5", "uuid": "^13.0.0" } }, "sha512-k1k3uxQQ9LIX2c0iWbyeG6JPPMAYVP8K1AQWvmtNqiMhePr6XY5QCOXLy5NzZ94q12m/a0N+p3vQRQKWFhHx5Q=="],
+
+    "get-intrinsic": ["get-intrinsic@1.3.0", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.2", "es-define-property": "^1.0.1", "es-errors": "^1.3.0", "es-object-atoms": "^1.1.1", "function-bind": "^1.1.2", "get-proto": "^1.0.1", "gopd": "^1.2.0", "has-symbols": "^1.1.0", "hasown": "^2.0.2", "math-intrinsics": "^1.1.0" } }, "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ=="],
+
+    "get-proto": ["get-proto@1.0.1", "", { "dependencies": { "dunder-proto": "^1.0.1", "es-object-atoms": "^1.0.0" } }, "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g=="],
+
+    "gopd": ["gopd@1.2.0", "", {}, "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg=="],
+
+    "has-symbols": ["has-symbols@1.1.0", "", {}, "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ=="],
+
+    "has-tostringtag": ["has-tostringtag@1.0.2", "", { "dependencies": { "has-symbols": "^1.0.3" } }, "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw=="],
+
+    "hasown": ["hasown@2.0.4", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A=="],
+
+    "https-proxy-agent": ["https-proxy-agent@5.0.1", "", { "dependencies": { "agent-base": "6", "debug": "4" } }, "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA=="],
+
+    "is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="],
+
+    "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
+
+    "mime-db": ["mime-db@1.52.0", "", {}, "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg=="],
+
+    "mime-types": ["mime-types@2.1.35", "", { "dependencies": { "mime-db": "1.52.0" } }, "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw=="],
+
+    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
+
+    "proxy-from-env": ["proxy-from-env@2.1.0", "", {}, "sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA=="],
+
+    "string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
+
+    "strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
+
+    "typescript": ["typescript@6.0.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw=="],
+
+    "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+
+    "uuid": ["uuid@13.0.2", "", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-vzi9uRZ926x4XV73S/4qQaTwPXM2JBj6/6lI/byHH1jOpCzb0zDbfytgA9LcN/hzb2l7WQSQnxITOVx5un/wGw=="],
+  }
+}

package/docs/INSTALL.md

@@ -0,0 +1,185 @@
+# Installation Guide
+
+The installer scripts are attached to every GitHub release by the `release.yml` workflow. If you see a 404 on the one-liner URL, the release pipeline (owned by the `cross-platform-build-and-ci` change) may not have attached the scripts; check the GitHub release page directly.
+
+## Install
+
+**Windows** (PowerShell 7+):
+
+```powershell
+irm https://github.com/expert-vision-software/GemiTerm/releases/latest/download/install.ps1 | iex
+```
+
+**Linux / WSL**:
+
+```bash
+curl -fsSL https://github.com/expert-vision-software/GemiTerm/releases/latest/download/install.sh | bash
+```
+
+> **Recommended install via package manager.** If you have `bun` or `npm` on PATH, the installer will detect it and prompt: "It is recommended to install via bun or npm package manager. Are you sure you want to continue with binary install?" Answer `y` to proceed with the binary drop, or install via:
+> - `bun i -g gemiterm`
+> - `npm i -g gemiterm`
+>
+> The prompt is suppressed when stdin is not a TTY (e.g. the `curl | bash` one-liner flow), so unattended installs proceed.
+
+## Upgrade from v1.4.1
+
+Your profiles, cookies, and default-profile marker are preserved. The installer replaces the binary in place; it does **NOT** touch `%APPDATA%\gemiterm\` (Windows) or `~/gemiterm/` (POSIX). This is verified by the path-resolution logic in `src/infrastructure/path-utils.ts` — the v2.0.0 binary reads from the same config directory that v1.4.1 wrote to.
+
+On Windows, the v1.4.1 Python config lived at `%USERPROFILE%\.config\gemiterm\` (Python's `Path.home() / ".config/gemiterm"` has no Windows branch). When the installer detects a v1.4.1 config at that path and no v2.0.0 config at `%APPDATA%\gemiterm\`, it copies the tree forward automatically. The v1.4.1 directory is left in place as a safety net — you can delete it manually after verifying the migration.
+
+On POSIX, the v1.4.1 Python config lived at `~/.config/gemiterm/`. v2.0.0 reads from `~/gemiterm/`. The installer performs the same one-time copy-forward when it detects the old path.
+
+If you have the Python v1.4.1 version installed via `pip`, the installer will detect it and ask you to run `pip uninstall gemiterm` first. Your config data is safe and will be preserved through the uninstall/reinstall cycle.
+
+## Uninstall
+
+**Windows**:
+
+```powershell
+pwsh -File install.ps1 -Uninstall
+```
+
+**Linux / WSL**:
+
+```bash
+bash install.sh --uninstall
+```
+
+Uninstall removes the binary and PATH entry but **preserves** your config directory (profiles, cookies, default-profile marker). Re-installing afterward will find the same profiles as before.
+
+## Data Paths
+
+| Path | Windows | Linux / WSL |
+|------|---------|-------------|
+| **Binary** | `$env:LOCALAPPDATA\GemiTerm\GemiTerm.exe` | `~/.local/bin/gemiterm` |
+| **Config** | `%APPDATA%\gemiterm\` | `~/gemiterm/` |
+| **Chromium cache** | `$env:LOCALAPPDATA\ms-playwright\` | `~/.cache/ms-playwright/` |
+
+> **Note:** On Windows, the install directory is **capital G** (`GemiTerm`) while the config directory is **lowercase** (`gemiterm`). This matches the v1.4.1 convention and is intentional.
+
+## Tag Override (Canary / RC Installs)
+
+To install a specific release instead of the latest:
+
+**Windows**:
+
+```powershell
+pwsh -File install.ps1 -Tag v2.0.0-rc.1
+```
+
+**Linux / WSL**:
+
+```bash
+GEMITERM_TAG=v2.0.0-rc.1 bash install.sh
+```
+
+## Custom Install Directory
+
+**Windows**:
+
+```powershell
+pwsh -File install.ps1 -InstallDir D:\Tools\GemiTerm
+```
+
+**Linux / WSL**:
+
+```bash
+GEMITERM_INSTALL_DIR=~/.local/bin bash install.sh
+```
+
+## Troubleshooting
+
+### PATH did not refresh in current shell
+
+After installing, if `gemiterm` is not found:
+
+**Windows** — reload your PATH in the current PowerShell session:
+
+```powershell
+$env:Path = [Environment]::GetEnvironmentVariable('Path', 'User')
+gemiterm --version
+```
+
+Or open a new terminal.
+
+**Linux / WSL** — source the env snippet:
+
+```bash
+source ~/gemiterm/env.sh
+gemiterm --version
+```
+
+Or open a new terminal.
+
+### Chromium installation fails
+
+The installer runs `bunx @playwright/cli install chromium` as part of the install flow. If it fails:
+
+1. Check your network connection (Chromium is ~100 MB).
+2. Re-run the installer.
+3. Or manually run: `bunx @playwright/cli install chromium`
+
+### Cannot reach GitHub releases
+
+If the installer cannot contact `api.github.com`:
+
+1. Check your network connection.
+2. Use the **Build from source** instructions below.
+
+### Bun not installed
+
+The installer automatically bootstraps [Bun](https://bun.sh) if it is not found. If the bootstrap fails:
+
+1. Install Bun manually from [bun.sh](https://bun.sh).
+2. Re-run the installer.
+
+### fish / nushell users
+
+The POSIX installer appends a `source` line to `~/.bashrc` and `~/.zshrc`. For other shells, add the PATH manually:
+
+**fish** (`~/.config/fish/config.fish`):
+
+```fish
+set -gx PATH ~/.local/bin $PATH
+```
+
+**nushell** (`~/.config/nushell/config.nu`):
+
+```nu
+$env.PATH = ($env.PATH | prepend ~/.local/bin)
+```
+
+## Build from Source
+
+Requires [Bun](https://bun.sh) 1.3.13 or later.
+
+```bash
+git clone https://github.com/expert-vision-software/GemiTerm.git
+cd GemiTerm
+bun install
+bun run build
+```
+
+The resulting binary is at `dist/gemiterm` (Linux/macOS) or `dist/gemiterm.exe` (Windows). Move it to the install path:
+
+**Linux / WSL**:
+
+```bash
+mkdir -p ~/.local/bin
+mv dist/gemiterm ~/.local/bin/gemiterm
+chmod +x ~/.local/bin/gemiterm
+```
+
+**Windows**:
+
+```powershell
+mkdir $env:LOCALAPPDATA\GemiTerm
+Move-Item dist\gemiterm.exe $env:LOCALAPPDATA\GemiTerm\GemiTerm.exe
+```
+
+Then install Chromium:
+
+```bash
+bunx @playwright/cli install chromium
+```