{
  "notes": "Conformance fixtures for scripts/skill-conformance.test.ts — shaped fake values only, never real credentials. Two scenarios cover both when:backend= legs; the echo stub answers the platform_id capture (the skill echoes the owner handle back). The hosted device-login effect:step is stubbed by the harness's execStream (no captured fields).",
  "scenarios": [
    {
      "name": "local",
      "inputs": {
        "backend": "local",
        "owner_handle": "owner@example.com"
      },
      "exec": [
        { "match": "echo \"owner@example.com\"", "stdout": "owner@example.com" }
      ]
    },
    {
      "name": "hosted",
      "inputs": {
        "backend": "hosted",
        "owner_handle": "+15551234567"
      },
      "exec": [
        { "match": "echo \"+15551234567\"", "stdout": "+15551234567" }
      ]
    }
  ]
}

# iMessage — one channel, two backends

NanoClaw connects to **iMessage** through a single `imessage` channel with two
pluggable backends. Pick one at install time (or force it with
`IMESSAGE_BACKEND=local|hosted`); only one runs per install.

- **Local** — the Chat SDK bridge over [`chat-adapter-imessage`][adapter],
  reading **this Mac's** signed-in iMessage account (`chat.db`). macOS only, and
  the Node binary needs Full Disk Access. No third-party service — your messages
  never leave your machine — but NanoClaw must run on the Mac that's signed in.
- **Hosted** — a native adapter connecting to iMessage through [Photon][photon],
  a managed service that owns the iMessage line, delivery, and
  abuse-prevention, so you don't run a Mac relay. Works on any OS. Photon's free
  tier uses a shared iMessage line pool, so anyone can start without a paid plan.

Install either flavor with `/add-imessage` (it asks which backend); the adapter
(`src/channels/imessage.ts`) is fetched from the `channels` branch and
self-registers in the channel barrel. It stays dormant until a backend is
configured.

## Choosing a backend

| | Local | Hosted iMessage (via photon.codes) |
| --- | --- | --- |
| Runs on | macOS only (reads `chat.db`) | any OS |
| iMessage line | your own Apple ID | Photon-managed number |
| Setup | grant Full Disk Access | device-login wizard |
| Package | `chat-adapter-imessage@0.1.1` | `spectrum-ts@11.0.0` |
| Credentials | `IMESSAGE_ENABLED=true` | `PHOTON_PROJECT_ID` / `PHOTON_PROJECT_SECRET` |
| Attachments out / tapbacks | as `chat-adapter-imessage` supports | yes |

The factory picks the backend deterministically: an explicit `IMESSAGE_BACKEND`
wins; otherwise Photon credentials imply hosted and `IMESSAGE_ENABLED` implies
local. If both are set without `IMESSAGE_BACKEND`, hosted wins (with a warning).

## Local backend (this Mac)

macOS only. The adapter reads the signed-in account's `chat.db`, which requires
**Full Disk Access** granted to the Node binary NanoClaw runs under. During
`/setup` (or `/add-imessage`) we open the Node binary's folder in Finder so you
can drag it into **System Settings → Privacy & Security → Full Disk Access**.

`.env`:

```bash
IMESSAGE_BACKEND=local
IMESSAGE_ENABLED=true
```

The DM `platform_id` / user id is the phone or email you iMessage with
(`imessage:+15551234567`).

## Hosted iMessage backend (via photon.codes)

Like Discord and Slack, Photon is a **persistent-connection** channel — no
public URL, no webhook, no signing secret. The `spectrum-ts` SDK holds a
long-lived **gRPC stream** to Photon for both directions. NanoClaw's host runs
on Node and `spectrum-ts` is a TypeScript SDK, so it runs **in-process on the
host** — no Python sidecar (as in Hermes), no loopback HTTP. `deliver()` /
`setTyping()` call the SDK directly; a re-subscribing consumer loop drains the
inbound stream.

