docs: Update README with container registry workflow

This commit updates the main README.md file to reflect the recent changes related to the container registry integration.

- Clarifies the difference between Starting development environment by pulling image from registry...
export IMAGE_NAME=audio-engine-hub && \
export REGISTRY=git.wlkns.org && \
export USERNAME=stephan && \
export TAG=latest && \
docker compose up -d (for registry images) and Starting development environment (local build) on port 8000... (for local builds).
- Adds a dedicated "Container Registry" section explaining the push/pull workflow.
- Updates the "Makefile Commands" section with the new , , and  targets.

README.md

@@ -8,16 +8,19 @@ AudioEngineHub is a local-first, modular, multi-engine Text-to-Speech (TTS) serv
 - **Configurable Engines:** Activate or deactivate engines on the fly via a simple configuration file.
 - **Caching:** Caches generated audio to save resources and provide faster responses for repeated requests.
 - **Dockerized:** Runs in a containerized environment for easy setup and dependency management.
-- **Automatic Port Finding:** Automatically finds and uses a free port, preventing conflicts.
+- **Automatic Port Finding:** Automatically finds and uses a free port when building locally.
+- **Container Registry Support:** Pre-configured to push to and pull from a container registry.
 
 ## Getting Started
 
+This guide covers local development. For information on using the container registry, see the "Container Registry" section below.
+
 ### Prerequisites
 
 - [Docker](https://docs.docker.com/get-docker/)
 - [Docker Compose](https://docs.docker.com/compose/install/)
 
-### Installation
+### Local Development Setup
 
 1.  **Clone the repository:**
     ```bash
@@ -36,20 +39,50 @@ AudioEngineHub is a local-first, modular, multi-engine Text-to-Speech (TTS) serv
     ```
 
 3.  **Build and start the container:**
-    Use the `make up` command to build the Docker image and start the service.
+    Use the `make dev-up` command to build the Docker image from your local source and start the service.
     ```bash
-    make up
+    make dev-up
     ```
-    This command will automatically find a free port starting from 8000 and run the application on it.
+    This command will automatically find a free port, build the image, and run the application.
 
     > **Note:** For the most reliable port detection, it is recommended to run the command with `sudo`:
     > ```bash
-    > sudo make up
+    > sudo make dev-up
     > ```
 
-## Usage
+## Container Registry
 
-The application provides a simple API to generate speech and inspect the available engines.
+The project is configured to work with the container registry at `git.wlkns.org`.
+
+### Pushing an Image
+
+1.  **Log in to the Registry:**
+    You only need to do this once per machine.
+    ```bash
+    docker login git.wlkns.org
+    ```
+
+2.  **Push the Image:**
+    This command will build your image, tag it correctly, and push it to the registry.
+    ```bash
+    make push
+    ```
+
+### Pulling and Running an Image
+
+1.  **Pull the Image:**
+    To download the latest image from the registry:
+    ```bash
+    make pull
+    ```
+
+2.  **Run the Image:**
+    This command will start the application using the pre-built image from the registry (pulling it if necessary).
+    ```bash
+    make up
+    ```
+
+## Usage
 
 ### Endpoints
 
@@ -57,16 +90,19 @@ The application provides a simple API to generate speech and inspect the availab
 -   `GET /health`: Check the health of the API and the status of the loaded engines.
 -   `GET /engines`: List the currently active engines.
 -   `GET /models`: List the available models for each active engine.
-_  `GET /speakers`: List the available speakers for a given engine and model.
+_   `GET /speakers`: List the available speakers for a given engine and model.
 
 ### Makefile Commands
 
 The project includes a `Makefile` with several commands to simplify development and management:
 
--   `make up`: Build the image and start the application container.
--   `make down`: Stop the application container.
+-   `make dev-up`: Build the image from local source and start the application. Recommended for development.
+-   `make up`: Start the application using the image from the container registry (pulls if not present).
+-   `make down`: Stop the application container(s).
 -   `make logs`: View the application logs.
 -   `make health-check`: Run a sanity check to ensure the deployed container is healthy and all engines are "ok".
+-   `make pull`: Pull the latest image from the container registry.
+-   `make push`: Build, tag, and push the image to the container registry.
 -   `make test`: Run the `pytest` test suite.
 -   `make help`: Display a list of all available commands.