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

package/docs/wallet_telegram_standalone_multichain_proposal.md

@@ -0,0 +1,192 @@
+# Unified Wallet Model: Telegram, Standalone, Multi-Chain & DLLR (TON)
+
+This document proposes a single coherent setup for the tensions between:
+
+- A **Telegram-first** experience (Mini App, bot confirmations, CloudStorage-assisted UX).
+- **Standalone operation** when Telegram is unavailable, blocked, or the user simply prefers not to use it.
+- **Non-custodial** custody: keys and mnemonics never held by our servers.
+- **DLLR** and core product flows anchored on **TON**, where issuance and program logic are expected to live.
+- **Multiple chains** where users may hold assets or use bridges, without fragmenting identity or safety.
+
+It complements `wallets_hosting_architecture.md`, `security_raw.md`, and `security_plan_raw.md` by resolving “which path wins when” and how they fit together.
+
+---
+
+## 1. Core idea: one logical wallet, three *surfaces*
+
+Think in terms of **one user-owned root of trust** (mnemonic for the primary TON wallet, and optional additional key material for other chains), and **three ways to use it**:
+
+| Surface | What it is | Best for |
+|--------|------------|----------|
+| **A. Telegram-hosted (TMA)** | Same non-custodial keys; encrypted material split between Telegram `SecureStorage` + `CloudStorage` (ciphertext only), identity via `initData`. | Smoothest UX inside Telegram, bot-driven tx confirmation, push-to-sign. |
+| **B. Unhosted / standalone** | Keys only on device OS keystore / WebCrypto; no Telegram APIs required to open the app or sign. | Telegram outage, privacy preference, store-review-friendly “works without Telegram”. |
+| **C. Connected** | External wallets via **TON Connect** (TON) and, later, analogous **WalletConnect** / chain-specific SDKs for other networks. | Power users, hardware wallets, assets already elsewhere. |
+
+**Important:** Surfaces are **not** different custodial models. They differ only in **where keys live** and **which transport** is used for identity and sync. The backend stores **public** data (addresses, `telegram_username` ↔ address mapping when the user opts in), never mnemonics.
+
+---
+
+## 2. Why Telegram alone is not enough (and how we fix it)
+
+Telegram can be unreachable (outage, censorship, user choice). A product that *only* creates or signs inside the Mini App forces a hard dependency on Telegram for custody and signing.
+
+**Proposal:**
+
+1. **Default recommended path** remains: create primary **TON** wallet in TMA (best onboarding, aligns with bot + DLLR messaging).
+2. **Mandatory parallel capability:** the same app build supports **Create / Restore wallet locally** (standalone) with **no Telegram account** and **no bot call** for key generation.
+3. **Linking layer (optional):** if the user *has* Telegram, they can **link** `telegram_username` ↔ `wallet_address` so CloudStorage sync and bot confirmations work. If they never link, they remain fully standalone; DLLR/Ton features still work on-chain by address.
+4. **Degraded mode:** if Telegram is down but the user already has keys on device, the app runs **full local signing** for TON (and any chain we have implemented client-side). Features that *require* the bot (e.g. push approval via Telegram) show a clear “Unavailable while Telegram is unreachable” with fallback: open pending items in TMA later, or confirm via standalone signing if the flow allows.
+
+This matches non-custodial rules: the server never becomes the signing authority.
+
+---
+
+## 3. DLLR on TON as the canonical product wallet
+
+**Clarification to remove confusion:**
+
+- **Primary app wallet** = **TON** address derived from the user’s main mnemonic (or from a TON Connect wallet they set as default).
+- **DLLR** is treated as a **TON jetton / program** (or locked-state construct per your issuance design). Balances, locks, and allocations are **read and signed on TON**.
+- “Multi-chain” does **not** mean DLLR exists on every chain. It means:
+  - **User may connect other addresses** for portfolio view, bridges, or future features.
+  - **Product-critical flows** (rewards, locks, compliance hooks tied to DLLR) stay **TON-first**.
+
+**UI rule:** always show a clear **“Primary (TON + DLLR)”** section, then **“Other networks”** as secondary, so expectations stay aligned with issuance on TON.
+
+---
+
+## 4. Multi-chain matrix (recommended model)
+
+Use a single **wallet registry** in the client and the `wallets` table (as in `security_plan_raw.md`), with explicit `blockchain`, `net`, and `type`:
+
+| Type | Example | Custody |
+|------|---------|--------|
+| `internal` | App-generated TON keypair | Non-custodial; keys in device/TMA storage |
+| `tonconnect` | Tonkeeper, MyTonWallet | User’s external wallet; we only hold address + session |
+| `walletconnect` / `evm` / `solana` (future) | MetaMask, Phantom, … | Same: address + connection state |
+
+**Telegram-hosted vs unhosted** applies only to **`internal`** wallets:
+
+- In TMA, `internal` wallet uses SecureStorage + CloudStorage ciphertext split.
+- In standalone app, `internal` wallet uses only OS secure storage (same cryptography, different storage adapters).
+
+**Connected** wallets are **always** “hosted” by the third-party provider, not by Telegram and not by us.
+
+---
+
+## 5. Identity: Telegram as optional glue, not a single gate
+
+Today’s docs lean **Telegram-first** for onboarding. The unified model adds:
+
+| User state | Can use app? | DLLR / TON actions |
+|------------|--------------|--------------------|
+| Standalone, never linked Telegram | Yes (after local create/restore) | Yes, if keys on device |
+| Telegram user, wallet only in TMA | Yes in TMA; on mobile/web after Telegram Login | Signing in TMA; read-only elsewhere unless mnemonic imported locally (optional advanced) |
+| Linked Telegram + local keys | Yes everywhere | Full: bot confirmations where implemented + local signing fallback |
+
+**Backend:**
+
+- `users.telegram_username` is **nullable** for standalone-only users, or use a separate **account id** (emailless) keyed by device-chosen identifier only for analytics—not for custody.
+- Linking Telegram is a **deliberate** step: “Connect Telegram for notifications and faster sync.”
+
+---
+
+## 6. First run and subsequent runs (program behavior)
+
+This section describes what the **client program** does on **cold start** (first launch or fresh install) versus **later launches** on the same install, for each major surface. It aligns with the state machine in `wallets_hosting_architecture.md` (e.g. `awallet_v1`, deploy status).
+
+### 6.1 Shared startup sequence (all surfaces)
+
+1. **Bootstrap UI shell** — Router loads; global providers start (network, wallet context).
+2. **Detect environment** — `TMA` (Telegram WebApp present) vs **standalone** (Expo native / open web) vs **web + Telegram Login** (widget session).
+3. **Resolve wallet presence** — Read local secure storage keys (`awallet_v1` or equivalent): encrypted blob for `internal` wallet, plus any **connected** wallet session handles (TON Connect).
+4. **Branch:**
+   - **No wallet record** → onboarding (Section 6.2).
+   - **Wallet record present** → main app (Section 6.3).
+
+Balances and DLLR/TON state are **always** refreshed asynchronously after UI is usable (do not block first paint on RPC unless product requires it).
+
+---
+
+### 6.2 First run (no wallet on this install)
+
+| Entry | What the user sees | What the program does |
+|--------|--------------------|------------------------|
+| **Telegram Mini App** | Intro → **Create wallet** / **Restore wallet** (optional **Connect Tonkeeper** if offered). | Generates mnemonic locally; stores **wallet master key** in Telegram `SecureStorage`; stores **seed ciphertext** in `CloudStorage`; registers **public** `wallet_address` (+ `telegram_username` from `initData`) with backend. Shows address and QR immediately; may show **Deploying** for SMC/jetton setup; nudges **backup seed**. |
+| **Standalone (native / web, no Telegram)** | Same choice: **Create** / **Restore** / **Connect** external wallet. | Generates or imports keys using **only** OS keystore / WebCrypto; **no** `initData`, **no** CloudStorage unless user later links Telegram. Optional backend call with a **non-Telegram** account id or anonymous mode until linked. |
+| **Store mobile app (Telegram-centric onboarding)** | Per `security_raw.md`: “Create wallet in Telegram” vs “I already have a wallet” + **Log in with Telegram**. | First path deep-links to TMA; second uses **Telegram Login** to fetch **public** linkage (`username` → `wallet_address`) for **read-only** until user imports mnemonic on device (if you add that flow). |
+
+**First run, new Telegram device (TMA):** `CloudStorage` may already hold **ciphertext** from another device, but **SecureStorage** is empty → program shows **Authorize this device** and asks for **mnemonic once**, then writes local master key and proceeds as normal.
+
+**First run, connected wallet only (TON Connect):** No internal blob; program stores connection session + address; primary balance flows use that address until user adds an `internal` wallet.
+
+---
+
+### 6.3 Subsequent runs (wallet already on this device)
+
+| Condition | Program behavior |
+|-----------|------------------|
+| **Encrypted blob + device key present** | **Silent load:** decrypt wallet, navigate to **home / wallet** without asking for seed. Poll `/wallet/status` or chain APIs for **deploy status**, **TON balance**, **DLLR** state. If deploy was **pending**, **retry deploy** in background (same as `wallets_hosting_architecture.md`). |
+| **TMA + CloudStorage ciphertext + SecureStorage OK** | Same silent path; CloudStorage may sync updates from other Telegram clients. |
+| **Standalone + keys in local secure storage** | Same as row 1; **no** Telegram dependency for open or sign. |
+| **User opened “Log in with Telegram” on mobile** | After verified login, app loads **cached** `telegram_username` + **addresses** from API; UI is **read-first** until local signing is enabled (mnemonic import), matching your phased plan. |
+| **Telegram unavailable (outage / blocked)** | If keys exist locally: **full app** for signing and reads that do not need the bot. If keys exist **only** in TMA on a device that cannot open Telegram: user must use **restore** on standalone build or wait for Telegram. Features that need the bot show **degraded / queue** messaging. |
+| **App update** | Same storage keys (`awallet_v1` versioning); run **migration** if blob format bumps. Wallet survives update if paths are stable. |
+
+**Subsequent run UX expectations:** back up seed remains **dismissible** until acknowledged; high-value actions may still route through **pending tx + bot confirmation** when Telegram is linked and the flow requires it.
+
+---
+
+### 6.4 Summary table
+
+| | First run | Subsequent runs |
+|---|-----------|-----------------|
+| **Typical path** | Onboarding → create / restore / connect | Silent unlock → home → background balance/deploy sync |
+| **Telegram required?** | Only for TMA path or Telegram-login shell | No, if standalone keys exist; yes for TMA-specific features |
+| **Seed prompt** | At creation (show once) or restore; optional “authorize device” on new TMA device | Only if blob missing, storage wiped, or user hits **Restore** |
+
+---
+
+## 7. “Perfect setup” summary (one paragraph)
+
+**Ship one Expo app** with three entry modes: (1) **Telegram Mini App** for best-in-class onboarding, CloudStorage-backed ciphertext sync, and bot-mediated confirmations; (2) **standalone** create/restore so the app **always launches** and can sign TON (and DLLR) without Telegram; (3) **TON Connect + future multi-chain connectors** for imported liquidity and power users. Treat **TON + DLLR** as the single source of truth for product economics; treat other chains as **attached accounts**. Keep **mnemonic / keys** only on the client, **ciphertext** in CloudStorage when Telegram is used, and **public addresses + optional Telegram link** on the server. When Telegram is down, **degrade gracefully**: local signing and read paths keep working; Telegram-only steps queue or hide with clear messaging.
+
+---
+
+## 8. Implementation phases (aligned with existing roadmap)
+
+1. **Phase A — Standalone parity (minimum viable resilience)**  
+   - Unhosted TON create/restore in **Expo web + native** without Telegram.  
+   - Same `WalletService` abstraction as in `wallets_hosting_architecture.md`; storage backend switches on environment (TMA vs native).  
+   - Optional “Link Telegram” after the fact.
+
+2. **Phase B — Linking & DB**  
+   - Nullable Telegram on `users`; `wallets` rows for `internal` + `tonconnect`.  
+   - Telegram Login only for users who want cross-surface sync.
+
+3. **Phase C — Bot confirmations + queue**  
+   - Pending tx from any client; confirmation in TMA when available; standalone users complete via **local sign** without bot where the protocol allows.
+
+4. **Phase D — Multi-chain read + selective write**  
+   - Add connected chains for **display** first; add signing per chain as product requires.
+
+---
+
+## 9. Security notes (unchanged principles)
+
+- No mnemonic on server; CloudStorage holds **ciphertext only**; device-bound keys decrypt.  
+- Telegram Login proves **identity**, not possession of keys.  
+- Standalone users rely on **seed backup** exactly as in self-custody best practice.  
+- DLLR issuance rules remain **on-chain** on TON; our app is a **client**, not an issuer.
+
+---
+
+## 10. Open decisions (to refine with product/legal)
+
+- Whether standalone users get **full** DLLR program participation or **subset** until KYC/Telegram link (if required by issuance policy).  
+- Exact **jetton master** and **wallet v4/v5** choices for DLLR display and deploy flows.  
+- Whether **one mnemonic** derives only TON or also other chains (prefer **separate mnemonics** per chain unless using a documented multi-chain HD profile).
+
+---
+
+*Proposal doc; iterate with team and adjust table/column names to match the actual migration from `security_plan_raw.md`.*

