chore: cleanup wave-2 (tomte, tox.ini, CI lint, slim docs)

.github/workflows/python-tests.yml

@@ -321,6 +321,28 @@ jobs:
         name: unit-test-coverage-xml-${{ matrix.python-version }}
         path: coverage-unit.xml
 
+  linter_checks:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - uses: astral-sh/setup-uv@v6
+      # `uv sync` picks up `tomte` + `tox-uv` from the dev group in
+      # pyproject.toml, so the pins stay in one place (matches the
+      # `unit-tests` job at line 304). `uv run tomte tox` then resolves
+      # the lint envs the same way contributors do locally.
+      - name: Install project dependencies
+        run: uv sync --all-groups --frozen
+      - name: Code checks
+        run: uv run tomte tox -p -e black-check -e isort-check -e flake8 -e mypy -e pylint -e darglint
+      - name: Security checks
+        run: uv run tomte tox -p -e safety -e bandit
+      - name: License compatibility check
+        run: uv run tomte tox -e liccheck
+
   all-checks-passed:
     # Single aggregate gate referenced by branch protection. When adding or
     # removing a mandatory job, update the `needs:` list here instead of
@@ -335,6 +357,7 @@ jobs:
       - changes
       - e2e-test-migrate-to-pearl
       - unit-tests
+      - linter_checks
     steps:
       - name: Verify all dependencies succeeded or were skipped
         run: |

.gitignore

@@ -17,4 +17,10 @@ logs
 .idea/
 .coverage
 coverage-*.xml
-htmlcov/
+htmlcov/
+
+# tox / setuptools artefacts (built by `tomte tox` testenvs that
+# run an editable install of the project)
+.tox/
+*.egg-info/
+.tomte-*

CONTRIBUTING.md

@@ -1,63 +1,25 @@
 # Contributing to OLAS AI Agents Quickstart
 
