Add ADB APK sideload tool

AGENTS.md

@@ -0,0 +1,31 @@
+# Agent Guide
+
+## Project Shape
+
+- This is a small Python project: the runtime entrypoint is `src/sideload.py`; tests are in `tests/test_sideload.py`.
+- The package requires Python 3.11+ because configuration is parsed with the standard-library `tomllib`.
+- The `sideload` console command is declared in `pyproject.toml`; install the project editable before using it from a checkout.
+
+## Setup And Commands
+
+- Recommended setup: `python -m venv .venv && .venv/bin/pip install -e .`.
+- Run the full test suite with `python -m pytest tests -q` or `python -m pytest tests/ -v`.
+- Run the CLI help after editable installation with `.venv/bin/sideload --help`.
+- Use `config.example.toml` as the template and copy it to the Git-ignored `config.toml`; do not add a real configuration containing local devices or app choices.
+- No linter, formatter, type checker, code generator, or CI workflow is configured; tests and `python -m compileall -q src tests` are the available local checks.
+
+## Runtime Constraints
+
+- Real installations require both `adb` and `apkanalyzer` in `PATH`; tests must continue to mock them rather than require a phone or Android SDK.
+- `apkanalyzer manifest application-id` is a mandatory pre-install validation; never add an installation path that bypasses package-ID validation.
+- ADB commands must remain argument lists passed with `shell=False`; do not construct shell command strings or use `shell=True`.
+- Multiple connected ADB devices require explicit interactive selection or `--device/-s`; never silently choose the first device.
+- Wi-Fi ADB uses an explicit `HOST:PORT` from `[adb]`; do not add network scanning or implicit device discovery.
+- Downloads are HTTPS-only and cached under the configured cache directory; preserve SHA-256 checks and atomic temporary-file downloads.
+
+## Source And Test Details
+
+- Application entries use `name`, `package`, `source`, and `url`; GitHub/GitLab entries may need `asset_pattern` when a release has multiple APKs.
+- F-Droid resolution reads `index-v2.json` and versions are nested under `packages[package].versions`; keep numeric `versionCode` ordering and correct URL joining.
+- GitHub and GitLab release parsing must reject ambiguous APK assets instead of selecting arbitrarily; do not treat GitLab source archives as APKs.
+- Network, ADB, and `apkanalyzer` behavior is mocked in the unit tests; add response fixtures or mocks for new integrations instead of live API tests.