scry-connect 0.1.0__tar.gz

scry_connect-0.1.0/.gitignore

@@ -0,0 +1,118 @@
+# Shared .gitignore baseline. Each repo extends this with its own
+# language/toolchain-specific entries (Python in scry-connect,
+# Gradle/Android in scry-android, etc.)
+
+# ── OS / editor noise ──────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+ehthumbs.db
+desktop.ini
+
+# JetBrains
+.idea/
+*.iml
+*.iws
+
+# VS Code
+.vscode/
+*.code-workspace
+
+# Vim / Emacs
+*.swp
+*.swo
+*~
+\#*\#
+.\#*
+
+# Sublime
+*.sublime-project
+*.sublime-workspace
+
+# ── Build / dependency artefacts ──────────────────────────────────
+node_modules/
+.cache/
+.tmp/
+.temp/
+*.log
+logs/
+
+# ── Secrets — NEVER commit ────────────────────────────────────────
+.env
+.env.*
+!.env.example
+!.env.sample
+*.pem
+*.key
+*.jks
+*.keystore
+*.p12
+*.p8
+*.mobileprovision
+secrets/
+credentials/
+
+# ── Test / coverage ───────────────────────────────────────────────
+.coverage
+.coverage.*
+htmlcov/
+coverage/
+.nyc_output/
+*.lcov
+
+# ── Misc ──────────────────────────────────────────────────────────
+*.orig
+*.bak
+*.rej
+
+# ── Python ─────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+.python-version
+
+# pytest
+.pytest_cache/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+
+# ruff
+.ruff_cache/
+
+# core dumps (e.g. from a crashed ros2 process)
+core
+core.*
+
+# rosbags + recordings
+*.db3
+*.mcap
+rosbag2_*/
+
+# Generated by hatch-vcs at build time.
+scry_connect/_version.py

scry_connect-0.1.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to **scry-connect** are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Pre-commit hook configuration (ruff + ruff-format + generic hygiene
+  checks). Install with `pip install pre-commit && pre-commit install`.
+- CI workflow on pull requests to `master`: lint (ruff) + build (sdist
+  + wheel).
+- Release workflow on `v*` tags: builds + publishes to PyPI / TestPyPI
+  via OIDC Trusted Publishing, pushes Docker image to GHCR, creates a
+  GitHub Release with sdist + wheel attached.
+- `Dockerfile` based on `ros:jazzy-ros-base` so rclpy + message types
+  ship inside the image.
+- Apache 2.0 LICENSE, NOTICE, SECURITY.md, CONTRIBUTING.md, GitHub
+  issue + PR templates.
+- ROS_DOMAIN_ID and ROS_DISTRO surfaced on the `/health` endpoint so
+  the Android discovery scan can distinguish multiple connects running
+  on the same host under different domains.
+- mDNS instance name now includes the port (`<host>-<port>`) so two
+  connects on the same machine don't collide on registration.
+
+### Changed
+- Project metadata polished for PyPI: author/maintainer separated,
+  full classifier list, project URLs, hatchling targets.
+- Bulk lint + format pass to bring the codebase under ruff's check.
+- Switched to dynamic versioning via `hatch-vcs`. Git tags like
+  `v0.1.0-beta.3` become PEP-440 `0.1.0b3` automatically; the version
+  is stamped into `scry_connect/_version.py` at build time.
+
+### Fixed
+- Dockerfile: use UID 1001 for the `scry` user. UID 1000 collided
+  with the `ubuntu` user that ships in `ros:jazzy-ros-base`.
+- Release workflow: `fetch-depth: 0` on the build-dist checkout so
+  hatch-vcs sees the git tag history.
+- Docker workflow: install from the pre-built wheel artefact instead
+  of from source. Source installs inside the image fail because
+  `.git` isn't in the build context (which hatch-vcs needs).
+- SSE stream no longer crashes when a topic uses an unknown ROS
+  message type (e.g. `nav2_msgs/action/NavigateToPose_FeedbackMessage`).
+  The handler now emits a clean `event: error` SSE frame.
+
+## [0.1.0] — unreleased
+
+Initial release. See README.md for features and install instructions.

scry_connect-0.1.0/CHANGELOG.rst

