@www.hyperlinks.space/program-kit 1.2.3

package/docs/database_messages.md

@@ -0,0 +1,34 @@
+### Database refactor and extensions (plan)
+
+**Goal**
+
+- DB bootstrap in `app/database`; keep `users`, `wallets`, `pending_transactions` as-is.
+- One minimal AI table shared by bot and TMA; one user identity: `user_telegram` (bot: `ctx.from.username`; TMA: initData `user.username`). No Chat table; TMA-only users use `type = 'app'`.
+
+---
+
+**messages** (single table, not implemented yet)
+
+- `id` (PK, BIGSERIAL) — same as other tables (e.g. wallets).
+- `created_at` (TIMESTAMPTZ, NOT NULL DEFAULT now()).
+- `user_telegram` (TEXT, FK → `users(telegram_username)`).
+- `thread_id` (BIGINT) — bot: Telegram `message_thread_id` (0 = default); TMA: app-chosen (e.g. 0).
+- `type` (TEXT) — `'bot'` | `'app'`.
+- `role` (TEXT) — `'user'` | `'assistant'` | `'system'`.
+- `content` (TEXT).
+- `telegram_update_id` (BIGINT, nullable) — bot only; NULL for TMA. Source: Telegram webhook payload (`ctx.update.update_id` in bot handler). Used for: (1) unique constraint → one row per update per thread, no double-reply; (2) before send, check max = our update_id → if not, abort (avoids mixed replies in serverless). TMA doesn’t need it: requests come from the app (HTTP), not Telegram’s update stream, so there is no update_id; TMA concurrency is a separate concern (e.g. client or request-scoped).
+
+**Thread key** — `(user_telegram, thread_id, type)` together identify one conversation. Example: user "alice", topic 0, bot = one thread; same user, topic 5, bot = another thread; same user, app = TMA thread.
+
+**Index** — `(user_telegram, thread_id, type, created_at)` so we can quickly get "all messages in this thread, ordered by time" (for building chat history for AI).
+
+**Unique for bot** — `(user_telegram, thread_id, type, telegram_update_id)` where `telegram_update_id IS NOT NULL`. Meaning: in a given thread, each Telegram update_id may appear at most once. So we can’t insert two rows for the same update (e.g. duplicate webhook or two serverless instances); the second insert fails, that handler skips. Only the first insert “owns” the reply.
+
+**Bot: no message mixing (messages-only)**
+
+1. Insert user message with `telegram_update_id`. On unique violation → skip.
+2. Before each send: if `MAX(telegram_update_id)` for thread ≠ our update_id → abort.
+3. No extra tables.
+
+**Migrations**
+

package/docs/fonts.md

@@ -0,0 +1,18 @@
+# Fonts (Expo web / TMA)
+
+## What the bottom bar asks for today
+
+- **Name in code:** **`Aeroport`** (geometric / grotesk-style sans — the brand face used elsewhere in the product).
+- **Reality in this repo:** There is **no** Aeroport font file under `app/assets/` and **no** `@font-face` rule, so **the browser cannot load “Aeroport”**. It falls back — in Telegram’s WebView that often looks like a **serif** (“antiqua”), not a grotesk.
+
+## What you see after the fix
+
+- **`app/fonts.ts`** exports **`WEB_UI_SANS_STACK`**: **`Aeroport` first** (for when files exist), then **`ui-sans-serif, system-ui, …, sans-serif`** so text always uses a **modern sans** until Aeroport is bundled.
+
+## How to use real Aeroport (optional)
+
+1. Add licensed `.otf`/`.ttf` files, e.g. `app/assets/fonts/Aeroport-Regular.otf`.
+2. Register with **`expo-font`** in the root layout, e.g. `useFonts({ Aeroport: require("./assets/fonts/Aeroport-Regular.otf") })`.
+3. Add **`@font-face`** in `global.css` if you prefer pure CSS loading on web (paths must match the exported static asset URL).
+
+Until then, the **stack** in `global.css` + `GlobalBottomBarWeb` keeps the UI **grotesk-like** via system fonts.

package/docs/releases.md

