docs: add Udash documentation and document relative paths

assets/code_example/docs/core/configuration/relativepaths.yaml

@@ -0,0 +1,22 @@
+name: Keep the chart image tag in sync
+
+options:
+  # "Chart.yaml" and "values.yaml" below are looked up next to this manifest,
+  # whatever directory updatecli was started from.
+  relativepaths: manifest
+
+sources:
+  version:
+    name: Read the chart version
+    kind: yaml
+    spec:
+      file: Chart.yaml
+      key: $.version
+
+targets:
+  tag:
+    name: Report it as the image tag
+    kind: yaml
+    spec:
+      file: values.yaml
+      key: $.image.tag

assets/code_example/docs/udash/dashboards/updatecli-compose.yaml

@@ -0,0 +1,5 @@
+policies:
+  - name: Rust dependencies
+    policy: ghcr.io/updatecli/policies/autodiscovery/cargo:0.9.1@sha256:237c49b0541ad1a5ce9bcdfef0a525dd47ff854436dee61985b56f2c981c828d
+    values:
+      - values.yaml

assets/code_example/docs/udash/dashboards/values.yaml

@@ -0,0 +1,17 @@
+scm:
+  enabled: true
+  kind: github
+  owner: my-org
+  repository: my-crate
+  branch: main
+
+# Pull request labels, applied on GitHub. Udash never sees these.
+labels:
+  - dependencies
+
+# Pipeline labels, stored with every report and offered by the Udash filters.
+pipeline:
+  labels:
+    ecosystem: cargo
+    policy: autodiscovery
+    team: platform

assets/code_example/docs/udash/quick-start/config.json

@@ -0,0 +1,6 @@
+{
+  "AUTH_ENABLED": false,
+  "API_BASE_URL": "/api",
+  "APP_BASE_PATH": "/",
+  "MAX_HISTORY_DAYS": 30
+}

assets/code_example/docs/udash/quick-start/config.yaml

@@ -0,0 +1,9 @@
+server:
+  auth:
+    # No authentication: anyone reaching this instance can read and write reports.
+    # Fine on a laptop, never on anything reachable from outside.
+    mode: "none"
+
+database:
+  uri: postgres://udash:password@db:5432/udash?sslmode=disable
+  migrationdisabled: false

assets/code_example/docs/udash/quick-start/docker-compose.yaml

@@ -0,0 +1,50 @@
+services:
+  db:
+    image: postgres:18@sha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722
+    restart: always
+    environment:
+      - POSTGRES_USER=udash
+      - POSTGRES_PASSWORD=password
+      - POSTGRES_DB=udash
+    expose:
+      - 5432
+
+  server:
+    image: ghcr.io/updatecli/udash:v0.18.2@sha256:899c2e3a7bf8b4aea588ba4ca398ce4ca1626479ab96881aa69ad6a18964fae1
+    command: server start
+    restart: always
+    environment:
+      - GIN_MODE=release
+    volumes:
+      - "./udash/config.yaml:/home/udash/.udash/config.yaml"
+    expose:
+      - 8080
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.server.rule=PathPrefix(`/api/`)"
+      - "traefik.http.routers.server.service=server"
+      - "traefik.http.services.server.loadbalancer.server.port=8080"
+
+  front:
+    image: ghcr.io/updatecli/udash-front:v0.26.0@sha256:21d5c66f6872907f5a83da1a07bde6fa1b46bd74d7e56898b52f0a6b5a8e7654
+    restart: always
+    volumes:
+      - "./udash-front/config.json:/usr/share/nginx/html/config.json"
+    expose:
+      - 80
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.front.rule=PathPrefix(`/`)"
+      - "traefik.http.routers.front.service=front"
+      - "traefik.http.services.front.loadbalancer.server.port=80"
+
+  traefik:
+    image: traefik:v3.7@sha256:24841fe2de7304c149343d877d2923b4c8800a38ba015dea9174c23b20e344a0
+    command:
+      - "--providers.docker=true"
+      - "--providers.docker.exposedbydefault=false"
+      - "--entrypoints.web.address=:80"
+    ports:
+      - "80:80"
+    volumes:
+      - "/var/run/docker.sock:/var/run/docker.sock:ro"

assets/code_example/docs/udash/quick-start/updatecli-compose.yaml

@@ -0,0 +1,3 @@
+policies:
+  - name: Discover what could be updated here
+    policy: ghcr.io/updatecli/policies/autodiscovery/all:0.7.0@sha256:09bd79160f4ecda4d8323b25815a733d39334c22544aaa6ac5859f0d3ef9fa79

assets/code_example/docs/udash/sending-reports/updatecli.yaml

