docs: require env example updates in integration skills (#44)

* docs: require env example updates in integration test skill

* docs: reinforce env example requirement across skills

Author: TheRealAgentK

skills/building-integration/SKILL.md

@@ -141,16 +141,22 @@ pytest <name>/ -v
 
 Only runs tests in `test_*_unit.py` files (configured in `pyproject.toml`).
 
-### Step 5 — Auto-fix lint and formatting issues
+### Step 5 — Verify `.env.example` for integration-test env vars
 
-If steps 2–4 report ruff errors, auto-fix with:
+If the integration has `test_*_integration.py` files, check whether they reference environment variables via `env_credentials(...)`, `os.environ.get(...)`, `os.getenv(...)`, `os.environ[...]`, or equivalent helpers. Every referenced variable must appear as a blank template entry in the repository root `.env.example`.
+
+This is a manual review/build requirement: `.env` stays local and uncommitted, but `.env.example` is the committed contract that tells humans, reviewers, and automation what to provide.
+
+### Step 6 — Auto-fix lint and formatting issues
+
+If steps 2–5 report ruff errors, auto-fix with:
 
 ```bash
 ruff check --fix --config ../autohive-integrations-tooling/ruff.toml <name>
 ruff format --config ../autohive-integrations-tooling/ruff.toml <name>
 ```
 
-Then re-run steps 2–4 to confirm.
+Then re-run steps 2–5 to confirm.
 
 ## Ruff Configuration
 
@@ -169,8 +175,9 @@ Key settings:
 2. Validate structure → `python ../autohive-integrations-tooling/scripts/validate_integration.py <name>`
 3. Check code → `python ../autohive-integrations-tooling/scripts/check_code.py <name>`
 4. Run tests → `pytest <name>/ -v`
-5. Fix issues → `ruff check --fix ...` / `ruff format ...`
-6. Re-run until all pass
+5. Verify integration-test env vars are listed in root `.env.example` (if applicable)
+6. Fix issues → `ruff check --fix ...` / `ruff format ...`
+7. Re-run until all pass
 
 ## Interpreting Output
 
@@ -194,3 +201,4 @@ Key settings:
 | Config-code sync | Ensure actions in `config.json` match handlers in source code |
 | Missing test files | Create `tests/test_<name>_unit.py` (see `writing-unit-tests` skill) |
 | Import errors | Check `requirements.txt` has all dependencies; check `__init__.py` exports |
+| Integration tests use env vars but `.env.example` missing entries | Add blank entries for every referenced env var to root `.env.example` |

skills/migrating-private-integration/SKILL.md

@@ -121,6 +121,7 @@ The private repo accumulates files that don't belong in the public repo. Drop th
 | `__pycache__/`, `.pytest_cache/`, `.ruff_cache/` | Build artefacts. |
 | Internal-only documentation (`INTERNAL.md`, `RUNBOOK.md` referencing internal infra) | Keep in private repo or rewrite without internal references. |
 | `.env*` files | Should not exist anywhere; if they do, abort Step 1. |
+| Migrated integration tests reference env vars but root `.env.example` was not updated | Add blank entries for every referenced env var in the public repo's root `.env.example`. |
 
 ## Step 3 — Copy and adapt files
 
@@ -152,6 +153,7 @@ cp ../integrations/<name>/tests/test_*.py      ../autohive-integrations/<name>/t
   - `## Usage Examples` (1–3 realistic JSON examples)
   - `## Testing`
 - Strip any internal references (Slack channels, Notion links, employee names) from the README before copying.
+- **Root `.env.example`** → if migrated tests read environment variables, add every required and optional test variable to the public repo's root `.env.example` in the same PR. Include variables read through `env_credentials(...)`, `os.environ.get(...)`, `os.getenv(...)`, `os.environ[...]`, or equivalent helpers. Do **not** copy private `.env*` files; only add blank template entries such as `MYINTEGRATION_ACCESS_TOKEN=` and `MYINTEGRATION_TEST_ITEM_ID=`.
 
 ### Update the repo-level READMEs
 
@@ -173,6 +175,7 @@ Required outcome:
 - `validate_integration.py` → `0` exit code (warnings about deprecated SDK pin are OK for a pure migration).
 - `check_code.py` → `✅ CODE CHECK PASSED`.
 - `pytest` → no failures (placeholder tests are fine; new tests are out of scope for a migration).
+- If migrated tests reference env vars, root `.env.example` includes all of them as blank template entries.
 
 If anything fails, fix with:
 

skills/upgrading-sdk-v2/SKILL.md

@@ -210,6 +210,8 @@ async def real_fetch(url, *, method="GET", json=None, headers=None, **kwargs):
             )
 ```
 
+If the integration tests read credentials or test resource IDs from environment variables, also verify the repository root `.env.example` lists every variable used by those tests. Add missing entries in the same PR. This applies to variables read through `env_credentials(...)`, `os.environ.get(...)`, `os.getenv(...)`, `os.environ[...]`, or equivalent helpers. The local `.env` file remains uncommitted; `.env.example` is the committed setup contract for humans and tooling.
+
 ### Step 7 — Local validation (required before pushing)
 
 Run the **same checks CI runs** locally. Skipping this step will result in CI failures. The tooling repo must be cloned alongside the integrations repo (see [CONTRIBUTING.md](CONTRIBUTING.md) for setup).
@@ -263,6 +265,7 @@ Before considering an integration upgraded, verify:
 - [ ] Unit test error assertions use `result.type == ResultType.ACTION_ERROR` and `result.result.message`
 - [ ] `pytest.raises(ValidationError)` replaced with `result.type == ResultType.VALIDATION_ERROR`
 - [ ] Integration test `real_fetch` returns `FetchResponse(...)` (if applicable)
+- [ ] Integration test env vars are documented in root `.env.example` (if integration tests read env vars)
 - [ ] `FetchResponse` and `ResultType` are imported where needed
 - [ ] All unit tests pass
 - [ ] `ruff check` and `ruff format --config ../autohive-integrations-tooling/ruff.toml` pass
@@ -299,3 +302,5 @@ Before considering an integration upgraded, verify:
     The 2.0.0 upgrade is the right time to catch this because you're already touching the auth path to convert error returns to `ActionError`.
 
 10. **PyPI package name collision**: If your integration folder name matches a PyPI package the source imports (e.g. an integration in `supadata/` that does `from supadata import Supadata`), an empty `<integration>/__init__.py` will shadow the real PyPI package and every test fails with `ImportError`. Drop `<integration>/__init__.py` — the validator's "missing __init__.py" warning is correct to ignore in this case, and the Lambda runtime is unaffected (the entry point is the action source file, not the package). See the `writing-unit-tests` skill for the matching test-side guidance.
+
+11. **Missing `.env.example` entries after touching integration tests**: SDK upgrades often touch `live_context` and credential handling. If the integration test file references `FOO_ACCESS_TOKEN`, `FOO_TEST_ID`, or similar, root `.env.example` must contain `FOO_ACCESS_TOKEN=`, `FOO_TEST_ID=`, etc. Do not rely on future contributors or automation to grep test code for setup requirements.

skills/writing-integration-tests/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: writing-integration-tests
-description: "Writes pytest end-to-end integration tests for an Autohive integration that call real APIs using the live_context fixture pattern. Use when asked to write integration tests, add e2e tests, create live API tests, or test an integration against a real service. Covers file structure, live_context fixture variants, environment variable handling, destructive markers, and test organization."
+description: "Writes pytest end-to-end integration tests for an Autohive integration that call real APIs using the live_context fixture pattern. Use when asked to write integration tests, add e2e tests, create live API tests, or test an integration against a real service. Covers file structure, live_context fixture variants, required root .env.example updates, environment variable handling, destructive markers, and test organization."
 ---
 
 # Writing Integration Tests for an Integration
@@ -125,9 +125,18 @@ class TestGetItem:
         ...
 ```
 
