@www.hyperlinks.space/program-kit 1.2.91881 → 18.18.18

package/docs/security_raw.md

@@ -1,345 +0,0 @@
-# Security Model: Telegram-First Wallet
-
-## Goals
-
-- Create wallets inside the Telegram Mini App.
-- Let users access the **same wallet** from:
-  - Telegram on any device.
-  - Other platforms (web / desktop / native) via **Login with Telegram**.
-- Keep custody with the **user** (mnemonic as ultimate root of trust), while using Telegram features to improve UX.
-
-This document describes the current high-level design; it is not a formal audit.
-
----
-
-## Key Concepts & Storage
-
-**Key terms**
-
-- **Mnemonic (seed phrase)**: Ultimate secret that controls the wallet. If lost, funds are lost; if leaked, funds are at risk.
-- **Wallet master key**: Device-specific key derived from the mnemonic and stored only on that device.
-- **Wallet seed cipher**: Encrypted blob that contains the wallet seed (or a seed-derived secret), usable only together with the wallet master key.
-- **Telegram CloudStorage**: Per-user, per-bot key–value store synced via Telegram servers. Suitable for non-secret data or ciphertext.
-- **Telegram SecureStorage**: Per-device secure storage, backed by iOS Keychain / Android Keystore, intended for small sensitive values like tokens and keys (see [Mini Apps docs](https://core.telegram.org/bots/webapps#securestorage)).
-
-We **never store raw mnemonics** on our backend or in Telegram CloudStorage.
-
----
-
-## I. Wallet Creation in Telegram
-
-Flow when a user creates a wallet for the first time in the Telegram Mini App on a device:
-
-1. **Generate mnemonic on the device**
-   - The Mini App generates a new mnemonic locally (client-side).
-   - The user is shown the mnemonic once and asked to write it down for lifelong backup.
-
-2. **Derive wallet master key (device-local)**
-   - From the mnemonic, the app derives a **wallet master key** (e.g. via a BIP-style KDF / HKDF).
-   - This master key is stored **only** in Telegram `SecureStorage` on that device.
-   - Because `SecureStorage` is backed by **Keychain / Keystore**, the key is:
-     - Encrypted at rest.
-     - Bound to this device + Telegram app.
-
-3. **Create and store wallet seed cipher (cloud)**
-   - The app creates a **wallet seed cipher**:
-     - `seed_cipher = Encrypt(wallet_seed_or_root, wallet_master_key)`.
-   - `seed_cipher` is stored in Telegram `CloudStorage` under this bot for this user.
-   - CloudStorage contains **only ciphertext**, never raw seed or keys.
-
-4. **Persist wallet mapping in our backend**
-   - Our backend stores a record like:
-     - `telegram_username` (Telegram username, treated as unique in our system),
-     - `wallet_address` (public address),
-     - metadata (creation time, network, etc.).
-   - No mnemonics or master keys are saved server-side.
-
-**Properties**
-
-- The **first Telegram device** has everything needed to use the wallet:
-  - Master key in `SecureStorage`.
-  - Seed cipher in `CloudStorage`.
-- If the app is reinstalled on the **same device**, we can:
-  - Recover the master key from `SecureStorage` (if Telegram restores it).
-  - Decrypt the seed cipher for a smooth UX without re-entering the mnemonic.
-- If `SecureStorage` is wiped, the user must re-enter the mnemonic.
-
----
-
-## II. New Telegram Device Authorization
-
-When the same user opens the Mini App on **another Telegram client** (new phone/tablet):
-
-1. **Detect existing wallet**
-   - Using `initData` / backend lookup, we see that this `telegram_username` already owns at least one `wallet_address`.
-
-2. **Check device SecureStorage**
-   - On this **new device**, `SecureStorage` is empty for our bot (no wallet master key yet).
-   - We may still see the `seed_cipher` in `CloudStorage` (it is synced across user devices), but without a master key it is useless.
-
-3. **Ask user for mnemonic to authorize this device**
-   - The Mini App prompts the user to enter their mnemonic.
-   - From the mnemonic we derive a **new device-specific wallet master key** and store it in this device’s `SecureStorage`.
-   - Optionally, we re-encrypt and update the `seed_cipher` for this device; but the canonical root of trust remains the mnemonic.
-
-**Result**
-
-- Each Telegram device gains access only after the user proves knowledge of the mnemonic once.
-- Loss of a device does **not** affect other devices, as long as the mnemonic is safe.
-
----
-
-## III. Other Platforms (Outside Telegram)
-
-For platforms outside Telegram (web, desktop app, native mobile app not running inside Telegram), we:
-
-1. **Authenticate via Telegram**
-   - Use **Telegram Login for Websites** (see [login widget docs](https://core.telegram.org/widgets/login)) in a browser or embedded WebView.
-   - The login widget:
-     - Shows a Telegram-branded authorization UI where the user confirms sharing their Telegram identity with our site.
-     - After success, returns a signed payload containing `id`, `first_name`, `last_name`, `username`, `photo_url`, `auth_date`, and `hash`.
-   - On our backend we verify the `hash` using HMAC-SHA-256 with the SHA-256 of the bot’s token as a key, as described in the official docs.
-   - This works on:
-     - **Desktop browsers** (Chrome, Firefox, Safari, Edge, …),
-     - **Mobile browsers** on **iOS and Android**,
-     - In-app WebViews (e.g. inside a native app’s web login screen).
-
-   > For pure native iOS/Android apps, we typically embed a small web login page (with the widget) or open the system browser, then pass the verified Telegram identity back into the app.
-
-2. **Lookup existing wallet**
-   - Once Telegram login succeeds, we resolve `telegram_username` in our DB.
-   - If there is an associated `wallet_address`, we know this user already owns a wallet.
-
-3. **Authorize the device with the mnemonic**
-   - Because we are **outside Telegram**, we do not have Telegram’s `SecureStorage`.
-   - We therefore ask the user to **enter the mnemonic** to authorize this new platform.
-   - The app derives a **local wallet master key** from the mnemonic and stores it using the platform’s secure storage:
-     - iOS: Keychain
-     - Android: Keystore
-     - Desktop: DPAPI / Keychain / Keyring, depending on OS
-     - Web: WebCrypto + IndexedDB (with the usual caveats around user clearing storage).
-
-**Result**
-
-- Telegram login is used purely as an **identity layer** (“who is this user?”).
-- The **mnemonic** is still required to authorize a completely new platform.
-- Our backend never receives the raw mnemonic; only derived public keys / addresses.
-
----
-
-## IV. Android / iOS (Single App, Telegram‑Centric Flow)
-
-We ship **one app** (the current Expo app at repository root) to iOS/Android stores. On mobile, the app acts as a shell that:
-
-- Explains why wallet creation happens in Telegram.
-- Sends the user into the Telegram Mini App to actually create the wallet.
-- Then uses **Telegram Login for Websites** + our backend to recognize the user and their wallet.
-
-### Database: user identification (Telegram username–centric)
-
-In the backend we maintain a `users` table (or equivalent) with at least:
-
-- `telegram_username` – Telegram username, treated as unique in our system.
-- `wallet_address` – current wallet address owned by this username.
-
-The mobile app never needs to store the mnemonic or keys; it only needs the `telegram_username` and `wallet_address` retrieved from the backend after Telegram login.
-
-### A. New user on iOS/Android (no wallet yet)
-
-1. **App start → “Log in with Telegram” screen**
-   - Shown when there is no linked `telegram_username` in local app storage.
-   - Content:
-     - Title: “Create your wallet in Telegram”.
-     - Short text summarizing benefits:
-       - “Wallets are created **inside Telegram**, we never see your seed phrase.”
-       - “Your keys are stored using Telegram **SecureStorage + CloudStorage** on your devices.”
-       - “You can access the same wallet from Telegram, web, and this app.”
-     - UI:
-       - Primary button: **“Open Telegram to create wallet”**.
-       - Secondary button (dimmed / smaller): **“I already created my wallet in Telegram”** (goes to login widget, see flow B).
-   - Action on primary:
-     - Deep link to Mini App, e.g. `https://t.me/<bot_username>?startapp=wallet_onboarding`.
-
-2. **Telegram Mini App: wallet creation (same as section I)**
-   - Generate mnemonic, show/confirm it.
-   - Derive wallet master key → store in `SecureStorage`.
-   - Encrypt wallet seed → store cipher in `CloudStorage`.
-   - Call backend `register_wallet(telegram_username, wallet_address)` which:
-     - Creates a new `users` row.
-     - Stores `telegram_username`, `wallet_address`.
-   - Show a completion screen:
-     - “Your wallet is ready in Telegram.”
-     - Instruction: “Return to the app and tap ‘I already created my wallet’ to connect.”
-
-3. **Back in iOS/Android app → “Log in with Telegram” (Telegram login widget)**
-   - User returns to the app and taps **“I already created my wallet in Telegram”** (or simply “Log in with Telegram”).
-   - App opens an embedded WebView or browser page with **Telegram Login for Websites**:
-     - Widget asks the user to confirm sharing their Telegram identity.
-     - After success, backend receives a signed payload and validates it as in section III.
-     - Backend extracts `username` from the payload and looks up `telegram_username` in `users`:
-       - If found, returns `{ telegram_username, wallet_address, ... }` to the app.
-       - If not found (edge case: user logged in before creating wallet), the app can:
-         - Show “No wallet yet, please create it in Telegram first” and show the **Open Telegram** button again.
-
-4. **App state after linking**
-   - The app stores `telegram_username` and `wallet_address` in its local storage.
-   - It can now:
-     - Display balances / history via backend or blockchain APIs.
-     - For signing, either:
-       - Redirect back to Telegram Mini App on an action (“Sign in Telegram”), or
-       - In a future advanced flow, allow the user to import mnemonic locally (explicit, non‑default).
-
-### B. Existing Telegram wallet user installing iOS/Android app
-
-For a user who already has a Telegram wallet (created earlier in the Mini App):
-
-1. **App start → same “Log in with Telegram” screen**
-   - The screen is identical, but the text emphasizes:
-     - “If you already created your wallet in Telegram, just log in below.”
-   - Action:
-     - User taps **“I already created my wallet in Telegram”** / **“Log in with Telegram”**.
-
-2. **Telegram Login for Websites**
-   - Same widget flow as in A.3.
-   - Backend verifies the payload and looks up `telegram_username` in `users`:
-     - If a row exists → return `{ telegram_username, wallet_address }` to the app.
-     - If no row exists → the app suggests:
-       - “We don’t see a wallet yet. Please open Telegram to create one.” and shows the **Open Telegram to create wallet** button.
-
-3. **After login**
-   - The app saves `telegram_username` + `wallet_address` locally and shows the wallet UI.
-   - No mnemonic is ever handled by the app in this default flow.
-
-**Key points of this model**
-
-- There is **one app** (repository root), not a separate companion; mobile just has a Telegram-centric onboarding path.
-- All wallet creation and key material remain in the Telegram Mini App and its SecureStorage/CloudStorage environment.
-- The iOS/Android app uses:
-  - **Telegram Login for Websites** to learn “who is this user?” (via `username`),
-  - The backend’s `users` table (`telegram_username`, `wallet_address`) to link that identity to a wallet.
-- Users who don’t want to connect Telegram can only use future “local‑only” features if we add them explicitly; the default path is Telegram‑first. 
-
----
-
-## V. Serverless Transaction Flow & Bot‑Based Confirmation
-
-We assume a **serverless backend** (e.g. Vercel / Cloudflare / Lambda functions) with:
-
-- Stateless HTTP handlers (API routes).
-- A persistent datastore (serverless Postgres / KV / Dynamo, etc.) for:
-  - `users` (`telegram_username`, `wallet_address`, …).
-  - `pending_transactions` (id, telegram_username, payload, status, timestamps).
-
-All **signing** happens on the client side (Telegram Mini App or other wallet environment); serverless functions never hold private keys.
-
-### 1. Initiating a transaction (any client)
-
-From any frontend (Telegram Mini App, web, iOS/Android app):
-
-1. Client sends a request to a serverless endpoint, e.g. `POST /api/tx/create`:
-   - Body includes:
-     - `telegram_username` (or derived from Telegram auth),
-     - transaction intent (action type, amount, asset, destination, etc.).
-2. Serverless handler:
-   - Validates the request and user identity.
-   - Creates a `pending_transactions` row with:
-     - `id` (e.g. UUID or short code),
-     - `telegram_username`,
-     - serialized transaction payload (what needs to be signed),
-     - status = `pending`.
-   - Uses the **Telegram Bot API** to send a push message to the user:
-     - “New action requires confirmation: <summary>”.
-     - Inline button: **“Review & confirm”** linking to:
-       - Recommended: Mini App deep link, e.g.\
-         `https://t.me/<bot_username>?startapp=tx_<id>`
-       - Optionally, a web URL, e.g.\
-         `https://app.hyperlinks.space/tx/<id>`.
-
-### 2. Confirmation page (Telegram Mini App)
-
-When the user taps the button in the bot message and opens the Mini App:
-
-1. The Mini App receives `start_param = tx_<id>` via `initData`.
-2. It calls a serverless endpoint, e.g. `GET /api/tx/<id>`:
-   - Backend verifies the request using `initData`/`hash` and checks that:
-     - `pending_transactions.id` exists,
-     - `telegram_username` from DB matches the Mini App user,
-     - status is `pending`.
-   - Backend returns the transaction details (read‑only).
-3. Mini App shows a **confirmation UI**:
-   - Clear summary: amounts, assets, destination, fees, network.
-   - Buttons: **Confirm** / **Reject**.
-
-### 3. Signing & broadcasting (inside Telegram)
-
-On **Confirm** from the Mini App:
-
-1. Mini App reconstructs/derives the transaction to be signed using:
-   - The locally available wallet (seed/master key in `SecureStorage`).
-   - The payload from `pending_transactions`.
-2. Mini App signs the transaction **locally** using the wallet key.
-3. Mini App sends a request to a serverless endpoint, e.g. `POST /api/tx/<id>/complete` with:
-   - `id`,
-   - signed transaction payload (or only the resulting transaction hash if the client broadcasts itself),
-   - confirmation that user accepted.
-4. Serverless handler:
-   - Verifies that the caller is the right `telegram_username` and that tx is still `pending`.
-   - Either:
-     - Broadcasts the signed transaction to the chain (if backend has RPC access and broadcasting doesn’t leak secrets), **or**
-     - Simply records the fact that this transaction was confirmed and uses a separate service / worker to broadcast.
-   - Updates `pending_transactions.status` to `confirmed` (or `failed` with reason).
-
-The originating client (web / mobile app) can poll or subscribe for status changes on `pending_transactions` to reflect completion.
-
-### 4. Optional: web‑only confirmation page
-
-For users who click a **web URL** from the bot instead of the Mini App:
-
-- The confirmation page:
-  - Uses **Telegram Login for Websites** to authenticate the user (retrieve `username`).
-  - Loads the `pending_transactions` row by `id` + `telegram_username`.
-  - Shows the same confirmation UI.
-- For signing, we recommend **redirecting back to Telegram** for actual key usage:
-  - On **Confirm**, the web page can:
-    - Either deep‑link into the Mini App with the same `tx_<id>`, or
-    - Ask the user to enter the mnemonic or connect an external wallet (advanced, non‑default).
-- This keeps the **self‑custodial key** anchored in the Mini App by default, while still allowing purely web‑based flows where the user explicitly opts into entering their mnemonic or linking another wallet.
-
-### Serverless guarantees
-
-- All backend logic is stateless across requests; long‑lived data lives in `users` and `pending_transactions`.
-- No private keys or mnemonics are ever stored or derived in serverless functions.
-- Bot pushes and confirmation flows are coordinated exclusively via:
-  - Telegram Bot API (for notifications),
-  - Telegram Mini App (for secure signing with SecureStorage),
-  - Telegram Login (for identity on web / mobile).
-
-This model keeps transaction approvals **user‑driven and key‑local** (inside Telegram or another explicit wallet) while still fitting neatly into a serverless architecture. 
-
----
-
-## Security Properties
-
-- **Self-custody:**
-  - The mnemonic is the **only ultimate key**; if the user keeps it offline and safe, they retain full control over funds.
-  - Neither our backend nor Telegram can unilaterally move funds without the mnemonic / keys.
-
-- **Device-local keys:**
-  - Each device has its own **wallet master key** stored in that device’s secure storage (Telegram SecureStorage or OS keystore).
-  - Compromise of one device does **not** automatically compromise others.
-
-- **Cloud data is ciphertext only:**
-  - `Wallet Seed Cipher` in CloudStorage is encrypted with a master key that lives only in secure storage on a device.
-  - An attacker with only CloudStorage access cannot derive the mnemonic.
-
-- **Cross-platform restore requires mnemonic:**
-  - Any **new environment** (new Telegram device with empty SecureStorage or any non-Telegram platform) requires the mnemonic once.
-
----
-
-## Limitations & Notes
-
-- If the **mnemonic is lost**, there is no recovery (by design) – it is the self-custodial root.
-- If a device with a master key is compromised, an attacker can act as the owner from that device until the user moves funds to a new wallet.
-- Telegram `SecureStorage` is documented for **iOS and Android**; behavior on other Telegram clients may differ.
-- Telegram Login for Websites is an **authentication mechanism only** – it does not give access to keys or the mnemonic itself, and cannot replace the mnemonic for wallet authorization.

package/docs/timing_raw.md

@@ -1,63 +0,0 @@
-# Raw timing estimate
-
-**Purpose:** Rough “time till app finish” and **MVP launch** based on commit history, plans, and the front app.
-
-**Important:** The app will not be sent to platforms (store/listing) before it is fully finished. So **MVP launch = full product launch**, and the realistic estimate is **3 months**.
-
-## Transfer layout to repository root (TypeScript) — build on new architecture
-
-The goal is **not** to finish the Flutter app in `front/`. The **Flutter** app in `front/` is the **reference layout** (web pages, flows, structure). The work is to **transfer that layout and flows into the repository root app in TypeScript** and make everything work there, with **security plan compliance** (see `docs/security_plan.md`). The production Mini App is the TS app at repository root (Expo/React), backed by the same repo’s API and DB.
-
-### Pages to implement in repository root (TS) — from `front/` reference
-
-- **Bootstrap** – initData auth, config from API, wallet warm-up.
-- **Main** – home / hub after bootstrap.
-- **Send** – send flow (security plan: pending tx, confirmations).
-- **Swap** – swap flow (rate state, rotation, etc. from root plan).
-- **Wallets** – list/create/manage; wallet creation and nickname (security plan: mnemonic flow, device auth, wallet registration).
-- **Apps** – apps design, brand book alignment.
-- **AI** – AI & search bar; response formatting; scrolling fix; wired to `app` AI routes.
-- **Get** – get flow.
-- **Trade** – trade page.
-- **Creators** – creators content.
-- **Mnemonics** – mnemonic display/backup (security plan).
-- **Wallet panel** – wallet panel page.
-
-### Services / wiring in repository root (TS)
-
-| Concern | Role | Backend / compliance |
-|--------|------|-----------------------|
-| **Auth** | Telegram initData auth (e.g. app’s telegram/init endpoint). | initData validation and user upsert (Phase 0–1). |
-| **AI** | Chat with AI via same-origin `/api/ai` (or app’s AI route). | Already in `app`; ensure config, keys, and error handling in prod. |
-| **Wallet** | Mnemonic generation, storage, key derivation (client-side). | Security plan: SecureStorage/CloudStorage, wallet registration (`POST /api/wallet/register`), device auth flow; optional TonConnect later. |
-
-### API surface (in repository root)
-
-- **`/api/telegram`** (or init) – initData validation, user upsert.
-- **`/api/ai`** – AI proxy; used by the TS app.
-
-All of the above must work end-to-end in the TS app and stay within the security model (initData-only auth, no raw secrets to server, wallet registration and pending tx where applicable).
-
----
-
-## Short and Medium term backlogs
-
-- **`app/short_term_backlog.md`** (3 items): Response formatting, app theme, AI & search bar.
-- **Root `medium_term_backlog.md`** (backlog): Header indent bug, rotation on swap, edit-interval healthcheck, ticker link, scrolling in AI widget, bot parts isolation, ld timeout, “AI bd”, hovers, languages, favicon, wallet creation & nickname, jetton lockup, theme in Chrome, “Bd”, wallet creation, apps design, plan users BD for search, brand book, fixes, starting rewards, feed item types, PAY BY QR, swap long rate state, swaps, tokens.
-
-**Security:** All features above are delivered **with security plan compliance** (Phase 0–2: initData validation, wallet creation and registration, device auth, pending transactions, TonConnect if in scope, etc.). No “MVP without security”; the launch build is compliant.
-
----
-
-## Time estimate
-
-Completion order and stages:
-
-| Stage | Scope | Estimate | Notes |
-|-------|--------|----------|--------|
-| **1** | **Security plan implementation** | **~3 weeks** | Phase 0 (validation, DB), Phase 1 (wallet creation, device auth, register), Phase 2 (pending tx, confirmations). |
-| **2** | **App (TS) – pages & UX** | **~3 weeks** | Transfer layout from `front/` and implement all pages in repository root app (send, swap, wallets, apps, AI, get, trade, creators, mnemonics, wallet panel); layout and navigation solid. |
-| **3** | **App (TS) – services & wiring** | **~3 weeks** | Auth, AI, and wallet flows in repository root app; backend alignment; errors and edge cases. |
-| **4** | **Integration, testing, finishing** | **~3 weeks** | E2E, platform checks, store/listing readiness, app/plan and root plan items (formatting, theme, bugs, features). |
-
-**MVP launch (full finish, platform-ready):** **~3 months** (12 weeks).

package/docs/tma_logo_bar_jump_investigation.md

@@ -1,69 +0,0 @@
-# TMA logo bar jump on input focus – fix
-
-## Problem
-
-When the user focuses the AI & Search input in the Telegram Mini App, the keyboard opens and the logo bar jumps (shifts down then up). The whole column (logo bar + main + bottom bar) was also scrollable.
-
-**Cause:** Viewport height shrinks when the keyboard opens; if root/body height follows that, the layout reflows and the host may scroll the window → logo bar moves. Reacting on every browser resize (e.g. Visual Viewport) caused intermediate reflows before the final state.
-
-## What we tried (dismissed or replaced)
-
-| Approach | Outcome |
-|----------|--------|
-| **Position fixed for logo bar** | Reverted. Did not fix the shift inside TMA. |
-| **Root height from `viewport.stableHeight()`** (pin layout to stable height so it doesn’t change on keyboard) | Not used. We chose “single update when TMA reports” instead. |
-| **Visual Viewport API** (`window.visualViewport` resize + `body.style.height` + `--vh` + `scrollTo(0,0)` on every resize) | Replaced. Caused intermediate reflows; keyboard open triggered multiple resize events before the final size. |
-| **Scroll lock only** (prevent window scroll) | Necessary but not sufficient on its own; layout still shifted. |
-
-## Solution
-
-Use **only the TMA viewport API**. When the keyboard opens, change nothing until TMA sends **viewport_changed**; then apply the new height and scroll reset in one turn.
-
-### 1. TMA viewport (Telegram.tsx)
-
-- After `viewport.mount()`:
-  - **`viewport.bindCssVars()`** – SDK sets/updates `--tg-viewport-height`. Layout height is driven by this.
-  - **`on("viewport_changed", handler)`** – Run **`window.scrollTo(0, 0)` only when `payload.is_state_stable`** (or `payload.isStateStable`). Do not reset scroll during drag or animation.
-- **Window scroll lock** – `window.addEventListener("scroll", …)` → if `scrollY > 0` then `scrollTo(0, 0)`.
-- **viewport-fit=cover** on the viewport meta (iOS).
-
-### 2. CSS (global.css)
-
-- **html**: `height: 100%`, `overflow: hidden`, `overscroll-behavior: none`.
-- **body**, **#root** / **[data-expo-root]**: `height: var(--tg-viewport-height, 100%)`, `min-height: var(--tg-viewport-height, 100%)`, `overflow: hidden` (body also `overscroll-behavior: none`).
-
-### 3. Layout
-
-- **Root View** (_layout.tsx): `overflow: "hidden"`, flex column.
-- **Logo bar** (GlobalLogoBar): `flexShrink: 0`.
-- **Main**: `flex: 1`, `minHeight: 0`.
-
-### 4. TMA (telegramWebApp.ts)
-
-- **readyAndExpand()**: `expand()`, `setHeaderColor("#000000")`, `setupSwipeBehavior({ allow_vertical_swipe: false })`, `disableVerticalSwipes?.()`.
-
-## viewport_changed payload
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `height` | number | Viewport height. |
-| `width` | number (optional) | Viewport width. |
-| `is_expanded` | boolean | Viewport expanded. |
-| `is_state_stable` | boolean | State stable (no change in the next moment). |
-
-Only call `scrollTo(0, 0)` when **is_state_stable** is true. Support both `is_state_stable` and `isStateStable` (bridge payload shape).
-
-## Summary: keep vs dismiss
-
-**Keep in the stack:**
-
-- TMA-only viewport logic: `viewport.bindCssVars()`, `on("viewport_changed", …)` with **is_state_stable** check before `scrollTo(0, 0)`, window scroll lock, viewport-fit=cover.
-- CSS: `--tg-viewport-height` for body and #root, overflow/overscroll locked on html/body and root.
-- Root `overflow: "hidden"` and logo bar `flexShrink: 0`.
-- readyAndExpand (expand, setHeaderColor, setupSwipeBehavior, disableVerticalSwipes).
-
-**Dismiss as try-outs:**
-
-- Any use of **Visual Viewport API** for TMA (resize/scroll listeners, `body.style.height`, `--vh`) — replaced by TMA viewport + bindCssVars + viewport_changed.
-- **Position fixed** for the logo bar — reverted.
-- **stableHeight**-based root height — not used; we use bindCssVars (current height) and rely on **is_state_stable** to avoid resetting scroll until the viewport is stable.

package/docs/update.md

@@ -1,205 +0,0 @@
-# Instant App Updates Plan
-
-This plan defines how to deliver near-instant updates for the app with minimal user friction, while keeping binary releases for native-level changes.
-
-## 1) Update Strategy (Two Lanes)
-
-- **Lane A: OTA updates (default, fast path)**
-  - Use Expo EAS Update to deliver JavaScript/TypeScript and asset changes.
-  - No reinstall required.
-  - Target latency: minutes or less after publish.
-- **Lane B: Binary releases (slow path)**
-  - Use installer/store release only when native/runtime changes are required.
-  - Triggered through `releases/**` and GitHub Release workflow.
-
-Decision rule:
-
-- JS/UI/business logic/assets changes -> OTA
-- Native dependency/plugin/permission/runtime changes -> binary release
-
-## 2) Current Project Baseline
-
-Already configured:
-
-- `app.json` has `updates.url`.
-- `app.json` has `runtimeVersion.policy = appVersion`.
-- `eas.json` has channels:
-  - preview profile -> `main`
-  - production profile -> `production`
-
-Implication:
-
-- Binaries built on a channel only receive updates from that same channel and compatible runtime version.
-
-## 3) Target Architecture for "Instant" Updates
-
-1. Developer merges code to branch.
-2. CI publishes OTA update to EAS (`main` or `production` branch/channel).
-3. App receives update check trigger (foreground/resume and optional push signal).
-4. App fetches update, then applies at safe point (next app restart or immediate reload based on policy).
-
-For binary-only updates:
-
-1. `releases/builder/build_MMDDYYYY_HHMM/` (or Forge under `releases/forge/...`) changes.
-2. GitHub workflow dedupes and creates Release if new.
-3. Workflow calls `POST /api/releases` webhook.
-4. Backend notifies clients that binary update is available.
-
-## 4) Server and CI Setup
-
-### 4.1 GitHub Secrets
-
-Add repository secrets:
-
-- `EXPO_TOKEN` (required for EAS CLI in CI)
-- `RELEASE_WEBHOOK_URL` (for binary-release notification)
-- `RELEASE_WEBHOOK_TOKEN` (for endpoint auth)
-
-### 4.2 OTA Workflow (GitHub Actions)
-
-Create workflow `.github/workflows/eas-update.yml`:
-
-- Trigger:
-  - `push` to selected branches (`main`, optionally `release/*`)
-  - Optional `workflow_dispatch`
-- Path filters to avoid unnecessary publishes (example):
-  - include app source and config paths
-  - exclude `releases/**`
-- Steps:
-  1. checkout
-  2. setup node
-  3. install deps (`npm ci` in repository root)
-  4. publish OTA:
-     - branch `main` for preview/internal
-     - branch `production` for production
-  5. output EAS update group id and URL
-
-Recommended publish command:
-
-- `npx eas update --branch <branch> --non-interactive --message "<commit message>"`
-
-### 4.3 Binary Workflow (Already Planned)
-
-Keep `releases/**` workflow with dedupe:
-
-- If release exists, skip.
-- If new, create GitHub Release and upload assets.
-- Call `POST /api/releases`.
-
-## 5) App Runtime Behavior
-
-Implement client update behavior with `expo-updates`:
-
-1. On app start and on foreground:
-   - call `checkForUpdateAsync()`
-2. If update exists:
-   - call `fetchUpdateAsync()`
-3. Apply policy:
-   - silent + apply on next launch (default safe)
-   - or prompt user and reload now (`reloadAsync()`)
-
-Suggested policy:
-
-- **Critical fixes:** prompt and reload now
-- **Normal updates:** fetch silently and apply next launch
-
-Minimum checks:
-
-- On cold start
-- On foreground if last check older than threshold (for example 10 minutes)
-
-## 6) Push-Accelerated Detection (Optional but Preferred)
-
-OTA itself is already fast, but to reduce time further:
-
-- Add backend push trigger when CI publishes OTA.
-- App receives push and immediately runs update check.
-
-Channels you can use:
-
-- Expo Push Notifications
-- Firebase Cloud Messaging
-- WebSocket/SSE (if app has persistent session)
-
-Fallback remains foreground polling.
-
-## 7) Versioning and Compatibility Rules
-
-With `runtimeVersion.policy = appVersion`:
-
-- OTA is only delivered to binaries with matching `expo.version`.
-- When native changes occur:
-  - bump app version
-  - ship new binary
-  - publish OTA for that new runtime afterward
-
-Team rule:
-
-- Do not bump app version for pure JS hotfixes unless intentionally creating a new runtime.
-
-## 8) Security and Reliability
-
-- Protect `/api/releases` using token and optional HMAC.
-- Make webhook handler idempotent by `release_id`.
-- Retry webhook delivery in workflow with backoff.
-- Log update lifecycle:
-  - CI publish success/failure
-  - release webhook accepted/rejected
-  - app check/fetch/apply events (client telemetry)
-
-## 9) Rollout Plan
-
-Phase 1 - Staging:
-
-1. Implement OTA workflow for `main` channel only.
-2. Add app-side check/fetch on startup + foreground.
-3. Test with internal build on `main`.
-
-Phase 2 - Production:
-
-1. Add production publish workflow/manual gate.
-2. Add push-accelerated trigger.
-3. Monitor crash-free sessions and update adoption rate.
-
-Phase 3 - Hardening:
-
-1. Add kill switch/rollback procedure.
-2. Add release dashboard with latest OTA and binary status.
-
-## 10) Operational Playbook
-
-### Publish OTA update
-
-From repository root:
-
-- `npx eas update --branch main --message "fix: ..."`
-- for production:
-  - `npx eas update --branch production --message "fix: ..."`
-
-### Publish binary update
-
-1. Create `releases/builder/build_MMDDYYYY_HHMM/` with installer at root and supporting files under `dev/`.
-2. Push changes.
-3. Workflow creates (or skips duplicate) GitHub Release and calls `/api/releases`.
-
-### Rollback OTA
-
-- Republish a known-good commit to the same branch/channel with a new OTA message.
-- If needed, temporarily disable update checks via remote config flag.
-
-## 11) Acceptance Criteria
-
-- OTA updates reach active users without reinstall for JS/UI changes.
-- Median time from CI publish to client fetch is within target SLA.
-- Binary updates only occur for native/runtime changes.
-- Duplicate `release_id` never creates duplicate GitHub Release.
-- `/api/releases` accepts only authenticated requests.
-- App always has fallback update detection even if push signal fails.
-
-## 12) Next Implementation Tasks
-
-1. Create `api/releases.ts` endpoint.
-2. Add `.github/workflows/eas-update.yml`.
-3. Add client update service wrapper (`check/fetch/apply` policy).
-4. Add docs section in `build_and_install.md` linking OTA vs binary rules.
-5. Add monitoring events for update checks and apply outcomes.