@@ -0,0 +1,37 @@
+name: Bump the base image
+pipelineid: docker/base-image
+
+labels:
+  ecosystem: docker
+  monitor: active
+
+# The scm files the reports under this Git repository in Udash.
+scms:
+  default:
+    kind: github
+    spec:
+      owner: my-org
+      repository: my-service
+      branch: main
+      token: '{{ requiredEnv "GITHUB_TOKEN" }}'
+
+sources:
+  alpine:
+    name: Get the latest Alpine version
+    kind: dockerimage
+    spec:
+      image: alpine
+      versionfilter:
+        kind: semver
+
+targets:
+  dockerfile:
+    name: Update the Alpine base image
+    kind: dockerfile
+    scmid: default
+    sourceid: alpine
+    spec:
+      file: Dockerfile
+      instruction:
+        keyword: FROM
+        matcher: alpine

config/_default/menus/menus.en.toml

@@ -32,6 +32,12 @@ weight = 40
 identifier = "guide"
 pageRef = "/docs/guides"
 
+[[sidebar_docs]]
+name = "Udash"
+weight = 45
+identifier = "udash"
+pageRef = "/docs/udash"
+
 [[sidebar_docs]]
 name = "Commands"
 weight = 50

content/en/docs/core/configuration.adoc

@@ -67,6 +67,10 @@ A manifest accepts the following root keys. All of them are optional except `nam
 | string
 | The minimum Updatecli version required by the manifest. Updatecli skips the manifest, with an error, when its own version is lower.
 
+| `options`
+| object
+| Settings changing how Updatecli behaves for this manifest, as opposed to describing the pipeline itself. See <<_options,Options>>.
+
 | `sources`
 | map
 | See link:/docs/core/source/[source].
@@ -147,6 +151,80 @@ This affects manifest execution order only and does not replace `pipelineid`.
 
 To learn more, see **link:/docs/core/order/[manifest order]**.
 
+[#_options]
+=== Options
+
+The `options` root key groups the settings that change how Updatecli behaves for a manifest, as opposed to the keys describing what the pipeline is made of.
+
+[cols="1,1,3",options=header]
+|===
+| Key | Default | Description
+
+| `relativepaths`
+| `workingdirectory`
+| What the relative paths of the manifest resolve against. See <<_relative_paths,Relative paths>>.
+|===
+
+[#_relative_paths]
+==== Relative paths
+
+By default, a relative path written in a manifest resolves against the directory Updatecli was started from, not against the manifest that declares it.
+A manifest stored in `updatecli.d/nodejs.yaml` and asking for `file: package.json` therefore reads the `package.json` of whichever directory you happened to run the command in.
+
+Setting `relativepaths` to `manifest` makes those paths resolve against the directory holding the manifest instead, which is what allows a manifest, or a whole directory of them, to be moved, vendored into another repository, or distributed as a link:/docs/core/shareandreuse/[policy] without rewriting every path.
+
+[cols="1,3",options=header]
+|===
+| Value | Behaviour
+
+| `workingdirectory`
+| Relative paths resolve against the directory Updatecli was started from. This is the default, and the historical behaviour.
+
+| `manifest`
+| Relative paths resolve against the directory holding the manifest that declares them.
+|===
+
+++++
+<details><summary>updatecli.yaml</summary>
+<pre>
+{{<include "assets/code_example/docs/core/configuration/relativepaths.yaml">}}
+</pre>
+</details>
+++++
+
+The setting applies to the manifest that declares it, so a directory of manifests can be migrated one file at a time.
+It can also be set for a whole run, with the `--relative-paths` flag or the `UPDATECLI_RELATIVE_PATHS` environment variable, which is the practical way to try it on an existing repository:
+
+[source,shell]
+----
+updatecli diff --relative-paths manifest --config updatecli.d
+----
+
+A manifest declaring `options.relativepaths` wins over the flag and the environment variable.
+
+[IMPORTANT]
+====
+`relativepaths` only affects resources that are **not** attached to an link:/docs/core/scm/[scm].
+
+A source, condition, or target with an `scmid` always resolves its paths against the working directory of that scm, which is the clone Updatecli made for it. That is unchanged, and is what makes a target committed to the right repository.
+====
+
+Within a manifest that sets `relativepaths: manifest`, the manifest directory becomes the base for:
+
+* the file paths of every resource without an `scmid`, such as `spec.file` and `spec.files`
+* the working directory of the link:/docs/plugins/resource/shell/[shell] resource, `spec.workdir`
+* a relative `directory` in an `scms` entry, and the repository the `local` scm auto-detects
+* the directory the link:/docs/core/autodiscovery/[autodiscovery] crawlers scan
+
+Absolute paths are never rewritten, and `http://` or `https://` locations are always fetched over the network rather than read from disk.
+
+NOTE: The values, secrets, and manifest files passed on the command line with `--values`, `--secrets`, and `--config` are resolved against the directory Updatecli was started from, whatever `relativepaths` says. They are arguments to the command, not content of a manifest.
+
+[TIP]
+====
+The default stays `workingdirectory` on purpose. The most common layout is a `updatecli.d/` directory whose manifests reference paths from the root of the repository, and those manifests only work because paths resolve against the working directory. Changing the default would break them, so opting in per manifest is the supported path.
+====
+
 === File
 
 Each Updatecli pipeline is defined in its own manifest file.

