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

package/docs/blue_bar_tackling.md

@@ -1,143 +0,0 @@
-## Blue bar & cursor issue in GlobalBottomBar (Telegram Mini App, iOS)
-
-### Context
-
-- The issue appears **only inside the Telegram Mini App (TMA) on iOS**.
-- The affected element is the **bottom AI input** implemented by `GlobalBottomBar` (`TextInput` wrapped in a `ScrollView`, with a custom scrollbar on the right).
-- On **desktop web** and standard browsers, the input behaves as intended: normal caret, no intrusive system scrollbar; our custom scrollbar is visible and correct.
-- On **Telegram Desktop TMA**, behavior also looks acceptable.
-- On **Telegram iOS TMA**, a **thick vertical blue line** appears on the right side of the input, and it visually replaces/obscures the caret, especially near the right edge of the text.
-
-### What the blue bar is
-
-- The blue bar is **not our custom scrollbar** and not a React Native element.
-- It is the **system scroll thumb** / scrollbar rendered by the iOS WebView that Telegram uses for Mini Apps:
-  - Appears when the underlying DOM element backing `TextInput` is scrollable.
-  - On iOS it is rendered as a thick blue bar overlay on the right.
-  - Its color and thickness are **controlled by the OS / WebView**, not standard CSS in many cases.
-- Even when we:
-  - Add `scrollbar-width: none;` (Firefox),
-  - Add `-ms-overflow-style: none;` (IE/Edge),
-  - Add `::-webkit-scrollbar { width: 0; height: 0; }` (WebKit),
-  the iOS Telegram WebView **still draws** this overlay thumb in some configurations.
-
-### Current RN Web / layout setup
-
-- `TextInput` (RN Web) is rendered with:
-  - `multiline`
-  - `lineHeight = 20`
-  - Dynamic height controlled via `inputDynamicStyle` (1–8 lines).
-  - `scrollEnabled={Platform.OS !== "web"}` so **on web** we *try* to disable internal scrolling.
-- Around this `TextInput` we have:
-  - An outer `ScrollView` that provides scrolling for long content.
-  - A **custom scrollbar** drawn along the bar edge, based on `scrollY` and `contentHeight`.
-- We also:
-  - Inject a `<style>` tag on web to hide scrollbars on any `[data-ai-input="true"]`.
-  - Add a right-side overlay `View` (gutter) inside the input container on web, with:
-    - `position: "absolute"`, `right: 0`, `top: 0`, `bottom: 0`, `width: 10`,
-    - `backgroundColor: colors.background`,
-    - `pointerEvents: "none"`.
-  - Increase `paddingRight` on the input on web so the caret and last characters do not go under the overlay.
-
-### Observed behavior by platform
-
-- **Desktop web (normal browser)**:
-  - Native scroll thumb is hidden (CSS + overlay).
-  - Text caret is clearly visible at the end of the text.
-  - Our custom scrollbar works and reflects scroll position correctly.
-
-- **Telegram Desktop TMA**:
-  - Behavior closely matches desktop web.
-  - No problematic blue bar; caret looks normal.
-
-- **Telegram iOS TMA**:
-  - A thick **blue vertical bar** still appears on the right side of the input.
-  - The bar roughly aligns with where the platform scroll thumb would sit.
-  - It **does not fully respect** our CSS scrollbar-hiding rules.
-  - It appears even when:
-    - `scrollEnabled={false}` on the `TextInput` for web.
-    - We rely solely on the outer `ScrollView` for scroll.
-    - We overlay the right edge with a background-colored React `View`.
-  - The caret is technically present, but visually:
-    - The blue bar is more dominant than the caret and sits at the same x-position,
-    - So the user perceives it as a “weird blue cursor” instead of a scroll thumb.
-  - The last character near the right edge can appear slightly crowded/overlapped because of how the webview draws the thumb and because we are trying to line things up tightly near the arrow icon.
-
-### Why Flutter/dart implementation did not show this issue
-
-- The original Flutter implementation ran as **native UI** (or Flutter Web with different internals), not as React Native Web inside Telegram’s custom webview.
-- Flutter’s text fields:
-  - Use their own composited rendering and native text controls.
-  - Have direct hooks into platform scroll behavior and caret rendering.
-  - Can fully own the scrollable area and scrollbar appearance.
-- In contrast, RN Web:
-  - Uses the browser/Telegram WebView’s textarea or contenteditable under the hood.
-  - Has to live with OS/WebView scroll thumb behavior.
-  - Only partially controls scrollbars via CSS, which the iOS Telegram WebView may override.
-
-### Why the bar is blue and how much we can style it
-
-- On iOS Safari / WebView, the scroll thumb color and style are **not standard CSS-stylable**:
-  - There is no official `::-webkit-scrollbar-thumb` support for iOS Safari comparable to desktop.
-  - The color (blue) is tied to the system accent / theme and internal WebKit defaults.
-  - Telegram’s WebView may apply its own styling on top.
-- Because of this:
-  - We **cannot reliably change** the thumb color to match our background.
-  - We **cannot reliably make it fully transparent** without also breaking scrolling in this embedded environment.
-  - Any success we get with `::-webkit-scrollbar*` rules on desktop Safari/Chrome does not necessarily carry over to Telegram iOS.
-
-### Attempts made so far (and results)
-
-1. **CSS-based hiding on `[data-ai-input="true"]`**  
-   - Rules: `scrollbar-width: none;`, `-ms-overflow-style: none;`, `::-webkit-scrollbar { width: 0; }`.  
-   - Works in normal browsers and some webviews.  
-   - In Telegram iOS WebView, the blue bar persists.
-
-2. **Disabling internal `TextInput` scrolling on web**  
-   - `scrollEnabled={Platform.OS !== "web"}` to avoid the input’s own scrollable area.  
-   - Rely on outer `ScrollView` + custom scrollbar.  
-   - The blue thumb still appears in TMA iOS, suggesting the underlying DOM element is still treated as scrollable by the WebView (or the thumb is drawn by an outer layer).
-
-3. **Right-edge overlay gutter**  
-   - Relative container + absolutely positioned right-side `View` with `backgroundColor: colors.background`.  
-   - `pointerEvents="none"` so it doesn’t break input.  
-   - On desktop, this effectively hides any native thumb.  
-   - On Telegram iOS, the blue bar can still appear visually on top or just beside that gutter, i.e. the overlay does not fully cover what the WebView paints.
-
-4. **Extra `paddingRight` on the input**  
-   - Prevents text/caret from touching the thumb/overlay region.  
-   - Improves readability of the last character, but the blue line remains visible.
-
-5. **DOM scroll listener + custom scrollbar**  
-   - We now track `scrollTop` of the underlying DOM node and sync our custom scrollbar correctly.  
-   - This is independent of the blue bar; it only ensures scroll indicator accuracy.
-
-### Current understanding / constraints
-
-- The blue bar on iOS Telegram Mini App is **owned by the host WebView**, not by our CSS or RN Web.  
-- That WebView:
-  - May treat the entire scrollable area (outer + inner) as a single scrollable region and draw an overlay thumb for accessibility/UX.
-  - May ignore some CSS attempts to hide or restyle the thumb.
-- Because of these constraints:
-  - We **cannot guarantee complete removal** or recoloring of the blue bar in all TMA/iOS cases.
-  - The safest path is to ensure:
-    - The caret and text are not visually overlapped (padding + layout tweaks).
-    - Our own scrollbar remains accurate and subtle.
-    - We don’t break native input behavior (selection, IME, copy/paste, scroll).
-
-### Potential future mitigations
-
-- **Platform-specific layout tweaks for TMA iOS**:
-  - Detect `Telegram.WebApp.platform === "ios"` in JS and:
-    - Increase right gutter width.
-    - Slightly reduce the visible width of the input to give the thumb more room.
-  - Accept that the bar exists but keep it visually away from text/caret.
-
-- **Experiment with non-scrollable inner element**:
-  - Render text inside a non-scrollable container and rely solely on outer scrolling.  
-  - Risk: may break text selection behavior and IME interaction in TMA; needs careful testing.
-
-- **Ask Telegram / WebView owners**:
-  - There may be feature flags or Meta tags specific to Telegram’s WebView that influence scrollbar presentation on iOS.
-  - If such an option exists, it would be the cleanest way to disable the blue overlay globally for the Mini App.
-

