docs: prepare browser extension alpha release

LICENSE

@@ -0,0 +1,17 @@
+Verstak Browser Extension
+Copyright (C) 2026 Verstak contributors
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+details.
+
+The complete license text is available at:
+https://www.gnu.org/licenses/agpl-3.0.html
+
+SPDX-License-Identifier: AGPL-3.0-or-later

README.md

@@ -1,4 +1,4 @@
-# verstak-browser-extension
+# Verstak Browser Extension
 
 Verstak Browser Extension captures pages, selected text, links, and selected
 files and sends them to a local Verstak browser inbox receiver.
@@ -7,6 +7,8 @@ The extension does not know Notes, Files, Activity, or Journal internals. It
 only sends capture events through the public local receiver protocol. If the
 receiver is offline, captures stay in the extension pending queue.
 
+> **Alpha software.** Use with a matching Verstak Desktop alpha release.
+
 ## Build
 
 ```bash
@@ -20,6 +22,23 @@ Build output:
 - `dist/chromium`
 - `dist/firefox`
 
+Load `dist/chromium` as an unpacked extension in Chromium-based browsers, or
+load `dist/firefox` temporarily in Firefox during development.
+
+## Passive domain activity
+
+Passive tracking is **off by default**. On first use the extension explains
+what it records; the user must explicitly enable it in extension settings.
+
+When enabled, it observes only the focused browser's active tab and sends
+bounded aggregate intervals as a canonical domain name plus duration. It never
+sends URL paths, page titles, page text, selected text, keystrokes, navigation
+history or inactive-tab time. The settings screen has an exclusion list for
+domains such as `youtube.com` or `x.com`.
+
+Manual “Send page”, selection, link and file actions are separate. They create
+Browser Inbox captures; they do not create a workspace or a journal entry.
+
 ## Firefox Release
 
 Firefox signing uses `web-ext` and AMO credentials from an env file. The script
@@ -38,6 +57,16 @@ Release output:
 The XPI is signed as an unlisted/self-distributed Firefox extension. Build and
 release artifacts are local outputs and are not committed.
 
+## Reproducible local package
+
+```bash
+npm run release:package -- v0.1.0-alpha.1
+```
+
+This runs the tests and build, then writes unsigned Chromium and Firefox source
+packages to `release/` with a `SHA256SUMS` file. Use `release:firefox` above
+when an AMO-signed XPI is required.
+
 ## Manual Check
 
 1. Start Verstak desktop with the `verstak.browser-inbox` plugin installed.
@@ -109,3 +138,8 @@ Expected success response:
 ```json
 { "status": "accepted", "captureId": "uuid-or-generated-id" }
 ```
+
+## License
+
+Copyright © 2026 Verstak contributors. Licensed under
+[GNU AGPLv3 or later](LICENSE).

package.json

@@ -7,7 +7,8 @@
     "build": "node scripts/build-extension.js",
     "test": "node scripts/test-hostname.js && node scripts/test-activity-tracker.js && node scripts/test-protocol.js && node scripts/test-i18n.js && node scripts/test-popup-settings.js && node scripts/test-popup-catalog-fallback.js && node scripts/test-background-i18n.js",
     "sign:firefox": "./scripts/sign-firefox-xpi.sh",
-    "release:firefox": "./scripts/release-firefox-xpi.sh"
+    "release:firefox": "./scripts/release-firefox-xpi.sh",
+    "release:package": "./scripts/package-release.sh"
   },
   "devDependencies": {
     "web-ext": "^8.3.0"

scripts/package-release.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+VERSION="${1:-}"
+
+if [[ -z "$VERSION" || ! "$VERSION" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]]; then
+  echo "usage: $0 <version>" >&2
+  echo "example: $0 v0.1.0-alpha.1" >&2
+  exit 2
+fi
+
+echo "=== verstak browser extension release $VERSION ==="
+(cd "$ROOT" && npm ci --no-audit --no-fund && npm test && npm run build)
+
+RELEASE_ROOT="$ROOT/release"
+STAGING="$RELEASE_ROOT/verstak-browser-extension-$VERSION"
+ARCHIVE="$RELEASE_ROOT/verstak-browser-extension-$VERSION.tar.gz"
+rm -rf "$STAGING" "$ARCHIVE"
+mkdir -p "$STAGING"
+
+cp "$ROOT/README.md" "$ROOT/LICENSE" "$STAGING/"
+cp -R "$ROOT/dist" "$STAGING/dist"
+tar -C "$RELEASE_ROOT" -czf "$ARCHIVE" "$(basename "$STAGING")"
+(cd "$RELEASE_ROOT" && sha256sum "$(basename "$ARCHIVE")" > SHA256SUMS)
+
+echo "release archive: $ARCHIVE"
+echo "checksums:       $RELEASE_ROOT/SHA256SUMS"