diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index de19f7b..7e7074f 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -13,27 +13,32 @@ on:
           - pypi
           - testpypi
 
+permissions:
+  contents: read
+  id-token: write
+
 jobs:
   publish:
     runs-on: ubuntu-latest
     environment: pypi
-    permissions:
-      id-token: write
 
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: actions/checkout@v4
         with:
           persist-credentials: false
 
       - name: Set up Python 3.12
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        uses: actions/setup-python@v5
         with:
           python-version: "3.12"
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install build twine
+          pip install build twine ruff
+
+      - name: Lint with ruff
+        run: ruff check src/ --target-version py310
 
       - name: Build package
         run: python -m build
@@ -43,10 +48,10 @@ jobs:
 
       - name: Publish to TestPyPI
         if: ${{ inputs.pypi_target == 'testpypi' }}
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b
+        uses: pypa/gh-action-pypi-publish@release/v1
         with:
           repository-url: https://test.pypi.org/legacy/
 
       - name: Publish to PyPI
         if: ${{ inputs.pypi_target == 'pypi' || github.event_name == 'release' }}
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b
+        uses: pypa/gh-action-pypi-publish@release/v1
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ec6b788
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,29 @@
+# datamorph
+
+## Purpose
+Batch data format converter — stream files between CSV, JSON, Parquet, YAML, Avro, and more. Includes schema inference and validation.
+
+## Build & Test Commands
+- Install: `pip install -e .` or `pip install datamorph-cli`
+- Test: `pytest tests/` (or `python -m pytest tests/ -v --tb=short`)
+- Lint: `ruff check .`
+- Build: `pip install build twine && python -m build && twine check dist/*`
+- CLI check: `datamorph --version && datamorph --help && datamorph formats`
+
+## Architecture
+Key directories:
+- `src/datamorph/` — Main package (CLI, converters, schema inference, validation)
+- `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 + test matrix: Python 3.10, 3.11, 3.12, 3.13)
+- Linting: ruff
+- Build system: hatchling
+- Package layout: src/ layout
+- Dependencies: click, rich, faker, flask, requests, jsonschema, werkzeug, pandas, pyarrow
+- CLI entry point: datamorph.cli:cli
+- Default branch: master
\ No newline at end of file