# deploy/ — Scripts Reference

All setup, build, and launch operations are handled by standalone shell scripts.
No sourcing required. Run them directly from the repo root.

## Scripts

| Script | Run when | What it does |
|---|---|---|
| `./deploy/setup.sh` | After every reboot | Copies CoreIK.framework to `/tmp`, codesigns it |
| `./deploy/build.sh` | After any code change | Compiles the app for the visionOS Simulator |
| `./deploy/launch.sh` | When you want to run it | Boots sim, clears FrontBoard state, installs + launches |
| `./deploy/logs.sh` | After launch (second terminal) | Streams `/tmp/coreik_invocations.log` live |
| `./deploy/verify.sh` | Pre-publish sanity check | Runs all of the above end-to-end, confirms solver fires |
| `./deploy/derive_offsets.sh` | New visionOS build | Derives symbol offsets via `nm`, prints Swift block to paste |

## Prerequisites

- macOS 15 (Sequoia) or later, Apple Silicon
- Xcode 26.x
- At least one visionOS Simulator runtime (Xcode → Settings → Platforms → visionOS, ~6.7 GB)
- Free Apple ID — no paid developer account needed

## Quick start

```bash
./deploy/setup.sh     # run once per boot
./deploy/build.sh     # compile (~60s first build)
./deploy/launch.sh    # boot sim + install + launch
./deploy/logs.sh      # second terminal — stream live log
```

Tap **Enter Immersive Space** in the Simulator. Skeleton appears. Move sliders.

## New visionOS build

Offsets for 26.2, 26.4.1, and 26.5 are pre-committed in `coreik_offsets/`.
For any newer build:

```bash
./deploy/setup.sh --version <version>
./deploy/derive_offsets.sh /tmp/CoreIK.framework/CoreIK
# paste printed Swift block into HelloVisionOS/CoreIKBridge.swift
```

`setup.sh` will print a red warning if no offset file exists for the detected build.

## Troubleshooting

**App crashes on launch** — stale FrontBoard state. `launch.sh` clears this automatically.
If it persists: `xcrun simctl shutdown all && xcrun simctl erase <UDID>` then relaunch.

**"Unknown CoreIK build" in app UI** — no offset file for this build. Run `derive_offsets.sh`.

**Solver returns nil / "Solver FAILED"** — `/tmp/CoreIK.framework` is stale or missing.
Re-run `setup.sh` (cleared on reboot).

**BUILD FAILED: SDK not found xrsimulator** — wrong Xcode selected.
`sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`

**logs.sh shows nothing** — app hasn't launched yet, or hasn't entered Immersive Space.
The log file is created on first CoreIK call.

## File locations (readable from host terminal)

| Path | Contents |
|---|---|
| `/tmp/coreik_invocations.log` | Live log of every CoreIK API call |
| `/tmp/CoreIK.framework/BUILD` | Build tag of the currently staged framework |
| `/tmp/CoreIK.framework/SETUP.info` | Full setup metadata (version, source path, timestamp) |

The simulator's `/tmp` maps directly to the host's `/private/tmp` — no `xcrun simctl` needed.