-### .env.example Documentation
+### .env.example Documentation (required)
 
-Document all required and optional environment variables in the integration's `.env.example`:
+If an integration test reads any environment variable, you **must** add that variable to the repository root `.env.example` in the same PR. This is not optional documentation — it is part of the integration-test deliverable.
+
+Why this matters:
+- Humans can set up local integration tests without digging through test code for variable names.
+- Automated and AI tooling can discover which credentials, test IDs, and optional knobs it needs to ask for.
+- Reviewers have one canonical place to verify the local test contract.
+
+Add every variable used by `env_credentials(...)`, `os.environ.get(...)`, `os.getenv(...)`, `os.environ[...]`, or equivalent helpers. Include both required credentials and optional test resource IDs. Keep real secrets only in local `.env`; never commit `.env`.
+
+Use a clearly labeled block in root `.env.example`:
 
 ```bash
 # -- MyIntegration --
@@ -136,6 +145,8 @@ MYINTEGRATION_TEST_ITEM_ID=
 MYINTEGRATION_TEST_PROJECT_ID=
 ```
 
+Before finishing, cross-check the integration test file against `.env.example`: every env var referenced in tests must appear in `.env.example`, even if the test skips when it is missing.
+
 ## The live_context Fixture
 
 The `live_context` fixture provides a `MagicMock` of the SDK's `ExecutionContext` but replaces the `fetch` method with a real async HTTP client using `aiohttp`. This lets the integration code run unchanged while making real network calls.
@@ -455,7 +466,7 @@ Write actions (create/update/delete) need at least:
 1. **Read the integration source** — understand each action and its auth mechanism
 2. **Check `config.json`** — determine auth type (none / API key / platform OAuth)
 3. **Choose the right `live_context` variant** — see the three variants above
-4. **Document env vars** in `.env.example`
+4. **Document env vars in root `.env.example` (required)** — add every env var referenced by the integration test file in the same PR
 5. **Write read-only tests first** — these are safe to run repeatedly
 6. **Add destructive tests** with `@pytest.mark.destructive` for write actions
 7. **Run read-only tests**:
@@ -483,7 +494,9 @@ Write actions (create/update/delete) need at least:
 
 5. **Destructive test cleanup**: Always clean up created data at the end of lifecycle tests. Use `os.getpid()` in created object names to avoid collisions when running tests in parallel.
 
-6. **OAuth token expiry**: Platform OAuth tokens expire. Document the refresh process in the integration's README or `.env.example`.
+6. **Missing `.env.example` entries**: If you add `env_credentials("FOO")`, `os.environ.get("FOO")`, or similar test env-var usage, add `FOO=` to root `.env.example` before you commit. Do not make reviewers or future contributors grep test files to discover setup requirements.
+
+7. **OAuth token expiry**: Platform OAuth tokens expire. Document the refresh process in the integration's README or root `.env.example`.
 
 ## Reference Implementations