@@ -0,0 +1,201 @@
+# GitHub Releases Automation Plan (Final)
+
+This document defines the production plan for release detection, deduped GitHub Release publishing, and near-instant app update signaling.
+
+## Goals
+
+- Build the Windows installer on GitHub Actions (`windows-latest`) with `npm run build:win` (no `.exe` committed to git).
+- Publish the installer to a GitHub Release only when that release tag does not already exist.
+- Notify an app-update service immediately after a new release is published.
+- Keep app-side update detection near-instant using push notification plus fallback polling.
+
+## Source of Truth
+
+- The **GitHub Release tag** is the release identity (`release_id`), for example `build_03252026_1929`.
+- Locally, `windows/cleanup.cjs` moves the built installer to `app/releases/builder/build_MMDDYYYY_HHMM/HyperlinksSpaceProgramInstaller_<stamp>.exe` (other artifacts under `dev/`). In CI you can set `RELEASE_BUILD_ID` to match a chosen tag, or leave it unset so the folder name comes from build time.
+
+## Workflow Trigger
+
+- **Manual only:** `workflow_dispatch` (Actions → “Windows release (CI build)”).
+- Optional input **release_id** (`build_MMDDYYYY_HHMM`). If empty, the tag is taken from the build output folder after `cleanup.cjs` runs.
+
+Example trigger:
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      release_id:
+        description: "Optional tag, e.g. build_03252026_1929"
+        required: false
+        default: ""
+```
+
+## Dedupe Rules (No Duplicate Releases)
+
+1. Run `npm run build:win` (or use optional `RELEASE_BUILD_ID` so the output folder matches the intended tag).
+2. Resolve `release_id` from the optional input or from `releases/builder/build_*/HyperlinksSpaceProgramInstaller_*.exe`.
+3. Check whether GitHub Release/tag already exists for that `release_id`.
+4. If it exists:
+   - Exit successfully (`0`)
+   - Do not upload assets
+   - Do not send webhook notification
+5. If it does not exist:
+   - Create GitHub Release/tag
+   - Upload all files from that folder as release assets
+   - Continue to webhook notification
+
+Recommended extra safety:
+
+- Use workflow `concurrency` keyed by `release_id` to avoid race conditions.
+
+## Endpoint Contract
+
+- Webhook endpoint path: `app/api/releases.ts`
+- Route URL: `POST /api/releases`
+- Purpose: accept release-published events from GitHub Actions and fan out update notifications to app clients.
+
+## Security
+
+- GitHub Actions sends auth header:
+  - `x-release-token: <secret>`
+- Endpoint validates against:
+  - `process.env.RELEASE_WEBHOOK_TOKEN`
+- Optional hardening:
+  - Add HMAC signature verification for request body.
+
+If auth fails:
+
+- Return `401` and do not process payload.
+
+## Payload Shape
+
+`POST /api/releases` expects JSON:
+
+```json
+{
+  "release_id": "build_03252026_1929",
+  "version": "1.0.0",
+  "published_at": "2026-03-25T19:29:00Z",
+  "platform": "windows",
+  "assets": [
+    {
+      "name": "HyperlinksSpaceProgramInstaller.exe",
+      "url": "https://github.com/<org>/<repo>/releases/download/build_03252026_1929/HyperlinksSpaceProgramInstaller.exe",
+      "sha256": "<optional>"
+    }
+  ],
+  "github_release_url": "https://github.com/<org>/<repo>/releases/tag/build_03252026_1929"
+}
+```
+
+## Endpoint Behavior (`app/api/releases.ts`)
+
+1. Accept only `POST`.
+2. Validate auth token/signature.
+3. Parse and validate required fields:
+   - `release_id`, `published_at`, `assets`.
+4. Enforce idempotency by `release_id`:
+   - If already processed, return `200 { ok: true, duplicate: true }`.
+5. Store/update latest release metadata in persistent storage.
+6. Push update signal to clients (WebSocket/SSE/Firebase/Expo push).
+7. Return quickly with `200 { ok: true }`.
+
+## GitHub Actions Notification Step
+
+After successful release creation and asset upload:
+
+1. Read webhook URL and token from repository secrets:
+   - `RELEASE_WEBHOOK_URL`
+   - `RELEASE_WEBHOOK_TOKEN`
+2. Send `POST` to `/api/releases` with release payload.
+3. Retry webhook call with backoff on transient failures.
+
+Important:
+
+- Do not send webhook if release already existed (dedupe branch).
+
+## When You Must Make a New Installer Release
+
+Use this section as the decision rule between OTA update and installer release.
+
+### Native/runtime changes (installer required)
+
+Create a new installer release when a change affects native binaries or runtime compatibility, including:
+
+- Installing, removing, or updating any package that forces you to rebuild the app.
+- Changing app permissions or native capabilities (camera, notifications, background modes, deep links, etc.).
+- Changing package identifiers, signing, entitlements, or other platform build settings.
+- Changing Expo SDK or React Native version in a way that changes native runtime.
+- Changing `runtimeVersion` policy/behavior or bumping app version when runtime compatibility changes.
+- Any change that requires running a fresh native build to take effect.
+
+### Non-native changes (OTA only, no installer)
+
+Do not make a new installer release for:
+
+- JavaScript/TypeScript business logic changes.
+- UI/layout/style changes.
+- Text/copy changes and static asset updates that are OTA-compatible.
+- Server/API behavior changes that do not require new native modules in app.
+
+### Exact release checklist
+
+Make a new installer release if at least one statement is true:
+
+1. "This change cannot work without rebuilding native binaries."
+2. "This change modifies runtime compatibility between app binary and updates."
+3. "This change touches native permissions/capabilities/config."
+
+If all three are false, ship via OTA update instead of installer release.
+
+### Team policy
+
+- Prefer OTA by default for speed.
+- Use installer releases only for native/runtime boundaries.
+- When uncertain, treat as installer-required and verify in staging before production.
+
+## App Update Strategy
+
+Primary strategy:
+
+- Real-time push signal from backend triggered by `/api/releases`.
+
+Fallback strategy:
+
+- App checks latest release on:
+  - app foreground/resume
+  - periodic interval (for example every 5-15 minutes)
+
+Client behavior:
+
+1. Compare local build/version with latest server metadata.
+2. If newer exists:
+   - Show "Update available" prompt or trigger controlled update flow.
+
+## Reliability and Observability
+
+- Idempotent handling on `release_id`.
+- Structured logs for each stage:
+  - detected -> published/skipped -> webhook sent -> app signal broadcast
+- Alert on partial failure:
+  - release created but webhook failed
+- Keep webhook processing fast and non-blocking for external calls.
+
+## Rollout Plan
+
+1. Deploy `app/api/releases.ts` in staging.
+2. Run workflow in dry-run mode to validate folder parsing and dedupe checks.
+3. Enable real release creation for test folder.
+4. Enable webhook call to staging endpoint.
+5. Verify end-to-end with one client device.
+6. Promote to production after stable validation.
+
+## Acceptance Criteria
+
+- A new `app/releases/builder/build_.../` folder produces exactly one GitHub Release.
+- Re-running workflow for the same `release_id` does not create duplicates.
+- Webhook is called only for newly created releases.
+- `POST /api/releases` rejects unauthorized requests.
+- Connected app receives update signal near-instantly in normal conditions.
+- Fallback polling still discovers updates if push delivery fails.

package/docs/releases_github_actions.md

@@ -0,0 +1,188 @@
+# GitHub Releases Automation Plan (Final)
+
+This document defines the production plan for release detection, deduped GitHub Release publishing, and near-instant app update signaling.
+
+## Goals
+
+- Build the Windows installer on GitHub Actions (`windows-latest`) with `npm run build:win` (no `.exe` committed to git).
+- Publish the installer to a GitHub Release only when that release tag does not already exist.
+- Notify an app-update service immediately after a new release is published.
+- Keep app-side update detection near-instant using push notification plus fallback polling.
+
+## Source of Truth
+
+- The **GitHub Release tag** is the release identity (`release_id`), for example `build_03252026_1929`.
+- Locally and in CI, `windows/cleanup.cjs` places the installer under `app/releases/builder/build_MMDDYYYY_HHMM/HyperlinksSpaceProgramInstaller_<stamp>.exe` (other files under `dev/`). In CI, set `RELEASE_BUILD_ID` to pin the folder/tag, or omit it to use the timestamp from build time.
+
+## When You Must Make a New Installer Release
+
+Create a new installer/GitHub Release when a change is native/runtime-level and cannot be delivered safely by OTA update alone.
+
+Native/runtime changes include:
+
+- Adding, removing, or upgrading native libraries/modules (anything requiring a new Android/iOS/desktop binary).
+- Changing app permissions or OS capabilities (camera, notifications, background modes, file access, etc.).
+- Changing Expo config plugins or native project settings that affect the compiled binary.
+- Upgrading Expo SDK/React Native/runtime where binary compatibility changes.
+- Changing `runtimeVersion` strategy/value, or bumping app version when `runtimeVersion.policy` depends on it.
+- Changing signing/notarization/install packaging behavior for distributed installers.
+- Any fix that touches native code or build-time platform configuration.
+
+Do not make a new installer release for:
+
+- Pure JavaScript/TypeScript logic changes.
+- UI changes in React components.
+- Asset/text/content updates that are OTA-compatible.
+- API integration changes that do not alter native dependencies.
+
+Practical decision checklist:
+
+1. Does this change require rebuilding a platform binary to work? If yes, make installer release.
+2. Does this change alter native modules, permissions, SDK/runtime, or build config? If yes, make installer release.
+3. If both answers are no, publish OTA update only and skip installer release.
+
+## Workflow Trigger
+
+- **Manual only:** `workflow_dispatch` (workflow “Windows release (CI build)”).
+- Optional input **release_id** (`build_MMDDYYYY_HHMM`). If empty, the tag is taken from the build output after `cleanup.cjs`.
+
+Example trigger:
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      release_id:
+        description: "Optional tag, e.g. build_03252026_1929"
+        required: false
+        default: ""
+```
+
+## Dedupe Rules (No Duplicate Releases)
+
+1. Run `npm run build:win` (optionally with `RELEASE_BUILD_ID` so the output folder matches the intended tag).
+2. Resolve `release_id` from the workflow input or from `releases/builder/build_*/HyperlinksSpaceProgramInstaller_*.exe`.
+3. Check whether GitHub Release/tag already exists for that `release_id`.
+4. If it exists:
+   - Exit successfully (`0`)
+   - Do not upload assets
+   - Do not send webhook notification
+5. If it does not exist:
+   - Create GitHub Release/tag
+   - Upload `HyperlinksSpaceProgramInstaller.exe` as the release asset
+   - Continue to webhook notification
+
+Recommended extra safety:
+
+- Use workflow `concurrency` keyed by `release_id` to avoid race conditions.
+
+## Endpoint Contract
+
+- Webhook endpoint path: `app/api/releases.ts`
+- Route URL: `POST /api/releases`
+- Purpose: accept release-published events from GitHub Actions and fan out update notifications to app clients.
+
+## Security
+
+- GitHub Actions sends auth header:
+  - `x-release-token: <secret>`
+- Endpoint validates against:
+  - `process.env.RELEASE_WEBHOOK_TOKEN`
+- Optional hardening:
+  - Add HMAC signature verification for request body.
+
+If auth fails:
+
+- Return `401` and do not process payload.
+
+## Payload Shape
+
+`POST /api/releases` expects JSON:
+
+```json
+{
+  "release_id": "build_03252026_1929",
+  "version": "1.0.0",
+  "published_at": "2026-03-25T19:29:00Z",
+  "platform": "windows",
+  "assets": [
+    {
+      "name": "HyperlinksSpaceProgramInstaller.exe",
+      "url": "https://github.com/<org>/<repo>/releases/download/build_03252026_1929/HyperlinksSpaceProgramInstaller.exe",
+      "sha256": "<optional>"
+    }
+  ],
+  "github_release_url": "https://github.com/<org>/<repo>/releases/tag/build_03252026_1929"
+}
+```
+
+## Endpoint Behavior (`app/api/releases.ts`)
+
+1. Accept only `POST`.
+2. Validate auth token/signature.
+3. Parse and validate required fields:
+   - `release_id`, `published_at`, `assets`.
+4. Enforce idempotency by `release_id`:
+   - If already processed, return `200 { ok: true, duplicate: true }`.
+5. Store/update latest release metadata in persistent storage.
+6. Push update signal to clients (WebSocket/SSE/Firebase/Expo push).
+7. Return quickly with `200 { ok: true }`.
+
+## GitHub Actions Notification Step
+
+After successful release creation and asset upload:
+
+1. Read webhook URL and token from repository secrets:
+   - `RELEASE_WEBHOOK_URL`
+   - `RELEASE_WEBHOOK_TOKEN`
+2. Send `POST` to `/api/releases` with release payload.
+3. Retry webhook call with backoff on transient failures.
+
+Important:
+
+- Do not send webhook if release already existed (dedupe branch).
+
+## App Update Strategy
+
+Primary strategy:
+
+- Real-time push signal from backend triggered by `/api/releases`.
+
+Fallback strategy:
+
+- App checks latest release on:
+  - app foreground/resume
+  - periodic interval (for example every 5-15 minutes)
+
+Client behavior:
+
+1. Compare local build/version with latest server metadata.
+2. If newer exists:
+   - Show "Update available" prompt or trigger controlled update flow.
+
+## Reliability and Observability
+
+- Idempotent handling on `release_id`.
+- Structured logs for each stage:
+  - detected -> published/skipped -> webhook sent -> app signal broadcast
+- Alert on partial failure:
+  - release created but webhook failed
+- Keep webhook processing fast and non-blocking for external calls.
+
+## Rollout Plan
+
+1. Deploy `app/api/releases.ts` in staging.
+2. Run workflow in dry-run mode to validate folder parsing and dedupe checks.
+3. Enable real release creation for test folder.
+4. Enable webhook call to staging endpoint.
+5. Verify end-to-end with one client device.
+6. Promote to production after stable validation.
+
+## Acceptance Criteria
+
+- A new `app/releases/builder/build_.../` folder produces exactly one GitHub Release.
+- Re-running workflow for the same `release_id` does not create duplicates.
+- Webhook is called only for newly created releases.
+- `POST /api/releases` rejects unauthorized requests.
+- Connected app receives update signal near-instantly in normal conditions.
+- Fallback polling still discovers updates if push delivery fails.

