# LOCALHOST CRT portable Mac setup

This is the agent-readable handoff. Download, inspect, verify, then run locally on the NEW Mac. Do not connect to the original Mac or change its live installation.

## Requirements and trust

macOS 12+ on Apple Silicon or Intel, an extended external CRT/projector/display, and built-in macOS command-line utilities only. No Xcode, Node, Python, Homebrew, browser automation, screen-recording permission, accessibility permission, or local web server is required. The prebuilt native app uses Apple's WKWebView. Hardware adapters and the CRT's video signal must already work in macOS. This does not configure resolution, overscan, mirroring, or adapter hardware.

The app is ad-hoc signed, NOT Developer-ID signed or notarized. It may be blocked by Gatekeeper. Do not remove quarantine, use xattr to clear flags, disable Gatekeeper, or use spctl overrides. If macOS blocks it, ask the human to review the source/publisher and use the ordinary Finder open / System Settings > Privacy & Security > Open Anyway approval flow if they choose to trust it. Organization policy may disallow this. Stop and report that limitation rather than bypassing it. Launching through `open` preserves normal macOS app approval behavior. A checksum detects corruption, it is not independent publisher authentication.

## Download and inspect

Use this stable origin: https://localhost-crt-kit.pages.dev

Run on the new Mac in Terminal or the local agent's shell:

```sh
mkdir -p "$HOME/Downloads/Localhost-CRT-kit"
cd "$HOME/Downloads/Localhost-CRT-kit"
curl --fail --location --proto '=https' --tlsv1.2 https://localhost-crt-kit.pages.dev/Localhost-CRT.zip -o Localhost-CRT.zip
curl --fail --location --proto '=https' --tlsv1.2 https://localhost-crt-kit.pages.dev/SHA256SUMS -o SHA256SUMS
shasum -a 256 -c SHA256SUMS
unzip -l Localhost-CRT.zip
/usr/bin/ditto -x -k Localhost-CRT.zip .
cd Localhost-CRT
cat AGENTS.md
cat launch.command stop.command update.command
```

Never proceed if checksum validation fails. No secrets or private host access are included. Source and build script are bundled under `source/` for inspection, not required for installation.

## Select the output safely

First confirm with the user that this new Mac's intended secondary display is connected in extended mode and they want the installation started. If another installation/browser is already displaying there, ask before covering it. Do not stop unrelated processes.

```sh
bash launch.command list
bash launch.command check
```

These commands create no windows or web requests. Default `auto` selects a display only if exactly one connected screen is neither built-in nor the macOS MAIN display. No laptop/main-display fallback, even with explicit selection. If there are zero candidates, ask the user to connect/extend the display or select a different main display in macOS. Never change that configuration yourself without permission. If there are multiple candidates, show the list and ASK which one is the CRT, then pass its numeric `id`:

```sh
bash launch.command check --display 2
```

Display IDs vary across machines/reconnections. Do not hardcode `2` or assume the name `Transmitter`. Mirrored displays are not supported as an independent canvas.

## Start

Only after output approval and successful check:

```sh
bash launch.command online
# Or, if the user selected a particular display:
bash launch.command online --display 2
```

Online mode loads the latest hosted artwork from https://localhost-projection-v2.pages.dev/?mapping=stretch&motion=on&presentation=1 and requires internet. This dedicated secondary-display panel does not activate the app, enter macOS fullscreen, move existing windows, or take the main display. Cable removal closes the player, never moves it to the laptop. The launcher refuses a second portable player instance. Stretch mapping deliberately fills the output; CRT 4:3 geometry depends on the adapter's signal and the physical CRT adjustments, not software screen-resolution changes.

For a bundled, frozen offline snapshot instead:

```sh
bash launch.command offline
# Or: bash launch.command offline --display 2
```

Offline mode reads bundled files directly. No internet or local server required. Snapshot captured for release 1.0.0 from the existing visual tree during packaging. It is NOT live-updating and may differ from the current online artwork. Online and offline modes must be switched by stopping then relaunching. No automatic fallback obscures which version is running.

## Stop / update / uninstall

```sh
bash stop.command
bash update.command
```

Stop sends TERM only to the separate `LocalhostCRT` app, never the original `LocalhostPlayer`, browsers, or other apps. It does not require that the installation have keyboard focus. Escape/Cmd-Q only work if the panel actually receives the keys; use the stop script as the reliable exit.

Update downloads and checks the current public release into a NEW Downloads folder. It does not stop, replace, or launch a live player. Read the new guide, ask approval to change output, stop the old portable player, then run the new folder's launcher. Online visuals update independently of the player release when the app is restarted; offline snapshots update only with kit releases. No auto-start, LaunchAgent, login item, daemon, or background web server is installed. To uninstall, stop it and delete the extracted kit folders.

## Tested and limitations

Release 1.0.0 was compiled on macOS with both arm64 and x86_64 slices and a macOS 12 deployment target. Ad-hoc code signature verification, display listing, safe no-window checks, archive inventory/checksum, and shell syntax were checked. The existing CRT player was left running. The portable app was deliberately NOT shown on that live CRT. Not tested on a clean Mac, Intel hardware, or macOS 12 hardware. Gatekeeper's first-run human approval flow has not been exercised on a clean destination. Offline files are packaged locally without remote assets, but native offline rendering has not been visually tested on a clean Mac. Report these limits honestly rather than promising zero-click unattended installation.

## Launcher hotfix 1.0.1

The launcher avoids empty arrays under nounset for stock macOS Bash 3.2. Default, online, offline, list, check, and explicit-display argument forwarding passed on macOS /bin/bash 3.2.57 with app/open mocks (no live windows changed). Stop/update scripts contain no empty-array expansions. Re-download ZIP and SHA256SUMS together for this fix.