packaging: publish nexusterminal to repo.dixon.cx and Homebrew; install instructions

- packaging/repo.sh: download release assets over HTTPS (no GitHub API),
  show nfpm errors, PKGREL for packaging-only revisions, and declare ALSA
  as a hard dependency (the release binary links libasound.so.2), with
  libasound2t64 preferred so Ubuntu 24.04 doesn't pick the OSS shim.
  Verified by clean installs on Debian 12/13, Ubuntu 22.04/24.04,
  Fedora 42 and Arch.
- README: Install section (Homebrew cask, apt, dnf/zypper, pacman, zips).

.github/copilot-instructions.md

@@ -1,109 +1,86 @@
 # Copilot Instructions — Nexus Terminal
 
+Nexus Terminal is a native desktop client (SSH, Telnet, RAW TCP, Serial, VNC, IRC, GitHub, local shell) written in Rust with an eframe/egui UI. All the code lives in the Cargo workspace under `rust/`.
+
 ## Build & Test
 
 ```bash
-make deps              # go mod download + npm install
-make build             # production build → build/bin/nexus-terminal.app
-make dev               # wails dev with hot reload
-make test              # go test ./... -v -count=1
-make lint              # golangci-lint run ./...
+cd rust
+cargo run --release                                     # the app (binary `nexus-terminal`)
+cargo test --workspace                                  # unit and integration tests
+cargo clippy --workspace --all-targets -- -D warnings   # must be clean
+cargo fmt --all --check                                 # must be clean
 
-# Single package test
-go test ./internal/storage/ -v -count=1 -run TestProfileCRUD
+# Single test
+cargo test -p nexus-core --lib storage::
+cargo test -p nexus-core --test ssh_integration
 ```
 
-The frontend has no separate build step — `npm run build` (called by Wails) copies xterm vendor libs from `node_modules` into `frontend/src/js/lib/` and `frontend/src/css/lib/`. All frontend assets are embedded at compile time via `frontend/embed.go`.
+CI (`.github/workflows/ci.yml`) runs `cargo test --locked`, `cargo fmt --check` and `cargo clippy --all-targets -D warnings` on Linux, macOS and Windows. The toolchain is pinned in `rust/rust-toolchain.toml`. Platform prerequisites and release packaging are in `docs/build-and-release.md`.
 
 ## Architecture
 
-Wails v2 desktop app: Go backend + HTML/CSS/JS frontend rendered in a native webview (WKWebView on macOS).
+The project is engine-first: a UI-free core crate, and the egui app is one client of it.
 
-**Go backend** (`internal/`):
-- `app/` — lifecycle bootstrap: opens SQLite, inits secret stores, wires everything together
-- `api/` — single `Service` struct bound to Wails; every public method is callable from JS as `window.go.api.Service.MethodName()`
-- `sessions/` — manages concurrent protocol sessions; owns SSH/Telnet/RAW/GitHub client lifecycles; handles auto-reconnect, login scripts, broadcast
-- `storage/` — SQLite repository (WAL mode) with embedded sequential migrations in `storage/migrations/`
-- `secrets/` — two-tier credential storage: OS keychain (preferred) → AES-256-GCM encrypted file vault (fallback)
-- `models/` — shared domain types and defaults; protocol configs are JSON-encoded in the DB
-- `sshclient/` — SSH client with agent, TOTP/2FA, and SOCKS5/HTTP proxy support
-- `telnetclient/`, `rawclient/`, `githubclient/` — protocol implementations
-- `sftpclient/` — SFTP file operations (browse, upload, download, rename, delete)
-- `sshconfig/` — OpenSSH `~/.ssh/config` parser and importer
-- `recording/` — asciicast v2 session recording and playback
-- `exportimport/` — encrypted profile bundles (.nexus format)
-- `updater/` — GitHub Releases update checker
-- `knownhosts/` — SSH host key management
-- `validation/` — profile and protocol validation
-- `audit/` — timestamped audit logging
+```
+rust/
+├── core/   nexus-core: storage, secrets, models, protocol clients, session Manager, Service. No egui.
+│   ├── migrations/       numbered SQL migrations, embedded with include_str!
+│   └── tests/            sessions.rs, ssh_integration.rs, fixtures/
+└── app/    nexus: the egui shell (binary `nexus-terminal`)
+```
 
-**Frontend** (`frontend/`):
-- Plain HTML/CSS/JS — no framework, no bundler, no ES modules
-- `index.html` is the app shell; loads CSS then JS in strict order
-- `src/js/` — 18 modules, each IIFE-wrapped, exporting to `window.NexusTerminal`
-- `src/css/` — modular stylesheets; `tokens.css` defines all design tokens
-- Vendor libs (xterm.js, addons) live in `src/js/lib/` and `src/css/lib/` — auto-copied, gitignored
+**Core (`rust/core/src/`):**
+- `service.rs` — `Service`, the app-facing API: profiles, connect/reconnect, credentials, known hosts, preferences, snippets, import/export, SSH keys, SFTP, updates. File dialogs live in the UI; methods here take paths.
+- `sessions.rs` — `Manager`: concurrent sessions, auto-reconnect with backoff, login scripts, broadcast writes, recording hooks, secret resolution (saved / session-only / ask every time), host-key checks. It reports through one `Event` enum (`Data`, `State`, `Closed`, `RawData`, `Irc`, `Github*`, `Forward*`, `Recording*`, `SftpProgress`, `SecretPrompt`, `HostKeyVerify`, `Vnc*`).
+- `clients/` — one module per protocol (`ssh`, `sftp`, `telnet`, `raw`, `serial`, `local`, `irc`, `github`, `vnc`). Read the conventions at the top of `clients/mod.rs` before touching one: `connect()` blocks its (worker) thread and returns once usable; the client then owns its reader thread(s) and reports through `Callbacks` (data, fatal error, close exactly once); `write`/`resize`/`close` are callable from any thread and `close` is idempotent. russh-based clients use the shared tokio runtime from `clients::rt()`; the rest use plain threads.
+- `storage.rs` (SQLite via rusqlite, WAL), `secrets.rs` (keychain + vault), `config.rs` (data directories and Alchementary Link migration), `models.rs`, `validation.rs`, `exportimport.rs`, `recording.rs` (asciicast v2), `sshconfig.rs`, `updater.rs`, `ircformat.rs`, `terminalenv.rs`, `keyfiles.rs`.
 
-**Go ↔ JS communication:**
-- **Synchronous:** Frontend calls `window.go.api.Service.*()` (returns Promise)
-- **Asynchronous:** Backend pushes events via `wailsRuntime.EventsEmit()`; frontend listens with `window.runtime.EventsOn()`
-- **Bidirectional events** for secret prompts and host key verification: backend emits a request event with a `requestID`, frontend shows a modal, then emits a response event with the same ID. The Go side blocks on a channel keyed by that ID.
+**App (`rust/app/src/`):**
+- `main.rs` parses flags, opens the `Service` and starts eframe. `app.rs` owns `App`: it installs an event sink that forwards `Event`s over a channel and calls `request_repaint`, drains them each frame (`on_event`), handles `Request`s, the keyboard shortcuts (`shortcuts()`), and lays out the frame.
+- `state.rs` — `Shared` (service handle, cached profiles and preferences, tabs, panes, toasts) and the `Request` queue features use to ask the main window to act.
+- `views.rs` — `View::{Terminal, Raw, Irc, Github, Vnc}`, one per pane.
+- `terminal.rs` (`TermView`: alacritty_terminal drawn with egui's painter), `tabs.rs` (tab strip, workspace, find bar, overlays), `splits.rs` (split tree), `sidebar.rs`, `chrome.rs` (title bar, status bar, command palette `Cmd` enum, prompts, dialogs, toasts).
+- Feature windows: `profile_editor.rs`, `quick_connect.rs`, `settings.rs` (including the Help topics), `ssh_keys.rs`, `transfer.rs` (import/export), `sftp.rs`, `forwards.rs`, `snippets.rs`, `triggers.rs`, `recordings.rs`.
+- Protocol views: `raw_view.rs`, `irc_view.rs`, `github_view.rs`, `vnc_view.rs`.
 
-Key events: `session:data`, `session:state`, `session:closed`, `session:raw:data`, `session:github:repos`, `session:secret:prompt`/`session:secret:response`, `session:hostkey:verify`/`session:hostkey:response`.
-
-## WKWebView Constraints (Critical)
-
-The macOS webview silently blocks or breaks several standard web APIs. These constraints affect every frontend change:
-
-1. **No `window.confirm()`, `window.prompt()`, `window.alert()`** — they either return false/null silently or do nothing. All user prompts must use the custom modal system (DOM-based backdrop + modal with `is-visible` class toggling).
-
-2. **No ES modules** — `<script type="module">` fails silently. All JS files use plain `<script>` tags and IIFE wrappers: `(function() { ... })();`
-
-3. **Click swallowing on text-selectable elements** — WKWebView initiates a text selection gesture on `mousedown` for `<div>` elements, which swallows the first `click` event (appears to require double-click). Fix: add `mousedown` handler with `e.preventDefault()` on any clickable non-input element (section headers, list items, etc.).
-
-4. **Modal visibility pattern** — both `.modal-backdrop` AND `.modal` elements start with `opacity: 0; visibility: hidden` in CSS. You must add the `is-visible` class to **both** elements, not just the backdrop.
-
-5. **Wails runtime injection** — `window.go` and `window.runtime` are injected by Wails before scripts execute. Do NOT add explicit script tags for Wails scripts. The frontend polls for their availability at startup (max 5s).
+**Flow:** UI → `Service` / `Manager` method (plain Rust call) → protocol client on a worker thread → `Callbacks` → `Manager` emits `Event` → app channel → `App::on_event` on the next frame. Credential and host-key questions are `Event::SecretPrompt` / `Event::HostKeyVerify` carrying an `mpsc::Sender` reply; the connecting thread blocks on the receiver, and dropping the sender (closing the prompt or the session) cancels it.
 
 ## Conventions
 
-**Language:** All code comments in British English (colour, initialise, behaviour, etc.).
+- **British English** in comments, docs and UI strings (colour, initialise, behaviour, favourite).
+- **Never block the UI thread.** Anything that touches the network, the keychain, `ssh-keygen` or slow disk work runs on a worker thread: `Shared::spawn` (errors become toasts), `settings::Job` (poll a result each frame), or a module's own inbox. Call `ctx.request_repaint()` when the work finishes. Quick SQLite calls through `Service` are fine inline.
+- **Colours come from `Tokens`** (`theme.rs`, `Tokens::get(ctx)`): `text`, `text_dim`, `text_faint`, `accent`, `success`, `warning`, `danger`, `field`, `card`, `dock`, … Don't hard-code colours; all three app themes (Pro, Midnight, Light) must work. Protocol colours and badges come from `views::protocol_color` / `protocol_badge`; terminal palettes from `terminal_themes.rs`.
+- **Icons are Phosphor** (`egui_phosphor::regular as icon`), usually as `format!("{}  Label", icon::X)`. Reuse the helpers in `widgets.rs` (`primary`, `button`, `icon_button`, `hint`, `empty`, `chip`, `section`, `kv`) and `chrome::modal` for modal dialogs.
+- **Shortcut labels** go through `state::keys("Mod+Shift+K")`, which renders ⌘ on macOS and Ctrl elsewhere. A new shortcut needs an entry in `App::shortcuts()`, the command palette (`chrome::commands`), the menu, the Help "Keyboard Shortcuts" topic and the README table.
+- **Formatting:** `rustfmt.toml` sets `max_width = 160` with `use_small_heuristics = "Max"`, so long single-line expressions are normal. Run `cargo fmt --all` rather than wrapping by hand.
+- Errors are `nexus_core::Result<T>` (`Box<dyn Error + Send + Sync>`); use `?` and `format!` messages that read well in a toast.
+- Protocol configs are `Option<…Config>` fields on `Profile` (`ssh`, `telnet`, `raw`, `github`, `vnc`, `irc`, `serial`), stored as JSON columns; `Profile::new(protocol)` fills the defaults, and the structs use `#[serde(default)]` so older rows still load.
+- A `ponytail:` comment marks a deliberate simplification and names its limit; keep them accurate when you change that code.
 
-**Go patterns:**
-- String-typed enums: `type Protocol string` with `const ProtocolSSH Protocol = "ssh"` etc.
-- Protocol configs are pointer fields on `Profile` (`SSH *SSHConfig`, `Telnet *TelnetConfig`, etc.) — nil when not applicable
-- `NewProfile(protocol)` factory in `defaults.go` populates sensible defaults per protocol
-- Storage uses `nullableJSON()` helper to write nil for unused config columns
-- Tests use `t.TempDir()` for isolation, `t.Fatalf()` for setup failures
+**Adding a protocol** touches: `models.rs` (`Protocol`, config struct, defaults, labels), `validation.rs`, a new migration (CHECK constraint and config column) plus the column lists in `storage.rs`, a client in `clients/`, the `Manager` connect/close/write paths in `sessions.rs`, the profile editor section, Quick Connect if relevant, a view (or `TermView` for terminal protocols), `views::protocol_badge`/`protocol_color`, the palette, and a Help topic.
 
-**Frontend patterns:**
-- Every JS file is IIFE-wrapped and exports to `window.NexusTerminal` namespace
-- Script load order matters (defined in `index.html`) — utils → state → notifications → sidebar → tabs → themes → terminal → profiles → raw → github → settings → commands → secrets → recordings → sftp → splitpane → snippets → app
-- DOM helpers: `createElement(tag, className, attrs)` from utils.js (supports `textContent`, `innerHTML`, `dataset`, `on*` event handlers)
-- Profile editor uses `_renderSection(title, fields)` pattern with `_field(type, name, label, value, opts)` helper for form generation
-- Login script editor uses `_renderLoginScriptSection(prefix, steps)` for expect-style step lists
-- TOTP section uses `_renderTOTPSection(profile)` with encrypted vault storage
-- `protocolColour()` returns CSS class names like `proto-ssh`; tab badges use `badge-ssh` class naming (different pattern)
+## Data compatibility (hard rules)
 
-**CSS patterns:**
-- Design tokens in `tokens.css`: `--bg-base`, `--bg-surface`, `--bg-elevated`, `--text-primary`, `--accent`, `--protocol-ssh`, etc.
-- Dark charcoal palette — not Material Design literally, but Material-inspired layering
-- Protocol colours: SSH=teal `#4ecdc4`, Telnet=amber `#ffa726`, RAW=purple `#ab47bc`, GitHub=indigo `#7c8aff`
+Existing users upgrade in place, and their data came from the Go app first. Nexus Terminal must keep reading it.
 
-**Adding a new protocol:**
-1. Add `Protocol` constant + config struct in `models/models.go`
-2. Add defaults in `models/defaults.go` `NewProfile()` switch
-3. Create client package in `internal/<proto>client/`
-4. Add `connect<Proto>()` in `sessions/manager.go` + case in `Connect()` switch
-5. Add API methods in `api/api.go` if needed
-6. Add DB migration in `storage/migrations/` (update CHECK constraint, add config column)
-7. Update `storage/store.go`: all SELECT/INSERT/UPDATE queries + both scan functions
-8. Frontend: add DEFAULTS in `profiles.js`, render sections, collect form values, protocol tab
-9. Frontend: add viewer in new JS file (IIFE-wrapped), include in `index.html`, wire in `app.js`
-10. Add CSS: protocol colour token, sidebar indicator, tab badge, viewer styles
+- **Never change the database, vault, export or recording formats incompatibly.** The vault (`vault/vault.json`: Argon2id t=3, m=128 MiB, 4 lanes; AES-256-GCM per secret), the export envelope (`[version][32-byte salt][12-byte nonce][ciphertext]`, `.nexus`; `.link` must still import) and asciicast v2 recordings are fixed.
+- **Fixtures** generated by the old Go app live in `rust/core/tests/fixtures/` (`link.db`, `vault/`, `profiles.link`, `recordings/`). Tests in `storage.rs`, `secrets.rs`, `exportimport.rs` and `recording.rs` read them. Don't regenerate or edit them to make a test pass.
+- **Schema changes are new SQL files** in `rust/core/migrations/` (`008_….sql`, …), added to `MIGRATIONS` in `storage.rs`. Each ends with `INSERT INTO schema_version (version, applied_at) VALUES (N, datetime('now'));`. Never edit an applied migration. SQLite has no `ALTER COLUMN`; use the recreate-table pattern.
+- **Keychain** entries are stored under the service `NexusTerminal`; reads fall back to `AlchementaryLink` and copy forward. Don't change key names (`profile:<id>:<kind>`).
+- **Data directory** names (`NexusTerminal`, `nexus.db`, `vault/`, `recordings/`) and the first-run migration from `AlchementaryLink/` in `config.rs` are user-facing; keep them stable.
 
-**Database migrations:**
-- Numbered SQL files: `001_initial.sql`, `002_github_protocol.sql`, etc.
-- Each must `INSERT INTO schema_version (version, applied_at) VALUES (N, datetime('now'))` at the end
-- SQLite has no `ALTER COLUMN` — use the recreate-table pattern (CREATE new → INSERT INTO new SELECT FROM old → DROP old → ALTER TABLE RENAME)
-- Every query in `store.go` that touches the profiles table must be updated when columns change (there are ~8 SELECT column lists + 2 scan functions)
+## Testing tips
+
+- **Never point a test or manual run at your real data.** Use `--data-dir DIR` (a temporary directory) for manual runs; tests create their own directory under `std::env::temp_dir()`, as the existing ones do.
+- **App flags** (`rust/app/src/main.rs`):
+  - `--data-dir DIR` — use another data directory.
+  - `--screenshot out.png` — render, save a PNG and exit (works under `xvfb-run`); combine with `--size WxH` and `--theme pro|midnight|light`.
+  - `--open WINDOW` — open a window at startup: `editor[:protocol|id]`, `quick`, `settings[:terminal|security|knownhosts|help|about]`, `keys`, `snippets`, `triggers`, `recordings`, `palette`, `export`, `import`.
+  - `--connect NAME` — connect a saved profile by display name or id.
+  - `--run-local CMD` — open a local terminal and type `CMD` into it once connected.
+
+  For example: `cargo run -- --data-dir /tmp/nx --open settings:help --screenshot /tmp/help.png`.
+- **SSH integration tests** (`core/tests/ssh_integration.rs`) start a throwaway `sshd` as the current user on a random port and skip themselves when OpenSSH isn't installed. They **must never open an interactive login shell** — the user's shell profile can auto-attach tmux/byobu to a real session. Set the profile's startup command to `/bin/sh -i`, as the existing `profile()` helper does.
+- `core/tests/sessions.rs` drives the `Manager` end to end against local TCP listeners; follow its `manager()` and `wait()` helpers for event-driven tests.
+- UI logic that can be tested without a window (parsers, fuzzy matching, split trees, snippet variables, trigger matching) has `#[cfg(test)]` unit tests next to it; add one with any non-trivial change.

.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+    push:
+        branches: ["**"]
+    pull_request:
+
+permissions:
+    contents: read
+
+jobs:
+    test:
+        name: Test (${{ matrix.os }})
+        runs-on: ${{ matrix.os }}
+        strategy:
+            fail-fast: false
+            matrix:
+                os: [ubuntu-22.04, macos-14, windows-latest]
+        defaults:
+            run:
+                shell: bash
+                working-directory: rust
+        steps:
+            - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+              with:
+                  persist-credentials: false
+            - name: Linux dependencies (GUI libs, and sshd for the SSH integration tests)
+              if: runner.os == 'Linux'
+              run: |
+                  sudo apt-get update
+                  sudo apt-get install -y libxkbcommon-dev libgl1-mesa-dev libx11-dev libxcursor-dev libxrandr-dev libxi-dev libwayland-dev libgtk-3-dev libasound2-dev openssh-server
+            - run: cargo test --locked --workspace
+            - run: cargo fmt --all --check
+            - run: cargo clippy --locked --workspace --all-targets -- -D warnings
+
+    audit:
+        name: Dependency audit
+        runs-on: ubuntu-22.04
+        defaults:
+            run:
+                working-directory: rust
+        steps:
+            - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+              with:
+                  persist-credentials: false
+            - run: cargo install cargo-audit --version 0.22.2 --locked
+            # Ignored advisories and their reasons live in rust/.cargo/audit.toml. Yanked crates
+            # fail the build; the fuzz workspace has its own lockfile, so it's audited too.
+            - run: cargo audit --deny yanked
+            - run: cargo audit --deny yanked --file fuzz/Cargo.lock

.github/workflows/fuzz.yml

@@ -0,0 +1,35 @@
+name: Fuzz
+
+on:
+    schedule:
+        - cron: "17 3 * * *"
+    workflow_dispatch:
+
+permissions:
+    contents: read
+
+jobs:
+    fuzz:
+        name: Fuzz (${{ matrix.target }})
+        runs-on: ubuntu-22.04
+        strategy:
+            fail-fast: false
+            matrix:
+                target: [telnet, irc, vnc, sshconfig, updater]
+        defaults:
+            run:
+                working-directory: rust/fuzz
+        steps:
+            - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+              with:
+                  persist-credentials: false
+            - run: sudo apt-get update && sudo apt-get install -y libasound2-dev
+            - run: rustup toolchain install nightly --profile minimal
+            - run: cargo +nightly install cargo-fuzz --locked
+            - run: cargo +nightly fuzz run ${{ matrix.target }} -- -max_total_time=120 -rss_limit_mb=2048 -timeout=10
+            - name: Upload crashing inputs
+              if: failure()
+              uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+              with:
+                  name: fuzz-${{ matrix.target }}
+                  path: rust/fuzz/artifacts

.github/workflows/release-builds.yml

@@ -6,8 +6,10 @@ on:
             - "v*"
     workflow_dispatch:
 
+# Building and testing runs every dependency's build scripts and tests, so those jobs only get a
+# read token. Publishing is a separate job that never runs project or dependency code.
 permissions:
-    contents: write
+    contents: read
 
 jobs:
     build:
@@ -17,121 +19,69 @@ jobs:
             fail-fast: false
             matrix:
                 include:
-                    - platform: darwin/amd64
-                      runner: macos-13
-                      os: darwin
-                      arch: amd64
-                      archive_type: zip
-                    - platform: darwin/arm64
-                      runner: macos-14
-                      os: darwin
-                      arch: arm64
-                      archive_type: zip
-                    - platform: linux/amd64
-                      runner: ubuntu-latest
-                      os: linux
-                      arch: amd64
-                      archive_type: tar
-                    - platform: linux/arm64
-                      runner: ubuntu-24.04-arm64
-                      os: linux
-                      arch: arm64
-                      archive_type: tar
-                    - platform: windows/amd64
-                      runner: windows-latest
-                      os: windows
-                      arch: amd64
-                      archive_type: zip
-                    - platform: windows/arm64
-                      runner: ubuntu-latest
-                      os: windows
-                      arch: arm64
-                      archive_type: zip
-                      cross: true
-
+                    - { platform: darwin/amd64, runner: macos-15-intel }
+                    - { platform: darwin/arm64, runner: macos-14 }
+                    - { platform: linux/amd64, runner: ubuntu-22.04 }
+                    - { platform: linux/arm64, runner: ubuntu-22.04-arm }
+                    - { platform: windows/amd64, runner: windows-latest }
+                    - { platform: windows/arm64, runner: windows-11-arm }
+        defaults:
+            run:
+                shell: bash
+                working-directory: rust
         steps:
-            - name: Checkout
-              uses: actions/checkout@v4
-
-            - name: Set up Go
-              uses: actions/setup-go@v5
+            - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
               with:
-                  go-version-file: go.mod
+                  fetch-depth: 0
+                  persist-credentials: false
 
-            - name: Set up Node
-              uses: actions/setup-node@v4
-              with:
-                  node-version: "20"
+            - name: Rust toolchain (pinned by rust-toolchain.toml)
+              run: rustup show active-toolchain || rustup toolchain install
 
-            - name: Install Wails
-              run: go install github.com/wailsapp/wails/v2/cmd/wails@$(go list -m -f '{{.Version}}' github.com/wailsapp/wails/v2)
-
-            - name: Install frontend dependencies
-              run: npm ci
-              working-directory: frontend
-
-            - name: Install Linux build dependencies
-              if: matrix.os == 'linux'
+            - name: Linux build dependencies
+              if: runner.os == 'Linux'
               run: |
                   sudo apt-get update
-                  sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev
+                  sudo apt-get install -y libxkbcommon-dev libgl1-mesa-dev libx11-dev libxcursor-dev libxrandr-dev libxi-dev libwayland-dev libgtk-3-dev libasound2-dev zip
 
-            - name: Install Windows cross-compiler
-              if: matrix.os == 'windows' && matrix.cross
-              run: |
-                  sudo apt-get update
-                  sudo apt-get install -y gcc-mingw-w64-x86-64 gcc-mingw-w64-aarch64 zip
+            - name: Test
+              run: cargo test --locked --workspace
 
-            - name: Build (non-Windows runners)
-              if: matrix.runner != 'windows-latest'
+            - name: Build and package
               env:
-                  CGO_ENABLED: "1"
-              run: |
-                  if [ "${{ matrix.os }}" = "windows" ] && [ "${{ matrix.cross }}" = "true" ]; then
-                    export CC=aarch64-w64-mingw32-gcc
-                  fi
-                  wails build -platform "${{ matrix.platform }}" -ldflags "-s -w"
+                  NEXUS_RELEASE_TARGETS: ${{ matrix.platform }}
+                  NEXUS_RELEASE_ROOT: ${{ github.workspace }}/build/releases
+              run: ./release.sh
 
-            - name: Build (Windows runner)
-              if: matrix.runner == 'windows-latest'
-              shell: pwsh
-              env:
-                  CGO_ENABLED: "1"
-              run: |
-                  wails build -platform "${{ matrix.platform }}" -ldflags "-s -w"
-
-            - name: Package (zip)
-              if: matrix.archive_type == 'zip' && matrix.runner != 'windows-latest'
-              run: |
-                  archive="nexus-terminal-${{ matrix.platform }}.zip"
-                  cd build/bin
-                  zip -r "../../${archive}" .
-
-            - name: Package (tar)
-              if: matrix.archive_type == 'tar'
-              run: |
-                  archive="nexus-terminal-${{ matrix.platform }}.tar.gz"
-                  tar -czf "${archive}" -C build/bin .
-
-            - name: Package (Windows zip)
-              if: matrix.archive_type == 'zip' && matrix.runner == 'windows-latest'
-              shell: pwsh
-              run: |
-                  $archive = "nexus-terminal-${{ matrix.platform }}.zip"
-                  Compress-Archive -Path "build/bin/*" -DestinationPath $archive
-
-            - name: Upload artifact
-              uses: actions/upload-artifact@v4
+            - name: Upload artefacts
+              uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
               with:
-                  name: nexus-terminal-${{ matrix.platform }}
+                  name: nexus-terminal-${{ matrix.runner }}
                   path: |
-                      nexus-terminal-${{ matrix.platform }}.zip
-                      nexus-terminal-${{ matrix.platform }}.tar.gz
+                      build/releases/*/NexusTerminal-*.zip
+                      build/releases/manifest-*.json
+                      build/releases/version-*.txt
 
-            - name: Attach to GitHub Release
-              if: startsWith(github.ref, 'refs/tags/')
-              uses: softprops/action-gh-release@v2
+    publish:
+        name: Attach to GitHub Release
+        needs: build
+        if: startsWith(github.ref, 'refs/tags/')
+        runs-on: ubuntu-22.04
+        permissions:
+            contents: write
+        steps:
+            - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+              with:
+                  path: artefacts
+            - name: Checksums
+              run: |
+                  find artefacts -name 'NexusTerminal-*.zip' | while read -r f; do
+                      (cd "$(dirname "$f")" && sha256sum "$(basename "$f")")
+                  done > SHA256SUMS
+                  cat SHA256SUMS
+            - uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2.6.2
               with:
                   files: |
-                      nexus-terminal-${{ matrix.platform }}.zip
-                      nexus-terminal-${{ matrix.platform }}.tar.gz
+                      artefacts/*/*/NexusTerminal-*.zip
+                      artefacts/*/NexusTerminal-*.zip
+                      SHA256SUMS

.gitignore

@@ -3,33 +3,8 @@
 # ==========================================================================
 
 # ── Build output ──────────────────────────────────────────────────────────
-build/bin/
-dist/
-
-# ── Build platform resources (tracked — icons, plists, manifests) ─────────
-# build/darwin/, build/windows/, build/linux/ are tracked for icons & metadata
-
-# ── Go ────────────────────────────────────────────────────────────────────
-vendor/
-.tools/
-.cache/
-*.exe
-*.exe~
-*.dll
-*.so
-*.dylib
-*.test
-*.out
-__debug_bin*
-coverage.out
-coverage.html
-
-# ── Frontend ──────────────────────────────────────────────────────────────
-frontend/node_modules/
-frontend/src/js/lib/
-
-# ── Wails auto-generated bindings (recreated on every build) ──────────────
-frontend/wailsjs/
+rust/target/
+build/releases/
 
 # ── IDE / editor ──────────────────────────────────────────────────────────
 .idea/
@@ -37,20 +12,12 @@ frontend/wailsjs/
 *.swp
 *.swo
 *~
-*.sublime-project
-*.sublime-workspace
-.project
-.classpath
-.settings/
 
 # ── OS metadata ───────────────────────────────────────────────────────────
 .DS_Store
-.DS_Store?
 ._*
 Thumbs.db
-ehthumbs.db
 Desktop.ini
-$RECYCLE.BIN/
 
 # ── Application data (never commit user data or secrets) ──────────────────
 *.db
@@ -59,9 +26,12 @@ $RECYCLE.BIN/
 vault.json
 *.pem
 *.key
-!build/appicon.png
 
+# Compatibility fixtures generated from the last Go build are deliberate test data.
+!rust/core/tests/fixtures/**
 
-# Builds
-build/releases/v*
-build/releases/manifest*
+# Agent worktrees
+.claude/worktrees/
+
+# User guide LaTeX output
+docs/guide/build/

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

Makefile

@@ -1,89 +0,0 @@
-.PHONY: all build build-compressed dev clean test test-cover lint install deps frontend-deps upx-check run package release help
-
-# Resolve the Wails binary. Prefer wails on PATH; fall back to GOPATH/bin.
-WAILS := $(or $(shell which wails 2>/dev/null),$(shell go env GOPATH)/bin/wails)
-VERSION := $(shell git describe --tags --abbrev=0 2>/dev/null || echo dev)-$(shell git rev-parse --short HEAD 2>/dev/null || echo unknown)
-LD_UPDATE_URL := $(if $(NEXUS_UPDATE_URL),-X github.com/andydixon/nexus/internal/api.appUpdateURL=$(NEXUS_UPDATE_URL),)
-UPX_FLAGS ?=
-NEXUS_FORCE_MACOS_UPX ?= 0
-GOBIN_DIR := $(shell go env GOPATH)/bin
-export PATH := $(GOBIN_DIR):$(PATH)
-
-# Default target
-all: build
-
-# Install all dependencies
-deps: frontend-deps
-	go mod download
-
-upx-check:
-	@command -v upx >/dev/null 2>&1 || { echo "UPX is required for compressed builds. Install it first, for example: brew install upx"; exit 1; }
-	@if [ "$$(uname -s)" = "Darwin" ] && [ "$(NEXUS_FORCE_MACOS_UPX)" != "1" ]; then \
-		echo "UPX compression is disabled for macOS by default. Use ./release.sh for a zipped .app, or run NEXUS_FORCE_MACOS_UPX=1 UPX_FLAGS='--force-macos --best --no-color --no-progress' make build-compressed."; \
-		exit 1; \
-	fi
-	@if [ "$$(uname -s)" = "Darwin" ] && [ "$(NEXUS_FORCE_MACOS_UPX)" = "1" ] && ! printf '%s\n' "$(UPX_FLAGS)" | grep -q -- '--force-macos'; then \
-		echo "macOS UPX builds must pass --force-macos in UPX_FLAGS."; \
-		exit 1; \
-	fi
-
-# Install frontend dependencies
-frontend-deps:
-	cd frontend && npm install
-
-# Development mode with hot reload
-dev: deps
-	$(WAILS) dev
-
-# Production build
-build: deps
-	CGO_CFLAGS="$${CGO_CFLAGS:--O2 -g0}" CGO_CXXFLAGS="$${CGO_CXXFLAGS:--O2 -g0}" $(WAILS) build -trimpath -ldflags "-s -w -buildid= -X github.com/andydixon/nexus/internal/api.appVersion=$(VERSION) $(LD_UPDATE_URL)"
-
-# Production build with UPX compression
-build-compressed: deps upx-check
-	CGO_CFLAGS="$${CGO_CFLAGS:--O2 -g0}" CGO_CXXFLAGS="$${CGO_CXXFLAGS:--O2 -g0}" $(WAILS) build -trimpath -upx $(if $(UPX_FLAGS),-upxflags "$(UPX_FLAGS)",) -ldflags "-s -w -buildid= -X github.com/andydixon/nexus/internal/api.appVersion=$(VERSION) $(LD_UPDATE_URL)"
-
-# Run tests
-test:
-	go test ./... -v -count=1
-
-# Run tests with coverage
-test-cover:
-	go test ./... -v -count=1 -coverprofile=coverage.out
-	go tool cover -html=coverage.out -o coverage.html
-
-# Clean build artefacts
-clean:
-	rm -rf build/bin
-	rm -rf frontend/node_modules
-	rm -rf frontend/src/js/lib
-	rm -rf frontend/src/css/lib
-	go clean -testcache
-
-# Lint (requires golangci-lint)
-lint:
-	golangci-lint run ./...
-
-# Package for distribution
-package: build
-	@echo "Binary built at build/bin/"
-
-# Build and package release artefacts for all platforms
-release:
-	./release.sh
-
-# Help
-help:
-	@echo "Nexus Terminal — Build Targets"
-	@echo ""
-	@echo "  make deps          — Install all dependencies"
-	@echo "  make dev           — Run in development mode with hot reload"
-	@echo "  make build         — Production build"
-	@echo "  make build-compressed — Production build with UPX compression"
-	@echo "  make test          — Run tests"
-	@echo "  make test-cover    — Run tests with coverage report"
-	@echo "  make clean         — Clean build artefacts"
-	@echo "  make lint          — Run linter (requires golangci-lint)"
-	@echo "  make package       — Build and package for distribution"
-	@echo "  make release       — Build multi-platform release artefacts"
-	@echo "  make help          — Show this help"

README.md

@@ -1,27 +1,67 @@
 # Nexus Terminal
 
-**A desktop client for SSH, Telnet, RAW TCP, VNC, GitHub, local terminals, and Leviathan binary analysis — with secure credential handling and a focused, multi-session workflow.**
+**A native desktop client for SSH, Telnet, RAW TCP, Serial, VNC, RDP, IRC, GitHub and local terminals — with secure credential handling and a focused, multi-session workflow.**
 
-Nexus Terminal helps you manage many connections at once, keep terminal work organised, and move files with confidence.
+Nexus Terminal helps you manage many connections at once, keep terminal work organised, and move files with confidence. It is a single Rust application with no webview, so it starts quickly and stays responsive under heavy terminal output.
 
 ## Highlights
 
-- SSH, Telnet, RAW TCP, VNC, GitHub, and local terminal sessions in one app
-- Tabbed sessions with split panes, pinning, and reordering
-- SFTP browser with drag-and-drop uploads and a directory picker
-- Leviathan binary workbench with hex editing, entropy, carving, BinSnoop, structure parsers, transforms, and spectrogram tools
-- Disconnected overlay with one-click reconnect
-- Broadcast input, snippets, and terminal search
-- Session recording and playback
-- Secure credential storage with OS keychain and encrypted vault fallback
+- SSH, Telnet, RAW TCP, Serial, VNC, RDP, IRC, GitHub and local terminal sessions in one app
+- Tabbed sessions with split panes, pinning and drag-to-reorder
+- SFTP browser with drag-and-drop uploads and a permission-aware directory picker
+- SSH jump hosts, SOCKS5/HTTP proxies, local and remote port forwards, agent forwarding and TOTP auto-fill
+- Serial consoles with full line settings (baud, data bits, parity, stop bits, flow control)
+- Native VNC and RDP viewers; RDP with NLA, certificate pinning, and SOCKS5/HTTP proxy or SSH tunnel routes
+- Disconnected overlay with one-click reconnect, and auto-reconnect with backoff
+- Broadcast input, snippets, trigger rules and terminal search
+- Session recording (asciicast v2) and playback
+- Secure credential storage with the OS keychain first and an encrypted vault fallback
+
+## Install
+
+**macOS** (Homebrew):
+
+```sh
+brew install --cask andydixon/tap/nexusterminal
+```
+
+**Debian, Ubuntu** (22.04 and later):
+
+```sh
+sudo install -d -m 0755 /etc/apt/keyrings
+curl -fsSL https://repo.dixon.cx/dixon.gpg | sudo tee /etc/apt/keyrings/dixon.gpg >/dev/null
+echo "deb [signed-by=/etc/apt/keyrings/dixon.gpg] https://repo.dixon.cx/apt stable main" |
+    sudo tee /etc/apt/sources.list.d/dixon.list
+sudo apt update && sudo apt install nexusterminal
+```
+
+**Fedora, RHEL, openSUSE:**
+
+```sh
+sudo curl -fsSL -o /etc/yum.repos.d/dixon.repo https://repo.dixon.cx/rpm/dixon.repo
+sudo dnf install nexusterminal        # or: sudo zypper install nexusterminal
+```
+
+**Arch Linux:**
+
+```sh
+curl -fsSL https://repo.dixon.cx/dixon.asc | sudo pacman-key --add -
+sudo pacman-key --lsign-key C22FF7330668417C62C7A304CBC7951D7F2234D1
+printf '\n[dixon]\nServer = https://repo.dixon.cx/arch/$arch\n' | sudo tee -a /etc/pacman.conf
+sudo pacman -Sy nexusterminal
+```
+
+**Windows**, or any platform by hand: download a zip from
+[GitHub Releases](https://github.com/andydixon/nexus/releases) and check it against `SHA256SUMS`.
+Builds aren't code-signed yet, so macOS and Windows ask you to confirm the first launch.
 
 ## Quick start
 
 1. Launch Nexus Terminal.
-2. Click **New** in the sidebar and create a connection profile.
-3. Click **Connect** to open a session in a new tab.
+2. Click **+** at the bottom of the sidebar (or press **Cmd+N** / **Ctrl+N**) and create a connection profile.
+3. Click **Create & Connect** to save it and open a session in a new tab. Afterwards, click the profile in the sidebar to connect.
 
-Prefer a one-off session? Use **Cmd+Shift+Q** / **Ctrl+Shift+Q** to quick connect.
+Prefer a one-off session? Use **Cmd+Shift+Q** / **Ctrl+Shift+Q** to quick connect, or click **Local Machine** in the sidebar for a local shell.
 
 If a session drops, use the **Reconnect** button in the disconnected overlay.
 
@@ -30,26 +70,52 @@ If a session drops, use the **Reconnect** button in the disconnected overlay.
 - Product overview: [docs/overview.md](docs/overview.md)
 - Quick start (shareable): [docs/quick-start.md](docs/quick-start.md)
 - User manual: [docs/user-manual.md](docs/user-manual.md)
+- Illustrated user guide (PDF): [docs/guide/nexus-guide.pdf](docs/guide/nexus-guide.pdf), built from LaTeX in [docs/guide](docs/guide) (`make` there; `tools/screenshots.sh` regenerates the screenshots)
 - Build and release: [docs/build-and-release.md](docs/build-and-release.md)
 
 ## Keyboard shortcuts
 
 All shortcuts use **Cmd** on macOS and **Ctrl** on Windows/Linux.
 
-| macOS Shortcut    | Windows/Linux Shortcut | Action                      |
-| ----------------- | ---------------------- | --------------------------- |
-| Cmd + K           | Ctrl + K               | Open command palette        |
-| Cmd + N           | Ctrl + N               | New connection              |
-| Cmd + W           | Ctrl + W               | Close current tab           |
-| Cmd + Tab         | Ctrl + Tab             | Next tab                    |
-| Cmd + Shift + Tab | Ctrl + Shift + Tab     | Previous tab                |
-| Cmd + 1–9         | Ctrl + 1–9             | Switch to tab by number     |
-| Cmd + ,           | Ctrl + ,               | Open settings               |
-| Cmd + F           | Ctrl + F               | Find in terminal            |
-| Cmd + Shift + D   | Ctrl + Shift + D       | Split pane vertically       |
-| Cmd + Shift + E   | Ctrl + Shift + E       | Split pane horizontally     |
-| Cmd + Shift + R   | Ctrl + Shift + R       | Toggle session recording    |
-| Cmd + Shift + B   | Ctrl + Shift + B       | Toggle broadcast input mode |
-| Cmd + Shift + S   | Ctrl + Shift + S       | Open snippet library        |
-| Cmd + Shift + Q   | Ctrl + Shift + Q       | Quick connect               |
-| F11               | F11                    | Toggle fullscreen           |
+| macOS Shortcut    | Windows/Linux Shortcut | Action                           |
+| ----------------- | ---------------------- | -------------------------------- |
+| Cmd + K           | Ctrl + K               | Open command palette             |
+| Cmd + N           | Ctrl + N               | New connection                   |
+| Cmd + W           | Ctrl + W               | Close current tab                |
+| Cmd + Tab         | Ctrl + Tab             | Next tab                         |
+| Cmd + Shift + Tab | Ctrl + Shift + Tab     | Previous tab                     |
+| Cmd + 1–9         | Ctrl + 1–9             | Switch to tab by number          |
+| Cmd + ,           | Ctrl + ,               | Open settings                    |
+| Cmd + F           | Ctrl + F               | Find in terminal                 |
+| Cmd + Shift + D   | Ctrl + Shift + D       | Split pane right (side by side)  |
+| Cmd + Shift + E   | Ctrl + Shift + E       | Split pane down (top and bottom) |
+| Cmd + Shift + R   | Ctrl + Shift + R       | Toggle session recording         |
+| Cmd + Shift + B   | Ctrl + Shift + B       | Toggle broadcast input mode      |
+| Cmd + Shift + S   | Ctrl + Shift + S       | Open snippet library             |
+| Cmd + Shift + Q   | Ctrl + Shift + Q       | Quick connect                    |
+| F11               | F11                    | Toggle fullscreen                |
+
+## Building from source
+
+Nexus Terminal is a Rust workspace in `rust/`. With [rustup](https://rustup.rs) installed:
+
+```bash
+cd rust
+cargo run --release
+```
+
+See [docs/build-and-release.md](docs/build-and-release.md) for platform prerequisites, tests and release packaging.
+
+## License
+
+Copyright (C) 2026 Andy Dixon.
+
+Nexus Terminal is free software: you can redistribute it and/or modify it under the terms of the
+[GNU Affero General Public License, version 3](LICENSE) as published by the Free Software
+Foundation. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+license for details.
+
+Third-party crates (including the patched copies in `rust/vendor/`) keep their own licenses,
+which are listed in each crate.
+

audits/20260616-1702-functionalityNextSteps.md

@@ -0,0 +1,138 @@
+# Functionality and Next Steps Report
+
+## 1. Executive Summary
+
+This fix pass improved robustness around local proxying, file imports, remote downloads, SSH key management, and frontend rendering. The app now fails earlier and more predictably when inputs are malformed or too large.
+
+Highest-impact next steps:
+
+- Manually verify packaged VNC connections after the new Origin allowlist.
+- Add UI copy for newly enforced limits.
+- Add CI coverage for the security checks run in this pass.
+- Continue frontend cleanup around dynamic `innerHTML`.
+
+## 2. Current Functional Risks
+
+VNC runtime compatibility:
+
+- The backend now allows missing, `wails://`, and loopback HTTP(S) origins. This should work for Wails/noVNC, but packaged app validation is still needed.
+
+Large-file and large-download behavior:
+
+- GitHub archive downloads now stop at 2 GiB. Very large repositories will fail fast.
+- SSH config imports now reject files above 5 MiB or more than 5000 Host blocks.
+
+SSH key generation:
+
+- RSA key generation is limited to 2048, 3072, and 4096 bits and times out after 30 seconds.
+- Slow systems should be checked with RSA 4096 to ensure the timeout is not too tight.
+
+Frontend:
+
+- SSH key manager dynamic rendering is safer. Other static `innerHTML` templates remain and should be reviewed when they take dynamic data.
+
+## 3. Code Quality Improvements
+
+Completed:
+
+- Added focused helper functions for VNC Origin validation.
+- Centralized GitHub endpoint construction and owner/repo parsing.
+- Added reusable archive stream limiting.
+- Added backend SSH key generation option validation.
+- Added import bounds to the SSH config parser.
+- Replaced SSH key manager dynamic modal HTML with DOM construction.
+
+Recommended refactors:
+
+- Move file-size and stream-size caps into named settings or a shared limits package if more subsystems need them.
+- Add a small frontend helper for safe modal construction so feature code stops hand-rolling modal `innerHTML`.
+- Consider a common backend "safe basename" helper for local and remote file operations.
+
+## 4. Frontend Interaction and Error-Handling Improvements
+
+Recommended:
+
+- Show a specific VNC connection error if the proxy rejects an unexpected Origin in packaged builds.
+- Show clear messages for SSH config files that exceed size or Host-block limits.
+- Show clear messages for GitHub archives above the cap.
+- Add a hostile-filename E2E test for the SSH key delete confirmation modal.
+- Continue converting dynamic modal content to DOM nodes or `textContent`.
+
+## 5. Testing Roadmap
+
+Added in this pass:
+
+- VNC Origin allowlist tests.
+- SFTP upload parent-directory rejection tests.
+- SSH config file and Host-block limit tests.
+- SSH key generation option validation tests.
+- GitHub path escaping and archive cap tests.
+- Frontend regression checks for SSH key manager text rendering.
+
+Next tests:
+
+- Packaged Wails VNC smoke test on macOS, Windows, and Linux.
+- Browser/E2E test for SSH key filenames containing `<`, `>`, quotes, and ampersands.
+- HTTP integration test for GitHub archive download caps and escaped branch refs.
+- UI tests for limit-aware error messages.
+- CI job that runs Go tests, frontend tests, frontend build, `npm audit --omit=dev`, `govulncheck`, and `git diff --check`.
+
+## 6. Recommended New Functionality
+
+Useful additions:
+
+- Preferences for maximum GitHub archive download size.
+- A pre-download confirmation for large GitHub archives when Content-Length is known.
+- Import preview for OpenSSH config showing Host count before persistence.
+- A diagnostics panel for VNC proxy status, including local URL redaction, Origin decisions, and connection state.
+- A unified "Limits" help page that lists SFTP upload caps, GitHub archive cap, SSH config import cap, and Leviathan file caps.
+
+## 7. Next-Level Opportunities
+
+Architecture:
+
+- Centralize resource limits and expose them to both Go and frontend UI copy.
+- Add a secure modal builder and migrate risky frontend dialogs gradually.
+- Add structured security regression tests for every Wails method that accepts file paths, filenames, URLs, or base64 payloads.
+
+Operations:
+
+- Generate checksums for release artifacts.
+- Generate an SBOM during release.
+- Publish a short security hardening checklist in `docs/build-and-release.md`.
+
+Developer experience:
+
+- Add a `make security-check` target that runs the same commands used in this audit.
+- Add pre-commit or CI checks for `gofmt`, `go test`, frontend regression tests, and `git diff --check`.
+
+## 8. Prioritised Action Plan
+
+Immediate:
+
+- Manually test packaged VNC on all supported platforms.
+- Keep the security patch tests in CI before release.
+
+Short-term:
+
+- Add user-facing messages for the new SSH config, GitHub archive, and SSH keygen limits.
+- Add E2E coverage for hostile SSH key filenames.
+- Add an HTTP test around GitHub archive download behavior.
+
+Medium-term:
+
+- Centralize app resource limits and expose them to UI/help.
+- Migrate high-risk frontend dynamic HTML patterns to safe modal helpers.
+- Add release checksums and SBOM generation.
+
+Long-term:
+
+- Add progressive/streaming UX for large GitHub and SFTP transfers.
+- Build a cross-platform packaged-app smoke test suite for Wails integrations.
+
+## 9. Caveats and Validation Needed
+
+- VNC Origin compatibility must be validated in packaged builds, not only unit tests.
+- The 2 GiB GitHub archive cap may need product tuning for users with very large repositories.
+- RSA 4096 key generation timeout should be checked on lower-powered machines.
+- The frontend build passed, but this pass did not interactively click through the SSH key modal in a real browser/WebView.

audits/20260616-1702-securityAudit.md

@@ -0,0 +1,641 @@
+# Security Audit Report
+
+## 1. Executive Summary
+
+This fix-mode audit reviewed the Wails API surface, local proxy behavior, file import paths, SSH key management, GitHub integration, frontend DOM sinks, dependency manifests, tests, and release workflow.
+
+Six concrete issues were fixed:
+
+- The local VNC WebSocket proxy accepted any browser `Origin` and did not cap client-to-proxy WebSocket message size.
+- SFTP browser uploads accepted the special filename `..`, allowing a Wails caller to escape the selected remote directory when the name was joined.
+- SSH config import parsed line-by-line but had no total file or Host-block cap.
+- Backend SSH key generation trusted caller-supplied key type and RSA bit count and had no process timeout.
+- GitHub repo/ref values were interpolated into API paths without escaping, and archive downloads had no explicit stream cap.
+- SSH key manager UI interpolated backend errors and filesystem-derived key names into `innerHTML`.
+
+Verification passed with targeted Go tests, full Go tests, frontend regression checks, frontend build, `npm audit --omit=dev`, `govulncheck`, and `git diff --check`.
+
+## 2. Scope Reviewed
+
+Reviewed:
+
+- Go backend packages under `internal/`: API bindings, VNC proxy, GitHub client, SSH config import, SSH key management, SFTP upload helpers, validation, sessions, storage, secrets, updater, recording, Leviathan parser bounds, and tests.
+- Browser-facing JavaScript under `frontend/src/js`, especially SSH key management, SFTP upload flows, VNC integration, and dynamic HTML usage.
+- Frontend package manifest, lockfile, build scripts, and regression script.
+- Go module dependencies and reachable vulnerability state.
+- GitHub Actions release workflow.
+
+Not fully live-tested:
+
+- A packaged Wails desktop binary.
+- Real noVNC connections inside the packaged WebView after the new Origin policy.
+- Real GitHub Enterprise archive downloads above normal repository sizes.
+
+## 3. Methodology
+
+The review used static analysis, targeted source searches, dependency/advisory tooling, and focused regression tests. I mapped attacker-controlled inputs from the renderer and local files into Go methods, network clients, local HTTP/WebSocket services, subprocesses, remote SFTP paths, and DOM sinks. I prioritized issues that could be fixed with small behavior-preserving changes and backed by tests.
+
+Commands run:
+
+- `go test ./internal/vncclient ./internal/api ./internal/sshconfig ./internal/githubclient -count=1`
+- `npm --prefix frontend test`
+- `git diff --check`
+- `go test ./... -count=1`
+- `npm --prefix frontend run build`
+- `npm --prefix frontend audit --omit=dev`
+- `go run golang.org/x/vuln/cmd/govulncheck@latest ./...`
+
+## 4. Risk Rating Method
+
+Severity reflects exploit prerequisite, affected trust boundary, likely impact, and availability/confidentiality/integrity outcome:
+
+- Critical: remote unauthenticated compromise or secret disclosure.
+- High: practical compromise of credentials, host access, or arbitrary code execution.
+- Medium: meaningful local, renderer, remote service, or connected-server abuse with realistic prerequisites.
+- Low: local robustness issues, bounded DoS, or defense-in-depth gaps.
+- Informational: observations and hardening opportunities.
+
+Confidence reflects direct code evidence and testability. Findings fixed here are High confidence because they map to concrete files and new regression tests.
+
+## 5. Attack Surface Map
+
+Entry points:
+
+- Wails-bound `api.Service` methods callable from the renderer.
+- Local VNC WebSocket proxy bound to `127.0.0.1` on a random port and random token path.
+- SSH, Telnet, RAW TCP, VNC, SFTP, GitHub, updater, and Leviathan binary-analysis workflows.
+- Profile import/export, encrypted `.nexus` import, OpenSSH config import, recording playback, SSH key generation/deletion, and drag/drop upload flows.
+
+Trust boundaries:
+
+- Renderer to Go backend.
+- Local browser/WebView to loopback VNC proxy.
+- Local filesystem files selected or scanned by the app.
+- Remote SSH/SFTP/VNC/GitHub/update endpoints.
+- OS keychain/encrypted vault to profile storage and session runtime.
+
+Attacker starting positions considered:
+
+- Malicious local webpage attempting loopback WebSocket access.
+- Malicious or compromised renderer script.
+- Malicious local filename or selected config/import file.
+- Malicious GitHub Enterprise/API endpoint or unusual repo/ref metadata.
+- Malicious connected SSH/SFTP/VNC host.
+
+## 6. Findings Summary Table
+
+| ID | Severity | Confidence | Title | Component | Status |
+|---|---|---|---|---|---|
+| SEC-20260616-1702-001 | Medium | High | VNC proxy allowed all origins and uncapped WebSocket frames | `internal/vncclient` | Fixed |
+| SEC-20260616-1702-002 | Medium | High | SFTP upload name `..` escaped selected remote directory | `internal/api` SFTP upload helpers | Fixed |
+| SEC-20260616-1702-003 | Low | High | SSH config import lacked total file and Host-block bounds | `internal/sshconfig` | Fixed |
+| SEC-20260616-1702-004 | Low | High | SSH key generation allowed expensive caller-controlled options without timeout | `internal/api` SSH key management | Fixed |
+| SEC-20260616-1702-005 | Medium | High | GitHub repo/ref path interpolation and uncapped archive stream | `internal/githubclient` | Fixed |
+| SEC-20260616-1702-006 | Medium | High | SSH key manager rendered key names/errors through dynamic `innerHTML` | `frontend/src/js/sshkeys.js` | Fixed |
+
+## 7. Detailed Findings
+
+### Finding ID: SEC-20260616-1702-001
+
+#### Title
+
+VNC proxy allowed all origins and uncapped WebSocket frames
+
+#### Severity
+
+Medium
+
+#### Confidence
+
+High
+
+#### Affected Files / Components
+
+- `internal/vncclient/vncclient.go`
+- `internal/vncclient/vncclient_test.go`
+- Local noVNC WebSocket proxy
+
+#### Description
+
+The VNC proxy was bound to loopback and protected by a random token path, but its Gorilla WebSocket upgrader accepted every `Origin`. It also read WebSocket messages without an explicit message size limit. If a proxy URL token leaked through logs, UI state, injected renderer code, or another local channel, a non-local browser origin could attempt to drive the active VNC TCP connection or send oversized frames that force memory allocation.
+
+#### Evidence
+
+Before the fix, `websocket.Upgrader.CheckOrigin` returned `true` for every request, and the proxy called `ws.ReadMessage()` without `SetReadLimit`.
+
+#### Attack Scenario
+
+A malicious local webpage or injected renderer script obtains an active `ws://127.0.0.1:<port>/<token>` URL. Because all origins were accepted, it could connect from a non-app origin and send very large WebSocket messages or VNC protocol bytes into the bridged TCP connection.
+
+#### Impact
+
+Potential local cross-origin abuse of active VNC sessions if the token is exposed, and avoidable memory pressure from oversized client-to-proxy WebSocket frames.
+
+#### Recommendation
+
+Allow only Wails and loopback browser origins, keep accepting missing origins for non-browser clients, and cap inbound WebSocket message size.
+
+#### Safer Example
+
+Implemented `allowProxyOrigin`, `isLoopbackHost`, and `ws.SetReadLimit(maxWebSocketMessageBytes)`.
+
+#### Suggested Tests
+
+Added `TestAllowProxyOrigin` for missing, Wails, loopback, remote, lookalike, and malformed origins.
+
+#### References
+
+- CWE-346: Origin Validation Error
+- CWE-400: Uncontrolled Resource Consumption
+- OWASP ASVS 14.4: HTTP security configuration
+
+#### Assumptions / Limitations
+
+The packaged Wails WebView should be manually tested to confirm its runtime Origin is covered by the `wails://` allow rule.
+
+### Finding ID: SEC-20260616-1702-002
+
+#### Title
+
+SFTP upload name `..` escaped selected remote directory
+
+#### Severity
+
+Medium
+
+#### Confidence
+
+High
+
+#### Affected Files / Components
+
+- `internal/api/api.go`
+- `internal/api/api_test.go`
+- `SFTPUploadData`
+- `SFTPUploadStart`
+
+#### Description
+
+`safeSFTPUploadName` normalized slash variants and used `path.Base`, but did not reject the special basename `..`. `path.Join(remoteDir, "..")` resolves to the parent directory, so a Wails caller could escape the selected upload directory.
+
+#### Evidence
+
+The previous rejection covered empty, `.`, `/`, and NUL, but not `..`. The upload methods then used `path.Join(remoteDir, safeName)`.
+
+#### Attack Scenario
+
+A malicious renderer call invokes chunked upload with `remoteDir="/home/user/upload"` and `fileName=".."`. The destination path resolves to `/home/user`, outside the selected directory.
+
+#### Impact
+
+Unexpected remote writes/truncation attempts outside the user's selected SFTP directory, depending on server permissions and target type.
+
+#### Recommendation
+
+Reject `..` after basename normalization.
+
+#### Safer Example
+
+Implemented `safeName == ".."` rejection.
+
+#### Suggested Tests
+
+Added `TestSafeSFTPUploadNameRejectsParentDirectory`.
+
+#### References
+
+- CWE-22: Path Traversal
+- OWASP ASVS 12.3: File path control
+
+#### Assumptions / Limitations
+
+The browser `File.name` API normally does not produce `..`, but Wails API methods are still a trust boundary and should validate independently.
+
+### Finding ID: SEC-20260616-1702-003
+
+#### Title
+
+SSH config import lacked total file and Host-block bounds
+
+#### Severity
+
+Low
+
+#### Confidence
+
+High
+
+#### Affected Files / Components
+
+- `internal/sshconfig/sshconfig.go`
+- `internal/sshconfig/sshconfig_test.go`
+- `ImportSSHConfig`
+
+#### Description
+
+The OpenSSH config parser scanned files line-by-line, but it did not cap total file size or the number of accumulated Host blocks. A very large selected config could allocate a large slice of parsed blocks and profiles.
+
+#### Evidence
+
+`ParseFile` opened the file and appended Host blocks to an in-memory slice until EOF.
+
+#### Attack Scenario
+
+A user imports a hostile or accidentally huge SSH config containing thousands of Host blocks. The app spends unnecessary CPU and memory parsing and converting entries.
+
+#### Impact
+
+Local denial of service or UI unresponsiveness during import.
+
+#### Recommendation
+
+Reject oversized config files, set a scanner line cap, and reject excessive Host-block counts.
+
+#### Safer Example
+
+Implemented `maxConfigFileBytes`, `maxConfigLineBytes`, and `maxHostBlocks`.
+
+#### Suggested Tests
+
+Added oversized-file and excessive-Host-block tests.
+
+#### References
+
+- CWE-400: Uncontrolled Resource Consumption
+
+#### Assumptions / Limitations
+
+The selected caps are conservative for normal OpenSSH config files. Extremely large enterprise configs may need batch import support later.
+
+### Finding ID: SEC-20260616-1702-004
+
+#### Title
+
+SSH key generation allowed expensive caller-controlled options without timeout
+
+#### Severity
+
+Low
+
+#### Confidence
+
+High
+
+#### Affected Files / Components
+
+- `internal/api/api.go`
+- `internal/api/api_test.go`
+- `GenerateSSHKey`
+
+#### Description
+
+The frontend exposes fixed key-type and bit-size choices, but the backend method accepted caller-supplied values directly and ran `ssh-keygen` without a context timeout. A malformed renderer call could request unsupported types or excessive RSA bit sizes, tying up the subprocess.
+
+#### Evidence
+
+`GenerateSSHKey` passed `keyType` to `ssh-keygen -t` and only checked `bits > 0` for RSA before adding `-b`.
+
+#### Attack Scenario
+
+A malicious renderer call requests a very large RSA key size. `ssh-keygen` consumes CPU for an extended period or fails slowly.
+
+#### Impact
+
+Local CPU denial of service and poor recovery if the subprocess hangs.
+
+#### Recommendation
+
+Validate allowed key types and RSA sizes server-side, and execute `ssh-keygen` with a timeout.
+
+#### Safer Example
+
+Implemented `validateSSHKeyGenerationOptions` and `exec.CommandContext` with a 30 second timeout.
+
+#### Suggested Tests
+
+Added validation tests for defaults, RSA defaults, oversized RSA sizes, and unsupported key types.
+
+#### References
+
+- CWE-400: Uncontrolled Resource Consumption
+- CWE-20: Improper Input Validation
+
+#### Assumptions / Limitations
+
+The timeout is a safety net, not a substitute for platform-level process controls. Real key generation should still be manually tested on slower hardware.
+
+### Finding ID: SEC-20260616-1702-005
+
+#### Title
+
+GitHub repo/ref path interpolation and uncapped archive stream
+
+#### Severity
+
+Medium
+
+#### Confidence
+
+High
+
+#### Affected Files / Components
+
+- `internal/githubclient/githubclient.go`
+- `internal/githubclient/githubclient_test.go`
+- `FetchLatestCommit`
+- `DownloadRepoArchive`
+
+#### Description
+
+Repository full names and refs were interpolated into REST API paths without escaping. The archive download also streamed response bodies to disk without an explicit maximum. A malformed renderer call, unusual branch name, or compromised GitHub Enterprise endpoint could create surprising request paths or consume disk.
+
+#### Evidence
+
+The client built paths with `fmt.Sprintf("%s/repos/%s/commits/%s", ...)` and copied archives with `io.Copy(file, resp.Body)`.
+
+#### Attack Scenario
+
+A renderer calls archive download with a malformed repo full name containing extra path segments, or a malicious GitHub Enterprise endpoint returns an unbounded archive response.
+
+#### Impact
+
+Potential confused API requests using the user's GitHub token and local disk exhaustion from unbounded archive streams.
+
+#### Recommendation
+
+Require `owner/repo` format, URL-escape each API path segment, and cap archive streams.
+
+#### Safer Example
+
+Implemented `splitRepoFullName`, `endpointURL`, `copyLimitedArchive`, and a 2 GiB archive cap.
+
+#### Suggested Tests
+
+Added tests for escaped refs, malformed repo names, archive limit rejection, and at-limit copies.
+
+#### References
+
+- CWE-20: Improper Input Validation
+- CWE-22: Path Traversal style path confusion
+- CWE-400: Uncontrolled Resource Consumption
+
+#### Assumptions / Limitations
+
+The 2 GiB archive cap may reject unusually large repositories. A future preferences setting could make this user-configurable.
+
+### Finding ID: SEC-20260616-1702-006
+
+#### Title
+
+SSH key manager rendered key names/errors through dynamic `innerHTML`
+
+#### Severity
+
+Medium
+
+#### Confidence
+
+High
+
+#### Affected Files / Components
+
+- `frontend/src/js/sshkeys.js`
+- `frontend/scripts/test-regressions.js`
+- SSH key manager modal
+
+#### Description
+
+The SSH key manager interpolated backend error text and confirmation title/message/button text into `innerHTML`. Key names are derived from local `~/.ssh/*.pub` filenames, so a malicious local filename could inject HTML into the delete confirmation modal.
+
+#### Evidence
+
+The previous code used `list.innerHTML = `<div ...>${err}</div>`` and built confirmation modal HTML with `${title}`, `${message}`, and `${confirmLabel}`.
+
+#### Attack Scenario
+
+A local attacker creates an SSH public key file with an HTML-like filename. When the user opens the key manager and deletes it, the filename is interpolated into modal HTML.
+
+#### Impact
+
+DOM XSS in the Wails renderer, with possible access to app UI actions exposed to the renderer.
+
+#### Recommendation
+
+Render dynamic strings with `textContent` or DOM node construction.
+
+#### Safer Example
+
+Implemented text-node rendering for key load errors and confirmation modal dynamic text.
+
+#### Suggested Tests
+
+Added frontend regression checks to prevent the vulnerable interpolation pattern from returning.
+
+#### References
+
+- CWE-79: Cross-Site Scripting
+- OWASP ASVS 5.3: Output encoding
+
+#### Assumptions / Limitations
+
+Other static-template `innerHTML` use remains in the frontend and should continue to be reviewed when it accepts dynamic values.
+
+## 8. Blackhat-Style Abuse Paths
+
+Path 1: Token leak to VNC abuse
+
+- Prerequisite: an active VNC proxy URL leaks to a non-app webpage or injected script.
+- Old path: any Origin could connect and send arbitrary WebSocket frames to the VNC TCP bridge.
+- Breakpoint added: Wails/loopback Origin allowlist plus message cap.
+
+Path 2: Renderer-to-remote path escape
+
+- Prerequisite: malicious renderer code or direct Wails call.
+- Old path: call SFTP upload with filename `..`, causing `path.Join(remoteDir, "..")`.
+- Breakpoint added: `..` is rejected after basename normalization.
+
+Path 3: Local filename to renderer script injection
+
+- Prerequisite: crafted key filename in `~/.ssh`.
+- Old path: key name appears in confirmation modal HTML.
+- Breakpoint added: key names and errors use `textContent`.
+
+Path 4: Malicious GitHub Enterprise response to disk pressure
+
+- Prerequisite: user connects to compromised or malicious API base URL allowed by profile validation.
+- Old path: archive stream was copied until EOF.
+- Breakpoint added: Content-Length precheck and streaming cap.
+
+## 9. Denial-of-Service Review
+
+Fixed resource-control issues:
+
+- VNC inbound WebSocket message cap.
+- SSH config file size, line size, and Host-block caps.
+- SSH key generation input validation and subprocess timeout.
+- GitHub archive stream cap.
+
+Previously fixed and rechecked from recent audit context:
+
+- GitHub/update JSON response caps.
+- Leviathan bounded reads and chunked save/export paths.
+- SFTP inline/chunk upload caps.
+- Secret vault and SSH key file read caps.
+
+Residual DoS considerations:
+
+- SFTP directory listings depend on remote server behavior and can still return large lists.
+- GitHub repository enrichment intentionally caps total repositories but still performs concurrent commit lookups.
+- Very large legitimate GitHub archives above 2 GiB now fail fast.
+
+## 10. Dependency and Supply-Chain Review
+
+Results:
+
+- `npm --prefix frontend audit --omit=dev`: 0 vulnerabilities.
+- `govulncheck ./...`: no vulnerabilities found.
+
+Reviewed manifests:
+
+- `go.mod`
+- `go.sum`
+- `frontend/package.json`
+- `frontend/package-lock.json`
+- `.github/workflows/release-builds.yml`
+
+No high-confidence dependency findings were found in this pass.
+
+## 11. Secrets and Sensitive Data Review
+
+Checked:
+
+- No obvious private keys, GitHub tokens, cloud keys, or hardcoded credentials were found in source outside documentation/examples.
+- Non-secret profile export redaction was already covered by tests.
+- Secret access logging records secret type, not value.
+- GitHub Authorization headers are set only in HTTP requests and not logged by this code.
+
+Residual:
+
+- Plain exports without secrets are safer, but encrypted export remains the recommended path for portable backups.
+- Local audit logs should continue to avoid host/user secrets in future features.
+
+## 12. Authentication and Authorisation Review
+
+This is a local desktop application, so there are no server-side user roles or tenant boundaries. Relevant controls reviewed:
+
+- SSH host-key callback requirement for VNC SSH tunnels.
+- Known-host storage and verification paths.
+- Secret retrieval via keychain/vault and prompt callbacks.
+- GitHub token validation before repo fetch.
+
+No missing multi-user authorization checks apply to the current architecture.
+
+## 13. Input Validation and Output Encoding Review
+
+Fixed:
+
+- SFTP upload basename `..`.
+- SSH key generation key type and RSA bit sizes.
+- GitHub repo full-name format and path segment escaping.
+- SSH key manager dynamic output encoding.
+
+Previously present controls:
+
+- Profile validation rejects invalid hosts, ports, secret modes, GitHub HTTP non-loopback base URLs, and malformed protocol configs.
+- Import profiles are size-capped and validated before persistence.
+
+## 14. Frontend HTML/JavaScript Robustness Review
+
+Fixed:
+
+- SSH key manager load errors now render via `textContent`.
+- SSH key deletion confirmation modal dynamic strings now render via DOM nodes/text.
+- Regression script now checks these patterns.
+
+Checked:
+
+- Wails service bridge ordering remains covered by regression checks.
+- SFTP drag/drop upload still uses chunked methods.
+- Direct VNC warning flow remains covered by regression checks.
+
+Residual:
+
+- Frontend still contains many static `innerHTML` templates. Future reviews should focus on any template that accepts local filesystem, remote host, profile, update, or GitHub data.
+
+## 15. Infrastructure and Deployment Review
+
+Reviewed:
+
+- GitHub Actions release workflow.
+- Wails build config.
+- Frontend build scripts.
+
+No new high-confidence release workflow finding was fixed. The workflow uses pinned major versions for common actions and default GitHub token permissions scoped to release attachment needs.
+
+Residual:
+
+- Consider adding checksums/SBOM generation for release artifacts.
+- Consider a CI job for `go test ./...`, frontend regression tests, `npm audit --omit=dev`, and `govulncheck`.
+
+## 16. Logging, Monitoring, and Error Handling Review
+
+Fixed:
+
+- SSH key manager no longer injects raw error strings into HTML.
+- GitHub malformed repo names now fail before request construction.
+- SSH keygen timeout returns a specific timeout error.
+
+Checked:
+
+- Error messages added in this pass do not include tokens, passwords, or key material.
+- Existing audit logger records profile/session actions and secret access metadata.
+
+## 17. Test Coverage and Security Regression Gaps
+
+Added:
+
+- VNC Origin allowlist tests.
+- SFTP parent-directory upload name tests.
+- SSH key generation option validation tests.
+- SSH config oversized file and Host-block cap tests.
+- GitHub URL escaping, malformed full-name, and archive cap tests.
+- Frontend static regression checks for SSH key manager safe rendering.
+
+Remaining gaps:
+
+- No packaged Wails/noVNC integration test for Origin behavior.
+- No E2E browser test for SSH key modal rendering with hostile filenames.
+- No integration test for GitHub archive cap against an HTTP test server.
+
+## 18. Prioritised Remediation Plan
+
+Immediate:
+
+- Manually test VNC connections in a packaged Wails app to verify the Origin allowlist.
+- Keep the new security tests in CI.
+
+Short-term:
+
+- Add an E2E test for SSH key manager hostile filenames.
+- Add an HTTP integration test for GitHub archive caps and escaped refs.
+- Surface user-friendly errors for new caps in the UI.
+
+Medium-term:
+
+- Add CI security checks for `govulncheck`, `npm audit --omit=dev`, and `git diff --check`.
+- Add release artifact checksums and an SBOM.
+
+Long-term:
+
+- Continue replacing dynamic frontend `innerHTML` where data provenance is mixed.
+- Add configurable large-download limits for GitHub archives and SFTP operations.
+
+## 19. False Positives / Needs Manual Verification
+
+- VNC Origin policy should be validated in macOS, Windows, and Linux packaged Wails builds.
+- The 2 GiB GitHub archive cap should be validated against expected user repository sizes.
+- The SSH keygen 30 second timeout should be checked on slow hardware, especially for RSA 4096.
+
+## 20. Final Notes
+
+This pass focused on concrete, testable hardening rather than broad speculative rewrites. The remaining risk is mostly runtime validation and UX around newly explicit limits. The repo still has an unrelated sidebar CSS spacing change in the working tree that was not part of this security audit.

audits/20260624-0945-functionalityNextSteps.md

@@ -0,0 +1,79 @@
+# Functionality and Next Steps Report
+
+## 1. Executive Summary
+
+This fix-mode pass improved VS Code extension robustness by hardening the local bridge and webview CSP handling. The highest-impact next step is runtime validation in a real VS Code host: the source-level tests pass, but the extension panels and long-lived bridge event stream deserve manual smoke coverage after the HTTP timeout and nonce changes.
+
+The codebase already has useful regression coverage for prior security fixes. The main opportunity now is to reduce duplicated webview HTML patterns and add integration tests around the VS Code bridge, because that surface currently depends heavily on static checks.
+
+## 2. Current Functional Risks
+
+- VS Code bridge `/events` uses a long-lived SSE stream. The new server has read/header/idle limits but intentionally no global write timeout, so a real VS Code smoke test should confirm events still flow correctly during SSH/SFTP/VNC/GitHub sessions.
+- VS Code webview HTML is duplicated across many panel classes. CSP, nonce generation, escaping, and message wiring are now correct in reviewed files, but duplication increases future regression risk.
+- The Node extension bridge client reads bridge responses without an explicit response-size cap or request timeout. The bridge is local and trusted, but a stuck bridge can still degrade the extension UX.
+- Frontend/webview coverage is mostly static regression assertions. It catches known bug patterns but does not prove that panels render and handlers fire inside VS Code.
+
+## 3. Code Quality Improvements
+
+- Centralise webview scaffolding in `vscode/nexus/extension.js` and `vscode/leviathan/extension.js`: CSP generation, nonce creation, common style policy, and HTML shell construction should live in one helper per extension or a shared local module.
+- Wrap bridge HTTP requests in a small client helper with timeout, response-size cap, JSON decode error handling, and consistent error messages.
+- Consider replacing large inline template-string webviews with smaller render helpers that build trusted static shell plus escaped dynamic content. The current approach is workable, but it makes security review repetitive.
+- Keep the bridge handler helpers small and testable. `newBridgeHTTPServer` and `decodeLimitedJSON` are a useful pattern for future endpoints.
+
+## 4. Frontend Interaction and Error-Handling Improvements
+
+- Add manual smoke steps for Nexus Connections, terminal, RAW, GitHub, IRC, VNC, Profile Editor, Settings, SFTP, Leviathan Tools, Leviathan Hex, and Leviathan tool panels.
+- Add non-sensitive `console.error` or visible status handling for JSON parse failures in VS Code webview message handlers where currently errors may be silent.
+- Validate that reconnect, resize, SFTP directory actions, GitHub refresh/download, and Leviathan tool execution still fire their expected events after panel reloads.
+- Confirm no webview logs secrets, bearer tokens, passwords, passphrases, private key material, or raw sensitive bridge responses.
+
+## 5. Testing Roadmap
+
+- Unit tests: keep `cmd/vscode-bridge` tests for server settings and body caps; add request method/auth tests for all bridge routes.
+- Integration tests: add socket-level bridge tests for slow headers, oversized headers, and idle connection cleanup.
+- VS Code extension smoke tests: exercise webview creation, command registration, bridge startup, one RPC, and one event frame.
+- Frontend interaction tests: use a browser/DOM harness for key Wails UI flows where practical, especially SFTP upload, profile import, SSH key management, and Leviathan mode switching.
+- Abuse-case tests: retain oversized import/upload/config tests and add edge cases whenever new parsers or bridge endpoints are introduced.
+- Release smoke tests: package VSIX files and assert expected files, CSP strings, media resources, and bridge executable permissions.
+
+## 6. Recommended New Functionality
+
+- Add an in-extension bridge diagnostics command that shows bridge status, version, last RPC error, and whether the event stream is connected, without exposing the bearer token.
+- Add a developer-only test command for the VS Code extension that opens each webview and posts a benign fixture state. This would make manual and automated smoke testing faster.
+- Add a small security status page or command that reports vault state, known-host policy, update-check source, and active local bridge address without sensitive values.
+
+## 7. Next-Level Opportunities
+
+- Create a shared webview rendering module for both Nexus and Leviathan extension panels, with typed helpers for CSP, escaping, buttons, and event wiring.
+- Introduce structured bridge RPC method allow-list metadata rather than reflective method dispatch alone. Reflection is convenient, but a visible allow-list would make the trust boundary easier to review.
+- Add observability around bridge request counts, rejected oversized requests, active event clients, and session lifecycle errors.
+- Add accessibility checks for VS Code webview panels, especially keyboard focus, button labels, and status updates in terminal/disconnected flows.
+
+## 8. Prioritised Action Plan
+
+Immediate:
+
+- Smoke-test the committed fix in a real VS Code host.
+- Confirm `/events` remains stable during session state changes.
+
+Short-term:
+
+- Add bridge client timeout and response-size caps in the Node extension code.
+- Add VS Code extension smoke tests for panel construction and bridge RPC.
+- Consolidate CSP nonce creation and webview HTML policy helpers.
+
+Medium-term:
+
+- Replace static-only regression assertions with executable DOM or VS Code integration tests for high-value panels.
+- Add bridge route coverage for auth failures, method errors, malformed JSON, and event subscription lifecycle.
+
+Long-term:
+
+- Build a release validation pipeline for desktop app, bridge binary, and VSIX packages.
+- Add structured diagnostics and observability for local bridge health and rejected requests.
+
+## 9. Caveats and Validation Needed
+
+- Source and automated tests passed, but VS Code runtime behaviour was not manually exercised in this pass.
+- The CSP nonce change should be behaviour-preserving, but every webview panel should still be opened once in VS Code.
+- The bridge timeout settings are conservative for local RPC; long-running operations should continue reporting progress through events rather than blocking a single HTTP request indefinitely.

audits/20260624-0945-securityAudit.md

@@ -0,0 +1,361 @@
+# Security Audit Report
+
+## 1. Executive Summary
+
+This fix-mode audit reviewed the Nexus desktop app, VS Code extensions, local bridge process, frontend regression harness, prior audit findings, dependency manifests, and build/test configuration. The codebase is in a materially better posture than the earlier June audits: major Wails, SFTP, VNC proxy, GitHub API, import-size, SSH key generation, and frontend DOM issues were already fixed and covered by tests.
+
+Two remaining issues were confirmed and fixed in commit `3a16a14`:
+
+- The VS Code bridge's localhost HTTP server had no explicit header/body read timeouts and decoded JSON request bodies without a hard cap.
+- VS Code webview CSP nonces were derived from `Date.now()`, which made a script allow-list nonce predictable rather than cryptographically random.
+
+Verification passed with targeted bridge tests, full Go tests, frontend regression checks, frontend build, `npm audit --omit=dev`, `govulncheck`, JavaScript syntax checks, and `git diff --check`.
+
+## 2. Scope Reviewed
+
+Reviewed:
+
+- Go backend packages under `internal/` and the `cmd/vscode-bridge` localhost JSON-RPC/SSE bridge.
+- Browser-facing frontend JavaScript and regression checks under `frontend/`.
+- VS Code extension webviews in `vscode/nexus/extension.js` and `vscode/leviathan/extension.js`.
+- Dependency manifests: `go.mod`, `go.sum`, `frontend/package.json`, `frontend/package-lock.json`, VS Code extension package manifests.
+- Build, release, and CI files including shell scripts and `.github/workflows/release-builds.yml`.
+- Existing audit reports under `audits/` to avoid duplicate findings.
+
+Not fully live-tested:
+
+- Packaged VS Code extensions inside a real VS Code host after the CSP nonce change.
+- Long-lived bridge event streams under deliberate slow-client conditions.
+- Packaged Wails binaries on all target operating systems.
+
+## 3. Methodology
+
+I used static review, adversarial attack-surface mapping, dependency review, configuration review, DoS review, frontend/webview review, and targeted regression tests. I traced attacker-controlled inputs from webviews, the VS Code extension host, local HTTP requests, imported files, remote services, and session events into filesystem, process, network, DOM, and parser boundaries.
+
+Commands run:
+
+- `node --check vscode/nexus/extension.js`
+- `node --check vscode/leviathan/extension.js`
+- `node --check frontend/scripts/test-regressions.js`
+- `go test ./cmd/vscode-bridge -count=1`
+- `npm --prefix frontend test`
+- `git diff --check`
+- `go test ./... -count=1`
+- `npm --prefix frontend run build`
+- `npm --prefix frontend audit --omit=dev`
+- `go run golang.org/x/vuln/cmd/govulncheck@latest ./...`
+
+## 4. Risk Rating Method
+
+Severity reflects attacker position, exploit practicality, affected trust boundary, and confidentiality/integrity/availability impact. Confidence reflects direct source evidence and regression coverage.
+
+- Critical: unauthenticated remote compromise or credential disclosure.
+- High: practical credential theft, code execution, or privilege escalation.
+- Medium: meaningful local, renderer, or connected-service abuse with realistic prerequisites.
+- Low: defence-in-depth or bounded local robustness issue.
+- Informational: hardening or validation gaps without a direct exploit path.
+
+## 5. Attack Surface Map
+
+Entry points:
+
+- Wails-bound API methods callable from the renderer.
+- VS Code extension webviews and their `postMessage` handlers.
+- `cmd/vscode-bridge` localhost HTTP endpoints: `/health`, `/rpc`, `/events`, and `/runtime/event`.
+- SSH, SFTP, Telnet, RAW TCP, VNC, GitHub, IRC, local shell, updater, recording, export/import, and Leviathan binary-analysis workflows.
+
+Trust boundaries:
+
+- Renderer/webview to Go backend.
+- Local browser or extension host to localhost bridge.
+- Local selected files and profile imports to parsers.
+- Remote GitHub, SSH/SFTP/VNC/IRC/Telnet/RAW endpoints to client code.
+- OS keychain/vault to profile/session runtime.
+
+Attacker starting positions considered:
+
+- Local unprivileged process attempting bridge resource exhaustion.
+- Malicious or compromised extension webview state.
+- Hostile remote service data rendered into webviews.
+- Malicious selected local file or imported profile/export.
+- Compromised connected host attempting terminal/session abuse.
+
+## 6. Findings Summary Table
+
+| ID | Severity | Confidence | Title | Component | Status |
+|---|---|---|---|---|---|
+| SEC-20260624-0945-001 | Low | High | VS Code bridge accepted unbounded HTTP parser work | `cmd/vscode-bridge` | Fixed in `3a16a14` |
+| SEC-20260624-0945-002 | Low | High | VS Code webview CSP nonces used predictable timestamps | `vscode/nexus`, `vscode/leviathan` | Fixed in `3a16a14` |
+
+## 7. Detailed Findings
+
+### Finding ID: SEC-20260624-0945-001
+
+#### Title
+
+VS Code bridge accepted unbounded HTTP parser work
+
+#### Severity
+
+Low
+
+#### Confidence
+
+High
+
+#### Affected Files / Components
+
+- `cmd/vscode-bridge/main.go:120`
+- `cmd/vscode-bridge/main.go:212`
+- `cmd/vscode-bridge/main.go:230`
+- `cmd/vscode-bridge/main.go:336`
+- `cmd/vscode-bridge/main.go:346`
+- `cmd/vscode-bridge/main_test.go:11`
+- `cmd/vscode-bridge/main_test.go:28`
+- `cmd/vscode-bridge/main_test.go:48`
+
+#### Description
+
+The bridge listens only on localhost and requires a random bearer token, but the HTTP server previously used default server timeouts and decoded JSON bodies directly from `r.Body`. A local process, or a compromised component with bridge token access, could keep connections open or send oversized JSON to force unnecessary parser work and memory use.
+
+#### Evidence
+
+Before the fix, `server := &http.Server{Handler: mux}` used default timeout values, and `/rpc` plus `/runtime/event` called `json.NewDecoder(r.Body).Decode(...)` without `http.MaxBytesReader`.
+
+The fix adds explicit bridge limits at `cmd/vscode-bridge/main.go:50`, uses `newBridgeHTTPServer` at `cmd/vscode-bridge/main.go:126`, and applies `decodeLimitedJSON` in both POST handlers at `cmd/vscode-bridge/main.go:218` and `cmd/vscode-bridge/main.go:236`.
+
+#### Attack Scenario
+
+A local unprivileged process repeatedly connects to the bridge and sends slow headers or a large authenticated JSON body. Without timeouts and body caps, the bridge can spend disproportionate time and memory on unauthorised or oversized traffic.
+
+#### Impact
+
+Local denial of service against the VS Code extension bridge, causing sluggishness, failed RPCs, or event-stream disruption.
+
+#### Recommendation
+
+Set bounded HTTP server timeouts and header limits. Cap JSON request bodies before decoding. Keep long-lived SSE compatibility by avoiding a global `WriteTimeout` that would break event streams.
+
+#### Safer Example
+
+Implemented:
+
+```go
+r.Body = http.MaxBytesReader(w, r.Body, bridgeMaxJSONBodyBytes)
+return json.NewDecoder(r.Body).Decode(dst)
+```
+
+#### Suggested Tests
+
+Added tests that assert bridge timeout/header settings and oversized `/rpc` plus `/runtime/event` bodies are rejected before reflective service dispatch.
+
+#### References
+
+- CWE-400: Uncontrolled Resource Consumption
+- OWASP ASVS 12.1: File and resource handling
+- OWASP API Security Top 10 API4: Unrestricted Resource Consumption
+
+#### Assumptions / Limitations
+
+The practical attacker is local, because the bridge binds to `127.0.0.1`. The bearer token remains an important control, but it is not a substitute for parser and server resource limits.
+
+### Finding ID: SEC-20260624-0945-002
+
+#### Title
+
+VS Code webview CSP nonces used predictable timestamps
+
+#### Severity
+
+Low
+
+#### Confidence
+
+High
+
+#### Affected Files / Components
+
+- `vscode/nexus/extension.js:5`
+- `vscode/nexus/extension.js:10`
+- `vscode/nexus/extension.js:219`
+- `vscode/nexus/extension.js:554`
+- `vscode/nexus/extension.js:895`
+- `vscode/nexus/extension.js:1061`
+- `vscode/nexus/extension.js:1162`
+- `vscode/nexus/extension.js:1260`
+- `vscode/nexus/extension.js:1375`
+- `vscode/nexus/extension.js:1618`
+- `vscode/nexus/extension.js:1832`
+- `vscode/leviathan/extension.js:5`
+- `vscode/leviathan/extension.js:10`
+- `vscode/leviathan/extension.js:189`
+- `vscode/leviathan/extension.js:497`
+- `vscode/leviathan/extension.js:773`
+- `frontend/scripts/test-regressions.js:222`
+
+#### Description
+
+The VS Code webviews use CSP script nonces, but each nonce was previously `String(Date.now())`. CSP nonces are intended to be high-entropy, per-render allow-list values. A timestamp nonce is guessable and weakens CSP if an HTML injection primitive is introduced elsewhere.
+
+#### Evidence
+
+All `const nonce = String(Date.now());` occurrences in the VS Code extension files were replaced with `createCSPNonce()`, backed by `crypto.randomBytes(16).toString('base64')`.
+
+#### Attack Scenario
+
+An attacker finds or later introduces a webview HTML injection path that can emit a `<script nonce="...">` tag. A predictable timestamp nonce materially reduces the barrier to bypassing CSP, especially when the webview creation time is observable or inferable.
+
+#### Impact
+
+Defence-in-depth weakness for webview script execution controls. A full exploit still requires an injection path, but predictable nonces undermine the CSP layer that should contain that class of defect.
+
+#### Recommendation
+
+Generate CSP nonces with cryptographically secure random bytes for every webview render, and keep regression coverage preventing timestamp nonce reintroduction.
+
+#### Safer Example
+
+Implemented:
+
+```js
+function createCSPNonce() {
+  return crypto.randomBytes(16).toString('base64');
+}
+```
+
+#### Suggested Tests
+
+Added regression assertions that both VS Code extension files use `crypto.randomBytes(16).toString('base64')` and that `const nonce = String(Date.now());` is absent under `vscode/`.
+
+#### References
+
+- CWE-345: Insufficient Verification of Data Authenticity
+- CWE-693: Protection Mechanism Failure
+- OWASP ASVS 14.4: Security headers
+
+#### Assumptions / Limitations
+
+I did not confirm a current exploitable webview injection path in these files during this pass. This fix preserves the CSP guarantee if a future DOM/HTML bug appears.
+
+## 8. Blackhat-Style Abuse Paths
+
+Path 1: Local bridge exhaustion.
+
+Prerequisite: local code execution on the same machine. The attacker opens many slow or oversized bridge requests. Before the fix, default server settings and uncapped JSON decoding provided weaker resistance. Defensive breakpoint: `ReadHeaderTimeout`, `ReadTimeout`, `IdleTimeout`, `MaxHeaderBytes`, and `http.MaxBytesReader`.
+
+Path 2: Future webview injection to script execution.
+
+Prerequisite: an HTML injection sink in a VS Code webview. Predictable CSP nonces made it easier to craft a nonce-bearing script. Defensive breakpoint: cryptographic per-render nonces and continued escaping/text-node rendering.
+
+## 9. Denial-of-Service Review
+
+Fixed:
+
+- Local bridge header/body parsing now has explicit limits.
+- Oversized bridge JSON bodies are rejected before reflective RPC dispatch.
+
+Previously fixed and still covered by tests:
+
+- VNC WebSocket frame read limits.
+- SFTP upload chunk and streaming size controls.
+- SSH config import file and Host-block caps.
+- GitHub archive stream cap.
+- Update response caps.
+- Leviathan and recording file-size limits in reviewed paths.
+
+Residual DoS considerations:
+
+- Long-lived `/events` streams intentionally remain open; they should be observed under slow-client conditions in VS Code.
+- Remote SFTP operations still rely on remote server responsiveness and transport-level behaviour.
+- Binary-analysis features should continue adding per-tool time and output caps as new parsers are added.
+
+## 10. Dependency and Supply-Chain Review
+
+`npm --prefix frontend audit --omit=dev` reported zero production vulnerabilities. `govulncheck` reported no reachable Go vulnerabilities. The release workflow uses pinned major versions of common GitHub Actions but still installs Wails dynamically from the module version; that is acceptable but should be monitored in release hardening.
+
+## 11. Secrets and Sensitive Data Review
+
+No new hard-coded credentials or private keys were found in the changed files. The bridge token remains generated with `crypto/rand` and is emitted to the extension process over stdout. Secret storage continues to use OS keychain and encrypted vault mechanisms reviewed in earlier audits.
+
+## 12. Authentication and Authorisation Review
+
+The bridge still requires `Authorization: Bearer <token>`. The fix does not change bridge authorisation semantics. No new auth bypass was identified in this pass. Host key handling, SFTP path validation, GitHub URL validation, and profile validation had existing regression coverage from prior fixes.
+
+## 13. Input Validation and Output Encoding Review
+
+Fixed:
+
+- Bridge JSON input is bounded to 1 MiB before decoding.
+
+Checked:
+
+- VS Code webviews continue escaping interpolated profile, repository, SFTP, and Leviathan state before `innerHTML` usage in reviewed areas.
+- Frontend regression tests include prior checks for SSH key manager error rendering and SFTP upload name handling.
+
+## 14. Frontend HTML/JavaScript Robustness Review
+
+Fixed:
+
+- VS Code webview CSP nonces are now cryptographically random.
+
+Checked:
+
+- Existing frontend regression script still passes.
+- JavaScript syntax checks pass for both VS Code extension files and the regression script.
+
+Manual validation still needed:
+
+- Open the Nexus and Leviathan VS Code webviews in a real VS Code host and confirm all panels load under the stricter nonce generation.
+
+## 15. Infrastructure and Deployment Review
+
+The GitHub Actions release workflow was reviewed for obvious command injection or secret leakage. No new finding was fixed here. It still uses broad `contents: write` permissions for release attachment, which is appropriate for the release job but should remain isolated to tag/manual workflows.
+
+## 16. Logging, Monitoring, and Error Handling Review
+
+Bridge oversized-body failures return structured JSON errors through the existing RPC error path. No sensitive values are logged by the new code. The bridge still logs startup/server failures through `log`.
+
+## 17. Test Coverage and Security Regression Gaps
+
+Added:
+
+- Bridge server resource-limit tests.
+- Oversized `/rpc` body test.
+- Oversized `/runtime/event` body test.
+- Regression assertions preventing timestamp CSP nonces in VS Code webviews.
+
+Remaining gaps:
+
+- No automated VS Code host integration test exercises all webview panels.
+- No slowloris-style integration test measures bridge timeout behaviour over real sockets.
+- No e2e test validates the long-lived SSE event stream after server timeout changes.
+
+## 18. Prioritised Remediation Plan
+
+Immediate:
+
+- Manually smoke-test the packaged VS Code extension panels and bridge event stream.
+
+Short-term:
+
+- Add a small VS Code extension integration smoke test for webview creation and bridge RPC.
+- Add a socket-level bridge test for slow headers and idle connections.
+
+Medium-term:
+
+- Centralise VS Code webview HTML helpers so CSP, escaping, and nonce generation are not duplicated.
+- Add response-size caps and request timeouts in the Node extension bridge client.
+
+Long-term:
+
+- Add release-time security checks for packaged VSIX contents, binary hashes, and expected CSP coverage.
+
+## 19. False Positives / Needs Manual Verification
+
+- The CSP nonce issue is a defence-in-depth finding, not evidence of a currently exploitable XSS.
+- Bridge DoS impact is local because the bridge binds to localhost.
+- VS Code runtime behaviour was not manually validated inside the actual editor during this audit.
+
+## 20. Final Notes
+
+The confirmed issues were fixed and committed in `3a16a14`. The residual risk is mainly operational validation: verify the VS Code extension panels in a real host and keep expanding integration coverage for bridge and webview behaviour.

audits/20260729-1237-functionalityNextSteps.md

@@ -0,0 +1,197 @@
+# Functionality and Next Steps Report
+
+## 1. Executive Summary
+
+This fix-mode pass makes long-running Nexus processes more predictable:
+reconnect prompts no longer accumulate runtime listeners, unfinished SFTP
+uploads are bounded and cancelled with their owning sessions, and application
+shutdown drains prompt, listener, session, and upload state. IPv6 literals now
+work in the reviewed VNC, IRC tunnel, and connection-test paths.
+
+The full backend, race, frontend, build, syntax, and dependency checks pass.
+The highest-value next step is a packaged long-duration soak test using real
+local and remote tabs. Unit tests prove the new ownership rules, but only a live
+test will show whether CPU, memory, goroutine, descriptor, and remote-session
+counts remain flat across thousands of open/close/reconnect cycles.
+
+## 2. Current Functional Risks
+
+- Application-level cleanup is now explicit, but remote libraries and OS
+  resources need live soak validation with real SSH, SFTP, VNC, IRC, Telnet,
+  RAW, and local shell sessions.
+- SFTP partial-file removal is best-effort. If a transport is already dead,
+  Nexus can close its local writer but may be unable to remove the remote
+  partial file.
+- External Leviathan extractors can run subprocesses without a shared timeout,
+  output-byte cap, or file-count cap. This path should remain unexposed until
+  those controls exist.
+- Parser test coverage varies by format. Complex hostile files may still find
+  correctness or performance edge cases not represented by current fixtures.
+- Several frontend areas still render trusted templates through `innerHTML`.
+  Existing dynamic values are escaped in reviewed paths, but DOM-based
+  construction would be less fragile for future edits.
+- Four Go module versions have advisories in code paths Nexus does not call.
+  They are not current reachable vulnerabilities, but routine dependency
+  refresh will reduce future uncertainty.
+- POSIX permission tests do not establish equivalent Windows ACL behaviour.
+
+## 3. Code Quality Improvements
+
+- Make ownership visible in types and naming. Sessions should own reconnect
+  contexts, uploads, protocol clients, terminal resources, and timers through a
+  single idempotent close path.
+- Introduce a small lifecycle registry for application-level Wails listeners.
+  The new stored unsubscribe functions are correct; a shared helper would make
+  future listeners harder to leak.
+- Replace `time.After` in long-lived or high-frequency paths with owned timers
+  when cancellation or reuse matters. The current reconnect prompt has bounded
+  frequency, but an owned timer makes resource lifetime more explicit.
+- Return structured cleanup results for unfinished uploads: local writer
+  closed, remote partial removed, or remote removal unavailable. This would
+  improve diagnostics without turning cleanup failure into a tab-close
+  blocker.
+- Centralise network endpoint formatting so every protocol consistently uses
+  `net.JoinHostPort` and one port-validation helper.
+- Keep frontend regression assertions aligned with tracked source. The audit
+  removed assertions for the intentionally deleted VS Code tree and replaced
+  the obsolete CGO flag check with the current pure-Go invariant.
+
+## 4. Frontend Interaction and Error-Handling Improvements
+
+- When a tab closes during an upload, display a brief non-blocking message that
+  the upload was cancelled and whether a remote partial file may remain.
+- Make credential-prompt cancellation explicit in the UI so a reconnect
+  cancellation is distinguishable from a wrong password or timeout.
+- Add an unobtrusive diagnostics panel showing counts only: open tabs, active
+  protocol sessions, reconnect workers, pending prompts, streaming uploads,
+  goroutines, and recent cleanup failures.
+- Disable or debounce reconnect controls while a reconnect is already in
+  progress.
+- Prefer `textContent`, element creation, and event delegation for dynamic UI
+  state. Keep `innerHTML` for reviewed static templates only.
+- Ensure every async action rechecks that its tab/session still exists before
+  updating the DOM. This prevents late remote responses from reviving stale
+  state or producing confusing errors.
+- Never put passwords, vault contents, tokens, private keys, bridge tokens, or
+  terminal contents in diagnostics or frontend logs.
+
+## 5. Testing Roadmap
+
+Immediate automated coverage:
+
+- Add tests that call `Service.Shutdown` and `Manager.Shutdown` twice to enforce
+  idempotence.
+- Add a race test where an SFTP chunk write, session close, and shutdown overlap.
+- Add tests for a capacity race where two upload starts pass the pre-check and
+  only one may claim the final slot.
+- Add address-table tests for IPv4, DNS names, bare IPv6, and scoped IPv6
+  literals.
+
+Packaged soak coverage:
+
+- Start with zero tabs and record CPU, RSS, goroutines, descriptors, and
+  listener/upload counts.
+- Repeat local terminal open/write/close and SSH open/reconnect/close at least
+  1,000 times.
+- Repeat cancelled credential prompts and interrupted SFTP uploads.
+- Leave two idle tabs open for several hours and confirm resource counts and
+  CPU settle rather than grow.
+- Shut down and verify all subprocesses, sockets, PTYs, uploads, and runtime
+  listeners terminate.
+
+Protocol integration coverage:
+
+- Real SFTP server: finish, cancel, disconnect mid-chunk, reconnect, dead
+  transport, and remote partial-file cleanup.
+- Real IPv6 endpoints for VNC and SSH-tunnelled IRC/VNC.
+- Host-key accept/reject/cancel and secret prompt cancel/timeout.
+- Slow or malicious peers for protocol read limits and cancellation.
+
+Parser and frontend coverage:
+
+- Fuzz the PE, ELF, Mach-O, SquashFS, PDF, archive, and transform entry points.
+- Add DOM tests for tab close during asynchronous callbacks.
+- Keep `npm test`, frontend build, `go vet`, focused race tests,
+  `govulncheck`, and `npm audit` as release gates.
+
+## 6. Recommended New Functionality
+
+- Add a resource diagnostics view with current and peak counts for tabs,
+  sessions, reconnects, prompts, uploads, goroutines, file descriptors where
+  available, and local child processes.
+- Add an optional "delete partial remote upload on disconnect" status/history
+  entry, including a retry action after reconnect.
+- Add a developer soak command that scripts repeated open/reconnect/close
+  cycles against safe fixture servers and emits a machine-readable resource
+  summary.
+- Add an export-permission warning when the destination filesystem cannot
+  enforce private file access.
+- Add a dependency-health command for development builds that reports the Go
+  toolchain version and last audit result without contacting external services
+  during normal application use.
+
+## 7. Next-Level Opportunities
+
+- Build one lifecycle coordinator that owns application listeners, service
+  uploads, sessions, reconnect workers, protocol clients, timers, and local
+  subprocesses. A small dependency graph would make shutdown ordering
+  testable.
+- Add pprof-enabled development builds and automated before/after heap,
+  goroutine, mutex, and CPU profile comparisons during soak tests.
+- Introduce fault injection around remote writes, EOF, connection resets,
+  prompt cancellation, delayed events, and shutdown.
+- Wrap external analysis tools in a sandbox-oriented runner with a context
+  deadline, process-group kill, private working directory, output byte/file
+  limits, and a minimal environment.
+- Add signed, reproducible release metadata and verify the expected Go
+  toolchain, module graph, frontend lock file, and artefact hashes in CI.
+
+## 8. Prioritised Action Plan
+
+Immediate:
+
+- Run a packaged local/remote tab soak test and capture resource graphs before
+  and after `b5c7528`.
+- Validate interrupted SFTP uploads against a real server.
+- Confirm shutdown leaves no Nexus child process, PTY, listener, or open
+  connection.
+
+Short-term:
+
+- Add shutdown-idempotence and overlapping upload/close race tests.
+- Add resource counters and a development diagnostics view.
+- Refresh modules with unreachable advisories under a dedicated compatibility
+  change.
+- Add live IPv6 integration tests.
+
+Medium-term:
+
+- Add parser fuzzing and external extractor limits.
+- Reduce dynamic HTML construction and add DOM lifecycle tests.
+- Add fault-injected protocol integration tests.
+
+Long-term:
+
+- Make packaged soak, vulnerability, dependency, race, and artefact checks part
+  of release qualification.
+- Track resource-count baselines so gradual lifecycle regressions fail before
+  release.
+
+## 9. Caveats and Validation Needed
+
+- Automated checks passed, but no packaged Wails application was opened during
+  this audit.
+- No real remote protocol server was used, so remote partial-file behaviour and
+  third-party client cleanup still need live confirmation.
+- The CPU symptom was not reproduced under a profiler in this pass. The
+  reconnect listener leak and upload leak were confirmed from source and fixed,
+  but they should not be claimed as the only possible causes of historical
+  high CPU without a profile from an affected long-running process.
+- Filesystem permission behaviour was validated on the current POSIX host, not
+  Windows ACLs or every network filesystem.
+- `clear` reduces the lifetime of mutable sensitive byte slices but does not
+  guarantee complete memory erasure in Go.
+- `govulncheck` reports no reachable vulnerability after the toolchain update;
+  its four module-only advisories still deserve normal upgrade testing.
+- The deleted VS Code extension sources were not audited as current code. Only
+  the still-tracked Go bridge was reviewed.

audits/20260729-1237-securityAudit.md

@@ -0,0 +1,858 @@
+# Security Audit Report
+
+## 1. Executive Summary
+
+This fix-mode audit reviewed the current Nexus desktop application, its local
+VS Code bridge process, browser-facing frontend, session and upload lifecycles,
+credential handling, network clients, encrypted storage and export, Leviathan
+file analysis, build/release configuration, dependencies, and earlier audit
+reports.
+
+No Critical or High severity vulnerability was confirmed. Four
+evidence-backed findings were fixed in commit `b5c7528`:
+
+- Auto-reconnect credential prompts registered a permanent Wails listener on
+  every prompt. Long-running processes with repeated reconnects accumulated
+  callbacks and unnecessary event-dispatch work.
+- Interrupted streaming SFTP uploads could retain open remote writers and
+  in-memory upload entries after their session closed. Concurrent unfinished
+  uploads were not bounded.
+- The accepted Go toolchain range included versions affected by a reachable
+  standard-library TLS privacy vulnerability.
+- Encrypted exports and Leviathan carve output did not consistently enforce
+  private local file permissions. Short-lived plaintext and derived key byte
+  slices were also retained until garbage collection.
+
+The same commit fixed malformed IPv6 host/port construction in VNC, IRC SSH
+tunnels, and the connection tester, and repaired stale frontend regression
+assertions left behind when the VS Code extension tree and CGO build were
+removed.
+
+All Go tests, focused race tests, Go vet, the complete frontend test suite,
+frontend production build, JavaScript and shell syntax checks, PHP syntax
+check, `npm audit`, and the reachable Go vulnerability scan pass. Live remote
+protocol testing and packaged desktop testing remain manual validation items.
+
+## 2. Scope Reviewed
+
+Reviewed:
+
+- Go packages under `internal/`, including sessions, SSH, SFTP, VNC, IRC,
+  Telnet, RAW TCP, local shells, storage, vault/keychain integration,
+  recording, updater, GitHub client, import/export, and Leviathan.
+- The localhost service bridge in `cmd/vscode-bridge`.
+- Frontend source, lifecycle handling, DOM construction, timers, Wails event
+  subscriptions, build scripts, and regression harness under `frontend/`.
+- Network address construction, host-key verification, connection setup, and
+  session shutdown paths.
+- Dependency manifests and lock files.
+- Build, release, update, and CI configuration.
+- Earlier reports under `audits/`, to distinguish regressions from already
+  fixed findings.
+
+Not live-tested:
+
+- Packaged Wails applications on every supported operating system.
+- Real SSH, SFTP, VNC, IRC, Telnet, RAW, GitHub, or update endpoints.
+- Malicious network peers under sustained load.
+- External Leviathan extractor tools. Their extraction path is not currently
+  exposed by the active Wails document response.
+- A VS Code extension runtime, because the `vscode/` source tree was
+  intentionally removed in commit `4fc3b19`.
+
+## 3. Methodology
+
+The review combined:
+
+- Repository and Git-history inspection.
+- Trust-boundary and attacker-starting-position mapping.
+- Static review of authentication, authorisation, secrets, cryptography,
+  filesystem operations, command execution, parsers, network clients, event
+  listeners, goroutines, timers, and cleanup paths.
+- Adversarial resource-exhaustion review, with particular attention to a
+  process that has run for a long time while tabs and sessions are repeatedly
+  opened, reconnected, and closed.
+- Frontend sink/source review for unsafe HTML, event-listener accumulation,
+  timers, stale state, and privileged Wails calls.
+- Dependency and supply-chain scanning.
+- Focused regression tests followed by broad test, race, build, syntax, and
+  static-analysis checks.
+
+Principal validation commands:
+
+- `go test ./... -count=1`
+- `go test -race ./internal/sessions ./internal/api ./internal/exportimport ./internal/vncclient ./cmd/vscode-bridge -count=1`
+- `go vet ./...`
+- `go run golang.org/x/vuln/cmd/govulncheck@latest -show verbose ./...`
+- `go run github.com/securego/gosec/v2/cmd/gosec@latest ./...`
+- `npm test` in `frontend/`
+- `npm run build` in `frontend/`
+- `npm audit --json` in `frontend/`
+- `node --check` for changed JavaScript
+- `bash -n build.sh build-all.sh release.sh scripts/build-common.sh`
+- `php -l updates/index.php`
+- `git diff --check`
+
+## 4. Risk Rating Method
+
+Severity reflects attacker position, prerequisites, exploit repeatability,
+trust-boundary impact, and confidentiality, integrity, and availability
+consequences.
+
+- Critical: practical unauthenticated remote compromise or broad secret
+  disclosure.
+- High: practical code execution, credential theft, or privilege escalation.
+- Medium: meaningful local, renderer, connected-peer, or privacy impact with
+  realistic prerequisites.
+- Low: bounded local exposure, defence-in-depth weakness, or correctness issue
+  with a security consequence.
+- Informational: hardening or validation work without a confirmed exploit.
+
+Confidence reflects the strength of source evidence, reproduction, scanner
+evidence, and regression coverage. Severity is not increased merely because a
+scanner reports a possible pattern.
+
+## 5. Attack Surface Map
+
+Entry points:
+
+- Wails-bound service methods invoked by the desktop renderer.
+- Runtime events crossing between frontend JavaScript and Go.
+- The token-authenticated localhost bridge endpoints.
+- User-selected SSH, SFTP, VNC, IRC, Telnet, RAW TCP, GitHub, and update
+  endpoints.
+- Imported profiles, OpenSSH configuration, encrypted Nexus exports,
+  recordings, and files selected for Leviathan analysis.
+- Local shell commands and SSH key generation.
+
+Trust boundaries:
+
+- Renderer to privileged Go backend.
+- Local bridge client to localhost HTTP/RPC service.
+- OS keychain or encrypted vault to runtime session credentials.
+- Remote network data to protocol clients and frontend rendering.
+- User-selected or hostile files to parsers and external analysis tooling.
+- Release workflow and update manifest to installed application binaries.
+
+Attacker starting positions considered:
+
+- A malicious or compromised remote service.
+- A hostile local file or imported configuration.
+- A local unprivileged process targeting the localhost bridge or filesystem
+  artefacts.
+- A renderer injection or future renderer compromise invoking bound methods.
+- An observer of TLS traffic.
+- A legitimate local user accidentally creating unbounded resource state over
+  a long-running process.
+
+## 6. Findings Summary Table
+
+| ID | Severity | Confidence | Title | Component | Status |
+|---|---|---|---|---|---|
+| SEC-20260729-1237-001 | Medium | High | Reconnect credential prompts accumulated permanent runtime listeners | `internal/sessions` | Fixed in `b5c7528` |
+| SEC-20260729-1237-002 | Medium | High | Interrupted SFTP uploads retained resources without a concurrency bound | `internal/api` | Fixed in `b5c7528` |
+| SEC-20260729-1237-003 | Medium | High | Build accepted a Go toolchain with a reachable TLS privacy vulnerability | `go.mod`, build scripts | Fixed in `b5c7528` |
+| SEC-20260729-1237-004 | Low | High | Sensitive local artefacts did not consistently enforce private permissions | Export/import and Leviathan | Fixed in `b5c7528` |
+
+## 7. Detailed Findings
+
+### Finding ID: SEC-20260729-1237-001
+
+#### Title
+
+Reconnect credential prompts accumulated permanent runtime listeners
+
+#### Severity
+
+Medium
+
+#### Confidence
+
+High
+
+#### Affected Files / Components
+
+- `internal/sessions/manager.go:110`
+- `internal/sessions/manager.go:676`
+- `internal/sessions/manager.go:2577`
+- `internal/sessions/manager.go:2615`
+- `internal/sessions/manager.go:2654`
+- `internal/sessions/manager_test.go:383`
+- `cmd/vscode-bridge/main.go:187`
+- `internal/app/app.go:118`
+
+#### Description
+
+Every credential request created during automatic reconnect registered another
+`session:secret:response` Wails listener. The listener was never unregistered,
+including after a response, timeout, cancelled reconnect, session close, or
+application shutdown.
+
+The request ID check prevented one prompt from accepting another prompt's
+value, but all historical callbacks were still invoked for every future
+credential response. A process left open for a long time could therefore
+accumulate event callbacks in proportion to its reconnect history. A closed
+session could also leave a credential prompt waiting for its full timeout.
+
+#### Evidence
+
+Before the fix, `buildInteractiveSecretCallback` called
+`wailsRuntime.EventsOn` inside the callback created for each prompt and
+discarded the returned unsubscribe function.
+
+The fix registers one manager-level response router from `SetContext`, stores
+the unsubscribe function, routes responses through a request-ID map, honours
+frontend cancellation, and selects on the reconnect context. `Shutdown`
+unregisters both host-key and credential listeners and releases all waiters.
+Application and bridge shutdown now call the complete service and manager
+shutdown methods.
+
+#### Attack Scenario
+
+A remote SSH or IRC service repeatedly drops connections after authentication,
+or a user repeatedly opens and reconnects profiles that require an interactive
+secret. Historical event listeners accumulate. Later secret responses fan out
+to all callbacks, increasing CPU work and retained memory even though old tabs
+are closed.
+
+#### Impact
+
+Progressive memory and CPU consumption in a long-running process, sluggish
+credential prompts, delayed shutdown, and eventual application availability
+loss. The request-ID routing means no cross-session secret disclosure was
+confirmed.
+
+#### Recommendation
+
+Use one application-lifetime event listener per event type, route responses by
+opaque request ID, bind every waiter to a cancellation context, and explicitly
+unsubscribe and release waiters during shutdown.
+
+#### Safer Example
+
+Implemented in outline:
+
+```go
+cancel := wailsRuntime.EventsOn(ctx, "session:secret:response", m.handleSecretResponse)
+m.secretListenerCancel = cancel
+
+select {
+case response := <-ch:
+    return response.value, cancellationError(response)
+case <-ctx.Done():
+    return "", ctx.Err()
+}
+```
+
+#### Suggested Tests
+
+Added tests verify request-ID routing, reconnect-context cancellation, frontend
+cancellation, pending-map cleanup, and shutdown waiter release. The focused
+race suite passes.
+
+#### References
+
+- CWE-400: Uncontrolled Resource Consumption
+- CWE-772: Missing Release of Resource after Effective Lifetime
+
+#### Assumptions / Limitations
+
+No packaged Wails runtime stress test was run. The defect and fix are directly
+visible in source, and the routing/cancellation logic is covered at Go level.
+
+### Finding ID: SEC-20260729-1237-002
+
+#### Title
+
+Interrupted SFTP uploads retained resources without a concurrency bound
+
+#### Severity
+
+Medium
+
+#### Confidence
+
+High
+
+#### Affected Files / Components
+
+- `internal/api/api.go:52`
+- `internal/api/api.go:117`
+- `internal/api/api.go:469`
+- `internal/api/api.go:475`
+- `internal/api/api.go:515`
+- `internal/api/api.go:1569`
+- `internal/api/api.go:2189`
+- `internal/api/api.go:2202`
+- `internal/api/api_test.go:145`
+
+#### Description
+
+Streaming SFTP upload state held an open remote writer in the service upload
+map. Finish and explicit cancel removed it, but disconnecting, reconnecting, or
+closing the owning session did not. Application shutdown also did not drain
+unfinished uploads. There was no limit on the number of simultaneously open
+streaming uploads.
+
+#### Evidence
+
+The earlier lifecycle paths called the session manager directly without
+visiting the upload map. `SFTPUploadStart` inserted every new writer without a
+capacity check.
+
+The fix:
+
+- Caps active streaming uploads at 16.
+- Checks capacity before opening a remote writer and atomically rechecks before
+  insertion.
+- Removes and closes uploads belonging to a session before disconnect or
+  reconnect.
+- Drains every upload during close-all and service shutdown.
+- Best-effort removes the partial remote file.
+- Releases secret-prompt waiters and the service's Wails listener during
+  shutdown as part of the same lifecycle hardening.
+
+#### Attack Scenario
+
+A compromised renderer, automation loop, or repeated user action starts
+uploads and closes the associated tabs or sessions without finishing them.
+Each iteration can retain a local map entry, SFTP request state, remote file
+handle, and partially written file. Repetition eventually exhausts descriptors,
+memory, or server-side resources.
+
+#### Impact
+
+Local and remote resource exhaustion, failed subsequent uploads, leaked partial
+files, and degraded session availability.
+
+#### Recommendation
+
+Make resource ownership explicit: uploads must be owned by a session and
+cancelled when that session ends. Bound concurrent work and keep a race-safe
+second capacity check after expensive setup.
+
+#### Safer Example
+
+Implemented:
+
+```go
+func (s *Service) DisconnectSession(sessionID string) error {
+    s.cancelSFTPUploads(sessionID)
+    return s.sessions.Disconnect(sessionID)
+}
+```
+
+#### Suggested Tests
+
+Added tests verify session-scoped cancellation, unrelated-upload preservation,
+the active-upload limit, writer closure, and shutdown cleanup. Full and race
+tests pass.
+
+#### References
+
+- CWE-400: Uncontrolled Resource Consumption
+- CWE-404: Improper Resource Shutdown or Release
+- CWE-772: Missing Release of Resource after Effective Lifetime
+
+#### Assumptions / Limitations
+
+No real SFTP server was used to verify partial-file deletion after a transport
+failure. Removal is best-effort because the session may already be unavailable;
+local writer and map cleanup do not depend on remote deletion succeeding.
+
+### Finding ID: SEC-20260729-1237-003
+
+#### Title
+
+Build accepted a Go toolchain with a reachable TLS privacy vulnerability
+
+#### Severity
+
+Medium
+
+#### Confidence
+
+High
+
+#### Affected Files / Components
+
+- `go.mod:3`
+- `go.mod:5`
+- `build.sh:21`
+- `build-all.sh:20`
+
+#### Description
+
+The build accepted Go 1.25.0 and the local build used Go 1.26.4.
+`govulncheck` identified GO-2026-5856 / CVE-2026-42505 in a reachable
+`crypto/tls` path. Affected clients could expose TLS PSK identities in a
+plaintext ClientHello while Encrypted Client Hello was in use, allowing a
+passive observer to undermine ECH privacy.
+
+#### Evidence
+
+The pre-fix scan reported the standard-library vulnerability as reachable.
+The [official Go vulnerability record](https://pkg.go.dev/vuln/GO-2026-5856)
+states that Go 1.25 is fixed in 1.25.12 and Go 1.26 is fixed in 1.26.5.
+
+The fix raises the module minimum to Go 1.25.12, requests toolchain Go 1.26.5,
+and aligns both Unix build scripts with the new minimum. The post-fix verbose
+scan used the Go 1.26.5 standard library and reported zero symbol or package
+vulnerabilities affecting Nexus.
+
+#### Attack Scenario
+
+Where ECH and PSK resumption are used, a passive network observer records the
+client's plaintext ClientHello and correlates an exposed PSK identity with the
+protected destination.
+
+#### Impact
+
+Conditional network privacy disclosure. No private key or application
+credential extraction was demonstrated. Nexus does not explicitly configure
+ECH, so actual exposure depends on TLS configuration and runtime behaviour.
+
+#### Recommendation
+
+Enforce fixed toolchain floors in `go.mod`, local build scripts, and CI. Keep
+`govulncheck` in release validation so standard-library vulnerabilities cannot
+be missed by module-only scanners.
+
+#### Safer Example
+
+Implemented:
+
+```text
+go 1.25.12
+toolchain go1.26.5
+```
+
+#### Suggested Tests
+
+Run `go version` and verbose `govulncheck` in release CI, and fail if a
+reachable symbol-level vulnerability is reported.
+
+#### References
+
+- GO-2026-5856
+- CVE-2026-42505
+- CWE-200: Exposure of Sensitive Information
+
+#### Assumptions / Limitations
+
+The scanner established a reachable TLS symbol path, not that Nexus actively
+negotiated ECH with a vulnerable server during this audit. Severity therefore
+reflects conditional exploitability.
+
+### Finding ID: SEC-20260729-1237-004
+
+#### Title
+
+Sensitive local artefacts did not consistently enforce private permissions
+
+#### Severity
+
+Low
+
+#### Confidence
+
+High
+
+#### Affected Files / Components
+
+- `internal/exportimport/exportimport.go:68`
+- `internal/exportimport/exportimport.go:111`
+- `internal/exportimport/exportimport.go:116`
+- `internal/exportimport/exportimport.go:170`
+- `internal/exportimport/exportimport_test.go:108`
+- `internal/leviathan/binsnoop/binsnoop.go:137`
+- `internal/leviathan/binsnoop/binsnoop.go:141`
+- `internal/leviathan/binsnoop/extract.go:17`
+- `internal/leviathan/binsnoop/extract.go:20`
+- `internal/leviathan/binsnoop/common_test.go:25`
+
+#### Description
+
+Encrypted profile exports were created through `os.Create`, which normally
+uses mode `0666` filtered by the process umask. Overwriting an existing file
+also preserved its existing mode. Leviathan carved binary data and extraction
+directories used `0644` and `0755`. Carved content can include credentials,
+private keys, firmware configuration, or other forensic secrets.
+
+Export encryption keys, password byte slices, and decrypted plaintext byte
+slices also remained live until garbage collection after use.
+
+#### Evidence
+
+The fix opens exports with mode `0600` and explicitly applies `Chmod(0600)` so
+an existing permissive destination is tightened. Leviathan-owned carve files
+now use `0600`, and directories use `0700`. Export/import makes a best-effort
+`clear` of transient password, derived-key, and plaintext byte slices.
+
+#### Attack Scenario
+
+On a multi-user host, another local account reads a carved private key or
+configuration from a world-readable output file. For an export destination
+that already had permissive permissions, another account can copy the
+encrypted profile bundle for offline password guessing.
+
+#### Impact
+
+Local confidentiality exposure. The export remains protected by Argon2id and
+AES-GCM, which significantly reduces its immediate sensitivity; raw carve
+output has no equivalent encryption.
+
+#### Recommendation
+
+Create sensitive artefacts and parent directories with private modes, tighten
+existing destinations explicitly, and minimise the lifetime of mutable
+plaintext and key buffers. Document that Go strings and internal copies cannot
+be guaranteed to be erased.
+
+#### Safer Example
+
+Implemented:
+
+```go
+f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0600)
+if err == nil {
+    err = f.Chmod(0600)
+}
+```
+
+#### Suggested Tests
+
+POSIX-only regression tests verify `0600` export and carve files and a `0700`
+carve directory, including overwriting a pre-existing `0644` export.
+
+#### References
+
+- CWE-276: Incorrect Default Permissions
+- CWE-316: Cleartext Storage of Sensitive Information in Memory
+
+#### Assumptions / Limitations
+
+POSIX mode bits are not equivalent on Windows, so permission tests skip there.
+`clear` is best-effort in Go and cannot erase immutable password strings,
+copies held by libraries, or compiler-created copies. External extraction
+tools may choose their own modes for files they create beneath the private
+directory.
+
+## 8. Blackhat-Style Abuse Paths
+
+### Path 1: Reconnect churn to process exhaustion
+
+Prerequisite: a profile needs an interactive credential during automatic
+reconnect. A hostile endpoint repeatedly drops the connection. Before the fix,
+each prompt left another Wails listener behind. Defensive breakpoint:
+application-level listener routing, context cancellation, and shutdown
+unsubscribe.
+
+### Path 2: Renderer-driven SFTP handle exhaustion
+
+Prerequisite: renderer access to bound service methods. Start streaming uploads
+without finishing them, then close or reconnect sessions repeatedly. Before the
+fix, writers and upload entries survived. Defensive breakpoint: the 16-upload
+cap and session-owned cancellation.
+
+### Path 3: Passive observation of vulnerable TLS ECH
+
+Prerequisite: affected Go runtime, ECH/PSK behaviour, and network visibility.
+Observe plaintext ClientHello state and correlate exposed PSK identity.
+Defensive breakpoint: Go 1.25.12 or 1.26.5 and later.
+
+### Path 4: Local recovery of carved secrets
+
+Prerequisite: another local account can traverse the selected output location.
+Read a `0644` carved file containing a private key or configuration secret.
+Defensive breakpoint: `0700` directories and `0600` files.
+
+No practical chain to unauthenticated remote code execution was identified.
+
+## 9. Denial-of-Service Review
+
+Fixed in this audit:
+
+- Reconnect secret listeners no longer grow with historical prompt count.
+- Cancelled reconnect prompts stop immediately instead of waiting up to 60
+  seconds.
+- Session close/reconnect and application shutdown drain streaming uploads.
+- Concurrent streaming uploads are capped at 16.
+- Runtime listeners and prompt waiters are released at shutdown.
+- IPv6 literals are joined with ports correctly, preventing connection failure
+  and misleading repeated retry behaviour.
+
+Previously hardened and rechecked:
+
+- SFTP inline/chunk/total upload size caps.
+- VNC WebSocket frame limits.
+- GitHub archive and update-response size limits.
+- SSH configuration and public-key input caps.
+- Recording and Leviathan file-size limits in exposed paths.
+- Session timers, latency pings, frontend intervals, and closed-tab lifecycle
+  cleanup covered by the current regression tests.
+
+Residual considerations:
+
+- Network protocols ultimately depend on remote peer responsiveness.
+- External Leviathan tools lack a shared timeout/output-budget wrapper, but
+  that path is not currently exposed by the active UI API.
+- Hostile binary parsers deserve continued fuzzing even where current bounds
+  checks reject malformed offsets.
+
+## 10. Dependency and Supply-Chain Review
+
+`npm audit --json` reported zero vulnerabilities across 33 frontend
+dependencies.
+
+Post-fix `govulncheck -show verbose` reported:
+
+- Zero vulnerabilities in symbols Nexus calls.
+- Zero vulnerabilities in imported package call paths.
+- Four advisories in required module versions that Nexus does not appear to
+  call:
+  - GO-2026-5970 in `golang.org/x/text@v0.37.0`.
+  - GO-2026-5942 in `golang.org/x/net@v0.55.0`.
+  - GO-2026-5932 for the unmaintained `x/crypto/openpgp` package.
+  - GO-2026-5841 in `github.com/klauspost/compress/s2@v1.17.11`.
+
+Those versions should be refreshed through normal dependency maintenance, but
+they were not forcibly upgraded in this fix because the scanner found no
+Nexus call path and broad transitive churn would require separate compatibility
+testing.
+
+The release workflow uses common GitHub Actions by major version and a
+write-capable release job. Pinning actions to immutable commit SHAs would
+further reduce supply-chain drift. Release permissions should remain scoped to
+the release job and tag/manual triggers.
+
+## 11. Secrets and Sensitive Data Review
+
+No hard-coded production credential, private key, token, or certificate was
+found. Test secrets were confined to test fixtures.
+
+Reviewed controls:
+
+- OS keychain integration.
+- Argon2id-derived AES-GCM vault and export encryption.
+- SSH host-key verification and known-host handling.
+- Bridge bearer token generation and comparison.
+- Secret prompt routing and cancellation.
+- Sensitive file permissions.
+- Logging and frontend error paths for obvious secret disclosure.
+
+Fixed:
+
+- Best-effort clearing of mutable export/import plaintext, password bytes, and
+  derived keys.
+- Private export and carve modes.
+- Prompt waiters and listeners released during shutdown.
+
+Residual:
+
+- Go strings and library copies cannot be reliably zeroed.
+- Users may explicitly choose plaintext Telnet, RAW TCP, or non-TLS VNC.
+- A user can explicitly select insecure SSH host-key behaviour; that choice
+  remains a visible compatibility option and should not be the default.
+
+## 12. Authentication and Authorisation Review
+
+Nexus is a single-user desktop client rather than a multi-tenant server. Its
+primary authorisation boundary is the logged-in OS account plus the Wails
+renderer/backend boundary.
+
+Checked:
+
+- Local bridge endpoints retain bearer-token authentication.
+- SSH host-key callbacks are required in the reviewed direct and tunnel paths.
+- GitHub and remote-session credentials are retrieved from configured secret
+  stores or interactive prompts.
+- Sensitive service methods validate session identifiers through the manager
+  and validate paths, sizes, or option allow-lists where applicable.
+
+No new authentication bypass or cross-user authorisation defect was confirmed.
+A future renderer compromise would still have substantial privileges because
+Wails-bound methods are designed for the trusted desktop UI; maintaining output
+encoding and a narrow method surface therefore remains important.
+
+## 13. Input Validation and Output Encoding Review
+
+Reviewed:
+
+- Profile fields, ports, hostnames, paths, filenames, import strategies,
+  archive/update URLs, SSH key options, recording files, binary offsets, and
+  base64 upload chunks.
+- HTML construction and text insertion in frontend modules.
+- Local subprocess arguments for shell, `ssh-keygen`, and Leviathan extraction.
+
+Fixed:
+
+- `net.JoinHostPort` now constructs IPv4, hostname, and IPv6 endpoints in VNC,
+  IRC SSH tunnels, and the connection tester.
+- Existing SFTP validation is now combined with a concurrency limit and
+  lifecycle cleanup.
+
+Scanner findings for MD5/SHA-1 in Leviathan are intentional forensic hash
+identifiers, not password or signature protection. Representative integer
+conversion and slice warnings in hostile-file parsers were manually traced to
+existing bounds checks; no concrete out-of-bounds path was confirmed. Parser
+fuzzing remains preferable to broad speculative casting changes.
+
+## 14. Frontend HTML/JavaScript Robustness Review
+
+The frontend contains numerous event listeners because each tab and modal owns
+interactive DOM. Reviewed tab/session paths attach handlers to ephemeral nodes
+that become collectable when their owning DOM is removed, while application
+listeners and intervals have explicit one-time or cleanup behaviour.
+
+Current regression coverage verifies session cleanup, active latency timer
+behaviour, closed-tab release, safe DOM patterns, upload constraints, build
+hardening, and other earlier fixes.
+
+The aggregate test harness still referenced VS Code files deleted in
+`4fc3b19` and a CGO flag removed by the same pure-Go migration. This caused
+`npm test` to fail before reaching its current assertions. The stale VS Code
+checks were removed, and the obsolete `-O2 -g0` assertion was replaced with a
+check that the current build retains `CGO_ENABLED=0`. Both frontend suites now
+pass.
+
+No confirmed exploitable current DOM injection was found. Some `innerHTML`
+usage remains and relies on escaping helpers or trusted static markup; future
+changes should prefer `textContent` and DOM construction for dynamic data.
+
+## 15. Infrastructure and Deployment Review
+
+Reviewed:
+
+- Shell, PowerShell, Makefile, and shared build helpers.
+- GitHub Actions release configuration.
+- Updater endpoint and PHP manifest delivery.
+- Cross-platform build flags and Go toolchain selection.
+
+Fixed:
+
+- Unix build scripts now reject Go versions older than 1.25.12.
+- `go.mod` requests Go 1.26.5 while keeping 1.25.12 as the minimum supported
+  language/toolchain floor.
+- Stale regression coverage now reflects the pure-Go build.
+
+The updater remains a high-value trust boundary. Production release validation
+should verify HTTPS, hashes/signatures where supported, expected artefact
+names, and least-privilege release credentials. No new command-injection or
+manifest-escaping defect was confirmed.
+
+## 16. Logging, Monitoring, and Error Handling Review
+
+The new cleanup paths do not log credentials or secret responses. Upload
+cleanup treats remote partial-file deletion as best-effort because the
+underlying session may already be broken.
+
+Useful future operational signals:
+
+- Active and rejected streaming-upload counts.
+- Reconnect attempt count and pending credential prompts.
+- Active runtime listener and session counts in a diagnostics view.
+- Resource snapshots during long-running open/close soak tests.
+
+These should expose counts and identifiers only, never passwords, tokens,
+private keys, terminal contents, or bridge bearer tokens.
+
+## 17. Test Coverage and Security Regression Gaps
+
+Added:
+
+- Credential response routing by request ID.
+- Reconnect cancellation releases its secret prompt immediately.
+- Frontend cancellation is honoured.
+- SFTP cleanup is scoped to the owning session.
+- Active streaming uploads are bounded.
+- Service shutdown releases uploads and prompt waiters.
+- Existing permissive export files are tightened to `0600`.
+- Leviathan carve directories/files use `0700`/`0600`.
+
+Passing:
+
+- Full Go test suite.
+- Focused Go race suite.
+- Go vet.
+- Complete frontend lifecycle and regression suite.
+- Frontend production build.
+- JavaScript, shell, and PHP syntax checks.
+- `npm audit`.
+- Reachable Go vulnerability scan.
+
+Remaining gaps:
+
+- No packaged Wails UI smoke or long-duration tab/reconnect soak test.
+- No real SFTP server test proves partial-file deletion after a broken
+  transport.
+- No live IPv6 protocol endpoint was used.
+- Hostile-file parser coverage is uneven; fuzzing should be expanded.
+- Windows ACL behaviour is not verified by POSIX permission tests.
+- External Leviathan extractors lack integration tests for time and output
+  limits.
+
+## 18. Prioritised Remediation Plan
+
+Immediate:
+
+- Soak-test a packaged app while repeatedly opening, reconnecting, and closing
+  local and remote tabs. Monitor process CPU, memory, goroutines, file
+  descriptors, and listener/upload counts.
+- Exercise interrupted SFTP uploads against a real server and verify local
+  handle cleanup plus remote partial-file behaviour.
+
+Short-term:
+
+- Add a packaged Wails lifecycle smoke test.
+- Add fuzz targets for the highest-complexity Leviathan parsers.
+- Refresh the four module versions with unreachable advisories and run protocol
+  compatibility tests.
+- Add metrics or a diagnostics screen for active sessions, reconnects,
+  uploads, prompts, and event subscriptions.
+
+Medium-term:
+
+- Wrap every external Leviathan extractor with context timeout, process-group
+  termination, and output-size/file-count budgets before exposing extraction
+  through the UI.
+- Replace remaining dynamic `innerHTML` paths with text nodes or narrowly
+  reviewed rendering helpers.
+- Add real IPv6 SSH/VNC/IRC tunnel integration coverage.
+
+Long-term:
+
+- Add release CI gates for full tests, race-focused tests, `govulncheck`,
+  frontend audit/build, packaged smoke checks, and signed artefact validation.
+- Pin third-party GitHub Actions to reviewed immutable revisions.
+
+## 19. False Positives / Needs Manual Verification
+
+- Gosec MD5 and SHA-1 reports in Leviathan are forensic digest features, not
+  security authentication or password hashing.
+- Gosec subprocess reports include user-selected local shells, allow-listed SSH
+  key generation options, and an external extraction path not exposed by the
+  current document API. The extraction path still needs limits before future
+  exposure.
+- File-parser integer-conversion and slice warnings were reviewed
+  representatively; existing range checks rejected the paths inspected.
+  Fuzzing is required for stronger assurance.
+- The four remaining Go module advisories are present in required versions,
+  but `govulncheck` found no called symbol or imported vulnerable package path.
+- The fixed TLS issue had a reachable standard-library path, but actual ECH
+  exposure was not reproduced.
+- Sensitive-buffer clearing is best-effort and must not be described as
+  guaranteed memory erasure in Go.
+
+## 20. Final Notes
+
+The confirmed issues and their regression tests are committed in `b5c7528`.
+The most important improvement for the reported long-running-process behaviour
+is that credential event listeners, prompt waiters, and unfinished upload
+writers now have explicit owners and terminal cleanup paths.
+
+Closing a session now cancels its reconnect work and SFTP uploads; closing all
+sessions drains all uploads; application or bridge shutdown also unregisters
+runtime listeners and releases pending prompts. This materially improves
+cleanup, but live soak testing is still required before claiming that every OS,
+third-party library, and remote-peer resource remains flat indefinitely.

audits/20261012-0723-functionalityNextSteps.md

@@ -0,0 +1,139 @@
+# Functionality and Next Steps Report
+
+**Project:** Nexus Terminal — Rust port (`rust/` workspace)
+**Branch / base commit:** `rust-port` @ `8766846` (after this run: `aac986d`)
+**Date:** 2026-10-12 07:23 (local)
+**Companion:** `audits/20261012-0723-securityAudit.md` (SEC-20261012-NNN references below)
+
+## 1. Executive Summary
+
+The port is functionally complete relative to the Go/Wails app and is in good shape: the core crate is cleanly separated from the UI, every protocol client follows one lifecycle contract (blocking connect, own reader thread, `on_close` exactly once), the test suite (142 tests) exercises real sockets, a real `sshd`, PTYs and fake IRC/VNC/GitHub servers, and `clippy -D warnings` is clean.
+
+The highest-impact improvements now are reliability and user-experience rather than new protocols:
+
+1. **Credential UX** — a mistyped “saved” password is persisted before it is verified and then blocks every reconnect with no re-prompt (SEC-015); store failures are silent.
+2. **Resilience** — a panic on any worker thread poisons shared mutexes and takes the whole app down (`lock().unwrap()` everywhere); there is no panic hook, no crash message and no recovery of open sessions.
+3. **Product/privacy switches** — update checks, remote clipboard writes and multi-line paste all happen without a preference or notice.
+4. **Operability** — recording metadata, audit-log growth and the IRC state model scale poorly with long-running use.
+5. **Developer experience** — fuzz targets, a CI audit step and a documented `cargo clean` note after moving the checkout would have saved time in this run.
+
+## 2. Current Functional Risks
+
+| # | Risk | Where | Effect on users |
+|---|---|---|---|
+| F1 | Saved credential stored before auth succeeds; no path to replace it on failure other than editing the profile | `core/src/sessions.rs` `secret_fn` | Typo → every connect fails silently with the wrong saved password |
+| F2 | `Secrets::set` swallows errors (`let _ =`) | `core/src/secrets.rs` | “Save securely” silently doesn't save when the keychain refuses and the vault is locked |
+| F3 | Mutex poisoning: ~60 `lock().unwrap()` sites; any panic in a callback thread (e.g. a decoder bug) crashes the UI on the next lock | `sessions.rs`, `app.rs`, clients | One bad session kills all sessions, recordings stop mid-write |
+| F4 | No panic hook / crash dialog; `eframe` aborts silently | `app/src/main.rs` | Users see the window vanish with no explanation |
+| F5 | Quick Connect (SSH) allows an empty username; connection then fails at auth with an opaque server error | `app/src/quick_connect.rs`, `service.rs` `connect_quick` (unvalidated) | Confusing failure |
+| F6 | `import_ssh_config` writes profiles without `validate_profile` (e.g. empty `User`) | `core/src/service.rs` | Profiles that fail validation when later edited |
+| F7 | Unknown enum value in a stored JSON column (`hostKeyPolicy`, `lineEnding`, …) makes `parse_col` return `None`; the profile silently reverts that protocol's config to defaults | `core/src/storage.rs` `parse_col` | Lost settings after a downgrade/edit with a newer app |
+| F8 | Empty vault accepts any master password; a typo on first use creates entries under the wrong key (SEC-016) | `core/src/secrets.rs` | Unrecoverable secrets |
+| F9 | Recording listing reads every `.cast` fully (up to 250 MiB each) on the UI's worker thread (SEC-020) | `core/src/recording.rs` `read_meta` | Recordings window stalls with large files |
+| F10 | macOS `capture_cwd` runs `/usr/sbin/lsof` on every Enter in a local shell | `core/src/clients/local.rs` | Noticeable latency on macOS local tabs |
+| F11 | Keychain probe writes and deletes an item at every launch | `core/src/secrets.rs` `Keychain::available` | Keychain prompts/noise on macOS; D-Bus wake-ups on Linux |
+| F12 | Keychain legacy read-through copies `AlchementaryLink` items forward on every miss | `Keychain::get` | Repeated writes for keys that only exist in the legacy service |
+| F13 | GitHub refresh performs up to 5000 commit lookups every refresh interval with 5 threads | `core/src/clients/github.rs` | Token rate-limit exhaustion; 403s surface as “auth failed” |
+| F14 | IRC: channels/users tracked for any JOIN/NAMES seen, UI targets created for any sender (SEC-014) | `irc.rs`, `irc_view.rs` | Memory growth on busy networks |
+| F15 | `check_github` in `updater.rs` is unused (dead code) and hardcodes an owner/repo that may not exist | `core/src/updater.rs` | Misleading; GitHub fallback never runs |
+| F16 | Update check at every launch, no preference, docs say opt-in (SEC-013) | `app/src/app.rs` | Privacy expectation mismatch |
+| F17 | Audit log has no cap/rotation | `storage.rs` `add_audit` | DB grows indefinitely |
+| F18 | Stale `target/` after moving the checkout bakes old `CARGO_MANIFEST_DIR` into fixture tests (4 failures until `cargo clean`) | build hygiene | Confusing CI-vs-local mismatch |
+| F19 | `Secrets::delete_profile` relies on a static list of kinds (`PROFILE_SECRET_KINDS`); the profile editor and session manager still use string literals for kinds | `secrets.rs`, `profile_editor.rs`, `sessions.rs` | A new kind added in one place is missed by the purge |
+| F20 | Reconnect credential prompt timeout is 60 s vs 300 s on first connect | `sessions.rs` `schedule_reconnect` | Reconnects fail if the user is away briefly |
+
+## 3. Code Quality Improvements
+
+- **Secret kinds as a type**: replace the `&'static str` kinds (`"password"`, `"github-token"`, `"vnc-ssh-passphrase"`, …) scattered across `sessions.rs`, `profile_editor.rs` and `secrets.rs` with an enum (`SecretKind`) that has `as_str()` and `ALL`. Why: F19 and SEC-001 depend on the list staying complete. Safe step: enum + `From<&str>`; keep the string form for storage keys.
+- **Poison-tolerant locking**: introduce a small `fn lock<T>(m: &Mutex<T>) -> MutexGuard<T>` that recovers from poisoning (`unwrap_or_else(|e| e.into_inner())`, as `irc.rs`/`vnc.rs` already do) and use it in `sessions.rs`, `ssh.rs`, `app.rs`. Why: F3. Mechanical refactor; existing tests cover behaviour.
+- **Panic hook**: install `std::panic::set_hook` in `main.rs` that logs the payload (no locals) and posts a toast via `post_error`; keep worker panics from killing the UI. Why: F4.
+- **`parse_col` should not swallow errors**: log the parse error and keep the raw JSON (or surface a toast once) instead of returning `None`. Why: F7. Add `#[serde(other)]` variants to the enums so unknown values map to a named `Unknown` instead of failing the whole struct.
+- **`sessions.rs` (1 300 lines)**: split per-protocol connect functions (`connect_ssh/irc/vnc/github`) and the reconnect state machine into modules; the file is the hardest to test in isolation. Behaviour-preserving move; `tests/sessions.rs` guards it.
+- **Thread-per-event**: `on_close` spawns a thread per close and each connect spawns one; fine for a desktop app but makes ordering hard to reason about. Consider one `std::sync::mpsc` worker for lifecycle events.
+- **Duplicated defaults**: `Profile::new`, `Profile::normalize`, `profile_editor::prep` and `SshConfig::defaults` each know the default port/keepalive/retry values. Centralise in `models.rs` constants (already partly done) and have `prep` call `normalize`.
+- **`run_command("pwd")`** is the only use of exec for state; SFTP `realpath(".")` already gives the home — consider dropping the shell call to avoid shells that print banners.
+- **`Keychain::available` probe**: cache the result in preferences with a timestamp; re-probe weekly or on explicit request. Why: F11.
+- **Dead code**: `updater::check_github`, `Protocol::Local` branches in validation (`unsupported protocol`). Remove or wire up.
+- **`Store::migrate`**: wrap each migration in a transaction and record `schema_version` explicitly in code rather than relying on the SQL files to insert it (verify each file does).
+
+## 4. Frontend Interaction and Error-Handling Improvements
+
+The UI is native egui; the equivalent of “event firing / async failures / console diagnostics” was reviewed:
+
+- **Async failures surface**: every worker reports through `Job`, `Inbox`, `post_error` or `Shared::spawn`; the pattern is consistent. Gap: `Secrets::set` (F2) and `let _ = self.store.update_profile(&p)` in `connect_profile` discard errors — toast them.
+- **Modal keyboard handling**: `prompts()` and `dialogs()` read `Key::Enter`/`Escape` globally; with two modals stacked (a credential prompt while the Delete dialog is open) one key can act on both. Route keys only to the top-most modal (check `app.prompts.is_empty()` before dialogs read Enter).
+- **Credential prompt**: show which credential kind and profile; add “Save this credential” checkbox when the profile is in ask-every-time mode; after an auth failure with a saved secret, offer “Re-enter”.
+- **Host-key prompt**: offer “Copy fingerprint” and show the port; on key change, show both fingerprints side by side with a “Remove old key” action (today the user must go to Settings → Known Hosts).
+- **Clipboard from remote** (SEC-010): toast with the first line whenever OSC 52 or VNC sets the clipboard; preference to disable.
+- **Multi-line paste** (SEC-017): confirmation preview when the terminal is not in bracketed-paste mode.
+- **Transfers**: SFTP upload stops at the first failure and drops the rest of the queue (by design) — show which files were skipped.
+- **Console diagnostics**: adopt `tracing` with `RUST_LOG` support for connection lifecycle (host, protocol, state, error) — never credentials, never terminal data; today only `eprintln!` for CLI misuse exists.
+- **Crash fallback** (F4): panic hook + “Nexus Terminal hit an internal error; sessions were kept open where possible” dialog.
+- **Screenshot automation flags** (`--answer`): read from `NEXUS_ANSWERS` env/file instead of argv (SEC-018) and print a warning when used without `--screenshot`.
+
+## 5. Testing Roadmap
+
+- **Unit**: `secret_fn` ordering (store after success), `Vault` verifier (once added), `parse_col` unknown-enum behaviour, IRC state caps, `read_meta` tail parsing, `export_json` redaction of login-script sends.
+- **Integration**: extend `tests/ssh_integration.rs` with password + keyboard-interactive auth (sshd with `PasswordAuthentication yes` and a PAM-less test user is awkward; alternatively a russh server fixture), host-key change detection against the known-hosts table, remote forward teardown, SFTP rename/mkdir/remove.
+- **Abuse-case / fuzz**: `cargo-fuzz` targets for `vnc::read_update` (+ decoders), `telnet::Inner::process`, `irc::parse_line` + `ircformat::format_event`, `recording::Store::get`, `sshconfig::parse`, `updater::parse_manifest`. Run in CI nightly with a corpus from the existing fake-server tests.
+- **UI interaction**: the `--screenshot --do --answer` automation already drives the app headlessly; turn it into a smoke test matrix in CI (connect to the in-test sshd, open SFTP, run a palette command, assert the PNG is non-empty and the process exits 0).
+- **Regression**: keep the Go-fixture compatibility tests; add a fixture written by *this* version so future format changes are caught both ways.
+- **Load**: the ignored `perf::feed_throughput` test (50 MiB through the VT parser) should run in release mode in CI with a threshold; add a VNC decode benchmark on a synthetic 4K frame.
+- **Smoke**: `cargo audit` and `cargo deny check licenses advisories` jobs; `cargo test --locked` already runs on three OSes.
+
+## 6. Recommended New Functionality
+
+- **Preferences**: check-for-updates on/off (SEC-013), allow remote clipboard writes (SEC-010), confirm multi-line paste (SEC-017), confirm before `insecure` host-key policy connects.
+- **Credential management**: a Settings → Credentials page listing stored kinds per profile with “forget” buttons; master-password change (re-encrypt vault); export/import of the vault.
+- **Known hosts**: import from `~/.ssh/known_hosts` and export to it; SSH certificate CA trust (`@cert-authority`) since russh already parses certificates.
+- **Update integrity**: signed manifest (minisign/Ed25519), verified before display; optional in-app download with sha256 + signature check.
+- **IRC**: SASL PLAIN/EXTERNAL (modern networks reject NickServ IDENTIFY over plaintext), IRCv3 message tags for timestamps, per-network ISUPPORT line length.
+- **Serial**: session logging to file, hex view like RAW, break duration setting.
+- **SFTP**: recursive directory upload/download, drag-out to the desktop, resume on reconnect.
+- **Session**: “Send to all tabs in group”, per-session environment overrides for local shells, custom shell arguments.
+- **Operability**: audit-log viewer with cap/rotation; recordings metadata cache; “Diagnostics” page (keychain status, data dir, versions of russh/rustls, last update check).
+
+## 7. Next-Level Opportunities
+
+- **Observability**: `tracing` + optional file log with redaction; connection timing metrics in the status bar; opt-in crash reports (local file only).
+- **Resilience architecture**: supervisor-style session threads that catch panics per session (`std::panic::catch_unwind` around client callbacks) so one protocol bug cannot end the app.
+- **Security architecture**: move all secret-bearing fields out of `Profile` into the secret store behind a migration (keeps `.nexus` compatibility by exporting them inline only when “include secrets” is chosen); `Zeroizing`/`SecretString` throughout; Linux `PR_SET_DUMPABLE` while the vault is unlocked.
+- **Distribution**: signed, notarised builds; Flatpak/AppImage with sandboxing (`--filesystem=home:ro` + explicit `~/.ssh`), winget/Homebrew casks; SLSA provenance from the release workflow.
+- **Performance**: VNC — upload only dirty rows to the texture (`TextureHandle::set_partial`), decode JPEG on the I/O thread (already) but avoid the full `local.clone()` on resize; terminal — batch paint runs per style (already) and cache galleys per row.
+- **Accessibility**: egui `accesskit` is enabled; audit focus order in modals and provide screen-reader labels for icon-only buttons (`widgets::icon_button` has hover text only).
+- **Developer experience**: `justfile`/`make` targets for `test`, `clippy`, `audit`, `screenshot-smoke`; a `CONTRIBUTING.md` note about `cargo clean` after moving the checkout (F18); fuzz corpus checked in.
+
+## 8. Prioritised Action Plan
+
+**Immediate (this week)** — low risk, high value
+- Add the three preferences (update check, remote clipboard, paste confirmation) with safe defaults. Risk: trivial.
+- Toast on `Secrets::set` failure; store saved credentials after auth success (F1/F2). Risk: touches the auth path; covered by sshd tests — add a keyboard-interactive case.
+- Poison-tolerant lock helper + panic hook (F3/F4). Risk: mechanical.
+- Add `cargo audit` to CI with SEC-012 ignored and dated (outside `rust/`, owner's call).
+
+**Short term (next release)**
+- IRC state caps and joined-only tracking (F14).
+- `parse_col` error visibility and `Unknown` enum variants (F7).
+- Vault verifier entry (F8); keychain probe caching (F11).
+- Known-hosts import/export; host-key change dialog improvements.
+- Recording metadata from file tail (F9).
+
+**Medium term**
+- Secret-kind enum and credential management page (F19).
+- Fuzz targets + nightly job; screenshot smoke matrix.
+- Signed update manifest; release signing.
+- SASL for IRC; SFTP recursive transfers.
+
+**Long term**
+- Move profile-embedded secrets into the store with migration; `SecretString` everywhere.
+- Per-session panic isolation; `tracing`-based diagnostics.
+- Sandboxed distribution and provenance.
+
+## 9. Caveats and Validation Needed
+
+- Keychain behaviour (purge on delete, probe cost, legacy copy-forward) was verified by reading `keyring` usage, not by running against macOS Keychain, Windows Credential Manager or a live Secret Service; test on each OS before release.
+- The in-process key generator (`ssh::generate_key_pair`) was tested for Ed25519 and ECDSA; RSA generation runs the `rsa` crate's keygen (slow in debug builds — verify the UI stays responsive and that OpenSSH accepts the files on all three platforms).
+- `--data-dir` now creates directories 0700; if any user relies on sharing a portable data directory between accounts this changes behaviour.
+- The VNC size cap (64 Mpx) is above any real display; confirm with multi-monitor spanning setups (e.g. 3×4K = 37 Mpx) before lowering it.
+- Preference defaults for update checks and remote clipboard are product decisions; both have compatibility implications (vim/tmux yank over SSH relies on OSC 52).
+- UI event flows were validated by code review and the existing automation flags, not by an interactive run in this environment.

audits/20261012-2201-functionalityNextSteps.md

@@ -0,0 +1,136 @@
+# Functionality and Next Steps Report
+
+Nexus Terminal 3.0.1, reviewed alongside `20261012-2201-securityAudit.md`.
+
+## 1. Executive Summary
+
+The product is broad and mostly solid: nine protocols, sync, restore, shell integration, inline images, RDP devices and a 71-page guide. The highest-impact improvements now:
+
+- **Make the UI thread untouchable.** Several remote- or device-driven paths still do blocking or unbounded work on the UI thread:
+  - serial writes;
+  - inline image decode;
+  - find-bar recomputation;
+  - recording seek;
+  - the unbounded event queue.
+  Moving them to workers, or adding budgets, removes a whole class of "one bad peer freezes everything" reports.
+- **Finish the trust story for sync.** Timestamps are clipped and retargeted credentials are forgotten. What's still missing:
+  - a visible "what changed" summary;
+  - approval for security-relevant fields;
+  - eventually per-machine signatures.
+- **Credentials out of profile data.** Login-script passwords are the last secrets stored as profile data.
+- **Signed updates and releases**, as already planned by the owner.
+- **One fixed functional break:** link opening never worked, because eframe's `links` feature was missing. It is fixed now, but it shows the UI has no automated coverage for "does the click do something".
+
+## 2. Current Functional Risks
+
+| Risk | Where | Effect |
+|---|---|---|
+| Find bar recomputes matches over the whole scrollback (≤100k lines) on every output chunk while open | `app/src/terminal.rs` find (≈1035-1075) | A chatty session plus an open find bar pins the UI thread |
+| Recording seek re-feeds from byte 0 on every slider frame | `app/src/recordings.rs` `seek` | Dragging the slider on a big recording wedges the UI |
+| `.cast` ids: `trim_end_matches(".cast")` strips repeatedly and `trim()` changes names | `core/src/recording.rs` | `a.cast.cast` plays or deletes `a.cast`; names with leading spaces break |
+| A failed recording load closes the browser before the error toast | `app/src/recordings.rs` | The user loses their place |
+| `Dialog` is a single `Option`; terminal responses and menus overwrite an open dialog | `tabs.rs`, `app.rs` | A pending Delete confirmation can silently disappear |
+| A remote forward with `bind_port == 0` can't be stopped (cancel uses port 0) | `core/src/clients/ssh.rs` `shutdown_forward` | Forward stays listed and active on the server |
+| `sftp()` session cached forever; a dead subsystem breaks SFTP until reconnect | `core/src/clients/ssh.rs` | "SFTP stopped working" reports |
+| SFTP `list()` treats symlinks to directories as files | `core/src/clients/sftp.rs` | Can't navigate into linked directories |
+| No SFTP transfer cancellation | `core/src/clients/sftp.rs` | Large accidental downloads can't be stopped |
+| ssh-config import keeps only the first `ProxyJump` hop; `Host !foo` becomes a profile; `=` split on the first `=` anywhere | `core/src/sshconfig.rs` | Imported profiles connect differently from `ssh` |
+| Jump-host `auth_method`/`secret_mode` ignored (key/agent only) | `core/src/clients/ssh.rs` `via_jumps` | Password-only bastions can't be used |
+| IPv6 literals break KDC and gateway host:port parsing | `rdp.rs`, `ironrdp-mstsgu` | `[::1]:443` doesn't work |
+| RD Gateway consent message aborts the connection | vendored `ironrdp-mstsgu` | Enterprise gateways with a banner fail |
+| Kerberos hostname comes from `$HOSTNAME`, which is rarely exported | `rdp.rs` | Computer name is almost always "nexus" |
+| `is_newer` ignores pre-release suffixes | `core/src/updater.rs` | An `-rc` build isn't offered the final release |
+| Swallowed errors: tombstone write failure, vault delete failure, `triggers.json` read failure | `service.rs`, `secrets.rs`, `triggers.rs` | Silent data inconsistency |
+| `has_sync_password` was a keychain round trip per frame (now cached for 5 s) | `service.rs` | Fixed; included here because macOS keychain prompts were possible |
+
+## 3. Code Quality Improvements
+
+- **One GCM helper.** `secrets::seal/open` and `exportimport::seal/open` duplicate the AES-GCM wrapping with different layouts. Merge them into one helper that takes AAD; that also closes SEC-049 at the next format bump.
+- **Writer threads for every byte-stream client.** VNC already has a bounded queue. Telnet/RAW now have a write timeout, but writes still run on the caller's thread, and Serial and local PTY writes block under locks. One pattern for all of them removes a recurring bug class.
+- **Dead code:** `Store::import_profiles` (no callers), `TermResponse.title` / `TermEvent::Title` plumbing (never read), the stray doc comment in `updater.rs`, the stale `.gitignore` whitelist for `rust/core/tests/fixtures/**`, and "Alchementary Link" strings left in `migrations/001_initial.sql` and `updates/index.php`.
+- **`parse_col`** drops an unreadable config column, and the next save overwrites it with defaults. Keep the raw JSON and merge, so a config written by a newer build survives an older one.
+- **Dependency hygiene:** move nexus-core to `rand 0.9`, `argon2 0.6`, `aes-gcm 0.11` and `sha2 0.11` to match the rest of the graph, collapsing duplicate crypto crates.
+- **Vendored crates:** commit `.patch` files plus upstream tarball sha256, and add a CI check that the patches still apply cleanly to the pinned upstream versions.
+
+## 4. Frontend Interaction and Error-Handling Improvements
+
+(The UI is native egui. These are its equivalents of the frontend event and error items.)
+
+- **Keep heavy work off the UI thread:**
+  - decode inline images on a worker;
+  - debounce find to ≤10 Hz, or restrict it to visible rows plus N;
+  - seek recordings on `drag_stopped`;
+  - write serial data on a writer thread.
+- **Bound the event queue:** a per-session byte budget, coalescing consecutive `Data` events.
+- **Dialogs:** make `Dialog` a small stack, or refuse to replace a confirmation dialog, so destructive confirmations can't vanish.
+- **A sync change summary:** after a pull, list the changed profiles and fields (host, user, key policy, scripts, forwards, shared folder), with approve/revert for the security-relevant ones.
+- **Explain withheld credentials:** IRC now does this for plaintext servers. Do the same for any future "held back for safety" behaviour, ideally with a one-click fix (enable TLS).
+- **Clipboard settings:** consider defaulting "Allow remote clipboard writes" to off, or prompting on multi-line writes. The toast is now honest about line counts.
+- **Debug logs:** before a user shares `RUST_LOG=debug` logs, the Diagnostics page should warn that debug output from the RDP libraries can contain authentication blobs and shared-folder data.
+
+## 5. Testing Roadmap
+
+- **Unit:**
+  - RDPDR read clamp;
+  - oversized RDP desktop;
+  - `.cast` id mapping;
+  - remote forward with port 0 stop;
+  - `parse_col` with an unknown future field;
+  - import strategies (skip/overwrite/duplicate, duplicate ids in one batch, size caps).
+- **Integration:**
+  - two-sshd jump chain proving a jump host can't open agent or forwarded-tcpip channels (SEC-008);
+  - a stalled SSH server proving every phase hits its timeout;
+  - a fake Telnet peer that floods and never reads, proving `close()` returns quickly.
+- **Migration fixtures:** real schema-1 and schema-7 databases opened by the current build, including one with Go-era `proxyPassword` keys.
+- **Fuzzing:**
+  - new targets for `.cast` parsing, `known_hosts::parse`, `exportimport::open` and the JSON profile importer;
+  - seed the VNC corpus with valid ZRLE/Tight zlib streams;
+  - keep `-timeout` (now 10 s) so slow-input bugs surface.
+- **UI smoke:**
+  - a headless run per protocol using the existing screenshot automation (`--connect`, `--do`, `--screenshot`) as a CI job, asserting no panic and a non-blank frame;
+  - "does this click do something" checks (link open, Copy, Paste) would have caught the missing `links` feature.
+- **Load:** stream 512 MiB through a RAW session with the UI paused and assert bounded RSS (SEC-044).
+
+## 6. Recommended New Functionality
+
+- **Secret placeholders in login scripts** (`{{password}}`, `{{totp}}`) resolved from the keychain or vault at run time. This removes plaintext secrets from profiles (SEC-020) and improves the feature.
+- **Sync change review and per-machine trust:** pair machines once by exchanging ed25519 public keys and sign sync records. Then the sync password is no longer the only key.
+- **Signed update checks:** a minisign signature over the manifest, with the public key embedded, and verification in the updater. Pairs with the signing work already planned.
+- **RDP NLA memory:** remember that a host did NLA and refuse a TLS-only downgrade later (SEC-019). Show "no NLA" visibly in the toolbar when it is in use.
+- **VNC "unauthenticated session" indicator**, shown when the server picks security type None.
+- **IRC TLS certificate pinning** for private-CA networks, so users aren't nudged to turn TLS off.
+- **SFTP:** transfer cancellation and following symlinked directories.
+- **Jump hosts with passwords:** honour the existing `auth_method` and `secret_mode` fields.
+
+## 7. Next-Level Opportunities
+
+- **Observability:** a "Copy debug bundle" action that redacts known-sensitive upstream log targets automatically, instead of relying on the user's `RUST_LOG` choice.
+- **Architecture:** a single I/O runtime per session (tokio already runs SSH) for Telnet, RAW, Serial and VNC. That gives consistent cancellation, timeouts and back-pressure, and removes several thread-per-connection blocking patterns.
+- **Release engineering:** build provenance attestations, signed tags, and reproducible-build notes. Releases are already split into build (read-only) and publish (write) jobs.
+- **Accessibility:** egui AccessKit is enabled. Audit screen-reader labels on the desktop viewers and terminal (password fields are already masked for AccessKit).
+- **Performance:** the OSC 8 underline painter issues up to cols/3 `hline` calls per cell per frame, and the RAW hex row cache is bounded by count, not bytes. Both are cheap wins.
+
+## 8. Prioritised Action Plan
+
+| When | Action | Why | Risk |
+|---|---|---|---|
+| Immediate | Fix the GitHub Actions billing block so CI and the v3.0.1 release builds run | No CI signal and no release artefacts right now | None |
+| Short term | Event budget, find debounce, recording seek on drag-stop, serial writer thread | Remove the remaining UI-freeze vectors | Low; contained changes |
+| Short term | Sync change summary plus approval for security-relevant fields | Closes SEC-021 | Medium; UX design needed |
+| Short term | RDP NLA memory (SEC-019) | Downgrade protection | Low; needs a small known-hosts field |
+| Medium | Login-script secret placeholders | Removes the last plaintext secrets | Medium; changes the script editor and migration |
+| Medium | Merge the GCM helpers with AAD, bump crypto crates, vendored patch checks | Hygiene and integrity | Low |
+| Medium | Fuzz targets and migration fixtures listed in §5 | Regression safety | None |
+| Long term | Signed manifests, binaries and tags; per-machine sync signatures | Supply-chain and sync trust | Medium; key management |
+
+## 9. Caveats and Validation Needed
+
+- **Not exercised against real systems:**
+  - Windows RDP with NLA and Display Control;
+  - RD Gateway;
+  - Kerberos;
+  - macOS/Windows keychains (after the `Zeroizing` API change);
+  - real plaintext IRC networks (behaviour changed: passwords are now held back there).
+- **Release ordering:** the release workflow now publishes only after every platform builds, so one failing platform blocks the release. Confirm that is the preferred trade-off over partial releases.
+- **Sync re-prompts:** forgetting credentials on retargeted sync/import means a host edit on one machine makes the others re-prompt once. That is intended, but users should be told (it's in the manual now).
+- **Profile ids:** ids are now limited to `[A-Za-z0-9._-]{1,64}`. Every id this app generates is a UUID, but hand-made JSON imports with unusual ids will be refused rather than rewritten. Rewriting them on import is a possible follow-up.

build-all.sh

@@ -1,302 +0,0 @@
-#!/usr/bin/env bash
-# build-all.sh — Cross-build helper for Nexus Terminal (macOS/Linux hosts)
-# Builds all supported targets where the required toolchains are installed.
-# Usage: ./build-all.sh
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-cd "$SCRIPT_DIR"
-source "$SCRIPT_DIR/scripts/build-common.sh"
-
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-RED='\033[0;31m'
-NC='\033[0m'
-
-log()  { echo -e "${GREEN}[nexus]${NC} $1"; }
-warn() { echo -e "${YELLOW}[nexus]${NC} $1"; }
-err()  { echo -e "${RED}[nexus]${NC} $1" >&2; }
-
-MIN_GO_VERSION="1.25.0"
-WAILS_VERSION="$(awk '$1 == "github.com/wailsapp/wails/v2" { print $2; exit }' go.mod)"
-WAILS_BIN=""
-WAILS_USE_GO_RUN=0
-BUILT_TARGETS=0
-SKIPPED_TARGETS=0
-
-if [ -x "$SCRIPT_DIR/.tools/go/bin/go" ]; then
-    export PATH="$SCRIPT_DIR/.tools/go/bin:$PATH"
-fi
-export GOCACHE="${GOCACHE:-$SCRIPT_DIR/.cache/go-build}"
-export GOPATH="${GOPATH:-$SCRIPT_DIR/.cache/go}"
-mkdir -p "$GOCACHE" "$GOPATH"
-export PATH="$GOPATH/bin:$PATH"
-
-version_at_least() {
-    local have="${1#go}"
-    local want="$2"
-    local IFS=.
-    local have_parts want_parts
-    read -r -a have_parts <<< "$have"
-    read -r -a want_parts <<< "$want"
-    for i in 0 1 2; do
-        local h="${have_parts[$i]:-0}"
-        local w="${want_parts[$i]:-0}"
-        if (( h > w )); then return 0; fi
-        if (( h < w )); then return 1; fi
-    done
-    return 0
-}
-
-check_go() {
-    command -v go >/dev/null 2>&1 || { err "Go is not installed"; exit 1; }
-
-    local version
-    version="$(go env GOVERSION 2>/dev/null || go version | awk '{print $3}')"
-    if ! version_at_least "$version" "$MIN_GO_VERSION"; then
-        err "Go ${MIN_GO_VERSION}+ is required by go.mod; found ${version} at $(command -v go)"
-        err "Install a newer Go, or place it at .tools/go/bin/go for this project."
-        exit 1
-    fi
-}
-
-resolve_wails() {
-    if WAILS_BIN="$(command -v wails 2>/dev/null)"; then
-        WAILS_USE_GO_RUN=0
-        return
-    fi
-
-    local gopath
-    gopath="$(go env GOPATH 2>/dev/null || true)"
-    if [ -n "$gopath" ] && [ -x "$gopath/bin/wails" ]; then
-        WAILS_BIN="$gopath/bin/wails"
-        WAILS_USE_GO_RUN=0
-        return
-    fi
-
-    if [ -n "$WAILS_VERSION" ]; then
-        WAILS_BIN="github.com/wailsapp/wails/v2/cmd/wails@${WAILS_VERSION}"
-        WAILS_USE_GO_RUN=1
-        warn "Wails CLI not found; using pinned ${WAILS_BIN} via go run"
-        return
-    fi
-
-    err "Wails is not installed and no Wails version was found in go.mod"
-    exit 1
-}
-
-wails_cmd() {
-    if [ "$WAILS_USE_GO_RUN" -eq 1 ]; then
-        go run "$WAILS_BIN" "$@"
-    else
-        "$WAILS_BIN" "$@"
-    fi
-}
-
-ensure_upx() {
-    if ! nexus_bool_enabled "${NEXUS_COMPRESS:-0}"; then
-        return
-    fi
-    if command -v upx >/dev/null 2>&1; then
-        return
-    fi
-    warn "UPX is not installed; compressed targets will be skipped unless the target does not use UPX."
-}
-
-linux_deps_ok() {
-    command -v pkg-config >/dev/null 2>&1 || return 1
-    pkg-config --exists gtk+-3.0 || return 1
-    if ! pkg-config --exists webkit2gtk-4.1 && ! pkg-config --exists webkit2gtk-4.0; then
-        return 1
-    fi
-    if ! pkg-config --exists ayatana-appindicator3-0.1 && ! pkg-config --exists appindicator3-0.1; then
-        return 1
-    fi
-}
-
-build_tags() {
-    if command -v pkg-config >/dev/null 2>&1 \
-        && pkg-config --exists webkit2gtk-4.1 \
-        && ! pkg-config --exists webkit2gtk-4.0; then
-        echo "webkit2_41"
-    fi
-}
-
-build_version() {
-    local tag
-    local commit
-    tag="$(git describe --tags --abbrev=0 2>/dev/null || echo "dev")"
-    commit="$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")"
-    echo "${tag}-${commit}"
-}
-
-build_ldflags() {
-    local version="$1"
-    local flags="-s -w -X github.com/andydixon/nexus/internal/api.appVersion=${version}"
-    if [ -n "${NEXUS_UPDATE_URL:-}" ]; then
-        flags="${flags} -X github.com/andydixon/nexus/internal/api.appUpdateURL=${NEXUS_UPDATE_URL}"
-    fi
-    echo "${flags}"
-}
-
-check_deps() {
-    check_go
-    command -v node >/dev/null 2>&1 || { err "Node.js is not installed"; exit 1; }
-    command -v npm >/dev/null 2>&1 || { err "npm is not installed"; exit 1; }
-    resolve_wails
-    ensure_upx
-
-    log "Go:    $(go version)"
-    log "Node:  $(node --version)"
-    log "Wails: $(wails_cmd version 2>/dev/null | head -1)"
-}
-
-install_deps() {
-    log "Installing Go dependencies…"
-    go mod download
-
-    log "Installing frontend dependencies…"
-    if [ -f frontend/package-lock.json ]; then
-        (cd frontend && npm ci)
-    else
-        (cd frontend && npm install)
-    fi
-}
-
-host_os() {
-    case "$(uname -s)" in
-        Darwin) echo "darwin" ;;
-        Linux) echo "linux" ;;
-        *) echo "unknown" ;;
-    esac
-}
-
-host_arch() {
-    case "$(uname -m)" in
-        x86_64|amd64) echo "amd64" ;;
-        arm64|aarch64) echo "arm64" ;;
-        *) echo "unknown" ;;
-    esac
-}
-
-pick_cc() {
-    local target_os="$1"
-    local target_arch="$2"
-
-    if [ "$target_os" = "windows" ]; then
-        if [ "$target_arch" = "amd64" ]; then
-            echo "x86_64-w64-mingw32-gcc"
-        else
-            echo "aarch64-w64-mingw32-gcc"
-        fi
-        return
-    fi
-
-    if [ "$target_os" = "linux" ]; then
-        if [ "$target_arch" = "amd64" ]; then
-            echo "x86_64-linux-gnu-gcc"
-        else
-            echo "aarch64-linux-gnu-gcc"
-        fi
-        return
-    fi
-
-    echo ""
-}
-
-build_target() {
-    local target_os="$1"
-    local target_arch="$2"
-    local host="$3"
-    local host_arch_value="$4"
-    local version="$5"
-    local platform="${target_os}/${target_arch}"
-    nexus_configure_release_cgo
-    local ldflags
-    ldflags="$(build_ldflags "${version}")"
-    local tags
-    tags="$(build_tags)"
-    local build_args=("-platform" "$target_os/$target_arch" "-trimpath")
-    if nexus_use_upx_for_target "$target_os"; then
-        if ! command -v upx >/dev/null 2>&1; then
-            warn "Skipping ${platform} (NEXUS_COMPRESS=1 requires UPX)"
-            ((SKIPPED_TARGETS += 1))
-            return 0
-        fi
-        build_args+=("-upx")
-        if [ -n "${NEXUS_UPX_FLAGS:-}" ]; then
-            build_args+=("-upxflags" "$NEXUS_UPX_FLAGS")
-        fi
-    elif nexus_skips_upx_for_target "$target_os"; then
-        warn "Skipping UPX compression for ${platform}; distribute the zipped .app instead, or set NEXUS_FORCE_MACOS_UPX=1 with suitable NEXUS_UPX_FLAGS."
-    fi
-    if [ -n "$tags" ]; then
-        build_args+=("-tags" "$tags")
-    fi
-    build_args+=("-ldflags" "$ldflags")
-
-    local cc=""
-
-    if [ "$target_os" = "linux" ] && ! linux_deps_ok; then
-        warn "Skipping ${platform} (missing Linux GTK/WebKit build dependencies)"
-        ((SKIPPED_TARGETS += 1))
-        return 0
-    fi
-
-    if [ "$target_os" != "$host" ] || [ "$target_arch" != "$host_arch_value" ]; then
-        cc="$(pick_cc "$target_os" "$target_arch")"
-        if [ -n "$cc" ] && ! command -v "$cc" >/dev/null 2>&1; then
-            warn "Skipping ${platform} (missing C compiler: ${cc})"
-            ((SKIPPED_TARGETS += 1))
-            return 0
-        fi
-    fi
-
-    log "Building ${platform}…"
-    if [ -n "$cc" ]; then
-        CC="$cc" CGO_ENABLED=1 wails_cmd build "${build_args[@]}"
-    else
-        CGO_ENABLED=1 wails_cmd build "${build_args[@]}"
-    fi
-    ((BUILT_TARGETS += 1))
-}
-
-main() {
-    check_deps
-    install_deps
-
-    local version
-    version="$(build_version)"
-
-    local host
-    host="$(host_os)"
-    local arch
-    arch="$(host_arch)"
-    if [ "$host" = "unknown" ] || [ "$arch" = "unknown" ]; then
-        err "Unsupported host platform: $(uname -s)/$(uname -m)"
-        exit 1
-    fi
-
-    build_target "$host" "$arch" "$host" "$arch" "$version"
-
-    # Cross-build Linux and Windows targets where toolchains are available
-    if [ "$host" = "darwin" ] || [ "$host" = "linux" ]; then
-        for target in linux/amd64 linux/arm64 windows/amd64 windows/arm64; do
-            local target_os="${target%%/*}"
-            local target_arch="${target##*/}"
-            if [ "$target_os" = "$host" ] && [ "$target_arch" = "$arch" ]; then
-                continue
-            fi
-            build_target "$target_os" "$target_arch" "$host" "$arch" "$version"
-        done
-    fi
-
-    if [ "$BUILT_TARGETS" -eq 0 ]; then
-        err "No targets were built; ${SKIPPED_TARGETS} target(s) were skipped because required system toolchains are missing."
-        exit 1
-    fi
-
-    log "Builds complete (${BUILT_TARGETS} built, ${SKIPPED_TARGETS} skipped). Output: build/bin/"
-}
-
-main "$@"

build.ps1

@@ -1,143 +0,0 @@
-# build.ps1 — Windows build script for Nexus Terminal
-# Usage: .\build.ps1 [dev|build|test|clean|deps]
-Set-StrictMode -Version Latest
-$ErrorActionPreference = 'Stop'
-
-function Write-Info($Message) { Write-Host "[nexus] $Message" -ForegroundColor Green }
-function Write-Warn($Message) { Write-Host "[nexus] $Message" -ForegroundColor Yellow }
-function Write-Err($Message)  { Write-Host "[nexus] $Message" -ForegroundColor Red }
-
-function Test-BoolEnabled([string]$Value) {
-    return $Value -match '^(1|true|TRUE|yes|YES|on|ON)$'
-}
-
-function Get-WailsPath {
-    $wails = Get-Command wails -ErrorAction SilentlyContinue
-    if ($wails) { return $wails.Source }
-
-    $goPath = & go env GOPATH
-    $fallback = Join-Path $goPath 'bin\wails.exe'
-    if (Test-Path $fallback) { return $fallback }
-    return $null
-}
-
-function Check-Deps {
-    if (-not (Get-Command go -ErrorAction SilentlyContinue)) { throw 'Go is not installed.' }
-    if (-not (Get-Command node -ErrorAction SilentlyContinue)) { throw 'Node.js is not installed.' }
-    if (-not (Get-Command npm -ErrorAction SilentlyContinue)) { throw 'npm is not installed.' }
-
-    $wailsPath = Get-WailsPath
-    if (-not $wailsPath) {
-        throw 'Wails is not installed. Run: go install github.com/wailsapp/wails/v2/cmd/wails@latest'
-    }
-
-    Write-Info "Go:    $(& go version)"
-    Write-Info "Node:  $(& node --version)"
-    Write-Info "Wails: $(& $wailsPath version | Select-Object -First 1)"
-
-    if (-not (Get-Command gcc -ErrorAction SilentlyContinue)) {
-        Write-Warn 'gcc not found. SQLite requires cgo + a C compiler (e.g. MSYS2 mingw-w64).'
-    }
-
-    return $wailsPath
-}
-
-function Install-Deps {
-    Write-Info 'Installing Go dependencies...'
-    & go mod download
-
-    Write-Info 'Installing frontend dependencies...'
-    Push-Location 'frontend'
-    & npm install
-    Pop-Location
-}
-
-function Get-BuildVersion {
-    try {
-        $tag = & git describe --tags --abbrev=0 2>$null
-        if (-not $tag) { $tag = 'dev' }
-    } catch {
-        $tag = 'dev'
-    }
-
-    try {
-        $commit = & git rev-parse --short HEAD 2>$null
-        if (-not $commit) { $commit = 'unknown' }
-    } catch {
-        $commit = 'unknown'
-    }
-
-    return "$tag-$commit"
-}
-
-function Get-Ldflags([string]$Version) {
-    $flags = "-s -w -buildid= -X github.com/andydixon/nexus/internal/api.appVersion=$Version"
-    if ($env:NEXUS_UPDATE_URL) {
-        $flags += " -X github.com/andydixon/nexus/internal/api.appUpdateURL=$($env:NEXUS_UPDATE_URL)"
-    }
-    return $flags
-}
-
-function Dev {
-    $wailsPath = Check-Deps
-    Install-Deps
-    Write-Info 'Starting development mode...'
-    & $wailsPath dev
-}
-
-function Build {
-    $wailsPath = Check-Deps
-    Install-Deps
-    $version = Get-BuildVersion
-    $ldflags = Get-Ldflags $version
-
-    $env:CGO_ENABLED = '1'
-    if (-not $env:CGO_CFLAGS) { $env:CGO_CFLAGS = '-O2 -g0' }
-    if (-not $env:CGO_CXXFLAGS) { $env:CGO_CXXFLAGS = '-O2 -g0' }
-
-    $buildArgs = @('build', '-trimpath')
-    if (Test-BoolEnabled $env:NEXUS_COMPRESS) {
-        if (-not (Get-Command upx -ErrorAction SilentlyContinue)) {
-            throw 'NEXUS_COMPRESS=1 requires UPX. Install it first.'
-        }
-        $buildArgs += '-upx'
-        if ($env:NEXUS_UPX_FLAGS) {
-            $buildArgs += @('-upxflags', $env:NEXUS_UPX_FLAGS)
-        }
-    }
-    $buildArgs += @('-ldflags', $ldflags)
-
-    Write-Info 'Building production binary (CGO_ENABLED=1)...'
-    & $wailsPath @buildArgs
-    Write-Info 'Build complete: build\bin\'
-}
-
-function Run-Tests {
-    Write-Info 'Running tests...'
-    & go test ./... -v -count=1
-}
-
-function Clean {
-    Write-Info 'Cleaning build artefacts...'
-    Remove-Item -Recurse -Force -ErrorAction SilentlyContinue build\bin
-    Remove-Item -Recurse -Force -ErrorAction SilentlyContinue frontend\node_modules
-    Remove-Item -Recurse -Force -ErrorAction SilentlyContinue frontend\src\js\lib
-    Remove-Item -Recurse -Force -ErrorAction SilentlyContinue frontend\src\css\lib
-    & go clean -testcache
-    Write-Info 'Clean complete'
-}
-
-$task = $args[0]
-if (-not $task) { $task = 'build' }
-
-switch ($task) {
-    'dev'   { Dev }
-    'build' { Build }
-    'test'  { Run-Tests }
-    'clean' { Clean }
-    'deps'  { Check-Deps | Out-Null; Install-Deps }
-    default {
-        Write-Err 'Usage: .\\build.ps1 [dev|build|test|clean|deps]'
-        exit 1
-    }
-}

build.sh

@@ -1,267 +0,0 @@
-#!/usr/bin/env bash
-# build.sh — Build script for Nexus Terminal
-# Provides a reproducible build process for CI and local builds.
-# Usage: ./build.sh [dev|build|test|clean|deps]
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-cd "$SCRIPT_DIR"
-source "$SCRIPT_DIR/scripts/build-common.sh"
-
-# Colours for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m'
-
-log()  { echo -e "${GREEN}[nexus]${NC} $1"; }
-warn() { echo -e "${YELLOW}[nexus]${NC} $1"; }
-err()  { echo -e "${RED}[nexus]${NC} $1" >&2; }
-
-MIN_GO_VERSION="1.25.0"
-WAILS_VERSION="$(nexus_wails_version go.mod)"
-WAILS_BIN=""
-WAILS_USE_GO_RUN=0
-
-if [ -x "$SCRIPT_DIR/.tools/go/bin/go" ]; then
-    export PATH="$SCRIPT_DIR/.tools/go/bin:$PATH"
-fi
-export GOCACHE="${GOCACHE:-$SCRIPT_DIR/.cache/go-build}"
-export GOPATH="${GOPATH:-$SCRIPT_DIR/.cache/go}"
-mkdir -p "$GOCACHE" "$GOPATH"
-export PATH="$GOPATH/bin:$PATH"
-
-version_at_least() {
-    local have="${1#go}"
-    local want="$2"
-    local IFS=.
-    local have_parts want_parts
-    read -r -a have_parts <<< "$have"
-    read -r -a want_parts <<< "$want"
-    for i in 0 1 2; do
-        local h="${have_parts[$i]:-0}"
-        local w="${want_parts[$i]:-0}"
-        if (( h > w )); then return 0; fi
-        if (( h < w )); then return 1; fi
-    done
-    return 0
-}
-
-check_go() {
-    command -v go >/dev/null 2>&1 || { err "Go is not installed"; exit 1; }
-
-    local version
-    version="$(go env GOVERSION 2>/dev/null || go version | awk '{print $3}')"
-    if ! version_at_least "$version" "$MIN_GO_VERSION"; then
-        err "Go ${MIN_GO_VERSION}+ is required by go.mod; found ${version} at $(command -v go)"
-        err "Install a newer Go, or place it at .tools/go/bin/go for this project."
-        exit 1
-    fi
-}
-
-resolve_wails() {
-    if WAILS_BIN="$(command -v wails 2>/dev/null)"; then
-        WAILS_USE_GO_RUN=0
-        return
-    fi
-
-    local gopath
-    gopath="$(go env GOPATH 2>/dev/null || true)"
-    if [ -n "$gopath" ] && [ -x "$gopath/bin/wails" ]; then
-        WAILS_BIN="$gopath/bin/wails"
-        WAILS_USE_GO_RUN=0
-        return
-    fi
-
-    if [ -n "$WAILS_VERSION" ]; then
-        WAILS_BIN="github.com/wailsapp/wails/v2/cmd/wails@${WAILS_VERSION}"
-        WAILS_USE_GO_RUN=1
-        warn "Wails CLI not found; using pinned ${WAILS_BIN} via go run"
-        return
-    fi
-
-    err "Wails is not installed and no Wails version was found in go.mod"
-    exit 1
-}
-
-wails_cmd() {
-    if [ "$WAILS_USE_GO_RUN" -eq 1 ]; then
-        go run "$WAILS_BIN" "$@"
-    else
-        "$WAILS_BIN" "$@"
-    fi
-}
-
-ensure_upx() {
-    if ! nexus_bool_enabled "${NEXUS_COMPRESS:-0}"; then
-        return
-    fi
-    if nexus_skips_upx_for_target "$(host_os)"; then
-        return
-    fi
-    if command -v upx >/dev/null 2>&1; then
-        return
-    fi
-    err "NEXUS_COMPRESS=1 requires UPX. Install it first, for example: brew install upx"
-    exit 1
-}
-
-check_linux_deps() {
-    if [ "$(uname -s)" != "Linux" ]; then
-        return
-    fi
-
-    command -v pkg-config >/dev/null 2>&1 || {
-        err "pkg-config is required for Linux Wails builds."
-        err "On Ubuntu/Pop!_OS install: sudo apt-get install -y build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev"
-        exit 1
-    }
-
-    local missing=()
-    pkg-config --exists gtk+-3.0 || missing+=("gtk+-3.0")
-    if ! pkg-config --exists webkit2gtk-4.1 && ! pkg-config --exists webkit2gtk-4.0; then
-        missing+=("webkit2gtk-4.1 or webkit2gtk-4.0")
-    fi
-    if ! pkg-config --exists ayatana-appindicator3-0.1 && ! pkg-config --exists appindicator3-0.1; then
-        missing+=("ayatana-appindicator3-0.1 or appindicator3-0.1")
-    fi
-
-    if [ "${#missing[@]}" -gt 0 ]; then
-        err "Missing Linux build dependencies: ${missing[*]}"
-        err "On Ubuntu/Pop!_OS install: sudo apt-get install -y build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev"
-        exit 1
-    fi
-}
-
-build_tags() {
-    nexus_build_tags
-}
-
-host_os() {
-    case "$(uname -s)" in
-        Darwin) echo "darwin" ;;
-        Linux) echo "linux" ;;
-        *) echo "unknown" ;;
-    esac
-}
-
-build_version() {
-    nexus_build_version
-}
-
-build_ldflags() {
-    nexus_build_ldflags "$1"
-}
-
-# Check prerequisites
-check_deps() {
-    check_go
-    command -v node >/dev/null 2>&1 || { err "Node.js is not installed"; exit 1; }
-    command -v npm >/dev/null 2>&1 || { err "npm is not installed"; exit 1; }
-    check_linux_deps
-    resolve_wails
-    ensure_upx
-
-    log "All prerequisites found"
-    log "Go:    $(go version)"
-    log "Node:  $(node --version)"
-    log "Wails: $(wails_cmd version 2>/dev/null | head -1)"
-}
-
-# Install dependencies
-install_deps() {
-    log "Installing Go dependencies…"
-    go mod download
-
-    log "Installing frontend dependencies…"
-    if [ -f frontend/package-lock.json ]; then
-        (cd frontend && npm ci)
-    else
-        (cd frontend && npm install)
-    fi
-
-    log "Dependencies installed"
-}
-
-# Development mode
-dev() {
-    check_deps
-    install_deps
-    log "Starting development mode…"
-    wails_cmd dev
-}
-
-# Production build
-build() {
-    check_deps
-    install_deps
-    log "Building production binary…"
-    local version
-    version="$(build_version)"
-    local tags
-    tags="$(build_tags)"
-    nexus_configure_release_cgo
-    local build_args=("-trimpath")
-    if nexus_bool_enabled "${NEXUS_COMPRESS:-0}"; then
-        if nexus_skips_upx_for_target "$(host_os)"; then
-            warn "Skipping UPX compression on macOS; distribute the zipped .app instead, or set NEXUS_FORCE_MACOS_UPX=1 with suitable NEXUS_UPX_FLAGS."
-        else
-            log "Using UPX compression"
-            build_args+=("-upx")
-            if [ -n "${NEXUS_UPX_FLAGS:-}" ]; then
-                build_args+=("-upxflags" "$NEXUS_UPX_FLAGS")
-            fi
-        fi
-    fi
-    if [ -n "$tags" ]; then
-        log "Using Wails build tags: ${tags}"
-        wails_cmd build "${build_args[@]}" -tags "$tags" -ldflags "$(build_ldflags "${version}")"
-    else
-        wails_cmd build "${build_args[@]}" -ldflags "$(build_ldflags "${version}")"
-    fi
-
-    # Replace Wails-generated icon with custom app icon on macOS.
-    if [[ "$OSTYPE" == darwin* ]]; then
-        local app_bundle="build/bin/nexus-terminal.app"
-        local custom_icns="build/darwin/AppIcon.icns"
-        if [ -d "$app_bundle" ] && [ -f "$custom_icns" ]; then
-            cp "$custom_icns" "$app_bundle/Contents/Resources/iconfile.icns"
-            log "Replaced app icon with custom AppIcon.icns"
-        fi
-    fi
-
-    log "Build complete: build/bin/"
-}
-
-# Run tests
-run_tests() {
-    check_go
-    log "Running tests…"
-    go test ./... -v -count=1
-    (cd frontend && npm test)
-}
-
-# Clean build artefacts
-clean() {
-    log "Cleaning build artefacts…"
-    rm -rf build/bin
-    rm -rf frontend/node_modules
-    rm -rf frontend/src/js/lib
-    if command -v go >/dev/null 2>&1; then
-        go clean -testcache
-    fi
-    log "Clean complete"
-}
-
-# Main
-case "${1:-build}" in
-    dev)     dev ;;
-    build)   build ;;
-    test)    run_tests ;;
-    clean)   clean ;;
-    deps)    check_deps && install_deps ;;
-    *)
-        echo "Usage: $0 [dev|build|test|clean|deps]"
-        exit 1
-        ;;
-esac

build/darwin/Info.plist

@@ -1,69 +0,0 @@
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-    <dict>
-        <key>CFBundlePackageType</key>
-        <string>APPL</string>
-        <key>CFBundleName</key>
-        <string>{{.Info.ProductName}}</string>
-        <key>CFBundleExecutable</key>
-        <string>{{.OutputFilename}}</string>
-        <key>CFBundleIdentifier</key>
-        <string>com.andydixon.nexusterminal</string>
-        <key>CFBundleVersion</key>
-        <string>{{.Info.ProductVersion}}</string>
-        <key>CFBundleGetInfoString</key>
-        <string>{{.Info.Comments}}</string>
-        <key>CFBundleShortVersionString</key>
-        <string>{{.Info.ProductVersion}}</string>
-        <key>CFBundleIconFile</key>
-        <string>iconfile</string>
-        <key>LSMinimumSystemVersion</key>
-        <string>10.13.0</string>
-        <key>LSApplicationCategoryType</key>
-        <string>public.app-category.developer-tools</string>
-        <key>NSHighResolutionCapable</key>
-        <string>true</string>
-        <key>NSSupportsAutomaticTermination</key>
-        <false/>
-        <key>NSSupportsSuddenTermination</key>
-        <false/>
-        <key>NSHumanReadableCopyright</key>
-        <string>{{.Info.Copyright}}</string>
-        {{if .Info.FileAssociations}}
-        <key>CFBundleDocumentTypes</key>
-        <array>
-          {{range .Info.FileAssociations}}
-          <dict>
-            <key>CFBundleTypeExtensions</key>
-            <array>
-              <string>{{.Ext}}</string>
-            </array>
-            <key>CFBundleTypeName</key>
-            <string>{{.Name}}</string>
-            <key>CFBundleTypeRole</key>
-            <string>{{.Role}}</string>
-            <key>CFBundleTypeIconFile</key>
-            <string>{{.IconName}}</string>
-          </dict>
-          {{end}}
-        </array>
-        {{end}}
-        {{if .Info.Protocols}}
-        <key>CFBundleURLTypes</key>
-        <array>
-          {{range .Info.Protocols}}
-            <dict>
-                <key>CFBundleURLName</key>
-                <string>com.wails.{{.Scheme}}</string>
-                <key>CFBundleURLSchemes</key>
-                <array>
-                    <string>{{.Scheme}}</string>
-                </array>
-                <key>CFBundleTypeRole</key>
-                <string>{{.Role}}</string>
-            </dict>
-          {{end}}
-        </array>
-        {{end}}
-    </dict>
-</plist>

build/windows/info.json

@@ -1,15 +0,0 @@
-{
-	"fixed": {
-		"file_version": "{{.Info.ProductVersion}}"
-	},
-	"info": {
-		"0000": {
-			"ProductVersion": "{{.Info.ProductVersion}}",
-			"CompanyName": "{{.Info.CompanyName}}",
-			"FileDescription": "{{.Info.ProductName}}",
-			"LegalCopyright": "{{.Info.Copyright}}",
-			"ProductName": "{{.Info.ProductName}}",
-			"Comments": "{{.Info.Comments}}"
-		}
-	}
-}

build/windows/wails.exe.manifest

@@ -1,15 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1" xmlns:asmv3="urn:schemas-microsoft-com:asm.v3">
-    <assemblyIdentity type="win32" name="com.wails.{{.Name}}" version="{{.Info.ProductVersion}}.0" processorArchitecture="*"/>
-    <dependency>
-        <dependentAssembly>
-            <assemblyIdentity type="win32" name="Microsoft.Windows.Common-Controls" version="6.0.0.0" processorArchitecture="*" publicKeyToken="6595b64144ccf1df" language="*"/>
-        </dependentAssembly>
-    </dependency>
-    <asmv3:application>
-        <asmv3:windowsSettings>
-            <dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">true/pm</dpiAware> <!-- fallback for Windows 7 and 8 -->
-            <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">permonitorv2,permonitor</dpiAwareness> <!-- falls back to per-monitor if per-monitor v2 is not supported -->
-        </asmv3:windowsSettings>
-    </asmv3:application>
-</assembly>

docs/build-and-release.md

@@ -1,77 +1,74 @@
 # Build and Release
 
-This project uses [Wails](https://wails.io/) for desktop packaging.
+Nexus Terminal is a Rust workspace in `rust/`:
 
-## Ubuntu 24.04 prerequisites
-
-Install the Linux build toolchain and Wails runtime headers with:
-
-```bash
-sudo apt-get update
-sudo apt-get install -y \
-  build-essential \
-  libgtk-3-dev \
-  libwebkit2gtk-4.1-dev \
-  libayatana-appindicator3-dev \
-  pkg-config \
-  zip
+```
+rust/
+├── core/   nexus-core: storage, secrets, protocol clients, session manager, Service. No GUI.
+└── app/    nexus: the egui desktop app (binary `nexus-terminal`)
 ```
 
-Notes:
+The toolchain is pinned in `rust/rust-toolchain.toml`; `rustup` installs it on first build.
 
-- Ubuntu 24.04 does not ship `libwebkit2gtk-4.0-dev`.
-- Wails `v2.12.0` supports Ubuntu 24.04 by building with the `webkit2_41` tag.
-- The local build scripts detect that package layout automatically and add the tag when needed.
+## Prerequisites
 
-You will also need these tools available in `PATH`:
+- **All platforms:** [rustup](https://rustup.rs).
+- **Linux:** the X11/Wayland/GL headers eframe links against, and GTK for native file dialogs:
 
-- `go`
-- `node`
-- `npm`
-- `wails`
+  ```bash
+  sudo apt-get install -y build-essential pkg-config libxkbcommon-dev libgl1-mesa-dev \
+    libx11-dev libxcursor-dev libxrandr-dev libxi-dev libwayland-dev libgtk-3-dev libasound2-dev zip
+  ```
 
-Install the Wails CLI with:
+- **macOS:** Xcode command-line tools (`xcode-select --install`).
+- **Windows:** the MSVC build tools (Visual Studio Build Tools, "Desktop development with C++").
+
+There are no runtime C libraries to install: SQLite is compiled in and TLS uses rustls.
+
+## Build and run
 
 ```bash
-go install github.com/wailsapp/wails/v2/cmd/wails@latest
-export PATH="$PATH:$(go env GOPATH)/bin"
+cd rust
+cargo run --release                 # the app
+cargo test --workspace              # unit and integration tests
+cargo clippy --workspace -- -D warnings
 ```
 
-## Build commands
+Useful flags (also handy for testing): `nexus-terminal [--theme pro|midnight|light]
+[--data-dir DIR] [--screenshot out.png] [--size WxH] [--run-local CMD]`. `--data-dir` points at
+another data directory; `--screenshot` renders the window, saves a PNG and exits (works under
+`xvfb-run`); `--run-local` opens a local terminal and types `CMD` into it.
 
-Build the app binary for the current host:
-
-```bash
-./build.sh
-```
-
-Build a packaged release for the current host platform:
-
-```bash
-./release.sh
-```
-
-By default, `./release.sh` now builds only the current host OS/architecture. On this Ubuntu 24.04 `amd64` host that means `linux/amd64`.
-
-## Optional cross-compilers
-
-If you want to add extra Linux/Windows targets from Ubuntu, install the relevant cross-compiler packages first:
-
-```bash
-sudo apt-get install -y \
-  gcc-aarch64-linux-gnu \
-  gcc-mingw-w64-x86-64
-```
-
-Then request explicit targets:
+The SSH integration tests start a throwaway `sshd` as the current user on a random port; they
+skip themselves when OpenSSH isn't installed.
+
+## Release packages
 
 ```bash
+cd rust
+./release.sh                                            # this machine's platform
 NEXUS_RELEASE_TARGETS=linux/amd64,windows/amd64 ./release.sh
 ```
 
-## Platform caveats
+Artefacts land in `build/releases/<version>/` at the repo root:
 
-- macOS targets cannot be cross-built from Linux with Wails. Build those on macOS.
-- `windows/arm64` is not covered by the default Ubuntu toolchain here.
-- `linux/arm64` needs more than `gcc-aarch64-linux-gnu`; it also needs an `arm64` sysroot and target GTK/WebKit development libraries for CGO to link cleanly.
-- Tested on Ubuntu 24.04 `amd64`: `linux/amd64` and `windows/amd64` build successfully; `linux/arm64` does not in the default host setup above.
+- `NexusTerminal-<os>-<arch>.zip` — on macOS a universal-capable `.app` bundle
+  (`rust/packaging/macos/build-app.sh`), on Windows the `.exe` (icon and version info embedded,
+  GUI subsystem), on Linux the binary plus `install.sh` and a `.desktop` entry
+  (`rust/packaging/linux/install.sh` installs into `~/.local`).
+- `manifest-<os>-<arch>.json` and `version-<os>-<arch>.txt` for the update server
+  (`updates/index.php`), in the same format as before.
+
+The version is `<latest tag>-<short commit>` unless `NEXUS_VERSION` is set. The update manifest
+URL is compiled in from `NEXUS_UPDATE_URL` (default in `release.sh`); `{platform}` and `{arch}` use
+the old Go names (`darwin`/`linux`/`windows`, `amd64`/`arm64`).
+
+Cross-building `windows/amd64` from Linux works with `x86_64-pc-windows-gnu` and mingw-w64.
+macOS bundles must be built on a Mac. CI (`.github/workflows/release-builds.yml`) builds every
+platform natively on GitHub runners and attaches the zips to tagged releases;
+`.github/workflows/ci.yml` runs tests and clippy on Linux, macOS and Windows.
+
+## Signing
+
+macOS bundles are ad-hoc signed. For distribution, sign with a Developer ID and notarize (see the
+comments in `build-app.sh`). Windows binaries are unsigned.

docs/guide/Makefile

@@ -0,0 +1,11 @@
+# Builds nexus-guide.pdf with LuaLaTeX (three passes: contents, page references, then page overlays settle).
+# Needs LuaLaTeX with luaotfload (Debian/Ubuntu: texlive-luatex texlive-latex-extra).
+# Screenshots: tools/screenshots.sh (needs xvfb-run, sshd, python3).
+OUT ?= build
+nexus-guide.pdf: nexus-guide.tex nexus-guide.sty chapters/*.tex img/*
+	mkdir -p $(OUT)
+	lualatex -interaction=nonstopmode -halt-on-error -output-directory=$(OUT) nexus-guide.tex > /dev/null || (grep -A8 '^!' $(OUT)/nexus-guide.log; false)
+	for i in 1 2; do lualatex -interaction=nonstopmode -halt-on-error -output-directory=$(OUT) nexus-guide.tex > /dev/null; done
+	cp $(OUT)/nexus-guide.pdf .
+clean:
+	rm -rf $(OUT)

docs/guide/chapters/appendix.tex

@@ -0,0 +1,120 @@
+\guidepart{slate}{Extras}{The extras}
+  {The cheat sheet, the command line, and words you might trip over.}
+  {\partitem{\iKeyboard}{Keyboard cheat sheet}
+   \partitem{\iTerminal}{Command-line options}
+   \partitem{\iBrain}{Glossary}}
+
+% =========================================================================================
+\chapter{Keyboard cheat sheet}\label{app:keys}
+\chapmeta{print it}{Stick this page next to your monitor}
+
+\newcommand\shortcut[2]{#1 & #2\\}
+\newcommand\sheet[3]{%
+  \begin{tcolorbox}[enhanced, arc=8pt, boxrule=0pt, colback=#1!7, left=10pt, right=10pt, top=8pt, bottom=8pt,
+    before skip=0pt, after skip=10pt, fontupper=\small]
+  {\heavy\large\color{#1!85!black}#2}\par\vspace{4pt}
+  \renewcommand\arraystretch{1.5}\begin{tabularx}{\linewidth}{@{}X>{\raggedleft\arraybackslash}p{36mm}@{}}#3\end{tabularx}
+  \end{tcolorbox}}
+
+\begin{multicols}{2}
+\sheet{accent}{\iRocket\enspace Everywhere}{%
+  \shortcut{Command palette}{\keys{\mod+K}}
+  \shortcut{New connection}{\keys{\mod+N}}
+  \shortcut{Quick Connect}{\keys{\mod+Shift+Q}}
+  \shortcut{Settings}{\keys{\mod+,}}
+  \shortcut{Full screen}{\kbd{F11}}}
+
+\sheet{violet}{\iSplit\enspace Tabs \& panes}{%
+  \shortcut{Close tab}{\keys{\mod+W}}
+  \shortcut{Next tab}{\keys{\mod+Tab}}
+  \shortcut{Previous tab}{\keys{\mod+Shift+Tab}}
+  \shortcut{Go to tab 1–9}{\keys{\mod+1}…\kbd{9}}
+  \shortcut{Split right}{\keys{\mod+Shift+D}}
+  \shortcut{Split down}{\keys{\mod+Shift+E}}}
+
+\sheet{teal}{\iWand\enspace Power tools}{%
+  \shortcut{Broadcast on/off}{\keys{\mod+Shift+B}}
+  \shortcut{Snippets}{\keys{\mod+Shift+S}}
+  \shortcut{Record on/off}{\keys{\mod+Shift+R}}}
+
+\sheet{amber}{\iTerminal\enspace In the terminal}{%
+  \shortcut{Copy selection}{\keys{\mod+C}}
+  \shortcut{Paste}{\keys{\mod+V}}
+  \shortcut{Find}{\keys{\mod+F}}
+  \shortcut{Next / previous match}{\kbd{Enter} / \keys{Shift+Enter}}
+  \shortcut{Scroll a page}{\keys{Shift+PageUp}}
+  \shortcut{Top / bottom}{\keys{Shift+Home} / \kbd{End}}
+  \shortcut{Previous / next prompt}{\keys{\mod+Shift+Up} / \kbd{Down}}
+  \shortcut{Open link}{\kbd{Ctrl}/\kbd{\ph{E1C4}} + click}}
+
+\sheet{pink}{\iMap\enspace Mouse moves}{%
+  \shortcut{Select word / line}{double / triple-click}
+  \shortcut{Extend selection}{\kbd{Shift} + click}
+  \shortcut{Select several profiles}{\kbd{Ctrl}/\kbd{\ph{E1C4}} + click}
+  \shortcut{Everything else}{right-click it}}
+\end{multicols}
+
+% =========================================================================================
+\chapter{Command-line options}\label{app:cli}
+\chapmeta{1 minute}{You'll script, demo and test with a few handy flags}
+
+\renewcommand\arraystretch{1.5}
+\begin{tabularx}{\linewidth}{@{}>{\leavevmode\ttfamily\color{ink}}p{52mm}X@{}}
+  \toprule
+  --data-dir DIR        & Use another data folder (portable installs, demos, testing).\\
+  --theme pro|midnight|light & Start with this theme.\\
+  --connect NAME        & Connect to a saved profile by name at startup. Repeat it for several.\\
+  --open WINDOW         & Open a window at startup: \code{settings}, \code{settings:security},
+                          \code{settings:diagnostics}, \code{snippets}, \code{keys}, \code{recordings}, \code{palette},
+                          \code{quick}…\\
+  --run-local CMD       & Open a local shell and run a command in it.\\
+  RUST\_LOG=debug        & (environment) More detail in \code{nexus.log}, and on the terminal you started from.\\
+  --version             & Print the version and exit.\\
+  \bottomrule
+\end{tabularx}
+
+\begin{sidequest}[How the screenshots in this guide were made]
+Every screenshot here is the real app, driven by \code{docs/guide/tools/screenshots.sh}: it starts throwaway
+SSH, IRC, VNC and GitHub-ish servers, fills a demo data folder, and runs Nexus Terminal headless with
+\code{--screenshot}, \code{--do} (run a palette command) and \code{--answer} (fill a password prompt; only accepted together with \code{--screenshot}). Change the app,
+rerun the script, rebuild the guide.
+\end{sidequest}
+
+% =========================================================================================
+\chapter{Glossary}\label{app:glossary}
+\chapmeta{dip in}{Words you might trip over, in one line each}
+
+\begin{multicols}{2}\small
+\begin{description}[leftmargin=0pt, itemsep=5pt]
+  \item[Agent] A background program holding your unlocked SSH keys, so you type the passphrase once.
+  \item[Asciicast] The file format for terminal recordings. Plays in Nexus Terminal and \code{asciinema}.
+  \item[Bastion / jump host] A server you go \emph{through} to reach the ones behind it.
+  \item[Baud rate] How fast a serial line talks. Both ends must agree.
+  \item[Broadcast] Typing into several sessions at once.
+  \item[Certificate authority] A key that vouches for other keys, so servers signed by it are trusted without a prompt.
+  \item[DTR / RTS] Serial control lines. Some boards use them for reset or flashing.
+  \item[Fingerprint] A short summary of a server's host key, used to spot imposters.
+  \item[Host key] A server's identity. Changes when it's rebuilt, or when someone's pretending.
+  \item[Keychain] Your operating system's password store.
+  \item[NLA] Network Level Authentication: Windows checks your password before building a desktop.
+  \item[OSC 133] The escape codes a shell uses to mark its prompts, which powers shell integration.
+  \item[Port forward] A tunnel carrying one TCP port through SSH.
+  \item[Profile] A saved connection.
+  \item[RAW TCP] A plain socket: bytes in, bytes out, no terminal rules.
+  \item[RDP] Microsoft's Remote Desktop Protocol, for Windows (and xrdp) desktops.
+  \item[SASL] How IRC networks log you in while you connect, instead of messaging NickServ afterwards.
+  \item[SFTP] File transfer over SSH.
+  \item[Snippet] A saved command, optionally with blanks to fill in.
+  \item[TOTP] Time-based one-time passwords: the six digits from your authenticator app.
+  \item[Trigger] A rule that watches output and reacts to a pattern.
+  \item[Vault] Nexus Terminal's encrypted password store, for when there's no keychain.
+  \item[VNC] A way of seeing and controlling another computer's desktop.
+\end{description}
+\end{multicols}
+
+\vfill
+\begin{center}
+\includegraphics[width=16mm]{img/logo.pdf}\par\vspace{6pt}
+{\heavy\color{ink}That's the lot.}\par
+{\small\color{muted}Go and connect to something. \iRocket}
+\end{center}

docs/guide/chapters/part1-start.tex

@@ -0,0 +1,247 @@
+\guidepart{accent}{Get going}{Get going}
+  {From zero to connected before your tea goes cold.}
+  {\partitem{\iRocket}{Five-minute start}
+   \partitem{\iMap}{The grand tour}
+   \partitem{\iList}{Profiles: your address book}}
+
+% =========================================================================================
+\chapter{Five-minute start}\label{ch:start}
+\chapmeta{5 minutes}{You'll be connected to something and know the one shortcut that matters}
+
+\begin{tldr}
+Install it, open it, press \keys{\mod+N}, fill in a host, hit \ui{Create \& Connect}. Done.
+Lost? Press \keys{\mod+K} and type what you want.
+\end{tldr}
+
+\section{Install it}
+
+Grab the zip for your machine from \code{dixon.cx/downloads/nexus}. They're named
+\code{NexusTerminal-<os>-<arch>.zip}, so a modern Mac wants \code{darwin-arm64} and most PCs want \code{amd64}.
+
+\begin{description}
+  \item[\iDesktop\enspace Windows] Unzip it and run \code{NexusTerminal-windows-amd64.exe}. No installer, no admin rights,
+    nothing in the registry. Pop it somewhere sensible like \code{C:\textbackslash Tools} and pin it to the taskbar.
+  \item[\iDesktop\enspace macOS] Unzip it and drag \code{NexusTerminal-darwin-arm64.app} into \ui{Applications}. If macOS
+    grumbles that it can't check the developer, right-click the app, choose \ui{Open}, then \ui{Open} again. You only
+    have to do that once.
+  \item[\iDesktop\enspace Linux] Unzip it and run \code{./install.sh}. It copies \code{nexus-terminal} into
+    \code{~/.local/bin} and adds a launcher entry with the icon, so it turns up in your app menu.
+    (Make sure \code{~/.local/bin} is on your \code{PATH}.)
+\end{description}
+
+\begin{sidequest}[Build it yourself]
+It's a single Rust program. With Rust installed: \code{cd rust \&\& cargo run --release}. The finished binary lands in
+\code{rust/target/release/nexus-terminal}. The build guide in \code{docs/build-and-release.md} has the full story.
+\end{sidequest}
+
+\section{Open it}
+
+The first time you open Nexus Terminal you get a calm, empty welcome screen. Three buttons, four shortcuts. That's it.
+
+\shot{welcome.png}{The welcome screen. Your saved connections will live down the left; here there are a few already.}
+
+\begin{headsup}[Got more than one computer?]
+Point \ui{Profile sync} at a shared folder and your connections follow you around. See
+\hyperref[ch:move]{Moving house} on p.\,\pageref{ch:move}.
+\end{headsup}
+
+\section{Make your first connection}
+
+\begin{enumerate}
+  \item Click \ui{New Connection}, or press \keys{\mod+N}.
+  \item Pick the protocol along the top: \proto[teal]{SSH}, \proto[amber]{Telnet}, \proto[violet]{RAW TCP},
+        \proto[slate]{GitHub}, \proto[rose]{VNC}, \proto[rose]{RDP}, \proto[amber]{IRC} or \proto[accent]{Serial}.
+  \item Fill in the \ui{General} bit: a \ui{Display Name} you'll recognise, the \ui{Host}, the \ui{Port}
+        and your \ui{Username}.
+  \item Click \ui{Create \& Connect}.
+\end{enumerate}
+
+That's genuinely it. A tab opens, you log in, and next time it's one click in the sidebar.
+
+\crop{editor-new.png}{1515}{40}{0}{70}{0.52\linewidth}{A brand-new SSH profile. Only the top few fields are needed to get going.}
+
+\begin{quickwin}
+Click \ui{Test} before you save. Nexus Terminal checks the host and port are reachable and tells you the
+round-trip time. If that fails, no amount of password-fiddling will help, so it's a great first check.
+\end{quickwin}
+
+\section{Two shortcuts for impatient people}
+
+\subsection{Quick Connect}
+Press \keys{\mod+Shift+Q}.
+For a one-off session you don't want to save. Pick SSH, Telnet, RAW, IRC or Serial, type the host (or serial
+device), hit \kbd{Enter}. Nothing gets saved.
+
+\crop{quick.png}{951}{620}{946}{481}{0.5\linewidth}{Quick Connect. In, out, nobody gets hurt.}
+
+\subsection{Local terminal}
+Click \ui{Local Machine} at the top of the sidebar (or \ui{Local} on the welcome screen) for a shell on
+\emph{this} computer. When you type \code{exit}, the tab says \code{[Exited - press enter to restart]}.
+Press \kbd{Enter} and you've got a fresh shell in the same tab.
+
+\section{The one shortcut to rule them all}
+
+\begin{center}
+\begin{tcolorbox}[enhanced, width=0.8\linewidth, arc=10pt, boxrule=0pt, colback=ink, fontupper=\color{white},
+  halign=center, top=10pt, bottom=10pt, drop fuzzy shadow]
+{\scalebox{2.4}{\keys{\mod+K}}}\par\vspace{6pt}\par\vspace{4pt}
+{\color{white!70!ink} The command palette. If you remember nothing else, remember this.}
+\end{tcolorbox}
+\end{center}
+
+Type a few letters of \emph{anything}: a connection name, a tab, ``theme'', ``split'', ``lock'', ``snippets''. Use
+\kbd{↑}\kbd{↓} to pick, \kbd{Enter} to go, \kbd{Esc} to bail. It's fuzzy, so ``atl'' finds \emph{atlas} and
+``sft'' finds the \emph{SFTP Browser}.
+
+\crop{palette.png}{755}{732}{733}{154}{0.72\linewidth}{The command palette: every connection, tab and action in one searchable list.}
+
+\begin{quickwin}[Your five-minute checklist]
+\begin{checklist}
+  \item Installed and opened Nexus Terminal
+  \item Opened a \ui{Local Machine} tab and typed \code{exit}, then \kbd{Enter} to get it back
+  \item Made a profile with \keys{\mod+N} and clicked \ui{Test}
+  \item Connected to it
+  \item Opened the palette with \keys{\mod+K} and found something by typing three letters
+\end{checklist}
+All ticked? You're officially more productive than you were five minutes ago. \iConfetti
+\end{quickwin}
+
+% =========================================================================================
+\chapter{The grand tour}\label{ch:tour}
+\chapmeta{4 minutes}{You'll know what every bit of the window is for}
+
+\begin{tldr}
+Connections on the left. Sessions in tabs across the top. The terminal in the middle. Status along the bottom.
+Everything else is one \keys{\mod+K} away.
+\end{tldr}
+
+\begin{annotated}{ssh.png}
+  \callout{1}{0.124}{0.022}
+  \callout{2}{0.66}{0.022}
+  \callout{3}{0.888}{0.022}
+  \callout{4}{0.22}{0.067}
+  \callout{5}{0.03}{0.152}
+  \callout{6}{0.53}{0.063}
+  \callout{7}{0.966}{0.063}
+  \callout{8}{0.62}{0.42}
+  \callout{9}{0.16}{0.945}
+  \callout{10}{0.26}{0.985}
+  \callout{11}{0.86}{0.985}
+\end{annotated}
+
+\begin{multicols}{2}\small
+\begin{description}[leftmargin=0pt, labelsep=0.4em]
+  \item[\num{1} Menus] \menu{File}, \menu{Session}, \menu{View} and \menu{Help}. Drag the title bar to move the
+        window; double-click it to maximise.
+  \item[\num{2} Palette] The search box is the command palette. Click it or press \keys{\mod+K}.
+  \item[\num{3} Light/dark] Flip between the dark and light themes in one click.
+  \item[\num{4} Search] Fuzzy-search your connections by name, host, tag or protocol.
+  \item[\num{5} Sections] \ui{Local Machine}, \ui{Favourites} \iStar, \ui{Recent} (your last five), then one section
+        per group. Click a header to fold it away.
+  \item[\num{6} Tabs] One per session, with a coloured state dot, protocol badge and close button. SSH tabs get a
+        little \iFolder{} for files. A blue dot means ``new output while you weren't looking''.
+  \item[\num{7} New \& broadcast] \ui{+} opens a new connection; \iBroadcast{} toggles broadcast mode.
+  \item[\num{8} Workspace] Your terminal (or IRC chat, VNC desktop, GitHub list…). Split it into panes, too.
+  \item[\num{9} Footer] New connection, palette, import, export, recordings and settings.
+  \item[\num{10} Status] State, protocol and live latency for SSH. Shows \ui{REC} while recording and
+        \ui{BROADCAST} when broadcasting.
+  \item[\num{11} Sessions \& vault] How many sessions are connected and whether the vault is locked. Click the vault to
+        open security settings.
+\end{description}
+\end{multicols}
+
+\begin{protip}
+Drag the right-hand edge of the sidebar to make it wider or narrower. Toasts (the little pop-up messages in the
+top-right) tidy themselves away after a few seconds; click \ui{×} if you're impatient.
+\end{protip}
+
+\section{Three looks}
+
+Nexus Terminal comes in \ui{Pro} (the default, a soft charcoal), \ui{Midnight} (darker, bluer, for 2\,a.m.
+deploys) and \ui{Light} (for sunny days and projectors). Switch with the \iBulb{} button in the title bar, the
+\menu{View} menu, or type ``theme'' into the palette.
+
+\shotpair{welcome-midnight.png}{Midnight}{ssh-light.png}{Light, with a session open}
+
+The \emph{terminal} has its own colour schemes too: eleven of them, including \ui{Dracula}, \ui{Nord},
+\ui{Tokyo Night}, \ui{Catppuccin Mocha} and \ui{Rosé Pine}. Those live in \menu{Settings\then Terminal} and the \menu{View} menu.
+
+% =========================================================================================
+\chapter{Profiles: your address book}\label{ch:profiles}
+\chapmeta{6 minutes}{You'll keep dozens of connections tidy without thinking about it}
+
+\begin{tldr}
+A \emph{profile} is a saved connection. Give it a name and a group, star the ones you use daily, and
+right-click for everything else. Ctrl-click to select lots at once.
+\end{tldr}
+
+\section{Create, edit, copy}
+
+\begin{itemize}
+  \item \textbf{New:} \ui{+} in the sidebar footer or tab strip, \keys{\mod+N}, or right-click a group header and choose
+        \ui{New connection in …} (it lands in that group automatically).
+  \item \textbf{Edit:} double-click a profile, or right-click\then\ui{Edit}. The editor slides in on the right.
+  \item \textbf{Copy:} right-click\then\ui{Duplicate}. Great for ``same as web-01 but web-02''.
+  \item \textbf{Delete:} right-click\then\ui{Delete}. This also deletes the saved passwords for that profile.
+\end{itemize}
+
+\crop{editor-ssh.png}{1515}{40}{0}{70}{0.52\linewidth}{Editing an existing SSH profile. The editor scrolls; sections are grouped so you can ignore most of them.}
+
+\subsection{What goes in a profile}
+
+Every profile has the same \ui{General} section, then sections specific to its protocol (Part 2 covers each
+one). The common bits are:
+
+\renewcommand\arraystretch{1.4}
+\begin{tabularx}{\linewidth}{@{}>{\leavevmode\heavy\color{ink}}p{32mm}X@{}}
+  \toprule
+  Display Name & What you'll see in the sidebar. Make it obvious: ``db-primary'', not ``server 3''.\\
+  Host / Port  & Where to connect. Serial profiles have a \ui{Device} instead.\\
+  Group        & Pick an existing group or type a new name to create one.\\
+  Description  & One line shown on hover.\\
+  Terminal     & Font, size (8–36), scrollback (0–100\,000 lines) and cursor style, just for this profile.\\
+  Tags \& Notes & Comma-separated tags (searchable!) and free-form notes for future-you.\\
+  \bottomrule
+\end{tabularx}
+
+Each protocol adds its own sections underneath. Here are four of them side by side; Part~2 goes through each one.
+
+\begin{center}
+\newcommand\mini[2]{\begin{minipage}[t]{0.24\linewidth}\centering\includegraphics[width=\linewidth, trim=1515 600 0 70, clip]{img/#1}\par\vspace{2pt}{\scriptsize\color{muted}#2}\end{minipage}}
+\mini{editor-telnet.png}{Telnet}\hfill\mini{editor-raw.png}{RAW TCP}\hfill\mini{editor-vnc.png}{VNC}\hfill\mini{editor-irc.png}{IRC}
+\end{center}
+
+\begin{protip}[Tags are secretly brilliant]
+Tag things by where they live and what they do (\code{eu-west}, \code{db}, \code{customer-x}). The sidebar search
+matches tags, so typing ``db'' instantly narrows hundreds of profiles to the database servers.
+\end{protip}
+
+\section{Favourites, groups and Recent}
+
+\begin{itemize}
+  \item Right-click\then\ui{Add to Favourites} pins a profile into the \ui{\iStar\ Favourites} section at the top.
+  \item \ui{Recent} always shows the last five things you connected to. You don't have to do anything.
+  \item Groups are just the \ui{Group} field. No group? It goes in \ui{Ungrouped}.
+\end{itemize}
+
+\section{Do lots at once}
+
+Hold \kbd{Ctrl} (\kbd{\ph{E1C4}} on a Mac) and click several profiles. A bar appears at the bottom of the sidebar:
+
+\begin{center}\small
+\begin{tabular}{@{}ll@{\qquad}ll@{}}
+  \ui{Connect all} & opens them all in tabs & \ui{Move group} & moves them (blank = Ungrouped)\\
+  \ui{Disconnect}  & closes their sessions & \ui{Delete} & deletes them (asks first)\\
+  \ui{Tags}        & add or replace tags & \ui{Clear} & forget the selection\\
+\end{tabular}
+\end{center}
+
+\begin{quickwin}
+Select every web server, choose \ui{Connect all}, then turn on broadcast (\keys{\mod+Shift+B}). You're now typing into
+all of them at once. Chapter~\ref{ch:repeat} has the details, and the safety advice.
+\end{quickwin}
+
+\section{``It's already open…''}
+
+Click a profile that already has a live session and Nexus Terminal asks whether to \ui{Use Existing} (jump to that
+tab), open a \ui{New Connection} alongside it, or \ui{Cancel}. No more accidental duplicate sessions.

docs/guide/chapters/part2-connect.tex

@@ -0,0 +1,333 @@
+\guidepart{teal}{Connect}{Connect to all the things}
+  {Nine ways in. Pick the one you need; skip the rest.}
+  {\partitem{\iTerminal}{SSH: the big one}
+   \partitem{\iUsb}{Serial: cables and consoles}
+   \partitem{\iPlug}{Telnet and RAW TCP}
+   \partitem{\iDesktop}{VNC remote desktops}
+   \partitem{\iDesktop}{RDP: Windows desktops}
+   \partitem{\iChat}{IRC}
+   \partitem{\iGithub}{GitHub}}
+
+% =========================================================================================
+\chapter{SSH: the big one}\label{ch:ssh}
+\chapmeta{10 minutes (or 2 for the basics)}{You'll log in with keys, hop through bastions and never type a 2FA code again}
+
+\begin{tldr}
+Host, username, key, done. Everything else (jump hosts, proxies, forwards, 2FA, login scripts) is optional and
+lives in its own fold-away section of the editor. Open only the ones you need.
+\end{tldr}
+
+\begin{glance}{teal}{SSH}
+  Default port & 22\\
+  Logs in with & Password, public key, keyboard-interactive, SSH agent\\
+  Extras       & SFTP file browser, port forwards, live latency, agent forwarding, TOTP 2FA\\
+  Good for     & Servers, VMs, Raspberry Pis, anything with \code{sshd}\\
+\end{glance}
+
+\section{The two-minute version}
+
+\begin{enumerate}
+  \item \keys{\mod+N}, leave the protocol on \proto[teal]{SSH}.
+  \item \ui{Host}, \ui{Username}. Leave the port on 22 unless you know otherwise.
+  \item Under \ui{Key \& Passphrase}, pick your key from the suggestions (Nexus Terminal lists the keys in your
+        \code{\textasciitilde/.ssh} folder) and check for a little green \ui{Key verified}.
+  \item \ui{Create \& Connect}. The first time, you'll be asked to trust the server's host key. Say yes if you
+        were expecting it.
+\end{enumerate}
+
+\crop{hostkey.png}{842}{720}{845}{589}{0.66\linewidth}{First time connecting? You'll be shown the server's fingerprint. \ui{Accept \& Save} if it's the server you meant.}
+
+\begin{headsup}
+Type the full path to a key if you're not using the suggestions. Nexus Terminal doesn't expand \code{\textasciitilde}
+in that box, so write \code{/home/you/.ssh/id\_ed25519} (or \code{C:\textbackslash Users\textbackslash you\textbackslash .ssh\textbackslash id\_ed25519}).
+\end{headsup}
+
+\section{How it logs in}
+
+Under \ui{Authentication}, tick which \ui{Auth Methods} to try: \ui{Public key}, \ui{Password} and
+\ui{Keyboard-interactive}. Under \ui{SSH Agent}, tick \ui{Use SSH Agent for Authentication} to use keys already
+loaded into \code{ssh-agent} (or Pageant, or the Windows OpenSSH agent).
+
+Got an SSH \emph{user certificate}? Put it next to the key with the usual name (\code{id\_ed25519-cert.pub} beside
+\code{id\_ed25519}) and Nexus Terminal presents it automatically. Servers that hand out \emph{host} certificates are
+covered in \hyperref[ch:hostkeys]{Host keys} (p.\,\pageref{ch:hostkeys}).
+
+Every password and passphrase has a \emph{mode}: save it securely, remember it until you quit, or ask every time.
+That's all explained in \hyperref[ch:secrets]{Passwords \& the vault} (p.\,\pageref{ch:secrets}).
+
+\begin{protip}[Agent forwarding]
+Tick \ui{Forward Agent to Remote} (it's \code{ssh -A}) and you can \code{git pull} or hop onwards from the server using
+the keys on \emph{your} machine. Only do it on servers you trust: anyone with root there can use your agent while
+you're connected.
+\end{protip}
+
+\section{Jump hosts: getting through the bastion}
+
+Lots of servers hide behind a bastion. Add one or more hops under \ui{Jump Hosts}, each with its own user, host,
+port and optional key. Nexus Terminal tunnels through them in order, so the chain
+\textit{you\then bastion\then internal-box\then db-primary} is just three rows.
+
+\section{Proxies}
+
+Stuck behind a corporate proxy? Under \ui{Proxy}, choose \ui{SOCKS5} or \ui{HTTP CONNECT} and fill in the host,
+port and (optional) username and password. The proxy is used to reach the SSH server, or the first jump host if
+you have some.
+
+\section{2FA without the phone faff}\label{sec:totp}
+
+If your server asks for a one-time code, paste the Base32 TOTP secret (the text version of the QR code) into
+\ui{TOTP Secret} and hit \ui{Save}. From then on, Nexus Terminal answers the ``Verification code:'' prompt itself.
+\ui{Test} shows today's code so you can check it matches your phone.
+
+\begin{headsup}
+Save the profile first, then save the TOTP secret. And make sure your computer's clock is right: TOTP codes are
+time-based, so a clock that's a minute out will produce wrong codes.
+\end{headsup}
+
+\section{Do things automatically on login}
+
+\begin{description}
+  \item[Startup] A \ui{Startup Command} to run once you're in (say, \code{tmux attach}), plus
+        \ui{Environment Variables} as \code{KEY=VALUE}, one per line.
+  \item[Login Script] For old-school boxes that ask questions. Add steps: \ui{Wait for} some text, then
+        \ui{Send} a reply. Repeat as needed.
+\end{description}
+
+\section{Keeping it alive}
+
+Under \ui{Advanced}: the \ui{Terminal Type}, the \ui{Keepalive Interval} and \ui{Max Missed Keepalives}, compression,
+and \ui{Auto-Reconnect} with a maximum number of attempts (1–20). Reconnection backs off politely: 1\,s, 2\,s,
+4\,s… up to 30\,s.
+
+\begin{sidequest}[What's that number in the status bar?]
+For SSH sessions the status bar shows live latency, the round trip to the server. Green is snappy. If it's
+in the hundreds and your typing feels sticky, it's the network, not you.
+\end{sidequest}
+
+% =========================================================================================
+\chapter{Serial: cables and consoles}\label{ch:serial}
+\chapmeta{4 minutes}{You'll be talking to a switch, router or microcontroller over USB}
+
+\begin{tldr}
+Plug in the adapter, pick the device, match the baud rate. 115200 8N1 is the default and usually right.
+Right-click the tab to send a break or wiggle DTR/RTS.
+\end{tldr}
+
+\begin{glance}{accent}{Serial}
+  Device       & \code{/dev/ttyUSB0}, \code{/dev/cu.usbserial-…} or \code{COM3}\\
+  Defaults     & 115200 baud, 8 data bits, no parity, 1 stop bit, no flow control, CR line endings, DTR and RTS on\\
+  Extras       & Send Break, toggle DTR/RTS, auto-reconnect when the cable comes back\\
+  Good for     & Network gear consoles, Arduinos, ESP32s, Raspberry Pi UARTs, 3D printers\\
+\end{glance}
+
+\crop{editor-serial.png}{1515}{40}{0}{70}{0.52\linewidth}{A serial profile for a switch console at 9600 baud. Click refresh after plugging in an adapter.}
+
+\section{Setting it up}
+
+\begin{description}
+  \item[Device] Pick it from the list (hit refresh after plugging in) or type the path.
+  \item[Line Settings] \ui{Baud Rate} (a preset from 300 to 1\,000\,000, or \ui{Custom}), \ui{Data Bits} (5–8),
+        \ui{Parity} (none, odd, even), \ui{Stop Bits} (1 or 2) and \ui{Flow Control} (none, XON/XOFF, RTS/CTS).
+  \item[Behaviour] \ui{Line Ending}, \ui{Encoding}, \ui{Local Echo} (for devices that don't echo what you type),
+        \ui{Assert DTR on connect}, \ui{Assert RTS on connect} and \ui{Auto-reconnect}.
+\end{description}
+
+\section{While you're connected}
+
+Right-click the tab for \ui{Send Break} (handy for getting into a router's ROMMON) and to toggle \ui{DTR} and
+\ui{RTS} (handy for resetting boards that wire those to reset). Pull the cable out and the session disconnects; with
+auto-reconnect on, it picks up again when you plug it back in.
+
+Serial tabs are proper terminals, so recording, triggers, broadcast, snippets, find and split panes all work.
+
+\begin{headsup}[Gibberish on screen?]
+Garbled characters nearly always mean the baud rate, parity or stop bits don't match the device. Check the
+device's manual. 9600 and 115200 are the usual suspects.
+\end{headsup}
+
+\begin{protip}[Linux and macOS quirks]
+On Linux, add yourself to the \code{dialout} group (\code{uucp} on some distributions) and log out and in again.
+On a Mac, use the \code{/dev/cu.*} device, not \code{/dev/tty.*}.
+\end{protip}
+
+% =========================================================================================
+\chapter{Telnet and RAW TCP}\label{ch:raw}
+\chapmeta{4 minutes}{You'll poke at old kit and raw sockets without reaching for netcat}
+
+\begin{tldr}
+Telnet is a terminal for old devices. RAW is a packet-level conversation with any TCP port, with a hex view.
+\end{tldr}
+
+\section{Telnet}
+
+\begin{glance}{amber}{Telnet}
+  Default port & 23\\
+  Options      & Local echo, line mode, terminal type, encoding (UTF-8, ASCII, ISO 8859-1), line endings, login script\\
+  Extras       & Send Break from the tab menu, \ui{Debug Negotiation} for when options go wrong\\
+\end{glance}
+
+\begin{danger}[Telnet is plain text]
+Everything, including your password, crosses the network unencrypted. Fine on a lab bench, not fine over the
+internet or café Wi-Fi.
+\end{danger}
+
+\section{RAW TCP}
+
+RAW connects to any TCP port and shows you exactly what goes back and forth. Instead of a terminal you get a
+traffic log with \ui{Text}, \ui{Hex} and \ui{Split} views.
+
+\shot{raw.png}{A RAW session to a chatty sensor, with timestamps and direction markers turned on.}
+
+\begin{itemize}
+  \item \textbf{Send bar:} pick \ui{Text}, \ui{Hex} or \ui{Escaped} (\code{\textbackslash r\textbackslash n} and friends),
+        type, press \kbd{Enter}. One-click buttons send \ui{NUL}, \ui{CR}, \ui{LF}, \ui{ETX} and \ui{EOT}.
+  \item \textbf{Presets:} save payloads you send often in the profile under \ui{Payload Presets}, then pick them from
+        \ui{Presets…}.
+  \item \textbf{Capture:} \ui{Pause}, \ui{Clear}, and \ui{Save} (writes the whole conversation as JSON).
+  \item \textbf{Profile options:} encoding (UTF-8, ASCII, Hex), line ending, timestamps, direction, timeouts and
+        auto-reconnect.
+\end{itemize}
+
+\begin{quickwin}
+Point a RAW profile at a web server on port 80 and send \code{HEAD / HTTP/1.0\textbackslash r\textbackslash n\textbackslash r\textbackslash n}
+in \ui{Escaped} mode. Instant HTTP headers, no browser required.
+\end{quickwin}
+
+% =========================================================================================
+\chapter{VNC remote desktops}\label{ch:vnc}
+\chapmeta{4 minutes}{You'll see and drive a remote desktop, safely}
+
+\begin{tldr}
+VNC shows you another computer's screen. Tunnel it through SSH (tick a box), because plain VNC isn't encrypted.
+\end{tldr}
+
+\begin{glance}{rose}{VNC}
+  Default port & 5900 (plus the display number: display \code{:1} is 5901)\\
+  Display      & \ui{View Only}, \ui{Scale to Fit}, \ui{Shared Session}, \ui{Quality (0-9)}\\
+  Security     & Optional SSH tunnel with password, key or agent login\\
+\end{glance}
+
+\shot{vnc.png}{A remote desktop, scaled to fit the tab.}
+
+\section{The toolbar}
+
+Connection state and desktop size on the left. On the right: switch between scaled and 1:1, refresh,
+\ui{Paste Clipboard} (sends your clipboard to the remote machine) and \ui{Ctrl+Alt+Del}. Click the desktop to give
+it your keyboard. Anything the remote machine copies lands on your clipboard automatically.
+
+\section{Tunnel it}
+
+Tick \ui{Enable SSH Tunnel} and fill in the SSH host, port, username and login method. The VNC traffic then
+travels inside an encrypted SSH connection. If you connect to a VNC profile \emph{without} a tunnel, Nexus Terminal
+warns you and offers \ui{Connect Anyway}, \ui{Edit Profile} or \ui{Cancel}.
+
+\begin{headsup}[Connecting to a Mac?]
+Turn on \ui{VNC viewers may control screen with password} in macOS Screen Sharing settings. Nexus Terminal uses
+standard VNC password authentication, not Apple's own login method.
+\end{headsup}
+
+% =========================================================================================
+\chapter{RDP: Windows desktops}\label{ch:rdp}
+\chapmeta{4 minutes}{You'll be on a Windows (or xrdp) desktop without leaving Nexus Terminal}
+
+\begin{tldr}
+Host, username, password. Nexus Terminal logs on with NLA, pins the server's certificate like an SSH host key, and
+can go through a proxy, an SSH tunnel or an RD Gateway.
+\end{tldr}
+
+\begin{glance}{rose}{RDP}
+  Default port & 3389\\
+  Logs in with & NLA (NTLM, or Kerberos with a KDC); \ui{Allow servers without NLA} for xrdp\\
+  Display      & \ui{Scale to Fit}, fixed size, \ui{Resize With Tab}\\
+  Extras       & Clipboard both ways, remote audio, printer, shared folder\\
+  Getting there & SOCKS5 or HTTP proxy, SSH tunnel, RD Gateway (experimental)\\
+\end{glance}
+
+\shot{rdp.png}{An xrdp desktop in a tab. Ctrl+Alt+Del and Paste Clipboard sit on the toolbar.}
+
+\section{Setting it up}
+
+\begin{enumerate}
+  \item \keys{\mod+N}, protocol \proto[rose]{RDP}.
+  \item \ui{Host} and \ui{Username}; add a \ui{Domain} if your account has one.
+  \item Pick how the password is kept (save it, remember it until you quit, or ask every time).
+  \item \ui{Create \& Connect}. The first time, you're shown the server's certificate fingerprint. Accept it if
+        it's the machine you meant.
+\end{enumerate}
+
+Windows checks your password \emph{before} it builds a desktop (Network Level Authentication), so a typo fails fast.
+Linux machines running xrdp don't speak NLA: tick \ui{Allow servers without NLA} for those. In an Active Directory
+shop, set a \ui{Kerberos KDC} (\code{host} or \code{host:port}) and use your realm as the domain.
+
+\begin{headsup}[A changed certificate]
+RDP servers mostly use self-signed certificates, so Nexus Terminal remembers the fingerprint in
+\ui{Known Hosts}. If it changes you get \ui{Reject}, \ui{Accept Once} or \ui{Accept \& Update}, and nothing (not even your
+password) is sent until you choose.
+\end{headsup}
+
+\section{While you're connected}
+
+It works like the VNC viewer: click the desktop to give it your keyboard, \ui{Ctrl+Alt+Del} sends exactly that, and
+text you copy on either side turns up on the other. With \ui{Resize With Tab} the remote desktop follows the tab's
+size (Windows does this; other servers are scaled).
+
+Under \ui{Devices}: \ui{Play Remote Audio}; \ui{Redirect Printer}, which adds a \emph{Nexus Terminal} printer whose jobs
+land as PostScript files in your Downloads folder; and (Linux and macOS) a \ui{Shared Folder} that shows up remotely as
+a drive called Nexus. The server can read and change that folder, and nothing outside it.
+
+\section{Getting through}
+
+Pick \emph{one} of: a \ui{Proxy} (SOCKS5 or HTTP CONNECT), an \ui{SSH Tunnel} (same as VNC), or an \ui{RD Gateway}
+(experimental: the gateway needs a proper public certificate and Basic authentication over HTTPS).
+
+% =========================================================================================
+\chapter{IRC}\label{ch:irc}
+\chapmeta{3 minutes}{You'll be chatting in your project's channels from the same window as your servers}
+
+\begin{tldr}
+Nick, server, rooms to join. Tabs for each room, \code{/commands} as you'd expect, \kbd{Tab} completes nicks.
+\end{tldr}
+
+\begin{glance}{amber}{IRC}
+  Default port & 6667, or 6697 with \ui{Use TLS} (use TLS!)\\
+  Logs in with & SASL PLAIN (most networks want this now), or NickServ identify\\
+  Extras       & Auto-join rooms, room browser, real message times (IRCv3 server-time), SSH tunnel\\
+\end{glance}
+
+\shot{irc.png}{Chatting in \#nexus. Rooms down the right, users in the room below them.}
+
+\begin{itemize}
+  \item A \ui{Server} tab plus one per room or private conversation. A dot means unread messages.
+  \item Commands: \code{/join}, \code{/part}, \code{/msg}, \code{/me}, \code{/notice}, \code{/nick}, \code{/topic},
+        \code{/list}, \code{/names}, \code{/whois}, \code{/who}, \code{/raw}, \code{/quit} and \code{/help}.
+  \item \kbd{Tab} completes a nick; click a nick to mention them.
+  \item The side panel lists your rooms, a room browser with a filter (click to join) and who's in the current room.
+\end{itemize}
+
+% =========================================================================================
+\chapter{GitHub}\label{ch:github}
+\chapmeta{2 minutes}{You'll see all your repositories, freshest first}
+
+\crop{editor-github.png}{1515}{780}{0}{70}{0.5\linewidth}{A GitHub profile: just the API address and a token.}
+
+\begin{tldr}
+Paste a personal access token with the \code{repo} scope. Get a tidy, filterable list of every repository you can see.
+\end{tldr}
+
+\shot{github.png}{Repositories grouped by owner, with the latest commit and who made it.}
+
+\begin{itemize}
+  \item Grouped by owner or organisation, sorted by most recent activity.
+  \item Badges for \proto[rose]{Private}, \proto[violet]{Fork} and \proto[amber]{Archived}, plus language and stars.
+  \item Filter box, \ui{Refresh now}, \ui{Visit} (opens in your browser) and \ui{ZIP} (downloads an archive).
+  \item Works with GitHub Enterprise: set \ui{API Base URL} to your server's API address. Refreshes every 60–3600 seconds.
+\end{itemize}
+
+% =========================================================================================
+\chapter{Your own computer}\label{ch:local}
+\chapmeta{1 minute}{You'll stop alt-tabbing to a separate terminal app}
+
+Click \ui{Local Machine} for a shell on this computer. It uses your system's default shell unless you choose
+another in \menu{Settings\then General\then Local shell} (\code{pwsh}, \code{zsh}, \code{fish}, whatever you fancy).
+
+\shot[0.86\linewidth]{local.png}{A local shell, with all the same terminal powers as SSH.}

docs/guide/chapters/part3-faster.tex

@@ -0,0 +1,264 @@
+\guidepart{violet}{Work faster}{Work faster}
+  {Fewer clicks, less typing, more getting on with it.}
+  {\partitem{\iSplit}{Tabs and split panes}
+   \partitem{\iKeyboard}{Terminal superpowers}
+   \partitem{\iWand}{Never type it twice}
+   \partitem{\iFolder}{Files: SFTP and drag-and-drop}
+   \partitem{\iArrows}{Port forwards}
+   \partitem{\iFilm}{Recordings}}
+
+% =========================================================================================
+\chapter{Tabs and split panes}\label{ch:tabs}
+\chapmeta{4 minutes}{You'll juggle a dozen sessions without losing any of them}
+
+\begin{tldr}
+Right-click a tab for everything. \keys{\mod+Shift+D} splits right, \keys{\mod+Shift+E} splits down.
+\keys{\mod+1} to \keys{\mod+9} jump straight to a tab.
+\end{tldr}
+
+\section{Tabs}
+
+\begin{description}
+  \item[Move] Drag tabs about, or right-click\then\ui{Move Left} / \ui{Move Right}.
+  \item[Pin] Right-click\then\ui{Pin}. Pinned tabs stay at the front.
+  \item[Rename] Right-click\then\ui{Rename}. ``prod DB, DON'T TOUCH'' is a perfectly valid tab name.
+  \item[Duplicate] Opens another session to the same profile.
+  \item[Reconnect] Does what it says.
+  \item[Peek] Hover a tab for its name, host, state and when it connected.
+  \item[Close] The \ui{×}, \keys{\mod+W}, or right-click\then\ui{Close}. Connected tabs ask first (you can turn that
+        off in Settings).
+  \item[Switch] \keys{\mod+Tab} and \keys{\mod+Shift+Tab}, or \keys{\mod+1} to \keys{\mod+9}.
+\end{description}
+
+Lots of tabs? Scroll the tab strip with your mouse wheel or trackpad. Quit with a dozen open and they're all back next
+time: \ui{Restore tabs at launch} (on by default) reconnects saved profiles and reopens local shells, splits and all,
+in the folder they were in.
+
+\section{Split panes}
+
+Want two sessions side by side? Split the focused pane right with \keys{\mod+Shift+D} or down with
+\keys{\mod+Shift+E} (also in the \menu{Session} menu, the right-click menu and the palette). The new pane asks
+what to open: \ui{Local Machine} or any of your terminal profiles.
+
+\shot{split.png}{A fresh split. Pick what goes in the new pane.}
+
+Drag a divider to resize. Click \ui{×} on a pane's header to close it and its neighbour takes the space. Closing
+the tab closes every pane in it.
+
+\begin{quickwin}
+Split right, open \code{htop} on one side and tail a log on the other. Now you look like a hacker in a film.
+\end{quickwin}
+
+% =========================================================================================
+\chapter{Terminal superpowers}\label{ch:terminal}
+\chapmeta{4 minutes}{You'll copy, search and scroll like you've used it for years}
+
+\begin{tldr}
+Select to copy, \keys{\mod+F} to search, Ctrl/\ph{E1C4}-click links. Right-click for the rest.
+\end{tldr}
+
+\section{Keyboard and mouse}
+
+\renewcommand\arraystretch{1.45}
+\begin{tabularx}{\linewidth}{@{}>{\leavevmode\heavy\color{ink}}p{24mm}X@{}}
+  \toprule
+  Copy   & Select text, then \keys{\mod+C}. Nothing selected? \keys{Ctrl+C} interrupts the program as usual.\\
+  Paste  & \keys{\mod+V}. Pastes are bracketed when the program asks for it, so editors won't auto-indent your paste
+           into a staircase. Pasting several lines into a shell asks first (turn that off in Settings).\\
+  Select & Drag for a range, double-click a word, triple-click a line, \kbd{Shift}-click to extend.\\
+  Links  & Hold \kbd{Ctrl} (\kbd{\ph{E1C4}}) and click a URL to open it in your browser. Real hyperlinks that
+           programs print (\code{ls --hyperlink}, compilers) get a dotted underline; hover to see where they really go.\\
+  Scroll & Mouse wheel, or \keys{Shift+PageUp}, \keys{Shift+PageDown}, \keys{Shift+Home}, \keys{Shift+End}.\\
+  \bottomrule
+\end{tabularx}
+
+\begin{sidequest}[Why does the scroll wheel move the cursor in less?]
+Full-screen programs (\code{less}, \code{vim}, \code{tmux}, \code{byobu}) use the terminal's ``alternate screen'', where the
+wheel sends arrow keys instead of scrolling. Programs with mouse support (\code{htop}, \code{vim} with
+\code{mouse=a}, \code{tmux} mouse mode) get your clicks directly. That's normal terminal behaviour, not a bug.
+\end{sidequest}
+
+\section{The right-click menu}
+
+\ui{Copy}, \ui{Paste}, \ui{Select All}, \ui{Find}, \ui{Previous Prompt} / \ui{Next Prompt}, \ui{Copy Last Command
+Output}, \ui{Send Snippet}, \ui{Port Forwards} (SSH), \ui{Split Right}, \ui{Split Down}, \ui{Export Output} (saves the
+whole scrollback as a text file), \ui{Clear} and \ui{Reset}.
+
+\section{Shell integration}
+
+If your shell marks its prompts (fish 4, Starship and Powerlevel10k do already), Nexus Terminal knows where every
+command starts and stops. \keys{\mod+Shift+Up} and \keys{\mod+Shift+Down} jump from prompt to prompt,
+\ui{Copy Last Command Output} grabs just what the last command printed, and a thin bar beside each prompt shows how it
+went: green for success, red for failure. Hover the bar for the exit code and how long it took.
+
+\shot{shell-integration.png}{\code{make test} failed (red bar), \code{ls} worked (green bar).}
+
+For bash, add this to \code{\textasciitilde/.bashrc} on the machine the shell runs on (the user manual has the zsh
+version):
+
+\begin{verbatim}
+PS0='\[\e]133;C\a\]'
+PROMPT_COMMAND='printf "\033]133;D;%s\007" "$?"; '"${PROMPT_COMMAND}"
+PS1='\[\e]133;A\a\]'"$PS1"'\[\e]133;B\a\]'
+\end{verbatim}
+
+\section{Pictures in the terminal}
+
+Programs that print images the iTerm2 way (\code{imgcat}, \code{wezterm imgcat}, \code{chafa -f iterm}) show PNG,
+JPEG and GIF images right in the scrollback. They scroll with the text and never spill past the edge.
+
+\shot{inline-image.png}{An image printed by a script, with the text carrying on underneath.}
+
+\section{Find}
+
+\keys{\mod+F} opens the find bar. Toggle \ui{Aa} for case-sensitive and \ui{.*} for regular expressions.
+\kbd{Enter} for the next match, \keys{Shift+Enter} for the previous one, \kbd{Esc} to close. It shows
+``3 of 17'' so you know where you are.
+
+\section{When the connection drops}
+
+The pane dims and shows a \ui{Disconnected} card with \ui{Reconnect} and \ui{Close}. If auto-reconnect is on,
+it says \ui{Reconnecting…} with a \ui{Cancel} button, and a toast tells you which attempt it's on.
+
+If the problem was a password or host key, you get a friendly dialog explaining what happened, with
+\ui{Retry}, \ui{Edit Profile}, \ui{Known Hosts} (for host-key trouble) and \ui{Close}.
+
+% =========================================================================================
+\chapter{Never type it twice}\label{ch:repeat}
+\chapmeta{6 minutes}{You'll stop retyping the same commands, and let Nexus Terminal watch the logs for you}
+
+\begin{tldr}
+\textbf{Snippets} store commands. \textbf{Broadcast} types into many sessions at once. \textbf{Triggers} watch output and
+tap you on the shoulder.
+\end{tldr}
+
+\section{Snippets: \keys{\mod+Shift+S}}
+
+Save commands you use a lot, with a name, description and folder. Search them, click
+\ui{Send to Session}, and the command is typed into the active session followed by \kbd{Enter}.
+
+\crop{snippets.png}{633}{384}{611}{402}{0.8\linewidth}{The snippet library, organised into folders.}
+
+Snippets can have blanks to fill in:
+
+\begin{itemize}
+  \item \code{\{\{hostname\}\}}, \code{\{\{date\}\}}, \code{\{\{time\}\}} and \code{\{\{timestamp\}\}} are filled in for you.
+  \item Anything else, like \code{\{\{service\}\}}, is asked for when you send it.
+\end{itemize}
+
+So \code{journalctl -fu \{\{service\}\}} asks ``service?'' and tails whichever one you type.
+
+\section{Broadcast: \keys{\mod+Shift+B}}
+
+Turn broadcast on and everything you type goes to \emph{every} connected terminal. The status bar shows
+\ui{BROADCAST} so you can't forget it's on.
+
+\shot{broadcast.png}{Broadcast is on: the status bar says so in no uncertain terms.}
+
+To broadcast to only some sessions, right-click the \iBroadcast{} button (or \menu{Session\then Broadcast
+targets…}), tick the ones you want and click \ui{Apply \& Enable}.
+
+\begin{danger}[With great power…]
+Broadcast doesn't care which tab you \emph{meant}. Double-check the target list before you type anything
+destructive. \code{sudo reboot} into twenty servers is very efficient and very memorable.
+\end{danger}
+
+\section{Triggers: let it watch for you}
+
+\menu{Session\then Trigger Rules} (or the palette). Each rule has a pattern (plain text or a regular
+expression), a case-sensitivity switch, an on/off switch, and an action:
+
+\begin{center}\small
+\begin{tabular}{@{}ll@{}}
+  \ui{Notify} & shows a toast\\
+  \ui{Highlight tab} & briefly outlines the pane\\
+  \ui{Notify + Highlight} & both\\
+  \ui{Sound} & asks your OS for attention (a bouncing dock icon or flashing taskbar button) and shows a toast\\
+\end{tabular}
+\end{center}
+
+\crop{triggers.png}{725}{610}{725}{625}{0.75\linewidth}{Three rules: shout about errors, ping when a build finishes, and one switched off for now.}
+
+Rules check each complete line of output, with colours stripped out first.
+
+\begin{quickwin}
+Add a rule for \code{BUILD SUCCESSFUL} with the \ui{Sound} action, start a long build, and go and make a cup of tea.
+Nexus Terminal will tell you when it's done. (Or \code{(?i)error|fatal} for the opposite.)
+\end{quickwin}
+
+% =========================================================================================
+\chapter{Files: SFTP and drag-and-drop}\label{ch:files}
+\chapmeta{4 minutes}{You'll move files to and from servers without leaving the terminal}
+
+\begin{tldr}
+Click the \iFolder{} on an SSH tab. Or drop a file onto the terminal and choose \ui{Upload}.
+\end{tldr}
+
+\section{The SFTP browser}
+
+Click the \iFolder{} folder icon on an SSH tab, \menu{Session\then SFTP browser}, or type ``sftp'' in the palette.
+It opens in the side dock next to your terminal, in the folder your shell is in if the shell reports it
+(fish does; bash and zsh need a one-line hook, see the user manual).
+
+\shot{sftp.png}{Browsing the server's files next to the terminal.}
+
+\begin{itemize}
+  \item Move around with the breadcrumb trail, the \code{..} entry or \ui{Go to path}.
+  \item Upload files; download one or many to a folder you choose.
+  \item Rename, delete (it asks first), make folders, refresh.
+  \item \iStar{} bookmarks the current folder, per profile.
+  \item Ctrl-click (\ph{E1C4}-click) or Shift-click to select several things. Transfers show progress as they go.
+\end{itemize}
+
+\section{Drag and drop}
+
+Drop files onto a terminal and choose:
+
+\begin{description}
+  \item[Upload to current directory] Pick the remote folder (SSH only).
+  \item[Paste contents] Types the file's contents into the terminal, as if you'd typed it.
+\end{description}
+
+The upload picker looks like the SFTP browser but shows folders only, labelled \proto[amber]{READ ONLY} if you can't
+write there and \proto[rose]{NO READ} if you can't look inside. Keyboard fans: \kbd{↑}\kbd{↓} to move, \kbd{Enter} to
+choose, \kbd{Backspace} to go up, \kbd{Esc} to cancel. If the SFTP browser is open, the picker starts in the same folder.
+
+% =========================================================================================
+\chapter{Port forwards}\label{ch:forwards}
+\chapmeta{3 minutes}{You'll reach a database or web app that only listens on the server}
+
+\begin{tldr}
+\emph{Local} forwards bring a remote port to your machine. \emph{Remote} forwards do the opposite.
+\end{tldr}
+
+Forwards saved in an SSH profile (under \ui{Port Forwarding}, with \ui{Active} ticked) start when you connect.
+To manage them on a live session, right-click the terminal\then\ui{Port Forwards}, or \menu{Session\then Port forwards}.
+
+\begin{description}
+  \item[Local \iArrow] Listen on your computer, forward to somewhere the server can reach.
+        Example: \code{127.0.0.1:15432}\then\code{127.0.0.1:5432} lets your desktop database app talk to Postgres on
+        the server as if it were local.
+  \item[Remote \ph{E058}] Ask the server to listen and send connections back to somewhere \emph{your} computer can reach.
+        Great for showing a colleague the dev server running on your laptop.
+\end{description}
+
+Active forwards are listed with an \proto[accent]{L} or \proto[violet]{R} badge and a stop button. Toasts tell you when one
+starts, stops or fails.
+
+% =========================================================================================
+\chapter{Recordings}\label{ch:recordings}
+\chapmeta{2 minutes}{You'll have a replayable record of exactly what happened}
+
+\keys{\mod+Shift+R} starts and stops recording the active session. A red dot appears on the tab and \ui{REC} in
+the status bar. Recordings are standard asciicast v2 files, so other tools (like \code{asciinema}) can play them too.
+
+\crop{recordings.png}{712}{392}{690}{415}{0.75\linewidth}{The recordings browser. Play, delete, or tidy up in bulk.}
+
+The browser (sidebar footer, \menu{Session} menu or palette) shows how many recordings you have and how much space
+they take. Play or delete each one, or use \ui{Clean up} to remove recordings older than 7, 30 or 90 days, or to keep
+the total under 1\,GB or 5\,GB. Playback has play/pause, restart, a seek bar and speed control.
+
+\begin{protip}
+Record the next time you do something fiddly and rare (a database failover, a certificate rotation). Six months
+later, ``how did we do that again?'' has an answer you can literally watch.
+\end{protip}

docs/guide/chapters/part4-safe.tex

@@ -0,0 +1,139 @@
+\guidepart{amber}{Stay safe}{Stay safe}
+  {Passwords, keys and host checks, minus the jargon headache.}
+  {\partitem{\iLock}{Passwords and the vault}
+   \partitem{\iShield}{Host keys: is it really that server?}
+   \partitem{\iKey}{SSH keys}}
+
+% =========================================================================================
+\chapter{Passwords and the vault}\label{ch:secrets}
+\chapmeta{5 minutes}{You'll know exactly where your passwords live and who can read them}
+
+\begin{tldr}
+Passwords go in your OS keychain. If there isn't one, they go in an encrypted vault protected by a master password.
+For each password you choose: save it, remember it until you quit, or ask every time.
+\end{tldr}
+
+\section{Where secrets live}
+
+\begin{center}
+\begin{tikzpicture}[
+  box/.style={rounded corners=6pt, fill=#1!12, draw=#1!60, line width=0.6pt, minimum height=13mm, text width=40mm,
+    align=center, font=\small},
+  arr/.style={-latex, line width=0.8pt, color=muted}]
+  \node[box=accent] (need) {\heavy A session needs\\a password};
+  \node[box=green, right=12mm of need] (kc) {\heavy OS keychain\\{\footnotesize Keychain · Credential Manager · Secret Service}};
+  \node[box=amber, right=12mm of kc] (vault) {\heavy Encrypted vault\\{\footnotesize AES-256-GCM, Argon2id}};
+  \node[box=rose, below=9mm of kc] (ask) {\heavy Ask you\\{\footnotesize then carry on}};
+  \draw[arr] (need) -- (kc);
+  \draw[arr] (kc) -- node[above, font=\scriptsize]{not there?} (vault);
+  \draw[arr] (vault) |- node[pos=0.25, right, font=\scriptsize]{still not there?} (ask);
+\end{tikzpicture}
+\end{center}
+
+\begin{description}
+  \item[OS keychain first] macOS Keychain, Windows Credential Manager, or the Linux Secret Service (GNOME Keyring,
+        KWallet and friends).
+  \item[Encrypted vault as backup] If there's no keychain, or it refuses, secrets go into Nexus Terminal's own
+        vault: AES-256-GCM with a key derived from your master password by Argon2id using 128\,MiB of memory. In
+        plain English: very, very expensive to brute-force.
+\end{description}
+
+\section{Setting up the vault}
+
+\menu{Settings\then Security\then Initialise Secret Store}. Choose a master password; the strength meter goes from
+\proto[rose]{Weak} through \proto[amber]{Fair} and \proto[accent]{Good} to \proto[green]{Strong}. Unlock and lock it
+from the same page, from the palette, or by clicking the vault badge in the status bar. It locks itself when you quit.
+
+\crop{settings-security.png}{581}{253}{576}{285}{0.8\linewidth}{Security settings on a machine without an OS keychain: the vault does the job instead.}
+
+\begin{danger}[There's no ``forgot password'' link]
+Lose the master password and the secrets in the vault are gone for good. That's the point of encryption. Put it in
+your password manager.
+\end{danger}
+
+\section{Three ways to handle each password}
+
+Every password, passphrase, token or TOTP secret has its own setting:
+
+\begin{center}
+\begin{tabular}{@{}p{0.3\linewidth}p{0.3\linewidth}p{0.3\linewidth}@{}}
+  \begin{tcolorbox}[colback=green!8, boxrule=0pt, arc=6pt, fontupper=\small, height=33mm]
+    {\heavy\color{green!60!black}\iLock\ Save securely}\par\smallskip Stored in the keychain or vault and used automatically. Most convenient.
+  \end{tcolorbox} &
+  \begin{tcolorbox}[colback=accent!8, boxrule=0pt, arc=6pt, fontupper=\small, height=33mm]
+    {\heavy\color{accent!80!black}\iClock\ Remember for this session}\par\smallskip Asked once, kept in memory, never written to disk.
+  \end{tcolorbox} &
+  \begin{tcolorbox}[colback=amber!10, boxrule=0pt, arc=6pt, fontupper=\small, height=33mm]
+    {\heavy\color{amber!75!black}\iDetective\ Ask every time}\par\smallskip Asked on every single connection. Most paranoid.
+  \end{tcolorbox}
+\end{tabular}
+\end{center}
+
+When Nexus Terminal needs a secret it doesn't have, it asks. Press \kbd{Esc} or \ui{Cancel} to give up on that
+connection.
+
+\section{Seeing and changing what's saved}
+
+\ui{Stored credentials} on the Security page lists every saved password, passphrase and token by profile, and whether
+it's in the keychain or the vault. \ui{Forget} deletes one. \ui{Change Master Password…} re-encrypts the whole vault
+under a new password in one go.
+
+\begin{sidequest}[What gets written down?]
+Connections, disconnections, profile changes, credential access, imports and exports go into an audit log in the
+database. Secrets themselves never do. TOTP secrets live in the keychain or vault too, never in the profile.
+\end{sidequest}
+
+% =========================================================================================
+\chapter{Host keys: is it really that server?}\label{ch:hostkeys}
+\chapmeta{3 minutes}{You'll understand the scary fingerprint dialog and what to do about it}
+
+\begin{tldr}
+Every SSH server (and every RDP server, via its certificate) has a fingerprint. Nexus Terminal remembers it the first time and shouts if it ever changes.
+A changed fingerprint means a reinstalled server, or someone in the middle. Find out which before carrying on.
+\end{tldr}
+
+Pick a policy per SSH profile under \ui{Host Verification}:
+
+\renewcommand\arraystretch{1.5}
+\begin{tabularx}{\linewidth}{@{}>{\leavevmode\heavy\color{ink}}p{48mm}X@{}}
+  \toprule
+  Strict (known hosts only)   & Only connects to servers you've already trusted.\\
+  Ask on new or changed keys  & Shows the fingerprint and asks. New: \ui{Accept \& Save} or \ui{Reject}. Changed:
+                                \ui{Reject}, \ui{Accept Once} or \ui{Accept \& Update}. The default.\\
+  Accept new, reject changed  & Trusts first-time servers silently, still refuses changed keys.\\
+  Insecure (accept anything)  & Exactly what it says. Lab use only.\\
+  \bottomrule
+\end{tabularx}
+
+Under \emph{Strict} and \emph{Accept new}, a key that differs from the saved one is rejected outright.
+
+\crop{settings-knownhosts.png}{581}{253}{576}{285}{0.8\linewidth}{Known hosts. Click a fingerprint to copy it; \ui{Remove} to forget a server.}
+
+\begin{quickwin}
+Nexus Terminal keeps its own list, but \ui{Import \textasciitilde/.ssh/known\_hosts} brings in everything your
+command-line \code{ssh} already trusts (hashed names can't be read back, so those are skipped). \ui{Export…} goes the
+other way, in OpenSSH format.
+\end{quickwin}
+
+\section{Certificate authorities}
+
+Big estates sign host keys with an SSH certificate authority instead of handing out fingerprints. \ui{Trust a CA…}
+adds the CA's public key for a host pattern in OpenSSH style (\code{*.corp.example}, \code{[jump.example]:2222},
+\code{!old.corp.example}); \code{@cert-authority} lines in an imported \code{known\_hosts} do the same. A server the CA
+covers must then show a certificate the CA signed, naming that host and in date. It's trusted without a prompt, and
+anything else is refused.
+
+% =========================================================================================
+\chapter{SSH keys}\label{ch:keys}
+\chapmeta{2 minutes}{You'll have a key pair without memorising ssh-keygen flags}
+
+\menu{Session\then SSH key manager} (or the palette) lists the key pairs in \code{\textasciitilde/.ssh} with their type. Copy a
+public key to the clipboard (ready to paste into GitHub or \code{authorized\_keys}), delete a pair, or generate a new
+\proto[teal]{Ed25519}, \proto[accent]{RSA} (2048 or 4096 bits) or \proto[violet]{ECDSA} key with an optional passphrase.
+
+\crop{keys.png}{725}{523}{725}{546}{0.75\linewidth}{The SSH key manager.}
+
+\begin{protip}
+Not sure which type? Pick Ed25519. It's small, fast and secure. Keys are generated inside Nexus Terminal and
+saved in the usual OpenSSH format, so \code{ssh} and \code{git} can use them too.
+\end{protip}

docs/guide/chapters/part5-yours.tex

@@ -0,0 +1,124 @@
+\guidepart{pink}{Make it yours}{Make it yours}
+  {Settings, backups, and keeping several computers in step.}
+  {\partitem{\iGear}{Settings}
+   \partitem{\iUpload}{Import and export}
+   \partitem{\iPlane}{Moving house}}
+
+% =========================================================================================
+\chapter{Settings}\label{ch:settings}
+\chapmeta{3 minutes}{You'll know where every setting lives}
+
+\keys{\mod+,} opens settings (also the \iGear{} in the sidebar footer and \menu{File\then Settings}). Change things,
+then click \ui{Save}.
+
+\begin{center}\begin{minipage}[t]{0.49\linewidth}\crop{settings-general.png}{581}{253}{576}{285}{\linewidth}{General}\end{minipage}\hfill\begin{minipage}[t]{0.49\linewidth}\crop{settings-terminal.png}{581}{253}{576}{285}{\linewidth}{Terminal}\end{minipage}\end{center}
+
+\begin{description}
+  \item[General] App theme (Pro, Midnight, Light), default protocol for new profiles, \ui{Restore tabs at launch}
+        (saved connections reconnect, local shells reopen in the folder they were in), whether to ask before closing or
+        disconnecting, whether remote programs may write to your clipboard, a confirmation before pasting several lines,
+        the update check, status bar, sidebar width, and the local shell (empty for the system default, or
+        \ui{Browse…}).
+  \item[Terminal] Colour scheme, font, size, scrollback and cursor style. These are the defaults for new profiles;
+        each profile can override them.
+  \item[Security] Keychain and vault status; set up, unlock or lock the vault; change the master password; your
+        stored credentials; profile sync.
+  \item[Known Hosts] Saved server fingerprints, with first-seen and last-seen times; import and export
+        \code{known\_hosts}; trusted SSH certificate authorities.
+  \item[Diagnostics] Version, platform, where your data and log live, and the state of the keychain, vault and sync.
+        \ui{Copy Diagnostics} for bug reports (never includes credentials).
+  \item[Help] Built-in help: connection types, shortcuts and troubleshooting, when this guide isn't to hand.
+  \item[About] Version, \ui{Check for Updates} and \ui{Import \textasciitilde/.ssh/config}.
+\end{description}
+
+\crop{settings-diagnostics.png}{604}{600}{604}{20}{0.8\linewidth}{Diagnostics: everything a bug report needs, nothing secret.}
+
+\section{Updates}
+
+Nexus Terminal checks once at launch. If there's a newer version the status bar says \ui{Update available}; click it to
+see the release notes and a \ui{View release} button. Nothing downloads or installs behind your back.
+
+% =========================================================================================
+\chapter{Import and export}\label{ch:transfer}
+\chapmeta{3 minutes}{You'll back up your profiles, or copy them to another computer}
+
+\begin{tldr}
+\menu{File\then Export profiles…} makes a password-protected \code{.nexus} file. \menu{File\then Import profiles…}
+reads it back. Already have an \code{\textasciitilde/.ssh/config}? Import that too.
+\end{tldr}
+
+\begin{description}
+  \item[Encrypted export] Choose the profiles, set a password, save a \code{.nexus} file. Saved passwords aren't
+        included, so the file is safe to email to yourself.
+  \item[Encrypted import] Pick a \code{.nexus} file, enter its password and decide what happens to
+        profiles that already exist: \ui{Skip existing}, \ui{Overwrite existing} or \ui{Create duplicates}.
+  \item[JSON] \ui{Export Profiles (JSON)} and \ui{Import Profiles (JSON)} are in the palette. Tick
+        \ui{Include secrets} to keep passwords typed by login scripts, which are otherwise blanked. Proxy passwords and
+        TOTP secrets live in the keychain or vault, so no export carries them.
+  \item[OpenSSH config] \menu{File\then Import \textasciitilde/.ssh/config} turns your \code{Host} blocks into profiles,
+        with host names, users, ports, identity files and jump hosts.
+\end{description}
+
+\crop{export.png}{906}{388}{904}{390}{0.55\linewidth}{Exporting profiles. Everything's ticked to start with; untick what you don't want.}
+
+\begin{danger}[JSON with secrets is not encrypted]
+A JSON export with \ui{Include secrets} ticked has those login-script passwords in plain text. Use the encrypted \code{.nexus} export to
+move things between machines.
+\end{danger}
+
+% =========================================================================================
+\chapter{Moving house}\label{ch:move}
+\chapmeta{3 minutes}{Your connections will follow you from laptop to desktop to work machine}
+
+\begin{tldr}
+Pick a folder every machine can see, set the same sync password on each, done. Profiles stay in step; passwords
+stay put on each machine.
+\end{tldr}
+
+\section{Profile sync}
+
+\menu{Settings\then Security\then Profile sync}. \ui{Choose…} a folder your machines share (Dropbox, iCloud Drive,
+OneDrive, Nextcloud, a network share, or a git checkout you commit) and set the same \ui{Sync password} everywhere.
+Nexus Terminal keeps one encrypted file there, \code{nexus-profiles.nexus}, and merges it at launch, a few seconds
+after you change a profile, every ten minutes and whenever you click \ui{Sync Now}.
+
+\begin{checklist}
+  \item[\color{green}\iCheck] Edited on two machines? The newer change wins, profile by profile.
+  \item[\color{green}\iCheck] Deleted on one machine? It goes from the others too (unless someone edited it afterwards).
+  \item[\color{rose}\ph{E4F6}] Saved passwords, keys and tokens never sync. Each machine keeps its own in its keychain or vault.
+        (Anything a login script \emph{sends} is part of the profile, so that does travel.)
+\end{checklist}
+
+\crop{settings-security.png}{581}{253}{576}{285}{0.8\linewidth}{Profile sync lives on the Security page, under your stored credentials.}
+
+\begin{headsup}
+Lose the sync password and the sync file can't be read, just like an encrypted export. Your local profiles are
+fine.
+\end{headsup}
+
+\section{One-off moves}
+
+Not worth setting up sync? \menu{File\then Export profiles…} on the old machine, \menu{File\then Import profiles…}
+on the new one (see \hyperref[ch:transfer]{Import and export}). Known hosts travel the same way through
+\ui{Export…} and \ui{Import} on the Known Hosts page.
+
+\section{Where everything lives}
+
+\renewcommand\arraystretch{1.45}
+\begin{tabularx}{\linewidth}{@{}>{\leavevmode\heavy\color{ink}}p{20mm}X@{}}
+  \toprule
+  macOS   & \code{\textasciitilde/Library/Application Support/NexusTerminal}\\
+  Windows & \code{\%APPDATA\%\textbackslash NexusTerminal}\\
+  Linux   & \code{\$XDG\_CONFIG\_HOME/NexusTerminal}, usually \code{\textasciitilde/.config/NexusTerminal}\\
+  \bottomrule
+\end{tabularx}
+
+Inside: \code{nexus.db} (profiles, known hosts, preferences, snippets, IRC state and the audit log),
+\code{vault/vault.json}, \code{recordings/}, \code{triggers.json}, \code{sftp-bookmarks.json} and \code{nexus.log}, the
+diagnostic log. Keychain entries are
+stored under the service name \code{NexusTerminal}.
+
+\begin{protip}[Try things without touching your real data]
+Start Nexus Terminal with \code{--data-dir /some/other/folder} and it uses that folder instead. Brilliant for
+experiments, demos and a portable install on a USB stick.
+\end{protip}

docs/guide/chapters/part6-fix.tex

@@ -0,0 +1,106 @@
+\guidepart{rose}{Fix it}{When things go wrong}
+  {Symptom first, fix second. No essays.}
+  {\partitem{\iLifebuoy}{Troubleshooting, by symptom}}
+\label{part:fix}
+
+% =========================================================================================
+\chapter{Troubleshooting, by symptom}\label{ch:trouble}
+\chapmeta{as long as it takes}{You'll find your symptom and the fix in one place}
+
+\begin{tldr}
+Find the heading that matches what you're seeing. Try the fixes in order. Most problems are the network, the
+password, or the baud rate.
+\end{tldr}
+
+\section{Connecting}
+
+\fix{``Authentication failed''}{%
+\begin{itemize}
+  \item Check the username, password, key path and the ticked \ui{Auth Methods}.
+  \item If the key has a passphrase, check how the passphrase is stored (\ui{Passphrase Mode}).
+  \item Two-factor server? Click \ui{Test} next to the TOTP secret and compare with your phone. Check your clock.
+  \item Saved password not being used? The vault might be locked: click \ui{Vault locked} in the status bar.
+\end{itemize}}
+
+\fix{``Host key verification failed''}{%
+The server's fingerprint changed since you last connected. That happens when a server is rebuilt, but it's also exactly
+what an attack looks like. \textbf{Check with whoever runs the server.} If it's legitimate:
+choose \ui{Accept \& Update} in the warning (or \ui{Accept Once} to defer the decision). Under a Strict or Accept-new
+policy there's no prompt: \menu{Settings\then Known Hosts}, \ui{Remove} the entry and reconnect.}
+
+\fix{It just says ``Connecting…'' forever}{%
+\begin{itemize}
+  \item Click \ui{Test} in the profile editor. If that fails too, it's the network, a firewall or the wrong port.
+  \item Behind a corporate proxy? Set one up under \ui{Proxy} (SSH profiles).
+  \item Going through a bastion? Check each jump host on its own first.
+\end{itemize}}
+
+\fix{The session keeps reconnecting}{%
+Check the network and the credentials, then the profile's auto-reconnect settings. Reconnection backs off (1\,s, 2\,s,
+4\,s… up to 30\,s) and stops after the maximum number of attempts.}
+
+\section{Serial}
+
+\fix{The port won't open}{%
+\begin{itemize}
+  \item Is the adapter plugged in? Hit refresh in the device list.
+  \item \textbf{Permission denied} on Linux: add yourself to \code{dialout} (or \code{uucp}), then log out and back in.
+  \item On a Mac, use \code{/dev/cu.*}, not \code{/dev/tty.*}.
+  \item \textbf{Port is in use by another program}: close \code{screen}, \code{minicom}, the Arduino IDE serial monitor or
+        whatever else has it open.
+\end{itemize}}
+
+\fix{Gibberish on screen}{The baud rate, parity or stop bits don't match the device. Check its manual.}
+
+\section{Remote desktops}
+
+\fix{VNC won't connect}{%
+\begin{itemize}
+  \item VNC ports are 5900 plus the display number: \code{:0} is 5900, \code{:1} is 5901.
+  \item Check the password and how it's stored.
+  \item Using an SSH tunnel? Check the tunnel's host, user, login method and key, and the host key policy.
+  \item Connecting to a Mac? Turn on password access in macOS Screen Sharing settings (see p.\,\pageref{ch:vnc}).
+\end{itemize}}
+
+\fix{RDP won't connect}{%
+\begin{itemize}
+  \item Linux box running xrdp? Tick \ui{Allow servers without NLA}.
+  \item ``Logon failed''? Check the domain. Kerberos users: the KDC must be reachable directly, not through the proxy.
+  \item Certificate warning after a server rebuild? That's expected once; compare the fingerprint, then
+        \ui{Accept \& Update}.
+  \item Going through an RD Gateway? It needs a certificate from a public CA and Basic authentication over HTTPS.
+\end{itemize}}
+
+\section{Files}
+
+\fix{Upload is greyed out or fails}{%
+The folder is probably \proto[amber]{READ ONLY} for your user. Pick another, or check permissions on the server. Uploads
+need an SSH session; other protocols can't do it.}
+
+\fix{``NO READ'' on a folder}{You don't have permission to look inside. Try the parent folder, or ask the server's admin.}
+
+\section{The terminal itself}
+
+\fix{The terminal is the wrong size}{%
+Resize the window or nudge a split divider; the terminal re-fits itself. Still wrong? Reconnect. Very old servers may
+prefer a different \ui{Terminal Type} in the profile (try \code{vt100}).}
+
+\fix{The scroll wheel moves the cursor instead of scrolling}{%
+You're in a full-screen program (\code{less}, \code{vim}, \code{tmux}). That's how terminals work: the wheel sends arrow keys
+there. Quit the program, or use its own scrolling (in \code{tmux}: \keys{Ctrl+B} then \kbd{[}).}
+
+\fix{Emoji are in black and white}{Known limitation: colour emoji show as monochrome glyphs. Everything else renders
+normally.}
+
+\begin{quickwin}[Still stuck?]
+Start Nexus Terminal with \code{--data-dir} pointing at an empty folder and try the same connection there. If it
+works, something in your profile is off; duplicate the working one and compare.
+\end{quickwin}
+
+\section{Still stuck?}
+
+\fix{Something odd that isn't on this list}{%
+Look at \code{nexus.log} in your data folder (\menu{Settings\then Diagnostics} shows where): connections, reconnects,
+host-key checks and errors, never passwords or what's on screen. Start Nexus Terminal with \code{RUST\_LOG=debug} for
+more detail. Reporting a bug? \ui{Copy Diagnostics} and paste it in.}
+

docs/guide/fonts/Phosphor-LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Romet Tagobert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/guide/nexus-guide.sty

@@ -0,0 +1,286 @@
+% Nexus Terminal user guide — look and feel. Build with lualatex (see Makefile).
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{nexus-guide}
+
+\RequirePackage[a4paper,top=24mm,bottom=26mm,inner=22mm,outer=26mm,headsep=8mm,footskip=12mm]{geometry}
+% Latin Modern OpenType isn't always installed, and the kernel selects it once before the guide's own
+% fonts take over. Point that one use at Inter so the build only needs fonts from the repo.
+\DeclareFontShape{TU}{lmr}{m}{n}{<->"[../../rust/app/assets/fonts/Inter-Regular.ttf]:mode=node;"}{}
+\RequirePackage{fontspec}
+\RequirePackage[dvipsnames]{xcolor}
+\RequirePackage{graphicx}
+\RequirePackage[most]{tcolorbox}
+\RequirePackage{tikz}
+\usetikzlibrary{calc,positioning,shadows.blur,fadings}
+\RequirePackage{titlesec}
+\RequirePackage{fancyhdr}
+\RequirePackage{enumitem}
+\RequirePackage{tabularx}
+\RequirePackage{booktabs}
+\RequirePackage{multicol}
+\RequirePackage{eso-pic}
+\RequirePackage{etoolbox}
+\RequirePackage{needspace}
+\RequirePackage{microtype}
+\RequirePackage[hidelinks]{hyperref}
+\RequirePackage{bookmark}
+
+% --- Fonts: the app's own Inter + JetBrains Mono, and its Phosphor icons ----------------
+\defaultfontfeatures{Ligatures=TeX}
+\setmainfont{Inter-Regular.ttf}[
+  Path=../../rust/app/assets/fonts/,
+  BoldFont=Inter-SemiBold.ttf,
+  ItalicFont=Inter-Regular.ttf, ItalicFeatures={FakeSlant=0.18},
+  BoldItalicFont=Inter-SemiBold.ttf, BoldItalicFeatures={FakeSlant=0.18}]
+\setsansfont{Inter-Regular.ttf}[Path=../../rust/app/assets/fonts/, BoldFont=Inter-SemiBold.ttf]
+\setmonofont{JetBrainsMono-Regular.ttf}[Path=../../rust/app/assets/fonts/, Scale=0.92]
+\newfontfamily\heavy{Inter-SemiBold.ttf}[Path=../../rust/app/assets/fonts/]
+\newfontfamily\phfont{Phosphor.ttf}[Path=fonts/]
+\newfontfamily\phfill{Phosphor-Fill.ttf}[Path=fonts/]
+\linespread{1.18}
+\setlength{\parindent}{0pt}
+\setlength{\parskip}{0.62em}
+\raggedbottom
+\sloppy
+
+% --- Palette (mirrors the app's Pro theme) ---------------------------------------------
+\definecolor{ink}{HTML}{1B1B1F}
+\definecolor{ink2}{HTML}{26262C}
+\definecolor{body}{HTML}{2A2A33}
+\definecolor{muted}{HTML}{6B6B78}
+\definecolor{rule}{HTML}{E4E4EA}
+\definecolor{paper}{HTML}{F7F7FA}
+\definecolor{accent}{HTML}{3B82F6}
+\definecolor{teal}{HTML}{14B8A6}
+\definecolor{violet}{HTML}{8B5CF6}
+\definecolor{amber}{HTML}{F59E0B}
+\definecolor{rose}{HTML}{F43F5E}
+\definecolor{pink}{HTML}{EC4899}
+\definecolor{green}{HTML}{22C55E}
+\definecolor{slate}{HTML}{64748B}
+\color{body}
+
+% Page-level drawing. Everything that paints relative to the page goes through here, drawn at shipout
+% from the page's lower-left corner, so it never depends on remember-picture positions settling.
+% Inside, the node (pg) is the whole page: use pg.north west, pg.south east and so on.
+\newcommand\pgnode{\node[inner sep=0pt, minimum width=\paperwidth, minimum height=\paperheight, anchor=south west] (pg) at (0,0) {};}
+\newcommand\pagecanvas[1]{\AddToShipoutPictureBG*{\AtPageLowerLeft{\begin{tikzpicture}[overlay]\pgnode#1\end{tikzpicture}}}}
+
+% Current part colour (set by \guidepart).
+\colorlet{partcol}{accent}
+\newcounter{guidepart}
+\newcommand\partshort{}
+
+% --- Icons ------------------------------------------------------------------------------
+\newcommand\ph[1]{{\phfont\symbol{"#1}}}
+\newcommand\phf[1]{{\phfill\symbol{"#1}}}
+\newcommand\iTerminal{\ph{EAE8}}  \newcommand\iBolt{\ph{E2DE}}     \newcommand\iBrain{\ph{E74E}}
+\newcommand\iWarn{\ph{E4E0}}      \newcommand\iBulb{\ph{E2DC}}     \newcommand\iCoffee{\ph{E1C2}}
+\newcommand\iRocket{\ph{E3FE}}    \newcommand\iCheck{\ph{E184}}    \newcommand\iTimer{\ph{E492}}
+\newcommand\iKeyboard{\ph{E2D8}}  \newcommand\iSparkle{\ph{E6A2}}  \newcommand\iShield{\ph{E40C}}
+\newcommand\iWand{\ph{E6B6}}      \newcommand\iBug{\ph{E5F4}}      \newcommand\iStar{\phf{E46A}}
+\newcommand\iSiren{\ph{E9B8}}     \newcommand\iWave{\ph{E580}}     \newcommand\iTarget{\ph{E47C}}
+\newcommand\iMap{\ph{E31A}}       \newcommand\iList{\ph{EADC}}     \newcommand\iBox{\ph{E45E}}
+\newcommand\iKey{\ph{E2D6}}       \newcommand\iPlugs{\ph{EB5A}}    \newcommand\iFolder{\ph{E256}}
+\newcommand\iBroadcast{\ph{E0F2}} \newcommand\iFilm{\ph{E792}}     \newcommand\iCode{\ph{E1BC}}
+\newcommand\iGear{\ph{E270}}      \newcommand\iLock{\ph{E2FA}}     \newcommand\iGithub{\ph{E576}}
+\newcommand\iChat{\ph{E16C}}      \newcommand\iDesktop{\ph{E560}}  \newcommand\iUsb{\ph{E956}}
+\newcommand\iTree{\ph{E67C}}      \newcommand\iArrows{\ph{E0A0}}   \newcommand\iCmd{\ph{E1C4}}
+\newcommand\iSearch{\ph{E30C}}    \newcommand\iSplit{\ph{E870}}    \newcommand\iLifebuoy{\ph{E63A}}
+\newcommand\iInfo{\ph{E2CE}}      \newcommand\iPin{\ph{E3E2}}      \newcommand\iConfetti{\ph{E81A}}
+\newcommand\iDetective{\ph{E83E}} \newcommand\iCompass{\ph{E1C8}}  \newcommand\iBinary{\ph{EE60}}
+\newcommand\iPalette{\ph{E6C8}}   \newcommand\iRecord{\ph{E3EE}}   \newcommand\iArrow{\ph{E06C}}
+\newcommand\iClock{\ph{E19A}}     \newcommand\iFlag{\ph{EA38}}     \newcommand\iPlug{\ph{E946}}
+\newcommand\iGhost{\ph{E62A}}     \newcommand\iBell{\ph{E5E8}}     \newcommand\iHourglass{\ph{E2B2}}
+\newcommand\iDownload{\ph{E20C}}  \newcommand\iUpload{\ph{E4C0}}   \newcommand\iPlane{\ph{E398}}
+
+% --- Inline bits --------------------------------------------------------------------------
+% \kbd{Ctrl} — a keycap. \keys{Ctrl+Shift+K} — keycaps joined with thin pluses.
+\newtcbox{\kbd}{on line, boxrule=0.4pt, arc=2.2pt, colback=paper, colframe=rule!70!slate,
+  boxsep=0pt, left=3.2pt, right=3.2pt, top=1.6pt, bottom=1.2pt, fontupper=\ttfamily\footnotesize\color{ink}}
+% \mod is "Ctrl, or ⌘ on a Mac": every shortcut in the guide is written \keys{\mod+K}.
+\renewcommand\mod{\kbd{Ctrl\,/\,\ph{E1C4}}}
+\def\keystop{\relax}\def\modtok{\mod}
+\DeclareRobustCommand\keys[1]{\keysplit#1+\relax+}
+\def\keysplit#1+{\def\kk{#1}\ifx\kk\keystop\else\keycap{#1}\expandafter\keysplitnext\fi}
+\def\keysplitnext#1+{\def\kk{#1}\ifx\kk\keystop\else{\kern0.15em\scriptsize\color{muted}+\kern0.15em}\keycap{#1}\expandafter\keysplitnext\fi}
+\newcommand\keycap[1]{\def\kc{#1}\ifx\kc\modtok\mod\else\kbd{#1}\fi}
+
+\newcommand\ui[1]{{\heavy\color{ink}#1}}               % on-screen labels
+\newcommand\code[1]{{\ttfamily\color{ink}#1}}           % file paths and commands
+\newcommand\menu[1]{{\heavy\color{ink}#1}}              % File → Thing
+\newcommand\then{\,{\color{muted}\iArrow}\,}
+\newcommand\proto[2][accent]{\tcbox[on line, arc=6pt, boxrule=0pt, colback=#1!14, boxsep=0pt,
+  left=4pt, right=4pt, top=1.2pt, bottom=1.2pt]{\scriptsize\heavy\color{#1!80!black}#2}}
+
+% --- Callout boxes ----------------------------------------------------------------------
+\tcbset{guidebox/.style={enhanced, breakable, arc=7pt, boxrule=0pt, left=12pt, right=12pt,
+  top=8pt, bottom=8pt, before skip=10pt, after skip=12pt, fontupper=\small,
+  parbox=false, before upper={\setlength{\parskip}{0.5em}}}}
+\newcommand\boxhead[3]{{\heavy\color{#1}\large#2\enspace\normalsize#3}\par\vspace{2pt}}
+
+\newtcolorbox{tldr}{guidebox, colback=partcol!8, borderline west={3pt}{0pt}{partcol},
+  before upper={\boxhead{partcol}{\iBolt}{TL;DR}\setlength{\parskip}{0.4em}}}
+\newtcolorbox{quickwin}[1][Quick win]{guidebox, colback=green!8, borderline west={3pt}{0pt}{green},
+  before upper={\boxhead{green!65!black}{\iTarget}{#1}}}
+\newtcolorbox{headsup}[1][Heads up]{guidebox, colback=amber!10, borderline west={3pt}{0pt}{amber},
+  before upper={\boxhead{amber!75!black}{\iWarn}{#1}}}
+\newtcolorbox{protip}[1][Pro tip]{guidebox, colback=accent!7, borderline west={3pt}{0pt}{accent},
+  before upper={\boxhead{accent!80!black}{\iBulb}{#1}}}
+\newtcolorbox{sidequest}[1][Side quest]{guidebox, colback=violet!7,
+  borderline west={3pt}{0pt}{violet}, borderline={0.5pt}{0pt}{violet!35,dashed},
+  before upper={\boxhead{violet}{\iCompass}{#1 {\normalfont\footnotesize\color{muted}\enspace·\enspace optional, skip it if you're in a hurry}}}}
+\newtcolorbox{danger}[1][Careful]{guidebox, colback=rose!8, borderline west={3pt}{0pt}{rose},
+  before upper={\boxhead{rose!85!black}{\iSiren}{#1}}}
+
+% "You are here": a one-line chapter header strip with reading time.
+\newcommand\chapmeta[2]{%
+  \begin{tcolorbox}[enhanced, arc=6pt, boxrule=0pt, colback=paper, left=10pt, right=10pt,
+    top=5pt, bottom=5pt, before skip=0pt, after skip=10pt, fontupper=\small\color{muted}]
+  {\color{partcol}\iTimer}\enspace about \textbf{#1}\hfill{\color{partcol}\iTarget}\enspace #2
+  \end{tcolorbox}}
+
+% Checklists.
+\newlist{checklist}{itemize}{1}
+\setlist[checklist]{label={\color{partcol}\large\iBox}, leftmargin=1.9em, itemsep=2pt, topsep=4pt}
+\setlist[itemize]{label={\color{partcol}\small\textbullet}, leftmargin=1.4em, itemsep=1pt, topsep=3pt}
+\setlist[enumerate]{label={\heavy\color{partcol}\arabic*}, leftmargin=1.6em, itemsep=2pt, topsep=4pt}
+\setlist[description]{font=\heavy\color{ink}, leftmargin=1.2em, itemsep=2pt}
+
+% --- Screenshots --------------------------------------------------------------------------
+% \shot[width]{file}{caption}
+\newcommand\shot[3][\linewidth]{%
+  \par\needspace{0.3\textheight}\begin{center}
+  \begin{tikzpicture}
+    \node[inner sep=0pt, rounded corners=6pt, blur shadow={shadow blur steps=8, shadow xshift=0pt,
+      shadow yshift=-2pt, shadow opacity=25}] (img) {\includegraphics[width=#1]{img/#2}};
+    \draw[rule!60!slate, line width=0.4pt, rounded corners=3pt] (img.south west) rectangle (img.north east);
+  \end{tikzpicture}\par\vspace{4pt}
+  {\footnotesize\color{muted}#3}\end{center}\vspace{-4pt}}
+
+% Two screenshots side by side.
+\newcommand\shotpair[4]{%
+  \par\needspace{0.22\textheight}\begin{center}
+  \begin{minipage}[t]{0.485\linewidth}\centering\includegraphics[width=\linewidth]{img/#1}\par\vspace{3pt}{\footnotesize\color{muted}#2}\end{minipage}\hfill
+  \begin{minipage}[t]{0.485\linewidth}\centering\includegraphics[width=\linewidth]{img/#3}\par\vspace{3pt}{\footnotesize\color{muted}#4}\end{minipage}
+  \end{center}}
+
+% A crop of a screenshot: \crop{file}{left}{bottom}{right}{top}{width}{caption}, trims in px of the 2720x1720 image.
+\newcommand\crop[7]{%
+  \par\needspace{0.2\textheight}\begin{center}
+  \begin{tikzpicture}
+    \node[inner sep=0pt, blur shadow={shadow blur steps=8, shadow yshift=-2pt, shadow opacity=25}] (img)
+      {\includegraphics[width=#6, trim=#2 #3 #4 #5, clip]{img/#1}};
+    \draw[rule!60!slate, line width=0.4pt] (img.south west) rectangle (img.north east);
+  \end{tikzpicture}\par\vspace{4pt}{\footnotesize\color{muted}#7}\end{center}\vspace{-4pt}}
+
+% Annotated screenshot: \begin{annotated}{file} \callout{1}{x}{y} … \end{annotated}, x/y in 0–1 from top left.
+\newenvironment{annotated}[1]{%
+  \par\begin{center}\begin{tikzpicture}
+  \node[anchor=north west, inner sep=0pt, blur shadow={shadow blur steps=8, shadow yshift=-2pt, shadow opacity=25}] (img)
+    {\includegraphics[width=\linewidth]{img/#1}};
+  \draw[rule!60!slate, line width=0.4pt] (img.south west) rectangle (img.north east);
+  \begin{scope}[x={(img.north east)}, y={($(img.north west)-(img.south west)$)}, shift={(img.north west)}]}
+  {\end{scope}\end{tikzpicture}\end{center}}
+\newcommand\callout[3]{%
+  \node[circle, fill=partcol, text=white, font=\heavy\footnotesize, inner sep=0pt, minimum size=15pt,
+    draw=white, line width=1.4pt, blur shadow={shadow blur steps=5, shadow opacity=40}] at (#2,-#3) {#1};}
+\newcommand\num[1]{\tikz[baseline=(n.base)]\node[circle, fill=partcol, text=white, font=\heavy\scriptsize,
+  inner sep=0pt, minimum size=13pt] (n) {#1};}
+
+% "At a glance" fact card for each connection type.
+\newenvironment{glance}[2]{%
+  \begin{tcolorbox}[enhanced, arc=8pt, boxrule=0pt, colback=#1!7, left=12pt, right=12pt, top=9pt, bottom=9pt,
+    before skip=6pt, after skip=12pt, fontupper=\small,
+    overlay={\node[anchor=north east, font=\heavy\tiny, text=#1!80!black, inner sep=8pt] at (frame.north east) {AT A GLANCE};}]
+  {\heavy\Large\color{#1!85!black}#2}\par\vspace{4pt}
+  \renewcommand\arraystretch{1.35}\begin{tabular}{@{}>{\leavevmode\color{muted}}p{0.24\linewidth}>{\leavevmode}p{0.72\linewidth}@{}}}
+  {\end{tabular}\end{tcolorbox}}
+
+% --- Headings --------------------------------------------------------------------------
+\titleformat{\chapter}[display]{\normalfont}{%
+  \pagecanvas{\fill[partcol] (pg.north west) rectangle ([yshift=-9mm]pg.north east);
+    \fill[partcol!12] ([yshift=-9mm]pg.north west) rectangle ([yshift=-11mm]pg.north east);}%
+  {\heavy\small\color{partcol}\MakeUppercase{\partshort}\enspace·\enspace CHAPTER \thechapter}}{2pt}
+  {\heavy\fontsize{30}{34}\selectfont\color{ink}}
+\titlespacing*{\chapter}{0pt}{0pt}{14pt}
+\titleformat{\section}{\heavy\Large\color{ink}}{%
+  \tikz[baseline=(n.base)]\node[fill=partcol, rounded corners=3pt, text=white, font=\heavy\small, inner sep=3pt, minimum width=18pt] (n) {\thesection};}{8pt}{}
+\titlespacing*{\section}{0pt}{18pt}{4pt}
+\titleformat{\subsection}{\heavy\large\color{ink}}{}{0pt}{{\color{partcol}\iArrow}\enspace}
+\titlespacing*{\subsection}{0pt}{12pt}{2pt}
+\renewcommand\thesection{\arabic{chapter}.\arabic{section}}
+\setcounter{secnumdepth}{1}
+\setcounter{tocdepth}{1}
+
+% --- Running heads + thumb tabs ---------------------------------------------------------
+\pagestyle{fancy}
+\fancyhf{}
+\renewcommand{\headrulewidth}{0pt}
+\renewcommand\chaptermark[1]{\markboth{#1}{}}
+\fancyhead[LE]{\footnotesize\color{muted}\heavy Nexus Terminal\enspace\normalfont·\enspace User Guide}
+\fancyhead[RO]{\footnotesize\color{muted}\leftmark}
+\fancyfoot[LE,RO]{\tikz[baseline=(n.base)]\node[fill=partcol, rounded corners=3pt, text=white,
+  font=\heavy\footnotesize, inner sep=3pt, minimum width=20pt] (n) {\thepage};}
+\fancyfoot[RE,LO]{\footnotesize\color{muted}\partshort}
+\fancypagestyle{plain}{\fancyhf{}\fancyfoot[LE,RO]{\tikz[baseline=(n.base)]\node[fill=partcol, rounded corners=3pt,
+  text=white, font=\heavy\footnotesize, inner sep=3pt, minimum width=20pt] (n) {\thepage};}}
+
+% Thumb tabs on the page edge, one slot per part, so you can flick to a part in print.
+\newif\ifthumbs
+\AddToShipoutPictureBG{%
+  \ifthumbs\ifnum\value{guidepart}>0
+  \AtPageLowerLeft{\begin{tikzpicture}[overlay]\pgnode
+    \pgfmathsetmacro\slot{28 + (\value{guidepart}-1)*30}
+    \ifodd\value{page}
+      \fill[partcol, rounded corners=4pt] ([xshift=-7mm, yshift=-\slot mm]pg.north east) rectangle ++(9mm,-26mm);
+      \node[rotate=-90, text=white, font=\heavy\tiny] at ([xshift=-3.6mm, yshift=-\slot mm - 13mm]pg.north east) {\MakeUppercase{\partshort}};
+    \else
+      \fill[partcol, rounded corners=4pt] ([xshift=7mm, yshift=-\slot mm]pg.north west) rectangle ++(-9mm,-26mm);
+      \node[rotate=90, text=white, font=\heavy\tiny] at ([xshift=3.6mm, yshift=-\slot mm - 13mm]pg.north west) {\MakeUppercase{\partshort}};
+    \fi
+  \end{tikzpicture}}\fi\fi}
+
+% \guidepart{colour}{short name}{Title}{tagline}{list of chapters}
+\newcommand\guidepart[5]{%
+  \clearpage
+  \stepcounter{guidepart}\colorlet{partcol}{#1}\renewcommand\partshort{#2}
+  \phantomsection\addcontentsline{toc}{part}{\protect\textcolor{#1}{\arabic{guidepart}}\quad #3}
+  \thispagestyle{empty}\thumbsfalse
+  \pagecanvas{
+    \fill[ink] (pg.south west) rectangle (pg.north east);
+    \fill[#1, opacity=0.9] (pg.north west) rectangle ([yshift=-95mm]pg.north east);
+    \fill[#1!70!black, opacity=0.35] ([yshift=-95mm]pg.north west) -- ++(0,-18mm) -- ([yshift=-95mm]pg.north east) -- cycle;
+    \node[anchor=north west, text=white, font=\heavy\fontsize{150}{150}\selectfont, opacity=0.25]
+      at ([xshift=14mm, yshift=-4mm]pg.north west) {\arabic{guidepart}};
+    \node[anchor=south west, text=white, font=\heavy\small] at ([xshift=24mm, yshift=-72mm]pg.north west) {PART \arabic{guidepart}};
+    \node[anchor=north west, text=white, font=\heavy\fontsize{38}{42}\selectfont, text width=160mm]
+      at ([xshift=24mm, yshift=-73mm]pg.north west) {#3};
+    \node[anchor=north west, text=white!80!#1, font=\large, text width=150mm]
+      at ([xshift=24mm, yshift=-125mm]pg.north west) {#4};
+    \node[anchor=north west, text=white, font=\normalsize, text width=150mm]
+      at ([xshift=24mm, yshift=-145mm]pg.north west) {#5};
+  }\null\clearpage\thumbstrue}
+\newcommand\partitem[2]{{\color{partcol}\large#1}\enspace #2\par\vspace{5pt}}
+
+% Table of contents.
+\RequirePackage{tocloft}
+\renewcommand\cftpartfont{\heavy\large\color{ink}}
+\renewcommand\cftpartpagefont{\heavy\color{ink}}
+\renewcommand\cftchapfont{\color{body}}
+\renewcommand\cftchappagefont{\color{muted}}
+\renewcommand\cftchapleader{\cftdotfill{\cftdotsep}}
+\setlength\cftbeforepartskip{14pt}
+\setlength\cftbeforechapskip{3pt}
+\renewcommand\cfttoctitlefont{\heavy\fontsize{30}{34}\selectfont\color{ink}}
+
+% Symptom → fix cards for troubleshooting.
+\newcommand\fix[2]{%
+  \begin{tcolorbox}[enhanced, breakable, arc=7pt, boxrule=0.5pt, colframe=rule, colback=white, left=11pt, right=11pt,
+    top=8pt, bottom=8pt, before skip=6pt, after skip=8pt, fontupper=\small, parbox=false,
+    title={\heavy\color{ink}\normalsize{\color{partcol}\iBug}\enspace #1}, coltitle=ink, colbacktitle=paper,
+    titlerule=0pt, toptitle=5pt, bottomtitle=5pt, attach title to upper={}, detach title, before upper={\tcbtitle\par\vspace{4pt}}]
+  #2\end{tcolorbox}}
+
+% Big pull-quote line used to break up long stretches.
+\newcommand\breather[1]{\par\vspace{6pt}{\centering\heavy\large\color{partcol}#1\par}\vspace{6pt}}

docs/guide/nexus-guide.tex

@@ -0,0 +1,100 @@
+% Nexus Terminal — User Guide. Build: make (in docs/guide), or: lualatex nexus-guide && lualatex nexus-guide
+\documentclass[10pt,twoside,openany]{book}
+\usepackage{nexus-guide}
+
+\hypersetup{pdftitle={Nexus Terminal: The User Guide}, pdfauthor={Andy Dixon},
+  pdfsubject={SSH, Telnet, RAW, Serial, VNC, RDP, IRC and GitHub in one native app}}
+
+\begin{document}
+\frontmatter
+\pagestyle{empty}
+
+% --- Cover ------------------------------------------------------------------------------
+\pagecanvas{
+  \fill[ink] (pg.south west) rectangle (pg.north east);
+  \shade[left color=accent, right color=violet, opacity=0.55]
+    ([yshift=-60mm]pg.north west) -- ([yshift=-20mm]pg.north east) --
+    ([yshift=-130mm]pg.north east) -- ([yshift=-170mm]pg.north west) -- cycle;
+  \shade[left color=teal, right color=accent, opacity=0.35]
+    ([yshift=-150mm]pg.north west) -- ([yshift=-120mm]pg.north east) --
+    ([yshift=-150mm]pg.north east) -- ([yshift=-185mm]pg.north west) -- cycle;
+  \node[anchor=north east, inner sep=0pt] at ([xshift=-22mm, yshift=-24mm]pg.north east)
+    {\includegraphics[width=34mm]{img/logo.pdf}};
+  \node[anchor=north west, text=white!70!ink, font=\heavy\small] at ([xshift=22mm, yshift=-30mm]pg.north west)
+    {THE USER GUIDE};
+  \node[anchor=north west, text=white, font=\heavy\fontsize{58}{60}\selectfont, text width=170mm]
+    at ([xshift=22mm, yshift=-36mm]pg.north west) {Nexus\\[-2pt]Terminal};
+  \node[anchor=north west, text=white, font=\Large, text width=150mm]
+    at ([xshift=22mm, yshift=-88mm]pg.north west)
+    {Every terminal you need. One window.\\Zero faff.};
+  \node[anchor=north west, text=white!65!ink, font=\normalsize, text width=150mm]
+    at ([xshift=22mm, yshift=-110mm]pg.north west)
+    {SSH\enspace·\enspace Telnet\enspace·\enspace RAW TCP\enspace·\enspace Serial\enspace·\enspace VNC\enspace·\enspace RDP\enspace·\enspace IRC\enspace·\enspace GitHub\enspace·\enspace Local shells};
+  \node[anchor=south west, inner sep=0pt] at ([xshift=22mm, yshift=22mm]pg.south west)
+    {\begin{tikzpicture}
+      \node[inner sep=0pt, draw=white!25!ink, line width=0.6pt, rounded corners=4pt] {\includegraphics[width=166mm]{img/ssh.png}};
+    \end{tikzpicture}};
+  \node[anchor=south east, text=white!55!ink, font=\footnotesize, align=right]
+    at ([xshift=-22mm, yshift=24mm]pg.south east) {Version 3.0.2\\October 2026\\dixon.cx};
+}\null
+\cleardoublepage
+
+% --- How to use this guide ----------------------------------------------------------------
+\colorlet{partcol}{accent}
+{\heavy\fontsize{30}{34}\selectfont\color{ink} Start here.\par}
+\vspace{2pt}{\large\color{muted} (Yes, even if you never read manuals. \emph{Especially} then.)\par}
+\vspace{10pt}
+
+This guide is built for skimming. You do \textbf{not} have to read it in order, cover to cover, like it's
+homework. Find the bit you need, grab it, get back to work. Every chapter opens with the time it takes and
+what you'll be able to do afterwards, and a \textbf{TL;DR} if you only want the gist.
+
+\vspace{4pt}
+{\heavy\large\color{ink}\iMap\enspace I just want to…}\par\vspace{2pt}
+\renewcommand\arraystretch{1.5}
+\begin{tabularx}{\linewidth}{@{}X>{\raggedleft\arraybackslash}p{52mm}@{}}
+  \toprule
+  …get connected to something \emph{right now} & \hyperref[ch:start]{Five-minute start}, p.\,\pageref{ch:start}\\
+  …work out what all the buttons do & \hyperref[ch:tour]{The grand tour}, p.\,\pageref{ch:tour}\\
+  …SSH into a server (keys, jump hosts, 2FA) & \hyperref[ch:ssh]{SSH}, p.\,\pageref{ch:ssh}\\
+  …talk to a router or Arduino over a USB cable & \hyperref[ch:serial]{Serial}, p.\,\pageref{ch:serial}\\
+  …copy files to and from a server & \hyperref[ch:files]{Files}, p.\,\pageref{ch:files}\\
+  …type the same thing into ten servers at once & \hyperref[ch:repeat]{Never type it twice}, p.\,\pageref{ch:repeat}\\
+  …keep my passwords safe & \hyperref[ch:secrets]{Passwords \& the vault}, p.\,\pageref{ch:secrets}\\
+  …keep two computers in step & \hyperref[ch:move]{Moving house}, p.\,\pageref{ch:move}\\
+  …fix something that's broken & \hyperref[part:fix]{When things go wrong}, p.\,\pageref{ch:trouble}\\
+  …just see the keyboard shortcuts & \hyperref[app:keys]{The cheat sheet}, p.\,\pageref{app:keys}\\
+  \bottomrule
+\end{tabularx}
+
+\vspace{8pt}
+{\heavy\large\color{ink}\iSparkle\enspace The little boxes}\par\vspace{-2pt}
+\begin{multicols}{2}\small
+\begin{tldr}The whole chapter in three lines.\end{tldr}
+\begin{quickwin}Something you can try in under a minute.\end{quickwin}
+\begin{protip}A trick that saves you time later.\end{protip}
+\columnbreak
+\begin{headsup}A thing that might trip you up.\end{headsup}
+\begin{danger}Could lose data or weaken security. Read it.\end{danger}
+\begin{sidequest}Interesting, but not needed to get the job done.\end{sidequest}
+\end{multicols}
+
+\vspace{-6pt}
+{\small\color{muted}\textbf{Shortcuts:} \mod{} means \kbd{Ctrl} on Windows and Linux, \kbd{\ph{E1C4}} (Command) on a Mac. So
+\keys{\mod+K} is \kbd{Ctrl}+\kbd{K} or \kbd{\ph{E1C4}}+\kbd{K} depending on your machine.}
+
+\clearpage
+\pagestyle{plain}
+{\hypersetup{linkcolor=body}\tableofcontents}
+\clearpage
+
+\mainmatter
+\pagestyle{fancy}
+\input{chapters/part1-start}
+\input{chapters/part2-connect}
+\input{chapters/part3-faster}
+\input{chapters/part4-safe}
+\input{chapters/part5-yours}
+\input{chapters/part6-fix}
+\input{chapters/appendix}
+\end{document}

docs/guide/tools/demo-shell.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Andy Dixon
+# ForceCommand for the throwaway screenshot sshd: never a login shell (no ~/.profile, no byobu).
+DEMO_HOME=$1 SFTP_SERVER=$2
+export LC_ALL=C.UTF-8
+case "$SSH_ORIGINAL_COMMAND" in
+  *sftp*) exec "$SFTP_SERVER" -d "$DEMO_HOME" ;;
+  ?*) cd "$DEMO_HOME" && HOME="$DEMO_HOME" exec bash --norc --noprofile -c "$SSH_ORIGINAL_COMMAND" ;;
+esac
+cd "$DEMO_HOME" || exit 1
+export HOME="$DEMO_HOME" PS1='\[\e[1;32m\]andy@atlas\[\e[0m\]:\[\e[1;34m\]\w\[\e[0m\]\$ '
+row() { # boxed line, padded on visible width
+  local plain; plain=$(printf '%b' "$1" | sed 's/\x1b\[[0-9;]*m//g')
+  printf '\e[1;36m│\e[0m  %b%*s\e[1;36m│\e[0m\n' "$1" $((44 - ${#plain})) ''
+}
+printf '\e[1;36m╭──────────────────────────────────────────────╮\e[0m\n'
+row 'Welcome to \e[1matlas\e[0m · Debian 13 · kernel 6.12'
+row 'Load \e[32m0.42\e[0m   Memory \e[33m61%\e[0m   Disk \e[32m38%\e[0m'
+row 'Last deploy: \e[1m2 hours ago\e[0m by andy'
+printf '\e[1;36m╰──────────────────────────────────────────────╯\e[0m\n\n'
+printf '\e[1;32m$\e[0m ls -l --color\n'; ls -l --color=always
+printf '\n\e[1;32m$\e[0m ./deploy.sh --dry-run\n'
+for s in "Resolving build" "Uploading artefacts" "Rolling out to 4 nodes" "Health checks"; do
+  printf '  \e[32m✔\e[0m %-26s \e[2m%s\e[0m\n' "$s" "$((RANDOM % 900 + 100))ms"
+done
+printf '  \e[33m⚠\e[0m 1 warning: \e[1mnginx.conf\e[0m has a deprecated directive\n'
+printf '  \e[1;32mDone.\e[0m Nothing was actually deployed (dry run).\n\n'
+exec bash --norc --noprofile -i

docs/guide/tools/fakes.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Andy Dixon
+"""Tiny fake servers for the user-guide screenshots: RAW sensor feed (42023), IRC (42667),
+GitHub API (42080) and a VNC desktop (42900). Stdlib only. Runs until killed."""
+
+import json, math, random, socket, socketserver, struct, threading, time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+
+class Threaded(socketserver.ThreadingMixIn, socketserver.TCPServer):
+    allow_reuse_address = True
+    daemon_threads = True
+
+
+# --- RAW: a chatty sensor --------------------------------------------------------------
+
+class Raw(socketserver.BaseRequestHandler):
+    def handle(self):
+        s = self.request
+        s.sendall(b"SENSOR-7 ready. Commands: STATUS, RESET\n")
+        t = 20.5
+        s.settimeout(0.25)
+        for i in range(400):
+            t += random.uniform(-0.3, 0.3)
+            s.sendall(f"temp={t:.2f}C hum={48 + 4 * math.sin(i / 3):.1f}% seq={i}\n".encode())
+            try:
+                if (cmd := s.recv(256)):
+                    s.sendall(b"OK " + cmd.strip() + b"\n")
+            except socket.timeout:
+                pass
+
+
+# --- IRC: a small, friendly network ----------------------------------------------------
+
+CHAT = [
+    ("ferris", "anyone tried the new Nexus build yet?"),
+    ("crabby", "yep, the split panes are lovely"),
+    ("ferris", "the serial console support saved my afternoon tbh"),
+    ("lin", "does it do jump hosts?"),
+    ("crabby", "lin: multiple hops, plus SOCKS5/HTTP proxies"),
+    ("ferris", "and it's Rust all the way down now :)"),
+]
+
+
+class Irc(socketserver.StreamRequestHandler):
+    def send(self, line):
+        self.wfile.write((line + "\r\n").encode())
+
+    def handle(self):
+        nick = "andy"
+        for raw in self.rfile:
+            line = raw.decode(errors="replace").strip()
+            cmd, _, rest = line.partition(" ")
+            if cmd == "NICK":
+                nick = rest.strip()
+            elif cmd == "USER":
+                self.send(f":irc.demo 001 {nick} :Welcome to the Demo IRC Network, {nick}")
+                self.send(f":irc.demo 375 {nick} :- irc.demo Message of the Day -")
+                self.send(f":irc.demo 372 {nick} :- Be excellent to each other.")
+                self.send(f":irc.demo 376 {nick} :End of /MOTD command.")
+            elif cmd == "JOIN":
+                for room in rest.split()[0].split(","):
+                    self.send(f":{nick}!u@demo JOIN {room}")
+                    self.send(f":irc.demo 332 {nick} {room} :Nexus Terminal chat · be kind · no pasting walls of logs")
+                    self.send(f":irc.demo 353 {nick} = {room} :@ferris +crabby lin {nick} octo rustacean")
+                    self.send(f":irc.demo 366 {nick} {room} :End of /NAMES list.")
+                    if room == "#nexus":
+                        for who, msg in CHAT:
+                            self.send(f":{who}!u@demo PRIVMSG #nexus :{msg}")
+                    else:
+                        self.send(f":octo!u@demo PRIVMSG {room} :borrow checker 1, me 0")
+            elif cmd == "LIST":
+                for room, n, topic in [("#nexus", 42, "Nexus Terminal"), ("#rust", 3110, "Rust"), ("#linux", 905, "Linux"), ("#homelab", 77, "Racks & routers")]:
+                    self.send(f":irc.demo 322 {nick} {room} {n} :{topic}")
+                self.send(f":irc.demo 323 {nick} :End of /LIST")
+            elif cmd == "PING":
+                self.send(f":irc.demo PONG irc.demo {rest}")
+            elif cmd == "QUIT":
+                return
+
+
+# --- GitHub API --------------------------------------------------------------------------
+
+REPOS = [
+    ("andydixon", "nexus-terminal", "SSH, Telnet, Serial, IRC and VNC in one tidy native app", "Rust", 128, False, False, False, 1),
+    ("andydixon", "leviathan", "The egui design system Nexus borrows its looks from", "Rust", 64, False, False, False, 3),
+    ("andydixon", "dotfiles", "Shell, editor and terminal config", "Shell", 12, False, False, False, 6),
+    ("andydixon", "homelab-ansible", "Playbooks for the rack under the stairs", "Jinja", 7, True, False, False, 9),
+    ("andydixon", "alchementary-link", "The Wails/Go predecessor to Nexus Terminal", "Go", 31, False, False, True, 40),
+    ("alchementary", "website", "Marketing site", "TypeScript", 3, True, False, False, 2),
+    ("alchementary", "infra", "Terraform for everything", "HCL", 2, True, False, False, 5),
+    ("alchementary", "russh", "Fork with a jump-host fix", "Rust", 0, False, True, False, 15),
+]
+WHO = ["Andy Dixon", "ferris", "crabby", "dependabot[bot]"]
+
+
+def iso(days):
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(time.time() - days * 86400 - 3600 * 5))
+
+
+class Github(BaseHTTPRequestHandler):
+    def log_message(self, *a):
+        pass
+
+    def reply(self, obj):
+        body = json.dumps(obj).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        if self.path == "/user":
+            return self.reply({"login": "andydixon"})
+        if self.path.startswith("/user/repos"):
+            page = 1 if "page=1" in self.path else 2
+            if page != 1:
+                return self.reply([])
+            return self.reply([
+                {"full_name": f"{o}/{n}", "name": n, "description": d, "html_url": f"https://github.com/{o}/{n}",
+                 "default_branch": "main", "private": p, "fork": f, "archived": a, "language": l,
+                 "stargazers_count": s, "pushed_at": iso(age), "updated_at": iso(age), "owner": {"login": o}}
+                for o, n, d, l, s, p, f, a, age in REPOS])
+        if "/commits/" in self.path:
+            i = sum(map(ord, self.path)) % len(WHO)
+            age = next((r[8] for r in REPOS if f"/{r[1]}/" in self.path), 1)
+            return self.reply({"commit": {"committer": {"name": WHO[i], "date": iso(age)}, "author": {"name": WHO[i], "date": iso(age)}}})
+        self.send_error(404)
+
+
+# --- VNC: a static "desktop" ---------------------------------------------------------------
+
+W, H = 1280, 800
+
+
+def desktop():
+    px = bytearray(W * H * 4)
+    wins = [(90, 90, 620, 420, (40, 44, 52)), (560, 260, 1180, 700, (250, 250, 252)), (140, 560, 460, 740, (32, 140, 120))]
+    for y in range(H):
+        for x in range(W):
+            # Diagonal violet → teal wallpaper.
+            k = (x + y) / (W + H)
+            r, g, b = int(88 * (1 - k) + 20 * k), int(40 * (1 - k) + 150 * k), int(160 * (1 - k) + 170 * k)
+            for x0, y0, x1, y1, c in wins:
+                if x0 <= x < x1 and y0 <= y < y1:
+                    r, g, b = (200, 70, 90) if y < y0 + 28 else c
+                    if y >= y0 + 28 and c == (40, 44, 52) and (y - y0) % 22 < 9 and x0 + 20 < x < x0 + 20 + ((y * 37) % 400):
+                        r, g, b = (120, 220, 140) if (y // 22) % 3 else (230, 200, 120)
+            if y >= H - 40:
+                r, g, b = 24, 24, 30
+            i = (y * W + x) * 4
+            px[i:i + 4] = bytes((r, g, b, 0))
+    return bytes(px)
+
+
+PIXELS = None
+
+
+class Vnc(socketserver.BaseRequestHandler):
+    def recv(self, n):
+        b = b""
+        while len(b) < n:
+            c = self.request.recv(n - len(b))
+            if not c:
+                raise EOFError
+            b += c
+        return b
+
+    def handle(self):
+        s = self.request
+        s.sendall(b"RFB 003.008\n")
+        self.recv(12)
+        s.sendall(bytes([1, 1]))  # one security type: None
+        self.recv(1)
+        s.sendall(struct.pack(">I", 0))
+        self.recv(1)  # ClientInit
+        name = b"studio:0 (demo)"
+        s.sendall(struct.pack(">HH", W, H) + bytes([32, 24, 0, 1, 0, 255, 0, 255, 0, 255, 0, 8, 16, 0, 0, 0]) + struct.pack(">I", len(name)) + name)
+        sent = False
+        try:
+            while True:
+                t = self.recv(1)[0]
+                if t == 0:
+                    self.recv(19)
+                elif t == 2:
+                    n = struct.unpack(">xH", self.recv(3))[0]
+                    self.recv(4 * n)
+                elif t == 3:
+                    self.recv(9)
+                    if not sent:
+                        s.sendall(struct.pack(">BxH", 0, 1) + struct.pack(">HHHHi", 0, 0, W, H, 0) + PIXELS)
+                        sent = True
+                    else:
+                        time.sleep(0.5)
+                        s.sendall(struct.pack(">BxH", 0, 0))
+                elif t == 4:
+                    self.recv(7)
+                elif t == 5:
+                    self.recv(5)
+                elif t == 6:
+                    n = struct.unpack(">3xI", self.recv(7))[0]
+                    self.recv(n)
+                else:
+                    return
+        except (EOFError, ConnectionError):
+            pass
+
+
+if __name__ == "__main__":
+    PIXELS = desktop()
+    for port, handler in [(42023, Raw), (42667, Irc), (42900, Vnc)]:
+        threading.Thread(target=Threaded(("127.0.0.1", port), handler).serve_forever, daemon=True).start()
+    print("fakes ready", flush=True)
+    ThreadingHTTPServer(("127.0.0.1", 42080), Github).serve_forever()

docs/guide/tools/screenshots.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Andy Dixon
+# Regenerates docs/guide/img/*.png: a throwaway sshd (ForceCommand, never a login shell),
+# fake RAW/IRC/GitHub/VNC servers, a demo data directory, then one headless app run per shot.
+# Needs: xvfb-run, sshd, ssh-keygen, python3, ImageMagick. Usage: docs/guide/tools/screenshots.sh [shot...]
+set -euo pipefail
+cd "$(dirname "$0")/.."
+GUIDE=$PWD
+B=${NEXUS_GUIDE_TMP:-/tmp/nexus-guide}
+IMG=$GUIDE/img
+APP=$GUIDE/../../rust/target/debug/nexus-terminal
+SCALE=${SCALE:-2}
+mkdir -p "$IMG"
+rm -rf "$B" && mkdir -p "$B/home/.ssh" "$B/sshd"
+
+(cd ../../rust && cargo build -q -p nexus && cargo build -q -p nexus-core --example demo_data)
+
+# Demo home: what the SFTP browser, the shell and the SSH key manager see.
+H=$B/home
+mkdir -p "$H"/{projects/nexus,backups,logs,www/static}
+printf 'server {\n  listen 443 ssl;\n}\n' > "$H/nginx.conf"
+echo '#!/bin/sh' > "$H/deploy.sh"; chmod +x "$H/deploy.sh"
+head -c 180000 /dev/urandom > "$H/backups/db-2026-10-10.sql.gz"
+head -c 52000 /dev/urandom > "$H/logs/access.log"
+echo "# Notes" > "$H/README.md"
+ssh-keygen -q -t ed25519 -N '' -C 'andy@laptop' -f "$H/.ssh/id_ed25519"
+ssh-keygen -q -t rsa -b 2048 -N '' -C 'andy@work' -f "$H/.ssh/work_rsa"
+ssh-keygen -q -t ecdsa -N '' -C 'deploy-bot' -f "$H/.ssh/deploy_ecdsa"
+
+# sshd on 42022 (ForceCommand keeps it away from ~/.profile).
+S=$B/sshd
+ssh-keygen -q -t ed25519 -N '' -f "$S/host"
+cp "$H/.ssh/id_ed25519.pub" "$S/authorized_keys"
+SFTP=$(ls /usr/lib/openssh/sftp-server /usr/libexec/openssh/sftp-server /usr/libexec/sftp-server 2>/dev/null | head -1 || true)
+cat > "$S/config" <<CFG
+Port 42022
+ListenAddress 127.0.0.1
+HostKey $S/host
+AuthorizedKeysFile $S/authorized_keys
+PidFile $S/pid
+StrictModes no
+UsePAM no
+PasswordAuthentication no
+KbdInteractiveAuthentication no
+PubkeyAuthentication yes
+PrintMotd no
+PrintLastLog no
+Subsystem sftp $SFTP
+ForceCommand $GUIDE/tools/demo-shell.sh $H $SFTP
+CFG
+"$(command -v sshd)" -f "$S/config" -E "$S/log"
+python3 -I "$GUIDE/tools/fakes.py" > "$B/fakes.log" 2>&1 &
+FAKES=$!
+trap 'kill $FAKES 2>/dev/null; kill "$(cat "$S/pid" 2>/dev/null)" 2>/dev/null || true' EXIT
+until grep -q ready "$B/fakes.log"; do sleep 0.2; done
+
+"$(dirname "$APP")/examples/demo_data" "$B/data" "$H/.ssh/id_ed25519" > /dev/null
+cp -r "$B/data" "$B/data.clean"
+
+shot() { # name, then app args
+  local name=$1; shift
+  if [ ${#ONLY[@]} -gt 0 ] && [[ ! " ${ONLY[*]} " =~ " $name " ]]; then return 0; fi
+  rm -rf "$B/data" && cp -r "$B/data.clean" "$B/data"
+  HOME=$H WINIT_X11_SCALE_FACTOR=$SCALE timeout 60 xvfb-run -a -s "-screen 0 3200x2000x24" \
+    "$APP" --data-dir "$B/data" --size 1360x860 --screenshot "$IMG/$name.png" "$@" 2>> "$B/app.log" || echo "  ! $name failed"
+  # 256-colour PNGs are a quarter of the size and look identical for UI shots.
+  [ -f "$IMG/$name.png" ] && magick "$IMG/$name.png" -colors 256 "PNG8:$IMG/$name.png"
+  echo "  $name"
+}
+ONLY=("$@")
+
+shot welcome
+shot welcome-midnight --theme midnight
+shot welcome-light    --theme light
+shot ssh              --connect "Sensor feed" --connect "Libera Chat" --connect atlas --shot-delay 5500
+shot ssh-light        --theme light --connect atlas --shot-delay 5500
+shot hostkey          --connect hello-ssh --shot-delay 5000
+shot split            --connect atlas --do "Split Pane Right" --shot-delay 5500
+shot sftp             --connect atlas --do "SFTP Browser" --shot-delay 6000
+shot broadcast        --connect build-runner --connect atlas --do "Toggle Broadcast Mode" --shot-delay 5500
+shot raw              --connect "Sensor feed" --shot-delay 5500
+shot irc              --connect "Libera Chat" --shot-delay 5500
+shot github           --connect GitHub --answer ghp_demo --shot-delay 6000
+shot vnc              --connect "Studio desktop" --answer demo --shot-delay 6000
+shot local            --run-local 'printf "\e[1;35mhello from the local shell\e[0m\n"; ls -la --color=always' --shot-delay 5000
+shot palette          --open palette
+shot quick            --open quick
+shot editor-ssh       --open editor:ssh
+shot editor-new       --open editor:new
+shot editor-serial    --open editor:serial
+shot editor-telnet    --open editor:telnet
+shot editor-raw       --open editor:raw
+shot editor-vnc       --open editor:vnc
+shot editor-rdp       --open editor:rdp
+shot editor-irc       --open editor:irc
+shot editor-github    --open editor:github
+for t in general terminal security knownhosts diagnostics help about; do shot "settings-$t" --open "settings:$t"; done
+shot keys             --open keys
+shot snippets         --open snippets
+shot triggers         --open triggers
+shot recordings       --open recordings
+shot export           --open export