docs: prepare sdk alpha release

.gitignore

@@ -1 +1,3 @@
 node_modules/
+dist/
+release/

LICENSE

@@ -0,0 +1,17 @@
+Verstak Plugin SDK
+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,6 +1,38 @@
-# verstak-sdk
+# Verstak Plugin SDK
 
-Verstak Plugin SDK — manifest schema, TypeScript SDK, RPC protocol, capability contracts, event schemas, test helpers, packaging tools
+TypeScript API, JSON schemas and contract tests for plugins running in Verstak
+Desktop. The SDK is versioned independently so plugin authors can validate
+their manifests and compile against the public host API.
+
+> **Alpha contract.** This is the first public alpha. Keep SDK, Desktop and
+> official-plugin versions in the same release line while APIs are evolving.
+
+## Install and verify
+
+```bash
+npm ci
+npm run lint
+npm test
+npm run build
+```
+
+The build emits `dist/`. A packed npm artifact can be made locally with:
+
+```bash
+./scripts/release.sh v0.1.0
+```
+
+It validates the requested version against `package.json`, then writes an npm
+tarball and `SHA256SUMS` to `release/`.
+
+## Contracts relevant to the alpha
+
+- Workspaces have durable UUID identities; paths are addresses, not identity.
+- Activity may be scoped to `workspaceId` or to explicit `unassigned` work.
+- The `hostname-normalization-v1.json` vectors define the shared canonical
+  browser-domain representation used by Desktop and the extension.
+- Browser activity batches contain only a normalized hostname and bounded
+  duration. Manual captures use a separate Inbox protocol.
 
 ## Bundled Frontend API Contract
 
@@ -40,3 +72,8 @@ or trash metadata.
 Bundled frontend plugins are trusted/cooperative and run in the desktop JS
 context. Current permission checks are contract checks, not a security boundary;
 real isolation belongs to a later sidecar/sandbox milestone.
+
+## License
+
+Copyright © 2026 Verstak contributors. Licensed under
+[GNU AGPLv3 or later](LICENSE).

scripts/release.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+REQUESTED_VERSION="${1:-}"
+PACKAGE_VERSION="$(node -p "require('$ROOT/package.json').version")"
+
+if [[ -z "$REQUESTED_VERSION" ]]; then
+  echo "usage: $0 <version>" >&2
+  echo "example: $0 v0.1.0" >&2
+  exit 2
+fi
+if [[ "${REQUESTED_VERSION#v}" != "$PACKAGE_VERSION" ]]; then
+  echo "requested version $REQUESTED_VERSION does not match package.json $PACKAGE_VERSION" >&2
+  exit 1
+fi
+
+echo "=== verstak sdk release $PACKAGE_VERSION ==="
+(cd "$ROOT" && npm ci --no-audit --no-fund && npm run lint && npm test && npm run build)
+
+RELEASE_ROOT="$ROOT/release"
+rm -rf "$RELEASE_ROOT"
+mkdir -p "$RELEASE_ROOT"
+(cd "$ROOT" && npm pack --pack-destination "$RELEASE_ROOT")
+(cd "$RELEASE_ROOT" && sha256sum ./*.tgz > SHA256SUMS)
+
+echo "release package: $RELEASE_ROOT"
+echo "checksums:       $RELEASE_ROOT/SHA256SUMS"