docs: update the readme

README.md

@@ -1,41 +1,32 @@
 # GitHub runner operators
 
-![WIP](https://img.shields.io/badge/status-WIP-yellow)
+This repository contains applications, Juju charms, Grafana dashboards and actions related to operating and using
+self-hosted GitHub Actions runners.
 
-A monorepo containing charms to operate Self-Hosted GitHub Action Runners.
 
 ## Repository layout
 
 ```
+actions/
+  enable-log-forwarding/    # GitHub Action: enable log forwarding on runners
+
 charms/
   planner-operator/         # Juju charm: GitHub runner planner
     cos_custom/
       grafana_dashboards/   # Grafana dashboards for the planner charm
-                            # (served via cos-configuration-k8s, path: charms/planner-operator/cos_custom/grafana_dashboards)
   webhook-gateway-operator/ # Juju charm: GitHub webhook gateway
 
-runner_grafana_dashboards/  # Grafana dashboards for runner VM host metrics
-                            # (served via cos-configuration-k8s, path: runner_grafana_dashboards)
-```
+cmd/
+  planner/                  # Application entry point: planner
+  webhook-gateway/          # Application entry point: webhook gateway
 
-## Observability: Grafana dashboards
+internal/                   # Shared Go packages
 
-Dashboards in this repo are delivered to Grafana through
-[`cos-configuration-k8s`](https://charmhub.io/cos-configuration-k8s), which syncs
-JSON files from this Git repository and provisions them via the `grafana-dashboard`
-relation. Provisioned dashboards are **immutable** in Grafana regardless of user
-role — they cannot be edited or deleted through the UI.
+docs/                       # Documentation
 
-### Conventions
+runner_grafana_dashboards/  # Grafana dashboards for runner VM host metrics
+```
 
-| Directory | Purpose | `grafana_dashboards_path` config value |
-|---|---|---|
-| `charms/<charm>/cos_custom/grafana_dashboards/` | Dashboards for a specific charm's workload metrics | `charms/<charm>/cos_custom/grafana_dashboards` |
-| `runner_grafana_dashboards/` | Dashboards for runner VM host-level metrics (CPU, memory, disk, network) | `runner_grafana_dashboards` |
+## Further information
 
-Dashboard JSON files should use `__inputs` to declare the datasource (type `prometheus`).
-Setting `"editable": false` is recommended for clarity, but is not strictly required:
-dashboards delivered through `cos-configuration-k8s` are filesystem-provisioned and
-therefore read-only in Grafana regardless of the JSON flag. Metric names follow the
-[OpenTelemetry hostmetrics receiver](https://opentelemetry.io/docs/collector/components/#receiver)
-Prometheus naming convention (e.g. `system_cpu_time_seconds_total`).
+Further information can be found in the `docs/` directory.

docs/reference/grafana-dashboards.md

@@ -0,0 +1,15 @@
+# Grafana dashboards
+
+## Dashboard directories
+
+| Directory | Purpose |
+|---|---|
+| `charms/<charm>/cos_custom/grafana_dashboards/` | Dashboards for a specific charm's workload metrics |
+| `runner_grafana_dashboards/` | Dashboards for runner VM host-level metrics (CPU, memory, disk, network) |
+
+## Conventions
+
+Dashboard JSON files should use `__inputs` to declare the data source (type `prometheus`).
+Setting `"editable": false` is recommended for clarity. Metric names follow the
+[OpenTelemetry host metrics receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver)
+Prometheus naming convention (for example, `system_cpu_time_seconds_total`).

docs/reference/index.rst

@@ -10,4 +10,5 @@ Contents
    :maxdepth: 1
 
    architecture
-   charms
+   charms
+   grafana-dashboards