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

package/fullREADME.md

@@ -4,23 +4,31 @@
 
 <u>**In progress, contribute!**</u>
 
-This program is built upon [React Native](https://reactnative.dev/) by Meta and [Expo](https://expo.dev) multiplatform technologies, Windows build and executable creation achieved with [Electron Builder](https://www.electron.build/) and [Electron Forge](https://www.electronforge.io/), working in Telegram with help of [Telegram Mini Apps React SDK](http://telegram-mini-apps.com/) and [Bot API](https://core.telegram.org/bots). AI is backed by [OpenAI API](https://openai.com/ru-RU/api/), blockchain data is processed from [Swap.Coffee API](https://docs.swap.coffee/eng/user-guides/welcome).
-
-## Program Kit
-
-To give value for other developers we decided to launch an npm package that provides a ready starter for creating a multiplatform program in one command.
-
-```bash
-npx @www.hyperlinks.space/program-kit ./new-program
-```
-
-Link to the package: https://www.npmjs.com/package/@www.hyperlinks.space/program-kit
+This program is built upon [React Native](https://reactnative.dev/) by Meta and [Expo](https://expo.dev) multiplatform technologies, Windows build and executable creation achieved with [Electron Builder](https://www.electron.build/) and [Electron Forge](https://www.electronforge.io/), working in Telegram with help of [Telegram Mini Apps React SDK](http://telegram-mini-apps.com/), [Bot API](https://core.telegram.org/bots) and [Grammy](https://grammy.dev/). AI is backed by [OpenAI API](https://openai.com/ru-RU/api/), blockchain info is processed from [Swap.Coffee API](https://docs.swap.coffee/eng/user-guides/welcome). DB for the best user's experience we host on [Neon](https://neon.tech/).
 
 ## Program design
 
 Access [Figma](https://www.figma.com/design/53lDKAD6pRv3e0uef1DP18/TECHSYMBAL-Inc.?node-id=754-71&t=v3tmAlywNgXkTWMd-1) in real time for contributing. Contact [Seva](t.me/sevaaignatyev) in Telegram to discuss and implement.
 
-Copying fully or partially, usage as an inspiration for other developments are unpleasant, participation in our projects is appreciated. All core materials are available publicly for instant access worldwide and our project availability for newcomers.
+All core materials are available publicly for сгккуте hyperlinks.space team members' instant and easy access worldwide and our project's availability for newcomers' research only.
+
+## Structure
+
+- [`app`](./app) - Expo/React Telegram Mini App client (web/mobile screens, navigation, UI logic).
+- [`ui`](./ui) - shared UI layer (components, theme tokens, and font configuration used by the app).
+- [`bot`](./bot) - TypeScript Telegram bot service and runtime entrypoints.
+- [`database`](./database) - database startup/migration/service scripts.
+- [`ai`](./ai) - AI assistant service logic and model integration points.
+- [`api`](./api) - backend API handlers and server-side endpoints.
+- [`blockchain`](./blockchain) - TON/blockchain interaction logic and related helpers.
+- [`telegram`](./telegram) - Telegram-specific integration utilities and adapters.
+- [`windows`](./windows) - Electron desktop shell, NSIS installer config, and auto-update flow.
+- [`scripts`](./scripts) - developer/ops scripts (local run, migration, release helpers).
+- [`docs`](./docs) - project and operational documentation (architecture, releases, security reference, tooling).
+- [`research`](./research) - exploratory notes, investigations, and proposals not yet promoted to `docs/`.
+- [`backlogs`](./backlogs) - short-term planning notes and prioritized work items.
+- [`assets`](./assets) - static assets used by app, installer, and branding.
+- [`dist`](./dist) - generated web build output (export artifacts).
 
 ## How to fork and contribute?
 
@@ -64,15 +72,36 @@ git switch -c new-branch-for-next-update # Create and switch to a new feature br
 
 **Move in loops starting from the step 3.**
 
-## Pull requests and commits requirements
+## Local deploy
 
-- Give pull requests and commits a proper name and description
-- Dedicate each pull request to an understandable area or field, each commit to a focused logical change
-- Check file changes in every commit pulled, no arbitrary files modifications should persist such as LF/CRLF line-ending conversion, broken/garbled text diffs, BOM added or removed, accidental "invisible" corruption from text filters
-- Add dependecies and packages step by step for security
-- An issue creation or following an existing before a pull request would be a good practice
+`npm` package note: `.env.example` is included in the published package so you can use it as a reference for establishing your testing environment with `.env` file.
+
+Before local deploy / cloud deploy, prepare these env-backed services:
+
+1. **Neon PostgreSQL (`DATABASE_URL`)**
+   - Create an account/project at [Neon](https://neon.tech/).
+   - Create a database and copy the connection string.
+   - Put it into `.env` as `DATABASE_URL=...`.
+2. **OpenAI API (`OPENAI_API_KEY`)**
+   - Create an account at [OpenAI Platform](https://platform.openai.com/).
+   - Create an API key in the API Keys page.
+   - Put it into `.env` as `OPENAI_API_KEY=...`.
+3. **Telegram bot token (`BOT_TOKEN`)**
+   - In Telegram, open [@BotFather](https://t.me/BotFather), create a test bot with `/newbot`.
+   - Copy the bot token and put it into `.env` as `BOT_TOKEN=...`.
+4. **Vercel project envs (for comfortable deploy/testing)**
+   - Create a [Vercel](https://vercel.com/) account and import this repository as a project.
+   - In Project Settings -> Environment Variables, set at least:
+     - `DATABASE_URL`
+     - `OPENAI_API_KEY`
+     - `BOT_TOKEN` (or `TELEGRAM_BOT_TOKEN`)
+   - Pull envs locally when needed with `vercel env pull .env.local`.
+
+Copy env template locally:
 
-## Local deploy
+```bash
+cp .env.example .env
+```
 
 To start the full local stack, run:
 
@@ -82,67 +111,31 @@ npm run start
 
 This runs Expo dev server, the Telegram bot (polling mode), and local Vercel API (`vercel dev`).
 
+After `npm run start`, you can test the app on real phones with Expo Go:
+
+- Install **Expo Go** from Google Play (Android) or App Store (iOS).
+- Make sure your phone and development machine are on the same network.
+- Open Expo Go and scan the QR code shown in the terminal/Expo UI.
+- The app will launch on the device and hot-reload on code changes.
+
 Isolated/local run options:
 
 - Expo only (no bot, no Vercel): `npm run start:expo`
 - Bot only (polling mode): `npm run bot:local`
 - Vercel API only: `npm run dev:vercel`
 
-## Milestone snapshot package (npm)
-
-NPM release and snapshot details were moved to `docs/npm-release.md`.
-
-### Local env setup
-
-1. **Copy the example file** (from the repository root):
-   ```bash
-   cp .env.example .env
-   ```
-2. **Edit `.env`** and set at least:
-   - **`BOT_TOKEN`** – if you run the Telegram bot locally (`npm run bot:local`).
-3. **Expo app** – `npx expo start` reads env from the environment; for app-only env vars you can also put them in `.env` and use an Expo-compatible loader if you add one, or set them in the shell before running:
-   ```bash
-   export BOT_TOKEN=your_token
-   npx expo start
-   ```
-4. **Bot local** – `npm run bot:local` loads `.env` from the project root (optional; you can also set `BOT_TOKEN` in the shell).
-
-The `.env` file is gitignored; do not commit it.
-
 ## GitHub Actions
 
 Current Actions workflows include:
 
-- `Vercel Deploy Test` (`.github/workflows/vercel-deploy-test-envs.yml`) - manual web deploy to Vercel.
-- `NPM Package Release` (`.github/workflows/npm-package-release.yml`) - npm/GitHub Packages release workflow.
-- `Electron EXE Release` and `Electron Forge EXE Release` - manual Windows release pipelines.
-- `EXPO Publish` (`.github/workflows/expo-publish.yml`) - manual OTA publish with EAS CLI.
-- `Lint errors check` (`.github/workflows/lint-errors-check.yml`) - manual lint check.
-
-## Expo Workflows
-
-This project uses two automation layers:
-
-- [EAS Workflows](https://docs.expo.dev/eas/workflows/get-started/) for Expo update/build/deploy flows (triggered via npm scripts from [`package.json`](./package.json)).
-- GitHub Actions for CI/CD tasks stored in `.github/workflows` (manual release/deploy jobs and checks).
-
-### Previews
+- [`Vercel Deploy Test`](./.github/workflows/vercel-deploy-test-envs.yml) - manual web deploy to Vercel.
+- [`Electron Forge EXE Release`](./.github/workflows/electron-forge-exe-release.yml) - manual Windows release pipeline.
+- [`Electron EXE Release`](./.github/workflows/electron-exe-release.yml) - manual Windows release pipeline.
+- [`Lint errors check`](./.github/workflows/lint-errors-check.yml) - manual lint check.
+- [`EXPO Publish`](./.github/workflows/expo-publish.yml) - manual OTA publish with EAS CLI.
+- [`NPM Package Release`](./.github/workflows/npm-package-release.yml) - npm/GitHub Packages release workflow.
 
-Run `npm run draft` to [publish a preview update](https://docs.expo.dev/eas/workflows/examples/publish-preview-update/) of your project, which can be viewed in Expo Go or in a development build.
-
-### Development Builds
-
-Run `npm run development-builds` to [create a development build](https://docs.expo.dev/eas/workflows/examples/create-development-builds/). Note - you'll need to follow the [Prerequisites](https://docs.expo.dev/eas/workflows/examples/create-development-builds/#prerequisites) to ensure you have the correct emulator setup on your machine.
-
-### Production Deployments
-
-Run `npm run deploy` to [deploy to production](https://docs.expo.dev/eas/workflows/examples/deploy-to-production/). Note - you'll need to follow the [Prerequisites](https://docs.expo.dev/eas/workflows/examples/deploy-to-production/#prerequisites) to ensure you're set up to submit to the Apple and Google stores.
-
-## Hosting
-
-Expo offers hosting for websites and API functions via EAS Hosting. See the [Getting Started](https://docs.expo.dev/eas/hosting/get-started/) guide to learn more.
-
-### Deploy web build to Vercel
+## Deploy to Vercel
 
 From the repository root, deploy the static web build to Vercel production:
 
@@ -152,7 +145,7 @@ vercel --prod
 
 Deploying from repository root makes this folder the project root, so `api/bot` is deployed and no Root Directory setting is needed. The project is configured so Vercel runs `npx expo export -p web` and serves the `dist/` output. Link the project first with `vercel` if needed.
 
-## Telegram bot (Grammy)
+## Telegram bot
 
 The bot is extended beyond a basic "Hello" and "Start program" responder and now supports AI streaming and threads.
 
@@ -174,6 +167,84 @@ The bot is extended beyond a basic "Hello" and "Start program" responder and now
 - Run full local stack (Expo + bot + Vercel): `npm run start`
 - Keep production and local bot tokens separate when possible to avoid webhook/polling conflicts.
 
-## Where to discuss the project?
+## Pull requests and commits requirements
+
+- Give pull requests and commits a proper name and description
+- Dedicate each pull request to an understandable area or field, each commit to a focused logical change
+- Check file changes in every commit pulled, no arbitrary files modifications should persist such as LF/CRLF line-ending conversion, broken/garbled text diffs, BOM added or removed, accidental "invisible" corruption from text filters
+- Add dependecies and packages step by step for security
+- An issue creation or following an existing before a pull request would be a good practice
+
+## Expo Workflows
+
+[EAS Workflows](https://docs.expo.dev/eas/workflows/get-started/) are here for Expo update/build/deploy flows (triggered via npm scripts from [`package.json`](./package.json)).
+
+## Previews
+
+Run `npm run draft` to [publish a preview update](https://docs.expo.dev/eas/workflows/examples/publish-preview-update/) of your project, which can be viewed in Expo Go or in a development build.
+
+## Development Builds
+
+Run `npm run development-builds` to [create a development build](https://docs.expo.dev/eas/workflows/examples/create-development-builds/). Note - you'll need to follow the [Prerequisites](https://docs.expo.dev/eas/workflows/examples/create-development-builds/#prerequisites) to ensure you have the correct emulator setup on your machine.
+
+## Expo envs setup
+
+**Expo app** – `npx expo start` reads env from the environment; for app-only env vars you can also put them in `.env` and use an Expo-compatible loader if you add one, or set them in the shell before running:
+   ```bash
+   export BOT_TOKEN=your_token
+   npx expo start
+   ```
+
+## GitLab access
+
+GitHub and GitLab repositories are identical. If you want to contribute through GitLab, get access from [@staindart](https://github.com/staindart).
+
+If you can push to **both** [GitHub](https://github.com/HyperlinksSpace/HyperlinksSpaceProgram) and [GitLab](https://gitlab.com/hyperlinks.space/HyperlinksSpaceProgram) directly, we ask you to configure Git so pushes keep **both** hosts in sync: the repositories are the same; avoid updating only one side.
+
+1. **Keep `origin` on GitHub for fetch and the first push URL.** If you cloned from GitHub, this is already true: `origin` is where `git pull` / `git fetch origin` get updates. We standardize on GitHub for **incoming** history from `origin` so your local `main` tracks `origin/main` on GitHub.
+
+2. **Register GitLab as a second push URL on `origin`.** Git allows multiple **push** URLs per remote name, but only one **fetch** URL. Adding GitLab here means a single `git push origin <branch>` (or the IDE **Sync** push step) sends the same commits to **both** GitHub and GitLab without a second command.
+
+   ```bash
+   git remote set-url --add --push origin https://gitlab.com/hyperlinks.space/HyperlinksSpaceProgram.git
+   ```
+
+   Run this once per clone; it does not change where you fetch from.
+
+3. **Add a separate remote named `gitlab`.** Because `origin`’s fetch URL stays on GitHub, `git fetch origin` never downloads refs from GitLab. The extra remote lets you run `git fetch gitlab` when you need to compare or merge with the GitLab copy (for example if CI or another contributor updated GitLab only).
+
+   ```bash
+   git remote add gitlab https://gitlab.com/hyperlinks.space/HyperlinksSpaceProgram.git
+   ```
+
+   Note, that GitHub and GitLab URL's are a little different :)
+
+   If `gitlab` already exists with a wrong URL, use `git remote set-url gitlab https://gitlab.com/hyperlinks.space/HyperlinksSpaceProgram.git` instead.
+
+4. **Verify** with `git remote -v`. You should see GitHub on fetch/push for `origin`, GitLab as the second `origin` push line, and `gitlab` for fetch/push to GitLab:
+
+   ```text
+   gitlab  https://gitlab.com/hyperlinks.space/HyperlinksSpaceProgram.git (fetch)
+   gitlab  https://gitlab.com/hyperlinks.space/HyperlinksSpaceProgram.git (push)
+   origin  https://github.com/HyperlinksSpace/HyperlinksSpaceProgram.git (fetch)
+   origin  https://github.com/HyperlinksSpace/HyperlinksSpaceProgram.git (push)
+   origin  https://gitlab.com/hyperlinks.space/HyperlinksSpaceProgram.git (push)
+   ```
+
+**GitLab HTTPS access:** GitLab.com does not use **fine-grained** personal access tokens for Git-over-HTTPS (`git push` / `git fetch`). Create a **legacy** personal access token under GitLab → **Edit profile** → **Access tokens** with scopes **`read_repository`** and **`write_repository`**, as described in the official guide: [Personal access tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html). Use your GitLab username and the token as the password when Git prompts. GitHub authentication stays separate (for example `gh auth login` or your existing GitHub credential).
+
+## Program Kit
+
+To make it easier for developers to create multiplatform programs with us, we decided to launch an npm package that provides a ready starter for creating such a program basis in one command.
+
+```bash
+npx @www.hyperlinks.space/program-kit ./new-program
+```
+
+Link to the package: https://www.npmjs.com/package/@www.hyperlinks.space/program-kit
+
+The **npm registry page** shows a separate package-oriented description: [`npmReadMe.md`](./npmReadMe.md) in the repo root. At publish time the [NPM Package Release](.github/workflows/npm-package-release.yml) workflow copies the main [`README.md`](./README.md) to `fullREADME.md`, then replaces `README.md` with the contents of `npmReadMe.md` so `npm pack` / `npm publish` ship the shorter readme as the package readme (npm always surfaces `README.md` from the tarball). Snapshot channels, tags, and local `npm pack` checks are in [`docs/npm-release.md`](./docs/npm-release.md).
+
+## Project discussions
 
 This repository has [GitHub Discussions](https://github.com/HyperlinksSpace/HyperlinksSpaceProgram/discussions) opened, as well you can join our [Telegram Chat](https://t.me/HyperlinksSpaceChat) and [Channel](https://t.me/HyperlinksSpace).

package/index.js

@@ -0,0 +1,3 @@
+// Earliest bundle entry: polyfill Node `Buffer` before expo-router loads route modules (@ton/* uses it at load time).
+import "./polyfills/buffer";
+import "expo-router/entry";

package/package.json

@@ -9,6 +9,7 @@
     "program-kit": "scripts/program-kit-init.cjs"
   },
   "files": [
+    ".env.example",
     "README.md",
     "fullREADME.md",
     "npmReadMe.md",
@@ -39,8 +40,8 @@
     "type": "git",
     "url": "https://github.com/HyperlinksSpace/HyperlinksSpaceBot.git"
   },
-  "main": "expo-router/entry",
-  "version": "1.2.181818",
+  "main": "index.js",
+  "version": "18.18.18",
   "type": "module",
   "engines": {
     "node": ">=18 <=22"
@@ -161,6 +162,10 @@
     "@react-navigation/native": "^7.1.6",
     "@swap-coffee/sdk": "^1.5.4",
     "@tma.js/sdk-react": "^3.0.16",
+    "@ton/core": "^0.63.1",
+    "@ton/crypto": "^3.3.0",
+    "@ton/ton": "^16.2.3",
+    "buffer": "^6.0.3",
     "electron-updater": "^6.8.3",
     "expo": "~54.0.0",
     "expo-blur": "~15.0.8",

package/scripts/test-api-base.ts

@@ -1,8 +1,8 @@
 /**
- * Quick check that api/base.ts works. Run: npx tsx scripts/test-api-base.ts
+ * Quick check that api/_base.ts works. Run: npx tsx scripts/test-api-base.ts
  * In Node (no window), getApiBaseUrl() uses Vercel env or falls back to http://localhost:3000.
  */
-import { getApiBaseUrl, buildApiUrl } from "../api/base.js";
+import { getApiBaseUrl, buildApiUrl } from "../api/_base.js";
 
 const base = getApiBaseUrl();
 const full = buildApiUrl("/api/telegram");

package/telegram/post.ts

@@ -7,6 +7,7 @@ import {
   normalizeUsername,
   upsertUserFromTma,
 } from '../database/users.js';
+import { getDefaultWalletByUsername } from '../database/wallets.js';
 
 const LOG_TAG = '[api/telegram]';
 
@@ -302,10 +303,53 @@ export async function handlePost(
   const dbStart = Date.now();
   try {
     await upsertUserFromTma({ telegramUsername, locale });
+    const wallet = await getDefaultWalletByUsername(telegramUsername);
     log('db_upsert_done', {
       dbMs: Date.now() - dbStart,
       elapsedMs: Date.now() - startMs,
+      hasWallet: !!wallet,
     });
+
+    if (wallet) {
+      log('success', {
+        telegramUsername,
+        hasWallet: true,
+        totalMs: Date.now() - startMs,
+      });
+      return new Response(
+        JSON.stringify({
+          ok: true,
+          telegram_username: telegramUsername,
+          has_wallet: true,
+          wallet: {
+            id: wallet.id,
+            wallet_address: wallet.wallet_address,
+            wallet_blockchain: wallet.wallet_blockchain,
+            wallet_net: wallet.wallet_net,
+            type: wallet.type,
+            label: wallet.label,
+            is_default: wallet.is_default,
+            source: wallet.source,
+          },
+        }),
+        { status: 200, headers: { 'content-type': 'application/json' } },
+      );
+    }
+
+    log('success', {
+      telegramUsername,
+      hasWallet: false,
+      totalMs: Date.now() - startMs,
+    });
+    return new Response(
+      JSON.stringify({
+        ok: true,
+        telegram_username: telegramUsername,
+        has_wallet: false,
+        wallet_required: true,
+      }),
+      { status: 200, headers: { 'content-type': 'application/json' } },
+    );
   } catch (e) {
     logErr('db_upsert_failed', e);
     return new Response(
@@ -317,12 +361,4 @@ export async function handlePost(
     );
   }
 
-  log('success', {
-    telegramUsername,
-    totalMs: Date.now() - startMs,
-  });
-  return new Response(
-    JSON.stringify({ ok: true, telegram_username: telegramUsername }),
-    { status: 200, headers: { 'content-type': 'application/json' } },
-  );
 }

package/docs/ai_and_search_bar_input.md

@@ -1,94 +0,0 @@
-## AI & Search bar input behaviour
-
-This document describes how the text in the global AI & Search bottom bar should behave as the user types, matching the Flutter implementation.
-
----
-
-### 1. Reference states (pictures sequence)
-
-The reference images show a sequence of states for a long line of text; they illustrate how the bar grows and then turns into a scrolling window:
-
-1. **Full text, no bar**  
-   Long multi‑line text fills a tall content area. This is effectively the raw content without the constraints of the bottom bar.
-
-2. **Initial bar: single line + arrow**  
-   - Only a single line of text is visible.  
-   - The text baseline is horizontally aligned with the apply arrow icon on the right.  
-   - There is empty space above the line; bar height is at its minimum.
-
-3. **Unconstrained multi‑line text**  
-   - Text has grown to multiple lines in a taller, unbounded view (again, this is the raw content).  
-
-4. **Growing bar: multiple lines + arrow**  
-   - The bottom bar has increased in height to show multiple lines.  
-   - As lines are added, the **space above the text shrinks**, but the **last visible line remains on the same vertical level as the arrow**.  
-   - Visually, the bar grows upwards while the arrow + last line baseline stays fixed.
-
-5. **Very long text, no bar**  
-   - The entire long text block is visible in a tall area, showing how much total content exists.
-
-6. **Capped bar height: scrolling window**  
-   - The bottom bar height is now capped (e.g. at 180 px).  
-   - The visible area becomes a **fixed‑height window** into the text:
-     - Older lines at the top continue moving up and eventually disappear under the **top edge** of the bar as more text is entered.
-     - The **last visible line stays aligned with the arrow baseline** at the bottom of the bar. The typing position does not move vertically once the bar has reached its maximum height.
-
----
-
-### 2. Detailed behaviour by line count
-
-#### 1–7 lines: growing bar
-
-- For each new line from 1 up to 7:
-  - The **bottom bar height increases** by exactly one line height (20 px).  
-  - The height formula is:
-    \[
-    \text{height} = 20\text{ (top padding)} + N \times 20\text{ (lines)} + 20\text{ (bottom padding)}, \quad 1 \le N \le 7.
-    \]
-  - The **last line is always on the same baseline as the arrow** on the right.
-  - Visually, the bar grows **upwards**; the arrow + last line stay fixed at the bottom.
-
-#### 8 lines: text reaches the top edge
-
-- When the **8th line** appears:
-  - The text block now reaches the **top edge of the bottom bar**.  
-  - The bar height is at its **maximum** (e.g. 180 px).  
-  - All 8 lines are still visible at once, from the top edge down to the arrow.
-
-#### 9 lines: full‑height text area, one line hidden
-
-- When the **9th line** appears:
-  - The **scrollable text area is exactly 180 px high**, the same as the bar.  
-  - The **last line remains aligned with the arrow** at the bottom.  
-  - The **topmost line (1st)** is now hidden just above the top edge of the bar.  
-  - If the user scrolls, they can reveal all 9 lines, because:
-    \[
-    9 \times 20\text{ px} = 180\text{ px},
-    \]
-    so all 9 lines can fit into the bar’s full height when scrolled to the appropriate position.
-
-#### 9+ lines: fixed bar, 9‑line scrolling window
-
-- For **any number of lines ≥ 9**:
-  - The bar height stays fixed at its maximum (e.g. 180 px).  
-  - The **scrollable area always occupies the full bar height** (180 px).  
-  - At any moment:
-    - Up to **9 lines are visible** in the window.  
-    - The **bottom (last visible) line stays aligned with the arrow** while typing.  
-    - Older lines scroll upwards and are hidden above the top edge; the user can scroll to reveal them.
-
----
-
-### 3. Implementation‑oriented summary
-
-- **Line height & padding**
-  - Line height: 20 px.
-  - Top padding: 20 px.
-  - Bottom padding: 20 px.
-
-- **Bar growth vs. scroll mode**
-  - For 1–7 lines, bar height grows; arrow + last line baseline are fixed.  
-  - From the 8th line onward, the bar stays at max height; the input switches to a scrollable window that:
-    - Always keeps the caret / last line baseline aligned with the arrow.
-    - Hides older lines under the top edge while allowing them to be revealed by scrolling.
-

package/docs/ai_bot_messages.md

@@ -1,124 +0,0 @@
-# Plan: Implement messages table in the bot
-
-**Goal:** Persist bot messages in the `messages` table and use the DB for "no message mixing" (serverless). Optionally use thread history for AI context later.
-
-**Existing:** `app/database/messages.ts` has `insertMessage`, `getThreadHistory`, `getMaxTelegramUpdateIdForThread`. Schema in `start.ts`; table created by `db:migrate`. Bot: `responder.ts` handles text/caption, gets `ctx.from`, `message_thread_id`, calls `transmit`/`transmitStream`, replies. No DB persistence today; no thread history for AI.
-
----
-
-## Best possible implementation (target design)
-
-**Split of responsibility**
-
-- **AI layer** owns all message persistence and context. **Bot** (and later TMA) own only transport and, for the bot, mixing prevention.
-
-**AI side (single place for persistence and context)**
-
-- Receives every request with: `input`, `user_telegram`, `thread_id`, `type` (`'bot'` | `'app'`), and optionally `telegram_update_id` (bot only).
-- **Claim / user message:** Inserts the user message (with `telegram_update_id` when provided). If insert returns `null` (unique violation), returns a **skipped** result so the caller does not send anything.
-- **Context:** Loads `getThreadHistory(...)` for that thread, converts to the format the model expects (e.g. `messages[]`), and passes current `input` + history to the model.
-- **Assistant message:** After a successful model response, inserts the assistant message (no `telegram_update_id`).
-- **Result:** One code path for “what gets stored” and “what context the model sees”. Bot and TMA both call this same layer; no duplicate insert logic in each client.
-
-**Bot side (mixing only)**
-
-- Resolves `user_telegram`, `thread_id`, `update_id` from `ctx`, and passes them into the AI call (including `telegram_update_id`).
-- If AI returns **skipped** (claim insert failed), returns without calling AI again and without sending any reply or draft.
-- Before **each** draft send and before the **final** reply: calls `getMaxTelegramUpdateIdForThread(user_telegram, thread_id, 'bot')`. If `max !== our update_id`, aborts (does not send). No message writes in the bot; only this read for mixing.
-- Sends drafts and final reply as today; does not call `insertMessage` itself.
-
-**TMA**
-
-- Calls the same AI layer with `user_telegram`, `thread_id`, `type: 'app'`. No `telegram_update_id`. Same persistence (user + assistant) and same history loading. No mixing logic unless we add a TMA-specific mechanism later (e.g. client request id + uniqueness).
-
-**Data flow (bot)**
-
-1. User sends a message → webhook → bot handler.
-2. Bot: resolve `user_telegram`, `thread_id`, `update_id`; call AI with `input`, `user_telegram`, `thread_id`, `type: 'bot'`, `telegram_update_id`.
-3. AI: insert user message (with `telegram_update_id`). If `null` → return skipped. Else: load thread history, call model with history + current input, insert assistant message, return response (and for streaming: stream + insert assistant when done).
-4. Bot: if skipped → return. Else: for each draft and for final reply, check `getMaxTelegramUpdateIdForThread`; if not ours, abort. Else send draft/reply.
-
-**Why this is best**
-
-- **Single source of truth:** All message rows and model context are created in the AI layer. Bot and TMA stay thin and consistent.
-- **No mixing in bot:** Mixing is entirely “check before send” + “skipped when claim fails”; no message writes in the bot.
-- **History by default:** AI always loads thread history and uses it for context, so conversations are coherent across turns.
-- **TMA-ready:** Same API for TMA (no `telegram_update_id`); mixing can be added later if needed.
-
----
-
-## 1. Resolve thread identity and update_id in the bot
-
-- **user_telegram:** `normalizeUsername(ctx.from?.username)` (same as grammy upsert). If empty, we can skip persistence or still reply (plan: skip DB only when username missing).
-- **thread_id:** `ctx.message?.message_thread_id ?? 0` (already used in responder for `replyOptions`).
-- **type:** `'bot'`.
-- **update_id:** `ctx.update.update_id` (Grammy context has it). Must be passed into the handler or read from `ctx.update` in responder.
-
-**Where:** `responder.ts` (and optionally grammy if we need to pass update_id explicitly). Ensure we have access to `ctx.update.update_id` in `handleBotAiResponse`.
-
----
-
-## 2. Insert user message first; skip if duplicate (claim by insert)
-
-- At the start of the AI flow (after we have `text`, `user_telegram`, `thread_id`), call:
-  `insertMessage({ user_telegram, thread_id, type: 'bot', role: 'user', content: text, telegram_update_id })`.
-- If `insertMessage` returns `null` (unique violation → another instance or duplicate webhook), **return without calling AI or replying** (so only one handler "owns" this update).
-
-**Where:** `responder.ts`, right after we have `text` and before we set up streaming/cancellation. Requires `user_telegram` and `update_id`; user must exist in `users` (grammy already upserts before calling the handler).
-
----
-
-## 3. Check "max update_id" before each send (no mixing)
-
-- Before each **draft** send and before the **final reply**, call:
-  `getMaxTelegramUpdateIdForThread(user_telegram, thread_id, 'bot')`.
-- If the returned max is not equal to our `update_id`, another instance has already processed a newer user message → **abort** (do not send draft or reply). Same idea as current in-memory `isCancelled()`, but DB-backed so it works across serverless instances.
-
-**Where:** In `responder.ts`, inside `sendDraftOnce` / before `ctx.reply`: call the DB; if `max !== ourUpdateId`, treat as cancelled (return / skip send).
-
----
-
-## 4. Persist assistant reply after successful send
-
-- After we send the final reply with `ctx.reply(result.output_text, replyOptions)` (and only when we actually send, not when we aborted or errored), call:
-  `insertMessage({ user_telegram, thread_id, type: 'bot', role: 'assistant', content: result.output_text })` (no `telegram_update_id`).
-
-**Where:** `responder.ts`, after the successful `ctx.reply(...)`.
-
----
-
-## 5. (Optional) Use thread history for AI context
-
-- Load history: `getThreadHistory({ user_telegram, thread_id, type: 'bot', limit })`.
-- Convert to the format expected by the AI (e.g. OpenAI `messages`: `{ role, content }[]`).
-- Pass this into the AI layer. Today `transmit`/`transmitStream` and `callOpenAiChat`/`callOpenAiChatStream` take a single `input` string; we’d need to extend the API to accept an optional `history` (or `messages`) and send a multi-turn request instead of a single user message.
-
-**Where:** New or changed code in `openai.ts` / `transmitter.ts` and call from `responder.ts` when in `chat` mode. Can be a follow-up step after 1–4.
-
----
-
-## Implementation order (recommended)
-
-| Step | What | Files |
-|------|------|--------|
-| 1 | Resolve and pass `user_telegram`, `thread_id`, `update_id` in responder | `responder.ts` |
-| 2 | Insert user message at start; if `null`, return (no AI, no reply) | `responder.ts`, `database/messages.ts` (already has API) |
-| 3 | Before each draft and before final reply: check `getMaxTelegramUpdateIdForThread`; if max ≠ our `update_id`, abort send | `responder.ts` |
-| 4 | After successful `ctx.reply`, insert assistant message | `responder.ts` |
-| 5 | (Later) Load thread history and pass to AI | `responder.ts`, `ai/openai.ts`, `ai/transmitter.ts` |
-
----
-
-## Edge cases
-
-- **No username:** If `user_telegram` is empty (no `ctx.from.username`), we can skip all DB calls and keep current behavior (reply without persisting), or refuse to reply; plan suggests skip persistence only.
-- **User not in DB:** `insertMessage` uses FK to `users(telegram_username)`. Grammy already upserts on message, so the user should exist. If we ever process before upsert, we’d get an FK error; keep upsert as first step in grammy (current behavior).
-- **Schema not run:** Ensure `ensureSchema()` runs before handlers (e.g. at deploy via `db:migrate`); no change needed if already in place.
-
----
-
-## Summary
-
-1. **Tell first:** This document is the plan.
-2. **Implement 1–4** so the bot persists user and assistant messages and uses the DB for "only latest wins" (no mixing in serverless).
-3. **Implement 5** later to add thread history to the AI.