From 94eaa35dd1dd7692fca53d9dcfe709e71a6ce84f Mon Sep 17 00:00:00 2001
From: Abhinaysai Kamineni <66816045+askmy-stack@users.noreply.github.com>
Date: Tue, 4 Aug 2026 20:52:42 -0400
Subject: [PATCH] Prepare v0.2.0 release and pin Action docs to tags.

Move Unreleased notes into 0.2.0, advertise pip install tool-semantics,
and document reproducible @vX.Y.Z Action pins instead of @main (#31, #32).

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 CHANGELOG.md                   |  7 +++++++
 README.md                      |  4 ++--
 docs/github-action.md          | 18 ++++++++++++++++--
 docs/publishing.md             |  8 +++++---
 pyproject.toml                 |  2 +-
 src/tool_semantics/__init__.py |  2 +-
 6 files changed, 32 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6ec38ea..a4e3d91 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,13 @@ All notable changes to Tool-Semantics will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+- (none yet)
+
+## [0.2.0] — 2026-08-04
+
+First PyPI release. Install with `pip install tool-semantics`.
+
 ### Added
 - `tool.output_schema_added` / `removed` / `changed` detection (#8)
 - `parameter.default_changed` warning when defaults are added, removed, or changed (#15)
diff --git a/README.md b/README.md
index 4f18457..dd43167 100644
--- a/README.md
+++ b/README.md
@@ -105,8 +105,8 @@ Result: breaking
 ## Install (library)
 
 ```bash
-pip install -e .
-# later: pip install tool-semantics
+pip install tool-semantics
+# or from source: pip install -e .
 ```
 
 ```python
diff --git a/docs/github-action.md b/docs/github-action.md
index 07a9050..e1076d1 100644
--- a/docs/github-action.md
+++ b/docs/github-action.md
@@ -9,6 +9,20 @@ the Markdown report as a pull-request comment.
 askmy-stack/tool-semantics/.github/actions/compare
 ```
 
+## Versioning the Action
+
+Pin the composite Action to a **release tag** (or commit SHA) so consumer CI stays
+reproducible. Tags follow the package version (`v0.2.0`, …). A floating major pin
+such as `@v0` is fine once a `v0` moving tag exists; prefer an exact tag for
+production workflows.
+
+`@main` tracks the tip of the default branch and **may break** without notice —
+use it only for local experiments.
+
+After each GitHub Release, the tagged tree includes this composite Action, so
+`uses: askmy-stack/tool-semantics/.github/actions/compare@vX.Y.Z` resolves from
+that tag.
+
 ## Example consumer workflow
 
 ```yaml
@@ -27,10 +41,10 @@ jobs:
       - uses: actions/checkout@v4
       - name: Capture baseline and candidate
         run: |
-          pip install "tool-semantics @ git+https://github.com/askmy-stack/tool-semantics.git"
+          pip install "tool-semantics==0.2.0"
           tool-semantics capture manifests/baseline.json -o .tool-semantics/baseline.json
           tool-semantics capture manifests/candidate.json -o .tool-semantics/candidate.json
-      - uses: askmy-stack/tool-semantics/.github/actions/compare@main
+      - uses: askmy-stack/tool-semantics/.github/actions/compare@v0.2.0
         with:
           baseline: .tool-semantics/baseline.json
           candidate: .tool-semantics/candidate.json
diff --git a/docs/publishing.md b/docs/publishing.md
index 6efb08b..f3752a0 100644
--- a/docs/publishing.md
+++ b/docs/publishing.md
@@ -17,9 +17,11 @@ No long-lived PyPI API token is stored in the repository.
 ## Release steps
 
 1. Bump `version` in `pyproject.toml` and `src/tool_semantics/__init__.py`.
-2. Update `CHANGELOG.md`.
-3. Tag and publish a GitHub Release (`vX.Y.Z`).
-4. The `Publish to PyPI` workflow builds sdist/wheel and uploads via OIDC.
+2. Update `CHANGELOG.md` (move Unreleased notes into a dated `X.Y.Z` section).
+3. Update Action pin examples in `docs/github-action.md` to `@vX.Y.Z`.
+4. Tag and publish a GitHub Release (`vX.Y.Z`).
+5. The `Publish to PyPI` workflow builds sdist/wheel and uploads via OIDC.
+6. Verify `pip install tool-semantics==X.Y.Z` in a clean venv.
 
 ## Local dry-run
 
diff --git a/pyproject.toml b/pyproject.toml
index 9ac2da9..c1fccf4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tool-semantics"
-version = "0.1.0"
+version = "0.2.0"
 description = "Behavioral compatibility testing for MCP tools and AI-agent interfaces"
 readme = "README.md"
 requires-python = ">=3.11"
diff --git a/src/tool_semantics/__init__.py b/src/tool_semantics/__init__.py
index 91e645f..63154a9 100644
--- a/src/tool_semantics/__init__.py
+++ b/src/tool_semantics/__init__.py
@@ -1,3 +1,3 @@
 """Tool-Semantics: behavioral compatibility testing for MCP tools and AI-agent interfaces."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"