```
                       gRPC (spectrum-ts, in-process)
┌─────────────────────────┐  ◄───────────────►  ┌──────────────────────────┐
│  Photon Spectrum cloud  │   app.messages       │  NanoClaw host (Node)    │
│  (iMessage line owner)  │   space.send()       │  imessage.ts (hosted)    │
└─────────────────────────┘                      └──────────┬───────────────┘
                                        onInbound / deliver  │  ▲
                                                             ▼  │
                                                   router / delivery pipeline
```

- **Inbound** — the SDK's `app.messages` async iterator yields
  `[space, message]` pairs. The adapter normalizes each into an
  `InboundMessage` (text, downloaded attachments, reaction markers) and hands
  it to the router via `onInbound`. If the stream ends or errors, the consumer
  loop re-subscribes with capped exponential backoff.
- **Outbound** — `deliver()` resolves the target space (a DM by phone number
  via `space.create`, or a group by its opaque space id via `space.get`) and
  calls `space.send(markdown | text | attachment | voice | typing | read)`.

### Credentials

Runtime SDK credentials live in `.env` (host-side; **never** enter a
container — delivery is host-side, and the container-runner does not mount
`.env` into agent containers):

```bash
PHOTON_PROJECT_ID=<spectrum project id>   # the SDK's projectId
PHOTON_PROJECT_SECRET=<project secret>
```

The device-login bearer token used during setup is cached in
`data/photon-auth.json` (mode `0600`) so re-running the wizard reuses it.

### Setup wizard

During first-time NanoClaw setup, choose **Yes, connect iMessage** and then
**Hosted iMessage**. That path asks for your iMessage phone number, runs the
Photon device login and provisioning wizard, installs the pinned runtime SDK,
restarts NanoClaw, and wires the DM to your first agent. It does not ask for a
server URL or API key.

`/add-imessage` (Hosted) provides the same flow for an existing installation.
The underlying commands are:

```bash
# 1. install the runtime SDK (pinned — spectrum-ts ships breaking majors)
pnpm install spectrum-ts@11.0.0

# 2. run the setup wizard (device login + guided provisioning; one manual step
#    — you text the assigned line once, and the wizard waits for it)
pnpm exec tsx scripts/photon-setup.ts --phone +15551234567
```

`scripts/photon-setup.ts` does, in order:

1. **Device login** (RFC 8628, `client_id=photon-cli`) — prints a URL + code,
   opens your browser, and polls until you approve. Talks only to Photon's
   dashboard HTTP API — it does not import `spectrum-ts`, so it works before the
   runtime SDK is installed.
2. **Find or create** the `NanoClaw` project on the Photon dashboard.
3. **Reuse the project's current secret** (regenerating only when the API
   returns none) and write `PHOTON_PROJECT_ID` + `PHOTON_PROJECT_SECRET` to
   `.env`.
4. **Register your phone and wait for its opt-in.** The wizard finds your
   Spectrum user row or creates one (`type: shared`), and prints the
   `assignedPhoneNumber` the row came back with. A new row never routes: the
   number only enters iMessage routing once it has sent one message to that
   assigned line, which is what flips the row's `meta.opt_in` server-side. The
   wizard polls the user list until it does — instant if the row is already
   opted in, and it never reports success before then.
5. **Surface the assigned iMessage line** — the number you text to reach your
   agent (the same one you texted to opt in).

Everything is idempotent: re-running reuses the stored token/project and the
existing user row, so it's safe to finish a partial setup. `pnpm exec tsx
scripts/photon-setup.ts status` shows what's configured, re-checking the opt-in
live.

After setup, restart the service so the adapter connects, then wire the DM to
an agent with `/init-first-agent` (the wizard prints a ready-to-run command).

### Configuration (hosted)

All optional, set in `.env`:

| Env var                              | Default                         | Meaning                                                                                  |
| ------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------ |
| `PHOTON_PROJECT_ID`                  | — (required)                    | Spectrum project id (SDK `projectId`)                                                    |
| `PHOTON_PROJECT_SECRET`              | — (required)                    | Project secret                                                                           |
| `PHOTON_MARKDOWN`                    | `true`                          | Send agent replies as markdown (iMessage renders it natively). `false` sends plain text. |
| `PHOTON_TELEMETRY`                   | `false`                         | Enable Spectrum SDK telemetry                                                            |
| `PHOTON_MAX_INLINE_ATTACHMENT_BYTES` | `20971520` (20 MB)              | Max inbound attachment size the adapter reads + caches                                   |
| `PHOTON_DASHBOARD_HOST`              | `https://app.photon.codes`      | Management API host — device login and project provisioning (setup wizard)               |
| `PHOTON_SPECTRUM_HOST`               | `https://spectrum.photon.codes` | Spectrum API host (setup wizard)                                                         |

