# Development Guide

## Install Paths

The packaged AppImage path:

- does not require a local Node or Electron toolchain
- uses the packaged Vessel app icon and metadata
- is the recommended path for early adopters who just want to run Vessel

Windows packaged releases:

- use the `Vessel-<version>-x64-setup.exe` NSIS installer
- can be installed over an existing Vessel install when upgrading
- preserve Vessel app data during the normal upgrade path

You do not need to uninstall Vessel before installing a newer Windows release. Uninstall first only if you are recovering from a broken install or intentionally removing local Vessel data.

The source installer:

- clones or updates Vessel into `~/.local/share/vessel-browser`
- installs dependencies and builds the app
- creates a `vessel-browser` launcher in `~/.local/bin`
- creates a `vessel-browser-launch` helper in `~/.local/bin`
- creates a `vessel-browser-update` helper in `~/.local/bin`
- creates a `vessel-browser-status` helper in `~/.local/bin`
- creates a desktop entry for Linux app launchers
- writes `~/.config/vessel/vessel-settings.json` with MCP port `3100`
- writes `~/.config/vessel/mcp-stdio-snippet.json`
- writes `~/.config/vessel/mcp-http-snippet.json`
- prints the exact recommended stdio MCP snippet to paste into your harness config

After a source install:

```bash
vessel-browser
```

## Local Development

Vessel development uses Node.js 22. If you use `fnm`, run `fnm use` from the repo root to pick up `.node-version`.

```bash
# Use the pinned Node.js 22 runtime
fnm use

# Install dependencies
npm install

# If Electron download fails, use a mirror
ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/" npm install

# Development (with HMR)
npm run dev

# Production build
npm run build

# Smoke-test the MVP release path
npm run smoke:test

# Package an unpacked universal macOS app bundle (run on macOS)
npm run dist:mac:dir

# Package universal macOS DMG + ZIP artifacts (run on macOS)
npm run dist:mac

# Verify a universal macOS build contains Intel and Apple Silicon slices
npm run verify:mac:universal

# Package signed macOS DMG + ZIP artifacts (run on macOS with signing set up)
npm run dist:mac:signed
```

Notes:

- `npm run dev` still launches the stock Electron binary, so Linux may continue showing the default Electron gear icon in development
- packaged builds created with `npm run dist` or `npm run dist:dir` use the Vessel app icon
- `npm run build:icon:mac` regenerates `resources/vessel-icon.icns` from `resources/vessel-icon.png`
- `npm run dist:mac` and `npm run dist:mac:dir` build universal macOS artifacts by default, so the same app runs natively on Intel and Apple Silicon Macs
- `npm run dist:mac:x64` and `npm run dist:mac:arm64` are available when you need smaller architecture-specific test artifacts
- `npm run verify:mac:universal` uses `lipo` to confirm the packaged app executable and Electron framework include both `x86_64` and `arm64` slices
- `npm run dist:mac`, `npm run dist:mac:dir`, `npm run dist:mac:x64`, and `npm run dist:mac:arm64` intentionally disable auto-signing for repeatable local packaging
- `npm run dist:mac:signed` and `npm run dist:mac:dir:signed` build universal artifacts and use `electron-builder` signing; if your login keychain has duplicate Apple certs, clean those up or use a dedicated keychain before running the signed path
- signed macOS packages are not notarized by default in this repo
- the tracked smoke test runs typecheck, build, the MCP stdio proxy regression check, and the Electron navigation regression harness
- for headless CI, run the smoke test under `xvfb-run -a npm run smoke:test`

## Helper Commands

The installer writes three MCP snippets to:

- `~/.config/vessel/mcp-stdio-snippet.json`
- `~/.config/vessel/mcp-http-snippet.json`
- `~/.config/vessel/mcp-hermes-snippet.yaml`

It also installs a helper command:

```bash
vessel-browser-mcp
```

Helper examples:

```bash
# Recommended stdio MCP snippet
vessel-browser-mcp

# Generic JSON snippet with Authorization header
vessel-browser-mcp --format json

# Hermes-ready YAML snippet with Authorization header
vessel-browser-mcp --format hermes

# Raw MCP endpoint URL
vessel-browser-mcp --format url

# Raw MCP bearer token
vessel-browser-mcp --format token
```

The stdio snippet assumes Vessel is already running and `~/.config/vessel/mcp-auth.json` exists from install or first launch.

Source install update helpers:

```bash
# Check whether a source-install update is available
vessel-browser-update --check

# Fetch, rebuild, and update the local source install
vessel-browser-update
```

Status helper:

```bash
# Human-readable local install + MCP status
vessel-browser-status

# Machine-readable status for harnesses
vessel-browser-status --json
```

Smart launch helper:

```bash
# Launch Vessel using the best available local install
vessel-browser-launch

# Show the chosen launch path without starting anything
vessel-browser-launch --dry-run
```

`vessel-browser-launch` prefers a healthy source install and falls back to the newest local AppImage when the source install is likely blocked by Electron sandbox permissions.
