meta-sovereign 0.0.0-stage → 0.49.2

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.hi.md

@@ -0,0 +1,171 @@
+# meta-sovereign (languages: [en](README.md) • [zh](README.zh.md) • hi • [ru](README.ru.md))
+
+`meta-sovereign` एक व्यक्तिगत **meta profile sovereign** सिस्टम है: ऐसा unified inbox, CRM और automation platform जिसका स्वामित्व सचमुच उपयोगकर्ता के पास रहता है। यह local-first और privacy-respecting है, और VK, Telegram, X, WhatsApp, Facebook, LinkedIn, career.habr.com, hh.ru, superjob.ru तथा email providers से contacts, chats, email और patterns को एक जगह लाता है।
+
+## अभी चलाकर देखें (install नहीं)
+
+किसी भी आधुनिक browser में <https://link-foundation.github.io/meta-sovereign/> खोलें। Web app तुरंत boot होता है, पूरी तरह browser में चलता है, और default रूप से local storage में लिखता है। जब तक आप server नहीं जोड़ते, आपका data device से बाहर नहीं जाता।
+
+> अगर link अभी live नहीं है, तो GitHub Pages workflow (`.github/workflows/pages.yml`) अगली `main` push पर इसे publish करेगा।
+
+Server के बिना hosted app **browser-only mode** में चलता है: contacts, patterns और broadcasts browser store से काम करते हैं, जबकि imports, automations, sync, CV sync और greetings local server का इंतज़ार करते हैं। एक notice server start करने का command और **Check again** button दिखाता है।
+
+## Desktop app
+
+अपने system का installer <https://link-foundation.github.io/meta-sovereign/download/> से या [GitHub releases](https://github.com/link-foundation/meta-sovereign/releases) से download करें: Linux (AppImage, deb, tar.gz), macOS (dmg, zip) और Windows (installer, portable), हर एक x64 और arm64 के लिए। Desktop app में server bundled है, इसलिए खुद server start किए बिना हर feature काम करता है। Unsigned builds की पहली launch, checksums और updates [`docs/USER-GUIDE.hi.md` §4](docs/USER-GUIDE.hi.md#4-desktop-या-mobile-app-install-करें) में हैं।
+
+## local server चलाएँ (sync के लिए recommended)
+
+Devices के बीच sync, encrypted backups और पूरा feature set इस्तेमाल करने के लिए SPA के पास local server start करें। दो backend उपलब्ध हैं; दोनों समान wire protocol लागू करते हैं (देखें [`docs/SERVER-PARITY.hi.md`](docs/SERVER-PARITY.hi.md))।
+
+### Rust server — single binary, runtime नहीं, पर सीमित
+
+```bash
+git clone https://github.com/link-foundation/meta-sovereign
+cd meta-sovereign
+cargo run --manifest-path rust/Cargo.toml -p meta-sovereign-server -- serve
+```
+
+> **Rust server की सीमाएँ।** यह links को **सिर्फ़ memory में** रखता है: disk पर कुछ नहीं लिखा जाता, इसलिए server बंद होते ही सारा data चला जाता है। इसमें **कोई source adapters नहीं हैं**: Telegram, VK, GitHub, Upwork आदि से live fetch नहीं, outbound HTTP/TLS client नहीं (email सिर्फ़ archives ingest करता है), और automations, CV sync, browser auto-import, backups तथा `/api/export-encrypted` नहीं हैं। असली इस्तेमाल के लिए JS server या desktop app चुनें। Route-by-route सूची [`docs/SERVER-PARITY.hi.md`](docs/SERVER-PARITY.hi.md) में है।
+
+### JavaScript server — पूरा feature set (Node/Bun/Deno), source से
+
+Package अभी **npm पर publish नहीं है** (registry 404 देती है), इसलिए `npx -y meta-sovereign serve` आज काम नहीं करता। Server को source checkout से चलाएँ (Node.js और npm चाहिए):
+
+```bash
+git clone https://github.com/link-foundation/meta-sovereign
+cd meta-sovereign
+npm install
+node js/bin/meta-sovereign.js serve
+```
+
+Package npm पर publish होने के बाद `npx -y meta-sovereign serve` (या `npm install -g meta-sovereign && meta-sovereign serve`) काम करेगा। तब तक toolchain के बिना server चलाने का तरीका desktop app (ऊपर) है।
+
+दोनों backend default रूप से <http://127.0.0.1:8787> पर listen करते हैं। JS server hosted app के origin (`https://link-foundation.github.io`) को CORS headers के साथ जवाब देता है; दूसरे origins `meta-sovereign serve --allow-origin=<origins>` या `MS_ALLOW_ORIGINS` से allow करें। Safari `https` pages को `http://127.0.0.1` तक नहीं पहुँचने देता, लेकिन `https://127.0.0.1` तक पहुँचने देता है; server अब उसी port पर HTTPS का भी जवाब देता है और इसके लिए localhost का अपना certificate बनाता है। एक बार `node js/bin/meta-sovereign.js trust` चलाएँ (macOS login keychain में जोड़ता है; दूसरे systems पर certificate का path print होता है) या Safari में `https://127.0.0.1:8787/trust` खोलें और prompts follow करें — उसके बाद hosted app Safari में सीधे server से connect हो जाता है। Trust से पहले notice server का नाम दिखाता है, उसकी copy (<http://127.0.0.1:8787>) और **सर्वर पर भरोसा करें** (<https://127.0.0.1:8787/trust>) का link देता है। `--tls=false` / `MS_TLS=off` HTTPS बंद करता है; server की अपनी copy fallback रहती है। Hosted SPA `discoverServer()` से local server खोजता है (saved override → `127.0.0.1` ports)। अगर browser auto-connect नहीं करता, app में **Settings → Server** खोलें और binary द्वारा print किया गया URL paste करें।
+
+Default UI hosted app है: `serve` उसका पता छापता है, <https://link-foundation.github.io/meta-sovereign/>, और app हमारे port 8787 पर server को खुद ढूँढ लेता है (वह 8788, 7001, 7002 और 3000 भी देखता है; किसी दूसरे port पर `serve` बताता है कि उसे **Settings → Server** में set करें), इसलिए server को web site host नहीं करनी पड़ती। <http://127.0.0.1:8787> पर उसकी अपनी copy Safari और बिना internet काम के लिए fallback रहती है; `serve --local-ui=false` (या `MS_LOCAL_UI=off`) उसे बंद करता है, और तब `/` hosted app खोलता है। `--ui-url=<url>` (या `MS_UI_URL`) कोई दूसरी hosted copy बताता है, जैसे किसी fork का Pages, और उसके origin को अनुमति देता है।
+
+## SPA को server से जोड़ें
+
+SPA server को इस क्रम में चुनता है ([`js/src/web/discover.js`](js/src/web/discover.js)):
+
+1. **Same origin** — जब SPA सीधे JS या Rust server से serve हो।
+2. **Saved override** — `localStorage.metaServer`, जिसे app का **Settings → Server** prompt set करता है।
+3. **Runtime shell candidates** — Electron और Capacitor embedded server URL inject करते हैं।
+4. **`127.0.0.1` ports** — default local-server port automatic probe होता है।
+5. **Caller-supplied LAN candidates** — programmatically pass किए गए URLs।
+
+यदि कोई server जवाब नहीं देता, SPA **offline mode** में रहता है: writes local browser store में जाती हैं ([`createBrowserStore`](js/src/storage/browser-store.js): IndexedDB → localStorage → memory) और अगली बार server मिलने पर [`OfflineClient`](js/src/web/client.js) उन्हें replay करता है।
+
+पूरी user flow guide — बिना install, Rust server, JS server, desktop/mobile app, encrypted export और troubleshooting — [`docs/USER-GUIDE.hi.md`](docs/USER-GUIDE.hi.md) में है।
+
+## यह क्या करता है
+
+- **Unified inbox**: VK, Telegram, X, WhatsApp, Facebook, LinkedIn, career.habr.com, hh.ru, superjob.ru और email।
+- **CV synchronisation**: LinkedIn, hh.ru, Habr Career, Naukri, VietnamWorks, TopCV और SuperJob — हर profile को अपने ही browser से पढ़ें, field दर field अंतर देखें और तय किए गए values वापस लिखें ([`docs/CV-SYNC.hi.md`](docs/CV-SYNC.hi.md))।
+- **Greetings**: VK, Telegram, WhatsApp, Messenger, X और email पर "hi" या greeting sticker से बातचीत शुरू करें, जैसे [konard/vk-bot](https://github.com/konard/vk-bot) करता है — UI में stickers चुनें, देखें किसे क्या जाएगा, और messages के बीच pause के साथ भेजें ([`docs/GREETINGS.hi.md`](docs/GREETINGS.hi.md))।
+- **Personal CRM**: contacts, communities, group memberships, intersections और mass-personal outreach।
+- **Personal memory**: conversations से structured `question → answer` facts।
+- **Conversation automation platform**: pattern editors, reply-variation editors और n8n-style dialog graphs।
+- **Portable data store**: binary [Doublets](https://github.com/linksplatform/doublets-rs) + text [Links Notation](https://github.com/link-foundation/links-notation), automated backups और `.lino` import/export।
+- **Local-first runtime**: user-owned devices के बीच WebRTC sync और optional self-hosted personal cloud।
+- **Two stacks**: JS + Rust/WebAssembly default stack और pure Rust server/microservice variant; on-disk format साझा है।
+
+पूर्ण requirement → status mapping [`docs/REQUIREMENTS.hi.md`](docs/REQUIREMENTS.hi.md) में है; per-issue case studies [`docs/case-studies/`](docs/case-studies/) में हैं।
+
+Telegram क्लाइंट की हर सुविधा — समर्थित, आंशिक, रोकी हुई या असमर्थित, और API या वेब ऐप से पहुँच — [`docs/FEATURES.hi.md`](docs/FEATURES.hi.md) में दर्ज है।
+
+## स्थिति
+
+issue #1 का prototype implement हो चुका है और PR #2 में track है:
+
+- **Data layer (R-A\*)**: `DualStore` Doublets binary और Links Notation text को lock-step में रखता है; AES-256-GCM backups और `secret:*` link encryption (केवल `MS_SECRET_PASSPHRASE` सेट होने पर; बाक़ी store encrypted नहीं) उपलब्ध हैं।
+- **Service connectors (R-E\*)**: VK, Telegram, X, WhatsApp, Facebook, LinkedIn, career.habr.com, hh.ru, superjob.ru और email के archive parsers तथा live connectors।
+- **Pattern matching और automation (R-C\*)**: `inferRegex`, `simplifyRegex`, `compilePeg`, fuzzy reply variation extraction और `createGraph` / `runGraph`।
+- **CRM (R-D\*)**: contact aggregation, audience DSL, mass-personal outreach, profile और resume sync envelopes।
+- **CV synchronisation (R-V\*)**: सात job platforms के declarative browser plans, cross-platform diff, चुनिंदा writes और हर run के लिए HTML/screenshot artifacts वाली redacted telemetry stream।
+- **Distribution (R-F\*)**: NPM library, CLI, local server, Electron shell, Capacitor mobile shell और Docker web + WebRTC microservices।
+- **Stacks (R-G\*)**: JS server + React SPA + Rust/WASM heavy workloads, साथ में pure Rust server।
+- **Hardening (R-K\*)**: soft delete by default, AES-256-GCM master-key vault, multiple unlock methods और encrypted export।
+- **Browser publishing (R-L\*)**: GitHub Pages CI workflow, public SPA URL और user-first README/user guide।
+
+## Repository structure
+
+`meta-sovereign` multi-language repository है:
+
+- **JavaScript** `js/` में रहता है: `js/src/`, `js/tests/`, `js/scripts/`, `js/bin/`, `js/electron/`, `js/examples/`, `js/experiments/`।
+- **Rust** `rust/` में रहता है: workspace manifest, lockfile और crates।
+- **Native shells**: `js/electron/`, `mobile/`, `capacitor.config.json`, `docker/`।
+- **Operations**: `.github/workflows/`, `.changeset/`, `docs/`।
+
+```
+.
+├── .changeset/           # Changeset configuration
+├── .github/workflows/    # GitHub Actions CI/CD
+├── docker/               # Web + WebRTC Dockerfiles
+├── docs/                 # Requirements, user guide, server parity, case studies
+├── js/                   # JavaScript tree
+├── mobile/               # Capacitor mobile shell
+├── rust/                 # Rust workspace
+└── package.json          # Node.js package manifest
+```
+
+---
+
+## Developer reference
+
+यह भाग contributors के लिए है।
+
+### Quick start
+
+```bash
+bun install
+bun test
+npm test
+deno test --allow-read --allow-write --allow-env --allow-net --allow-sys js/tests
+
+RUN_BROWSER_E2E=1 npm run test:e2e:browser
+cargo test --manifest-path rust/Cargo.toml --workspace
+npm run build:web
+npm run build:pages
+bun run lint
+bun run format:check
+```
+
+### CI/CD और quality gates
+
+Pipeline fast checks, slow matrix tests, API docs build, broken-link checks और automated release चलाता है। हर job में explicit `timeout-minutes` है, और individual tests में `node --test --test-timeout=30000` / `bun test --timeout 30000` guard है।
+
+हर PR को ये checks पास करने चाहिए:
+
+- ESLint और Prettier;
+- `jscpd` duplication check;
+- secrets scan;
+- file line limits;
+- Node, Bun, Deno × Ubuntu, macOS, Windows test matrix;
+- docs बदलने पर documentation validation।
+
+विस्तार के लिए [`docs/BEST-PRACTICES.hi.md`](docs/BEST-PRACTICES.hi.md) देखें।
+
+### Scripts reference
+
+| Script                 | Description                       |
+| ---------------------- | --------------------------------- |
+| `bun test`             | Bun से tests चलाएँ                |
+| `bun run lint`         | ESLint से code जाँचें             |
+| `bun run lint:fix`     | lint issues auto-fix करें         |
+| `bun run format`       | Prettier से formatting करें       |
+| `bun run format:check` | formatting check करें             |
+| `bun run check`        | lint + format + duplication चलाएँ |
+| `bun run changeset`    | नया changeset बनाएँ               |
+| `bun run build:web`    | production SPA bundle बनाएँ       |
+| `bun run build:pages`  | `dist/pages/` artifact बनाएँ      |
+| `bun run build:mobile` | Capacitor mobile bundle बनाएँ     |
+
+### Contributing
+
+विस्तृत guidelines [`docs/CONTRIBUTING.hi.md`](docs/CONTRIBUTING.hi.md) में हैं। सामान्य flow: fork करें, branch बनाएँ, बदलाव करें, changeset बनाएँ, commit करें, push करें और Pull Request खोलें।
+
+## License
+
+[Unlicense](LICENSE) - public domain.

package/README.md

@@ -1,3 +1,361 @@
-# Temporary Holding Version
+# meta-sovereign (languages: en • [zh](README.zh.md) • [hi](README.hi.md) • [ru](README.ru.md))
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A personal **meta profile sovereign** system — a unified inbox + CRM + automation platform that the user actually owns. Local-first, privacy-respecting, with all your contacts, chats, email, and patterns from VK, Telegram, X, WhatsApp, Facebook, LinkedIn, career.habr.com, hh.ru, superjob.ru, email, GitHub, Upwork, and PeoplePerHour providers.
+
+## Try it now (no install)
+
+Open <https://link-foundation.github.io/meta-sovereign/> in any modern browser. The web app boots immediately, runs entirely in your browser, and writes to local storage by default — nothing leaves your device until you point it at a server.
+
+> If the link is not yet live, the GitHub Pages workflow (`.github/workflows/pages.yml`) publishes it on the next push to `main`.
+
+Without a server the hosted app runs in **browser-only mode**: contacts, patterns and broadcasts work from the browser store, while imports, automations, sync, CV sync and greetings wait for a local server. A notice shows the command to start one and a **Check again** button.
+
+## Desktop app
+
+Download the installer for your system from <https://link-foundation.github.io/meta-sovereign/download/>, or from [GitHub releases](https://github.com/link-foundation/meta-sovereign/releases): Linux (AppImage, deb, tar.gz), macOS (dmg, zip) and Windows (installer, portable), each for x64 and arm64. The desktop app bundles the server, so every feature works without starting one yourself. First-launch steps for unsigned builds, checksums and update notes are in [`docs/USER-GUIDE.md` §4](docs/USER-GUIDE.md#4-install-the-desktop-or-mobile-app).
+
+## Run a local server (recommended for sync)
+
+To sync between devices, keep encrypted backups, and unlock the full feature set, start a local server next to the SPA. Two backends are available; both implement the same wire protocol (see [`docs/SERVER-PARITY.md`](docs/SERVER-PARITY.md)).
+
+### Rust server — single binary, no runtime, but limited
+
+```bash
+git clone https://github.com/link-foundation/meta-sovereign
+cd meta-sovereign
+cargo run --manifest-path rust/Cargo.toml -p meta-sovereign-server -- serve
+```
+
+> **Rust server limits.** It keeps links **in memory only**: nothing is written to disk, so everything is gone when the server stops. It has **no source adapters**: no live fetches from Telegram, VK, GitHub, Upwork or similar, no outbound HTTP or TLS client (email only ingests archives), and no automations, CV sync, browser auto-import, backups or `/api/export-encrypted`. Pick the JS server or the desktop app for real use. The route-by-route list is in [`docs/SERVER-PARITY.md`](docs/SERVER-PARITY.md).
+
+### JavaScript server — full feature set (Node/Bun/Deno), from source
+
+The package is **not published on npm yet** (the registry answers 404), so `npx -y meta-sovereign serve` does not work today. Run the server from a source checkout (needs Node.js and npm):
+
+```bash
+git clone https://github.com/link-foundation/meta-sovereign
+cd meta-sovereign
+npm install
+node js/bin/meta-sovereign.js serve
+```
+
+Once the package is published to npm, `npx -y meta-sovereign serve` (or `npm install -g meta-sovereign && meta-sovereign serve`) will work. Until then, the desktop app (above) is the way to run the server without a toolchain.
+
+Either backend listens on <http://127.0.0.1:8787> by default. The JS server answers the hosted app's origin (`https://link-foundation.github.io`) with CORS headers; allow other origins with `meta-sovereign serve --allow-origin=<origins>` or `MS_ALLOW_ORIGINS`. Safari does not let `https` pages reach `http://127.0.0.1`, but it allows `https://127.0.0.1`; the server also answers HTTPS on the same port with its own certificate for localhost — run `node js/bin/meta-sovereign.js trust` once (macOS adds it to the login keychain; other systems print the certificate path), or open `https://127.0.0.1:8787/trust` in Safari and follow the prompts, and the hosted app connects directly. Before trusting, the notice names the server, links its own copy (<http://127.0.0.1:8787>) and a **Trust the server** link (<https://127.0.0.1:8787/trust>). `--tls=false` / `MS_TLS=off` turns HTTPS off; the server's own copy remains the fallback. The hosted SPA discovers the local server automatically through `discoverServer()` (saved override → `127.0.0.1` ports). If your browser does not auto-connect, open the in-app **Settings → Server** prompt and paste the URL the binary printed.
+
+The hosted app is the default UI: `serve` prints its address, <https://link-foundation.github.io/meta-sovereign/>, and the app finds the server on our port 8787 by itself (it also looks at 8788, 7001, 7002 and 3000; on another port `serve` says to set it in **Settings → Server**), so the server does not have to host a web site. Its own copy at <http://127.0.0.1:8787> stays as a fallback for Safari and for working offline; `serve --local-ui=false` (or `MS_LOCAL_UI=off`) turns it off, and `/` then opens the hosted app. `--ui-url=<url>` (or `MS_UI_URL`) names another hosted copy, such as a fork's Pages, and allows its origin.
+
+## Connect the SPA to your server
+
+The SPA picks a server in this order ([`js/src/web/discover.js`](js/src/web/discover.js)):
+
+1. **Same origin** — when you serve the SPA from the JS or Rust server directly.
+2. **Saved override** — `localStorage.metaServer`. Set via the in-app **Settings → Server** prompt.
+3. **Runtime shell candidates** — Electron and Capacitor inject the embedded server URL.
+4. **`127.0.0.1` ports** — the default local-server port is probed automatically.
+5. **Caller-supplied LAN candidates** — passed programmatically.
+
+If nothing answers, the SPA falls back to **offline mode**: writes go to the local browser store ([`createBrowserStore`](js/src/storage/browser-store.js): IndexedDB → localStorage → in-memory) and replay automatically through [`OfflineClient`](js/src/web/client.js) the next time a server appears.
+
+The full user-facing flow — install nothing, install Rust server, install JS server, install desktop / mobile app, encrypted export, troubleshooting — is in [`docs/USER-GUIDE.md`](docs/USER-GUIDE.md).
+
+## What it does
+
+- **Unified inbox** spanning VK, Telegram, X, WhatsApp, Facebook, LinkedIn, career.habr.com, hh.ru, superjob.ru, email, GitHub, Upwork, and PeoplePerHour.
+- **CV synchronisation** across LinkedIn, hh.ru, Habr Career, Naukri, VietnamWorks, TopCV and SuperJob: read every profile through your own browser, see the differences field by field, and push the agreed values back ([`docs/CV-SYNC.md`](docs/CV-SYNC.md)).
+- **Greetings**: open dialogs on VK, Telegram, WhatsApp, Messenger, X and email with a "hi" or a greeting sticker, the way [konard/vk-bot](https://github.com/konard/vk-bot) does — pick stickers in the UI, preview who gets what, send with a pause between messages ([`docs/GREETINGS.md`](docs/GREETINGS.md)).
+- **Chat** with the connected Telegram account that behaves like Telegram's own apps: each message sent once, delivery ticks, live updates and catch-up after a gap, read marking, cloud drafts, retries that survive a reload. How the open-source Telegram, Signal and Element clients do it, pinned to the commits we read, is in [`docs/CHAT-REFERENCES.md`](docs/CHAT-REFERENCES.md).
+- **Personal CRM**: contacts, communities, group memberships, intersections, mass-personal outreach.
+- **Personal memory**: structured `question → answer` facts captured automatically from conversations.
+- **Conversation automation platform**: pattern editors, reply-variation editors, n8n-style dialog graphs.
+- **Portable data store**: dual binary ([Doublets](https://github.com/linksplatform/doublets-rs)) + text ([Links Notation](https://github.com/link-foundation/links-notation)) representation, automated backups, `.lino` import/export.
+- **Local-first runtime**: WebRTC sync between user-owned devices, optional self-hosted personal cloud.
+- **Two stacks**: JS + Rust/WebAssembly (default) and pure Rust (server/microservice variant). The on-disk format is shared.
+
+The full requirement → status mapping lives in [`docs/REQUIREMENTS.md`](docs/REQUIREMENTS.md); the per-issue case studies live in [`docs/case-studies/`](docs/case-studies/).
+
+Every Telegram client feature, with what is supported, partial, parked or not supported, and whether it is reachable by API or web app, is tracked in [`docs/FEATURES.md`](docs/FEATURES.md).
+
+## Status
+
+The prototype targeted by issue #1 is implemented and tracked in PR #2:
+
+- **Data layer (R-A\*)**: `DualStore` keeps Doublets binary + Links Notation text in lock-step, with AES-256-GCM encrypted backups (`createBackupScheduler`) and `secret:*` link encryption (only when `MS_SECRET_PASSPHRASE` is set; the rest of the store is not encrypted).
+- **Service connectors (R-E\*)**: archive parser + live API connector for VK, Telegram, X, WhatsApp, Facebook, LinkedIn, career.habr.com, hh.ru, superjob.ru, email, GitHub, Upwork, and PeoplePerHour.
+- **Pattern matching and automation (R-C\*)**: `inferRegex` / `simplifyRegex` / `compilePeg`, fuzzy reply-variation extraction, and an n8n-style automation graph (`createGraph` + `runGraph`).
+- **CRM (R-D\*)**: contact aggregation, audience DSL, mass-personal outreach, profile and resume sync envelopes.
+- **CV synchronisation (R-V\*)**: declarative browser plans for seven job platforms, cross-platform diff, selective writes, and a redacted telemetry stream with HTML/screenshot artifacts for every run.
+- **Distribution (R-F\*)**: NPM library, CLI (`js/bin/meta-sovereign.js`), local server (`meta-sovereign serve`), Electron shell, Capacitor mobile shell, Docker microservices for web + WebRTC.
+- **Stacks (R-G\*)**: default JS server + React SPA + Rust/WASM heavy workloads; alternative pure-Rust server (`meta-sovereign-rs serve`).
+- **Hardening (R-K\*)**: soft-delete by default, AES-256-GCM master-key vault with multi-method unlock, encrypted export.
+- **Browser publishing (R-L\*)**: GitHub Pages CI workflow, SPA on a public URL, user-first README and user guide.
+
+## Repository structure
+
+`meta-sovereign` is multi-language. Each language tree mirrors the corresponding [link-foundation AI-driven-development pipeline template](https://github.com/link-foundation):
+
+- **JavaScript** lives under `js/`: `js/src/`, `js/tests/`, `js/scripts/`, `js/bin/`, `js/electron/`, `js/examples/`, and `js/experiments/`.
+- **Rust** lives under `rust/`: `rust/Cargo.toml`, `rust/Cargo.lock`, and the `rust/crates/` workspace (`meta-sovereign-server`, `meta-sovereign-core`, `meta-sovereign-wasm`).
+- **Native shells**: `js/electron/` (desktop), `mobile/` + `capacitor.config.json` (iOS/Android), `docker/` (web + WebRTC microservices).
+- **Operations**: `.github/workflows/` (CI/CD), `.changeset/` (release management), `docs/` (this guide and case studies).
+
+```
+.
+├── .changeset/           # Changeset configuration
+├── .github/workflows/    # GitHub Actions CI/CD (release.yml, links.yml, pages.yml)
+├── .husky/               # Git hooks (pre-commit)
+├── docker/               # Web + WebRTC microservice Dockerfiles
+├── docs/                 # REQUIREMENTS, USER-GUIDE, SERVER-PARITY, case studies
+├── js/                   # JavaScript tree (src, tests, scripts, bin, electron)
+├── mobile/               # Capacitor mobile shell
+├── rust/                 # Rust workspace manifest, lockfile, and crates
+├── bunfig.toml           # Bun configuration
+├── capacitor.config.json # Capacitor mobile config
+├── deno.json             # Deno configuration
+└── package.json          # Node.js package manifest
+```
+
+---
+
+## Developer reference
+
+Everything below is for contributors. End-users do not need to read it.
+
+### Inherited features (CI/CD baseline)
+
+- **Multi-runtime support**: Works with Bun, Node.js, and Deno.
+- **Universal testing**: Uses [test-anywhere](https://github.com/link-foundation/test-anywhere) for cross-runtime tests.
+- **Automated releases**: Changesets-based versioning with GitHub Actions.
+- **Code quality**: ESLint + Prettier with pre-commit hooks via Husky.
+- **Package manager agnostic**: Works with bun, npm, yarn, pnpm, and deno.
+- **Broken link checks**: Automated link validation with [lychee](https://github.com/lycheeverse/lychee-action) and Web Archive fallback suggestions.
+- **GitHub Pages publishing**: `pages.yml` deploys the SPA on every push to `main` (this PR).
+
+### Quick Start
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Or with other runtimes:
+npm test
+deno test --allow-read --allow-write --allow-env --allow-net --allow-sys js/tests
+
+# Run the real-browser e2e (opt-in; needs Playwright + Chromium)
+RUN_BROWSER_E2E=1 npm run test:e2e:browser
+
+# Run the Rust workspace tests
+cargo test --manifest-path rust/Cargo.toml --workspace
+
+# Build the SPA bundle
+npm run build:web
+
+# Build the GitHub Pages artifact (writes dist/pages/)
+npm run build:pages
+
+# Lint code
+bun run lint
+
+# Format code
+bun run format
+
+# Check all (lint + format + file size)
+bun run check
+```
+
+### Design Choices
+
+#### Multi-Runtime Support
+
+This template is designed to work seamlessly with all major JavaScript runtimes:
+
+- **Bun**: Primary runtime with highest performance, uses native test support (`bun test`)
+- **Node.js**: Alternative runtime, uses built-in test runner (`node --test`)
+- **Deno**: Secure runtime with built-in TypeScript support (`deno test`)
+
+The [test-anywhere](https://github.com/link-foundation/test-anywhere) framework provides a unified testing API that works identically across all runtimes.
+
+#### Package Manager Agnostic
+
+While `package.json` is the source of truth for dependencies, the template supports:
+
+- **bun**: Primary choice, uses `bun.lockb`
+- **npm**: Uses `package-lock.json`
+- **yarn**: Uses `yarn.lock`
+- **pnpm**: Uses `pnpm-lock.yaml`
+- **deno**: Uses `deno.json` for configuration
+
+Note: `package-lock.json` is not committed by default to allow any package manager.
+
+#### Code Quality
+
+- **ESLint**: Configured with recommended rules + Prettier integration
+- **Prettier**: Consistent code formatting
+- **Husky + lint-staged**: Pre-commit hooks ensure code quality
+- **File size limit**: Files must stay under 1500 lines for maintainability (enforced via ESLint and CI)
+
+#### Release Workflow
+
+The release workflow uses [Changesets](https://github.com/changesets/changesets) for version management:
+
+1. **Creating a changeset**: Run `bun run changeset` to document changes
+2. **PR validation**: CI checks for valid changeset in each PR
+3. **Automated versioning**: Merging to `main` triggers version bump
+4. **npm publishing**: Automated via OIDC trusted publishing (no tokens needed)
+5. **GitHub releases**: Auto-created with formatted release notes
+
+##### Manual Releases
+
+Two manual release modes are available via GitHub Actions:
+
+- **Instant release**: Immediately bump version and publish
+- **Changeset PR**: Create a PR with changeset for review
+
+#### CI/CD Pipeline
+
+The GitHub Actions workflow (`.github/workflows/release.yml`) implements a fast-fail pipeline:
+
+**Fast checks** (~7-30s each, run first for fastest feedback):
+
+1. **Test compilation**: Syntax-checks all `.mjs` files with `node --check`
+2. **Lint, format & secrets scan**: ESLint, Prettier, jscpd, and [secretlint](https://github.com/secretlint/secretlint) for credential leak detection
+3. **File line limits**: Enforces 1500-line limit on `.mjs` files and `release.yml`
+4. **Changeset check**: Validates PR has exactly one changeset (added by that PR)
+5. **Version check**: Blocks manual version changes in `package.json`
+6. **Documentation validation**: Checks doc file sizes and required files
+
+**Slow checks** (only run after all fast checks pass):
+
+7. **Test matrix**: 3 runtimes × 3 OS = 9 test combinations
+8. **API doc build**: `npm run docs:api` + `cargo doc --manifest-path rust/Cargo.toml --no-deps --workspace`
+9. **Broken link checks**: Validates all links in Markdown/HTML files (separate workflow)
+
+**Release** (on merge to main):
+
+10. **Changeset merge**: Combines multiple pending changesets at release time
+11. **Release**: Automated versioning and npm publishing
+12. **GitHub Pages**: `pages.yml` publishes the SPA bundle (this PR).
+
+##### Reasonable timeouts on every job
+
+Every CI job declares an explicit `timeout-minutes` so a hung step
+fails fast instead of stalling for the GitHub default of six hours.
+The bands are sized at roughly 5–10× the observed p95 to absorb cold
+runners without hiding real flakiness:
+
+| Job                        | Cap      | Typical                                      |
+| -------------------------- | -------- | -------------------------------------------- |
+| Detect Changes / file size | 5 min    | ~3–6 s                                       |
+| Test Compilation           | 5 min    | ~4 s                                         |
+| Version / Changeset checks | 5–10 min | ~6–13 s                                      |
+| Lint and Format            | 10 min   | ~23 s                                        |
+| Build API Docs             | 15 min   | ~25 s                                        |
+| Test (per runtime × OS)    | 10 min   | ~13–55 s (deno-windows up to ~2 min on cold) |
+| Release / Instant Release  | 30 min   | well under 10 min                            |
+| Broken Link Checker        | 10 min   | ~8 s                                         |
+| GitHub Pages build/deploy  | 10 min   | ~30–60 s                                     |
+
+Per-test timeouts are also enforced inside the runners themselves so
+an individual hung promise surfaces in seconds rather than at the job
+cap: `node --test --test-timeout=30000` and `bun test --timeout 30000`.
+
+See [BEST-PRACTICES.md](docs/BEST-PRACTICES.md) for detailed explanations of each practice.
+
+##### Robust Changeset Handling
+
+The CI/CD pipeline is designed to handle concurrent PRs gracefully:
+
+- **PR Validation**: Only validates changesets **added by the current PR**, not pre-existing ones from other merged PRs. This prevents false failures when multiple PRs merge before a release cycle completes.
+
+- **Release-time Merging**: If multiple changesets exist when releasing, they are automatically merged into a single changeset with:
+  - The highest version bump type (major > minor > patch)
+  - All descriptions preserved in chronological order
+
+This design decouples PR validation from the need to pull changes from the default branch, reducing conflicts and ensuring that even if CI/CD fails, all unpublished changesets will still get published when the error is resolved.
+
+#### Broken Link Checker
+
+The link checker workflow (`.github/workflows/links.yml`) validates all links in Markdown and HTML files:
+
+1. **Detection**: Uses [lychee](https://github.com/lycheeverse/lychee-action) to scan all `*.md` and `*.html` files
+2. **Web Archive fallback**: For any broken links found, automatically checks the [Wayback Machine](https://web.archive.org) for archived versions
+3. **Actionable suggestions**: Reports one of three outcomes for each broken link:
+   - **Archived**: Suggests the Web Archive URL as a replacement
+   - **Not archived**: Clearly reports the link is unrecoverable
+4. **Scheduled checks**: Runs weekly to catch links that break over time (even if no files changed)
+5. **Issue creation**: On scheduled runs, creates a GitHub Issue with the full broken links report
+
+Add regex patterns to `.lycheeignore` to exclude URLs from checks (e.g., local dev URLs, example.com, known rate-limited sites).
+
+#### GitHub Pages publishing
+
+The `pages.yml` workflow (added in PR #9 / issue #8) builds `dist/pages/` from `js/src/web/` and deploys it to GitHub Pages on every push to `main`. The workflow uses the official `actions/configure-pages`, `actions/upload-pages-artifact`, and `actions/deploy-pages` actions. PRs run a build-only job for early feedback; only `main` and `workflow_dispatch` trigger an actual deploy. See [`docs/case-studies/issue-8/`](docs/case-studies/issue-8/README.md) for the full rationale, and [`js/scripts/build-pages.mjs`](js/scripts/build-pages.mjs) for the build helper.
+
+### Configuration
+
+#### ESLint Rules
+
+Customize ESLint in `js/eslint.config.js`. Current configuration:
+
+- ES Modules support
+- Prettier integration
+- No console restrictions (common in CLI tools)
+- Strict equality enforcement
+- Async/await best practices
+- **Strict unused variables rule**: No exceptions - all unused variables, arguments, and caught errors must be removed (no `_` prefix exceptions)
+
+#### Prettier Options
+
+Configured in `.prettierrc`:
+
+- Single quotes
+- Semicolons
+- 2-space indentation
+- 80-character line width
+- ES5 trailing commas
+- LF line endings
+
+### Scripts Reference
+
+| Script                 | Description                                      |
+| ---------------------- | ------------------------------------------------ |
+| `bun test`             | Run tests with Bun                               |
+| `bun run lint`         | Check code with ESLint                           |
+| `bun run lint:fix`     | Fix ESLint issues automatically                  |
+| `bun run format`       | Format code with Prettier                        |
+| `bun run format:check` | Check formatting without changing files          |
+| `bun run check`        | Run all checks (lint + format)                   |
+| `bun run changeset`    | Create a new changeset                           |
+| `bun run build:web`    | Build the production SPA bundle                  |
+| `bun run build:pages`  | Build the GitHub Pages artifact in `dist/pages/` |
+| `bun run build:mobile` | Build the Capacitor mobile bundle                |
+
+### Contributing
+
+See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for detailed contribution guidelines.
+
+Quick steps:
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes
+4. Create a changeset: `bun run changeset`
+5. Commit your changes (pre-commit hooks will run automatically)
+6. Push and create a Pull Request
+
+### Best Practices
+
+The CI/CD pipeline inherited from `js-ai-driven-development-pipeline-template` covers the practices documented in [BEST-PRACTICES.md](docs/BEST-PRACTICES.md):
+
+- File size limits for AI readability
+- Automated formatting and linting
+- Multi-runtime and cross-platform testing
+- Changeset-based versioning
+- Concurrency control for CI/CD pipelines
+
+## License
+
+[Unlicense](LICENSE) - Public Domain