# Route C Host Setup Contract

This document records the production user journey contract for installing and
starting an Oysterun Host. It focuses on the final intended user path, not
historical setup experiments.

## Stage 1 Product Model

Stage 1 uses:

- direct Host URL/IP:port for app/web connectivity
- Cloud for app installation identity, pairing metadata, and APNs notification
- one saved Host in the phone app
- durable login until explicit logout, credential revocation, or app storage
  reset

Stage 1 does not require the Oysterun tunnel for normal chat.

## Release Setup Command Contract

The source-worktree install path should be:

```bash
npm install
npm run setup
```

`npm install` only installs dependencies. It must not start the Host or mutate
runtime config.

The npm package install path should be:

```bash
npm install -g oysterun
oysterun
```

`oysterun` enters setup automatically when required Host config is missing.
`npm run setup` and `oysterun setup` both run the first-run wizard. Interactive
setup questions use a step-based terminal format such as `[1/7] Host name` and
a stable `?` prompt prefix, so explanatory copy and questions are visually
separate.

```text
[1/7] Host name
1. Ask for Host display name.

[2/7] Host port
2. Ask for Host port.
   - default production port is 8802.
   - if occupied, offer the next available port.

[3/7] iPhone connection URL
3. Ask how the iPhone will connect to this Mac.
   - prefer detected Tailscale/VPN or LAN URL.
   - localhost is Mac-browser-only; for iPhone on the same Wi-Fi/LAN, use the
     Mac LAN IP address.
   - if not on the same reachable network, use Tailscale, Cloudflare Tunnel,
     VPN, or another reachable tunnel/direct URL.

[4/7] Host password
4. Ask for Host password.
   - password input must be hidden.
   - first setup must confirm password by entering it twice.
   - local dashboard user is admin; user does not input a username.
5. Write Host config.
6. Create dashboard credential hash.
7. Register Stage 1 direct-IP Host with Cloud when Cloud direct mode is enabled.
8. Write Host Cloud identity to cloud_identity.json, not config.json.

[5/7] Phone app
9. Explain: "You need the Oysterun phone app to scan the login QR."
   Ask: "Show phone app download link and QR code?"
   - yes: show the phone app download link and QR.
   - no: continue to the Host login QR step.
   - first version download URL: `https://oysterun.com`.
   - later production URL should be the App Store link.

[6/7] Login QR
10. Create a 15-minute one-time QR/bootstrap login token.
11. Show the QR code in terminal.

[7/7] Start Host
12. Install the launchd service.
13. Ask whether to start Host now, default yes.
14. yes:
      launchd start
      health check
      display Web URL
      on interactive macOS setup, open `<Host URL>/app/sessions` in the browser
      after health check succeeds
    no:
      print `oysterun` as the start command.
```

Setup must not ask for macOS Full Disk Access during first-run installation.
macOS folder access recovery UI is a Host Preferences debug block, hidden by
default and shown only when `config.debug.json` explicitly enables it.

Setup must run before the server starts. The server reads the config generated
by setup.

When `OYSTERUN_CONFIG_DIR` points at a stack folder such as:

```text
~/.oysterun-stacks/test4/host
```

setup should run service actions against that same stack. Production setup uses
`~/.oysterun` and therefore the production service stack.

If the Host is already running and setup changes runtime connection settings,
setup should tell the user restart is required and offer to restart through the
service manager.

## Service Contract

Release Host should run as a local managed service, not as a foreground
terminal process.

Required commands:

```bash
oysterun service:start
oysterun service:stop
oysterun service:restart
oysterun service:logs
oysterun show-qr
```

Release service behavior:

```text
- starts after Mac login
- restarts on crash
- writes stdout/stderr to a fixed log path
- can be restarted from Host Preferences
- does not require the user to remember a raw server command
```

## QR Login Contract

The setup QR is a convenience login/bootstrap path. It should contain enough
information for the app to connect and log in without typing IP:port/password:

```text
host_id
direct_host_url
one-time login/bootstrap token
expiry
Cloud API URL when Cloud direct mode is enabled
display name
```

The one-time token should expire after 15 minutes.

Host Preferences must provide a "generate login QR" action for later pairing or
re-login. It creates a new short-lived token and displays the QR.

Scanning the QR must not make `installation_id` into Host product login auth.
Host product login remains:

```text
- Host password, or
- Host-owned one-time QR/bootstrap token
```

## Cloud Identity Storage Contract

The production Cloud API endpoint is a tracked code default, not Host user
config:

```text
host-service/config.mjs
PRODUCT_CLOUD_BACKEND_URL = https://api.oysterun.com
```

`config.json` stores user/deployment preferences. It must not persist
`backend_url`, `device_token`, or other Host Cloud identity credentials.

Host Cloud identity is stored in:

```text
<host_config_dir>/cloud_identity.json
```

That file stores:

```text
device_id
device_token
registered_at
cloud_registration_state
```

Host Preferences may show Cloud registration status, but must not expose a
user-editable Cloud backend URL or token field.

## Phone App First Page Contract

Stage 1 phone app first page should support:

```text
1. Scan QR code.
2. Manual Host URL/IP:port + password login.
3. Open saved Host.
```

Open saved Host should show the saved Host display name and URL. Selecting a
saved Host fills the login page fields or opens the saved Host according to
whether durable auth is still valid.

Logout from the phone app should return to the phone app bootstrap/login page,
not to the web dashboard login page.

## Web Login Contract

Web login should remain Host-local:

```text
- password only
- no username field in product UI
- dashboard user is admin internally
```

The web login page is separate from the phone app bootstrap/login shell.

## Host Preferences Runtime Settings

Host Preferences may allow changing Host URL/IP:port and related connection
settings. For settings that require process restart:

```text
1. Save the setting.
2. Show a clear "restart required" notice.
3. Provide a restart action.
4. After restart, redirect or instruct the user to open the new URL.
```

Runtime edits must not require rebuilding the phone app. Capacitor sync/build
is only for app code changes, not day-to-day Host/IP changes.

## Stage 2 Direction

Stage 2 may add:

- Oysterun tunnel connection option
- Host list / multi-Host details
- biometric unlock

Stage 2 must not rewrite Stage 1 notification identity. The app installation
identity and APNs registration model should remain compatible.