package/docs/wallets_hosting_architecture.md

@@ -254,4 +254,4 @@ Swap between implementations via a flag (`kUseMockWalletState` for dev, env-driv
 
 ---
 
-*Last updated: April 2026. Maintained in repo at `app/docs/wallet_architecture.md`.*
+*Last updated: April 2026. Maintained in repo at `docs/wallets_hosting_architecture.md`.*

package/fullREADME.md

@@ -1,68 +1,100 @@
-# Welcome to your Expo app 👋
-This is an [Expo](https://expo.dev) project created with [`create-expo-app`](https://www.npmjs.com/package/create-expo-app).
+![Preview Image](https://raw.githubusercontent.com/HyperlinksSpace/HyperlinksSpaceProgram/refs/heads/main/assets/images/PreviewImage.png)
 
-## Get started
+# Hyperlinks Space Program
 
-To start the app (and the Telegram bot in polling mode), run:
+<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
-npm run start
+npx @www.hyperlinks.space/program-kit ./new-program
 ```
 
-This runs both the Expo dev server and the bot. For Expo only (no bot), use `npm run start:expo`.
+Link to the package: https://www.npmjs.com/package/@www.hyperlinks.space/program-kit
 
-## Milestone snapshot package (npm)
+## Program design
 
-This repository includes a publishable snapshot package for fast developer bootstrap:
+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.
 
-- package source: `app/` (published directly, no duplicate snapshot folder)
-- **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)
+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.
 
-**npm ownership:** your token must be allowed to publish under scope `@www.hyperlinks.space` (org members or automation token with access to that org).
+## How to fork and contribute?
 
-### Verify publish payload locally
+1. Install GitHub CLI and authorize to GitHub from CLI for instant work
 
-The npm package page uses `README.md` from the published tarball, not `npmReadMe.md`. The published package also includes **`fullREADME.md`**, a copy of this developer readme (saved before the npm readme replaces `README.md`). Match CI before `npm pack`, then restore:
+```
+winget install --id GitHub.cli
+gh auth login
+```
 
-```bash
-cp README.md fullREADME.md
-cp npmReadMe.md README.md
-npm pack --dry-run
-git checkout -- README.md
-rm -f fullREADME.md
+2. Fork the repo, clone it and create a new branch and switch to it
+
+```
+gh repo fork https://github.com/HyperlinksSpace/HyperlinksSpaceBot.git --clone
+git checkout -b new-branch-for-an-update
+git switch -c new-branch-for-an-update
 ```
 
-### Install snapshot as a developer
+3. Make a commit (address unassigned issue or think yourself)
 
-```bash
-npx @www.hyperlinks.space/program-kit ./my-hsp-app
+```
+git add . # Stage changes on this branch
+git commit -m "Describe your change" # Commit on this branch
+```
+
+3. After making a commit, make a pull request, gh tool will already know the upstream remote
+
+```
+gh pr create --title "My new PR" --body "It is my best PR"
+```
+
+4. For subsequent commits (sync `main`, create a fresh branch, and commit there)
+
+```
+git checkout main # Return to main
+git fetch upstream # Fully sync with upstream main
+git reset --hard upstream/main # Reset local main to upstream/main
+git push origin main # Keep your fork main in sync too
+git switch -c new-branch-for-next-update # Create and switch to a new feature branch
 ```
 
-The CLI materializes the bundled package payload into your target folder, then you run:
+**Move in loops starting from the step 3.**
+
+## 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
+
+## Local deploy
+
+To start the full local stack, run:
 
 ```bash
-cd my-hsp-app
-npm install
+npm run start
 ```
 
-### Release channels
+This runs Expo dev server, the Telegram bot (polling mode), and local Vercel API (`vercel dev`).
 
-- `latest`: immutable stable snapshots (tag workflow `snapshot-vX.Y.Z`)
-- `next`: rolling snapshots from manual workflow dispatch
+Isolated/local run options:
 
-In the output, you'll find options to open the app in:
+- 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`
 
-- [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
+## Milestone snapshot package (npm)
 
-You can start developing by editing the files inside the **app** directory. This project uses [file-based routing](https://docs.expo.dev/router/introduction).
+NPM release and snapshot details were moved to `docs/npm-release.md`.
 
 ### Local env setup
 
-1. **Copy the example file** (from the `app/` directory):
+1. **Copy the example file** (from the repository root):
    ```bash
    cp .env.example .env
    ```
@@ -77,9 +109,22 @@ You can start developing by editing the files inside the **app** directory. This
 
 The `.env` file is gitignored; do not commit it.
 
-## Workflows
+## 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:
 
-This project is configured to use [EAS Workflows](https://docs.expo.dev/eas/workflows/get-started/) to automate some development and release processes. These commands are set up in [`package.json`](./package.json) and can be run using NPM scripts in your terminal.
+- [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
 
@@ -99,61 +144,36 @@ Expo offers hosting for websites and API functions via EAS Hosting. See the [Get
 
 ### Deploy web build to Vercel
 
-From this directory (`app/`), deploy the static web build to Vercel production:
+From the repository root, deploy the static web build to Vercel production:
 
 ```bash
 vercel --prod
 ```
 
-Deploying from `app/` 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.
+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 (Grammy)
 
-A minimal bot that replies "Hello" is included. It is deployable on Vercel via webhook and runnable locally with getUpdates.
+The bot is extended beyond a basic "Hello" and "Start program" responder and now supports AI streaming and threads.
 
 **Vercel (webhook)**  
-- **Env for deploy:** In Vercel → **Settings → Environment Variables** add **`BOT_TOKEN`** (or `TELEGRAM_BOT_TOKEN`). Assign to **Production** (and to **Build** if your dashboard has that option) so the deploy-step webhook script can run. The webhook URL is built from Vercel’s `VERCEL_PROJECT_PRODUCTION_URL` or `VERCEL_URL`.
-- **Webhook on deploy:** Each build runs `scripts/set-webhook.ts` and calls Telegram `setWebhook` with the base URL + `/api/bot`. If the script fails (e.g. missing URL or Telegram error), the build fails so you see the error in the deploy log.
-- Telegram sends updates to **POST** `/api/bot`; the bot replies "Hello".
+- **Runtime path:** Telegram sends updates to `POST /api/bot`. This route proxies to the shared bot webhook handler in `bot/webhook`.
+- **Webhook setup:** `scripts/set-webhook.ts` sets `https://<base>/api/bot` using `VERCEL_PROJECT_PRODUCTION_URL` (preferred) or `VERCEL_URL`.
+- **Required env:** set `BOT_TOKEN` (or `TELEGRAM_BOT_TOKEN`) in Vercel project envs for production deploys.
+- **Deploy flow:** webhook mode is intended for Vercel deploys (CLI `vercel --prod` or the manual GitHub Action `Vercel Deploy (Test Envs)`).
 
 **Bot works locally but not on Vercel**  
-1. Open **GET** `https://<your-app>.vercel.app/api/bot` in a browser. The JSON shows:
-   - `bot: true` → BOT_TOKEN is set; `bot: false` → add BOT_TOKEN in Vercel → Settings → Environment Variables (Production), then redeploy.
-   - `expected_url` → URL we use for the webhook (from VERCEL_PROJECT_PRODUCTION_URL or VERCEL_URL).
-   - `telegram_has` → URL Telegram actually has. It must match your production URL (e.g. `https://hsbexpo.vercel.app/api/bot`). If it’s `(none)` or different, ensure the project’s production domain is set in Vercel and redeploy so set-webhook.ts runs with the correct URL.
-   - `webhook_set: true` → last setWebhook call succeeded.
-2. **Root directory:** Only needed if you deploy via Git (auto-deploy from the repo). Then set **Root Directory** to **`app`** in Vercel → Project Settings → General. If you always run `vercel --prod` from inside `app/`, the CLI uses this folder as the project root and you don’t need to set it.
-3. **Logs:** After sending /start, check **Logs** for `[webhook] POST update` and any `[bot]` errors (e.g. handler_error, timeout).
-4. Don’t run the same bot in polling locally while testing the webhook (or Telegram may deliver updates to the wrong place).
+1. Confirm Vercel env has `BOT_TOKEN` and redeploy.
+2. Ensure the deployed URL is stable and matches the webhook target (`/api/bot`).
+3. Check deploy/runtime logs for `[set-webhook]` and `[webhook]` errors.
+4. Do not run local polling with the same token while validating webhook mode.
 
 **Local (getUpdates, no webhook)**  
-- Only `BOT_TOKEN` is required (in env or `.env`).
-- Run the bot in polling mode (do not use the same token with webhook set elsewhere):
-  ```bash
-  npx tsx scripts/run-bot-local.ts
-  ```
-- `npm run start` runs both Expo and the bot; or run the bot alone with `npm run bot:local`.
-
-## Get a fresh project
-
-When you're ready, run:
-
-```bash
-npm run reset-project
-```
-
-This command will move the starter code to the **app-example** directory and create a blank **app** directory where you can start developing.
-
-## Learn more
-
-To learn more about developing your project with Expo, look at the following resources:
-
-- [Expo documentation](https://docs.expo.dev/): Learn fundamentals, or go into advanced topics with our [guides](https://docs.expo.dev/guides).
-- [Learn Expo tutorial](https://docs.expo.dev/tutorial/introduction/): Follow a step-by-step tutorial where you'll create a project that runs on Android, iOS, and the web.
-
-## Join the community
+- Only `BOT_TOKEN` is required (env or `.env`).
+- Run bot only: `npm run bot:local`
+- Run full local stack (Expo + bot + Vercel): `npm run start`
+- Keep production and local bot tokens separate when possible to avoid webhook/polling conflicts.
 
-Join our community of developers creating universal apps.
+## Where to discuss the project?
 
-- [Expo on GitHub](https://github.com/expo/expo): View our open source platform and contribute.
-- [Discord community](https://chat.expo.dev): Chat with Expo users and ask questions.
+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/npmReadMe.md

@@ -1,30 +1,31 @@
 # Program Kit
 
-Program Kit is a production-ready cross-platform starter published from `app/`.
+Program Kit is a production-ready cross-platform starter published from repository root.
 It is built around React Native + Expo and is designed to be quickly tested, scaled,
 and deployed across popular platforms.
 
 ## What You Get
 
 - Expo + React Native app foundation
-- Telegram bot support (webhook + local bot scripts)
+- Telegram bot support (webhook + local bot scripts) with AI functionality
 - Telegram Mini App-ready client structure
-- Android and iOS workflow scripts
+- Android and iOS clients
 - Windows desktop packaging (`.exe`) with Electron Builder
 - CI-oriented release workflow and deployment helpers
+- OpenAI functionality and Swap.Coffee for blockchain data retrievement
 
 ## Install
 
 ### npmjs (public)
 
 ```bash
-npx @www.hyperlinks.space/program-kit ./my-new-program
+npx @www.hyperlinks.space/program-kit ./new-program
 ```
 
 ### GitHub Packages
 
 ```bash
-npx @hyperlinksspace/program-kit ./my-new-program
+npx @hyperlinksspace/program-kit ./new-program
 ```
 
 If you install from GitHub Packages, configure `.npmrc` with the `@hyperlinksspace`
@@ -33,12 +34,12 @@ registry and token.
 ## After Scaffold
 
 ```bash
-cd my-new-program
+cd new-program
 npm install
 npm run start
 ```
 
-Then open the project `README.md` for full setup details (env vars, bot setup, build
+Then open the project **`fullREADME.md`** for details (env vars, bot setup, build
 and release commands).
 
 ## Release Channels
@@ -50,4 +51,3 @@ and release commands).
 
 - Published directly from the `app/` folder.
 - Package tarball is filtered to include only required project files.
-- **`fullREADME.md`** in the package is the full in-repo developer guide (Expo setup, scripts, and the rest of the project readme).

package/package.json

@@ -40,7 +40,7 @@
     "url": "https://github.com/HyperlinksSpace/HyperlinksSpaceBot.git"
   },
   "main": "expo-router/entry",
-  "version": "1.2.3",
+  "version": "1.2.181818",
   "type": "module",
   "engines": {
     "node": ">=18 <=22"
@@ -200,7 +200,7 @@
     "@vercel/functions": "^3.4.3",
     "concurrently": "^9.1.0",
     "cross-env": "^7.0.3",
-    "dotenv": "^16.4.5",
+    "dotenv": "^16.6.1",
     "electron": "^41.0.4",
     "electron-builder": "^26.8.1",
     "electron-forge": "^5.2.4",

package/scripts/load-env.ts

@@ -4,14 +4,12 @@ import path from "path";
 /**
  * Unified env loader for local Node contexts.
  *
- * Loads .env and .env.local from repo root and app/.
+ * Loads .env and .env.local from repo root.
  * On Vercel, these files normally aren't present, so this is effectively a no-op.
  */
 export function loadEnv() {
   const cwd = process.cwd();
   dotenv.config({ path: path.join(cwd, ".env") });
-  dotenv.config({ path: path.join(cwd, "app", ".env") });
   dotenv.config({ path: path.join(cwd, ".env.local") });
-  dotenv.config({ path: path.join(cwd, "app", ".env.local") });
 }
 

package/scripts/test-api-base.ts

@@ -1,5 +1,5 @@
 /**
- * Quick check that app/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";

package/tsconfig.json

@@ -14,4 +14,4 @@
     ".expo/types/**/*.ts",
     "expo-env.d.ts"
   ]
-}
+}

package/windows/build.cjs

@@ -2115,7 +2115,7 @@ async function createWindow() {
 
   // NSIS close-app uses PRODUCT_NAME (package.json → build.productName). The window title must
   // match that string, not a URL — otherwise the installer cannot find/close the running app.
-  // Keep in sync with app/package.json "build.productName".
+  // Keep in sync with package.json "build.productName".
   const windowTitle = isDev ? "http://www.hyperlinks.space/" : brand.productDisplayName;
 
   const mainWindow = new BrowserWindow({

package/windows/cleanup-legacy-appdata-installs.ps1

@@ -1,7 +1,7 @@
 # Remove leftover per-user installs under %LOCALAPPDATA%\Programs\ and updater sidecars.
 # Older builds often installed to AppData while current NSIS uses perMachine -> Program Files.
 #
-# Usage (from app/):
+# Usage (from repo root):
 #   powershell -ExecutionPolicy Bypass -File .\windows\cleanup-legacy-appdata-installs.ps1          # list only
 #   powershell -ExecutionPolicy Bypass -File .\windows\cleanup-legacy-appdata-installs.ps1 -Force   # delete
 # If removal fails with "in use", close the app or run with -KillAppProcesses (stops exes under those folders).

package/windows/product-brand.cjs

@@ -1,6 +1,6 @@
 /**
  * Single source of truth for Windows/Electron product naming.
- * Display name and artifact slug come from app/package.json → build.productName.
+ * Display name and artifact slug come from package.json → build.productName.
  */
 const fs = require("fs");
 const path = require("path");