whatsapp-ng 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+## Unreleased
+
+## 1.1.0 — 2026-10-29
+
+The maintainer approved promoting the prepared, unpublished RC2 source to stable `1.1.0` under `latest`. The release adds the outcomes below to published RC1; broader platform/live qualification and the documented inherited SDK findings are unchanged. `next` is not advanced by this promotion.
+
+- Add a default-off **Connection → Auto-connect on startup** preference for TUI/RPC, persisted as a strict `autoConnect` boolean. Serialize config writes/cleanup and preserve newer cross-process selections; keep print/JSON opt-in and skip occupied-profile retry noise. Reuse saved credentials and the explicit online flag; changes are future-only, and Off survives reload/session replacement in its process. Back from this setting returns to Connection without changing the preference. No new tool, dependency or automatic pairing.
+
+- Add case-insensitive fuzzy `/model` search across authenticated provider/model identifiers. Require explicit selection for search results, retain filters through pagination, and preserve exact selection, owner/group authorization, idle guards and private-identifier redaction. No dependency changes.
+
+- Refresh maintainer guidance, startup/Back acceptance, version availability and package discovery explanations; preserve dated source/live/artifact limits and the inherited development-audit findings. Publication is deliberate; no publishing-automation activation.
+
+### Earlier development notes shipped in RC1
+
+The published RC1 artifact retained these notes under “Unreleased”. They are preserved as historical development context, not new 1.1.0 work or current publication/bootstrap status. See the release guide for current preparation and separate publishing gates.
+
+- Prepare PR/main validation and default-off tag-triggered GitHub/npm OIDC publishing. Require exact version-tag/main ancestry, protected-environment approval and the same checksummed candidate; reject rerun publication and token fallback, retain attempt evidence, and verify registry integrity/tags. First publication still needs a separately approved manual bootstrap; no tokens, environment settings, tags or releases are created automatically.
+
+- Add dependency-free local release commands for explicit version/lockfile updates, clean-commit validation and tarball preparation, plus separately confirmed publication of the checksummed artifact. Keep prereleases on `next`, reserve `latest` for explicit stable versions, and retain publication-attempt evidence instead of retrying uncertain outcomes. No automatic commits, tags, pushes or release promotion.
+
+- Clean a separate spoken copy of automatic answers: remove ordinary emphasis/headings/bullets and quote escapes, allow short inline words/menu labels, preserve approximate values and bound heading parsing. Keep displayed text unchanged and command-like snippets/tables/overlong answers as complete text. Preserve link addresses through full-text fallback in Voice/Mirror; Voice + text speaks link labels only after its text send is accepted. No summarization or provider change.
+
+- Restrict `configure_wa_stt` updates and resets to verified local requests or the configured WhatsApp owner. Recheck authority through atomic settings commit; denied, stale, cancelled and failed writes preserve disk and memory. This prevents other allowed chats from redirecting transcription uploads or selecting a different API-key environment variable through this tool.
+
+- Permit loopback HTTP speech endpoints and explicitly opted-in non-loopback HTTP without relaxing URL/redirect guards or destination consent. Add CrispASR CLI/model/language aliases while retaining Whisper-first PATH discovery, plus optional remote-only STT language and a packaged [local speech guide](docs/crispasr.md). Preserve TTS wire bodies and existing backends; no binaries/models or new download machinery are bundled. Validate with **1194 tests/81 files**, no skips, lint/typecheck clean; clarify non-destructive HTTP opt-in recovery and isolate tests from the operator's exported opt-in.
+- Retain full JID namespaces in model-facing sender/participant labels and require +E164 or a complete person JID for manual Owner entry, with localized validation. Preserve verified PN/LID voice preference matching and explicit-text duplicate suppression; do not guess aliases, migrate live settings or claim that a malformed Mirror key caused a voice failure.
+- Group `/whatsapp` into Connection, Chats / Owner, Replies, Voice, Groups and Advanced. Share confirmed terminal/phone Off, make repeated Off inert, refresh connection options and close expired dialogs without applying stale choices. Cancel stale startup retries and restore only previously active outbound tools after reload/re-enable. Keep offline history, login and saved preferences.
+- Replace body/error-payload diagnostics with private metadata-only runtime logs, best-effort 5 MiB rotation plus one backup and bounded records. Preserve historical logs; verbose no longer enables protocol traces. Keep ordinary error notices visible through the narrow startup/shutdown noise filter.
+- Correct Sonnet-reviewed group/optional-output behavior: preserve questions on failed quoted-image downloads, retain final explanations after projected images in legacy mode, and avoid read receipts for ignored/paused input. Clarify image-tool consent, warn locally on oversized terminal answers and resolve source diagnostic warnings without changing live settings.
+- Add default-off, individually approved tool-image projection for verified WhatsApp work and explicitly confirmed terminal/RPC final-text forwarding to the private owner/account only. Keep terminal screenshots local; reject paths/URLs, stale work, group/gateway retargeting and mid-task opt-in. Reuse bounded private snapshots, deferred settlement and uncertain-delivery suppression. Owner-confirmed private terminal forwarding/disable checks passed; automatic-image live checks remain open.
+- Default allowed groups to verified mentions/replies, with terminal choices for mentions, replies or all messages. Add explicitly confirmed, bounded memory-only text context and retained same-group image references for text/audio requests. Preserve pauses, group-only binding and control authorization; stale queued admissions abort before usable inference. Owner-confirmed live group mention/reply testing passed; broader live paths remain unverified.
+- Accept manual self-chat messages through authenticated own PN/LID identity, including text ending in `π`, without accepting registered outgoing echoes or turning ordinary own-direction messages to other chats into automatic work. Keep history/import/replay exclusions and make phone pause state explicit.
+- Extend default-off final stats with independently selected successful write/edit file labels, completed interim assistant text and one throttled own-key edited activity message. Keep reporting bounded, input-time consented and withdrawable without suppressing final answers, exporting reasoning/tool bodies or reviving revoked work. Conservatively adapt assistant Markdown while preserving code and URL destinations; live rendering remains owner-controlled.
+- Default native phone-control polls off behind explicit `--whatsapp-ng-native-polls`; numbered menus remain usable. Correct valid implicit self-chat references and raw LID/phone cryptographic author selection without relaxing owner checks. Exact Codex-high review: OK; 984 tests passed. The owner subsequently confirmed bounded self-chat navigation and a thinking acknowledgement; broader poll/client compatibility remains experimental.
+- Add verified-owner phone controls for exact model/thinking, compact/new/stop, approved voice/reply preferences and confirmed Off/quit. Numbered menus work first; bounded native polls share the existing admitted intake. Handled controls never become model prompts.
+- Preserve Off across session replacement/reload, withdraw outbound tools and retain terminal-only re-enable. Bound pending plus withdrawn follow-ups together without eviction/expiry reviving stopped work; redact explicit filesystem model identifiers from phone output.
+- Refresh source validation to **1148 tests/79 files**, no skips, lint/typecheck clean. Correct the Opus-reviewed inline-code formatting defect, bound long-line parsing and preserve existing stats/phone controls when optional reporting settings are malformed. Correct the final-stats review's late opt-in timing defect with seven failing-before/passing-after regressions, including production-entry RPC/UI. Existing production-audit and live-speech evidence remain separately dated; C4 live-client, remaining C3 image, new Linux/Windows and clean-install qualification are not claimed.
+- Make the completed **October 24, 2026 Tesseract 5.5.3/LiteParse 2.17.0 OCR checks** explicit: direct English raster recognition, scanned-PDF OCR, OCR-disabled behavior, corrupt-input fallback and worker cleanup passed. English/Spanish language data were present; a separate Spanish-accuracy benchmark is not claimed.
+- Record the user-confirmed **Groq STT → Fish TTS** self-chat voice-note round trip; distinguish that playback evidence from the separate English/Spanish Edge synthesis checks. Use explicit Mexico City/UTC dates for the Edge result.
+- Add persisted Voice/Owner settings, terminal-only destination consent, per-chat output/automatic-reply controls and a reviewed AI introduction. Existing chats remain text-only; group speech requires independent opt-in and paused work is not replayed.
+- Add owner-authorized `configure_wa_tts` with atomic merge/removal, safe metadata and no immediate synthesis or consent grant. Verify native terminal/RPC provenance or the actual configured WhatsApp owner, never a rendered header or absent reply target; pairing no longer appoints the owner.
+- Offer an explicitly confirmed, selected-allowed-chat fixed-phrase voice preview; preserve cancellation, no automatic unknown-delivery retry, and sender-owned snapshot settlement.
+- Wire a final-output coordinator for text, voice, voice + text and metadata-driven mirror modes, selected from validated saved preferences and destination approval.
+- Reserve finalization throughout synthesis, cancel stale/session-disconnected work, retain full-text fallbacks without another model call, and never resend uncertain voice uploads or duplicate the text in both mode. Keep generated snapshots until actual sender settlement, including archive-preflight/recording failures.
+- Upgrade the exact Edge client pin to MIT `msedge-tts@2.1.1`, incorporating merged upstream PR #43 and its Bing/v2 signing fix. Align consent/result metadata with the new synthesis endpoint; old-endpoint approval is not reused. Real English/Spanish Andrew Multilingual checks produced complete Opus voice-note artifacts, closing the local Edge synthesis gate without changing Fish/WhatsApp settings. See [evidence and scope](DEPENDENCIES.md#edge-service-regression-october-23-2026).
+- Add internal bounded speech backends: native-fetch Fish/OpenAI-compatible/OpenRouter and an explicitly approved MIT Edge client, with exact provider mapping, destination consent checks, owned worker cancellation, private intermediates and existing Ogg/Opus voice-note preparation. Speech stays off until explicitly enabled in the terminal Voice menu.
+- Carry input kind and verified direct/group/self actor metadata through exact input consumption and frozen routing snapshots, with conservative mixed/unknown handling and runtime/account revalidation; keep metadata out of hashed prompt content.
+- Deliver the final explanation after attachment sends by default; retain explicit-text duplicate suppression and a persisted terminal option for legacy caption/tool-only behavior.
+- Track attachment, explicit text, progress and final delivery separately, claim each final response before transmission, and reject captured snapshots after session reset.
+- Add policy-aware WhatsApp prompt guidance and fixed retry notices for mixed, verified conversation inputs without forwarding ambiguously owned model content.
+- Clarify the Voice/Owner menu, backend-only `configure_wa_tts`, global versus chat-specific Mirror settings, and why LID digits must not be converted into a phone JID.
+
+## 1.1.0-rc.1
+
+Maintained continuation of the [upstream project](README.md#fork-and-legacy-names), preserving original history, attribution and MIT notices. The prerelease tag is `next`, not `latest`.
+
+### Messaging foundation
+
+- Process every eligible batch item; isolate failures and suppress bounded replay/owned-send echoes.
+- Resolve PN/LID/device aliases without replacing transport identity; re-index late mappings and fence obsolete socket/account work.
+- Preserve complete message keys, including group participants; support compound emoji and unambiguous reaction targets.
+- Attribute shared-context replies through Pi input provenance and immutable routing snapshots. Ambiguous or terminal-only work fails closed rather than using a stale recipient.
+- Distinguish pre-send failure, socket acceptance and delivery-unknown outcomes; do not automatically retry uncertain sends.
+
+### Media and native replies
+
+- Add explicit local document/image/audio/voice-note/video sending and native quoted replies in tools/UI.
+- Validate file type, allowed roots, ancestry and descriptor stability; reject symlinks/FIFOs/secret paths and bound files to 25 MiB.
+- Prepare codec conversions/thumbnails in owned processes with a shared 60-second budget; retain private snapshots until consumers settle.
+- Keep raw retry content bounded and exclude view-once/disappearing payloads as applicable. Missing/expired/unsupported quote targets remain explicitly unavailable.
+- Bound incoming image/video/document downloads to 25 MiB; avoid repeated buffer copies and save new files privately with collision-resistant, exclusive names.
+
+### Conversation fidelity
+
+- Add private, versioned, atomically replaced per-profile/account archives and offline scope selection/pagination.
+- Preserve visible text/emoji, observed identities, safe quote/media metadata and lifecycle state without transport secrets or attachment bytes.
+- Add explicit bounded history requests and local status tracking; imported history never triggers agent prompts or media processing.
+- Reconcile receipts, edits, revocations and reactions, with bounded pending updates and deletion-protecting admission floors. Interrupted work is not automatically reissued.
+
+### Authentication and namespace
+
+- Add canonical-profile transport ownership, serialized lifecycle transitions, retired-auth I/O fences and pinned rc14 credential-shape validation.
+- Gate explicit legacy-profile adoption by source/destination ownership; preserve originals, reject merging and retain private adoption/reset markers.
+- Rename the entry, logger, flags, environment identifiers, scripts, service templates and session/shutdown state to the independent `whatsapp-ng` namespace.
+- Add explicit-source, same-filesystem whole-state migration to `~/.pi/agent/extensions/whatsapp-ng`: preserve settings/auth/history/media/logs and relative archive/profile identities. Never merge an occupied destination, copy credentials or steal locks.
+- Gate startup/storage/logging on migration completion, including shutdown; retain startup results across session replacement and extension recreation. Recover interrupted moves only by verified directory identity.
+- Verify that moving the data directory preserves settings, saved authentication, media, conversation archives, profile metadata and private permissions.
+
+### Dependencies and packaging
+
+- Pin Baileys 7.0.0-rc14 and upgrade LiteParse from 2.15.1 to 2.17.0; retain lazy native PDF loading and bounded parsing/cleanup/fallback.
+- Remove the FFmpeg npm binary/downloader dependency. Use user-installed FFmpeg through `FFMPEG_PATH` or `PATH`.
+- Use wildcard host-provided Pi/TUI/TypeBox peers and align the SDK/AI/TUI development cohort and lockfile with Pi 1.4.0; retain the host's independent TypeBox 1.3.27 version and refresh test tooling.
+- Include MIT terms, original/yearless upstream attribution, the owner's 2026 notice and private security reporting. No transport upgrade or protocol patch.
+
+### Remote transcription
+
+- Add provider-neutral `sttEndpoint`, `sttModel` and `sttEnv` settings for an OpenAI-compatible `/audio/transcriptions` endpoint. Persist the environment-variable name, never its key value.
+- Keep local Whisper as the unconfigured default; configured remote mode skips local initialization/model downloads and never silently falls back after a configuration/provider error.
+- Preserve omitted fields in STT configuration updates, reject invalid/incomplete combined settings before saving, and retain explicit empty-configuration clearing.
+- Retain FFmpeg WAV conversion, add private collision-resistant audio scratch directories/cleanup, download/upload/response bounds, timeouts, redacted errors and account/session fencing with best-effort in-flight cancellation. No new dependency or live provider certification.
+
+### Local transcription and documentation
+
+- Use user-installed Whisper.cpp through `WHISPER_CLI_PATH` or `PATH`; remove repository build helpers and implicit vendor-directory lookup. Keep the independent Node binding fallback; npm still lists 0.2.12 as latest at the time of this update.
+- Prefer an available CLI over the optional Node binding, so a working system install does not depend on the binding's Node ABI/build.
+- Reuse an explicit `WHISPER_MODEL_PATH`, reject invalid/empty model overrides without a replacement download, support `WHISPER_LANGUAGE` (default `auto`), and use CPU mode.
+- Bound CLI model preparation/transcription to ten minutes, abort on cancellation/session change, wait for child closure before cleanup, and publish downloaded models atomically from private temporary files.
+- Replace the misleading Node-binding-only availability error with backend-neutral setup guidance; keep the obsolete local debug capture and generated Pi state out of version control.
+- Refresh README/dependency guidance, index historical versus current specs and remove the redundant local strategy pointer. Historical decision/review records remain intact.
+
+### Testing and known limits
+
+- Recorded source validation passed 585 tests across 58 files with two workers and no skips, plus lint and typecheck on macOS with Pi 1.4.0. Direct Tesseract raster OCR and LiteParse 2.17.0 text/OCR/corrupt-file/worker-cleanup tests passed using system tools. Tests cover actual FFmpeg conversion, intercepted uploads, config persistence, credential handling, cleanup and session cancellation.
+- Live direct-chat checks include media/native replies, saved-session reconnects, selected history/receipt behavior and a real WhatsApp voice note transcribed through Groq into Pi. These checks do not establish general recognition accuracy or compatibility with every provider.
+- Earlier Linux package and storage-migration tests used Pi 1.3.0. The updated package needs fresh Linux testing; Windows, service installers and broader group/history/receipt behavior remain unverified. See [storage migration test results](specs/038-whatsapp-ng-namespace/validation.md) for the earlier evidence.
+- Known Pi SDK/host Undici advisories remain outstanding. The latest recorded production-only npm audit reports zero findings but excludes host-supplied packages. See [dependency and security details](DEPENDENCIES.md#latest-audit-refresh).
+- Published-package and host behavior remain subject to the limitations above; this prerelease is not a stable-support commitment.

package/DEPENDENCIES.md

@@ -0,0 +1,148 @@
+# Dependency and native-tool policy
+
+## Maintainer reproduction
+
+Use the committed npm lockfile with Node 26.x and Pi 1.4.0, matching the development SDK/AI/TUI cohort retained unchanged for `1.1.0`:
+
+```sh
+npm ci --ignore-scripts --legacy-peer-deps --no-audit --no-fund
+npm test -- --maxWorkers=2
+npm run lint
+npm run typecheck
+npm audit
+npm audit --omit=dev
+```
+
+`--legacy-peer-deps` matches the Pi managed-install policy: Pi supplies the runtime host packages. Keep the flag with `npm ci`; the lock was generated with it. `--ignore-scripts` prevents dependency lifecycle downloads/builds. This workflow requires system FFmpeg; local OCR additionally requires Tesseract and its English data. It does not build Whisper or install a model.
+
+The lock fixes the maintainer dependency graph and records integrity for npm artifacts. It does **not** freeze system executables, model files, future consumer transitive resolution or every native platform. Root package-lock.json is not shipped in the npm tarball. Consumers need their own lock/policy; exact Baileys/LiteParse pins are not a universal transitive freeze.
+
+## Dated source checkpoint: October 27, 2026
+
+The following is the earlier source/control checkpoint, not the current RC2 artifact qualification. Later source checks, fresh audits and remaining acceptance scope are recorded in the [RC2 preparation record](https://github.com/jagaliano/whatsapp-ng/blob/main/specs/040-rc2-publication-readiness/validation.md). Earlier live checks retain their separately recorded dates:
+
+- macOS/Node 26.12.1 source validation: **1101 tests/78 files**, zero failures or skips, lint/typecheck clean. The previously recorded production-only `npm audit` reported **zero findings**; dependencies are unchanged by phone control, final stats, group/self-chat policy, optional output projection and settings/log privacy changes. That audit does not cover host-supplied peers or certify embedded native binaries.
+- Exact Codex high phone-control review initially blocked retirement-fence eviction/expiry and identified relative-path disclosure. Both were corrected; focused re-review returned **OK**. Real isolated Pi fixtures verify session cancellation/replacement, Off persistence across replacement/reload, write-tool withdrawal and an already-aborted signal for withdrawn follow-ups. Encrypted direct/group votes are synthetic fixtures, not live-client qualification.
+- Optional final-stats review identified one late opt-in timing defect. Eligibility now latches at input consumption, not the first assistant frame. Seven failing regressions, including actual production-entry RPC/UI, pass after correction; no second independent verdict is claimed. Native SDK cases cover successful/failed tools and terminal isolation. See [stats evidence and scope](specs/039-extension-improvements/c1-stats-validation.md).
+- Group/self-chat policy adds default verified mention/reply triggers, optional confirmed bounded text context and cached image references without changing login/history layouts. Five production-entry RPC scenarios cover controls, polls, stats, stale queued group admission and self-LID echo protection with synthetic transport/model streams and zero network attempts. The owner subsequently confirmed the native mention/reply flow in one live test group from another participant; other live paths/clients remain unverified. See [C2 validation](specs/039-extension-improvements/c2-validation.md).
+- Default-off optional outputs reuse existing image snapshots/sender guards and require individual tool consent or owner/account-bound private terminal-forwarding consent. Two additional production-entry RPC cases verify image deduplication/terminal isolation and late-opt-in/private-owner/group/disable routing with zero network attempts or extra model calls. The owner subsequently confirmed bounded private terminal forwarding and its local-only disable path. Automatic-image live checks remain open; the subsequent Sonnet 5.5 C2/C3 review and parent fixes are recorded in [the disposition](specs/039-extension-improvements/c2-c3-review.md). No agent-side real settings change is claimed. See [C3 validation](specs/039-extension-improvements/c3-validation.md).
+- Grouped settings and shared terminal/phone Off add an eighth production-entry RPC scenario: active/queued WhatsApp work is withdrawn, Off survives new-session/reload, only previously active outbound tools return on terminal Connect, and fresh work succeeds. Private metadata logs exclude request/answer bodies and preserve historical logs. Synthetic transport/model streams made zero network attempts; no real settings change, independent C4 review or live-client verification is claimed. See [C4 scope](specs/039-extension-improvements/c4-validation.md).
+- **Tesseract/OCR is verified, not pending.** The October 24 checks used Tesseract **5.5.3**, Leptonica **1.87.0** and LiteParse **2.17.0**. Direct English raster recognition and scanned-PDF OCR passed; the same real-tool contract tests passed without skips in that source suite. `eng` and `spa` data were installed, but a separate Spanish-recognition accuracy benchmark was not run.
+- A real **Groq STT → Fish `s2.1-pro-free` TTS** self-chat round trip produced an accepted Ogg/Opus voice note, with user-confirmed playback. Self-chat does not establish independent-recipient receipt behavior.
+- **Edge `msedge-tts@2.1.1`** completed fixed English/Spanish Andrew Multilingual synthesis and produced valid private Opus artifacts. The local synthesis compatibility gate is closed; Edge WhatsApp playback and universal service availability are not claimed.
+- The **51-file phone-control package** was byte-checked and source/packaged startup-tested at the 976-test checkpoint. The later native-poll correction and final stats have isolated source/RPC checks; the current settings/log-privacy dry run contains 56 files, not a newly qualified tarball or clean consumer install. The native v2 Edge worker remains included.
+- Native polls default off behind `--whatsapp-ng-native-polls`. Live self-chat showed votes without actions while typed numbers worked. A reviewed correction passes raw LID/phone author and implicit-reference fixtures through the production entry, with zero model/network activity; the owner subsequently confirmed bounded self-chat navigation and a thinking-level acknowledgement. Other clients/groups and model switching are not implied qualified.
+- No new Linux/Windows qualification was performed. The older test counts below describe earlier checkpoints, not the current suite. The [full-tree/host assessment](#latest-audit-refresh) remains separately dated; the clean production audit does not close those findings.
+
+## Reviewed changes
+
+| Area | Candidate selection | Reason |
+|---|---|---|
+| Transport | Baileys 7.0.0-rc14 exact | Preserve the characterized transport; no protocol patch or newer prerelease. |
+| PDF | LiteParse 2.17.0 exact | Upgrade from 2.15.1; native text extraction, real local OCR, corrupt-file recovery and worker cleanup tested. |
+| Edge speech | msedge-tts 2.1.1 exact, MIT | Adopt merged PR #43's Bing/v2 signing fix; align consent identity, require completed protocol/audio and retain bounded worker cancellation. |
+| Dev SDK/AI/TUI | Official Pi 1.4.0 packages, retaining legacy SDK/TUI import aliases | Align the SDK cohort with the installed host; keep runtime host peers wildcard rather than bundling copies. |
+| Dev TypeBox | Legacy name aliased to typebox 1.3.27 | Pi 1.4.0 still supplies this independent TypeBox version; it is intentionally not changed to 1.4.0. |
+| Test tools | Vitest/coverage 5.0.5, required Vite peer 8.3.5, Node types 26.6.5 | Remove the old critical Tinypool/test-server paths and satisfy declared tooling peers. |
+
+The wildcard runtime host peers remain unchanged; dev copies are not runtime dependencies. The real SDK policy/input/image ownership test is retained with the current ModelRuntime API, an intercepted stream, blocked fetch and assertions of zero provider fetches.
+
+## Native/runtime inventory and limits
+
+| Component | Declared license / supply path | Candidate behavior |
+|---|---|---|
+| LiteParse/platform package 2.17.0 | Apache-2.0; platform-native addon and PDFium library supplied through npm artifacts | Matching optional package required. The generic tarball also contains Linux native files; those do not provide macOS/Windows support. Seven optional platform variants are locked, not all tested. |
+| Speech synthesis | MIT `msedge-tts@2.1.1` (Edge only); native fetch for remote HTTP providers | Explicitly approved Edge dependency, including its browser-compatibility/axios/ws transitives. No Fish/OpenAI/OpenRouter SDK, dotenv package, CLI installer or speech model download. Edge is an unofficial online Microsoft service, not local inference or an Azure SLA. |
+| Local OCR | System Tesseract (Apache-2.0), Leptonica and language data with their own terms | Tesseract 5.5.3/Leptonica 1.87.0 tested with direct raster OCR and LiteParse scanned-PDF OCR. No configured OCR server; missing tools/data retain the existing text/saved-file fallback. No JS Tesseract/model downloader. |
+| Baileys/native crypto | MIT Baileys and whatsapp-rust-bridge 0.5.4; libsignal 6.0.0 declares GPL-3.0 | Retained, not relabeled MIT by this fork. Rust bridge ships its compiled/WASM assets; no transport-source build performed. |
+| System FFmpeg | User-installed build; its licenses and codec support depend on the distributor | Resolve `FFMPEG_PATH`, otherwise `ffmpeg` on `PATH`. No binary, npm FFmpeg package or downloader is supplied. Users install and update it; tests used FFmpeg 9.0.2. |
+| Whisper-cpp-node 0.2.12 / external Whisper.cpp CLI | MIT package with optional platform-native addons; independent user-installed CLI/models | Prefer explicit `CRISPASR_CLI_PATH`, then `WHISPER_CLI_PATH`; otherwise discover Whisper before CrispASR on `PATH`. A compatible Node addon packages the Whisper.cpp engine and does not need a separately installed CLI, but still needs a GGML model. Unsupported/missing addons do not prevent system CLI use. CPU mode is explicit. |
+| Other lifecycle entries | Baileys engine check, protobufjs setup, esbuild binary setup, optional fsevents, dev @google/genai setup | All disabled by the stated workflow. Native code can still arrive in npm optional packages and execute at import; `--ignore-scripts` is not a native-code sandbox. |
+
+The project's MIT license applies to its code, not to every dependency/native binary. Preserve third-party notices and obligations for any redistribution; no dependency binaries are vendored into this extension tarball. This table records package-declared licenses and observed setup, not a complete legal/native-library vulnerability certification.
+
+PDF native import/construction occurs only inside the PDF fallback boundary. Each PDF gets one pool process/one native worker, with a 60-second **parse** timeout and close on success/error. Startup/initialization is outside the library's parse timeout. Successful shutdown/replacement-child cleanup is tested; no total-operation or all-descendant cancellation guarantee is asserted. Invalid/unavailable parsing retains the saved bytes and existing bounded-preview/fallback behavior.
+
+## Remote STT
+
+`sttEndpoint`, `sttModel` and `sttEnv` in extension config select an OpenAI-compatible `/audio/transcriptions` backend. `sttEnv` stores only an environment-variable name; its value is resolved at request time and is never copied into config. There is no provider SDK or new dependency. The implementation uses the host's `fetch`, `FormData`, `Blob`, TLS and cancellation support; auditing npm dependencies alone does not certify the host's HTTP implementation.
+
+Selecting remote STT explicitly sends admitted voice-note audio to the configured endpoint. HTTPS is required except for loopback HTTP or launch-environment `WHATSAPP_NG_ALLOW_PLAIN_HTTP=1`; non-loopback HTTP exposes audio and Bearer credentials unencrypted. The same transport policy applies to remote TTS text/audio. URL/redirect guards and destination-specific speech approval remain intact. FFmpeg still converts to mono 16 kHz WAV; remote mode does not initialize local Whisper or download a model. Invalid/partial settings or request failures never silently fall back. No provider is selected by hostname, and compatible chat endpoints are not automatically compatible transcription endpoints. See [configuration, limits and privacy](README.md#audio-transcription).
+
+Recorded validation passed 552 tests/55 files with `npm test -- --maxWorkers=2`, lint and typecheck in an isolated HOME. Coverage includes actual FFmpeg conversion, private scratch permissions/cleanup, config persistence, intercepted multipart uploads, byte limits, error redaction and session cancellation. An initial unrestricted run hit a 15-second native PDF/OCR timeout; the unchanged test passed alone and with two workers. Isolated Pi 1.4.0 startup/session-replacement checks preserved local and remote settings, and a 40-entry package dry run included the remote transcriber.
+
+Live Groq checks include a five-second public speech upload returning HTTP 200, a real WhatsApp voice note transcribed through `whisper-large-v3-turbo` into Pi, and the subsequently confirmed Groq-to-Fish self-chat voice round trip. These validate specific examples, not general accuracy, every provider or all WhatsApp routing behavior. Additional regression coverage could exercise stalled response bodies and session changes during file preparation.
+
+## Speech backend foundation
+
+Remote adapters use native fetch and streaming responses; Edge alone uses the owner-approved exact `msedge-tts@2.1.1`. Source inspection and native-worker protocol tests confirm that the client ends its audio stream on `turn.end` and rejects premature socket closure; the earlier `node-edge-tts` streaming candidate could finish on error/timeout instead. The AGPL `edge-tts-universal` package was not adopted. Automatic finalization and the Voice/Owner settings require explicit destination consent; configuring a backend alone never enables speech.
+
+Edge synthesis uses `wss://speech.platform.bing.com/consumer/speech/synthesize/readaloud/edge/v1`; destination consent and result metadata identify that exact transport. Approval for the former `api.msedgeservices.com` endpoint is not carried to the new destination. Each request runs in an owned native `.mjs` worker, avoiding TypeScript stripping inside installed node_modules. Text crosses an in-memory channel, not argv; credentials and inherited preload flags are excluded. Worker diagnostics are discarded and termination is awaited. The remote adapters do not use the Edge client's transitive axios dependency. Destination-specific consent, credential-variable names, bounded text/audio/queue/deadline, session cancellation and existing FFmpeg/private PTT snapshot ownership apply to every backend. These bounded checks do not certify every provider/model/platform; the separately recorded Groq/Fish WhatsApp self-chat playback test does not qualify Edge WhatsApp playback.
+
+### Edge service regression: October 23, 2026
+
+Upstream [issue #42](https://github.com/Migushthe2nd/MsEdgeTTS/issues/42) reports a synthesis regression beginning **October 23, 2026**. Our October 25 check reproduced it with `msedge-tts@2.1.0`: HTTP 200 instead of a WebSocket upgrade; an endpoint-only legacy-route check returned HTTP 403. Those failed receipts remain historical evidence, not the current compatibility result.
+
+Upstream [PR #43](https://github.com/Migushthe2nd/MsEdgeTTS/pull/43) merged October 25 and ships in the exact adopted **`msedge-tts@2.1.1`**. It restores the Bing synthesis route with v2 signing; changing the endpoint alone was insufficient ([issue #44](https://github.com/Migushthe2nd/MsEdgeTTS/issues/44)). The update's registry integrity/MIT license and completion/error/cancellation contract were inspected. Installation used `--ignore-scripts --legacy-peer-deps`; the package's `preinstall` (`npx only-allow pnpm`) was not run. Only the root dependency pin and msedge-tts lock node changed; no Python alternative or locally patched authentication code was adopted.
+
+**Local synthesis gate closed October 25, Mexico City (October 26 UTC):** real English and Spanish fixed phrases using `en-US-AndrewMultilingualNeural`/`en-US` both reached successful protocol completion and produced valid private Ogg/Opus PTT artifacts (4 and 5 seconds). Native protocol tests cover v2 signing, compatibility headers, exact consent destination, truncated/empty/oversized streams and fresh approval after the endpoint change. Full regression validation passed **884 tests/69 files**, lint and typecheck. No live WhatsApp send or Fish-configuration change was performed for these Edge checks. This is scoped Node/macOS synthesis evidence, not an Azure SLA, universal availability or human-confirmed Edge WhatsApp playback.
+
+## Whisper setup and model policy
+
+The following applies to local mode, when remote STT is not configured. An existing system Whisper.cpp installation is sufficient; do not rebuild/install the Node addon merely to use that CLI. The runtime never runs a package installer or build script. Set `WHISPER_CLI_PATH` for a nonstandard executable, `WHISPER_MODEL_PATH` for your existing GGML model (including a light/tiny model), and optionally `WHISPER_LANGUAGE` (`auto` by default). Nonempty `CRISPASR_CLI_PATH`, `CRISPASR_MODEL_PATH` and `CRISPASR_LANGUAGE` are higher-priority aliases; invalid explicit paths never silently fall back. No CrispASR binary/model or new downloader is bundled. The optional remote-only `sttLanguage` does not change local language or TTS bodies. See the [CrispASR setup and limitations guide](docs/crispasr.md). The CLI receives `--no-gpu`; the native binding uses `use_gpu: false`.
+
+A configured model must be a nonempty regular file. An invalid override fails without downloading or substituting another model. Without an override, the legacy default remains `whisper/models/ggml-base.bin` under the extension data root; first transcription downloads that model from Hugging Face if absent. Set an existing model path to avoid that download. Model bytes, licenses, provenance and runtime cost are separate from the npm lock.
+
+A configured but invalid CLI is not silently replaced by another executable/backend. CLI selection does not prove model compatibility or successful transcription. Executables/models configured after the extension starts require a reload/restart to reconstruct its transcriber. Users install/build the CLI using upstream instructions; extension-maintained build helpers and implicit vendor-directory lookup have been removed.
+
+## Native-tool update validation
+
+Registry checks on 2026-10-24 reported LiteParse **2.17.0** and whisper-cpp-node **0.2.12** as their latest stable npm versions. LiteParse and its matching native package were upgraded; the Node binding was already current and remains a fallback. Its loader loads a packaged native addon, not an external `whisper-cli` process. CLI use is independent of that package.
+
+The **October 24, 2026** native-tool validation on macOS used Node 26.12.1, system FFmpeg 9.0.2, Tesseract 5.5.3/Leptonica 1.87.0 and installed whisper-cli 1.9.5. English and Spanish OCR data were available; the OCR recognition fixtures exercised English. The installed Whisper CLI passed version/discovery checks; no new speech transcription was run. The Node addon cannot load on this environment's platform, so its native execution was not tested here. All **559 tests/57 files** passed with two workers and no skips, including direct Tesseract recognition of a synthetic raster and LiteParse OCR of a raster-only PDF. Native PDF text extraction, corrupt input/fallback, worker cleanup, FFmpeg codecs, media preparation and remote-STT conversion fixtures passed. Lint/typecheck passed; the package dry run contained 40 entries.
+
+The production-only npm audit reported zero findings; the full tree retained the two known Pi SDK/Undici findings (one high, one moderate). No system tools were installed/upgraded, no Whisper model downloaded and no live WhatsApp or STT request was needed. These local checks do not requalify Linux/Windows packages or every user-installed tool version. See [OCR setup and manual checks](README.md#pdf-previews-and-ocr).
+
+## Publication-review corrections
+
+Fresh macOS validation with Node 26.12.1/Pi 1.4.0 passed **585 tests/58 files**, lint and typecheck, using a credential-free environment and isolated HOME. An actual `pi -e` synthetic probe first reproduced destructive partial STT updates and a CLI child continuing after abort; the corrected probe preserves the configured endpoint/key-variable name and observes cancellation. No real WhatsApp/STT call or model download was made.
+
+Regression coverage now includes configuration-tool updates/rejections/clearing, CLI timeout/cancellation/session changes/child closure, mocked stalled model responses, private atomic model publication, concurrent model preparation, and capped/private incoming image/video/document storage. The CLI has a shared ten-minute preparation/transcription budget; its process guarantee does not extend to the native addon. The compatible Node fallback and dependency declarations remain intact: the installed `whisper-cpp-node@0.2.12` main package has no install/preinstall/postinstall hook, and native platform packages are optional.
+
+The refreshed production audit remains clean; the full tree still has the two known SDK/Undici affected packages (one high, one moderate). No override, downgrade or dependency change was applied. Earlier test counts below remain historical rather than current release qualification.
+
+## Earlier dependency-security testing
+
+Assessment dated 2026-10-22. Before changes: 16 npm findings (11 high, 3 critical, 2 moderate), including LiteParse/Sharp, deprecated dev SDK/proxy/archive helpers and Vitest/Tinypool/Vite paths. After the scoped migrations, fresh full-tree and production-only `npm audit` runs reported **0 vulnerabilities**, without overrides, audit suppression or `npm audit fix --force`. Sharp is absent from the candidate lock; Baileys' separate optional image support is not represented as an installed vulnerable Sharp copy.
+
+Audit results are time-scoped registry-advisory evidence. They do not scan all embedded PDFium/Tesseract/codec binaries or prove absence of vulnerabilities; refresh before release. Deprecation warnings for unchanged tooling are not automatically ignored security findings.
+
+A fresh script-disabled `npm ci` regenerated node_modules with unchanged lock bytes, followed by 414 passing tests across 45 files, lint and typecheck. Real synthetic fixtures exercised PDF text, OCR off/on, corrupt PDFs, saved bytes/fallback and native child reaping. Tesseract-dependent tests explicitly skip if it is missing; the reported run had no such skip. Existing native Baileys/FFmpeg contracts also ran.
+
+Those dependency-security tests used macOS, Node 26.12.0, npm 12.2.0, Pi 1.3.0, FFmpeg 9.0.2, Tesseract 5.5.3/Leptonica 1.87.0. Its 414-test count and audit date are historical, not the current validation status.
+
+## Storage, platform and local transcription tests
+
+Storage migration testing passed 502 tests/51 files on macOS and Linux amd64, Node 26.12.1/Pi 1.3.0. Both platforms passed managed-package install/remove/reinstall, host-peer/schema discovery, packaged RPC migration/session-replacement/recovery, installed native auth and competing-process checks. Repository and consumer audits, full-tree and production-only, reported zero findings. The two 39-member tarballs had identical uncompressed payload bytes despite different gzip hashes; see the [storage migration test results](specs/038-whatsapp-ng-namespace/validation.md).
+
+The real namespace move was verified offline with settings/auth/media/archive/profile identities and permissions preserved. Earlier media/history checks predate that move. A later real WhatsApp voice note was transcribed through Groq and received by Pi; broader live behavior still requires separate testing.
+
+The local transcription fix was reproduced on macOS: a working `whisper-cli` on `PATH` was missed by the old resolver. The updated source passed **515 tests/53 files**, lint and typecheck in an isolated HOME; new fixture checks cover selection, CPU arguments, explicit model reuse, language and no-download failure paths. Isolated actual `pi -e` startup and installed-CLI discovery were checked without connecting WhatsApp. A subsequent real CPU smoke check used the owner's existing `ggml-large-v3-turbo-q5_0.bin` with the source transcriber and installed CLI: five seconds of bundled public-domain speech produced the expected opening phrase in 32.3 seconds. Model metadata remained unchanged; no model was downloaded and no WhatsApp state was accessed. This single fixture does not establish general recognition quality, long-audio performance, Windows/ARM behavior or new artifact qualification. Service deployment and other model/platform combinations require separate checks. The prerelease targets the `next` tag; it is not a stable-support commitment.
+
+### Pi 1.4.0 alignment
+
+The SDK, AI and TUI development dependencies and their Pi dependencies use version 1.4.0. Runtime peers are still supplied by Pi. A clean `npm ci --ignore-scripts --legacy-peer-deps --no-audit --no-fund` reproduced the lock without changing it or building native tools/downloading models. Validation of that dependency update passed 515 tests/53 files, lint and typecheck on macOS, including real SDK policy/input/image ownership checks with provider requests blocked. Isolated Pi startup, session replacement and package-discovery checks also passed. Those results cover the dependency update, not later source changes or other platforms.
+
+### Latest audit refresh
+
+The 2026-10-24 publication-review refresh with Pi 1.4.0 still reports **0 production findings**, but **2 affected packages in the full tree: one high and one moderate**. The development SDK cohort is **1.4.0**; the recorded host assessment also used Pi **1.4.0**, pinning `undici@8.10.2`. That alignment did not remove the Undici findings. The later Edge-update production-only audit remains clean, but is not a fresh full-tree or installed-host reassessment.
+
+The current Undici record includes three advisories, all patched at **8.12.2**:
+
+- Moderate: [EventSource parser memory exhaustion](https://github.com/advisories/GHSA-4qv8-2p9j-2685).
+- Moderate: [SRI algorithm-token validation](https://github.com/advisories/GHSA-f72v-6w45-q472).
+- High: [unhandled errors with excessive content-encodings](https://github.com/advisories/GHSA-xjj6-f33q-929c), newly observed in this refresh.
+
+The package-level count is not the advisory count. Installed Pi 1.4.0 also contains bundled Undici modules in its CLI chunks. Replacing a nested dependency or applying a repo override does not rewrite those bundles or certify their patched provenance; a complete host fix needs an upstream patched/rebuilt release or a separately reviewed rebuild. Do not treat a clean overridden dependency graph as proof that embedded runtime code was replaced.
+
+**Remediation: wait for a patched Pi release.** The development dependencies use Pi 1.4.0; no Undici override, audit suppression or forced fix has been applied. npm's proposed SDK downgrade to 0.75.3 is not accepted: it would abandon the characterized integration. Reassess the remaining findings and rerun validation when Pi updates its dependency and bundles; waiting does not mean the current host is certified unaffected. Production-only extension auditing also excludes host-supplied SDK peers, so it does not certify the host SDK as unaffected. Refresh the host/development dependency assessment and final artifacts before release; the earlier zero-finding audit results are historical, not a current clean full-tree claim.

package/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Copyright (c) 2026 José Antonio Galiano Sandoval
+Copyright (c) Rapha Castelloes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

package/LICENSING.md

@@ -0,0 +1,21 @@
+# Licensing and attribution
+
+This maintained continuation is licensed under the [MIT License](LICENSE).
+
+## Basis and notices
+
+- Upstream commit `49adbc3` and the [upstream package, version 1.0.70](README.md#upstream-license-evidence), both declare MIT and identify Rapha as author.
+- The owner explicitly accepted that upstream declaration as the licensing basis for this continuation. The earlier absence of a separate upstream license file is no longer a release blocker.
+- `LICENSE` includes the owner's supplied 2026 notice for José Antonio Galiano Sandoval and a yearless notice for Rapha Castelloes. No unverified upstream year range is asserted.
+- Original history and attribution are preserved. The new notice does not claim ownership of all inherited work.
+- Dependencies and third-party components retain their own licenses and notices; the fork's MIT license does not replace those obligations.
+
+## Advisory upstream inquiry
+
+[Upstream issue #17](README.md#upstream-license-evidence) remains a request for any preferred original notice. It is advisory, not a prerequisite for using the declared MIT license. No upstream confirmation is claimed; any authoritative notice supplied later can be incorporated.
+
+This owner decision supersedes the earlier choice to wait for upstream clarification.
+
+## Publication boundaries
+
+The maintainer controls publication of `whatsapp-ng` and its prerelease tags. The MIT license permits use of the code; it does not grant access to maintainer accounts or authority to publish under the project's package identity.

package/README.md

@@ -1,3 +1,234 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://upload.wikimedia.org/wikipedia/commons/6/6b/WhatsApp.svg" alt="WhatsApp Logo" width="100">
+</p>
 
-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.
+# whatsapp-ng
+
+Use WhatsApp to talk to your [Pi](https://pi.dev) agent: send tasks, share files and voice notes, receive answers, and control the running session from your phone.
+
+## Features
+
+- **Manual WhatsApp connection:** pair by QR code, keep the saved login, and reconnect when needed or on startup.
+- **Allowed contacts:** choose who can interact with Pi; add names and aliases, inspect ignored senders, and print contact identifiers from the menu.
+- **Allowed groups:** allow specific group JIDs with aliases, then choose mention/reply triggers or all-message handling. Other groups do not trigger the agent.
+- **Recents and history:** browse conversations offline, inspect message details and send native quoted replies.
+- **Reliable messaging:** stable message IDs, bounded pre-transmission retries and explicit uncertain outcomes instead of blind resends.
+- **Terminal menu:** manage connection, contacts, groups, history, reply delivery, voice settings and the authorized phone owner through `/whatsapp`.
+- **Phone controls:** select models and thinking levels, stop work, compact context or start a new shared session from the owner's phone.
+- **Group-only mode:** bind Pi to one WhatsApp group with `--whatsapp-group <jid>`.
+- **Media support:**
+  - **Images:** forward incoming WhatsApp images to Pi for analysis with a vision-capable model.
+  - **Audio transcription:** use Whisper.cpp/CrispASR locally, a compatible native Whisper addon, or a configured transcription API. FFmpeg first converts voice notes to 16 kHz mono WAV.
+  - **Documents:** save documents for agent access, with bounded text previews for readable PDFs and optional local OCR for scans.
+  - **Outgoing attachments:** explicitly send documents, images, audio, voice notes and video, with optional native quotes.
+- **Spoken replies:** opt into text, voice, voice + text or input-mirroring output, with per-chat preferences and separate group consent.
+
+**All allowed chats share one Pi session and its context. Only allow people and groups you trust with that shared access.**
+
+## Install and connect
+
+With Pi already installed, install the stable channel:
+
+```bash
+pi install npm:whatsapp-ng@latest
+```
+
+The `1.1.0` release line includes saved startup preferences and fuzzy `/model` search. Check the actual channel version with `npm view whatsapp-ng@latest version`; `next` is independent and may still point to an older prerelease. Stable versioning does not imply an SLA, all-platform qualification or guaranteed npm/Pi catalog indexing. See the [security and qualification limits](SECURITY.md).
+
+Restart Pi, then:
+
+1. Open `/whatsapp` → **Connection** → **Connect WhatsApp** and scan the QR code.
+2. Add contacts under **Chats / Owner → Allowed Contacts**, or groups under **Groups → Allowed Groups**.
+3. Send a message from an allowed chat. Pi answers in that conversation.
+
+The login is saved. To reconnect automatically without a launch flag, open **Connection → Auto-connect on startup → Enabled**. This saves `autoConnect: true` in the extension's `config.json`; the default is disabled. Only the literal boolean `true` enables it.
+
+The saved preference applies to **TUI and RPC sessions using the same profile**, across workspaces, including `/reload` and `/new`. Any RPC process that loads the extension, including an extension-enabled subagent, follows that preference; print/JSON runs need an explicit online flag. Only one Pi process can own the profile: preference-based startup skips an occupied/unverified profile lock with one notice rather than repeated retries.
+
+Changing the preference does not immediately connect or disconnect WhatsApp. Existing saved credentials are required; first-time pairing still uses **Connect WhatsApp**. Explicit **Off** survives reload/session changes in the current process even with auto-connect enabled; it does not disable other Pi processes. A fresh TUI/RPC process follows the shared saved preference. Cooperative config writes preserve newer auto-connect selections made by another updated Pi process.
+
+The launch flag remains an explicit auto-connect request, even if the saved preference is disabled:
+
+```bash
+pi --whatsapp-ng-online
+```
+
+<a id="auth-adoption-and-recovery"></a>
+
+Use `--whatsapp-group <jid>` to bind the extension to one group. Stop any other instance using the same WhatsApp profile before connecting. For an existing installation with an older data directory, use the [migration guide](docs/reference.md#migration-and-recovery) rather than pairing again or deleting its data.
+
+<a id="pdf-previews-and-ocr"></a>
+
+## Optional system tools
+
+Text chat needs no additional media tools. Install the tools below only for the features you use, following their instructions for **macOS, Linux or Windows**. System executables and model/language data are not bundled; availability depends on the tool's supported platforms.
+
+| Tool | Needed for |
+| --- | --- |
+| [FFmpeg](https://ffmpeg.org/download.html) | Audio conversion, video processing and outgoing image/video preparation. Required for voice-note transcription and spoken replies, even with a remote speech API. |
+| [Whisper.cpp](https://github.com/ggml-org/whisper.cpp) with a GGML model | Local transcription through `whisper-cli`. Not needed for remote transcription or when using a compatible native addon. |
+| [CrispASR](docs/crispasr.md) with a compatible model | Optional beta/experimental local speech toolkit: a Whisper-compatible transcription CLI, or a separately managed STT/TTS server with broader model choices. |
+| [Tesseract](https://tesseract-ocr.github.io/tessdoc/Installation.html) with language data | Local OCR of scanned PDFs. PDFs with readable text do not require OCR. |
+
+For local CLI transcription, choose Whisper.cpp **or** CrispASR; you do not need both. The included `whisper-cpp-node` addon offers an alternative backend on compatible **macOS/Windows** builds, not Linux. It includes its own Whisper engine and still needs a model, but no separate CLI. Setting an explicit CLI path disables native-addon fallback.
+
+Make executables available on `PATH` to the process running Pi, or set `FFMPEG_PATH`, `WHISPER_CLI_PATH` or `CRISPASR_CLI_PATH` for an executable elsewhere. Point `WHISPER_MODEL_PATH` or `CRISPASR_MODEL_PATH` to your existing model. Services may have a different environment from your terminal. See [PDF/OCR setup and manual checks](docs/reference.md#pdf-previews-and-ocr) for scanned documents.
+
+## Audio transcription
+
+Choose local transcription or a compatible remote API. FFmpeg is required for both.
+
+### Local
+
+Install `whisper-cli` and point `WHISPER_MODEL_PATH` to your existing GGML model. Set `WHISPER_LANGUAGE` to `auto` or a language code such as `en` or `es` in the environment that launches Pi.
+
+Local transcription runs on CPU. Without a model override, the base model downloads on first use. When neither CLI is available and no explicit CLI path is set, compatible macOS/Windows builds can use the included native addon instead; Linux requires a CLI.
+
+[CrispASR](docs/crispasr.md) is another supported local CLI/server option. See the [speech reference](docs/reference.md#speech-configuration) for discovery order and environment variables.
+
+### Local CrispASR speech servers (beta)
+
+[CrispASR](https://github.com/CrispStrobe/CrispASR) is a unified C++ speech toolkit, originally based on Whisper.cpp, with many STT and TTS model families and model auto-download/cache options. Treat this optional setup as **beta/experimental**: it is a fast-moving 0.x project, and model/build compatibility needs checking. STT choices include Whisper, Parakeet, Canary and Qwen3-ASR; TTS choices include Kokoro, Piper, Qwen3-TTS and OmniVoice.
+
+We added **`http://` support for STT/TTS endpoints** to open the way for local servers such as CrispASR, without needing TLS just for localhost. Loopback HTTP is allowed; non-loopback HTTP requires an explicit launch-environment opt-in and is unencrypted. See the [setup, model examples and transport safeguards](docs/crispasr.md).
+
+CrispASR provides **Windows, Linux and macOS** builds, with **CPU, NVIDIA CUDA, Apple Metal and Vulkan** execution options depending on the build, hardware and model—not every combination on every OS. Multilingual Whisper covers **99 STT languages**, while upstream OmniVoice advertises **600+ TTS languages**; coverage is model/voice-specific, not a promise that every engine supports all languages. These are upstream capabilities, not a full `whatsapp-ng` validation matrix. Our direct CLI path remains CPU-only and requires a compatible Whisper GGML model; use a separate compatible HTTP server for other model families or GPU acceleration. OmniVoice's reference-audio HTTP flow still has [additional integration limits](docs/crispasr.md#multilingual-and-omnivoice-limits).
+
+The guide explicitly downloads `ggml-large-v3-turbo-q5_0.bin` using CrispASR's **`--hf-repo` / `--hf-file`** selectors rather than accepting a base-model default. **It is an example: choose the model that fits your languages, accuracy, memory and latency needs.**
+
+### Remote
+
+Use any provider or self-hosted server implementing the OpenAI-compatible **`/audio/transcriptions`** API. This is not tied to Groq or to Pi's model provider; chat API compatibility alone does not guarantee transcription support.
+
+From a verified local terminal/RPC request or the configured WhatsApp owner's chat, ask Pi to call `configure_wa_stt` with your provider's base URL, transcription model and API-key environment-variable name. Other allowed contacts cannot change or clear these settings. Replace these placeholders:
+
+```json
+{
+  "sttEndpoint": "https://speech.example.com/v1",
+  "sttModel": "your-transcription-model",
+  "sttEnv": "STT_API_KEY"
+}
+```
+
+Set `STT_API_KEY` securely in the environment that launches Pi, then restart Pi. **Pass only the variable's name to the tool, never the key itself.** Optional `sttLanguage` selects a language; omit it or use `auto` for server detection.
+
+Configuring remote transcription authorizes sending admitted voice-note audio to that endpoint. The provider's billing and retention policies apply. Failures are reported without silently switching providers or falling back to local transcription.
+
+Updates preserve omitted settings. Call `configure_wa_stt({})` to return to local transcription. See [endpoint and request details](docs/reference.md#remote-speech-endpoints) for local servers and transport limits.
+
+## Speech replies (opt-in)
+
+Open `/whatsapp` → **Voice** to choose a speech backend, voice, speed and reply mode:
+
+| Mode | Output |
+| --- | --- |
+| Text | Text only. |
+| Voice | A voice note when the answer is suitable for speech. |
+| Voice + text | Both formats. |
+| Mirror | Voice for verified audio input; text otherwise. |
+
+Backends include Fish, OpenAI-compatible speech APIs and the unofficial Microsoft Edge speech service. A compatible [CrispASR TTS server](docs/crispasr.md#tts-server), such as the Kokoro example, can provide local synthesis through the same endpoint client. Edge requires no configured API key but is an online service, not offline synthesis. The transcription and speech backends are independent.
+
+Speech is disabled until you approve its destination in the terminal Voice menu. Groups need separate opt-in. Changing the endpoint requires new approval; configuring a backend with `configure_wa_tts` does not enable speech or grant consent.
+
+Voice settings also let you pause automatic replies for individual chats and send a confirmed preview. Speech uses a separate plain-text copy: emphasis markers, headings, bullets and escaped quotes are cleaned up; short labels such as `config.json` can be spoken normally. Ordinary approximate values such as “~5 minutes” remain eligible. Voice and audio Mirror keep an answer as text when speaking its link label would omit the address. Voice + text speaks link labels only if the full text send succeeds. The displayed answer is unchanged. Long answers, code/command-like snippets and tables stay as complete text. See the [speech reference](docs/reference.md#speech-replies) for backend fields and failure behavior.
+
+<a id="settings-off-and-diagnostic-privacy"></a>
+
+## Chats and replies
+
+The `/whatsapp` menu groups settings into **Connection**, **Chats / Owner**, **Replies**, **Voice**, **Groups** and **Advanced**. See [Off behavior and diagnostic privacy](docs/reference.md#off-and-diagnostics) for shutdown and log retention.
+
+- **Contacts:** add phone numbers in `+E164` format; use aliases to identify them.
+- **Groups:** add the group JID. By default, the agent responds to actual WhatsApp mentions of its account or replies to that account's messages. Change this under **Groups → Group replies**.
+- **Recents:** browse conversations, inspect messages, reply manually or allow a new chat.
+- **Replies:** choose whether attachments are followed by a final explanation. Optional elapsed/tool-count stats, file-path summaries, interim text and live activity are off by default.
+- **Optional outputs:** explicitly approve individual tools whose image results may be shared, or forward future terminal answers to the private owner. These are off by default.
+- **Owner:** explicitly choose the person authorized to use phone controls. An allowed contact or paired device is not automatically an owner.
+
+WhatsApp `@lid` identifiers are not phone numbers. Select known conversations in the menu rather than constructing a recipient from displayed digits.
+
+## Phone controls
+
+Allowed people can use `/help` and `/status`. State-changing commands require the configured owner and affect the shared Pi session.
+
+| Command | Action |
+| --- | --- |
+| `/model [provider/model or search]` | Select an exact authenticated model, or search providers/models and confirm a match. |
+| `/think [level]` | Change thinking level. |
+| `/stop`, `/abort` | Stop current work and withdraw queued WhatsApp input. |
+| `/compact [focus]` | Compact session context. |
+| `/new` | Confirm a new Pi session, keeping login, settings and history. |
+| `/voice [text\|voice\|both\|mirror]` | Change this chat's mode within existing speech approvals. |
+| `/replies` | Change reply delivery and optional reporting. |
+| `/off` | Confirm WhatsApp shutdown without logging out. Re-enable from the terminal Connection menu. |
+| `/quit` | Confirm graceful Pi shutdown. |
+
+Use `/model` to browse, `/model anthropic` to filter by provider, or `/model anthropic/opus` (also `opus anthropic`) for case-insensitive fuzzy matching across provider/model identifiers. `/model DeepSeek`, `/model Deepseek` and `/model deepseek` show matching models across all authenticated providers, with provider/model labels kept distinct. Search results require a numbered selection even when only one matches; an exact `provider/model` still selects directly. Previous/next pages retain the search. Only currently authenticated models are offered; no match leaves the current model unchanged. Private filesystem identifiers stay redacted and are reachable through browsing, not fuzzy search.
+
+Menus use numbered replies. Group selections must quote the menu. Native polls are experimental and require `--whatsapp-ng-native-polls`. Configuration changes require idle Pi; stop active work explicitly rather than interrupting it through a settings change.
+
+## LLM-Callable Tools
+
+The extension registers these tools for Pi's agent:
+
+| Tool | Direction | Description |
+| --- | --- | --- |
+| `send_wa_message` | Outbound | Send text to a contact/group, optionally quoting a retained message. Omit `jid` only when the current turn has one owning conversation; idle manual calls retain the last-conversation/operator fallback. |
+| `send_wa_media` | Outbound | Explicitly send a local document, image, audio file, voice note or video, with optional caption and native quote. Uses the same recipient-ownership rules as text. |
+| `send_reaction` | Outbound | React to an unambiguous retained message. Optional `fromMe` and `participant` fields disambiguate its key; compound emoji are supported. |
+| `list_wa_conversations` | Read-only | List local recent conversations. Supports `onlyIncoming`, `onlyAllowed`, `limit` and local `scope`; returns available scope IDs. |
+| `get_wa_conversation_history` | Read-only | Read messages for `senderNumber` (`+E164`, raw phone digits or a JID). Supports `limit`, local `scope` and opaque `cursor` / `nextCursor` pagination. |
+| `check_wa_new_messages` | Read-only | List conversations whose latest message is incoming. Supports `sinceTimestamp` (milliseconds since epoch) and local `scope`. |
+| `request_wa_history` | Network request / local status | `{mode:"request",jid,count?}` explicitly requests up to 100 older messages for an allowed connected chat; `{mode:"status",requestId?}` reads retained request status locally. |
+| `configure_wa_stt` | Guarded configuration | Owner/local-only: set or update `sttEndpoint`, `sttModel`, `sttEnv` and optional `sttLanguage`. Pass the key's environment-variable name, never its value; `{}` selects local transcription. |
+| `configure_wa_tts` | Guarded configuration | Update speech backend settings for an authorized local/owner request. Does not grant consent, enable speech or synthesize immediately. |
+
+File uploads must be explicit, at most **25 MiB**, and under the current workspace or extension media directory. Mentioning a file path does not upload it. Native quotes require a retained, unambiguous message in the same chat.
+
+The three read-only inbox tools use the selected local archive under `~/.pi/agent/extensions/whatsapp-ng/archive/`. They work offline, never fetch network history and do not mark messages as read. The list/history tools default to, and cap at, 20 items; `check_wa_new_messages` returns all matching conversations. Only an explicit `request_wa_history` request fetches older messages; availability depends on WhatsApp and the linked devices.
+
+## Data and privacy
+
+Settings, login, history and downloaded media live under `~/.pi/agent/extensions/whatsapp-ng/`. Recents remain readable offline. Archive retention is bounded to 1,000 messages per conversation, 30 days and 100 MiB per account partition; it does not erase Pi transcripts, logs or downloaded media.
+
+- Allowed chats share model context; routing is not privacy isolation.
+- Images may reach Pi's vision model. Remote transcription and speech send content to the selected service.
+- A successful send means API acceptance, not proof of delivery or reading. An unknown outcome may still arrive; do not automatically resend it.
+- **Connection → Turn WhatsApp off** (or `/off`) keeps your login. **Advanced → Logoff (Delete Session)** resets the current authentication profile. Do not delete login or history to resolve a lock.
+- This uses an unofficial WhatsApp transport. Protocol changes or account policies can disrupt it.
+
+See the [operating reference](docs/reference.md) for migration, recovery, media formats, history and diagnostics. [Security reports](SECURITY.md) must not include credentials or private conversation dumps.
+
+## Development
+
+The development baseline is Node 26.x and Pi 1.4.0.
+
+```bash
+git clone https://github.com/jagaliano/whatsapp-ng.git
+cd whatsapp-ng
+npm ci --ignore-scripts --legacy-peer-deps --no-audit --no-fund
+npm test
+npm run lint
+npm run typecheck
+pi --no-extensions -e ./whatsapp-ng.ts
+```
+
+Maintainers can use the [release guide](docs/releases.md) for explicit local version bumps, validated tarball preparation and separately confirmed publication. PR/main CI and a default-off, environment-gated tag-triggered OIDC workflow are provided; npm requires a first manual package publication before trusted publishing can be configured. RC1 is published; the working version is `1.1.0-rc.2`. Preparing a candidate does not bump or publish it.
+
+Use a disposable HOME/Pi agent directory and credential-free environment for validation; the isolated setup in `scripts/release.mjs` is the reference. A deliberate source launch with your normal HOME shares saved settings/auth and may auto-connect. Do not run a second same-profile owner.
+
+System tools must be installed separately. Add `--verbose` for extension diagnostics, not message bodies or protocol-key traces. See [dependencies and platform checks](DEPENDENCIES.md), the source-only [manual acceptance guide](https://github.com/jagaliano/whatsapp-ng/blob/main/tests/manual/prerelease-acceptance.md), and [design records](https://github.com/jagaliano/whatsapp-ng/tree/main/specs). Package search is not exact availability: see [discovery checks](docs/releases.md#package-discovery).
+
+## Support and license
+
+Report bugs through [GitHub issues](https://github.com/jagaliano/whatsapp-ng/issues). See the [changelog](CHANGELOG.md) and [MIT license](LICENSE).
+
+<a id="fork-and-legacy-names"></a>
+
+Based on [Rapha Castelloes' original project](https://github.com/RaphaCastelloes/whatsapp-pi), maintained by José Antonio Galiano Sandoval. Older names and paths are listed in the [migration reference](docs/reference.md#historical-identifiers).
+
+<a id="upstream-license-evidence"></a>
+Original license evidence refers to the [upstream npm package at 1.0.70](https://www.npmjs.com/package/whatsapp-pi/v/1.0.70) and the advisory [upstream notice inquiry](https://github.com/RaphaCastelloes/whatsapp-pi/issues/17); no new upstream response is claimed.
+
+The local speech overview is adapted from [CrispStrobe/CrispASR](https://github.com/CrispStrobe/CrispASR) and its contributors' documentation; see the [guide's credits and upstream references](docs/crispasr.md#credits-and-upstream-references).