docs: update tooling for SDK 2.0.1 (#47)

Author: TheRealAgentK

.github/workflows/self-test.yml

@@ -103,6 +103,9 @@ jobs:
       - name: Test check_code.py — long lines pass with ruff.toml config
         run: python scripts/check_code.py tests/examples/long-lines-integration
 
+      - name: Test run_tests.py — SDK 2.0.1 unit fixtures
+        run: python scripts/run_tests.py tests/examples/good-integration tests/examples/modular-integration tests/examples/long-lines-integration tests/sample-api
+
       - name: Test check_code.py — ruff.toml applied from different working directory
         run: |
           cd /tmp

CONTRIBUTING.md

@@ -36,8 +36,11 @@ Run these before submitting a PR:
 # Validate structure and config
 python scripts/validate_integration.py my-integration
 
-# Run all code quality checks (syntax, imports, JSON, lint, format, security, deps)
+# Run all code quality checks (syntax, imports, JSON, lint, format, security, deps, config sync, fetch pattern)
 python scripts/check_code.py my-integration
+
+# Run unit tests when the integration has test_*_unit.py files
+python scripts/run_tests.py my-integration
 ```
 
 ### What Gets Checked
@@ -53,6 +56,8 @@ python scripts/check_code.py my-integration
 | Security | `bandit` | No hardcoded secrets, unsafe eval/exec |
 | Dependencies | `pip-audit` | No known CVEs in requirements.txt |
 | Config sync | `check_config_sync.py` | Config.json actions and input schemas match code |
+| Fetch pattern | `check_fetch_pattern.py` | SDK 2.x `context.fetch()` responses are accessed via `.data` |
+| Unit tests | `run_tests.py` | Runs `test_*_unit.py` files with each integration's own dependencies |
 
 ### Auto-Fixing Common Issues
 
@@ -85,7 +90,7 @@ docs: update Netlify README with auth setup
 
 ## Pull Request Process
 
-1. **Run validation locally** — both `validate_integration.py` and `check_code.py`
+1. **Run validation locally** — `validate_integration.py`, `check_code.py`, and `run_tests.py` when unit tests exist
 2. **Update the main README.md** — add your integration to the integrations table
 3. **Use a conventional commit PR title** — CI enforces this
 4. **One integration per PR** — keep PRs focused
@@ -95,7 +100,8 @@ docs: update Netlify README with auth setup
 Your PR will automatically run:
 
 - **Structure Check** — validates folder structure and config.json
-- **Code Check** — syntax, imports, JSON, lint, format, security, dependency audit
+- **Code Check** — syntax, imports, JSON, lint, format, security, dependency audit, config sync, fetch pattern
+- **Tests** — runs `test_*_unit.py` files with pytest and coverage
 - **README Check** — verifies the main README.md was updated
 - **Version Check** — verifies config.json version was incremented, recommends bump level
 - **Conventional Commits** — validates PR title format

INTEGRATION_CHECKLIST.md

@@ -56,7 +56,7 @@ The structure check produces warnings (not errors) for these cases:
 
 | Warning | Explanation |
 |---------|-------------|
-| `Integration.load()` not found | The check looks for the literal string `Integration.load()`. Using `Integration.load(config_path)` triggers this warning — that's expected for multi-file integrations. |
+| `Integration.load(...)` not found | The check looks for `Integration.load` in Python files. Use `Integration.load()` for vendored single-file integrations, or `Integration.load(config_path)` / `Integration.load(Path(__file__).with_name("config.json"))` when an explicit config path is needed. |
 | Missing `__init__.py` | Optional for modular integrations with an `actions/` subdirectory |
 | Missing top-level `display_name` | Recommended but not required |
 | Missing `display_name` on actions | Recommended but not required |
@@ -144,9 +144,9 @@ but only list_sites and create_site are implemented:
 | Missing icon | Add `icon.png` or `icon.svg` (512×512 pixels) |
 | Missing or incomplete README | Document all actions, auth setup, inputs/outputs |
 | Not updating main repo README | Add integration entry in alphabetical order |
-| Unpinned SDK version | Use `autohive-integrations-sdk~=2.0.0` (or `~=1.1.1` for 1.x) |
+| Unpinned SDK version | Use `autohive-integrations-sdk~=2.0.1` (or `~=1.1.1` for 1.x) |
 | Sync functions for action handlers | Must be `async def execute()` |
 
 ---
 
-*Last updated: March 2026*
+*Last updated: July 2026*

LOCAL_DEVELOPMENT.md

@@ -27,10 +27,10 @@ python scripts/validate_integration.py my-integration
 Run this **first** — it catches structural problems before you waste time on code quality checks. It validates:
 
 - Folder name is lowercase
-- All required files exist (`config.json`, `__init__.py`, `requirements.txt`, `README.md`, `icon.png`/`icon.svg`)
+- All required files exist (`config.json`, `requirements.txt`, `README.md`, `icon.png`/`icon.svg`; `__init__.py` is required for single-file/package-style integrations and optional for modular integrations with `actions/`)
 - `config.json` has the required fields and valid schema
 - `__init__.py` is minimal (only import + `__all__`)
-- `requirements.txt` includes `autohive-integrations-sdk`
+- `requirements.txt` includes `autohive-integrations-sdk~=2.0.1` or later in the SDK 2.x line
 - `tests/` folder has `__init__.py`, `context.py` or `conftest.py`, and at least one `test_*.py`
 - Icon is exactly 512x512 pixels
 - OAuth scopes are actually used (heuristic)

README.md

@@ -62,7 +62,7 @@ flowchart TB
     end
 
     subgraph external["External Repos"]
-        EXT["uses: autohive-ai/autohive-integrations-tooling@1.0.0"]
+        EXT["uses: autohive-ai/autohive-integrations-tooling@v2"]
     end
 
     PR --> wf1
@@ -108,7 +108,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: autohive-ai/autohive-integrations-tooling@1.0.0
+      - uses: autohive-ai/autohive-integrations-tooling@v2
         with:
           base_ref: origin/${{ github.base_ref }}
 ```
@@ -139,6 +139,7 @@ jobs:
 | `tests_output` | Full output of the test runner |
 | `readme_output` | Full output of the README check |
 | `version_output` | Full output of the version check |
+| `comment_path` | Path to the rendered Markdown PR comment body, useful for fork-safe comment posting from a separate workflow |
 
 ### PR Comment
 
@@ -215,7 +216,7 @@ See `INTEGRATION_CHECKLIST.md` for full details.
 - `config.json` - Integration configuration
 - `{name}.py` - Main implementation
 - `__init__.py` - Package init (minimal, optional for modular integrations with `actions/`)
-- `requirements.txt` - Dependencies (must include `autohive-integrations-sdk`)
+- `requirements.txt` - Dependencies (must include `autohive-integrations-sdk~=2.0.1` or later in the SDK 2.x line)
 - `README.md` - Documentation
 - `icon.png` or `icon.svg` - Integration icon (512x512 pixels)
 - `tests/` - Test folder with `__init__.py`, `context.py` or `conftest.py`, and `test_*.py`

scripts/docs/check_code.md

@@ -354,8 +354,8 @@ Called by the `validate-integration.yml` workflow (on pull requests):
 
 ```yaml
 - name: Code Check
-  if: steps.changed.outputs.dirs != ''
-  run: python scripts/check_code.py --base-ref origin/${{ github.base_ref }} ${{ steps.changed.outputs.dirs }}
+  if: steps.detect.outputs.dirs != ''
+  run: python scripts/check_code.py --base-ref origin/${{ github.base_ref }} ${{ steps.detect.outputs.dirs }}
 ```
 
 Also exercised by the `self-test.yml` workflow against test examples in `tests/examples/` as a regression guard.

scripts/docs/check_readme.md

@@ -122,8 +122,8 @@ Called by the `validate-integration.yml` workflow, **only during pull requests**
 
 ```yaml
 - name: README Check
-  if: steps.changed.outputs.dirs != ''
-  run: python scripts/check_readme.py "origin/${{ github.base_ref }}" ${{ steps.changed.outputs.dirs }}
+  if: steps.detect.outputs.dirs != ''
+  run: python scripts/check_readme.py "origin/${{ github.base_ref }}" ${{ steps.detect.outputs.dirs }}
 ```
 
 This check is skipped on direct pushes since there is no meaningful base ref to compare against for README changes.

scripts/docs/run_tests.md

@@ -79,7 +79,7 @@ flowchart TD
 Different integrations may pin different SDK versions. For example:
 
 - `bitly/requirements.txt` → `autohive-integrations-sdk~=1.0.2`
-- `notion/requirements.txt` → `autohive-integrations-sdk~=2.0.0`
+- `notion/requirements.txt` → `autohive-integrations-sdk~=2.0.1`
 
 The test runner handles this by installing dependencies and running pytest separately for each integration. The last `pip install` overwrites the previous SDK version, which is why pytest must run immediately after each install.
 

scripts/docs/validate_integration.md

@@ -147,7 +147,7 @@ Allowed patterns:
 | Check | Severity | Description |
 |-------|----------|-------------|
 | `autohive-integrations-sdk` present | Error | SDK dependency is mandatory |
-| Version pinned and not deprecated | Warning | Should pin SDK version (e.g., `~=2.0.0`); deprecated versions warn |
+| Version pinned and not deprecated | Warning | Should pin SDK version (e.g., `~=2.0.1`); deprecated versions warn |
 
 ### 6. Tests Folder (`_check_tests_folder`)
 
@@ -166,7 +166,7 @@ Inspects all `.py` files in the integration directory (not just the entry point)
 |-------|----------|-------------|
 | `Integration` imported | Warning | Should import from SDK |
 | `ActionHandler` imported | Warning | Should import from SDK |
-| `Integration.load()` called | Warning | Standard loading pattern |
+| `Integration.load(...)` called | Warning | Standard loading pattern, with or without an explicit config path |
 
 > **Note:** Action decorator matching (config ↔ code) is handled by `check_config_sync.py`, which uses AST parsing for more accurate bidirectional validation.
 
@@ -254,8 +254,8 @@ Called by the `validate-integration.yml` workflow (on pull requests) as the **St
 
 ```yaml
 - name: Structure Check
-  if: steps.changed.outputs.dirs != ''
-  run: python scripts/validate_integration.py ${{ steps.changed.outputs.dirs }}
+  if: steps.detect.outputs.dirs != ''
+  run: python scripts/validate_integration.py ${{ steps.detect.outputs.dirs }}
 ```
 
 The script is also exercised by the `self-test.yml` workflow, which runs it against the test examples in `tests/examples/` as a regression guard whenever `scripts/` or `tests/` change.

scripts/validate_integration.py

@@ -309,7 +309,7 @@ def _check_init_py(self):
     # Integrations pinning older versions will receive a deprecation warning.
     _MIN_SDK_VERSIONS = {
         1: (1, 1, 1),   # 1.x line: minimum 1.1.1
-        2: (2, 0, 0),   # 2.x line: minimum 2.0.0
+        2: (2, 0, 1),   # 2.x line: minimum 2.0.1
     }
 
     def _check_requirements_txt(self):
@@ -330,7 +330,7 @@ def _check_requirements_txt(self):
         if not match:
             self.add_warning(
                 "requirements.txt should pin SDK version "
-                "(e.g., autohive-integrations-sdk~=2.0.0)"
+                "(e.g., autohive-integrations-sdk~=2.0.1)"
             )
             return
 
@@ -404,9 +404,9 @@ def _check_main_python_file(self):
             if item not in all_content:
                 self.add_warning(f"Integration may be missing import: {item} ({source})")
 
-        # Check for Integration.load() across all Python files
-        if 'Integration.load()' not in all_content:
-            self.add_warning("Integration should use 'Integration.load()' to load the integration")
+        # Check for Integration.load(...) across all Python files.
+        if 'Integration.load' not in all_content:
+            self.add_warning("Integration should use 'Integration.load(...)' to load the integration")
 
     def _check_unused_scopes(self):
         """Check for potentially unused scopes."""