diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index d79cda0..7e7074f 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -3,32 +3,55 @@ name: Publish to PyPI
 on:
   release:
     types: [published]
+  workflow_dispatch:
+    inputs:
+      pypi_target:
+        description: 'PyPI target (pypi or testpypi)'
+        default: 'pypi'
+        type: choice
+        options:
+          - pypi
+          - testpypi
 
 permissions:
   contents: read
+  id-token: write
 
 jobs:
-  deploy:
+  publish:
     runs-on: ubuntu-latest
+    environment: pypi
+
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: actions/checkout@v4
         with:
           persist-credentials: false
-      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
-      - name: Install build tools
+          python-version: "3.12"
+
+      - name: Install dependencies
         run: |
-          pip install --upgrade pip
-          pip install build twine
+          python -m pip install --upgrade pip
+          pip install build twine ruff
+
       - name: Lint with ruff
-        run: pip install ruff && ruff check src/ tests/
+        run: ruff check src/ --target-version py310
 
       - name: Build package
         run: python -m build
+
+      - name: Check package
+        run: twine check dist/*
+
+      - name: Publish to TestPyPI
+        if: ${{ inputs.pypi_target == 'testpypi' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
       - name: Publish to PyPI
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
-        run: twine upload dist/*
+        if: ${{ inputs.pypi_target == 'pypi' || github.event_name == 'release' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..0d8c5b8
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,29 @@
+# apighost
+
+## Purpose
+CLI tool that reads an OpenAPI spec and spawns a realistic mock API server with VCR cassette recording and replay — OpenAPI spec → mock server with VCR recording.
+
+## Build & Test Commands
+- Install: `pip install -e .` or `pip install git+https://github.com/Coding-Dev-Tools/apighost.git`
+- Test: `pytest tests/` (or `python -m pytest tests/ -v --tb=short`)
+- Lint: `ruff check src/ tests/`
+- Build: `pip install build twine && python -m build && twine check dist/*`
+- CLI check: `apighost --help`
+
+## Architecture
+Key directories:
+- `src/apighost/` — Main package (CLI, OpenAPI parser, mock server, VCR recorder, scenarios)
+- `tests/` — Test suite
+- `.github/workflows/` — CI/CD (auto-code-review.yml, ci.yml, pages.yml, publish.yml)
+- `dist/` — Built distributions
+
+## Conventions
+- Language: Python 3.10+
+- Test framework: pytest
+- CI: GitHub Actions (lint job + test job with matrix: Python 3.10, 3.11, 3.12, 3.13)
+- Linting: ruff (line-length 120, target py310)
+- Formatting: ruff
+- Package layout: src/ layout with setuptools
+- Dependencies: click, pyyaml, faker, flask, rich, requests, jsonschema, werkzeug
+- CLI entry point: apighost.cli:cli
+- Master branch: master
\ No newline at end of file