# Phase 04 — Device Gate: the ONBD-02 deep-link carrier + the ONBD-03 home-screen launch

**Deployed origin:** https://araharah-bot.araharah-bot.workers.dev/
**Deployed version:** `31138f79-3385-4079-a9a8-f1351da3b149` (`npm run deploy` — theme → web → `wrangler deploy` with `web/dist` as static assets + `set-webhook.mjs` re-arm)
**Status: PENDING REAL-DEVICE VERIFICATION — the phase does not close until every leg has an explicit verdict. Every leg below is currently `UNVERIFIED`; no device is attached to this environment. Do NOT fake device results.**

## What this gate decides

ONBD-02's carrier is the ONE requirement whose success depends on undocumented Telegram
client behaviour: the bot's OPEN button is a `web_app` inline button whose URL carries
`?dest=<plain-gazetteer-id>` (RESEARCH Pitfall 1 — `WebAppInfo` has exactly one field,
`url`, so `start_param` cannot ride an inline button). The webview reads the URL query
first, the signed `initData`'s `start_param` second, with one shared validation. Only a
real client proves Telegram actually delivers the button's query string into the webview.

## Automated half (already green — this deploy, 2026-10-23)

- `npm test -w web` — 57 passed, 0 failed (DP1–DP12 destination gates, HS1–HS9 home-screen
  gates, BA1–BA8 build gates incl. the NEW BA7 bot/web id-set parity gate + BA8 no-crypto gate,
  the extended GEO-03 storage gate incl. the explicit `web/src/search` pin)
