From 226464f082b150c09bc7ca24d7531c6d3d002cdb Mon Sep 17 00:00:00 2001
From: mirivlad <mirvtop@yandex.ru>
Date: Sun, 12 Jul 2026 21:22:24 +0800
Subject: [PATCH] docs: prepare official plugins alpha release

---
 LICENSE            | 17 +++++++++++++++
 README.md          | 54 +++++++++++++++++++++++++++++++++++++++++++---
 scripts/release.sh | 29 +++++++++++++++++++++++++
 3 files changed, 97 insertions(+), 3 deletions(-)
 create mode 100644 LICENSE
 create mode 100755 scripts/release.sh

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..b88c55e
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,17 @@
+Verstak Official Plugins
+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
diff --git a/README.md b/README.md
index edfa340..5ea2c5c 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,53 @@
-# verstak-official-plugins
+# Verstak Official Plugins
 
-Official Verstak plugins monorepo — files, trash, notes, markdown-editor, preview, activity, journal, todos, browser-inbox, search, secrets, templates + shared packages.
+The first-party plugin set for Verstak Desktop: Files, Trash, Notes, editor and
+preview providers, Browser Inbox, Activity, Journal, Todo, Search, Secrets and
+Templates. Plugin bundles are built into independent directories that the
+desktop host loads from its `plugins/` folder.
 
-`Files` shows live workspace files and folders. Global `Trash` contains deleted items from every workspace; restoring never overwrites an existing item, and permanent deletion is confirmed before it runs.
+> **Alpha software.** Build this repository together with compatible
+> `verstak-desktop` and `verstak-sdk` checkouts.
+
+## Build
+
+Requirements: Node.js with npm, Go and Python 3. Keep this repository next to
+`verstak-sdk` so manifest validation can use the SDK schema.
+
+```bash
+npm --version
+go version
+./scripts/check.sh
+./scripts/build.sh
+```
+
+The build creates `dist/<plugin-id>/` packages. To install them into a sibling
+desktop checkout:
+
+```bash
+cd ../verstak-desktop
+./scripts/install-dev-plugins.sh
+```
+
+## Alpha behaviour
+
+- Browser Inbox archives processed captures and can restore them; permanent
+  deletion is a separate action.
+- Saving a browser link creates a collision-safe `.url` file. Opening a link is
+  handled by Verstak, so it does not depend on a Linux `.url` file association.
+- Activity sessions can be scoped to a durable workspace identity or to an
+  explicit unassigned scope. Journal creation is always a user action.
+- Todo is optional: Overview uses it only when the Todo capability is present.
+
+## Release package
+
+```bash
+./scripts/release.sh v0.1.0-alpha.1
+```
+
+The command rebuilds all packages and writes
+`release/verstak-official-plugins-<version>.tar.gz` plus `SHA256SUMS`.
+
+## License
+
+Copyright © 2026 Verstak contributors. Licensed under
+[GNU AGPLv3 or later](LICENSE).
diff --git a/scripts/release.sh b/scripts/release.sh
new file mode 100755
index 0000000..5a94b3e
--- /dev/null
+++ b/scripts/release.sh
@@ -0,0 +1,29 @@
+#!/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 official plugins release $VERSION ==="
+"$ROOT/scripts/check.sh"
+"$ROOT/scripts/build.sh"
+
+RELEASE_ROOT="$ROOT/release"
+STAGING="$RELEASE_ROOT/verstak-official-plugins-$VERSION"
+ARCHIVE="$RELEASE_ROOT/verstak-official-plugins-$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"