package/docs/bot_async_streaming.md

@@ -1,174 +0,0 @@
-## Bot async streaming & Telegram constraints
-
-This document captures the current behavior of the Telegram bot streaming path, the issues we observed, and the gap between the ideal "multi-segment async streaming" design and the current implementation.
-
----
-
-## 1. Constraints and goals
-
-### Telegram constraints
-
-- **Per-message length limit:** Telegram's `parse_mode: "HTML"` messages must be ≤ **4096 characters** after HTML escaping and tagging.
-- **HTML parsing rules:** Only specific tags are allowed (`<b>`, `<i>`, `<u>`, `<s>`, `<tg-spoiler>`, `<a>`, `<code>`, `<pre>`, `<blockquote>`). All `<`, `>`, `&`, `"` must be escaped unless they are part of a valid tag or entity; otherwise Telegram returns `Bad Request: can't parse entities`.
-- **Delivery semantics:**
-  - A user's outgoing message shows a **clock** until Telegram's server accepts it, then switches to ✓/✓✓.
-  - Our bot's webhook `handleRequest` must return HTTP 2xx quickly; otherwise Telegram retries and may delay/hide the user's message.
-  - We return 200 immediately and process updates in `waitUntil`; updates for the **same chat** are serialized via a per-chat queue so Reply A is sent before we start processing Prompt B (see `app/bot/webhook.ts`).
-
-### Product goals
-
-- **Bot replies must be well-formed HTML and ≤4096 characters per message** so Telegram doesn't reject them.
-- **Single message preferred;** when the AI output exceeds 4096 characters, the overflow is sent as **continuation message(s)** (each ≤4096), so the user sees the full reply.
-- **Per-chat serialization at webhook:** updates for the same chat are processed one after another so Reply A is sent before we start Prompt B.
-- **Cancellation within a chat:** we track a generation counter per chat; when a new message arrives for that chat, the in-flight stream is cancelled so only the latest reply is completed.
-
----
-
-## 2. Current implementation
-
-### 2.1 AI layer (shared bot + TMA)
-
-File: `app/ai/openai.ts`, `app/ai/transmitter.ts`
-
-- `callOpenAiChat` / `callOpenAiChatStream` wrap the OpenAI Responses API (`client.responses.create` / `client.responses.stream`).
-- They accept:
-  - `mode` (`"chat"` or `"token_info"`),
-  - `input` (text; for token_info a prefix is prepended in openai; for chat, history is prepended in transmitter),
-  - `context` (arbitrary metadata),
-  - optional `threadContext` (for DB persistence),
-  - optional `instructions` (string passed to the model; OpenAI native `instructions` field).
-- **Bot** requests are initiated from `app/bot/responder.ts`, which sets `instructions: TELEGRAM_BOT_LENGTH_INSTRUCTION` on every transmit/transmitStream call. That instruction asks the model to keep replies under 4096 chars and to mention that full responses are available in TMA when the user asks for long messages.
-- The AI layer does **not** derive instructions from `threadContext.type`; the caller (responder) supplies `instructions` when present. `transmitter` forwards `request.instructions` to the OpenAI layer.
-- For **token_info**, openai still prepends a system-style prefix to `input` ("You are a blockchain and token analyst...").
-- `transmit` / `transmitStream`:
-  - Claim the user message in the DB (`insertMessage` + `telegram_update_id`), or return `skipped` if another instance already handled it.
-  - For chat mode, prepend conversation history with `formatHistoryForInput`.
-  - Call OpenAI (with or without streaming).
-  - On success, persist the assistant `output_text` to the `messages` table.
-
-### 2.2 Bot responder (Telegram side)
-
-File: `app/bot/responder.ts`
-
-#### 2.2.1 Concurrency & cancellation
-
-- We track **per-chat generations** (key is `chatId`, not thread_id):
-
-  ```ts
-  const chatGenerations = new Map<number, number>();
-  const numericChatId = typeof chatId === "number" ? chatId : undefined;
-  let generation = 0;
-  if (numericChatId !== undefined) {
-    const prev = chatGenerations.get(numericChatId) ?? 0;
-    generation = prev + 1;
-    chatGenerations.set(numericChatId, generation);
-  }
-  const isCancelled = (): boolean =>
-    numericChatId !== undefined &&
-    chatGenerations.get(numericChatId) !== generation;
-  ```
-
-- `shouldAbortSend()` checks the DB (`getMaxTelegramUpdateIdForThread`) for the latest user `telegram_update_id`; if the current update isn't the latest for that thread, it returns `true`.
-- `transmitStream` receives:
-
-  ```ts
-  {
-    isCancelled,
-    getAbortSignal: async () => (await shouldAbortSend()) || isCancelled(),
-  }
-  ```
-
-  and uses this to abort the OpenAI stream if a newer prompt arrives.
-
-- When a stream is cancelled mid-way, `responder.ts` calls `sendInterruptedReply`:
-  - If we already created and edited a message for this reply and have non-empty `streamedAccumulated`, we do one last `editMessageText` (HTML) to finish that message and persist the partial content.
-  - If the reply was cancelled before any text was sent but we have some accumulated content, we send a single capped HTML reply with that content and persist it.
-  - If we have no content and `sendToChat` is true, we may send a single "…" reply.
-
-Together with the per-chat queue in the webhook (see 2.2.3), replies for the same chat are serialized so Reply A is sent before we start Prompt B; within that, the generation counter ensures the latest prompt wins and in-flight streams are cancelled.
-
-#### 2.2.2 Streaming and overflow (multi-message)
-
-- We use a **single streaming segment** for the first 4096 characters:
-
-  ```ts
-  const MAX_MESSAGE_TEXT_LENGTH = 4096;
-  let streamSentMessageId: number | null = null;
-  let streamedAccumulated = "";
-  ```
-
-- `sendOrEdit` is called on every `onDelta` from OpenAI and:
-  - Updates `streamedAccumulated`.
-  - Computes `slice = accumulated.slice(0, MAX_MESSAGE_TEXT_LENGTH)`.
-  - Formats `slice` via `mdToTelegramHtml` → `stripUnpairedMarkdownDelimiters` → `closeOpenTelegramHtml` → `truncateTelegramHtmlSafe`.
-  - Sends/edits a single Telegram message (first `sendMessage` with `"…"`, then `editMessageText` on `streamSentMessageId`), guarded by `sendOrEditQueue` and `editsDisabled`.
-- After `transmitStream` completes:
-  - We flush the edit queue and perform a **final edit** on `streamSentMessageId` with the first 4096 characters from `result.output_text` (formatted as HTML, with plain fallback on error).
-  - If `result.output_text.length > MAX_MESSAGE_TEXT_LENGTH`, we call **`sendLongMessage`** with the remainder (`result.output_text.slice(MAX_MESSAGE_TEXT_LENGTH)`). Continuation messages are sent as separate Telegram messages (each chunk ≤4096), formatted with the same HTML pipeline and Markdown/plain fallback; they reply to the previous message so they appear in order.
-- **Non-streaming path:** we call `transmit`; then if the result fits in one message we send a single reply; otherwise we call `sendLongMessage` with the full `result.output_text` (it chunks and sends multiple messages, each ≤4096).
-- Helpers **`chunkText`** and **`sendLongMessage`** in responder split long text at newlines when possible and send multiple messages, replying to the previous one so the thread reads in order.
-
-#### 2.2.3 Webhook concurrency
-
-- In `app/bot/webhook.ts` we **serialize updates per chat** using a `chatQueue`:
-
-  ```ts
-  const chatQueue = new Map<number, Promise<void>>();
-  // ...
-  const chatId = getChatIdFromUpdate(update);
-  const prev = chatId !== undefined ? chatQueue.get(chatId) : undefined;
-  const work = (prev ?? Promise.resolve())
-    .then(() => ensureBotInit())
-    .then(() => bot!.handleUpdate(update))
-    .then(() => { console.log('[webhook] handled update', updateId); })
-    .catch((err) => { console.error('[bot]', err); });
-  const tail = work.then(() => {}, () => {});
-  if (chatId !== undefined) chatQueue.set(chatId, tail);
-  waitUntil(work);
-  return jsonResponse({ ok: true });
-  ```
-
-- So for a given chat, the next update waits for the previous handler to finish. Reply A is sent before we start processing Prompt B, which avoids reorder flash. Different chats are still processed in parallel.
-
----
-
-## 3. Gaps vs. ideal multi-segment streaming design
-
-The ideal design would:
-
-1. **AI always produces full `output_text`** (already true).
-2. **Bot maintains multiple segment messages per reply:**
-   - Segment 0: chars `[0..4096)`, streamed live and finalized.
-   - Segment 1: chars `[4096..8192)`, streamed live in a second message, etc.
-3. **After completion**, each segment is edited once more to match the exact final slice of `output_text`.
-
-The **current implementation**:
-
-- **First segment** is streamed live (single message, up to 4096 chars) and gets a final edit from `result.output_text`.
-- **Overflow** (beyond 4096 chars) is sent **after** the stream completes via `sendLongMessage` as one or more continuation messages. We do **not** stream into the second (and further) segments live; only the first segment is streamed.
-- So the user gets the full reply (first message + continuation messages), but only the first 4096 characters are streamed; the rest is sent in one go after completion. The TMA path still gets the full `output_text` (no truncation).
-
-To implement **live streaming into multiple segments**, we would need to:
-
-- In `sendOrEdit`, detect when the accumulated text crosses 4096 and create a new Telegram message for the next segment, then route subsequent edits to the correct segment.
-- Maintain a `segments: { id: number; start: number; end: number }[]` (or similar) and issue a final `editMessageText` per segment on completion.
-
-That refactor adds state and edge cases (segment creation, cancellation across segments). The current approach (stream first segment, then send overflow as continuation messages) is simpler and still delivers the full reply.
-
----
-
-## 4. Known issues / open questions
-
-1. **"Clock + flash" in threads (historical vs. current):**
-   - With per-chat serialization at the webhook, Reply B does not start until Reply A's handler has finished (or at least until A's work is chained after). So we avoid overlapping replies in the same chat; the "clock + flash" reorder is largely avoided because A completes before B starts.
-   - Cancellation (generation counter) still matters when A is cancelled by B so that we don't keep editing A after B has been sent.
-
-2. **Length vs. HTML edge cases:**
-   - We depend on the model respecting the 4096-character instruction; if it overshoots, we truncate, then trim at the last `>` and call `closeOpenTelegramHtml` to avoid cutting tags in half.
-   - "Bad Request: can't parse entities" can still occur on malformed HTML; `stripUnpairedMarkdownDelimiters` + `closeOpenTelegramHtml` + `truncateTelegramHtmlSafe` reduce this.
-
-3. **Segment-level streaming:** Only the first segment is streamed live; overflow is sent after completion. For truly long live multi-segment streaming we'd need the refactor described in §3.
-
-4. **Behavior when cancellation happens late:** If `isCancelled()` flips very close to the end of a stream, the final edit might still land. We check `shouldAbortSend()` in `sendOrEditOnce` and before the final completion edit to reduce this.
-
-If you want to adjust any of these behaviors (e.g. live multi-segment streaming, or how we finalize a cancelled reply), we can extend this design and update `responder.ts` accordingly.