content/en/docs/core/label.adoc

@@ -49,7 +49,7 @@ updatecli compose apply --labels="ecosystem:go"
 +
 Pipelines matching the filter will execute. Pipelines without the label or with a different value will be skipped.
 
-2. **Filtering pipeline reports** in link:https://github.com/updatecli/udash/[Udash]
+2. **Filtering pipeline reports** in link:/docs/udash/[Udash], where labels group pipelines from many repositories into one view. See link:/docs/udash/dashboards/#_filtering_by_label[Filtering by label].
 
 == Filtering with `--labels`
 

content/en/docs/core/scm.adoc

@@ -28,7 +28,8 @@ current working directory, and a target that changes a file there gets its chang
 to a branch named after the pipeline `pipelineid`.
 
 A resource without an `scmid` simply works on the current working directory, and Updatecli neither
-clones nor commits anything for it.
+clones nor commits anything for it. A manifest can ask for its own directory to be used instead, with
+link:/docs/core/configuration/#_relative_paths[`options.relativepaths`].
 
 === The `local` scm
 

content/en/docs/help/environment.adoc

@@ -107,11 +107,12 @@ fails with `you cannot use both token and app authentication methods`.
 |===
 
 NOTE: Reporting to Udash requires `--experimental`. Without it the step is skipped silently, whatever
-these variables say. See link:/docs/help/experimental/["Experimental features" page].
+these variables say. See link:/docs/help/experimental/["Experimental features" page] and
+link:/docs/udash/sending-reports/["Sending reports"].
 
 == Flag defaults
 
-Two flags read a default from the environment, which is the practical way to set them once for a whole
+These flags read a default from the environment, which is the practical way to set them once for a whole
 CI job rather than on every invocation. An unparsable value is ignored and logged at debug level.
 
 [cols="1,1,2", options="header"]
@@ -125,6 +126,12 @@ CI job rather than on every invocation. An unparsable value is ignored and logge
 | `UPDATECLI_DISABLE_VERSION_CHECK`
 | `--disable-version-check`
 | Skip the check for a newer Updatecli release, which runs after the command completes.
+
+| `UPDATECLI_RELATIVE_PATHS`
+| `--relative-paths`
+| What the relative paths of a manifest resolve against, `workingdirectory` (the default) or
+`manifest`. A manifest setting `options.relativepaths` itself wins over this. See
+link:/docs/core/configuration/#_relative_paths["Relative paths"].
 |===
 
 == The `local` scm

content/en/docs/help/experimental.adoc

@@ -52,12 +52,14 @@ set.
 
 === Reporting to Udash
 
-link:https://github.com/updatecli/udash[Udash] collects pipeline results for viewing over time.
+link:/docs/udash/[Udash] collects pipeline results for viewing over time.
 
 Without the flag, publishing is skipped **silently**, no warning, no error, and the run reports
 success. Configuring `UPDATECLI_UDASH_*` or running `updatecli udash login` is not enough on its own.
 With the flag, results are published under a section headed `Udash - Experimental`.
 
+See link:/docs/udash/sending-reports/["Sending reports"] for how to configure the endpoint.
+
 `--disable-udash-report` switches it off again without dropping the rest of the flag.
 
 === WebAssembly autodiscovery plugins

content/en/docs/udash/_index.md

@@ -0,0 +1,30 @@
+---
+title: "Udash"
+description: "Publish your Updatecli pipeline reports to Udash, the Updatecli dashboard, and follow update activity across every repository."
+lead: ""
+date: 2026-08-07T10:00:00+02:00
+lastmod: 2026-09-24T10:00:00+02:00
+draft: false
+images: []
+sidebar:
+  collapsed: true
+---
+
+Updatecli tells you what changed on one run, in one repository. [Udash](https://github.com/updatecli/udash)
+keeps those runs, so you can see the same information across every repository and over time.
+
+To see it in use, browse [updatecli.uda.sh](https://updatecli.uda.sh), the public instance the
+Updatecli project publishes its own pipeline reports to.
+
+{{< alert icon="⚠️" text="Udash is experimental, and so is the Updatecli side of it. Publishing reports requires the <code>--experimental</code> flag, and both the API and the interface can change without going through the usual deprecation cycle." >}}
+
+- [Introduction](/docs/udash/introduction/) - what Udash is and how Updatecli feeds it.
+- [Quick start](/docs/udash/quick-start/) - run Udash locally with Docker Compose and publish your
+  first report.
+- [Sending reports](/docs/udash/sending-reports/) - connect Updatecli to an instance, locally or
+  from CI.
+- [Dashboards](/docs/udash/dashboards/) - find your pipelines, filter them with labels, and share a
+  view.
+
+Deploying, configuring, and securing a Udash instance, the agent, and the API are documented in the
+[updatecli/udash](https://github.com/updatecli/udash) repository.