## Platform ids

- **DMs** are direct-addressable: the `platform_id` is the counterpart's bare
  E.164 number (e.g. `+15551234567`, or an email for the local backend), and the
  user id is `imessage:+15551234567` (see `src/platform-id.ts`).
- **Groups** (hosted) use the opaque Spectrum space id, discovered on first
  message.

## Features (hosted)

- **First contact is user-initiated** (intended Photon behavior) — the line can
  only message numbers that have already texted it; a cold outbound to an
  unknown number is rejected with `Target not allowed for this project`. Text
  your agent's number once before expecting anything back (this is why the
  wiring steps start with "text the number"). A welcome DM queued before that
  first inbound text simply fails delivery — it is not a NanoClaw bug.
- **Markdown** — replies are sent via the SDK's `markdown()` builder; iMessage
  renders bold/italics/lists/code natively. `PHOTON_MARKDOWN=false` reverts to
  plain text.
- **Inbound attachments & voice notes** — read off the stream (with retry on
  transient stream resets) and staged into the session's inbox by the host,
  surfaced to the agent as structured `attachments` (with a
  `[… could not be downloaded]` note on failure). Over-cap media is skipped.
- **Outbound attachments** — files are written to a temp path and sent via
  `space.send(attachment(...))`.
- **Reactions (tapbacks)** — `send_reaction` maps to an iMessage tapback;
  inbound tapbacks arrive to the agent as `reaction:added:<emoji>`.
- **Read receipts** — each inbound message marks its iMessage chat read via
  `space.send(read(message))`; receipt failures never block inbound routing.
- **Approval questions** — `ask_user_question` renders as text with
  `/approve` / `/reject` slash-command replies (iMessage has no buttons). A
  matching reply routes to the approval handler instead of waking the agent.
- **Typing indicators** — sent while the agent is working.

The local backend's feature set is whatever `chat-adapter-imessage` and the
Chat SDK bridge provide.

## Upgrading spectrum-ts (hosted)

`spectrum-ts` is pinned to an **exact** version in `package.json` because the
SDK ships breaking majors (v11 is what the adapter targets). Upgrades are
deliberate:

1. Read the [SDK release notes][releases] for every version between the current
   pin and the target.
2. Bump the exact pin and run `pnpm install`.
3. Reconcile `src/channels/imessage.ts` against the new typings. The hosted
   backend uses `Spectrum`, the `imessage` provider, the `text` / `markdown` /
   `typing` / `read` / `attachment` / `voice` content builders, and
   `space.send` / `space.getMessage` / `message.react`.
4. Run `pnpm run build` and `pnpm exec vitest run src/channels/imessage.test.ts`.

## Troubleshooting

| Symptom                                 | Fix                                                                                                                   |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `spectrum-ts is not installed` at setup | Hosted backend: `pnpm install spectrum-ts@11.0.0`, then restart                                                        |
| `Target not allowed for this project`   | The number's user row is not opted in yet (`meta.opt_in` absent) — send one message from that phone to the line assigned to the row, then re-run setup (the line only messages numbers that have texted it first) |
| Device login times out                  | Re-run the wizard (the code expires in ~30 min; a stored token is reused)                                             |
| No iMessage line assigned               | The line comes back on your user row — re-run the wizard with `--phone` so the row is created, then `… photon-setup.ts status` |
| Inbound stops arriving (hosted)         | The adapter re-subscribes automatically; if it persists it's usually upstream — restart to force a fresh stream       |
| Local: no inbound                       | Confirm Full Disk Access is granted to the Node binary NanoClaw runs under, and that it runs on the signed-in Mac     |
| Bot silent (hosted)                     | Check `grep "Photon channel connected" logs/nanoclaw.log`, that the channel is wired, and that the service is running |