- `npm test -w bot` — 65 passed, 0 failed (CR1–CR15 `/cari` payload gates; the deep-link
  contract's other half)
- `npm run search:corpus` — threshold PASS: top-3 68/68 (100%), negatives refused 7/7,
  refusal margin 0.643 < 0.72 (the D-14 close holds; lever: None)
- `npm run capture -w web` — **CAPTURE OK — 8/8 non-blank captures**, including the NEW
  `shell-dest-preload.png` (?mock=android&dest=suria-klcc → ARAHARAH-DEST
  `state=resolved` → the DESTINATION card rendered **Suria KLCC / Jalan Ampang, 50088
  Kuala Lumpur** over the live map, ADD TO HOME SCREEN in the strip). GEO-03 runtime
  probe: app storage surfaces empty after boot-to-live.
- Shipped-bundle canary (live origin, `cache: no-store`): `assets/main-B7xbFMG5.js`
  carries **all 30/30 gazetteer ids**, ZERO crypto tokens (`createHmac`/`crypto.subtle`/
  `sha256`/`HMAC(` absent), the ONBD-03 copy present. `web/dist/index.html` carries no
  harness markers (BA5/BA6 hold in production).

## Deploy canaries (2026-10-23, post-deploy)

| Canary | Result |
|--------|--------|
| `getWebhookInfo.url` | `https://araharah-bot.araharah-bot.workers.dev/telegram/webhook` (ends `/telegram/webhook`) ✓ |
| `getWebhookInfo.last_error` | **STALE** — "500 Internal Server Error" dated 2026-10-22 11:18 UTC (phase-3 era, BEFORE the 04-03 and 04-04 deploys); `pending_update_count: 0`. The field cannot clear until the next real update is delivered — re-read it during leg 1 and record what you see. |
| `getChatMenuButton` | `web_app` → `https://araharah-bot.araharah-bot.workers.dev/` ✓ (was un-armed on the first canary read — re-armed with `node bot/scripts/set-menu-button.mjs`) |
| `getMyCommands` | default scope + `all_private_chats` + `ms` scope all list `help`, `privacy`, `cari` ✓ (re-registered with `node bot/scripts/register-commands.mjs`. Note: a `language_code:"en"` lookup returns `[]` because en IS the language-agnostic default set — language-specific sets exist only for `ms`. This is Telegram's scoping semantics, not a registration failure.) |
| Unsigned webhook POST | **401** (the `X-Telegram-Bot-Api-Secret-Token` gate is live) ✓ |
| `MINI_APP_URL` (wrangler vars) | `https://araharah-bot.araharah-bot.workers.dev` — equals the deployed origin exactly ✓ (binding visible in the deploy log) |
| Secrets | never echoed — the bot token was only ever concatenated into Bot API URLs, never printed ✓ |

## Bot API 10.2 origin prerequisite (hard, blocking)

- [ ] **@BotFather's Mini App URL == `https://araharah-bot.araharah-bot.workers.dev`.** The
  Bot API cannot read the BotFather-side value, so this half is verified on the device: if
  the origins mismatch, Bot API 10.2 silently no-ops every `Telegram.WebApp.*` call and
  EVERY leg below fails with a blank-shell symptom. The bot-side origins (menu button,
  OPEN button via `MINI_APP_URL`) are confirmed equal above — confirm the BotFather side
  matches while walking leg 1.
  Observed / Symptom: ______________________________________

## The six device legs (each: an explicit verdict + observation)

### 1. ONBD-02 — Android (the carrier that matters)

- [ ] Send `/cari KLCC` in the bot's chat → a NATIVE venue card for Suria KLCC appears with
  "OPEN IN ARAHARAH" + 2–4 alternates.
- [ ] Tap OPEN → the Mini App opens **with the destination PRELOADED**: the DESTINATION card
  shows **Suria KLCC / Jalan Ampang, 50088 Kuala Lumpur** over the live map.
- [ ] FAIL SYMPTOMS: a blank map, an empty card stack, or "Destination unavailable" = the
  `web_app` button's query string did not survive into the webview (Carrier A collapsed →
  pull the carrier-swap lever: `miniAppUrlFor(origin, id)` in `bot/src/bot/commands/cari.ts`
  is the ONE place the link is built).
- [ ] While here: re-read `getWebhookInfo.last_error` — it should now be cleared (the
  pre-deploy stale error dated 2026-10-22 must not reappear).
  Verdict: `UNVERIFIED` (needs Android device)
  Client version / OS: ____________  Observed / Symptom: ______________________________________

### 2. ONBD-02 — iOS

- [ ] The same flow on an iPhone: `/cari KLCC` → venue card → OPEN → the destination card
  shows Suria KLCC preloaded.
- [ ] Expect `checkHomeScreenStatus` to report `"unknown"` (iOS platform behaviour — see
  leg 4; NOT a failure).
  Verdict: `UNVERIFIED` (needs iOS device)
  Client version / OS: ____________  Observed / Symptom: ______________________________________

### 3. ONBD-02 — Telegram Desktop

- [ ] The same flow on Desktop: `/cari KLCC` → venue card → OPEN.
- [ ] Desktop has no Telegram geolocation (phase 3's issue #77), so observe the DESTINATION
  CARD specifically — the location half is phase 3's separate matrix and is NOT this leg.
  The boot lands on the denied/awaiting-pin location card first; send a chat pin (attach →
  Location) to push the chain live, and the destination card then holds the center register.
- [ ] FAIL SYMPTOM: "Destination unavailable" or a blank map.
  Verdict: `UNVERIFIED` (needs Desktop client)
  Client version / OS: ____________  Observed / Symptom: ______________________________________

### 4. ONBD-03 — home screen add + launch

- [ ] With the app open, tap the app's "ADD TO HOME SCREEN" affordance (or Telegram's own
  "Add to Home Screen" menu item) → the icon appears on the phone's home screen.
- [ ] Close the app fully → tap the icon → the app opens into the SEARCH-READY state: the
  map renders, the strip shows its normal boot state, NO destination, NO crash, NO blank map
  (D-12: the startapp-less boot is unchanged).
- [ ] On iOS, `checkHomeScreenStatus` reports `"unknown"` — that is the DOCUMENTED platform
  limitation (Telegram-iOS #1729, closed as expected behaviour). The affordance still shows
  the neutral "ADD TO HOME SCREEN" prompt. This MUST NOT be recorded as a failure.
- [ ] On Android, after adding, the affordance should HIDE (status `"added"`) — record
  whether it did.
  Verdict: `UNVERIFIED` (needs a phone)
  Client version / OS: ____________  Observed / Symptom: ______________________________________

### 5. The honest unknown-id state

- **Carrier note (orchestrator, 2026-10-24):** a plain browser CANNOT observe this leg —
  with no initData the boot stops at the session wall (denied card) before the destination
  reader runs. Verified live 2026-10-24: `?dest=not-a-real-place` in desktop Chrome →
  the denied card (`leg5-browser-sessionwall.png`). That is correct off-Telegram behavior,
  NOT this leg's verdict.
- **On-device procedure:** in ANY chat, send yourself the deep link
  `https://t.me/arah2bot?startapp=not-a-real-place` and tap it — Telegram opens the Mini
  App with `start_param=not-a-real-place` (the secondary carrier), the session validates,
  and the reader must show the honest surface.
- [ ] Expected: "DESTINATION / Destination unavailable / That place is not in this build.
  Search again from the bot." — never a blank map, never a fabricated pin, never a crash.
  Verdict: `UNVERIFIED`
  Observed / Symptom: ______________________________________

### 6. The honest refusal

- [ ] Send `/cari Kuching` in the chat → a plain-text reply naming the v1 area, with NO venue
  card, NO inline keyboard, NO pin (SRCH/D-13 negative-refusal law, live on the real bot).
  Verdict: `UNVERIFIED`
  Observed / Symptom: ______________________________________

## If a leg fails

- Legs 1–3 (carrier): pull the carrier-swap lever — `miniAppUrlFor(origin, id)` in
  `bot/src/bot/commands/cari.ts` is the single place the deep link is built (04-03 kept it
  swappable for exactly this contingency). The webview reader already accepts BOTH carriers.
- Leg 4: the affordance is behind the Bot API 8.0 guard — record the client's Bot API
  version (`wa.version`) if it no-ops.
- Record the verdict inline above, then update `.planning/STATE.md` "Blockers/Concerns"
  (the executor leaves this to the orchestrator) — the phase stays OPEN on any
  FAIL/UNVERIFIED, never silently closed on unverified hardware.

---

*Phase: 04-destination-search-kl-gazetteer — plan 04-04 blocking gate*
*Automated legs + deploy: 2026-10-23; physical legs: pending user*