Health-Informatics-UoN · AndyRae · Feb 6, 2025 · Feb 6, 2025 · Feb 6, 2025 · Feb 6, 2025
diff --git a/README.md b/README.md
@@ -2,26 +2,31 @@
 
 **Hutch** is part of an application stack for **Federated Activities**, such as Analytics, Data Discovery or Machine Learning.
 
-## Hutch-Trefx 
-[Hutch-Trefx](https://github.com/Health-Informatics-UoN/hutch-trefx/tree/main) is an Executing Agent implementation that accepts jobs from a TRE Agent, executes them and records outputs and provenance, submitting the results to be approved for egress.
+## Hutch-TREFX
+
+![MIT License][license-badge] [![Trefx Repo][github-badge]][trefx-repo] [![Trefx Releases][trefx-releases-badge]][trefx-releases] [![Trefx Tests][trefx-tests-badge]][trefx-tests]
+
+![.NET][dotnet-badge] [![Trefx Docs][docs-badge]][trefx-docs]
+
+[Hutch-TREFX][trefx-repo] is an Executing Agent implementation that accepts jobs from a TRE Agent, executes them and records outputs and provenance, submitting the results to be approved for egress.
 
 ## Cohort Discovery
 
-### 🐇 [Bunny](https://github.com/Health-Informatics-UoN/hutch-bunny) ![MIT License][license-badge]
+### 🐇 [Bunny][bunny-repo]
 
-| | | |
-|-|-|-|
-| ![Python][python-badge] | [![Bunny Docker Images][docker-badge]][bunny-containers] | [![Bunny Docs][docs-badge]][bunny-docs] |
+![MIT License][license-badge] [![Bunny Repo][github-badge]][bunny-repo] [![Bunny Releases][bunny-releases-badge]][bunny-releases] [![Bunny Tests][bunny-tests-badge]][bunny-tests]
+
+![Python][python-badge] [![Bunny Docker Images][docker-badge]][bunny-containers]  [![Bunny Docs][docs-badge]][bunny-docs] [![Bunny Roadmap][roadmap-badge]][roadmap]
 
 A Cohort Discovery Task Resolver.
 
 Fetches and resolves Availability and Distribution Queries against a PostgreSQL OMOP CDM database.
 
-### 🔄 [Relay](https://github.com/Health-Informatics-UoN/hutch-relay) ![MIT License][license-badge]
+### 🔄 [Relay][relay-repo]
+
+[![MIT License][license-badge]][license-badge] [![Relay Repo][github-badge]][relay-repo] [![Relay Releases][relay-releases-badge]][relay-releases] [![Relay Tests][relay-tests-badge]][relay-tests]
 
-| | | |
-|-|-|-|
-| ![.NET][dotnet-badge] | [![Relay Docker Images][docker-badge]][relay-containers] | [![Relay Docs][docs-badge]][relay-docs] |
+![.NET][dotnet-badge] [![Relay Docker Images][docker-badge]][relay-containers]   [![Relay Docs][docs-badge]][relay-docs] [![Relay Roadmap][roadmap-badge]][roadmap]
 
 A Federated Proxy for a Cohort Discovery Task API.
 
@@ -33,19 +38,36 @@ A Federated Proxy for a Cohort Discovery Task API.
 
 Implements a subset of the Task API for the downstream nodes to interact with.
 
-
 [hutch-logo]: https://raw.githubusercontent.com/HDRUK/hutch/main/assets/Hutch%20splash%20bg.svg
-[hutch-repo]: https://github.com/health-informatics-uon/hutch
+[roadmap]: https://github.com/orgs/Health-Informatics-UoN/projects/22/views/1
 
+[bunny-repo]: https://github.com/Health-Informatics-UoN/hutch-bunny
 [bunny-docs]: https://health-informatics-uon.github.io/hutch/bunny
 [bunny-containers]: https://github.com/Health-Informatics-UoN/hutch-bunny/pkgs/container/hutch%2Fbunny
+[bunny-releases]: https://github.com/Health-Informatics-UoN/hutch-bunny/releases
+[bunny-tests]: https://github.com/Health-Informatics-UoN/hutch-bunny/actions/workflows/check.run-tests.yml 
+[bunny-releases-badge]: https://img.shields.io/github/v/tag/Health-Informatics-UoN/hutch-bunny
+[bunny-tests-badge]: https://github.com/Health-Informatics-UoN/hutch-bunny/actions/workflows/check.run-tests.yml/badge.svg
 
+[relay-repo]: https://github.com/Health-Informatics-UoN/hutch-relay
 [relay-docs]: https://health-informatics-uon.github.io/hutch/relay
 [relay-containers]: https://github.com/Health-Informatics-UoN/hutch-relay/pkgs/container/hutch%2Frelay
+[relay-releases]: https://github.com/Health-Informatics-UoN/hutch-relay/releases
+[relay-tests]: https://github.com/Health-Informatics-UoN/hutch-relay/actions/workflows/check.relay.build-test.yml
+[relay-releases-badge]: https://img.shields.io/github/v/tag/Health-Informatics-UoN/hutch-relay
+[relay-tests-badge]: https://github.com/Health-Informatics-UoN/hutch-relay/actions/workflows/check.relay.build-test.yml/badge.svg
+
+[trefx-repo]: https://github.com/Health-Informatics-UoN/hutch-trefx
+[trefx-docs]: https://health-informatics-uon.github.io/hutch-trefx/
+[trefx-releases]: https://github.com/Health-Informatics-UoN/hutch-trefx/releases
+[trefx-releases-badge]: https://img.shields.io/github/v/tag/Health-Informatics-UoN/hutch-trefx
+[trefx-tests]: https://github.com/Health-Informatics-UoN/hutch-trefx/actions/workflows/build.HutchAgent.yml
+[trefx-tests-badge]: https://github.com/Health-Informatics-UoN/hutch-trefx/actions/workflows/build.HutchAgent.yml/badge.svg
 
 [license-badge]: https://img.shields.io/github/license/health-informatics-uon/hutch-bunny.svg
-[dotnet-badge]: https://img.shields.io/badge/.NET-5C2D91?style=for-the-badge&logo=.net&logoColor=white
-[python-badge]: https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white
-[docker-badge]: https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge&logo=docker&logoColor=white
-[docs-badge]: https://img.shields.io/badge/docs-black?style=for-the-badge&labelColor=%23222
-[readme-badge]: https://img.shields.io/badge/readme-lightgrey?style=for-the-badge&labelColor=%23222
+[dotnet-badge]: https://img.shields.io/badge/.NET-5C2D91?style=flat&logo=.net&logoColor=white
+[python-badge]: https://img.shields.io/badge/Python-3776AB?style=flat&logo=python&logoColor=white
+[docker-badge]: https://img.shields.io/badge/docker-%230db7ed.svg?style=flat&logo=docker&logoColor=white
+[docs-badge]: https://img.shields.io/badge/docs-black?style=flat&labelColor=%23222
+[roadmap-badge]: https://img.shields.io/badge/roadmap-blue?style=flat&labelColor=%230066cc
+[github-badge]: https://img.shields.io/badge/github-black?style=flat&logo=github&logoColor=white
diff --git a/website/pages/bunny/deployment.mdx b/website/pages/bunny/deployment.mdx
@@ -17,6 +17,8 @@ This page will guide you through getting Bunny deployed in a Virtual Machine (VM
 
 ## Deployment Steps
 
+<Steps>
+
 ### Get the example Compose file
 
 Download the [sample Bunny Compose](https://raw.githubusercontent.com/Health-Informatics-UoN/hutch/refs/heads/main/samples/Bunny/bunny-standalone.compose.yml) file* by running the command:
@@ -61,6 +63,7 @@ You won't see the results here, but if you see the messages, then it's successfu
 
 <Callout emoji="🎉">Congratulations on your first Bunny deployment!</Callout>
 
+</Steps>
 ## Best Practices
 
 When deploying Bunny, follow these best practices to ensure stability and consistency:

diff --git a/website/pages/bunny/developers/setup.mdx b/website/pages/bunny/developers/setup.mdx
@@ -5,6 +5,8 @@ import { Steps } from "nextra/components";
 
 This page will guide you through getting a Bunny developer environment locally.
 
+To make development easy as possible, we recommend using Docker to run the OMOP CDM database, and a uv Python environment to run Bunny.
+
 Start by cloning [the Bunny repository](https://github.com/Health-Informatics-UoN/hutch-bunny)
 
 ```bash copy
@@ -44,6 +46,7 @@ TASK_API_PASSWORD=password
 LOW_NUMBER_SUPPRESSION_THRESHOLD=
 ROUNDING_TARGET=
 POLLING_INTERVAL=5
+BUNNY_LOGGER_LEVEL=DEBUG
 ```
 
 - If you are querying a remote database, the variables prefixed with `DATASOURCE` must be configured accordingly.
@@ -66,11 +69,11 @@ To execute a query using the CLI, run the following command from the project roo
 uv run bunny --body tests/queries/availability.json
 ```
 
-This will write the result for your query to `output.json`
+This will write the result for your query to `output.json`, and log the result to the console.
 
 <Callout emoji="🎉">Congratulations on your first Bunny query!</Callout>
 
-This workflow can be used to run queries and quickly iterate in development.
+We recommend this workflow to run queries and quickly iterate in development.
 
 ### Run the Bunny daemon
 
@@ -80,7 +83,7 @@ If you are connecting to an upstream Task API, you can use the Bunny daemon to p
 uv run bunny-daemon
 ```
 
-You should then see a message in your console like this:
+You should then see messages in your console like this:
 
 ```bash
 INFO - 12-Nov-24 12:36:24 - Setting up database connection...
@@ -96,7 +99,11 @@ INFO - 12-Nov-24 12:36:45 - Looking for job...
 
 - Bunny establishes a connection to your OMOP CDM database, then polls the upstream Task API for a task.
 - When it receives a task, it processes the query, queries the database, and returns the result.
-- You won't see the results here, but if you see the messages, then it's successfully contacting both the database and API.
+
+<Callout emoji="🐇">
+For debugging purposes, you can run Bunny directly from the source code by executing the `bunny-daemon` script in the `src/hutch_bunny` directory. This allows you to use your IDE's debugger - we've included preconfigured debug settings for VSCode in the repository.
+</Callout>
+
 
 ### Running Tests
 

diff --git a/website/pages/bunny/quickstart.mdx b/website/pages/bunny/quickstart.mdx
@@ -1,3 +1,5 @@
+import { Steps } from "nextra/components";
+
 # Quickstart
 
 The quickest way to run Bunny is to use the provided [Bunny Image](https://github.com/Health-Informatics-UoN/hutch-bunny/pkgs/container/hutch%2Fbunny) command line interface to run a query against your existing OMOP database. This way you don't need an upstream Task API to connect to yet.
@@ -9,6 +11,8 @@ The quickest way to run Bunny is to use the provided [Bunny Image](https://githu
 
 ## Setup
 
+<Steps>
+### Configuration
 You'll need to set some environment variables to connect the container to the database, you can create a `.env` file with your database details:
 
 ```bash copy filename=".env"
@@ -86,6 +90,8 @@ docker run \
 
 Your results should be available in `output.json`
 
+</Steps>
+
 ## Next Steps
 
 To connect your Bunny to a upstream Task API, read the [deployment](deployment) guide.
diff --git a/website/pages/contributing.mdx b/website/pages/contributing.mdx
@@ -10,7 +10,8 @@ Thanks for your interest in contributing! We welcome contributions of all kinds,
 
 To contribute:
 
-- Check open issues, and create or comment on an issue if you are working on it.
+- Check open issues, and create or comment on an issue to volunteer to work on it.
+- A maintainer will then assign the issue to you if it is available and appropriate to work on.
 - Fork the repository and create a branch for your changes.
 - Follow existing coding patterns and keep contributions focussed.
 - Open a pull request (PR) with a clear description of your changes.