@www.hyperlinks.space/program-kit 81.81.81 → 123.123.123

package/ai/transmitter.ts

@@ -0,0 +1,367 @@
+import type { AiMode, AiRequestBase, AiResponseBase, ThreadContext } from "./openai.js";
+import { callOpenAiChat, callOpenAiChatStream } from "./openai.js";
+import {
+  getTokenBySymbol,
+  normalizeSymbol,
+  type TokenSearchResult,
+} from "../blockchain/coffee.js";
+import {
+  insertMessage,
+  getThreadHistory,
+  type Message,
+} from "../database/messages.js";
+
+export type AiRequest = AiRequestBase & {
+  mode?: AiMode;
+};
+
+export type AiResponse = AiResponseBase;
+
+const HISTORY_LIMIT = 50;
+
+function formatHistoryForInput(history: Message[]): string {
+  if (history.length === 0) return "";
+  const lines = history.map((m) => {
+    const role = m.role === "user" ? "user" : m.role === "assistant" ? "assistant" : "system";
+    const content = (m.content ?? "").trim();
+    return `${role}: ${content}`;
+  });
+  return "Previous conversation:\n" + lines.join("\n") + "\n\n";
+}
+
+/** Claim by insert; return skipped response if another instance won. */
+async function claimUserMessage(
+  thread: ThreadContext,
+  content: string,
+): Promise<AiResponse | null> {
+  const inserted = await insertMessage({
+    user_telegram: thread.user_telegram,
+    thread_id: thread.thread_id,
+    type: thread.type,
+    role: "user",
+    content,
+    telegram_update_id: thread.telegram_update_id ?? undefined,
+  });
+  if (inserted === null) {
+    return {
+      ok: false,
+      provider: "openai",
+      mode: "chat",
+      skipped: true,
+    };
+  }
+  return null;
+}
+
+async function persistAssistantMessage(
+  thread: ThreadContext,
+  content: string,
+): Promise<void> {
+  await insertMessage({
+    user_telegram: thread.user_telegram,
+    thread_id: thread.thread_id,
+    type: thread.type,
+    role: "assistant",
+    content,
+  });
+}
+
+function extractSymbolCandidate(input: string): string | null {
+  const raw = input.trim();
+  if (!raw) return null;
+
+  // Simple patterns like "USDT", "$USDT", "USDT on TON".
+  const parts = raw.split(/\s+/);
+  const first = parts[0]?.replace(/^\$/g, "") ?? "";
+  const normalized = normalizeSymbol(first);
+  return normalized || null;
+}
+
+function buildTokenFactsBlock(symbol: string, token: any): string {
+  const lines: string[] = [];
+
+  const sym = token?.symbol ?? symbol;
+  const name = token?.name ?? null;
+  const address = token?.id ?? token?.address ?? null;
+  const type = token?.type ?? "token";
+  const decimals = token?.decimals ?? token?.metadata?.decimals ?? null;
+  const verification =
+    token?.verification ?? token?.metadata?.verification ?? null;
+
+  const market = token?.market_stats ?? {};
+  const holders =
+    market?.holders_count ?? token?.holders ?? market?.holders ?? null;
+  const priceUsd = market?.price_usd ?? null;
+  const mcap = market?.mcap ?? market?.fdmc ?? null;
+  const volume24h = market?.volume_usd_24h ?? null;
+
+  lines.push(`Symbol: ${sym}`);
+  if (name) {
+    lines.push(`Name: ${name}`);
+  }
+  lines.push(`Type: ${type}`);
+  lines.push(`Blockchain: TON`);
+  if (address) {
+    lines.push(`Address: ${address}`);
+  }
+  if (decimals != null) {
+    lines.push(`Decimals: ${decimals}`);
+  }
+  if (verification) {
+    lines.push(`Verification: ${verification}`);
+  }
+  if (holders != null) {
+    lines.push(`Holders: ${holders}`);
+  }
+  if (priceUsd != null) {
+    lines.push(`Price (USD): ${priceUsd}`);
+  }
+  if (mcap != null) {
+    lines.push(`Market cap (USD): ${mcap}`);
+  }
+  if (volume24h != null) {
+    lines.push(`24h volume (USD): ${volume24h}`);
+  }
+
+  return lines.join("\n");
+}
+
+async function handleTokenInfo(
+  request: AiRequest,
+): Promise<AiResponse> {
+  const trimmed = request.input?.trim() ?? "";
+  const symbolCandidate = extractSymbolCandidate(trimmed);
+
+  if (!symbolCandidate) {
+    return {
+      ok: false,
+      provider: "openai",
+      mode: "token_info",
+      error: "Could not detect a token symbol. Try sending something like USDT.",
+    };
+  }
+
+  const tokenResult: TokenSearchResult = await getTokenBySymbol(
+    symbolCandidate,
+  );
+
+  if (!tokenResult.ok) {
+    return {
+      ok: false,
+      provider: "openai",
+      mode: "token_info",
+      error:
+        tokenResult.error === "not_found"
+          ? `Token ${symbolCandidate} was not found on TON.`
+          : "Token service is temporarily unavailable.",
+      meta: {
+        symbol: symbolCandidate,
+        reason: tokenResult.reason,
+        status_code: tokenResult.status_code,
+      },
+    };
+  }
+
+  const token = tokenResult.data;
+  const facts = buildTokenFactsBlock(symbolCandidate, token);
+
+  const promptParts = [
+    "You are a concise TON token analyst.",
+    "",
+    "Facts about the token:",
+    facts,
+    "",
+    "User question or context:",
+    trimmed,
+  ];
+
+  const composedInput = promptParts.join("\n");
+
+  const result = await callOpenAiChat("token_info", {
+    input: composedInput,
+    userId: request.userId,
+    context: {
+      ...request.context,
+      symbol: symbolCandidate,
+      token,
+      source: "swap.coffee",
+    },
+    instructions: request.instructions,
+  });
+
+  return {
+    ...result,
+    mode: "token_info",
+    meta: {
+      ...(result.meta ?? {}),
+      symbol: symbolCandidate,
+      token,
+    },
+  };
+}
+
+export async function transmit(request: AiRequest): Promise<AiResponse> {
+  const mode: AiMode = request.mode ?? "chat";
+  const thread = request.threadContext;
+
+  if (thread && !thread.skipClaim) {
+    const skipped = await claimUserMessage(thread, request.input);
+    if (skipped) return skipped;
+  }
+
+  if (mode === "token_info") {
+    const result = await handleTokenInfo(request);
+    if (result.ok && result.output_text && thread) {
+      await persistAssistantMessage(thread, result.output_text);
+    }
+    return result;
+  }
+
+  let input = request.input;
+  if (thread) {
+    const history = await getThreadHistory({
+      user_telegram: thread.user_telegram,
+      thread_id: thread.thread_id,
+      type: thread.type,
+      limit: HISTORY_LIMIT,
+    });
+    input = formatHistoryForInput(history) + "Current message:\nuser: " + request.input;
+  }
+
+  const result = await callOpenAiChat(mode, {
+    input,
+    userId: request.userId,
+    context: request.context,
+    instructions: request.instructions,
+  });
+
+  if (result.ok && result.output_text && thread) {
+    await persistAssistantMessage(thread, result.output_text);
+  }
+  return result;
+}
+
+/** Stream AI response; onDelta(accumulatedText) is called for each chunk. Only the final OpenAI call is streamed. */
+export async function transmitStream(
+  request: AiRequest,
+  onDelta: (text: string) => void | Promise<void>,
+  opts?: { isCancelled?: () => boolean; getAbortSignal?: () => Promise<boolean> },
+): Promise<AiResponse> {
+  const mode: AiMode = request.mode ?? "chat";
+  const thread = request.threadContext;
+
+  if (thread && !thread.skipClaim) {
+    const skipped = await claimUserMessage(thread, request.input);
+    if (skipped) return skipped;
+  }
+
+  if (mode === "token_info") {
+    const tokenResult = await (async () => {
+      const trimmed = request.input?.trim() ?? "";
+      const symbolCandidate = extractSymbolCandidate(trimmed);
+      if (!symbolCandidate) {
+        return null;
+      }
+      return getTokenBySymbol(symbolCandidate);
+    })();
+
+    if (!tokenResult) {
+      return {
+        ok: false,
+        provider: "openai",
+        mode: "token_info",
+        error: "Could not detect a token symbol. Try sending something like USDT.",
+      };
+    }
+    if (!tokenResult.ok) {
+      const symbolCandidate = extractSymbolCandidate(request.input?.trim() ?? "");
+      return {
+        ok: false,
+        provider: "openai",
+        mode: "token_info",
+        error:
+          tokenResult.error === "not_found"
+            ? `Token ${symbolCandidate ?? ""} was not found on TON.`
+            : "Token service is temporarily unavailable.",
+        meta: {
+          symbol: tokenResult.symbol,
+          reason: tokenResult.reason,
+          status_code: tokenResult.status_code,
+        },
+      };
+    }
+
+    const token = tokenResult.data;
+    const symbolCandidate = extractSymbolCandidate(request.input?.trim() ?? "")!;
+    const facts = buildTokenFactsBlock(symbolCandidate, token);
+    const trimmed = request.input?.trim() ?? "";
+    const promptParts = [
+      "You are a concise TON token analyst.",
+      "",
+      "Facts about the token:",
+      facts,
+      "",
+      "User question or context:",
+      trimmed,
+    ];
+    const composedInput = promptParts.join("\n");
+
+    const result = await callOpenAiChatStream(
+      "token_info",
+      {
+        input: composedInput,
+        userId: request.userId,
+        context: {
+          ...request.context,
+          symbol: symbolCandidate,
+          token,
+          source: "swap.coffee",
+        },
+        instructions: request.instructions,
+      },
+      onDelta,
+      opts,
+    );
+
+    if (result.ok && result.output_text && thread) {
+      await persistAssistantMessage(thread, result.output_text);
+    }
+    return {
+      ...result,
+      mode: "token_info",
+      meta: {
+        ...(result.meta ?? {}),
+        symbol: symbolCandidate,
+        token,
+      },
+    };
+  }
+
+  let input = request.input;
+  if (thread) {
+    const history = await getThreadHistory({
+      user_telegram: thread.user_telegram,
+      thread_id: thread.thread_id,
+      type: thread.type,
+      limit: HISTORY_LIMIT,
+    });
+    input = formatHistoryForInput(history) + "Current message:\nuser: " + request.input;
+  }
+
+  const result = await callOpenAiChatStream(
+    mode,
+    {
+      input,
+      userId: request.userId,
+      context: request.context,
+      instructions: request.instructions,
+    },
+    onDelta,
+    opts,
+  );
+
+  if (result.ok && result.output_text && thread) {
+    await persistAssistantMessage(thread, result.output_text);
+  }
+  return result;
+}

