@abot-ai/socket 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dor Shitrit
+
+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/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# ABot Socket
 
-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 self-hosted chat relay between a native ABot client and your ABot Runtime
+instances. You operate the relay, pair your devices, and connect your own
+computers. The relay does not require an ABot-hosted account or backend.
+
+The source is available under the [MIT license](LICENSE). Install the versioned
+`@abot-ai/socket` package from npm, or build a local tarball from source.
+
+## Install and prepare
+
+Start with [Installation and first connection](docs/INSTALLATION.md), the consumer
+guide for installing the command, preparing a server, connecting a runtime and
+pairing the app by QR or manual entry.
+
+```sh
+npm install --global @abot-ai/socket@0.1.0
+abot-socket setup
+```
+
+The command requires Node.js 24 or later. Its terminal wizard creates private
+configuration/state and, on Linux, reviewable systemd/HTTPS proxy files. The
+operator supplies DNS, TLS, service activation and the runtime's bridge settings.
+Neither npm installation nor setup activates those services; no install hook runs.
+
+- [Installation](docs/INSTALLATION.md): wizard, defaults, runtime connection and pairing.
+- [Deployment](docs/DEPLOYMENT.md): explicit Linux service and HTTPS activation.
+- [Self-hosting](docs/SELF-HOSTING.md): configuration, operation and the proxy trust boundary.
+- [Protocol](docs/PROTOCOL.md): pairing API and existing runtime bridge.
+- [Security](docs/SECURITY.md): authentication, trust boundaries and limitations.
+- [Migration](docs/MIGRATION.md): moving an existing installation deliberately.
+- [App review preparation](docs/APP-REVIEW.md): a separate review installation,
+  protected renewable pairing access and the remaining deployment/device checks.
+
+`abot-socket start` runs the relay in the foreground. `abot-socket doctor` checks
+public HTTPS relay health without credentials; runtime readiness is verified in
+the paired app. `abot-socket pair` creates fresh one-time pairing details and
+displays a private QR in a capable terminal. Scanner-enabled clients can scan it
+and confirm the server address; manual entry remains available.
+
+## Scope
+
+One installation represents one owner, with up to 10 paired devices and 16
+runtimes. Pairing requires a six-digit code and a separate random temporary key
+created locally by the operator. Both expire after five minutes or one successful
+use. There is no email delivery or central authentication provider.
+
+ABot App scans the private pairing QR and asks you to confirm its server address.
+Manual code, HTTPS URL and temporary-key entry remains available. The app receives
+its own device credential; never copy the runtime credential into the app.
+
+The relay supports chat, steering, observed tool approvals, runtime history,
+model selection and attachments through the existing bridge. It does not execute
+models or store conversation history. Runtime configuration uses the existing
+bridge adapter; runtime source changes are not part of this project.
+
+Device sessions last up to 30 days without sliding renewal and survive restarts
+in a private SQLite database. Operators can list and revoke devices locally.
+The device-scoped notification inbox records completion, failure and observed
+approval requests initiated through this relay. Push delivery is off by default;
+operators may configure their own FCM sender or an explicitly trusted ABot push
+gateway. Notifications are generic by default. An optional per-device encrypted
+preview can show a bounded final-answer excerpt; the gateway/provider never gets
+the preview key or plaintext. The app remains usable without push.
+Cancellation, durable approval restoration and recovery of events missed while
+the relay/runtime is disconnected are not implemented. The relay host is trusted and can read routed content;
+transport encryption is not end-to-end encryption.
+
+Notification metadata and pending deliveries share the private SQLite state.
+Upgrading migrates schema v1 or v2 to v3 without replacing paired devices. Back up the
+private state before deploying: an older binary cannot open the new schema.
+See [notification protocol and delivery](docs/PROTOCOL.md#notifications).
+
+## Source layout
+
+`bin/abot-socket.mjs` is the installed entry point; `src/main.mjs` starts a
+configured relay. The source modules are grouped by responsibility:
+
+| Directory | Owns |
+| --- | --- |
+| `src/cli/`, `src/setup/` | Command dispatch, operator output and new-installation preparation. |
+| `src/config/`, `src/deployment/` | Private configuration validation and reviewable service/proxy plans. |
+| `src/auth/`, `src/pairing/` | Durable device credentials, revocation and one-use pairing/QR. |
+| `src/transport/`, `src/protocol/` | HTTP/WebSocket boundary, limits and allowed client message shapes. |
+| `src/relay/` | Runtime routing, correlations, request ownership and session operations. |
+| `src/notifications/` | Device inbox/outbox, delivery adapters, gateway and encrypted previews. |
+| `src/review/` | Separate app-review installation and protected pairing portal. |
+
+## Local validation
+
+From the development checkout, install the locked dependencies and run the local tests:
+
+```sh
+npm ci --omit=optional --ignore-scripts
+npm test
+```
+
+Runtime dependencies are pinned `ws` for transport and `qrcode-generator` for
+local pairing QR generation; the latter has no runtime dependencies. Source tests and
+package-verification scripts are not shipped inside the npm consumer package.
+
+To inspect the exact distribution files before installing a source-built package:
+
+```sh
+npm pack --ignore-scripts --json > /tmp/abot-socket-pack.json
+npm run check-package -- /tmp/abot-socket-pack.json
+```
+
+The tarball contains an explicit allowlist of runtime modules and consumer docs.
+Keep credentials, machine configuration, state, logs and private support reports
+outside the checkout. Never attach pairing codes or QR images to a public issue.
+
+Tests use dummy identities and mock runtime peers. The transport tests
+open loopback HTTP and WebSocket listeners; they do not connect to a live runtime
+or send email. Run them only in an environment permitted for that local traffic.
+Passing these tests does not establish proxy correctness,
+or compatibility with a separately installed client/runtime version.

package/bin/abot-socket.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+// Check before loading node:sqlite so unsupported Node versions get a useful error.
+if (Number(process.versions.node.split('.')[0]) < 24) {
+  console.error('ABot Socket requires Node.js 24 or later. Install a supported Node.js version first.');
+  process.exitCode = 1;
+} else {
+  try {
+    const { runEntry } = await import('../src/cli/cli-entry.mjs');
+    process.exitCode = await runEntry(process.argv.slice(2));
+  } catch {
+    console.error('ABot Socket could not complete the command. Check the local configuration and installation.');
+    process.exitCode = 1;
+  }
+}

package/config.example.json

@@ -0,0 +1,14 @@
+{
+  "publicOrigin": "https://socket.example.invalid",
+  "port": 8788,
+  "runtimeGrants": [
+    {
+      "runtimeId": "workstation",
+      "tokenSha256": "REPLACE_WITH_SHA256_OF_A_NEW_RUNTIME_TOKEN",
+      "allowedModes": [
+        "ask"
+      ]
+    }
+  ],
+  "stateDirectory": "./state"
+}

package/docs/APP-REVIEW.md

@@ -0,0 +1,184 @@
+# Preparing a dedicated app-review installation
+
+This guide prepares renewable access to an isolated review Socket using the
+ordinary app pairing protocol. It does not deploy services, configure a model,
+publish a package or establish App Store readiness. Actual hosting and signed
+device checks remain required; installing the package does not complete them.
+
+Apple requests full app access, necessary resources such as pairing QR codes,
+and backend services that remain live during review. See the current
+[App Review Guidelines](https://developer.apple.com/app-store/review/guidelines/#before-you-submit),
+including sections 2.1 and 2.3.1. Reviewers should not have to contact the developer
+for each new five-minute code.
+
+## 1. Prepare a fresh installation
+
+Use Node.js 24 or later and an explicitly installed package version. Choose a
+new, private output directory outside source control. Its parent must already
+exist; the output directory must not. Run setup as the account that will own and
+run both processes; the private files are deliberately rejected for another owner.
+Replace these reserved example origins
+with the dedicated HTTPS origins you intend to operate:
+
+```sh
+abot-socket review-setup \
+  --output /srv/abot-review \
+  --origin https://demo.example.test \
+  --runtime-id review-demo \
+  --review-origin https://review.example.test \
+  --port 8788 \
+  --review-port 8789
+```
+
+The Socket and reviewer portal require distinct HTTPS origins and listener
+ports. The default ports are 8788 and 8789. Pick unused ports if other services
+share the host. These examples do not authorize or perform changes to those
+services.
+
+The command creates a separate installation rather than attaching review access
+to an existing Socket:
+
+| Output | Purpose |
+| --- | --- |
+| `config.json` | Configuration for the dedicated review Socket. |
+| `runtime-connection.json` | Private bridge URL, runtime identity and runtime secret. |
+| `state/` | Dedicated Socket database, ownership and review-installation metadata. |
+| `review-portal.json` | Private portal configuration bound to this review installation. |
+| `review-access.txt` | Portal URL, reviewer username and generated stable password. |
+
+The directory is private and the credential/configuration files use mode 0600.
+Console output identifies the files; do not copy their secret contents into
+logs, source, screenshots or a public support page. Keep this installation's
+state separate from production and from any push gateway database.
+
+The portal verifies its fresh-installation marker and database owner as well as
+the bound Socket identity: origin, state directory and runtime credentials.
+Changing those identity fields makes the binding invalid. Do not edit a marker
+or credential hash to attach the portal to another installation. This workflow
+is not a migration or a generic pairing endpoint for an existing personal server.
+
+## 2. Configure the review runtime and optional push
+
+Privately transfer `runtime-connection.json` only to the dedicated runtime host.
+Use that runtime's existing bridge configuration to connect it; never enter the
+runtime secret into the app or disclose it to reviewers. Configure a working
+model and benign sample resources on that runtime. No runtime source changes
+are required by this setup.
+
+Provide enough access to exercise the app's normal features while isolating the
+review workspace from personal files, accounts, credentials and production
+administration. Do not rely on a home Mac remaining awake or on a developer
+manually maintaining the connection during review. Hosting, model capacity and
+availability are operator responsibilities.
+
+The app uses the same submitted binary and standard behavior. There is no
+reviewer-specific client mode, fake chat implementation or hidden feature switch.
+Document the normal model/tool capabilities offered by this workspace.
+
+Remote push remains disabled unless configured deliberately. If the submitted
+app offers push, configure the dedicated Socket's appropriate delivery mode and
+provider/gateway through the normal configuration described in
+[Self-hosting](SELF-HOSTING.md) and [Deployment](DEPLOYMENT.md#optional-notification-gateway).
+Keep sender credentials and gateway configuration private. Permitted operational
+changes such as notification delivery and allowed permission modes do not replace
+the installation's bound identity. Restart the affected process after a deliberate
+configuration change, then verify the complete signed-device flow. Setup does not
+prove push delivery or provision a sender service.
+
+## 3. Prepare separate HTTPS forwarding
+
+Run each process behind its own HTTPS origin, forwarding only to the corresponding
+loopback listener. Use valid certificates and separate proxy routes. Keep the
+relay's WebSocket upgrade support; the reviewer portal is a separate HTTP service.
+
+The direct HTTPS proxy must:
+
+- Preserve `Host` for the intended public origin, and pass `Authorization` and
+  `Origin` without rewriting their meaning.
+- Remove untrusted incoming `X-Forwarded-Proto` and `X-Socket-Client-IP`, then set
+  the verified HTTPS protocol and the actual connection client's IP itself.
+  Never trust a client-supplied forwarding header.
+- Disable caching for the reviewer portal, including authenticated pages and
+  QR responses. Do not enable CDN caching for this origin.
+- Disable proxy access/body/header logging and tracing for the reviewer portal.
+  Ensure upstream/CDN logging cannot record credentials, generated pairing
+  bundles or responses. Do not introduce secret logging in the relay either.
+
+See [the proxy trust boundary](SELF-HOSTING.md#3-configure-https-and-the-proxy-boundary).
+Additional proxies or a CDN require a separately validated trusted-peer policy;
+copying their incoming IP headers is not sufficient. Configuring DNS, TLS,
+firewalls, service users and process supervision is separate deployment work.
+No setup command activates or reloads those components.
+
+## 4. Start and verify deliberately
+
+After the hosting configuration has been reviewed, run the two processes with
+the same Socket configuration path, in separate supervised processes or terminals:
+
+```sh
+abot-socket start --config /srv/abot-review/config.json
+```
+
+```sh
+abot-socket review-portal --config /srv/abot-review/config.json
+```
+
+The second command derives the fixed sibling `review-portal.json`; do not pass
+that file as the `--config` argument. Keep the separate portal origin and port
+chosen during setup.
+
+Open the protected `/review` webpage on the portal origin using the access
+details in `review-access.txt` (for example, `https://review.example.test/review`).
+Generate a fresh standard QR and pair the real app. The QR
+lasts five minutes and is single-use. Generating another QR replaces the pending
+one, while devices already paired successfully remain authorized.
+
+Display the webpage on another screen for camera scanning. A reviewer using one
+device can instead copy the displayed six-digit code, Socket URL and temporary
+pairing key into the app's normal manual flow. The QR is not an app-opening link.
+The app also requires the device's own passcode or biometric authentication;
+this is separate from the webpage's reviewer login and Socket pairing code.
+
+Put actual reviewer access details only in private App Review Information in
+App Store Connect. Keep the portal login usable throughout review and allow
+repeat pairing without developer intervention. Monitor capacity so additional
+review devices can pair; revoke only obsolete review devices deliberately.
+
+## 5. Readiness record
+
+Before submitting the app, verify and record:
+
+- Both public HTTPS origins, their proxy boundaries and the protected portal
+  work externally; no secret appears in caches or operational logs.
+- Fresh, expired, replaced and already-used pairing codes behave correctly.
+  Replacing a pending code leaves paired devices usable.
+- The intended runtime is online, the configured model completes real chat
+  requests, and history, attachments, tool activity and approvals work with the
+  submitted app. An HTTP health check proves neither runtime nor model readiness.
+- The runtime and review files are isolated from personal data, and availability
+  does not depend on a home computer or developer attendance.
+- Device authentication, background return, camera permissions and manual
+  pairing work on the actual supported Apple devices and signed build.
+- Any advertised push capability is configured and verified end to end,
+  including permission denial, background delivery and authenticated tap routing.
+- App privacy disclosures describe actual Socket, runtime, model-provider,
+  Firebase/APNs and gateway traffic. User-controlled hosting is not a substitute
+  for verifying those data flows.
+
+No deployment, live runtime/model test, notification send, account operation or
+submission is implied by this guide. Keep readiness evidence and actual access
+details outside the source repository.
+
+## 6. End or renew review access
+
+Keep both services and the runtime available until the review and any follow-up
+checks finish. Afterwards, stopping the portal prevents new reviewer pairings;
+it does not revoke devices that have already paired. Inspect those devices with
+`abot-socket devices --config /srv/abot-review/config.json` and revoke obsolete
+ones with `abot-socket revoke <device-id> --config /srv/abot-review/config.json`.
+Stop the dedicated Socket/runtime as well when the demo is no longer needed.
+
+The reviewer password remains stable until the installation is retired. If it
+needs replacement, prepare a new dedicated installation and replace the private
+review instructions; do not weaken checks or reuse a production configuration.
+Retiring or deleting actual hosted resources is a separate operator action.

package/docs/DEPLOYMENT.md

@@ -0,0 +1,124 @@
+# Preparing a Linux deployment
+
+The deployment command creates files for operator review. It does not install
+packages, enable services, reload a proxy, obtain certificates or change system
+configuration. The existing operating-system user and proxy remain your choice.
+Begin with [Installation](INSTALLATION.md) to install the package and
+prepare private state; this guide is the subsequent service/HTTPS step.
+
+After creating the private installation, prepare a plan on the Linux host where
+the package is persistently installed. Run this as the installation owner; the
+optional --user value must match that current unprivileged account:
+
+```sh
+abot-socket deployment --config /srv/abot/config.json \
+  --output /srv/abot/deployment-plan --user abot --proxy nginx \
+  --certificate /etc/tls/socket/fullchain.pem \
+  --private-key /etc/tls/socket/private.key
+```
+
+Use `--proxy apache` for Apache 2.4.47 or later. Use `--proxy none` if HTTPS is
+already configured; certificate/key arguments are then unnecessary. The output
+directory must not exist. Its parent must exist. Generated files use mode 0600
+inside a new 0700 directory. No certificate contents or pairing secrets are read
+or copied into the plan.
+
+## Review the service
+
+The systemd unit runs the installed Node executable and CLI directly in the
+foreground. It uses the specified unprivileged user, a 0077 umask, restart on
+failure, and limits persistent writes to the configured state directory.
+
+The named user must already exist and own the private configuration/state. The
+state directory must exist with mode 0700 and its files must be private. It must
+be outside temporary filesystem paths. The user also needs access to the Node
+and package paths; a root-only Node installation cannot serve an unprivileged
+application. Do not use an `npx` cache installation for a persistent service.
+
+The plan contains exact executable/configuration paths. Regenerate it after
+changing those locations. Paths with spaces are quoted; percent signs are escaped
+for systemd. Other shell/proxy metacharacters are rejected rather than interpreted.
+See [systemd command syntax](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html).
+
+## Review HTTPS forwarding
+
+The proxy examples require existing certificate/key files and a DNS hostname.
+They preserve the incoming Host authority, including a non-default port, so the
+relay can reject unknown authorities. They preserve Origin and Authorization,
+support WebSocket upgrades and overwrite the trusted client-IP/protocol headers.
+The generated proxy plans cap request bodies at 4 KiB. Application limits differ
+by route: push registration accepts up to 8 KiB and preview-key registration up
+to 512 bytes. See [HTTP limits](PROTOCOL.md#http); a stricter proxy limit wins.
+If an installation needs the full registration limit, review that proxy setting
+explicitly while retaining the application's route-specific limits.
+
+The nginx example belongs in the `http` context and uses its connection address.
+Review inherited real-IP settings before use. The Apache example uses
+`CONN_REMOTE_ADDR`, the actual connection peer, and requires `ssl`, `headers`,
+`proxy` and `proxy_http`. Apache also needs an existing Listen directive for the
+HTTPS port; the plan does not add a potentially duplicate listener.
+
+These examples describe a direct Internet-to-local-proxy-to-relay connection.
+CDN or additional proxy chains need a separate trusted-peer policy. Keep pairing
+details, request bodies and Authorization headers out of inherited logging rules.
+
+References: [nginx WebSocket proxying](https://nginx.org/en/docs/http/websocket.html),
+[Apache WebSocket upgrade](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html),
+[Apache header handling](https://httpd.apache.org/docs/2.4/mod/mod_headers.html),
+[Apache connection address](https://httpd.apache.org/docs/current/en/expr.html).
+
+## Apply explicitly
+
+`DEPLOYMENT.txt` lists commands to run manually from the generated directory.
+Inspect existing destination files before copying anything; these are new-install
+examples, not an overwrite or migration tool. Execute one command at a time and
+stop on a failure. Check the proxy configuration before reloading it. The Apache
+command examples use Debian/Ubuntu conventions; other distributions differ.
+
+The service starts separately from the HTTPS proxy. After verifying both, issue
+fresh pairing details and connect the app. An HTTPS health response establishes
+relay reachability; the paired app must still verify that the intended runtime
+is online and can complete a chat request.
+
+## Optional notification gateway
+
+Users of the Store app configure their Socket to use the publisher's trusted
+gateway; they do not need to host this additional process. Self-built apps can
+use their own FCM sender directly. See [push delivery configuration](SELF-HOSTING.md#optional-push-delivery).
+
+The Store application's publisher can run a separate sender process from this
+package. It is distinct from a user's Socket and must have its own private state
+directory, HTTPS origin and Firebase service account. Nothing in ordinary Socket
+setup creates an account, starts this gateway or enables remote delivery.
+
+Keep the gateway JSON and service-account file outside source with mode `0600`:
+
+```json
+{
+  "publicOrigin": "https://push.example.invalid",
+  "port": 8790,
+  "stateDirectory": "./push-state",
+  "serviceAccountFile": "./firebase-service-account.json"
+}
+```
+
+Run `abot-socket push-gateway --config /absolute/private/gateway.json` behind a
+trusted HTTPS reverse proxy. Like the Socket, it binds loopback only; the proxy
+must supply the verified client address and HTTPS forwarding headers described
+in this guide and allow its bounded JSON requests up to 8 KiB. Do not reuse the
+Socket's authentication state directory: the gateway
+has a separate database identity and rejects mixed state.
+
+The app uses `/v1/enroll` and `/v1/confirm` to prove receipt of a short-lived
+provider challenge. It receives separate device-scoped send and revoke grants,
+valid for up to 30 days. Only proof of receipt can replace an existing target.
+The paired Socket calls `/v1/deliver` with the send grant, fixed event kind and
+opaque notification ID. The gateway accepts neither arbitrary text nor a target
+token from a sender. `/v1/revoke` requires the separate management grant.
+
+Enrollment and sending have bounded rates, record counts, request sizes and
+timeouts. Provider tokens and credential hashes stay in private gateway state.
+The gateway sees delivery metadata, not chat text or pairing/runtime credentials.
+Data-only enrollment delivery is best effort; a delayed challenge can expire
+and must be retried while the app is open. Production deployment and a real
+signed-device test remain separate from local mocked validation.

package/docs/INSTALLATION.md

@@ -0,0 +1,166 @@
+# Installation and first connection
+
+ABot Socket is MIT-licensed and distributed as `@abot-ai/socket` on npm.
+This guide covers package installation, server preparation and the first
+runtime/app connection.
+
+## Install the command
+
+Use Node.js 24 or later and a persistent npm installation owned by an unprivileged
+account. Linux with systemd is the server deployment target; macOS can run the
+foreground service and local development checks. The authentication store uses
+POSIX ownership/permissions and does not support Windows server installation.
+
+Install the command from the official npm registry:
+
+```sh
+npm install --global @abot-ai/socket@0.1.0
+abot-socket --version
+abot-socket setup
+```
+
+Prefer an explicit version for server upgrades. An installed package uses the
+`abot-socket` command; it does not require a Git checkout or `npm ci`.
+
+Alternatively, prepare a tarball from the public source:
+
+```sh
+git clone https://github.com/Dorshitrit/abot-socket.git
+cd abot-socket
+npm ci --omit=optional --ignore-scripts
+npm pack --ignore-scripts --json > /tmp/abot-socket-pack.json
+npm run check-package -- /tmp/abot-socket-pack.json
+```
+
+Then install that tarball (or a verified local tarball you already have):
+
+```sh
+npm install --global ./abot-ai-socket-0.1.0.tgz
+abot-socket --version
+abot-socket setup
+```
+
+Contributor commands are separate in [Self-hosting](SELF-HOSTING.md#source-checkout-development).
+
+Do not use an ephemeral npx installation for a persistent system service. npm
+installation has no lifecycle install hooks and does not run the setup wizard,
+request certificates, contact your runtime or change OS service settings.
+
+## Follow setup
+
+The interactive wizard asks for:
+
+1. A new private installation directory; the default is `~/.abot-socket`.
+2. Your canonical HTTPS origin, for example `https://socket.example.net`.
+3. The runtime identity and a private loopback listener port (default 8788).
+4. On Linux as a non-root user: nginx, Apache or an existing HTTPS setup. Proxy
+   templates require paths to an existing full-chain certificate and private key.
+5. Confirmation before writing any installation files.
+
+Setup creates a new directory with mode `0700` and private files with mode `0600`:
+
+| Output | Purpose |
+| --- | --- |
+| `config.json` | HTTPS origin, listener port, state location and runtime grants containing token hashes. |
+| `runtime-connection.json` | Bridge URL, runtime identity and secret; transfer only to the runtime computer. |
+| `state/auth.sqlite3` | Pairing state, device credentials, notification metadata and pending delivery state. |
+| `deployment/` | Reviewable Linux service/proxy plan, when selected in the interactive wizard. |
+
+Setup defaults to Ask permission and port `8788`. Keep the installation outside
+the package/source directory so package updates cannot replace its state.
+No services are installed/started and certificate contents are never read.
+Pairing details are displayed in the terminal, not stored as a plaintext file.
+They expire after five minutes, so request a fresh bundle when HTTPS is ready.
+
+The optional endpoint check at the end makes one bounded public HTTPS request only
+if you explicitly choose it. A successful check proves relay health, not a working
+runtime or model. Cancellation before file creation leaves no installation behind.
+
+For unattended local file preparation, use explicit arguments instead of prompts:
+
+```sh
+abot-socket setup --output /srv/abot-private \
+  --origin https://socket.example.net --runtime-id workstation --port 8788
+```
+
+The parent directory must exist, and the output directory must not exist. Run as
+the same unprivileged account that will operate the relay. The unattended command
+creates the configuration/state only; use `deployment` separately for service files.
+If state initialization fails after files were written, preserve the installation,
+correct the private-state path/permissions and use `pair` to retry. Setup never
+overwrites existing configuration or state.
+
+## Configure HTTPS and start the relay
+
+Follow [Deployment](DEPLOYMENT.md) to review and explicitly apply the generated
+systemd and proxy files. Supply DNS, a valid certificate and the required proxy
+software yourself; neither npm nor setup obtains or installs them. Existing
+services must be checked before applying the plan.
+
+For foreground operation instead of a system service:
+
+```sh
+abot-socket start
+```
+
+Commands use `~/.abot-socket/config.json` by default. For a custom location:
+
+```sh
+abot-socket start --config /srv/abot-private/config.json
+abot-socket check-config --config /srv/abot-private/config.json
+```
+
+`--config` overrides environment settings. Otherwise `ABOT_SOCKET_CONFIG` and its
+legacy `SOCKET_V2_CONFIG` alias retain their existing precedence/conflict checks.
+`setup` takes `--output` instead; it never overwrites an existing configuration.
+
+## Connect runtime, then pair the app
+
+Privately transfer `runtime-connection.json` to the intended runtime computer.
+Configure its existing bridge with the generated `agentBridgeUrl`, `runtimeId`
+and `runtimeToken`, using that runtime version's documented configuration names.
+The file is a credential handoff, not a replacement runtime configuration or a
+second bridge process. This is separate from app pairing; the runtime secret
+must never go into the app.
+No runtime source changes are required by this installer.
+
+```sh
+abot-socket doctor
+abot-socket pair
+```
+
+For custom configuration locations, add `--config` to those commands as above.
+Doctor verifies TLS and the `/health` response, refuses redirects and has a five-second
+total timeout. Its output always includes `runtimeVerified: false`. It never sends
+credentials or generates a device session. The app must confirm that the selected
+runtime is online and can complete a chat request.
+
+In a normal terminal, `abot-socket pair` also displays a private QR for a scanner-capable
+ABot App. Scan inside the app, check the displayed server address, and confirm.
+The QR contains the same HTTPS URL, temporary pairing key and six-digit code; it
+expires after five minutes and can be used once. Anyone with the QR can use that
+pending pairing, so do not publish it or send it to a public QR service.
+
+Generate a fresh QR **after** the service and HTTPS are ready; setup does not start
+the server, and its initial pairing may expire while deployment is being completed.
+The QR is printed locally, not saved to disk or served at a public endpoint.
+Piped output keeps the existing text/JSON format. `TERM=dumb` or a narrow terminal
+uses manual details instead; widen the terminal and run `pair` again if needed.
+When running a remote command through SSH, allocate a terminal to display the QR.
+
+Manual entry remains available for app versions without a scanner or when camera
+access is unavailable: enter the new code, HTTPS URL and temporary pairing key. Afterwards,
+`abot-socket devices` lists devices and `abot-socket revoke <device-id>` revokes one.
+Both operate on the local private state without restarting the service.
+
+Push delivery is optional and off by default. Ordinary chat and the notification
+inbox work without it. See [push delivery configuration](SELF-HOSTING.md#optional-push-delivery)
+for the difference between the Store application's gateway and a self-built app's
+own Firebase sender.
+
+## Updates
+
+Keep private configuration/state outside the npm package directory. Updating the
+package must not replace that state. Regenerate the service plan if Node or the
+package path changes, and restart the service explicitly during the approved update.
+No automatic update, live migration or service restart is implemented here.