Prepare v0.2.0 release + pin Action examples to tags (#31, #32)

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)

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

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/[email protected]` 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

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
 

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"

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"