package/backlogs/medium_term_backlog.md

@@ -0,0 +1,26 @@
+header indent bag in fullsize<br>
+rotation on swap page<br>
+edit interval healthcheck<br>
+Ticker link<br>
+Scrolling in AI widget fix<br>
+Finish bot parts isolation<br>
+ld timeout<br>
+AI bd<br>
+Hovers<br>
+Languages<br>
+Favicon change<br>
+Wallet creation and nickname generation<br>
+Jetton lockup<br>
+Theme in Chrome<br>
+Bd<br>
+Wallet creation<br>
+Apps design<br>
+Plan users bd for search<br>
+Brand book<br>
+Fix<br>
+Starting Rewards<br>
+Feed items types<br>
+PAY BY QR<br>
+swap long rate state<br>
+swaps<br>
+tokns<br>

package/backlogs/short_term_backlog.md

@@ -0,0 +1,42 @@
+Polyfils refactoring<br>
+Wallet: Telegram, Connected, Unhosted<br>
+Username loaded without intermediate state<br>
+Bottom bar refactor<br>
+AI options page<br>
+Bottom bar icon review<br>
+AI chat page<br>
+Bring repository root app to demo design state<br>
+GitHub and GitLab bidirectional mirroring<br>
+readme.md<br>
+Windows setup refactor<br>
+https://azure.microsoft.com/en-us/products/artifact-signing<br>
+README.md: Project news, discussions, where to learn for contributions<br>
+
+Issues:<br>
+Several chats async streaming<br>
+
+Pull requests:<br>
+AI responce checkup in bot (message interruption on new prompt)<br>
+Typing in the middle of the text on large inputting<br>
+
+To think about:<br>
+Branding and naming
+Place of the install update dialog in the UI<br>
+Updater: fasten instant reload<br>
+Custom installer design<br>
+Fluent installer progress bar<br>
+Optional cleanup of legacy Forge v5 deps<br>
+Workflows dry mode (build check without releasing)<br>
+Move Telegram folder contents to API<br>
+https://www.npmjs.com/package/electron-log<br>
+PGP release signing<br>
+File's formats and folders structure<br>
+Selection and pointing text detalization<br>
+    on word tapping places at the end of the word<br>
+    zoom-in cursor placing on long tap<br>
+Instructions.ts in AI<br>
+
+Abandoned:<br>
+Placeholder refactor<br>
+Logo bar visibility<br>
+Overlay on screen expansion from mobile<br>