package/docs/build_and_install.md

@@ -1,129 +0,0 @@
-# Build and Install: Faster & Better
-
-This doc describes the Windows Electron build and install flow and how to speed them up and improve them.
-
-Exe creating example:
-
-```
-cd /d C:\1\1\1\1\1\HyperlinksSpaceProgram
-npm run build:win:verbose
-```
-
-Exe bash run example:
-
-```
-powershell -NoProfile -Command "Start-Process -FilePath 'C:/1/1/1/1/1/HyperlinksSpaceBot/releases/builder/build_03252026_1449/HyperlinksSpaceProgramInstaller_03252026_1449.exe'"
-```
-
----
-
-## 1. Build process
-
-### What runs
-
-`npm run build:win` does three things:
-
-1. **Expo web export** – `npm run build` → `expo export -p web`. Metro bundles the app and writes static files to `dist/`. Usually the slowest step (tens of seconds).
-2. **Electron pack** – `electron-builder --win`. Rebuilds native deps (if any), packages the app, builds the NSIS installer. Downloads (Electron, NSIS, winCodeSign) are cached after first run.
-3. **Clean** – `node windows/cleanup.cjs`. Moves artifacts into `releases/builder/build_MMDDYYYY_HHMM/` (installer only at root; zip, yml, unpacked, and other artifacts under `dev/`).
-
-**Output:** `releases/builder/build_<date>_<time>/HyperlinksSpaceProgramInstaller_<stamp>.exe` at root and `dev/` (portable zip, latest.yml, zip-latest.yml, win-unpacked, blockmap, builder-debug.yml, builder-effective-config.yaml).
-
-### How to make the build faster
-
-| Goal | What to do |
-|------|------------|
-| **Skip Expo when only Electron changed** | Use `npm run pack:win` when `dist/` is already up to date (no Expo app changes). Saves the full Expo/Metro run (often 30–60+ s). |
-| **Skip native rebuild** | In `package.json` → `build`, add `"npmRebuild": false`. The packaged app only runs the web bundle; native rebuild can often be skipped. Try it; if the app runs, keep it. Saves time every build. |
-| **Avoid building the installer when iterating** | Use `npm run build:win:dir` when you only need the unpacked app (e.g. quick runs from `release/win-unpacked/app.exe`). Skips NSIS and clean; faster and no “file locked” risk. |
-| **Keep caches** | Don’t clear Metro/Expo cache unless needed. Electron and electron-builder caches (e.g. under `%LOCALAPPDATA%\electron-builder\Cache`) are reused; leave them. |
-| **Verbose only when debugging** | Use `npm run build:win:verbose` only to diagnose failures; normal builds are quicker without DEBUG. |
-| **Faster installer step (7z/NSIS)** | The slowest step is 7-Zip compressing the packed app (~31k files, hundreds of MB). Use `build:win:dir` when you don’t need the installer. For full builds, set `nsis.compression: "normal"` or `"store"` in `package.json` → `build.nsis` to trade installer size for speed (e.g. 50–70% faster with `"store"`). |
-
-### Rebuilding only what changed
-
-- **Caches:** Expo/Metro and electron-builder already use caches. A full `build:win` reuses cached transforms and packed files where nothing changed, so rebuilds are partly incremental by default.
-- **Skip the web build when only Electron changed:** If you only changed `windows/build.cjs` or other files in `windows/`, the icon, or `package.json` build config (not the React app code), run **`npm run pack:win`** instead of `build:win`. That runs only electron-builder + clean and reuses the existing `dist/`. Ensure `dist/` is up to date (run `npm run build` once, or after any Expo app changes).
-
----
-
-## 2. Install process
-
-### What runs
-
-User runs **`HyperlinksSpaceProgramInstaller.exe`**. NSIS extracts the app (e.g. to `%LOCALAPPDATA%` or Program Files), creates shortcuts, and optionally adds Start Menu / Desktop entries. After that, launching the app runs the already-extracted exe (no extraction at startup → fast launch).
-
-### How to make install faster and more reliable
-
-| Goal | What to do |
-|------|------------|
-| **Avoid “file locked” / long waits** | Add the project or `release` folder to Windows Defender (or AV) exclusions so the new exe isn’t scanned/locked during build. For end users, a one-time exclusion for the installer download folder can reduce install time. |
-| **Faster first launch after install** | Install to an SSD if possible. First launch may trigger AV scan once; exclusions help. |
-| **Fewer prompts** | NSIS can be configured for one-click install (no “Choose directory” step) to shorten the flow; current config can be tuned in `build.nsis` (e.g. `oneClick: true` if desired). |
-| **Run installer as admin only if needed** | For per-machine install to Program Files, run the installer as Administrator. For per-user install (default), no admin needed. |
-
----
-
-## 3. Improvements for both
-
-| Area | Suggestion |
-|------|------------|
-| **Code signing** | Sign the installer and app exe (e.g. Windows Authenticode) so Windows and AV trust it. Reduces warnings and can speed up install/launch. |
-| **Auto-updates** | Add `electron-updater` (or similar) and serve updates over HTTPS so users get patches without reinstalling. |
-| **CI/CD** | In CI, cache `node_modules`, `.expo`, Metro cache, and `electron-builder` cache to make repeated builds much faster. |
-| **Developer Mode (Windows)** | If you build on Windows and use exe editing (icon, etc.), Developer Mode avoids symlink errors during the winCodeSign step. |
-| **Structured releases** | `windows/cleanup.cjs` puts each build in `releases/builder/build_<date>_<time>/` with the installer at root and all other artifacts in `dev/`. |
-
----
-
-## 4. Quick reference
-
-| Script | Use when |
-|--------|----------|
-| `npm run build:win` | Full build: Expo export + Electron + NSIS + clean. Use for releases. |
-| `npm run pack:win` | Electron + clean only; reuses existing `dist/`. Use when only Electron/wrapper changed (no app code). |
-| `npm run build:win:dir` | Same export + pack but no installer; output is `release/win-unpacked/`. Use for quick local runs. |
-| `npm run build:win:verbose` | Full build with `DEBUG=electron-builder` for troubleshooting. |
-
----
-
-## 5. File layout after build
-
-- **After `build:win` or `pack:win`:** `releases/builder/build_MMDDYYYY_HHMM/HyperlinksSpaceProgramInstaller_<stamp>.exe` and `releases/builder/build_MMDDYYYY_HHMM/dev/` (portable zip, yml, win-unpacked, blockmap, builder-debug.yml, builder-effective-config.yaml).
-- **After `build:win:dir`:** `release/win-unpacked/` (run `app.exe` from there).
-- **Build inputs:** `dist/` (Expo export), `windows/` (build.cjs, app-shell.html, preload-log.cjs), `assets/icon.ico`, and files listed under `build.files` in `package.json`.
-
----
-
-## 6. Conclusions (build verbosity and improvements)
-
-### What the slow step is
-
-When you run a full Windows build with verbose logging (`build:win:verbose`), the long part is **7-Zip compressing the packed app** for the NSIS installer. electron-builder:
-
-1. Builds the unpacked app (Expo export + Electron pack) into `release/win-unpacked/`.
-2. Runs 7za to compress that into a single archive (e.g. `expo-template-default-53.0.43-x64.nsis.7z`).
-3. Runs NSIS to wrap that archive into `HyperlinksSpaceProgramInstaller.exe`.
-
-Step 2 compresses a large number of files (tens of thousands) and hundreds of MB, so it dominates build time. The final installer size is much smaller (e.g. ~141 MB) but the compression work is heavy.
-
-### Why the payload is big
-
-The packed app under `release/win-unpacked/resources/app/` should contain only what’s in `build.files` (e.g. `dist/**/*`, `windows/**`, `assets/icon.ico`). If you see `node_modules` or other unneeded folders there, the payload is larger than necessary. Check with:
-
-- `dir release\win-unpacked\resources\app` (or list that folder) before the installer step.
-
-If `node_modules` is present, tighten `build.files` or add exclusions so only what the packaged app needs is included; that will also speed up the 7z step.
-
-### How to improve the process
-
-| Improvement | Action |
-|-------------|--------|
-| **Skip the slow step when possible** | Use `npm run build:win:dir` for daily work. You get the unpacked app and can run it from `release/win-unpacked/app.exe`; 7z and NSIS are skipped. |
-| **Faster 7z at the cost of installer size** | In `package.json` → `build.nsis`, set `"compression": "normal"` or `"store"`. `"store"` (no compression) can cut installer build time by roughly 50–70%; the resulting `.exe` will be larger. |
-| **Keep the table in §1** | Use the “How to make the build faster” table (skip Expo when possible, `npmRebuild: false`, AV exclusions, etc.) together with the compression and dir-build options above. |
-
-### Summary
-
-- **Slow step:** 7-Zip compressing the packed app (many files, large size) before NSIS.
-- **Improvements:** Use `build:win:dir` when you don’t need the installer; lower NSIS compression for faster full builds; ensure only needed files are packed (no stray `node_modules`); use the other tips in this doc (pack-only script, caches, AV exclusions).

