GRM-53: refactor: enforce script separation and document import rules

AGENTS.md

@@ -237,15 +237,14 @@ types from accidentally skipping releases.
 - `hooks/**` — Git hooks
 
 **User-facing paths** (tool changes → release needed) — everything else:
-- `src/gitea_runner_manager/**` — Python CLI source
+- `src/gitea_runner_manager/**` — Python CLI source (except `__init__.py` and `api_clients.py`)
 - `ansible/**` — Ansible role
 - `pyproject.toml` — Package metadata
-- `scripts/check_test_speed.py`, `scripts/configure_repo.py`, `scripts/install_checkmake.py` — Dev tools
 - Any new file type not in the allowlist
 
 **Script directory structure:**
-- `scripts/` — Dev tools (run locally by developers): `check_test_speed.py`, `configure_repo.py`, `install_checkmake.py`, `install_tools.py`, `setup.py`, `molecule_all.py`
-- `scripts/ci/` — CI/CD automation (run by workflows): `release.py`, `publish.py`, `auto_merge.py`, `classify_changes.py`, `detect_release_commit.py`, `push_badges.py`, `doc_coverage.py`, `sync_wiki.py`, etc.
+- `scripts/` — Dev tools (run locally by developers): `check_test_speed.py`, `configure_repo.py`, `install_checkmake.py`, `install_tools.py`, `setup.py`, `molecule_all.py`, `generate_badges.py`
+- `scripts/ci/` — CI/CD automation (run by workflows): `release.py`, `publish.py`, `auto_merge.py`, `classify_changes.py`, `detect_release_commit.py`, `push_badges.py`, `doc_coverage.py`, `sync_wiki.py`, `distribute_molecule.py`, `molecule_ci_guard.py`, `discover_runners.py`, `notify_failure.py`, `post_merge.py`, `pr_review.py`, `review_pr.py`, `validate_commit_msg.py`, `platforms.py`
 
 **CI behavior based on classification:**
 - **Molecule tests**: Only run when `ansible/` or `.ansible-lint` files change
@@ -259,6 +258,52 @@ types from accidentally skipping releases.
 - The `classify_changes.py` script enforces this automatically — no manual intervention needed
 - When adding a new CI script, place it in `scripts/ci/`. Dev tools go in `scripts/`.
 
+## Script Separation and Import Rules
+
+The codebase enforces strict separation between the GRM tool and CI/dev scripts:
+
+### Directory Layout
+
+| Directory | Purpose | Release impact |
+|-----------|---------|----------------|
+| `src/gitea_runner_manager/` | User-facing GRM CLI tool | Changes trigger release |
+| `scripts/` | Dev tools (run locally) | Workflow-only (no release) |
+| `scripts/ci/` | CI/CD automation (run by workflows) | Workflow-only (no release) |
+| `ansible/` | Ansible role for runner setup | Changes trigger release |
+
+### Import Rules
+
+1. **`src/gitea_runner_manager/` NEVER imports from `scripts/`** — the tool is self-contained
+2. **Scripts MAY import from `gitea_runner_manager`** — one-way dependency (scripts use the tool's API clients, config, i18n)
+3. **Cross-script imports** (scripts importing from other scripts) are allowed within `scripts/ci/` but must be documented
+
+### PYTHONPATH Configuration
+
+Scripts have different import requirements. Workflows must set `PYTHONPATH` accordingly:
+
+| PYTHONPATH | When to use | Example scripts |
+|------------|-------------|-----------------|
+| `src` | Script imports from `gitea_runner_manager` | `auto_merge.py`, `pr_review.py`, `notify_failure.py`, `sync_wiki.py`, `post_merge.py`, `publish.py`, `classify_changes.py`, `discover_runners.py`, `doc_coverage.py` |
+| `.` | Script imports from other `scripts.ci.*` modules | `release.py` (imports `classify_changes.has_user_facing_changes`) |
+| (none) | Script has no GRM or cross-script imports | `detect_release_commit.py`, `distribute_molecule.py`, `molecule_ci_guard.py`, `push_badges.py`, `validate_commit_msg.py` |
+
+**In workflows**, always use `env:` blocks (not inline `PYTHONPATH=value`):
+```yaml
+- name: Run script
+  env:
+    PYTHONPATH: src
+  run: python3 scripts/ci/example.py
+```
+
+**Locally**, the current directory is in `sys.path` by default, so `PYTHONPATH` is usually not needed.
+
+### Shared Constants
+
+`scripts/ci/platforms.py` is the single source of truth for the molecule
+platform matrix. Both `scripts/ci/distribute_molecule.py` (CI) and
+`scripts/molecule_all.py` (dev tool) import `PLATFORMS` from it — this
+avoids dev tools importing directly from CI scripts.
+
 2. **Publish workflow** (`.gitea/workflows/publish.yml`):
    - Triggers on tag push (`v*`)
    - Validates `PYPI_TOKEN` is set (warns if missing)
@@ -319,7 +364,7 @@ main.yml → systemd_check → user_setup → rootless_docker → install_runner
 
 6 scenarios: `default`, `multi-instance`, `lifecycle`, `template-content`, `deregister`, `update`
 4 platforms: `ubuntu-2204`, `ubuntu-2404`, `debian-12`, `archlinux`
-Platform list is defined in `scripts/ci/distribute_molecule.py` (single source of truth)
+Platform list is defined in `scripts/ci/platforms.py` (single source of truth)
 
 ## Known Issues