package/eslint.config.cjs

@@ -0,0 +1,10 @@
+// https://docs.expo.dev/guides/using-eslint/
+const { defineConfig } = require('eslint/config');
+const expoConfig = require('eslint-config-expo/flat');
+
+module.exports = defineConfig([
+  expoConfig,
+  {
+    ignores: ['dist/*'],
+  },
+]);

package/fullREADME.md

@@ -24,7 +24,8 @@ All core materials are available publicly for сгккуте hyperlinks.space te
 - [`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.
+- [`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).
@@ -71,14 +72,6 @@ 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
-
-- 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
 
 `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.
@@ -131,53 +124,18 @@ Isolated/local run options:
 - 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`](./.github/workflows/electron-exe-release.yml) and [`Electron Forge EXE Release`](./.github/workflows/electron-forge-exe-release.yml) - manual Windows release pipelines.
-- [`EXPO Publish`](./.github/workflows/expo-publish.yml) - manual OTA publish with EAS CLI.
+- [`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.
 
-## 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
-
-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.
-
-### Deploy web build to Vercel
+## Deploy to Vercel
 
 From the repository root, deploy the static web build to Vercel production:
 
@@ -209,6 +167,72 @@ 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.
 
+## 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.
@@ -219,6 +243,8 @@ npx @www.hyperlinks.space/program-kit ./new-program
 
 Link to the package: https://www.npmjs.com/package/@www.hyperlinks.space/program-kit
 
-## Where to discuss the project?
+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/npmReadMe.md

@@ -33,12 +33,17 @@ registry and token.
 
 ## After Scaffold
 
+Copy `npmrc.example` to `.npmrc` so installs match this repo (`legacy-peer-deps`; npm does not ship a real `.npmrc` in the tarball for security):
+
 ```bash
 cd new-program
+cp npmrc.example .npmrc
 npm install
 npm run start
 ```
 
+If you prefer not to use a `.npmrc`, you can run **`npm install --legacy-peer-deps`** instead of the copy step.
+
 Then open the project **`fullREADME.md`** for details (env vars, bot setup, build
 and release commands).
 
@@ -49,5 +54,15 @@ and release commands).
 
 ## Notes
 
-- Published directly from the `app/` folder.
-- Package tarball is filtered to include only required project files.
+- Published from the repository root; the pack includes everything except patterns in [`.npmignore`](./.npmignore) (no `files` whitelist in `package.json`).
+- `.npmrc` cannot be published on npm; `npmrc.example` is included so you can copy it locally.
+
+## Matching local development
+
+Use the same setup you would after cloning this repo:
+
+1. **Node** — Prefer the version in [`.nvmrc`](./.nvmrc) (aligned with [`package.json`](./package.json) `engines`).
+2. **npm install** — Copy [`npmrc.example`](./npmrc.example) to `.npmrc`, then run `npm install` (same `legacy-peer-deps` behavior as a local checkout with a root `.npmrc`).
+3. **Env** — Copy [`.env.example`](./.env.example) to `.env` and fill variables (details in **`fullREADME.md`** after the CI readme swap, or in the main repo README).
+
+The tarball does not ship `package-lock.json` (by [`.npmignore`](./.npmignore)); the first install generates a lockfile for your machine, like cloning without a committed lock.

package/npmrc.example

@@ -0,0 +1 @@
+legacy-peer-deps=true