package/docs/scalability.md

@@ -0,0 +1,34 @@
+# Scalability overview and challenges
+
+**Stack:** Vercel serverless (webhook, API), Neon Postgres, Telegram bot (Grammy), OpenAI, single `messages` table for bot + TMA.
+
+---
+
+## Overview
+
+- **Webhook:** Stateless. Returns 200 immediately; update is processed in `waitUntil`. No in-memory state between requests. Vercel scales out with traffic (more concurrent requests → more instances).
+- **Bot:** One bot instance per serverless instance (module-level in webhook). No global singleton; fits serverless.
+- **Dedupe / “only latest wins”:** Done in the DB (`telegram_update_id` unique constraint + `getMaxTelegramUpdateIdForThread`). Works across instances; no reliance on in-process state.
+- **Messages:** One table, indexed by `(user_telegram, thread_id, type, created_at)` and unique on `(..., telegram_update_id)` for bot. Per-request load is small (insert user, get history, insert assistant, optional max-update-id read).
+- **Database:** Neon with **connection pooling** already on (supports up to 10,000 concurrent connections). Use the pooled `DATABASE_URL` in Vercel so serverless invocations go through the pooler.
+
+The design is horizontally scalable: more users → more invocations → more instances; no single bottleneck in the app logic.
+
+---
+
+## Challenges and what to do
+
+| Area | Challenge | What to do |
+|------|-----------|------------|
+| **DB connections** | Pooling is already on (up to 10,000 concurrent connections). | Ensure `DATABASE_URL` in Vercel is the **pooled** connection string from Neon. |
+| **OpenAI** | Limits are per key (RPM/TPM). One key can scale. | Raise **usage tier** (limits increase with spend/account age—e.g. Tier 4: 10k RPM, 2M TPM). Enterprise: **Scale Tier** for dedicated capacity. Optionally multiple keys or queue only if you need beyond tier limits. |
+| **Vercel** | Hobby has invocation/duration limits; long AI flows need enough timeout. | Use Pro (or Enterprise) for production at scale; set function timeout to cover longest flow (e.g. streaming + DB). |
+| **Messages table** | Grows with users and time; very large tables can slow queries and increase cost. | Retention (delete or archive old threads); optional partitioning by time or user; keep `getThreadHistory` with a small `limit`. |
+| **Observability** | At scale, bottlenecks and errors are hard to see without metrics. | Logging, metrics, and alerts (errors, latency, DB pool usage, OpenAI rate limits) in Vercel/Neon or a third-party tool. |
+
+---
+
+## Summary
+
+- **Scalable:** Stateless webhook, 200-first response, DB-backed dedupe and history, Neon connection pooling.
+- **To scale to very high traffic:** Neon pooling is already on (10k connections); keep using the pooled `DATABASE_URL`. For OpenAI, extend plan/usage to reach a higher tier (or Scale Tier for enterprise); one key is enough. Plan for Vercel limits/timeouts; add message retention and monitoring.