-## How to Contribute
-
-### Before You Start
-
-1. **Open an Issue First**: Before starting work on a feature, bug fix, or significant change, please [open an issue](https://github.com/valory-xyz/quickstart/issues) to discuss your idea with the maintainers. This helps ensure your contribution aligns with the project's direction and avoids duplicate work.
-
-2. **Check Existing Issues**: Review open and closed issues to see if your concern has already been discussed.
-
-### Contribution Areas
-
-We welcome contributions in the following areas:
-
-- **`configs/`**: Agent configurations and setup files
-- **`scripts/`**: Agent-specific scripts and utilities
-- **`tests/`**: Test cases and testing improvements
-
-### Git Workflow
-
-We follow a standard git workflow:
-
-1. **Create a Branch**: Create a feature branch from `main`
-   ```bash
-   git checkout -b feature/your-feature-name
-   ```
-
-2. **Make Your Changes**: Implement your changes following the guidelines below
-
-3. **Commit Your Work**: Make clear, descriptive commits
-   ```bash
-   git commit -m "Brief description of your changes"
-   ```
-
-4. **Push and Create a PR**: Push your branch and create a pull request
-   ```bash
-   git push origin feature/your-feature-name
-   ```
-
-5. **Code Review**: Address any feedback from reviewers
-
-6. **Merge**: Once approved, your PR will be merged into `main`
-
-### Code Quality
-
-- **CI Checks**: All code changes are validated through CI checks. Ensure your changes pass all automated checks (linting, testing, etc.)
-- **Local Testing**: While not required, testing your changes locally is recommended
-- **Documentation**: Include or update documentation as needed for new features or changes
-
-### Commit Guidelines
-
-- Use clear, descriptive commit messages
-- Reference related issues when applicable: `Fixes #123` or `Related to #123`
-- Keep commits focused on a single logical change
-
-## Questions?
-
-If you have questions or need clarification:
-- Check existing [issues](https://github.com/valory-xyz/quickstart/issues) and [PRs](https://github.com/valory-xyz/quickstart/pulls)
-- Open a new issue with your question
+This repository follows the Valory Open-Autonomy contribution workflow.
+
+See the canonical guide for the PR checklist, pre-commit routine,
+coding style, and linter / test commands:
+**[open-autonomy/CONTRIBUTING.md](https://github.com/valory-xyz/open-autonomy/blob/main/CONTRIBUTING.md)**
+
+Repo-specific notes for this project:
+
+- **Scope**: contributions are welcome in `configs/` (agent configs),
+  `scripts/` (agent-specific scripts), and `tests/`.
+- **Open an issue first** for any non-trivial change so it can be
+  discussed before you spend time on it.
+- **Run lint locally** with `uv run tomte tox -p -e black-check -e
+  isort-check -e flake8 -e mypy -e pylint -e darglint -e safety -e
+  bandit -e liccheck`. CI runs the same set.
+- **Run unit tests locally** with `PYTHONPATH=. uv run pytest tests
+  --ignore=tests/test_run_service.py
+  --ignore=tests/test_staking_service.py
+  --ignore=tests/test_migrate_to_pearl.py`. The ignored files are
+  e2e tests that need Docker and live RPC secrets.
 
 ## Guide for the AI agent `config.json`
 

pyproject.toml

@@ -27,20 +27,51 @@ dependencies = [
 [dependency-groups]
 dev = [
     "pexpect==4.9.0",
-    "pytest==9.0.3",
-    "pytest-cov==7.1.0",
+    "tomte[cli, tests]==0.7.0",
+    "tox-uv==1.16.0",
 ]
+# Note: pytest, pytest-cov and pytest-asyncio are brought in by
+# tomte[tests] at pinned versions (pytest==8.4.2, pytest-cov==7.0.0,
+# pytest-asyncio==1.3.0). Don't pin them separately or uv will
+# refuse to resolve.
 
 [tool.uv]
 package = false
 default-groups = "all"
 
+# Some tomte testenvs (pylint, py3.x) trigger an editable install via tox.
+# Without a build-system block setuptools falls back to flat-layout
+# auto-discovery and trips on `data/`, `images/`, `configs/` at repo root.
+# Declare an empty package set so the build is a no-op.
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = []
+
+[tool.tomte]
+tomte_dep_pin = "==0.7.0"
+# Quickstart has no Valory `packages/<author>/...` tree (it consumes
+# pre-published packages via `olas-operate-middleware`). Lint scope
+# is `scripts/` only — `tests/` is excluded from lint following
+# trader's pattern (production code lints, tests don't).
+packages_paths = "."
+service_specific_packages = ["scripts"]
+pytest_targets = ["tests"]
+
 [tool.pytest.ini_options]
-# anchorpy ships a pytest plugin (via open-autonomy -> open-aea-ledger-solana ->
-# anchorpy) that imports pytest_xprocess at startup, but xprocess is only in
-# anchorpy's [pytest] extra and is never installed. Disable the plugin so
-# pytest can boot.
-addopts = "-p no:pytest_anchorpy"
+# `-p no:pytest_anchorpy`: anchorpy ships a pytest plugin (via
+#   open-autonomy -> open-aea-ledger-solana -> anchorpy) that imports
+#   pytest_xprocess at startup, but xprocess is only in anchorpy's
+#   [pytest] extra and is never installed. Disabling the plugin lets
+#   pytest boot.
+# `-p no:randomly`: tomte[tests] pulls in pytest-randomly which shuffles
+#   test order by default. tests/test_migrate_to_pearl.py uses numeric
+#   `test_NN_*` naming because each test depends on state set up by the
+#   previous one (e.g. test_03_*_mode_b asserts pearl_home from
+#   test_02_*_mode_a). Disable the plugin so the sequential order holds.
+addopts = "-p no:pytest_anchorpy -p no:randomly"
 markers = [
     "e2e: end-to-end tests that may use real network/external systems",
     "integration: integration tests that may use networked dependencies",

scripts/optimus/README.md

@@ -15,8 +15,8 @@ If you were previously using [optimus-quickstart](https://github.com/valory-xyz/
 2. Run the migration script to create the new `.operate` folder compatible with unified quickstart:
 
     ```bash
-    poetry install
-    poetry run python -m scripts.optimus.migrate_legacy_optimus configs/config_optimus.json
+    uv sync
+    uv run python -m scripts.optimus.migrate_legacy_optimus configs/config_optimus.json
     ```
 
 3. Follow the prompts to complete the migration process. The script will: