diff --git a/gitea-act-runner/CHANGELOG.md b/gitea-act-runner/CHANGELOG.md
new file mode 100644
index 0000000..ae4e326
--- /dev/null
+++ b/gitea-act-runner/CHANGELOG.md
@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.0.0 - 2026-04-01
+
+- Initial release
+- Self-registers to Gitea on first boot using options from HA supervisor
+- Persists `.runner` registration file in `/data/` across restarts
+- Generates `act_runner_config.yaml` at runtime from configured options
+- Docker socket access via `full_access: true` for job container spawning
+- Configurable: `gitea_url`, `runner_token`, `runner_name`, `runner_labels`, `log_level`
diff --git a/gitea-act-runner/DOCS.md b/gitea-act-runner/DOCS.md
index ff61fab..04dde00 100644
--- a/gitea-act-runner/DOCS.md
+++ b/gitea-act-runner/DOCS.md
@@ -1,88 +1,37 @@
-# Gitea act_runner — Home Assistant Addon
+# Gitea act_runner
 
-Runs the [Gitea Actions runner](https://gitea.com/gitea/act_runner) as a native Home Assistant addon, allowing your HAOS machine to execute Gitea CI/CD jobs.
+Runs the Gitea Actions runner on your Home Assistant machine.  
+The runner self-registers on first boot and persists its state across restarts.
 
----
+## Setup
 
-## Prerequisites
+1. Get a registration token: **Gitea → Site Admin → Actions → Runners → Create new runner**
+2. Set `gitea_url` to your Gitea LAN IP, e.g. `http://192.168.1.50:3000` — **not** `localhost`
+3. Paste the token into `runner_token`
+4. Start the add-on
 
-1. A running **Gitea instance** (version ≥ 1.21) with Actions enabled.  
-   In Gitea: **Site Administration → Configuration** — confirm `[actions] ENABLED = true`.
-2. A **runner registration token** from your Gitea instance (see below).
-3. The Gitea instance must be reachable from your HA machine by a **LAN IP address** (e.g. `http://192.168.1.50:3000`), not `localhost`.
+## Runner Labels
 
----
-
-## Getting the Registration Token
-
-1. Log in to Gitea as a **site administrator**.
-2. Navigate to **Site Administration → Actions → Runners**.
-3. Click **Create new runner**.
-4. Copy the displayed registration token — you will paste it into the addon options.
-
-> **Tip:** Tokens can also be scoped to an organisation or a single repository via the respective *Settings → Actions → Runners* page if you don't want a global runner.
-
----
-
-## Configuration Options
-
-| Option | Required | Default | Description |
-|---|---|---|---|
-| `gitea_url` | ✅ | — | Full URL of your Gitea instance, e.g. `http://192.168.1.50:3000` |
-| `runner_token` | ✅ | — | Registration token from the Gitea Runners page |
-| `runner_name` | | `haos-runner` | Display name shown in Gitea's runner list |
-| `runner_labels` | | `ubuntu-latest:docker://catthehacker/ubuntu:act-22.04` | Comma-separated list of labels this runner accepts |
-| `log_level` | | `info` | Verbosity: `debug`, `info`, `warn`, or `error` |
-
----
-
-## Runner Labels Format
-
-Labels tell Gitea which job `runs-on:` values this runner handles, and which Docker image to use for each:
-
-```
-<label>:docker://<image>
-```
-
-**Examples:**
+Labels map a workflow `runs-on:` value to a Docker image:
 
 ```
 ubuntu-latest:docker://catthehacker/ubuntu:act-22.04
-ubuntu-22.04:docker://catthehacker/ubuntu:act-22.04,ubuntu-20.04:docker://catthehacker/ubuntu:act-20.04
 ```
 
-The label on the left must match the `runs-on:` string in your workflow YAML. Multiple labels are comma-separated.
-
----
-
-## Why `full_access: true`?
-
-`full_access: true` in the addon manifest mounts `/var/run/docker.sock` inside the container. This is required so `act_runner` can communicate with the host Docker daemon to **spawn and manage job containers** for each CI run.
-
-Without this, the runner starts but will fail every job that uses a `container:` or `docker://` image.
-
-> ⚠️ This grants the addon broad access to the host Docker daemon. Only install this addon if you trust the Gitea instance and the workflow definitions it will run.
-
----
+Multiple labels are comma-separated.
 
 ## Persistent State
 
-The runner's registration file (`.runner`) and the generated runtime config are stored in `/data/` inside the addon, which is **persisted across restarts and updates**. The runner will **not** re-register on every boot.
-
-To force re-registration (e.g. if the token is revoked):
-1. Stop the addon.
-2. SSH into HAOS and delete `/data/addon_configs/gitea_act_runner/.runner` (exact path may vary).
-3. Update the `runner_token` option with a new token.
-4. Start the addon.
-
----
+`.runner` is stored in `/data/` and survives restarts — the runner will not re-register on every boot.  
+To force re-registration: stop the add-on, delete `/data/.runner`, update the token, and restart.
 
 ## Troubleshooting
 
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Runner shows **Offline** in Gitea immediately | `gitea_url` uses `localhost` or `127.0.0.1` | Use the LAN IP of the Gitea machine |
-| `[ERROR] runner_token is not configured` | Token field is blank | Paste the token from Gitea Runners page |
-| Jobs fail with *"Cannot connect to the Docker daemon"* | `full_access` not effective | Verify the addon config has `full_access: true` and restart |
-| Runner registers but jobs stay **Waiting** | Labels mismatch | Ensure workflow `runs-on:` matches a label configured in `runner_labels` |
-| Want more detail in logs | — | Set `log_level` to `debug` and restart |
+| Symptom | Fix |
+|---|---|
+| Runner **Offline** in Gitea | Use the LAN IP in `gitea_url`, not `localhost` |
+| Jobs fail with *"Cannot connect to Docker"* | Ensure `full_access: true` is set and restart |
+| Jobs stay **Waiting** | Check `runner_labels` matches the workflow `runs-on:` value |
+| Need more detail | Set `log_level: debug` and restart |
+
+Full documentation: [README.md](https://github.com/martemme/HomeAssistantAddons/tree/main/gitea-act-runner)
diff --git a/gitea-act-runner/README.md b/gitea-act-runner/README.md
new file mode 100644
index 0000000..3770001
--- /dev/null
+++ b/gitea-act-runner/README.md
@@ -0,0 +1,113 @@
+# Home Assistant Add-on: Gitea act_runner
+
+![Supports amd64 Architecture][amd64-shield]
+![Supports aarch64 Architecture][aarch64-shield]
+
+This add-on runs the **[Gitea Actions runner](https://gitea.com/gitea/act_runner)** natively on your Home Assistant machine, perfect for:
+
+- Running CI/CD pipelines defined in your Gitea repositories
+- Building and testing software directly on your home server
+- Executing Docker-based job containers without a separate runner host
+
+It self-registers to your Gitea instance on first boot, persists the registration across restarts, and is fully configurable from the HA add-on UI.
+
+## ⚙️ Configuration
+
+```yaml
+gitea_url: "http://192.168.1.50:3000"
+runner_token: "your-registration-token"
+runner_name: "haos-runner"
+runner_labels: "ubuntu-latest:docker://catthehacker/ubuntu:act-22.04"
+log_level: "info"
+```
+
+### Parameters
+
+| Variable        | Default                                                               | Description                                                                                      |
+|-----------------|-----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
+| `gitea_url`     | *(required)*                                                          | Full URL of your Gitea instance. **Must be a LAN IP**, not `localhost`.                          |
+| `runner_token`  | *(required)*                                                          | Registration token from Gitea → Site Admin → Actions → Runners → Create new runner.             |
+| `runner_name`   | `haos-runner`                                                         | Display name shown in the Gitea runner list.                                                     |
+| `runner_labels` | `ubuntu-latest:docker://catthehacker/ubuntu:act-22.04`                | Comma-separated `<label>:docker://<image>` pairs. Must match the `runs-on:` in your workflows.  |
+| `log_level`     | `info`                                                                | Verbosity level: `debug`, `info`, `warn`, or `error`.                                            |
+
+## 🚀 Installation
+
+1. Go to Home Assistant → **Settings → Add-ons → Add-on Store**
+2. Click **⋮ → Repositories** and add: `https://github.com/martemme/HomeAssistantAddons`
+3. Find **Gitea act_runner**, install it
+4. Fill in `gitea_url` and `runner_token` in the **Configuration** tab
+5. Start the add-on
+
+## 🏃 Getting the Registration Token
+
+1. Log in to Gitea as a **site administrator**
+2. Navigate to **Site Administration → Actions → Runners**
+3. Click **Create new runner** and copy the token
+
+> Tokens can also be scoped to an organisation or a single repository via the respective *Settings → Actions → Runners* page.
+
+## 🔖 Runner Labels Format
+
+Labels map a workflow `runs-on:` value to a Docker image:
+
+```
+<label>:docker://<image>
+```
+
+Multiple labels are comma-separated:
+
+```
+ubuntu-latest:docker://catthehacker/ubuntu:act-22.04,ubuntu-20.04:docker://catthehacker/ubuntu:act-20.04
+```
+
+## 📂 Repository Structure
+
+```
+gitea-act-runner/
+├── config.yaml     # Add-on definition
+├── Dockerfile      # Extends gitea/act_runner:latest
+├── run.sh          # Startup & registration script
+├── README.md
+└── DOCS.md
+```
+
+## 🧾 Requirements
+
+- Home Assistant OS or Supervised
+- A running Gitea instance (≥ 1.21) with Actions enabled
+- Supported architecture: `amd64`, `aarch64`
+
+## 🔒 Security — Why `full_access: true`?
+
+`full_access: true` mounts `/var/run/docker.sock` inside the container so `act_runner` can spawn and manage job containers on the host Docker daemon. Without it, every CI job fails with *"Cannot connect to the Docker daemon"*.
+
+> ⚠️ Only install this add-on if you trust the Gitea instance and the workflow definitions it will run.
+
+## 🛠 Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Runner shows **Offline** in Gitea | Use the LAN IP in `gitea_url`, not `localhost` |
+| Jobs fail with *"Cannot connect to Docker"* | Confirm `full_access: true` is present in config and restart |
+| Runner registers but jobs stay **Waiting** | Check that `runner_labels` matches the workflow `runs-on:` value |
+| Need more detail in logs | Set `log_level` to `debug` and restart |
+
+## Changelog & Releases
+
+Releases are based on [Semantic Versioning][semver], and use the format
+of `MAJOR.MINOR.PATCH`. In a nutshell, the version will be incremented
+based on the following:
+
+- `MAJOR`: Incompatible or major changes.
+- `MINOR`: Backwards-compatible new features and enhancements.
+- `PATCH`: Backwards-compatible bugfixes and package updates.
+
+---
+Made with ❤️ for automation and resilience.
+
+[semver]: http://semver.org/spec/v2.0.0.html
+[aarch64-shield]: https://img.shields.io/badge/aarch64-yes-green.svg
+[amd64-shield]: https://img.shields.io/badge/amd64-yes-green.svg
+[repository-badge]: https://img.shields.io/badge/Add%20repository%20to%20my-Home%20Assistant-41BDF5?logo=home-assistant&style=for-the-badge
+[repository-url]: https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fmartemme%2FHomeAssistantAddons
diff --git a/gitea-act-runner/config.yaml b/gitea-act-runner/config.yaml
index c7c3e1e..4fbbba1 100644
--- a/gitea-act-runner/config.yaml
+++ b/gitea-act-runner/config.yaml
@@ -21,8 +21,8 @@ build_from:
   aarch64: "gitea/act_runner:latest"
 
 options:
-  gitea_url: ""
-  runner_token: ""
+  gitea_url: "http://192.168.1.x:3000"
+  runner_token: "paste-your-registration-token-here"
   runner_name: "haos-runner"
   runner_labels: "ubuntu-latest:docker://catthehacker/ubuntu:act-22.04"
   log_level: "info"