chore(release): add trusted-publishing workflows and PyPI docs

Author: trevor-nichols

.github/workflows/publish-pypi.yml

@@ -0,0 +1,109 @@
+name: Publish Python Package
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: "Target index for publish"
+        required: true
+        default: testpypi
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build Distribution Artifacts
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Validate tag matches pyproject version
+        if: github.event_name == 'push'
+        run: |
+          PYTHONPATH=src python -m agentrules.core.utils.release_metadata \
+            --tag "${GITHUB_REF_NAME}"
+
+      - name: Guard manual PyPI publish to tagged refs only
+        if: github.event_name == 'workflow_dispatch' && github.event.inputs.repository == 'pypi'
+        run: |
+          if [ "${GITHUB_REF_TYPE}" != "tag" ]; then
+            echo "Manual PyPI publish must run from a tag ref (vX.Y.Z)."
+            exit 1
+          fi
+          PYTHONPATH=src python -m agentrules.core.utils.release_metadata \
+            --tag "${GITHUB_REF_NAME}"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --upgrade build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check built metadata
+        run: python -m twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/*
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.repository == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+
+      - name: Publish package distributions to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.repository == 'pypi')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

README.md

@@ -75,7 +75,13 @@ The pipeline captures metrics (elapsed time, agent counts) and hands them to the
 
 ## 📦 Installation
 
-### Clone & bootstrap
+### Install from PyPI
+
+```bash
+pip install agentrules
+```
+
+### Install from source
 
 ```bash
 git clone https://github.com/trevor-nichols/agentrules-architect.git
@@ -104,7 +110,7 @@ Prefer module execution during development? Invoke the CLI with Python’s modul
 python -m agentrules analyze /path/to/project
 ```
 
-Need to skip local cloning? Install straight from GitHub (PyPI release pending):
+Need to install directly from GitHub instead of PyPI?
 
 ```bash
 pip install "git+https://github.com/trevor-nichols/agentrules-architect.git#egg=agentrules"
@@ -320,9 +326,18 @@ Toggle outputs with `agentrules configure --outputs` or via the config TOML.
 - Run targeted tests: `python tests/phase_3_test/run_test.py`
 - Deterministic smoke runs (CI/local without API calls): `agentrules analyze --offline tests/tests_input`
 - Full suite: `python -m unittest discover tests -v`
-- Releases are tag-driven: bump `[project].version` in `pyproject.toml`, commit it, create the matching `vX.Y.Z` tag, and push the tag to let GitHub Actions publish the GitHub Release automatically.
+- Releases are tag-driven: bump `[project].version` in `pyproject.toml`, commit, create matching `vX.Y.Z` tag, and push it.
+- GitHub Actions now publishes package artifacts with Trusted Publishing (OIDC) via `.github/workflows/publish-pypi.yml` (no long-lived PyPI API token).
+- Run a safe preflight publish first from Actions with `workflow_dispatch` and `repository = testpypi`; publish to production PyPI on tag push or manual `repository = pypi`.
 - Keep docs and presets in sync when adding providers (`config/agents.py`, `config/tools.py`, `core/agents/*`).
 
+### Release Process (PyPI)
+
+1. Update `[project].version` in `pyproject.toml`, then commit and push.
+2. Run `.github/workflows/publish-pypi.yml` manually with `repository = testpypi` to validate package upload first.
+3. Create and push matching tag `vX.Y.Z` to trigger Trusted Publishing to PyPI.
+4. The same tag also triggers `.github/workflows/release.yml` for GitHub Release artifact/notes.
+
 ## 🤝 Contributing
 
 See `CONTRIBUTING.md` for detailed guidelines on workflows, testing, and pull request expectations. Issues and PRs are welcome—just ensure Ruff/Pyright/tests pass before submitting.

pyproject.toml

@@ -5,17 +5,16 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "agentrules"
 version = "3.4.0"
-description = "Interactive CLI for the CursorRules Architect multi-phase analysis pipeline."
+description = "AGENTS.md/CLAUDE.md generator and ExecPlan harness for coding agents"
 readme = "README.md"
 authors = [{name = "trevor-nichols"}]
-license = {text = "MIT"}
+license = "MIT"
 requires-python = ">=3.11.9"
 keywords = ["cursor", "ai", "analysis", "cli", "agents"]
 classifiers = [
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
-  "License :: OSI Approved :: MIT License",
   "Operating System :: OS Independent"
 ]
 dependencies = [