@@ -0,0 +1,48 @@
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Changelog for package scry_connect
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This file is the ROS-specific changelog consumed by bloom-release when
+building Debian packages. ``CHANGELOG.md`` is the source-of-truth for
+PyPI / GHCR / GitHub Releases; both files are kept in sync but use
+different formats because bloom and PyPI / GitHub each expect their
+own conventions.
+
+0.1.0 (2026-05-16)
+------------------
+
+Initial release.
+
+* MCP (Model Context Protocol) server that exposes the ROS 2 graph
+  (topics, nodes, services, parameters, actions, lifecycle states,
+  diagnostics) as AI-callable tools.
+* Pairs with the Scry Android app for natural-language robot
+  debugging — the AI proposes a tool call, the user approves, the
+  connect dispatches.
+* HTTP + SSE transport for low-overhead streaming of topic data.
+* Three auth modes:
+
+  * **open** — no token, LAN-only filter (default; mirrors
+    ``rosbridge`` / ``foxglove_bridge``)
+  * **token** — bearer token over HTTPS, QR pairing for the app
+  * **mTLS** — client-cert authentication for production deployments
+
+* Write tools (publish, set parameter, lifecycle transition,
+  controller switch, etc.) require an explicit ``X-Scry-Confirm``
+  nonce minted by the app after the user approves the proposed
+  call.
+* Token-bucket rate limiting (default 10 calls/sec) prevents
+  runaway AI loops from overwhelming the robot.
+* mDNS / Zeroconf advertisement (``_scry._tcp.local.``) so the
+  Android app auto-discovers connects on the LAN.
+* ``/health``, ``/mcp``, ``/stream``, ``/tools/categories``,
+  ``/auth/print_qr`` endpoints.
+* Supports ROS 2 Jazzy, Humble, and Rolling; DDS-agnostic
+  (Fast-DDS, CycloneDDS, Connext, Zenoh).
+* Distribution:
+
+  * ``apt install ros-jazzy-scry-connect`` (this changelog's audience)
+  * ``pip install scry-connect`` (PyPI)
+  * ``docker run ghcr.io/phaneron-robotics/scry-connect`` (GHCR)
+
+* See ``CHANGELOG.md`` for the granular PR-by-PR development history.

scry_connect-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may accept and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Phaneron Robotics, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

scry_connect-0.1.0/NOTICE

@@ -0,0 +1,5 @@
+Scry
+Copyright 2026 Phaneron Robotics, Inc.
+
+This product includes software developed at
+Phaneron Robotics, Inc. (https://www.phaneronrobotics.com/).

scry_connect-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: scry-connect
+Version: 0.1.0
+Summary: MCP server for ROS 2 — exposes robot capabilities as AI-callable tools
+Project-URL: Homepage, https://github.com/phaneron-robotics/scry
+Project-URL: Documentation, https://phaneron-robotics.github.io/scry-docs/
+Project-URL: Repository, https://github.com/phaneron-robotics/scry-connect
+Project-URL: Issues, https://github.com/phaneron-robotics/scry-connect/issues
+Project-URL: Changelog, https://github.com/phaneron-robotics/scry-connect/blob/master/CHANGELOG.md
+Author-email: "Phaneron Robotics, Inc." <info@phaneronrobotics.com>
+Maintainer-email: Deep Kotadiya <deep@phaneronrobotics.com>
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agent,ai,debugging,fleet,introspection,mcp,rclpy,robotics,ros2
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: qrcode>=7.4
+Requires-Dist: sse-starlette>=1.8.0
+Requires-Dist: starlette>=0.36.0
+Requires-Dist: uvicorn>=0.27.0
+Requires-Dist: zeroconf>=0.131
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.2.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# scry-connect
+
+MCP server for ROS 2 — exposes your robot's topics, nodes, services, parameters, actions, diagnostics, and introspection tools to AI agents.
+
+Pairs with the Scry Android app.
+
+## Install
+
+Pick the path that matches how your robot is deployed. All three install
+the same `scry-connect` from PyPI — they just package it differently.
+
+### Option A — one-line installer (Docker or bare-metal, auto-detect)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/phaneron-robotics/scry-connect/master/install.sh | bash
+```
+
+The script detects your ROS distro, picks Docker if available else pip,
+writes a systemd `--user` unit, starts the service, and prints a
+pairing QR. Re-running upgrades in place. Mode override:
+`SCRY_INSTALL_MODE=docker bash` or `SCRY_INSTALL_MODE=pip bash`.
+
+### Option B — sidecar Docker container
+
+Drop into your existing `docker-compose.yml`:
+
+```yaml
+services:
+  scry-connect:
+    image: ghcr.io/phaneron-robotics/scry-connect:${ROS_DISTRO:-jazzy}
+    network_mode: host
+    ipc: host
+    pid: host
+    restart: unless-stopped
+    environment:
+      - ROS_DOMAIN_ID=${ROS_DOMAIN_ID:-0}
+    volumes:
+      - scry_config:/home/scry/.config/scry
+      - scry_audit:/var/log/scry
+
+volumes:
+  scry_config:
+  scry_audit:
+```
+
+A turnkey reference compose with every tunable surfaced lives at
+[docker/docker-compose.yml](docker/docker-compose.yml).
+
+| Tag | Resolves to |
+|-----|------|
+| `:humble`, `:jazzy`, `:kilted`, `:rolling` | Per-ROS-distro images (multi-arch: amd64 + arm64) |
+| `:0.1.0-jazzy` | Pinned version on jazzy |
+| `:latest` | Most recent stable release on the LTS distro (jazzy today) |
+
+### Option C — add scry-connect to your own robot image
+
+If you already publish a robot Docker image, append one line to your
+Dockerfile and run `scry-connect` alongside your existing nodes:
+
+```dockerfile
+RUN pip install scry-connect
+```
+
+No second ROS install required — `scry-connect` uses the `rclpy`
+that's already in your image.
+
+### Option D — bare-metal pip (no Docker)
+
+```bash
+source /opt/ros/$ROS_DISTRO/setup.bash
+pip install --user scry-connect
+scry-connect
+```
+
+A reference [systemd user unit](install.sh) is written automatically
+by Option A in pip mode.
+
+Prereleases (alpha / beta / rc) live on TestPyPI:
+
+```bash
+pip install -i https://test.pypi.org/simple/ scry-connect
+```
+
+## Run
+
+```bash
+# Defaults to 0.0.0.0:5339 in open mode (LAN-only, no token).
+scry-connect
+
+# Common overrides
+scry-connect --port 5339 --log-level INFO
+scry-connect --token              # token mode; prints QR for the phone
+scry-connect --mtls               # client-cert mode
+scry-connect --skip-ros-check     # smoke test without rclpy
+```
+
+## Endpoints
+
+| Path | Method | Description |
+|------|--------|-------------|
+| `/mcp` | POST/GET | MCP JSON-RPC (Streamable HTTP) |
+| `/stream?topic=/odom&rate=10` | GET | SSE topic stream |
+| `/health` | GET | Health check |
+
+## Tools exposed
+
+22 tools grouped into: Topics, Nodes, Services, Parameters, Actions, Diagnostics, Logs, Introspection, System. See [docs/mcp-tools-reference.md](../docs/mcp-tools-reference.md).
+
+## Config (env vars)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SCRY_HOST` | `0.0.0.0` | Bind address |
+| `SCRY_PORT` | `5339` | HTTP port |
+| `SCRY_RATE_LIMIT` | `10` | Tool calls per second |
+| `SCRY_LOG_LEVEL` | `INFO` | Log level |
+| `SCRY_AUTH_MODE` | `open` | `open` \| `token` \| `mtls` |
+| `SCRY_TOKEN` | (unset) | Force token mode with this shared token |
+| `SCRY_PUBLIC_INTERNET` | `0` | In open mode, accept non-LAN callers |
+| `SCRY_REQUIRE_DEADMAN` | `0` | Writes need `/scry/enable` heartbeat |
+| `SCRY_AUDIT_LOG` | (unset) | Append JSONL audit trail to this path |
+| `SCRY_MDNS` | `1` | Advertise `_scry._tcp` via Zeroconf |
+| `ROS_DOMAIN_ID` | (inherited) | ROS 2 domain ID |
+| `RMW_IMPLEMENTATION` | (inherited) | DDS/RMW implementation |
+
+## Development
+
+### Setup
+
+```bash
+# Editable install + dev dependencies
+pip install -e ".[dev]"
+
+# Install pre-commit hooks (run once per fresh clone)
+pip install pre-commit
+pre-commit install
+```
+
+After `pre-commit install`, every `git commit` automatically runs `ruff`
+(auto-fix) + `ruff format` on the staged Python files. If anything was
+fixed, the commit is rejected — `git add` the fixes and commit again.
+
+### Manual lint commands
+
+```bash
+# Run pre-commit against every file (not just staged)
+pre-commit run --all-files
+
+# Run ruff directly
+ruff check scry_connect tests          # report issues
+ruff check --fix scry_connect tests    # auto-fix what can be fixed
+ruff format scry_connect tests         # apply formatter
+```
+
+### Tests
+
+```bash
+pytest tests/
+```
+
+Note: many tests require a working ROS 2 environment (rclpy). In CI we
+only run lint + build; tests run on a real robot or local ROS 2 install.
+
+### CI / release pipeline
+
+| Workflow | Trigger | What it does |
+|----------|---------|--------------|
+| **CI** | PR to master, push to master, manual | ruff check + format check, `python -m build` (sdist + wheel) |
+| **Release** | Tag matching `v*`, manual | Build, publish to PyPI / TestPyPI (Trusted Publishing — no API key needed), push to `ghcr.io/phaneron-robotics/scry-connect`, create GitHub Release |
+| **Dependency Graph** | Auto-managed | Tracks third-party deps for security alerts |
+
+To cut a release: bump `version` in `pyproject.toml`, merge the bump PR,
+then tag the merge commit. Prerelease tags (`v0.1.0-beta.1`) route to
+TestPyPI + a prerelease GitHub Release. Stable tags (`v0.1.0`) route
+to PyPI proper and the Docker image gets the `latest` tag.
+
+See [docs/PYPI_SETUP.md](docs/PYPI_SETUP.md) for the one-time PyPI
+Trusted Publishing setup.