package/docs/database_messages.md

@@ -1,34 +0,0 @@
-### 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

@@ -1,18 +0,0 @@
-# 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/npm-release.md

@@ -1,46 +0,0 @@
-# Milestone snapshot package (npm)
-
-This repository includes a publishable snapshot package for fast developer bootstrap:
-
-- package source: repository root (published directly)
-- **npmjs (public):** `@www.hyperlinks.space/program-kit` — manage org and tokens: [www.hyperlinks.space on npm](https://www.npmjs.com/settings/www.hyperlinks.space/packages)
-- **GitHub Packages:** `@hyperlinksspace/program-kit` (same version; GitHub requires the package scope to match this repo's owner)
-
-## Verify publish payload locally
-
-The npm package page uses `README.md` from the published tarball, not `npmReadMe.md`. The published package also includes **`fullREADME.md`**, a copy of the developer readme (saved before the npm readme replaces `README.md`). Match CI before `npm pack`, then restore:
-
-```bash
-cp README.md fullREADME.md
-cp npmReadMe.md README.md
-npm pack --dry-run
-git checkout -- README.md
-rm -f fullREADME.md
-```
-
-## Install snapshot as a developer
-
-```bash
-npx @www.hyperlinks.space/program-kit ./my-hsp-app
-```
-
-The CLI materializes the bundled package payload into your target folder, then you run:
-
-```bash
-cd my-hsp-app
-npm install
-```
-
-## Release channels
-
-- `latest`: immutable stable snapshots (tag workflow `snapshot-vX.Y.Z`)
-- `next`: rolling snapshots from manual workflow dispatch
-
-In the output, you'll find options to open the app in:
-
-- [a development build](https://docs.expo.dev/develop/development-builds/introduction/)
-- [an Android emulator](https://docs.expo.dev/workflow/android-studio-emulator/)
-- [an iOS simulator](https://docs.expo.dev/workflow/ios-simulator/)
-- [Expo Go](https://expo.dev/go), a limited sandbox for trying out app development with Expo
-
-You can start developing by editing the files inside the **app** directory. This project uses [file-based routing](https://docs.expo.dev/router/introduction).