[photon]: https://photon.codes/
[adapter]: https://www.npmjs.com/package/chat-adapter-imessage
[releases]: https://github.com/photon-hq/spectrum-ts/releases

# Remove iMessage

Reverses whatever `/add-imessage` installed — either backend. Detect which one
is present and reverse it. Every step is idempotent — safe to re-run. (The
provisioning wizard `scripts/photon-setup.ts` ships in trunk and is left in
place.)

## 1. Remove the self-registration import

Delete the `import './imessage.js';` line from `src/channels/index.ts` (delete
the line, don't comment it out).

## 2. Delete the adapter + its tests

```bash
rm -f src/channels/imessage.ts src/channels/imessage.test.ts src/channels/imessage-registration.test.ts
```

## 3. Uninstall the backend package(s)

Uninstall whichever is present:

```bash
pnpm uninstall chat-adapter-imessage   # local backend
pnpm uninstall spectrum-ts             # hosted backend
```

## 4. Remove credentials

Strip these from `.env` (skip any not present):

```bash
# selector + local backend
IMESSAGE_BACKEND
IMESSAGE_ENABLED
# legacy Chat-SDK remote mode (removed) — clean up stragglers
IMESSAGE_LOCAL
IMESSAGE_SERVER_URL
IMESSAGE_API_KEY
# hosted backend
PHOTON_PROJECT_ID
PHOTON_PROJECT_SECRET
PHOTON_MARKDOWN
PHOTON_TELEMETRY
PHOTON_MAX_INLINE_ATTACHMENT_BYTES
PHOTON_DASHBOARD_HOST
PHOTON_SPECTRUM_HOST
```

## 5. Remove the cached device token (optional, hosted)

```bash
rm -f data/photon-auth.json
```

## 6. Rebuild and restart

```bash
pnpm run build
source setup/lib/install-slug.sh
launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
# systemctl --user restart $(systemd_unit)            # Linux
```

## 7. Unwire and delete the messaging group (optional)

```bash
pnpm exec tsx scripts/q.ts data/v2.db "
DELETE FROM messaging_group_agents WHERE messaging_group_id IN
  (SELECT id FROM messaging_groups WHERE channel_type='imessage');
DELETE FROM messaging_groups WHERE channel_type='imessage';
"
```

## 8. Delete the Photon project (optional, hosted)

To fully deprovision, delete the `NanoClaw` project from the
[Photon dashboard](https://app.photon.codes). This releases the iMessage line.

---
name: add-imessage
description: Add iMessage to NanoClaw — one channel, two backends. Local (this Mac's chat.db via the Chat SDK bridge; macOS + Full Disk Access) or Hosted iMessage (via photon.codes — native spectrum-ts with a device-login wizard; any OS, no Mac relay). Triggers on "add imessage", "connect imessage", "add photon", "imessage via photon", "native imessage".
---

# Add iMessage

NanoClaw talks to iMessage through a single **`imessage`** channel with two
pluggable backends:

- **Local (this Mac)** — the Chat SDK bridge over `chat-adapter-imessage`,
  reading this Mac's signed-in iMessage account (`chat.db`). macOS only; the
  Node binary needs Full Disk Access.
- **Hosted iMessage (via photon.codes)** — a native adapter over Photon's
  `spectrum-ts` gRPC stream. The hosted service owns the iMessage line, so
  there's no Mac relay, webhook, or public URL. Works on any OS, and a
  device-login flow provisions everything for you.

Both register the same `imessage` channel type; only one runs per install.
NanoClaw doesn't ship channels in trunk — this skill copies the unified
`imessage` adapter in from the `channels` branch. Full reference:
[docs/imessage.md](docs.md).

The mechanical steps under **Apply** carry `nc:` directive fences: an agent reads
the prose and applies them, and a parser can apply them deterministically from
the same document. Every directive is idempotent, so the whole skill is safe to
re-run; anything a parser can't apply falls back to the prose beside it.

## Apply

### 1. Choose a backend

Pick the backend first — it decides which package gets installed and which
walkthrough runs below (the other backend's steps are skipped):

```nc:prompt backend validate:^(local|hosted)$
How should iMessage run — `local` (this Mac's signed-in iMessage account; macOS only, needs Full Disk Access) or `hosted` (a managed line via photon.codes; works on any OS)?
```

The local backend only works on a Mac — it reads this machine's iMessage
`chat.db` directly, and there is no such database off macOS. On any other OS,
stop here and choose `hosted` instead; otherwise you'd write a local config
that can never receive a message:

```nc:run effect:check when:backend=local
[ "$(uname)" = Darwin ]
```

### 2. Copy the adapter

Fetch the `channels` branch and copy the unified iMessage adapter and its tests
into `src/channels/`:

```nc:copy from-branch:channels
src/channels/imessage.ts
src/channels/imessage.test.ts
src/channels/imessage-registration.test.ts
```

### 3. Register the adapter

Append the self-registration import to the channel barrel (skipped if the line
is already present). This one line is the skill's only reach-in into core:

```nc:append to:src/channels/index.ts
import './imessage.js';
```

### 4. Install the chosen backend's package

Pinned to an exact version — the supply-chain policy rejects ranges and
`latest`. Install only the chosen backend's package.

**Local** — the Chat SDK iMessage adapter:

```nc:dep when:backend=local
chat-adapter-imessage@0.1.1
```

**Hosted** — Photon's Spectrum SDK:

```nc:dep when:backend=hosted
spectrum-ts@11.0.0
```

> Pin exactly. `spectrum-ts` ships breaking majors (v11 is what the adapter
> targets); don't `@latest`. NanoClaw's pnpm gate (`minimumReleaseAge`) requires
> a version ≥3 days old — both pins clear it. A fresher pin needs human sign-off
> before a `minimumReleaseAgeExclude` entry (CLAUDE.md → Supply Chain Security).

### 5. Build and validate

Build guards the typed `createChatSdkBridge(...)` core call used by the local
backend, and the registration test proves the channel is wired:

```nc:run effect:build
pnpm run build
```
```nc:run effect:test
pnpm exec vitest run src/channels/imessage-registration.test.ts
```

Both must be clean. `imessage-registration.test.ts` imports the real channel
barrel and asserts the registry contains `imessage` — it goes red if the
`import './imessage.js';` line is missing or the barrel fails to evaluate. The
adapter loads neither backend's SDK at import (hosted `spectrum-ts` only in
`setup()`, local `chat-adapter-imessage` only in the factory), so the test
needs no package.

For the hosted backend, also run the full adapter suite — it includes an
integration block that exercises the real installed `spectrum-ts` (version,
exports, builders) and auto-skips when the package is absent:

```nc:run effect:test when:backend=hosted
pnpm exec vitest run src/channels/imessage.test.ts
```

## Local backend: Full Disk Access (macOS)

The adapter reads this Mac's `chat.db`, which requires Full Disk Access granted
to the Node binary the host runs under. The Node path is buried deep (e.g.
`~/.nvm/versions/node/v22.x.x/bin/node`), so open its folder in Finder to make
the drag-and-drop target obvious. Harmless off a desktop (SSH/headless) — it
just no-ops:

```nc:run effect:external when:backend=local
open "$(dirname "$(which node)")" 2>/dev/null || true
```

Then tell the user:

```nc:operator when:backend=local
Grant Full Disk Access to Node so iMessage can read your chat history:
1. Open System Settings > Privacy & Security > Full Disk Access.
2. Click +, then drag the "node" file from the Finder window that just opened.
3. Toggle it on, then come back here.
```

Stop and wait for the user to confirm Full Disk Access is granted before
continuing.

Now select the local backend in `.env`. The configure script owns this
upsert-and-remove (a plain set-if-absent env write can neither replace a stale
value nor delete a key, and a lingering hosted selector would shadow the
choice):

```nc:run effect:external when:backend=local
bash setup/channels/imessage-configure.sh local
```

## Hosted backend: device login (via photon.codes)

The provisioning flow needs the phone number you send iMessages from — it
registers that number with your project so the hosted line recognises you:

```nc:prompt owner_handle normalize:trim validate:^\+\d{8,15}$ when:backend=hosted
The phone number you iMessage from, in E.164 format — + followed by country code and number, no spaces or dashes (e.g. +14155551234).
```

Tell the user what's about to happen:

```nc:operator when:backend=hosted
Connect your hosted iMessage line (photon.codes):
1. A login URL and a short code will print below.
2. Open the URL in a browser, approve the device, and enter the code.
3. Setup then registers your number and prints the iMessage line Photon assigned to it. Send one message from your phone to that line — a number only enters routing after it has texted its line once.
4. Once the opt-in lands, setup finishes on its own and confirms your agent's iMessage number.
```

Run the device-login flow. It provisions the project, reuses its current secret
(regenerating only when the API returns none), registers your number, prints
the line to text and waits until that message opts the number in, and surfaces
the iMessage number you'll use — writing
`PHOTON_PROJECT_ID` + `PHOTON_PROJECT_SECRET` to `.env` and the assigned number
to `data/photon-auth.json`:

```nc:run effect:step when:backend=hosted
pnpm exec tsx scripts/photon-setup.ts setup --phone {{owner_handle}} --embedded
```

If the login times out, the code expired (~30 min) — re-run the step; a stored
token is reused. Check state any time with
`pnpm exec tsx scripts/photon-setup.ts status`.

Then select the hosted backend in `.env` — the Photon credentials already imply
hosted, but the explicit selector avoids ambiguity if local keys linger:

```nc:run effect:external when:backend=hosted
bash setup/channels/imessage-configure.sh hosted
```

## Restart

Restart the service so it loads the iMessage adapter and the backend config you
just wrote, and wait for its CLI socket before wiring:

```nc:run effect:restart
bash setup/lib/restart.sh
```

For the hosted backend, confirm the connection came up:
`grep "Photon channel connected" logs/nanoclaw.log | tail -1`.

## Resolve your iMessage handle

The agent greets you in the iMessage conversation tied to the handle you
message from — that handle is both your identity and the conversation address.
The hosted flow already collected it above; for the local backend, resolve it
now (email works too — whatever iMessage recognises):

```nc:prompt owner_handle validate:^(\+\d{8,15}|[^\s@]+@[^\s@]+\.[^\s@]+)$ when:backend=local
The phone number or email you iMessage from — a +E.164 number (e.g. +14155551234) or an email / Apple ID (e.g. you@icloud.com).
```

**Hosted first contact:** text your agent's iMessage number once (it was
printed above; also stored in `data/photon-auth.json`) before expecting any
message from it. This first text is required, not just convenient — the hosted
line can only message numbers that have already texted it (cold outbound is
rejected with `Target not allowed for this project`). Tell the user:

```nc:operator when:backend=hosted
Send one text — anything — from your phone to your agent's iMessage number (printed above). The hosted line can only reply to numbers that have texted it first, so its welcome message needs yours to arrive first.
```

iMessage is a native channel: it sends the raw handle as the conversation
address, with no channel prefix — so the messaging-group platform id is that
handle as-is:

```nc:run capture:platform_id
echo "{{owner_handle}}"
```

`owner_handle` and `platform_id` are what the owner-wiring step needs. The
welcome iMessage goes out through the adapter once the service is running — on
the local backend that needs Full Disk Access granted (above); on the hosted
backend it goes out via your photon.codes line after your first text.

## Next Steps

If you're in the middle of `/setup`, return to the setup flow now. Otherwise
`/init-first-agent` stands up an agent on your iMessage DM, or `/manage-channels`
wires it to an existing agent group.

## Channel Info

- **type**: `imessage` (one channel; the backend is local or hosted)
- **terminology**: iMessage has 1:1 "chats" (DMs) and group chats. Photon
  (hosted) calls each conversation a "space".
- **platform-id-format**: DM = your bare handle (E.164 phone, or email for
  local) — direct-addressable; the user id is `imessage:<handle>`. Group
  (hosted) = the opaque Spectrum space id.
- **how-to-find-id**: DMs use the counterpart's phone/email. Groups (hosted) are
  discovered on first message —
  `pnpm exec tsx scripts/q.ts data/v2.db "SELECT platform_id, name FROM messaging_groups WHERE channel_type='imessage'"`
- **supports-threads**: no
- **typical-use**: Interactive 1:1 chat — personal messaging
- **default-isolation**: One agent per install. Multiple DMs with the same
  operator can share an agent group; groups with other people should typically
  use `isolated` session mode.

### Hosted features

Markdown (native; `PHOTON_MARKDOWN=false` for plain text), file attachments in
and out (inbound staged into the session inbox, capped by
`PHOTON_MAX_INLINE_ATTACHMENT_BYTES`, default 20 MB), tapback reactions, read
receipts, typing indicators, and `ask_user_question` via `/approve` / `/reject`
slash replies. Optional `.env`: `PHOTON_MARKDOWN`, `PHOTON_TELEMETRY`,
`PHOTON_MAX_INLINE_ATTACHMENT_BYTES`, `PHOTON_DASHBOARD_HOST`,
`PHOTON_SPECTRUM_HOST`. Full table in [docs/imessage.md](docs.md).

## Troubleshooting

**The backend answer is rejected.** It must be exactly `local` or `hosted`,
lowercase. Local only exists on macOS — it reads this Mac's `chat.db` directly —
so on any other OS the platform check stops you and hosted is the only path.

**Local: outgoing works but nothing ever arrives.** Full Disk Access wasn't
granted to the *actual* Node binary the service runs under — with nvm the path
changes per Node version (`~/.nvm/versions/node/v22.x.x/bin/node`), so an old
grant silently stops covering a new binary. Re-open System Settings → Privacy &
Security → Full Disk Access, add the binary at `$(which node)`, then restart
the service.

**`spectrum-ts` not installed** (hosted) — re-run step 4
(`pnpm install spectrum-ts@11.0.0`) and restart.

**Device login times out** (hosted) — the code expires in ~30 min; re-run the
login step (a stored token is reused).

**`Target not allowed for this project`** (hosted) — intended: the line only
messages numbers that have texted it first. Text the agent's number once, then
retry (a welcome DM queued before that first text simply fails delivery).

**Your handle is rejected at the resolve step.** It must be a bare +E.164
number (`+14155551234` — no spaces, dashes, or parentheses) or, on the local
backend, an email/Apple ID. Use the exact handle you actually send iMessages
from — a number-vs-email mismatch means your messages never map to the wired
conversation.

**Adapter installed but silent.** Run
`pnpm exec vitest run src/channels/imessage-registration.test.ts` — red means
the barrel import or the package install drifted, so re-run the Apply steps.
If green, confirm the backend connected (hosted:
`grep "Photon channel connected" logs/nanoclaw.log`), restart the service
(`bash setup/lib/restart.sh`), then check `logs/nanoclaw.error.log`.

More in [docs/imessage.md](docs.md).

## Upgrading spectrum-ts (hosted)

`spectrum-ts` is pinned exactly because it ships breaking majors. To upgrade,
read the [release notes](https://github.com/photon-hq/spectrum-ts/releases) for
every version between the pins, bump the pin, reconcile
`src/channels/imessage.ts` against the new typings, then `pnpm run build` and
`pnpm exec vitest run src/channels/imessage.test.ts`. See
[docs/imessage.md](docs.md).